Functions | |
void | Include_Segment (const char *include) |
HC_KEY | KInclude_Segment (const char *include) |
void | Include_Segment_By_Key (HC_KEY seg_key) |
HC_KEY | KInclude_Segment_By_Key (HC_KEY seg_key) |
void | Conditional_Include (const char *include, const char *conditions) |
HC_KEY | KConditional_Include (const char *include, const char *conditions) |
void | Conditional_Include_By_Key (HC_KEY seg_key, const char *conditions) |
HC_KEY | KConditional_Include_By_Key (HC_KEY seg_key, const char *conditions) |
void 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.
include | - Name, possibly including wildcards and lists, of extra segment(s) to be included when displaying the current segment. |
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.
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.
HC_KEY KInclude_Segment | ( | const char * | include | ) |
Similar to Include_Segment(), but returns an HC_KEY to the object.
include | - Name, possibly including wildcards and lists, of extra segment(s) to be included when displaying the current segment. |
void Include_Segment_By_Key | ( | HC_KEY | seg_key | ) |
Similar to Include_Segment(), but operates on an object referenced by an HC_KEY.
seg_key | - Unique numeric identifier to of the segment to be included. Accepted as argument in Open_Segment_By_Key. |
HC_KEY KInclude_Segment_By_Key | ( | HC_KEY | seg_key | ) |
Similar to KInclude_Segment(), but operates on an object referenced by an HC_KEY.
seg_key | - Unique numeric identifier to of the segment to be included. Accepted as argument in Open_Segment_By_Key. |
void Conditional_Include | ( | const char * | include, | |
const char * | conditions | |||
) |
Similar to Include_Segment(), but uses a list of conditions that must be satisfied in order for the inclusion to apply.
include | - Pathname to extra segment(s) to be included when displaying the current segment. | |
conditions | - The conditions that are associated with a particular conditional include and that are valid input to Set_Conditions(). |
HC_KEY KConditional_Include | ( | const char * | include, | |
const char * | conditions | |||
) |
Similar to Conditional_Include(), but returns a key to the included segment.
include | - Pathname to extra segment(s) to be included when displaying the current segment. | |
conditions | - The conditions that are associated with a particular conditional include and that are valid input to Set_Conditions(). |
void Conditional_Include_By_Key | ( | HC_KEY | seg_key, | |
const char * | conditions | |||
) |
Similar to Conditional_Include(), but accepts a key rather than a pathname to identify the segment to be included.
seg_key | - Segment key to extra segment(s) to be included when displaying the current segment. | |
conditions | - The conditions that are associated with a particular conditional include and that are valid input to Set_Conditions(). |
HC_KEY KConditional_Include_By_Key | ( | HC_KEY | seg_key, | |
const char * | conditions | |||
) |
Similar to Conditional_Include(), but accepts a key rather than a pathname to identify the segment to be included.
seg_key | - Segment key to extra segment(s) to be included when displaying the current segment. | |
conditions | - The conditions that are associated with a particular conditional include and that are valid input to Set_Conditions(). |