Harry's Code Class: Tips for Programmers (May 2007)

Write Routines to Create Entity Objects

Use one of several options available to AutoCAD programmers,
then sit back and watch the magic.

A common task performed by AutoCAD applications is to create entity objects in drawings -- for example, a line or an arc. In many cases, entity creation is the purpose of an application. All automated drawing processes revolve around the ability of a program to create entity objects. That is where the magic lies: Push a few buttons, answer a few questions and presto, the drawing creates itself. As such, AutoCAD programmers have a variety of choices regarding how to create entity objects in a drawing. This month we will explore those options and when to use them. Along the way, I'll share a few tricks to make the work easier.

Using Commands
AutoCAD operators know the AutoCAD commands. This makes the command approach to creating entity objects the easiest to understand and use. When AutoLISP first appeared, the command approach was the only way to create new objects inside the drawing from a program. You will find this approach works well for most purposes and allows for very simple program design. To create a program based on command sequences, start by simply running the commands and keeping a list of the commands used and the responses given.

An easy way to record this information is to turn on the Command line in AutoCAD then, when you have finished the sequence of commands, press F2 to display the Command Text screen. With the commands now visible, highlight them and right-click the mouse to display an Edit menu. Click the Copy option to copy the highlighted text into the clipboard. Now you can Paste that command sequence directly into an open Text Editor window, such as the one found in VLIDE (Visual LISP for AutoCAD Developer Environment) or VBAIDE (Visual BASIC Integrated Developer Environment) programs. Add comments to the text you just pasted in and begin using the file as a template for the command-driven program sequence. Now you can add the front part of the program, where you ask the operator to enter the variable parts to supply in the commands.

Some commands in AutoCAD bring up dialog boxes, and those cannot be used from inside one of our programs. When the dialog box appears, our programs will stop and wait for the operator to respond to the dialog box. At the completion of a command dialog box, we may not know what was input or how it ended. If the operator selects Cancel or an option that would normally take the operator to the graphics screen for a selection, things can really get messed up. To avoid the dialog boxes, type a hyphen at the start of the command name. The most commonly encountered example of this issue is the Layer command. Typing Layer at the Command line will display a dialog box. Typing -Layer will present a set of Command line options that are perfect for driving with a Command function.

Entity Lists
So why not just do everything with command functions? The answer is that when you are programming, you are not driving AutoCAD with just commands. Programming often requires much more functionality. And there are times when you want to do things such as add a series of entity objects with different properties. The command stream can quickly get rather long. To assist in that regard and provide an avenue to even more advanced programming, an early version of AutoLISP introduced the entity list.

An entity list is a nested list that contains all the basic details needed for an AutoCAD entity object. Basic details include things such as points, scalars and common properties such as layer and color. Entity lists are of interest only to Visual LISP programmers; VBA programmers have another option -- see Create by Adding an Object, below.

Entity lists are built on a rather simple structure. Each entity list consists of lists, and each of those lists starts with an integer. The integer is a code indicating exactly what follows. The code numbers correspond with those found in the DXF definition of AutoCAD. In Visual LISP these code numbers are called group codes. Certain group codes will become increasingly familiar to you. For example, you'll find that the group code 8 is the layer name and group code 10 is a primary point.

When you use the ENTGET function in Visual LISP, you get an entity list from AutoCAD that contains many group codes and data elements. Your program can then change the values of the data elements and update the drawing with the ENTMOD function. Or you can create a new entity object from the list data using ENTMAKE.

In most cases you will need a prototype entity list of the objects you want to create. The fastest way to get one is to use the AutoCAD command line again. This time draw an example entity of interest. Then use the expression (ENTGET (ENTLAST)) at the Command line of AutoCAD. Press F2 to view an entity data list of the object you just created. Copy that entity data list by highlighting it, then right-click and Copy. Now you can insert it into a text code window inside VLIDE for use in your programming efforts. Of course you will need to trim some of the data to match what you need -- specifically, remove all -1, 5 and 300+ group codes, which are entity references -- but most of the data list is all set.

