Functions | |
int | Compute_Selection (const char *display, const char *start_seg, const char *action, double x, double y) |
int | Compute_Selection_By_Area (const char *display, const char *start_seg, const char *action, double left, double right, double bottom, double top) |
int | Compute_Selection_By_Polygon (const char *display, const char *start_seg, const char *action, int pcount, const HC_POINT *points) |
int | Compute_Selection_By_Polylin (const char *display, const char *start_seg, const char *action, int pcount, const HC_POINT *points) |
int | Compute_Selection_By_Volume (const char *display, const char *start_seg, const char *action, double left, double right, double bottom, double top, double hither, double yon) |
int Compute_Selection | ( | const char * | display, |
const char * | start_seg, | ||
const char * | action, | ||
double | x, | ||
double | y | ||
) |
Forces the explicit computation and generation of selection events.
display | - Commonly "?Picture". In general, a segment with an attached device driver that knows how to test for selections. |
start_seg | - A segment somewhere in the tree belonging to display, at which point it would be good to start selection testing. If blank or null, then testing begins at display. |
action | - One of "v", "^", "*", or "O". Action is compared against the Selectability attribute settings as testing proceeds. See details for a discussion on actions. |
x | - The nominal mouse x-position, measured in window coordinates: -1.0 to +1.0. If start-seg is non-blank, then the parameter is taken in terms of the window in effect on start-seg, otherwise in terms of display. |
y | - The nominal mouse y-position |
Compute_Selection() allows access to the internal routines used for figuring selection events from mouse locations. Given the usual locater information, Compute_Selection() will observe the appropriate attributes and find out what lies at that position. If anything is found, a Selection Event is generated and is made the "current" event. Any previous current event is discarded. The various Show_Selection() routines can then be used to retrieve information about the selection.
If a value for start_seg is given, then testing begins there. Coordinates are measured in terms of that segment's effective window, and testing is restricted to that window.
The available values for actions are detailed in Set_Selectability(). Additionally, you can set Driver Options and Heuristics which pertain to selection. These values will override the settings on the segment for this selection event. Currently this is the selection proximity Driver Option and the selection level, visual selection, detail selection, selection sorting, related selection limit and internal selection limit which can be found in Set_Heuristics. See the documentation of Set_Driver_Options and Set_Heuristics for specific details on each of these options.
Compute_Selection_By_Area() lets you specify a rectangular region of the screen instead of a single point. Every item of geometry within or overlapping that region is identified and returned as part of the selection event. The "selection proximity" Driver Option is ignored in the case of testing "by area", since the geometry must be properly within or overlapping the specified region. Everything within the area has equal status.
A typical programming sequence that computes a selection and does something with every one of the selected items follows (in pseudo-C):
if (Compute_Selection_By_Area (...) > 0) do { Show_Selection_Element (...) /*... process item... */ } while (Find_Related_Selection())
As with regular selection events, the "related" selections are returned in proximity order. If the proximities are zero (the position is within the item). The related sections are in front-to-back order. For "by area" selecting, the ordering is from the approximate center of the area.
Compute_Selection_By_Volume() lets you specify a volume of the screen. The meaning of "screen Z" coordinates is described in detail under Show_Selection_Position() . Hither must be less than or equal to yon. If display is given as blank or null, an "object space" test is done, as described below. Similar to Compute_Selection_By_Area() , Compute_Selection_By_Polylin() lets you specify a polyline. Any object intersected by the path of the polyline is selected. The points that define the polyline have their X and Y values defined in window coordinates. The Z values are ignored.
Compute_Selection_By_Polygon() lets you specify a polygon instead of a polyline. Every item of geometry, within or overlapping the region defined by the polygon, is identified and returned as part of the selection event. The points that define the polygon have their X and Y values defined in window coordinates. The Z values are ignored.
Compute_Selection_By_Volume() does its selection in "object space". The idea of an object-space test is to search a certain volume of space without reference to any screen display. In particular:
The status returned by Show_Selection_Source() will be a one if action was "v" or "*", otherwise zero.
Selectability and Visibility are enforced during a Compute_Selection() just as they are during normal user input. An object must be both visible and selectable to be selected. The "attribute lock" Rendering Option might be useful for overriding these.
In the current implementation, display, if given, has to be a real driver segment. There are, however, ways to get around this. Selecting works if the window visibility for display itself is turned off. Alternatively, a debugging driver—"?driverprintf/null"—can be used for display (the "?driver/null" driver cannot do selection testing.) If you do use "printf/null", the "physical size" Driver Option might be useful to get the nominal shape of the screen right.
In the current implementation, if a blank or null start_seg is given to Compute_Selection_By_Area() (so that window-selecting is turned on), then at most one window selected—the window in effect for the center of the area. Geometry testing will be limited to that one window.
In the current implementation, the selection-testing code can include a geometry item even if the item is completely covered up by a polygon closer to the camera. For example—if the item doesn't know how to tell that the geometry is actually invisible. (Note the closer polygon will be returned first.) Likewise, once the testing code decides the action is within a particular window it becomes oblivious to extraneous windows that may overlap some of the geometry.
Compute_Selection() always makes its result the "current" event. To take advantage of having a queue of events, you could use Queue_Location_Event() to save the information. Then do Compute_Selection() when you see the Location event coming off the queue.
Compute_Selection_By_Area() typically requires first letting the user rubberband a bounding box into position. The bounding box is conveniently done in a subsegment that has a viewing camera such as
Set_Camera_By_Volume ("stretched", -1., 1., -1., 1.)
This makes the geometry coordinate system the same as the window coordinate system. (The "quick moves" Heuristic can also be useful for rubberbanding.)
Once you have called Compute_Selection(), you can iterate through the list of selected objects via Find_Related_Selection(). Note that the returned selected objects are sorted by z-order for direct hits (objects that were directly under the selection ray calculated from the position camera and the hit point) followed by objects that were not in the path of the ray but were within the "selection proximity" of the ray and that these are sorted by their proximity to the ray.
The start_seg parameter must not be an included segment.
int Compute_Selection_By_Area | ( | const char * | display, |
const char * | start_seg, | ||
const char * | action, | ||
double | left, | ||
double | right, | ||
double | bottom, | ||
double | top | ||
) |
Similar to Compute_Selection(), but operates on a rectangular area.
display | - Commonly "?Picture". In general, a segment with an attached device driver that knows how to test for selections. |
start_seg | - A segment somewhere in the tree belonging to display, at which point it would be good to start selection testing. If blank or null, then testing begins at display. |
action | - One of "v", "^", "*", or "O". Action is compared against the Selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions. |
left | - The -(x) boundary for a rectangular area of the screen, in window coordinates |
right | - The (x) boundary for a rectangular area of the screen, in window coordinates |
bottom | - The -(y) boundary for a rectangular area of the screen, in window coordinates |
top | - The (y) boundary for a rectangular area of the screen, in window coordinates |
No additional details. See Compute_Selection()
The start_seg parameter must not be an included segment.
int Compute_Selection_By_Polygon | ( | const char * | display, |
const char * | start_seg, | ||
const char * | action, | ||
int | pcount, | ||
const HC_POINT * | points | ||
) |
Similar to Compute_Selection(), but operates on a polygonal area.
display | - Commonly "?Picture". In general, a segment with an attached device driver that knows how to test for selections. |
start_seg | - A segment somewhere in the tree belonging to display, at which point it would be good to start selection testing. If blank or null, then testing begins at display. |
action | - One of "v", "^", "*", or "O". Action is compared against the Selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions. |
pcount | - Number of points contained in the points list. |
points | - Set of points that comprise the polyline or polygon used to compute the selection. |
No additional details. See Compute_Selection()
The start_seg parameter must not be an included segment.
int Compute_Selection_By_Polylin | ( | const char * | display, |
const char * | start_seg, | ||
const char * | action, | ||
int | pcount, | ||
const HC_POINT * | points | ||
) |
Similar to Compute_Selection(), but operates on polyline intersections.
display | - Commonly "?Picture". In general, a segment with an attached device driver that knows how to test for selections. |
start_seg | - A segment somewhere in the tree belonging to display, at which point it would be good to start selection testing. If blank or null, then testing begins at display. |
action | - One of "v", "^", "*", or "O". Action is compared against the Selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions. |
pcount | - Number of points contained in the points list. |
points | - Set of points that comprise the polyline or polygon used to compute the selection. |
No additional details. See Compute_Selection()
The start_seg parameter must not be an included segment.
int Compute_Selection_By_Volume | ( | const char * | display, |
const char * | start_seg, | ||
const char * | action, | ||
double | left, | ||
double | right, | ||
double | bottom, | ||
double | top, | ||
double | hither, | ||
double | yon | ||
) |
Similar to Compute_Selection(), but operates on a cuboid volume.
display | - Commonly "?Picture". In general, a segment with an attached device driver that knows how to test for selections. If blank or null, then an "object space selection" is made (see below.) |
start_seg | - A segment somewhere in the tree belonging to display, at which point it would be good to start selection testing. If blank or null, then testing begins at display. |
action | - One of "v", "^", "*", or "O". Action is compared against the Selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions. |
left | - The -(x) boundary for a rectangular area of the screen, in window coordinates |
right | - The (x) boundary for a rectangular area of the screen, in window coordinates |
bottom | - The -(y) boundary for a rectangular area of the screen, in window coordinates |
top | - The (y) boundary for a rectangular area of the screen, in window coordinates |
hither | - The -(z) boundary, described in Show_Selection_Position() . |
yon | - The (z) boundary, described in Show_Selection_Position() . |
No additional details. See Compute_Selection()