When the entmask argument specifies a list of entity field values, acedSSGet() scans the selected entities and creates a selection set containing the names of all main entities that match the specified criteria. For example, using this mechanism, you can obtain a selection set that includes all entities of a given type, on a given layer, or of a given color.
You can use a filter in conjunction with any of the selection options. The “X” option says to create the selection set using only filtering; as in previous AutoCAD versions, if you use the “X” option, acedSSGet() scans the entire drawing database.
The entmask argument must be a result buffer list. Each buffer specifies a property to check and a value that constitutes a match; the buffer's restype field is a DXF group code that indicates the kind of property to look for, and its resval field specifies the value to match.
The following are some examples.
struct resbuf eb1, eb2, eb3;
char sbuf1[10], sbuf2[10]; // Buffers to hold strings
ads_name ssname1, ssname2;
eb1.restype = 0; // Entity name
strcpy(sbuf1, "CIRCLE");
eb1.resval.rstring = sbuf1;
eb1.rbnext = NULL; // No other properties
// Retrieve all circles.
acedSSGet("X", NULL, NULL, &eb1, ssname1);
eb2.restype = 8; // Layer name
strcpy(sbuf2, "FLOOR3");
eb2.resval.rstring = sbuf2;
eb2.rbnext = NULL; // No other properties
// Retrieve all entities on layer FLOOR3.
acedSSGet("X", NULL, NULL, &eb2, ssname2);
If entmask specifies more than one property, an entity is included in the selection set only if it matches all specified conditions, as shown in the following example:
eb3.restype = 62; // Entity color
eb3.resval.rint = 1; // Request red entities.
eb3.rbnext = NULL; // Last property in list
eb1.rbnext = &eb2; // Add the two properties
eb2.rbnext = &eb3; // to form a list.
// Retrieve all red circles on layer FLOOR3.
acedSSGet("X", NULL, NULL, &eb1, ssname1);
An entity is tested against all fields specified in the filtering list unless the list contains relational or conditional operators, as described in Relational Tests and Conditional Filtering.
The acedSSGet() function returns RTERROR if no entities in the database match the specified filtering criteria.
The previous acedSSGet() examples use the “X” option, which scans the entire drawing database. If filter lists are used in conjunction with the other options (user selection, a window, and so forth), the filter is applied only to the entities initially selected.
The following is an example of the filtering of user-selected entities.
eb1.restype = 0; // Entity type group strcpy(sbuf1, "TEXT"); eb1.resval.rstring = sbuf1; // Entity type is text. eb1.rbnext = NULL; // Ask the user to generally select entities, but include // only text entities in the selection set returned. acedSSGet(NULL, NULL, NULL, &eb1, ssname1);
The next example demonstrates the filtering of the previous selection set.
eb1.restype = 0; // Entity type group
strcpy(sbuf1, "LINE");
eb1.resval.rstring = sbuf1; // Entity type is line.
eb1.rbnext = NULL;
// Select all the lines in the previously created selection set.
acedSSGet("P", NULL, NULL, &eb1, ssname1);
The final example shows the filtering of entities within a selection window.
eb1.restype = 8; // Layer
strcpy(sbuf1, "FLOOR9");
eb1.resval.rstring = sbuf1; // Layer name
eb1.rbnext = NULL;
// Select all the entities within the window that are also
// on the layer FLOOR9.
acedSSGet("W", pt1, pt2, &eb1, ssname1);