Entity Name Functions

To operate on an entity, an ObjectARX application must obtain its name for use in subsequent calls to the entity data functions or the selection set functions. The functions acedEntSel(), acedNEntSelP(), and acedNEntSel() return not only the entity's name but additional information for the application's use. The entsel functions require AutoCAD users (or the application) to select an entity by specifying a point on the graphics screen; all the other entity name functions can retrieve an entity even if it is not visible on the screen or is on a frozen layer. Like the acedGetxxx() functions, you can have acedEntSel(), acedNEntSelP(), and acedNEntSel() return a keyword instead of a point by preceding them with a call to acedInitGet().

If a call to acedEntSel(), acedNEntSelP(), or acedNEntSel() returns RTERROR, and you want to know whether the user specified a point that had no entity or whether the user pressed RETURN, you can inspect the value of the ERRNO system variable. If the user specified an empty point, ERRNO equals 7 (OL_ENTSELPICK). If the user pressed RETURN, ERRNO equals 52 (OL_ENTSELNULL). (You can use the symbolic names if your program includes the header file ol_errno.h.)

Note: You should inspect ERRNO immediately after acedEntSel(), acedNEntSelP(), or acedNEntSel() returns. A subsequent ObjectARX call can change the value of ERRNO.

The acdbEntNext() function retrieves entity names sequentially. If its first argument is NULL, it returns the name of the first entity in the drawing database; if its first argument is the name of an entity in the current drawing, it returns the name of the succeeding entity.

The following sample code fragment illustrates how acedSSAdd() can be used in conjunction with acdbEntNext() to create selection sets and to add members to an existing set.

ads_name ss, e1, e2; 
// Set e1 to the name of first entity.
if (acdbEntNext(NULL, e1) != RTNORM) { 
    acdbFail("No entities in drawing\n"); 
    return BAD; 
} 
// Set ss to a null selection set.
acedSSAdd(NULL, NULL, ss); 
// Return the selection set ss with entity name e1 added.
if (acedSSAdd(e1, ss, ss) != RTNORM) { 
    acdbFail("Unable to add entity to selection set\n"); 
    return BAD; 
} 
// Get the entity following e1.
if (acdbEntNext(e1, e2) != RTNORM) { 
    acdbFail("Not enough entities in drawing\n"); 
    return BAD; 
} 
// Add e2 to selection set ss  
if (acedSSAdd(e2, ss, ss) != RTNORM) { 
    acdbFail("Unable to add entity to selection set\n"); 
    return BAD; 
} 

The following sample code fragment uses acdbEntNext() to “walk” through the database, one entity at a time.

ads_name ent0, ent1; 
struct resbuf *entdata; 
if (acdbEntNext(NULL, ent0) != RTNORM) { 
    acdbFail("Drawing is empty\n"); 
    return BAD; 
} 
do { 
// Get entity's definition data.
    entdata = acdbEntGet(ent0); 
    if (entdata == NULL) { 
        acdbFail("Failed to get entity\n"); 
        return BAD; 
    } 
        . 
        . // Process new entity.
        . 
    if (acedUsrBrk() == TRUE) { 
        acdbFail("User break\n"); 
        return BAD; 
    } 
    acutRelRb(entdata); // Release the list.
    ads_name_set(ent0, ent1); // Bump the name.
} while (acdbEntNext(ent1, ent0) == RTNORM); 

Note: You can also go through the database by “bumping” a single variable in the acdbEntNext() call (such as acdbEntNext(ent0, ent0)), but if you do, the value of the variable is no longer defined once the loop ends.

The acdbEntLast() function retrieves the name of the last entity in the database. The last entity is the most recently created main entity, so acdbEntLast() can be called to obtain the name of an entity that has just been created by means of a call to acedCommandS()/acedCommandC(), acedCmdS()/acedCmdC(), or acdbEntMake().

The acedEntSel() function prompts the AutoCAD user to select an entity by specifying a point on the graphics screen; acedEntSel() returns both the entity name and the value of the specified point. Some entity operations require knowledge of the point by which the entity was selected. Examples from the set of existing AutoCAD commands include BREAK, TRIM, EXTEND, and OSNAP.