Brief Index      Full Index      Events Index      I.M. Reference

Collect_Area_Samples

Functions

int Collect_Area_Samples (double left, double right, double bottom, double top)

Function Documentation

int Collect_Area_Samples ( double  left,
double  right,
double  bottom,
double  top 
)

Gathers all objects that have been drawn in the selection area, and prepares them to be returned to the user.

Parameters:
left- The left bound of the selection point, in window coordinates.
right- The right bound of the selection point, in window coordinates.
bottom- The bottom bound of the selection point, in window coordinates.
top- The top bound of the selection point, in window coordinates.
Returns:
The number of unique selection items found in the selection region, as determined by the selection 'options'.

DETAILS

This routine will gather all objects that have been drawn in the specified selection area and prepare them to be returned to the user. The objects that have been drawn in the specified selection area correspond with what is currently visible on screen. After calling this function, Find_Next_Sample should be used to iterate through the list of selected items and obtain more detailed information about each one.

The parameters describe a rectangle where the selection should be processed. This would be a small region around the point that the end-user clicked on, or a selection box (area). Note that to specify a single pixel, use the same value for 'left' and 'right', as well as 'top' and 'bottom'.

Any calls to this routine will obtain results from the 'current' selection buffer, which is the one created by the most recent call to Begin_Buffered_Selection. If you wish to perform a selection after editing the scene in some way, remember to first call End_Buffered_Selection, and then once again call Begin_Buffered_Selection to begin a new buffered selection process.

If there was no valid selection buffer the function will return -1. (For example, maybe there was not a prevoius call to Begin_Buffered_Selection, or the hardware doesn't support the buffered selection capability.)

NOTES

The "related selection limit" Heuristic does not apply. Collect_Area_Samples returns all the items in the specified area, and then they should be interated through.

The 'selection proximity' Driver_Option does not apply. If you wish to perform an 'aperture' select, for example, as a result of the end-user doing a 'single click/point select' on an entity such as a polyline, but wish to give the user some level of flexibility so that they don't have to select precisely on the visible pixel(s) of the polyline, you should pass in a small box region as the selection region. For example, if you want to collect samples for a .5cm square box, you would first obtain "resolution" info from Show_Device_Info, calculate the # of pixels/cm, and then use Compute_Coordinates to convert from 'pixels' to 'window' coordinates (using the window coordinates for Collect_Area_Samples).

There is a subtle implication of selecting on what is visible on the screen: if you happen to pass in a single pixel as the 'selection region' and that falls between the dashes in a dashed line, note that the line would not get selected.

RESTRICTIONS

Currently, samples can only be requested for the specified rectangular region. It is possible that support for non-rectangular selections could be added in the future (such as polyline or polygon).

See also:
Begin_Buffered_Selection, End_Buffered_Selection, Find_Next_Sample, Show_Sample_Max_Length

Brief Index      Full Index      Events Index      I.M. Reference