Entity data lists are easy to manipulate using functions such as ASSOC and CDR. Numerous examples exist that show how you can extract the data using the combination (CDR (ASSOC group-code entity-list)) in your programs. But how do you replace a value? The easy way is found in Visual LISP with the SUBST function. To use the SUBST function, build a new list consisting of a group code and data to be substituted for an existing group code that can be found with the ASSOC function.

How to Get a Prototype Entity List
To produce a prototype entity list, draw a line on the screen, then type (SETQ EL (ENTGET (ENTLAST))) at the Command prompt. Press F2 to bring up the text screen. You should see an entity list.

Capturing an entity list in an AutoCAD drawing.

To change the layer name to New, use the following expression:

(setq EL (subst (cons 8 "NEW") (assoc 8 EL) EL))

The SUBST function has three parameters. The first is the new value. The second is the existing value and the third is the list to search. SUBST works fine with lists as well as just data but for entity data lists we need to maintain the group codes. The expression (CONS 8 "NEW") builds a dotted pair list of the type used in the entity data lists for substitution with the existing group code.

Look closer at the figure above and note the (8 . "0") in the entity data list. The dot is not a mistake; it is what denotes the list as a special type of list known as a dotted pair. Dotted pairs were introduced in the earliest appearance of entity data lists in AutoLISP as a way to conserve the operating memory for AutoLISP. Memory is much more extensive today, but a long legacy of programs has maintained the dotted pair as the way entity data lists are presented.

When creating new entity objects using an entity data list, you do not need all the data that you see in the example shown. The group codes -1, 5 and 330 are not needed when creating a new entity data list, but the others found in the LINE entity data list will be needed for proper set-up. Once you have a new entity data list, simply send it to AutoCAD using (ENTMAKE). The result of ENTMAKE will be the completed entity data list with entity names if all is OK. Otherwise, the result of ENTMAKE will be nil, indicating that something is wrong with the entity data list.

ENTMAKE is substantially faster than COMMAND streams when creating many entities. It also provides a higher degree of control over how the entities will be created and bypasses any anomalies that could result from system variable settings by AutoCAD operators. For example, if you don't clear the Snap mode, your command stream functions will honor them while ENTMAKE-based routines will do as you instructed.

Create by Adding an Object
A third method for creating entity objects is to add them using the object system. AutoCAD is an exposed-object system, meaning that programmers can reference libraries containing the methods and properties of the AutoCAD object model. An object model is simply a way of perceiving another program and communicating with the elements that make up the other program. When a program is "exposed," it has published a set of objects that can be used by other applications.

The object model is also available inside AutoCAD's programming options of Visual LISP, ObjectARX and VBA, albeit in different flavors and with in the constraints of the host languages. The basic structure of the AutoCAD object model is entered through the application object. From there you can work with open drawings and control the AutoCAD program in general. For the purposes of our discussion we need to drill into the AutoCAD application object to an open drawing and then a specific space in the drawing to begin adding new entity objects.

In this context, the term space refers to things such as the drawing's model space or various layout spaces (paper space). It can also refer to block definitions, making the object model approach of creating entity objects the only option to directly add entity objects to existing block definitions.

Working with the objects in AutoCAD programming is very easy. Objects have properties and methods associated with them that accomplish most of the tasks you might have in mind. Properties are the basic elements that define the object, while the methods are functions you can run that are related to the object.

Which Way is Best?
All of them! There's a reason AutoCAD programmers have a variety of choices when it comes to creating new entities in a drawing: Simply put, each fits nicely with the methodology being employed. If you are thinking about automating a series of commands, then any entity creation that is part of that sequence will slide right in to the command sequence. When working with entity data and creating a variety of the same thing, entity lists or objects will make the most sense. Of course, the key is to make it work for you. The goal of this article was merely to inform you of the options for making your own magic.

Until next time, keep on programmin'!