The History of Entity References in AutoCAD Programming
Bill Kramer
In the earliest days of AutoLISP, there existed only the (GETPOINT) and (OSNAP) subrs for accessing entity objects in a round about way. A program would ask the user to select a point, then use the object snap function to try and isolate what kind of entity the point was near. If an object had a center-point and a mid-point, then it was an arc. Should the center point exist, but no mid point then it was a circle. A mid-point with no center-point had to be a line. Get it yet? Not only was the approach a hassle, but it was an error prone and didn’t provide any way to get at text and other objects. This situation existed for some time before a better way was introduced, the Entity Name and associated data list.
Then the entity names and entity data lists were introduced, along with selection sets. These were fantastic tools and opened a new generation of development opportunity. Albeit they were cryptic at first glance and did require some experience before they became second nature. The entity name, which is still very much in active use today, was introduced as a new data type. When displayed it was a hexadecimal number such as <Entity name: A00123>. So long as an application worked in the current drawing session only, it was great. An entity name would lead to an entity data list containing all the parameters required to generate the object. And programs could change these values resulting in new or modified entities.
The only negative was that if you wanted to access the same entity in a later edit session, the entity name was not valid and there was no way to preserve it. Although the value could be printed to a file using a subr like (PRINT) it was not the same when read back in. Entity name values changed in a drawing from one edit session to the next. They were only valid in the current drawing session. Of course, given an inch we want a mile! We wanted to save selection sets and entity picks.
Once again, AutoLISP programmers had to be clever to accomplish the task of making the miracles our users expected. By saving the number count or offset of how many entities into a drawing of an entity, we could retrieve the same object again. That is, if a line was the third object in the drawing we saved the number three and then later read three objects using (ENTNEXT). So long as the function was the first command run during the later edit session, we were able to reconstruct entity selections and sets. A shaky solution at best, but it worked while we waited for something better from Autodesk.
And then came entity handles. Entity handles are strings saved with each entity. Best yet, they stay the same from one drawing session to the next. If written to a file or database, the same name will be found in the drawing at a later time. The subr (HANDENT) was provided to search the drawing for us and return the entity name [which leads directly to the entity list]. This simple addition to AutoLISP opened the door for advanced databases to be linked into drawings through clever programming. That is, there were still some problems - AutoLISP did not support databases and users demanded more miracles. But compared with where we were when AutoLISP first appeared, quantum leaps of progress had occurred!
So let us review the situation. Using subrs like (ENTSEL) one can get entity names. Using the entity name the subr (ENTGET) will retrieve the entity data list. The entity data list contains all the details about an entity such as the entity type, data points, parameters, layers, colors, and so forth. It also contains the entity handle. Using (CDR) and (ASSOC) with the number five as the association key, the entity handle string can be extracted. This string can then be written to a file or a database. When read back, the (HANDENT) subr can be used to retrieve the entity name of the exact same entity.
From a programming point of view, entity names go away at the end of a drawing session while entity handles are preserved. Handles allow entities to reference each other internally in a fashion that we can control directly. If you intend to link entity objects with outside databases then you use handles. They are persistent in the sense that they never change.
And now there are objects. Now this gets muddled a bit as we switch gears and talk about VBA or Visual LISP applications involving objects. In VBA, entities are manipulated as objects. In Visual LISP, entities can be manipulated as either objects or entity names.
The properties and methods of the object are used to reference the details that comprise the entity object. Most of the properties are pretty obvious as to what they reference. The end points of a line object, the center point of an arc object and so forth. But you cannot store object references in a database directly. To link an entity object with a database you use the handle of the object. The handle is a property and can be retrieved from any object and saved in a string. That string can then be written to the database. Given a handle, the method HandleToObject will result in the object.
When working in VBA, the conversion of a handle to an object reference can be a tad confusing. When the object is retrieved you might not know what kind of object it is. This is resolved by simply returning the object reference to a generic entity object container as in the following code where the entity object referenced by the string variable "the_handle" is set into a generic AutoCAD object "Obj".
Dim Obj As AcadObject
Set Obj = ThisDrawing.HandleToObject(the_handle)
The next step might be to figure out what kind of object you have and move the data to another container of the specific type. You don’t always have to move the object to the more specific container, but it can make things easier (and slightly faster) as you access the methods and properties specific to that type of object. For example, the following code will check to see if an object is a line, and move it to a line object reference if so.
Dim Lobj as AcadLine
If Obj.ObjectName = "AcDbLine" then
Set Lobj = Obj
End if
The ObjectName property returns the class name of the object. Note that all of the objects in the AutoCAD database will start with the characters "AcDb". Thus an arc is "AcDbArc" and a circle is "AcDbCircle".
Another way to reference an object is to use the Object ID. For most applications in VBA you will not be using Object ID values. They are mostly used to talk to ObjectARX based applications. In ObjectARX we use Object ID values, and object references just like VBA. We can also use handles however it is always faster to have a direct address for the object and that is precisely what the Object ID provides. But the Object ID is not like the handle of an object. That is, it will change from one drawing edit session to the next like an entity name. So if you need to link to something outside AutoCAD and maintain that linkage for more than drawing session, then you must use handles.
The basic rules of entity access and what tool to use are as follows.
Entity Handle - Used for drawing edit session to edit session transfer
Entity Name - Used in Visual LISP to directly access entity data lists
Object Reference - Used in Visual LISP, VBA, or ObjectARX to access object properties or run methods.
Keep on programmin’