Assigning Extended Entity Data to an AutoCAD Object.

Once the application name for the extended entity has been registered in the applications identification table, extended data may now be assigned to an AutoCAD object. This is usually accomplished by appending the extended data to the object definition data using one of the many list functions provided in AutoLISP. Then the entity data is updated in the AutoCAD drawing database using ENTMOD function and assigned the extended information. Before extended data can be appended to an existing entity, it must be contained within an association list that starts with the code –3 and is followed by the name of the application with which the data is associated. Extended data can only be assigned to existing AutoCAD objects. The entity must either already exist or be created before the extended data can be assigned. An object can be assigned multiple application names and extended entity data. The following program illustrates how extended data can be assigned to an AutoCAD object.

 

(DEFUN c:extended_entity_data ()

(SETQ select_entity (ENTGET (CAR (ENTSEL))))

; Gets the association list of

; definition data for the entity

; selected.

(REGAPP "EXAMPLE_1_EXTENDED_DATA"); Registers the application name

; EXAMPLE_1_EXTENDED_DATA

(SETQ    extend_data            ; Sets the variable extend_data

; equal

         '((-3

             ("EXAMPLE_1_EXTENDED_DATA"

                        ; to the new extended data, which

; is a text string and two

; scaleable values 1041 and

; 1042.

             (1000 . "Imagine what can be saved to extended entity data")

             (1041 . 4.5)

             (1042 . 10.0)

             )

             )            ; End of association list

            )            ; End of QUOTE function

    new_entity_def

         (APPEND select_entity extend_data)

)

                        ; Appends the extended entity data

; to the object definition data.

(ENTMOD new_entity_def)        ; Updates the entity defination in

; the AutoCAD database with the new

; definition data containing the

; extended entity data.

)

Registering an Application Name

Before AutoCAD will allow a developer to set extended entity data to an AutoCAD object, the application name in must first be registered in AutoCAD application identification or appid table. This table is used by AutoCAD to store the names of all the applications that have been registered in an AutoCAD drawing. To add an application name to the appid table, the REGAPP function (REGAPP application) must be used. This function, when supplied with the name of the application, first checks the appid table to determine if the application name is already in use. If the application name is not used then the function adds the name to the table and returns the name that was added. If the application name already exists, then the function returns nil. The nil in this particular case only means that the application name is already registered. This is illustrated in the following examples in which the application name "Visual_LISP" is registered.

Command: (REGAPP "Visual_LISP")

"VISUAL_LISP"

Command: (REGAPP "Visual_VLISP")

nil

Command:

