Traversal Control

Both the display and pick traversal processes can be controlled by their respective user-definable controls:

display traversal control elements
pick traversal control elements
maximum traversal depth
segment control
element control

Traversal control elements are elements that can be placed in a segment to control the display or pick traversal process. Pick traversal control affects the detectability or ability to pick parts of the segment network. Display traversal control elements affect both display and pick traversal (this is necessary so a pick operation does not pick an invisible object), pick traversal control elements only affect pick traversal, and segment- and element-control elements control either or both.

The two routines that set traversal control (i.e., the ones that insert display-traversal control and pick-traversal control elements into the open segment) are set_disp_traversal_control and set_pick_traversal_control:

set_disp_traversal_control(〈fildes〉, 〈control〉);
- and
set_pick_traversal_control(〈fildes〉, 〈control〉);

where:

〈control〉 determines what part of the segment network is affected by the traversal control element. It can be one of the following values:
- TRAVERSAL_RETURN: This causes traversal of the current segment to stop. Control is returned to the parent segment, where traversal continues with the next element; that one following the most recently-executed segment-calling element. Thus, traversal of the current segment is affected, while traversal of the parent segment is not affected.
- TRAVERSAL_ABORT: This causes the entire traversal process to terminate. Traversal of the segment being traversed, as well as all segments calling this segment, are terminated.
- TRAVERSAL_CONTINUE: Continue the traversal, effectively ignoring the traver-sal-control element. TRAVERSAL_CONTINUE acts to disable traversal control elements, holding a place for the traversal control element in the segment while having no affect on traversal.

The following figure shows how different values of 〈control〉 would affect the display of the segment network shown.

Figure 7-31 Display List with Traversal Control

Assuming the previous display list, and having a 〈control〉 parameter value of TRAVERSAL_CONTINUE in effect, the output would be:

Figure 7-32 Title not available (Traversal Control)

Assuming the previous display list, and having a 〈control〉 parameter value of TRAVERSAL_RETURN in effect, the output would be:

Figure 7-33 Title not available (Traversal Control)

And finally, assuming the previous display list, and having a 〈control〉 parameter value of TRAVERSAL_ABORT in effect, the output would be:

Figure 7-34 Title not available (Traversal Control)

Traversal Depth

The traversal depth is defined to be the depth into the hierarchical structure of the currently traversed segment. At the start of the traversal process, the traversal depth is 0. Each time a call_segment or execute_segment element (conditional or not) is traversed, the traversal depth is incremented. As the traversal process proceeds deeper into a segment network the traversal depth increases. Similarly, when traversal of a segment is terminated and control is returned to its parent segment, the traversal depth is decremented.

Display List maintains a value for its maximum traversal depth; by default, it is 42. When the maximum traversal depth would be exceeded during traversal, a warning is generated and the segment referenced by the call_segment or execute_segment element is not traversed.

You can define your own value for the maximum traversal depth by calling set_traversal_depth and specifying an appropriate value. You can inquire the maximum depth with inq_traversal_depth:

set_traversal_depth(〈fildes〉, 〈depth〉);
- and
inq_traversal_depth(〈fildes〉, 〈depth〉);

where:

〈depth〉 is an integer value (for set_traversal_depth) or a pointer to an integer (for inq_traversal_depth). There is no upper limit on what the maximum traversal depth except that imposed by the number of bits in an integer. A negative value for 〈depth〉 will cause an error and the set_traversal_depth call will be ignored.

The maximum traversal depth prevents infinite looping when traversing recursive networks.

Segment Control and Element Control

Each segment and element in a display list has two more attributes: visibility and pickability. The default value of these attributes is visible and pickable. The attributes are controlled and inquired by the seg_control, inq_seg_control, ele_control and inq_ele_control calls, respectively:

seg_control(〈fildes〉, 〈segno〉, 〈control〉, 〈on〉);
inq_seg_control(〈fildes〉, 〈segno〉, 〈control〉);
ele_control(〈fildes〉, 〈control〉, 〈on〉);
inq_ele_control(〈fildes〉, 〈control〉);

where:

〈segno〉 is an integer specifying the segment number.
〈control〉 is an integer flag indicating which control flag(s) to affect. These flags are:
- DISP_IGNORE — The segment/element is ignored during display traversal.
- PICK_IGNORE — The segment/element is ignored during pick traversal.
- BOTH_IGNORE — The segment/element is ignored during pick traversal and display traversal.
- NONE_IGNORE — The segment/element is not ignored during pick traversal or display traversal.
The segment-related routines (seg_control and inq_seg_control) support a third attribute: HIGHLIGHT. When this is used, the object is drawn highlighted.
〈on〉 is a boolean that causes the flags specified in 〈control〉 to be set (if 〈on〉 is TRUE) or cleared (if 〈on〉 is FALSE).

Unlike traversal control elements and filters, an element's DISP_IGNORE flag does not affect its pickability. To affect both visibility and pickability, use both flags. Also, if an element is normally invisible/unpickable (e.g., application_data) it cannot be made visible/pickable by clearing control flags.

Traversal Control

Technical documentation

» Table of Contents

» Glossary

» Index

Traversal Depth

Segment Control and Element Control