Functions
Include_Segment

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.

See also
Show_Conditional_Include, Set_Conditions, Show_Conditions

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

See also
Copy_Segment, Flush_Contents, Style_Segment, Open_Segment, Set_Visibility, Conditional_Include

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