Functions | |
HC_BOOLEAN | Find_Related_Selection (void) |
HC_BOOLEAN Find_Related_Selection | ( | void | ) |
Allows you to inspect the "next best" geometry item with the current Selection Event.
The "Show Selection" routines that inspect a Selection Event normally return information about the best item of geometry that was selected. ("Best" is defined as the selectable item nearest the mouse. If more than one geometry is right under the mouse, then it's the one closest to the camera.) Find_Related_Selection() , each time it is called, lets you inspect the next best item. The previous item information is discarded. When nothing more is available the entire Selection Event is discarded and Find_Related_Selection() returns false.
It is not necessary to look at all the related selections---you might only be interested in the best selection or the first few selections. Anything that causes the current event to be discarded ( Await_Event() , Get_Selection() , etc.) gets rid of the remaining uninspected related selections.
A typical C programming sequence that acquires a selection and does something with every one of the selected items would be the following:
HC_Get_Selection(...); do { HC_Show_Selection_Pathname (...); HC_Show_Selection_Element (...); /*... process item... */ } while (HC_Find_Related_Selection());
Use the "related selection limit" Heuristic and/or the "selection proximity" Driver Option judiciously to limit the amount of related-selection work the system has to do.