The IDLgrBuffer::Select function method returns a list of objects selected at a specified location. If no objects are selected, the Select function returns -1.

Note: IDL returns a maximum of 512 objects. This maximum may be smaller if any of the objects are contained in deep model hierarchies. Because of this limit, it is possible that not all objects eligible for selection will appear in the list.

Syntax

Result = Obj->[IDLgrBuffer::]Select(Picture, XY [, DIMENSIONS=[width, height]] [, /ORDER] [, SUB_SELECTION=variable] [, UNITS={0 | 1 | 2 | 3}])

Return Value

Returns a list of objects selected at a specified location. Returns -1 if no objects are selected.

Arguments

Picture

The view, viewgroup, or scene (an instance of the IDLgrView, IDLgrViewgroup, or IDLgrScene class) whose children are among the candidates for selection.

If the first argument is a scene or viewgroup, then the returned object list will contain one or more views. If the first argument is a view, the list will contain atomic graphic objects (or model objects which have their SELECT_TARGET property set). Objects are returned in order, according to their distance from the viewer. The closer an object is to the viewer, the lower its index in the returned object list. If multiple objects are at the same distance from the viewer (views in a scene or 2-D geometry), the first object drawn will appear at a lower index in the list. (The ORDER keyword can be used to change this behavior.)

XY

A two-element array defining the center of the selection box in device space. By default, the selection box is 3 pixels by 3 pixels.

Keywords

DIMENSIONS

Set this keyword to a two-element array [w, h] to specify that the selection box will have a width w and a height h, and will be centered about the coordinates [x, y] specified in the XY argument. The box occupies the rectangle defined by:

(x-(w/2), y-(h/2)) - (x+(w/2), y+(h/2))

Any object which intersects this box is considered to be selected. By default, the selection box is 3 pixels by 3 pixels.

ORDER

Set this keyword to control how objects that are the same distance from the viewer are ordered in the selection list. If ORDER=0 (the default), the order of objects in the selection list will be the same as the order in which the objects are drawn. If ORDER=1, the order of objects in the selection list will be the reverse of the order in which they are drawn. This keyword has no affect on the ordering of objects that are not at the same distance from the viewer.

Tip: If you are using DEPTH_TEST_FUNCTION=4 (“less than or equal”) on your graphics objects, set ORDER=1 to return objects at the same depth in the order in which they appear visually.

SUB_SELECTION

Set this keyword to a named variable that upon return will contain a vector of references to the graphic objects that were sub-selected at the given location. This vector includes all graphic objects that are:

  • Graphic objects contained by the nearest selected object (the first object in the return value)
  • Select targets (IDLgrModel objects with the SELECT_TARGET property set)
  • Graphic objects displayed at the given XY location

UNITS

Set this keyword to indicate the units of measure. Valid values are:

0

Device (default)

1

Inches

2

Centimeters

3

Normalized: relative to the dimensions of the graphics destination

Version History

5.0

Introduced

6.1

Added SUB_SELECTION keyword