C++
int acedSSNameX( struct resbuf ** rbpp, const ads_name ss, int i );
File
acedads.h
Description
Retrieves information about how one or more elements in a selection set were created.
Note Only selection sets with entities from the current drawing's model space and paper space (not nongraphical objects or entities in other block definitions) can be retrieved by this function.
Call acutRelRb() to deallocate resbufs pointed to by rbpp.
acedSSNameX() returns RTNORM if successful; otherwise, it returns RTERROR.
The contents of the list returned from this function is composed of a series of sublists, each encapsulated within its own RTLB/RTLE pair. At the top level, there is a sublist for the i'th entity (or, if i == -1, a series of sublists - one for each entity in the selection) followed by a sublist for each window, window polygon, crossing window, and crossing polygon used during selection. Windows and crossing windows are considered to be polygons with four vertex points.
Each entity data list contains certain information that is selection method independent:
| RTSHORT | selection method |
| RTENAME | picked entity's entity name |
| RTSHORT | GS marker |
The selection method will be one of the following:
| 0 | non-graphical selection (the "X" or "L" modes of ssget) |
| 1 | pick point selection |
| 2 | window or window polygon selection |
| 3 | crossing or crossing polygon selection |
| 4 | fence selection |
| 5 | subentity selection |
The GS (graphic system) marker will be 0 for entities that do not support them or for non-graphical selection methods. The GS marker will be less than 0 if the entity type supports them but the marker is invalid for some reason. The GS marker will be greater than 0 if it's a valid marker.
What follows the GS marker value will depend on how the entity was selected as well as whether or not the current view is a World Coordinate System (WCS) plan view.
Non-Graphical Selection
If the selection method was non-graphical, the selection method, entity name, and GS marker will be the only information in the sublist, for example:
RTLB RTSHORT : 0 RTENAME : <Entity name: 2ac0548> RTSHORT : 0 RTLE
Pick Point Selection
For entities selected by a pick point, information about the point will follow the GS marker information. The point information will be bracketed by an RTLB/RTLE pair
The point information describes the pick point in a display independent manner. In a normal view this is done by describing an infinite line that passes through the actual pick point and is parallel to the users line of sight. In a perspective view, or a view with one clipping plane active, the line becomes a ray. If front and back clipping planes are on, the line becomes a line segment.
To describe the line/ray/line-segment, a type descriptor, a point, and either a unit vector describing the direction of the infinite-line/ray or a vector describing the direction and distance to the other side of the line segment are used.
The data items for a complete entity sublist involving a pick point selection are:
| RTLB | start of entity data sublist |
| RTSHORT | selection method |
| RTENAME | picked entity's entity name |
| RTSHORT | GS marker |
| RTLB | start of list for pick point |
| RTSHORT | point descriptor |
| RT3DPOINT | point on pick line (in WCS) |
| RT3DPOINT | vector describing direction of pick line or direction & distance to other end of line segment (only present if viewpoint is not plan WCS) |
| RTLE | end of list for pick point |
| RT3DPOINT | first of four points that provide a transformation matrix in the same format (and for the same purpose) as provided by acedNEntSel() (only present if :N option of acedSSGet() was used during selection) |
| RT3DPOINT | second of four points that provide a transformation matrix in the same format (and for the same purpose) as provided by acedNEntSel() (only present if :N option of acedSSGet() was used during selection) |
| RT3DPOINT | third of four points that provide a transformation matrix in the same format (and for the same purpose) as provided by acedNEntSel() (only present if :N option of acedSSGet() was used during selection) |
| RT3DPOINT | last of four points that provide a transformation matrix in the same format (and for the same purpose) as provided by acedNEntSel() (only present if :N option of acedSSGet() was used during selection) |
| RTENAME | entity name of innermost nested container of the selected entity (only present if :N option of acedSSGet() was used during selection) |
| entity names of other nested containers in innermost to outermost order (only present if :N option of acedSSGet() was used during selection) | |
| RTENAME | entity name of outermost nested container (in other words, the one in Model Space or Paper Space) of the selected entity (only present if :N option of acedSSGet() was used during selection) |
| RTLE | end of entity data sublist |
The point descriptor will be one of the following:
| 0 | an infinite line |
| 1 | a ray |
| 2 | a line segment |
If the current view is a WCS plan view with no perspective mode and no active clipping planes, then the point value will be the actual pick point and there will be no vector data item since it's the default of (0,0,1). Otherwise, the point value will almost never be the actual pick point and there will be a vector data item in the list, for example:
RTLB RTSHORT : 1 RTENAME : <Entity name: 1d20608> RTSHORT : 4 RTLB RTSHORT : 1 RT3DPOINT : 28.596, -23.096, 13.465 RT3DPOINT : -0.554, 0.752, -0.357 RTLE RTLE
This entity was selected using a pick point, the edge selected had a GS marker of 4, a ray type point was used, a point on the ray was (28.596, -23.096, 13.465), and the unit vector describing the direction of the ray is (-0.554, 0.752, -0.357). Notice the nested RTLB/RTLE pairs bracketing the complete entity information list and the point sub-list.
Fence Selection
For fence selection the selection point is the intersection of the fence with the entity being selected. The fence point data list is the same as for a standard pick point, however, there will be a point data sublist for each intersection between the fence and visible edges of the entity.
| RTLB | start of entity data sublist |
| RTSHORT | selection method |
| RTENAME | picked entity's entity name |
| RTENAME | GS marker |
| RTLB | start of first fence intersection point data sublist |
| RTSHORT | point description |
| RT3DPOINT | point on intersection "line" (in WCS) |
| RT3DPOINT | vector describing direction of intersection "line" or direction & distance to other end of line segment (only present if viewpoint is not plan WCS) |
| RTLE | end of first fence intersection point data sublist |
| RTLB | start of second fence intersection point data sublist |
| RTSHORT | point description |
| RT3DPOINT | point on fence intersection "line" (in WCS) |
| RT3DPOINT | vector describing direction of fence intersection "line" or direction & distance to other end of line segment (only present if viewpoint is not plan WCS) |
| RTLE | end of second fence intersection point data sublist |
| RTLE | end of entity data sublist |
Subentity Selection
This selection method is set when an entity appears in the selection set due to subentity selections on the entity. In this case, the format of the remaining result buffers in the chain will be the same as the format for non-graphical selections.
Crossing/Window/Polygon Selection
For crossing, window, crossing polygon, and window polygon selections, a window ID value is provided in the entity data sublist in order to identify which crossing/window/polygon was used to select the entity. This same window ID is also provided within the data list for the window/crossing/polygon. By matching up these IDs, the application can determine all the information about how the entity was selected.
Window IDs start with -1 sequentially decrease (in other words, -1, -2, -3, and so on). Each individual crossing/window/polygon used during the selection process will get its own window ID.
| RTLB | start of entity data sublist |
| RTSHORT | selection method |
| RTENAME | picked entity's entity name |
| RTSHORT | GS marker |
| RTSHORT | polygon/window ID |
| RTLE | end of entity data sublist |
An example of an entity data list for a crossing selection is:
RTLB RTSHORT : 3 RTENAME : <Entity name: 2ac0548> RTSHORT : 0 RTSHORT : -1 RTLE
Crossing/Window/Polygon Data
After all of the entity data sublists, the crossing/window/polygon data sublists will be provided (if there are any). Windows for crossing and window selection are treated as four vertex polygons. Each polygon sublist consists of the window ID followed by a collection of point sublists, one for each vertex point in the polygon. Each point sublist is in the same format as the point sublists described for pick point selection:
| RTLB | start of polygon data sublist |
| RTSHORT | polygon window ID |
| RTLB | start of first vertex point data sublist |
| RTSHORT | point description |
| RT3DPOINT | point on vertex "line" (in WCS) |
| RT3DPOINT | vector describing direction of vertex "line" or direction & distance to other end of line segment (only present if viewpoint is not plan WCS) |
| RTLE | end of first vertex point data sublist |
| RTLB | start of second vertex point data sublist |
| RTSHORT | point description |
| RT3DPOINT | point on vertex "line" (in WCS) |
| RT3DPOINT | vector describing direction of vertex "line" or direction & distance to other end of line segment (only present if viewpoint is not plan WCS) |
| RTLE | end of second vertex point data sublist |
| RTLE | end of polygon data sublist |
An example of a crossing window data list is:
RTLB RTSHORT : -1 RTLB RTSHORT : 0 RT3DPOINT : 0.000, 4.000, 0.000 RTLE RTLB RTSHORT : 0 RT3DPOINT : 5.000, 4.000, 0.000 RTLE RTLB RTSHORT : 0 RT3DPOINT : 5.000, 3.000, 0.000 RTLE RTLB RTSHORT : 0 RT3DPOINT : 0.000, 3.000, 0.000 RTLE RTLE
Notice that in this example the point data sublists do not have a vector data item. This indicates that this selection was done with the viewpoint set to plan WCS with no perspective mode and no active clipping planes.
Here's an example of a complete data list as returned from this function. This data list includes entities selected by several different polygons as well as pick point selection. In this example the viewpoint was not plan WCS.
RTLB RTSHORT : 3 RTENAME : <Entity name: 1d205e8> RTSHORT : 0 RTSHORT : -1 RTLE RTLB RTSHORT : 3 RTENAME : <Entity name: 1d20540> RTSHORT : 0 RTSHORT : -1 RTLE RTLB RTSHORT : 3 RTENAME : <Entity name: 1d205f0> RTSHORT : 0 RTSHORT : -2 RTLE RTLB RTSHORT : 1 RTENAME : <Entity name: 1d20608> RTSHORT : 2 RTLB RTSHORT : 0 RT3DPOINT : 5.307, 6.622, 1.631 RT3DPOINT : -0.667, 0.667, -0.333 RTLE RTLE RTLB RTSHORT : 2 RTENAME : <Entity name: 1d20600> RTSHORT : -1 RTSHORT : -3 RTLE RTLB RTSHORT : -3 RTLB RTSHORT : 0 RT3DPOINT : -5.095, -2.608, 3.974 RT3DPOINT : -0.667, 0.667, -0.333 RTLE RTLB RTSHORT : 0 RT3DPOINT : -0.660, 1.827, 3.974 RT3DPOINT : -0.667, 0.667, -0.333 RTLE RTLB RTSHORT : 0 RT3DPOINT : 0.837, 0.330, -2.013 RT3DPOINT : -0.667, 0.667, -0.333 RTLE RTLB RTSHORT : 0 RT3DPOINT : -3.598, -4.105, -2.013 RT3DPOINT : -0.667, 0.667, -0.333 RTLE RTLE RTLB RTSHORT : -2 RTLB RTSHORT : 0 RT3DPOINT : 4.588, 6.242, 2.308 RT3DPOINT : -0.667, 0.667, -0.333 RTLE RTLB RTSHORT : 0 RT3DPOINT : 0.987, 2.560, 2.145 RT3DPOINT : -0.667, 0.667, -0.333 RTLE RTLB RTSHORT : 0 RT3DPOINT : 0.696, 2.892, 3.391 RT3DPOINT : -0.667, 0.667, -0.333 RTLE RTLB RTSHORT : 0 RT3DPOINT : 4.100, 6.242, 3.283 RT3DPOINT : -0.667, 0.667, -0.333 RTLE RTLE RTLB RTSHORT : -1 RTLB RTSHORT : 0 RT3DPOINT : 0.302, 0.682, -0.239 RT3DPOINT : -0.667, 0.667, -0.333 RTLE RTLB RTSHORT : 0 RT3DPOINT : 2.173, 2.025, -1.295 RT3DPOINT : -0.667, 0.667, -0.333 RTLE RTLB RTSHORT : 0 RT3DPOINT : 3.407, 3.598, -0.618 RT3DPOINT : -0.667, 0.667, -0.333 RTLE RTLB RTSHORT : 0 RT3DPOINT : 1.034, 1.659, 0.249 RT3DPOINT : -0.667, 0.667, -0.333 RTLE RTLE
Parameters
| Parameters | Description |
|---|---|
| rbpp | Points to the resulting linked list of result buffers that contain information about the specified element(s) in the selection set |
| ss | Name of the selection set |
| i | Zero-based index position of the element for which information is requested or -1 to obtain information about all the elements in the selections set |
Previous Declaration
int acedSSNameX(
struct resbuf ** rbpp,
const ads_name ss,
const AdInt32 i
);