Set_User_Options

Functions

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. More...
 
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. More...
 
void Set_User_Index (long index, const void *data)
 Associates a segment with an index into a user-defined array of option strings. More...
 
void Set_User_Options (const char *list)
 Allows you to create new "attributes" of your own choosing. More...
 
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. More...
 
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. More...
 
void UnSet_One_User_Index (long index)
 Removes a given setting established by a previous call to Set_User_Options(), rather than all settings. More...
 
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. More...
 
void UnSet_User_Options (void)
 Removes all settings established by a previous call to Set_User_Options(). More...
 

Detailed Description

Function Documentation

◆ Set_User_Data()

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.

Parameters
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.

DETAILS

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.

RESTRICTIONS

This data is not available from HIC unlike user indices.

See also
Show_One_User_Data

◆ Set_User_Data_By_Key()

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.

Parameters
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.

DETAILS

No additional details. See Set_User_Data().

See also
Show_One_User_Data

◆ Set_User_Index()

void Set_User_Index ( long  index,
const void *  data 
)

Associates a segment with an index into a user-defined array of option strings.

Parameters
index- An index into a user-defined array of options.
data- The value of the user data to be associated with its corresponding array index. Passed by reference always.

DETAILS

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().

See also
Set_User_Options, Show_User_Index

◆ Set_User_Options()

void Set_User_Options ( const char *  list)

Allows you to create new "attributes" of your own choosing.

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

DETAILS

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.

NOTES

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");

RESTRICTIONS

None.

See also
Renumber_Key, Show_One_User_Option

◆ UnSet_One_User_Data()

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.

Parameters
index- A unique indentifier associated with the user data you want to unset.

DETAILS

No additional details. See Set_User_Data().

See also
Set_User_Data

◆ UnSet_One_User_Data_By_Key()

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.

Parameters
key- the key in which the user data should be unset.
index- A unique indentifier associated with the user data.

DETAILS

No additional details.

See also
Set_User_Data

◆ UnSet_One_User_Index()

void UnSet_One_User_Index ( long  index)

Removes a given setting established by a previous call to Set_User_Options(), rather than all settings.

Parameters
index- An index into a user-defined array of options.

DETAILS

No additional details. See Set_User_Options()

See also
Set_User_Index

◆ UnSet_One_User_Option()

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.

Parameters
which- A particular user option whose data should be discarded.

DETAILS

No additional details. See Set_User_Options()

See also
Set_User_Options

◆ UnSet_User_Options()

void UnSet_User_Options ( void  )

Removes all settings established by a previous call to Set_User_Options().

DETAILS

No additional details. See Set_User_Options()

See also
Set_User_Options