Functions | |
void | Set_User_Options (const char *list) |
void | Set_User_Index (long index, const void *data) |
void | Set_User_Data (POINTER_SIZED_INT index, void const *data, long data_length) |
void | Set_User_Data_By_Key (Key key, POINTER_SIZED_INT index, void const *data, long data_length) |
void | UnSet_User_Options (void) |
void | UnSet_One_User_Option (const char *which) |
void | UnSet_One_User_Index (long index) |
void | UnSet_One_User_Data (POINTER_SIZED_INT index) |
void | UnSet_One_User_Data_By_Key (Key key, POINTER_SIZED_INT index) |
void Set_User_Options | ( | const char * | list | ) |
Allows you to create new "attributes" of your own choosing.
list | - A quoted string or a string variable containing a list of the desired option settings. |
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 type 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().
HC_Define_System_Options("no update control"); //Set_User calls HC_Define_System_Options("update control");
None.
void Set_User_Index | ( | long | index, |
const void * | data | ||
) |
Associates a segment with an index into a user-defined array of option strings.
index | - An index into a user-defined array of options. |
data | - The value of the user data to be associated with its corre sponding array index. Passed by reference always. |
Set_User_Index() 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().
void Set_User_Data | ( | POINTER_SIZED_INT | index, |
void const * | data, | ||
long | data_length | ||
) |
This function allows the user to associate binary data with a segment or piece of geometry in the database.
index | - A unique indentifier associated with the user data. |
data | - A pointer to binary data to store in the database. |
data_length | - The size of the binary user data. |
The index parameter lets you map multiple chunks of binary data to a segment or piece of geometry. Note that index values must be unique but also can be less than zero. The binary data is not processed or modified in the HOOPS database.
This data is not available from HIC unlike user indices.
void Set_User_Data_By_Key | ( | Key | key, |
POINTER_SIZED_INT | index, | ||
void const * | data, | ||
long | data_length | ||
) |
This function associates binary user data with a segment or piece of geometry in the database.
key | - the key in which the user data should be set. |
index | - A unique indentifier associated with the user data. |
data | - A pointer to binary data to store in the database. |
data_length | - The size of the binary user data. |
No additional details. See Set_User_Data().
void UnSet_User_Options | ( | void | ) |
Removes all settings established by a previous call to Set_User_Options().
No additional details. See Set_User_Options()
void UnSet_One_User_Option | ( | const char * | which | ) |
Removes a given setting established by a previous call to Set_User_Options(), rather than all settings.
which | - A particular user option whose data should be discarded. |
No additional details. See Set_User_Options()
void UnSet_One_User_Index | ( | long | index | ) |
Removes a given setting established by a previous call to Set_User_Options(), rather than all settings.
index | - An index into a user-defined array of options. |
No additional details. See Set_User_Options()
void UnSet_One_User_Data | ( | POINTER_SIZED_INT | index | ) |
This function unsets binary user data associated with a segment or piece of geometry in the database.
index | - A unique indentifier associated with the user data you want to unset. |
No additional details. See Set_User_Data().
void UnSet_One_User_Data_By_Key | ( | Key | key, |
POINTER_SIZED_INT | index | ||
) |
This function unsets binary user data associated with a segment or piece of geometry in the database.
key | - the key in which the user data should be unset. |
index | - A unique indentifier associated with the user data. |
No additional details.