HC_Include_Segment

Key HC_Include_Segment(char const *include)
Key HC_Include_Segment(char const include)

Leaves a note for the system directing it to grab a copy of another segment whenever the current one is displayed.

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.

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.

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.

HC_Copy_Segment, HC_Flush_Contents, HC_Style_Segment, HC_Open_Segment, HC_Set_Visibility, HC_Conditional_Include

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