Brief Index      Full Index      Events Index      I.M. Reference

Find_Related_Selection

Functions

HC_BOOLEAN Find_Related_Selection (void)

Function Documentation

HC_BOOLEAN Find_Related_Selection ( void  )

Allows you to inspect the "next best" geometry item with the current Selection Event.

Returns:
success

DETAILS

One mouse action (button-down, for example) generates at most one Selection Event. However, more than one geometry item can lie under or near the mouse.

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()); 

NOTES

"Related" Selections are only interesting if geometry testing is turned on. In the current implementation, at most one window will be included in the selection event, even if other windows are nearby and even if the included window is transparent. The window itself (if window selectability is on) will be last in the list of related selections.

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.

RESTRICTIONS

See also:
Get_Selection, Enable_Selection_Events, Compute_Selection, Set_Selectability, Set_Visibility.

Brief Index      Full Index      Events Index      I.M. Reference