Functions | |
HC_KEY | Conditional_Include (const char *include, const char *condition) |
Similar to Include_Segment(), but uses a list of conditions that must be satisfied in order for the inclusion to apply. More... | |
HC_KEY | Conditional_Include_By_Key (HC_KEY seg_key, const char *condition) |
Similar to Conditional_Include(), but accepts a key rather than a pathname to identify the segment to be included. More... | |
HC_KEY | Conditional_Include_Key_By_Key (HC_KEY key, char const *condition, HC_KEY includer_key) |
Similar to Conditional_Include_By_Key(), but inserts the include into the segment associated with the passed key. More... | |
HC_KEY | Include_Segment (const char *include) |
Leaves a note for the system directing it to grab a copy of another segment whenever the current one is displayed. More... | |
HC_KEY | Include_Segment_By_Key (HC_KEY seg_key) |
Similar to Include_Segment(), but operates on an object referenced by an HC_KEY. More... | |
HC_KEY | Include_Segment_Key_By_Key (HC_KEY key, HC_KEY includer_key) |
Similar to Include_Segment_By_Key(), but inserts the include into a the segment associated with the passed key. More... | |
Detailed Description
Function Documentation
◆ Conditional_Include()
HC_KEY Conditional_Include | ( | const char * | include, |
const char * | condition | ||
) |
Similar to Include_Segment(), but uses a list of conditions that must be satisfied in order for the inclusion to apply.
- Parameters
-
include - Pathname to extra segment(s) to be included when displaying the current segment. condition - The conditions that are associated with a particular conditional include and that are valid input to Set_Conditions().
- Returns
- The new key for the segment as conditionally included, as opposed to its original key
DETAILS
The Conditional variant of Include_Segment allows the user to register, during the inclusion, one or a series of conditions that must match with the conditions set on the including segment ( see Set_Conditions() ) in order for the inclusion to apply. The conditions are user-defined and have no internal meaning to HOOPS other than as elements that can be compared. Conditions are inherited down the try like other regular attributes and are resolved at draw time when the inheritance from includes and styles are fully resolved.
◆ Conditional_Include_By_Key()
HC_KEY Conditional_Include_By_Key | ( | HC_KEY | seg_key, |
const char * | condition | ||
) |
Similar to Conditional_Include(), but accepts a key rather than a pathname to identify the segment to be included.
- Parameters
-
seg_key - Segment key to extra segment(s) to be included when displaying the current segment. condition - The conditions that are associated with a particular conditional include and that are valid input to Set_Conditions().
- Returns
- The new key for the segment as conditionally included, as opposed to its original key
DETAILS
No additional details. See Conditional_Include().
◆ Conditional_Include_Key_By_Key()
HC_KEY Conditional_Include_Key_By_Key | ( | HC_KEY | key, |
char const * | condition, | ||
HC_KEY | includer_key | ||
) |
Similar to Conditional_Include_By_Key(), but inserts the include into the segment associated with the passed key.
- Parameters
-
key - Segment key in with the condition include will be inserted. condition - The conditions that are associated with a particular conditional include and that are valid input to Set_Conditions(). includer_key - Segment key to extra segment(s) to be included when displaying the segment associated with the key parameter.
- Returns
- The new key for the segment as conditionally included, as opposed to its original key
DETAILS
No additional details. See Conditional_Include().
◆ Include_Segment()
HC_KEY Include_Segment | ( | const char * | include | ) |
Leaves a note for the system directing it to grab a copy of another segment whenever the current one is displayed.
- Parameters
-
include - Name, possibly including wildcards and lists, of extra segment(s) to be included when displaying the current segment.
- Returns
- The new key for the segment as included, as opposed to its original key
DETAILS
Include_Segment() inserts a request into the currently open segment. The request asks that whenever this segment is displayed, the referenced segment should be searched for and included as part of this scene—as if it had been built right into the segment as a subsegment. The included segment comes complete with all its attributes and subsegments, and its own styles and inclusions. It is detached from its regular context. However, if the segment that owns the segment being included has an opinion about something, it doesn't matter.
The primary use of "including"—as opposed to chopping up a segment into subsegments to improve organization—is when the same scene or object needs to appear in several or many contexts. The include can be as simple as an icon or as complex as a complete scene, of which you're going to present multiple simultaneous views on the screen.
The difference between Include_Segment() and Copy_Segment() is that Copy_Segment() actually makes a copy of the referenced segment. You would perform a Copy if you need to make changes and want to leave the original segment alone. If you simply want to 'reuse' a segment by referencing it, you would Include. Think of an Include as a Unix directory soft link.
Includes follow the same inheritance rules as sub-segments. First, if the include has an opinion about an attribute setting, its opinion is used (otherwise the including segment's is used). Second, the include cannot affect the display of the including segment or anything higher up in the tree.
By convention, includes live in the "Include Library" segment tree—their full names should begin with "?Include Library/". This aids in making sure they don't pop up on their own as they would if they were in "?Picture/...". If you do want them in the "Picture" tree, you'll have to protect them from being displayed on their own. The easiest way to do this is to invent your own "include library" segment (down in the picture tree), and to set Visibility to "Off" on the library segment itself.
NOTES
The segment being included must exist at the time Include_Segment() is called, so the system can make the connection.
To be consistent with all the other routines that "Insert" picture pieces into a segment, this routine might be better named "Insert_Include_Request". But just plain Include_Segment() is nicely short.
RESTRICTIONS
The "as-included-by" segment name syntax is ignored when passed to HOOPS as a segment name. This makes it hard to accurately requeue an arbitrary Selection Event.
◆ Include_Segment_By_Key()
HC_KEY Include_Segment_By_Key | ( | HC_KEY | seg_key | ) |
Similar to Include_Segment(), but operates on an object referenced by an HC_KEY.
- Parameters
-
seg_key - Unique numeric identifier to the segment to be included. Accepted as argument in Open_Segment_By_Key().
- Returns
- The new key for the segment as included, as opposed to its original key
DETAILS
No additional details. See Include_Segment()
◆ Include_Segment_Key_By_Key()
HC_KEY Include_Segment_Key_By_Key | ( | HC_KEY | key, |
HC_KEY | includer_key | ||
) |
Similar to Include_Segment_By_Key(), but inserts the include into a the segment associated with the passed key.
- Parameters
-
key - Unique numeric identifier to the segment which will be included in "includer_key". includer_key - Unique numeric identifier to the segment in which "key" will be included. Accepted as argument in Open_Segment_By_Key().
- Returns
- The new key for the segment as included, as opposed to its original key.
DETAILS
No additional details. See Include_Segment().