HC_Set_User_Options

void HC_Set_User_Options(char const *list)
void HC_Set_User_Options(char const list)

Allows you to create new “attributes” of your own choosing.

It’s useful sometimes to be able to store extra information of your own choosing into the HOOPS segment tree. Set_User_Options() , just like (for example) Set_Visibility() , accepts a long formatted string containing one or more type specifications, separated by commas, where each specification is of the form *”type=value”*. The type‘s for Set_Visibility() are predefined and have specific meanings to HOOPS, but in Set_User_Options() the type‘s are defined by you, and can be anything you please.

“User Options” have all the properties of other HOOPS attributes: they are set, maintained, copied, retrieved, inherited down the tree, and “metafiled” just like other attributes. User Options are especially useful for passing extra information from one program, through a metafile, into another program.

User Options have no effect at all on any other part of HOOPS - the system just stores them; it doesn’t look at them. They acquire meaning only when your program (or a subsequent interpreter program) checks the setting (via Show_One_User_Option() or Show_One_Net_User_Option() ) for a particular type.

The type is not case-sensitive. The value is case-sensitive.

Set_User_Options() may be used to associate user data with any piece of geometry, as well as with segments. This must be done during a block using Open_Geometry().

When you call Set_User_Options() on a segment that already has some User Options, the list of option specifications are merged, with the newer values for a given option replacing the older values (if any). When you call UnSet_User_Options() , all the option specifications are thrown away. Use UnSet_One_User_Option() to discard the setting for one option without disturbing the rest.

If there are any special characters, embed extra quote marks around the value. (Use matching’, “, or `). You can specify just a *”type”*, with no *”=value”*; the system turns it into *”type=on”*. Similarly, *”no type”* is interpreted as *”type =off”*. You might find it appropriate to choose a standard prefix for all of the <em>type</em> names you choose, so that your types can’t accidentally conflict with those chosen by the program(s) that call your routines. User Options are very similar in purpose to the “User Value” attribute. User Value is an older style, limited to storing a single integer. User Values have been replaced by renumbered keys. ISO Latin-1 characters can be used in option names and values. See Table 4.1 in Insert_Text() . Developers also have the ability to embed wide character user options via Set_Unicode_User_Options. Please refer to Set_Unicode_User_Options for further details. As a convenience, Show_One_Net_User_Option() will return a blank string even when the option in question hasn’t been set anywhere at all up the segment tree. You may, however, wish to explicitly set default values for your User Options at an appropriate place (either on “?Picture” or, better, “/”). For each of this family of functions called, a full update is triggered on the next Update_Display(). To avoid this, one must wrap the function calls in the below calls to Define_System_Options(). @code HC_Define_System_Options(“no update control”); //Set_User calls HC_Define_System_Options(“update control”);

HC_Renumber_Key, HC_Show_One_User_Option

Parameters

list: A quoted string or a string variable containing a list of the desired option settings.