In the first example the application name VISUAL_LISP is added to the appid table. In the second example the REGAPP function returns nil because the application name already exists in the appid table. Also notice in the first example that the application name returned by the REGAPP function is displayed as all upper case letters. When a name is supplied to the REGAPP function, all letters contained in that name are converted to upper case and are stored in the appid table as such. Application names are limited to 31 characters in length and can be made up of letters, numbers or a combination of the two. They can even contain special characters such as dollar signs ($), hyphens (-), and underscores (_), but they can not contain less-than and greater-than (<>), forward slash and backslash (/\), quotation marks ("), Question marks (?), colon (:), asterisks (*), vertical bars (|), commas (,), equal signs (=), backquotes (`) and semi-colon (;). Examples of valid and invalid application names are provided below.

Valid Application Names                Invalid Applications Names

VISUAL_LISP                    VISUAL*LISP

VISUAL_1_LISP                    VISUAL<>1_LISP

VISUAL$LISP                    VISUAL?LISP

$VISUAL_LISP                    VISUAL:LISP

$1$VISUAL_LISP                    VISUAL`LISP

$1-VISUAL_LISP                    VISUAL=LISP

Although the REGAPP function takes some precautions to ensure that an overlap of application names does not occur, there is a possibility that an overlap can happen. To guarantee that this does not occur, the AutoLISP TLBSEARCH function (TBLSEARCH table-name symbol [setnext]) can be used. This function, when supplied with the name of the table to search along with the symbol name to check for, returns either nil if the symbol is not present or an association list containing the symbol's name and table if the symbol exists. To check the application identification table to determine if the application VISUAL_1$_LISP-EXAMPLE has been registered, and if not register it, the following syntax would be used.

Attaching Extended Entity Data to an AutoCAD Object

Extended entity data is attached to an object's definition data using the DXF codes 1000 – 1071. Because of the limited range of these DXF codes and the fact that xdata can be set by any application, Autodesk has devised a method to keep this information is unique to a particular program. This reduces the possibility of information stored by one program affecting the data or even the operations of other applications. AutoCAD requires that all extended entity data be assigned an application name. That application name may only be used once in a drawing. This helps ensure that information assigned by more than one program to the same AutoCAD entity is unique as long as the application names used by these programs are different.

Using Extended Entity Data

Extended entity data is really nothing more than an extension of the objects regular entity data. By using the procedures and techniques previously discussed for handling and manipulating the association list of an AutoCAD entity along with a few specifically designed Xdata functions, extended entity data can be assigned, retrieved, modified, and even saved to an object with very little effort. Once the information has been saved to an object's definition, then it may be recalled at a later time, long after the initial drawing session has been terminated. This information remains attached to the entity until the information is either removed using a process similar to the way it was attached, or the entity is erased from the drawing. Extended entity data does have one major limitation; the amount of information that can be attached to an entity is limited to 16K bytes.

Introduction to Extended Entity Data

Chapters Three and Four introduced list manipulation and processing which is the true power of AutoLISP programming. Even though these capabilities have greatly extended the potential of AutoLISP programming, one down fall still exists concerning non-AutoCAD entity information. Unless the information is either assigned to an AutoCAD attribute or saved in an external file, the program is unable to recall any of the information once the current drawing session has been terminated. This limits the applications where these theories can be used. For example, if the resistance program illustrated in Chapter Four used attributes contained within blocks to store information concerning the resistance and voltage drop for each resistor, then extreme care would have to be taken to insure that these blocks are not exploded. If one or more of the blocks were exploded, then this would result in the program ignoring the values that were assigned to those entities thereby increasing the voltage drop for the remaining resistors. If this were to happen and the situation were to go unnoticed, then the results obtained from running the program would produce a situation in which the actual circuit could fail. Therefore the programmer is forced to rely on constructing a program that would either prevent the user from exploding the attributed blocks or one that warns the user of the potential danger involved if this process is continued. On the other hand if the program had saved the information to an external file, then a similar situation could result if the file were deleted. AutoLISP provides two possible solutions to this problem. They are Extended Entity Data (or Xdata as it is sometimes referred to) and Xrecord. While both methods are similar in concept and application each method has its advantages and disadvantages. The programmer should be well versed in the use of both of these methods. The intent of these methods is to provide the programmer with a means of storing and managing information in an object's association list using DXF codes. Attached information can be relevant or non-relevant to the particular entity.

Introduction to List and List Processing

One of the many attributes that makes Common LISP an excellent candidate for artificial intelligence and the perfect model for AutoLISP is its ability to store large amounts of data in the form of a list. A list is nothing more than a collection of data that is either related or non-related to a particular entity or event. For example, a list describing the characteristics of a line could include the Entity Name, Entity Type, Entity Handle, Entity Color, Layer, Starting Point, and Ending Point. A list can also consist of a set of instructions or commands describing a particular sequence of events. For example, a list containing the steps for determining the area of a circle given only its diameter would be:

1. Calculate the radius of the circle by dividing its diameter by two.
   
2. Square the radius and multiplying the result by 3.14, (producing the area of the circle).
   

In most cases, lists provide an efficient as well as practical way of storing information over the traditional method of using variables (variables are only able to store a single item known as an atom). This is especially true if the information used by a program varies from execution to execution. For example, to write a program that would find the equivalent resistance of a series circuit and calculate the voltage drop for each resistor at first seems like an easy task to accomplish. First, add up the resistance of all the resistors in the circuit to find the equivalent resistance. Next, divide the total voltage supplied to the circuit by the equivalent resistance, producing the current supplied to the circuit. Finally, the voltage drop for each resistor can be found by multiplying the current by the resistance of the individual resistor. However, there is one small problem, the number of resistors could vary from circuit to circuit making it extremely difficult if not impossible to create a generic program using variables. An alternative is to construct a list containing values assigned to each resistor and then setting that list equal to a single variable. Not only does this solve the problem of the variant amount of information entered into the program, but also reduces the number variables used in the program and the amount of code required to create the program. A list can also contain other lists (this is often referred to as a sub-list). Each entry in a list is referred to as an Element. For example, the list (apple orange peach) contains the elements apple, orange and peach. In AutoLISP a list will always start with an opening parenthesis and end with a closing parenthesis.

Lists in AutoCAD

When information is requested from AutoCAD, that information is returned in the form of a list. This can be illustrated using the GETPOINT function. Recall from Chapter Two that the GETPOINT function prompts the user to either select or enter a point. The result returned by this function is in the form of a list (7.4366 6.16185 3.80986) regardless of whether or not the user entered the information from the keyboard or selected a point from the graphics screen.