Show_Selection_Element

Functions

void Show_Selection_Element (HC_KEY *key, int *offset1, int *offset2, int *offset3)
 Returns the key of the database element that was selected by the user, plus an offset within that element. More...
 

Detailed Description

Function Documentation

◆ Show_Selection_Element()

void Show_Selection_Element ( HC_KEY *  key,
int *  offset1,
int *  offset2,
int *  offset3 
)

Returns the key of the database element that was selected by the user, plus an offset within that element.

Parameters
key- The key of the "best match" element of your scene. Passed by reference always. Returned to user.
offset1- A rough indication of what came closest within the element pointed to by key. See below for details. Passed by reference always. Returned to user.
offset2- As above.
offset3- As above.

DETAILS

Once a "selection" event has reached the front of the event queue and become the current event—either by enabling selection events and calling Await_Event() , or by calling Get_Selection() to do all the work—your program can ask for details about it. Show_Selection() and Get_Selection() return the name of the segment that was selected; Show_Selection_Element() can be used to identify the exact element in either case. The information is returned as a key and three offsets. The key is that of the item of geometry if geometry was selected, or of the segment itself if a window was selected. The key might be compared against a list of "interesting" keys saved from the original calls to Insert_Polygon() , Insert_Polyline() , etc., or it can be used in calls to the geometry "Show" routines ( Show_Key_Type() , Show_Polygon() , etc.)
The offsets have the following meanings when the key value is:

  • Arc
    • offset1: is a 1, a 2, or a 3, indicating the nearest of the start point, the midpoint, or the end point of the arc.
    • offset2: similarly indicates the second nearest of those reference points.
    • offset3: is 0.
  • Circle or Ellipse
    • offset1: is a 1, a 2, or a 3, indicating the nearest of the original three definition points.
    • offset2: similarly indicates the second nearest definition point.
    • offset3: is 0.
  • Image
    • offset1: is the X offset.
    • offset2: is the Y offset within the array, counting the upper-left pixel as (0, 0).
    • offset3: is 0.
  • Marker
    • offset1: is always set to 0.
    • offset2: is always set to 0.
    • offset3: is always set to 0.
  • NURBS Curve
    • offset1: is the index of the nearest control point (starting at 0).
    • offset2: is set to -1.
    • offset3: is set to -1.
  • Polygon
    • offset1: is the vertex nearest to where the user's pointing.
    • offset2: is the vertex that defines the best edge
    • offset3: is 0.
    • Note: If in a polygon the last vertex was coincident with the first, Insert_Polygon() may have trimmed it off.
  • Polyline
    • offset1: counting the first vertex as offset zero, is the offset within the polyline of the vertex nearest to where the user is pointing.
    • offset2: is the connecting vertex (choice of two) that defines the "best edge"
    • offset3: is 0.
  • Segment
    • offset1: is set to -1.
    • offset2: is set to -1.
    • offset3: is set to -1.
    • Note: this indicate that a window was hit as opposed to a piece geometry.
  • Shell or Mesh
    • offset1: is the vertex nearest to where the user's pointing.
    • offset2: is the vertex that defines the best edge.
    • offset3: normally the best face.
    • Notes:
      • If there is no visible and selectable face attached to the edge from offset1 to offset2, then offset3 is -1. See Insert_Mesh() for a description of the mesh vertex and face numbering system.
      • If an isoline was selected, offset1 is -1. Offset2 is the index to the selected isoline. Offset3 is the total number of isolines in the selected shell. Note that the total number of isolines is needed if you want to explicitly change attributes on the isoline to highlight it.
  • Text
    • offset1: is always set to 0.
    • offset2: counting the first character as offset zero, is the offset of the character nearest to where the user is pointing.
    • offset3: is always set to 0.

NOTES

Negative offsets will only be returned if a window is the selected element. This is a quick way to differentiate between window selections and geometry selections.
If a variety of types of keys are selectable, Show_Key_Type() might be helpful in determining the meaning of key.
If the selecting situation is totally ambiguous—a polyline was defined with coincident vertices, for example, or two polygons occupy the same position on the screen (and hidden surfaces are not enabled)—the system will have made an arbitrary choice. See Find_Related_Selection() .
If the heuristic "internal selection element = -1" is set, then the subgeometry elements defined in offset1, offset2 and offset3 are not guaranteed to be the best elements for that specific piece of geometry. For example, if a shell that represented a sphere was selected, then a back face may be passed back rather than the face on the front of the sphere.

RESTRICTIONS

See also
Renumber_Key, Show_Key_Type, Await_Event, Get_Selection, Enable_Selection_Events, Find_Related_Selection, Show_Selection, Show_Selection_Position, Show_Selection_Pathname, Show_Selection_Keys, Show_Selection_Source, Set_Selectability, Delete_By_Key, Edit_Polygon, Insert_Shell, Show_Polyline.