|HC_KEY||Renumber_Key (HC_KEY oldkey, HC_KEY newkey, const char *scope)|
|Changes the key for a segment, include, style, or piece of geometry to a value more useful to your program. More...|
|const char *||scope|
Changes the key for a segment, include, style, or piece of geometry to a value more useful to your program.
oldkey - The key generated by HOOPS and returned in a previous call to one of the "Insert" routines, Find_Contents() , or Show_Selection_Element() . newkey - The new value to be used as the key for the item. scope - Either "local" or "global". Uppercase versus lowercase doesn't matter, nor do trailing blanks. Can be abbreviated.
- The key to the object.
Items of geometry, in HOOPS, don't have full-fledged names as segments do. Keys were therefore invented as a method of referring to a particular item of geometry. They were extended to be able to refer to segments, include references, and style references as well as to geometry. Keys are normally generated by HOOPS and returned to you from calls to various routines such as Insert_Line() .
Renumber_Key() is a convenient routine that lets you replace the key number that HOOPS picked for an item and use a number more pleasing to your program instead. All the numbers HOOPS picks will be negative. All the numbers you pick must be zero or positive. Renumber_Key() can also be used to restore the object to use the previously renumbered old key instead of the current key, if the argument newkey is set to a special value of -1.
A common example of the use of Renumber_Key() is to index into an array. To do this you would assign values such as 1, 2, 3, as you inserted your geometry. Then Show_Selection_Element() , for example, might later return 1, 2, 3, - values you could conveniently use.
Renumber_Key() returns the new key to which the object is now referred. It is useful for obtaining the key originally assigned by HOOPS by calling it with an argument of -1. In the case, the value returned is the key that was originally assigned by HOOPS.
The scope flag controls whether your key is defined in terms of the containing segment or whether it is global. If it's local, you have to have the containing segment open before HOOPS will be able to see that key. But the key number "1", for example, can be reused in any number of different places in your segment tree. If it's global, such as the keys HOOPS generates, you don't need to go through the ritual of opening a segment before using the key—but the key must be globally unique.
If a key occurs both locally and globally, the local one takes precedence as long as the segment is open. You can "hide" the distracting local scope temporarily by opening up another segment, for example the "/" root segment.
If a key is "global", the path name is ignored, only the base name is used. For example, if "?Include Library/scene/object" refers to "1" globally, accessing "1" from anywhere in the segment tree is equivalent to accessing "?Include Library/scene/object".
When geometry or segments that have not been renumbered are saved to metafile, their keys are not written out. Renumbered keys are written out and retrieved—which is very useful. But when they are read back in you will get errors if there are conflicts with key values already assigned by the program doing the reading. (The use of "local" keys avoids most of these problems.)
For speed, only the first letter of the scope is checked for validity.
To tell whether a renumbered key has local or global scope, you can use Show_Key_Status().
HOOPS will be slightly less speedy looking up a renumbered key than the original key. The original key can always be used instead of the renumbered key on calls to HOOPS, if you want. (Though the renumbered key, once it exists, will be the one returned by all HOOPS routines except Show_Original_Key() and Show_Selection_Original_Key().) Pass the renumbered key to Show_Original_Key() to get the original key.
Keys can be renumbered back to the original value, essentially cancelling the effect of a call to Renumber_Key() .
Keys can be renumbered more than once.
Keys are defined to be a "pointer sized integer". On most systems a long is large enough. The one notable exception is 64-bit windows which (in its infinite wisdom) chose to make it a "long long". The best bet is to use either the HC_KEY or POINTER_SIZED_INT types that HOOPS provides.