In this section, you look at developing a small routine, written in AutoLISP, that mimics ActiveX properties and methods. This will help you to compare how AutoLISP works compared to ActiveX.

To understand Visual LISP's ActiveX features, you need to know how AutoCAD exposes an object's properties in AutoLISP. The following examples work with a line that is 10 units long and that was created by using the following AutoLISP function:

;;; This function creates a line using the AutoLISP
;;; command function and returns nil.
(defun make-aLine ()
 (command "_line" "5,5" "15,5" "")
)

After loading it, you can use this function (that is, draw the line) by typing the following in the Visual LISP Console window:

(make-aLine)

As explained in Chapter 35, to retrieve the last object that was created (the line), you use ENTLAST, as shown in the following code fragment. The next expression assigns the value of the last created entity, as an entity name, to the variable LineEntity. To try this out, type the following code in the Console window:

(setq LineEntity (entlast))

Visual LISP responds with the entity name. As soon as you receive the entity name, you can use ENTGET to retrieve the object property list of the line. The following code fragment places the property list value in the variable LinePropertyList. If you type the following in the Console window and press Enter, Visual LISP responds with the property list:

(setq LinePropertyList (entget LineEntity))

Here is an example of a property list, which is formatted for readability:

((−1 . <Entity name: 1456d60>)
 (0 . "LINE")
 (330 . <Entity name: 1456cf8>)
 (5 . "2C")
 (100 . "AcDbEntity")
 (67 . 0)
 (410 . "Model")
 (8 . "0")
 (100 . "AcDbLine")
 (10 5.0 5.0 0.0)
 (11 15.0 5.0 0.0)
 (210 0.0 0.0 1.0))

As you can see, ENTGET returns an entity's properties as a collection of lists, all which have a distinctive number at their first position. Some of these group codes (also commonly known as DXF fields, because you can also find them in DXF files) were listed in Table 35.2 in Chapter 35. For this exercise, you just need to remember that the group 10 code is associated with the start point of a line.

Having the entity list and knowing which values to retrieve, you can use the AutoLISP function ASSOC, which returns an associated item from a property list.

To retrieve the start point of the line, you would use the following code, which you can type in the Console window:

(setq StartofLineList (assoc 10 LinePropertyList))

The Console returns the list that is associated with the group 10 code, including the group code and the coordinates:

(10 5.0 5.0 0.0)

Because the only value that you require is the start point of the line object, use the function CDR to remove the first element of the list, as shown in the following code.

(setq StartofLine (cdr (assoc 10 LinePropertyList)))

This code returns only the start point coordinate:

(5.0 5.0 0.0)

This review of how to retrieve a value from an AutoCAD object shows that retrieving information from an associated list is relatively straightforward. But how about retrieving more than one property at a time? As you can see from the preceding example, you'd have to repeat the same body of code many times over to retrieve any information. Knowing this, you could write a simple interface function, putting together all the steps that I have just explained, to retrieve any group code — not just the group 10 code — from an object.

An example of an interface function is shown in the following lines:

;;; Returns any group code value if it is present in the entity
;;; the required parameters are an entity name and a group code.
(defun Get-A-Group-Code (EntityName GroupCode)
  (cdr (assoc GroupCode (entget EntityName)))
)

After you create this function and load it, you can test it out in the Console window as follows, using the LineEntity variable that was previously defined:

(Get-A-Group-Code LineEntity 10) 

(5.0 5.0 0.0)

As you can see, the function returns only the value of the group 10 code.

You can refine this small interface by defining a separate group 10 code function, such as the following. The only required parameter is an entity name. The group code is included in the call to Get-A-Group-Code. You could do the same for a group 11 code, if you want.

(defun Get-Group-10-Code (anEntityName)
  (Get-A-Group-Code anEntityName 10)
)

After loading, test the function, as follows:

(Get-Group-10-Code LineEntity) 

Visual LISP returns the start point of the line:

(5.0 5.0 0.0)

These examples summarize how you would create a simple function to get the start point of a line by using AutoLISP. What if you need to change an object's property? You can do this by using the functions CONS, SUBST, and ENTMOD, which Chapter 35 covers.

CONS constructs a list. Use it when you want to create new values for a group code within an entity list, as in the following example, which you can type in the Console window:

(setq NewStartPoint (cons 10 '( 0.0 0.0 0.0 ))) 

Visual LISP returns the following:

(10 0.0 0.0 0.0)

Using the variables NewStartPoint and LinePropertyList, you can now substitute the newly created group 10 code. You do this by using the SUBST function. The following code substitutes the new group 10 code that is represented by the variable NewStartPoint for the 10 association in LinePropertyList in the list called LinePropertyList.

(Setq LinePropertyList
       (subst NewStartPoint (assoc 10 LinePropertyList)
  LinePropertyList)
  )

To test this out, type the preceding code in the Console window. To see the new start point, you need to scroll all the way to the right. The list (nicely formatted here) now has a new group 10 value (the start point), shown on the third-to-last line that follows:

((−1 . <Entity name: 1456d60>)
  (0 . "LINE")
  (330 . <Entity name: 1456cf8>)
  (5 . "2C")
  (100 . "AcDbEntity")
  (67 . 0)
  (410 . "Model")
  (8 . "0")
  (100 . "AcDbLine")
  (10 0.0 0.0 0.0)
  (11 15.0 5.0 0.0)
  (210 0.0 0.0 1.0))

To reflect the modification of this line in AutoCAD, you can now use the function ENTMOD by typing it in the Console window, as follows. This code actually changes the start point of the line. (You can return to AutoCAD to check it out.)

(entmod LinePropertyList) 

As you can see from this example, getting object properties and modifying them can be a tedious and time-consuming process. Here is an example of an interface function that modifies any group code that is contained in any object.

(defun put-group-code-value (Entityname Groupcode Value / PropertyList)
  (setq PropertyList (entget EntityName))
  (setq PropertyList
      (subst
        (cons GroupCode Value)
        (assoc GroupCode PropertyList)
        PropertyList
      )
  )
  (entmod PropertyList)
 )

This function combines all the preceding steps into one function. Here's how it works:

Using the preceding function, you now have a much simpler interface for modifying any group code. Next, you use the function Put-Group-Code-Value to modify the group 10 code of the line object.

After entering and loading the preceding function, you can test the function by typing the following in the Console window:

(Put-Group-Code-Value LineEntity 10 '(5.0 5.0 0.0))

This function changes the start point of the line to 5,5,0.

Using the same logic to write the GET functions, you can now define a separate group 10 code modifier function. You can do the same for any group code.

(defun Put-Group-10-Code (EntityName Value)
  (Put-Group-Code-Value EntityName 10 Value)
)

After entering and loading this function, type the following in the Console window to change the start point of the line to 15,−5,0.

(Put-Group-10-Code LineEntity '( 15.0 −5.0 0.0))

Activate AutoCAD to check that the line has been changed.

ActiveX enables you to retrieve and modify objects similar to the method used in the previous section of this chapter, but it requires some preparation. The following section explains how you can use ActiveX functions to create, retrieve, and modify an object.

Retrieving and modifying object information with ActiveX

Visual LISP enables you to retrieve and modify most AutoCAD objects by using AutoCAD's ActiveX interface. That is to say, AutoCAD exposes most of its objects to ActiveX-enabled applications. This includes Visual LISP as ActiveX objects, which expose their properties, including PUT (modify) and GET (retrieve) functions.

Using Visual LISP to communicate with AutoCAD is very straightforward. You must first load all the ActiveX functions, using the VL-LOAD-COM function within Visual LISP. You need to use the VL-LOAD-COM function only once each time that you open AutoCAD, because VL-LOAD-COM loads the ActiveX functions for the entire drawing session. (However, using VL-LOAD-COM more than once doesn't cause any harm.) To use the ActiveX interface, enter the following in the Visual LISP Console window:

(vl-load-com)

After the ActiveX interface is loaded, you can interrogate the line that you created previously, but first you need to convert the entity name into a vla-object. A vla-object is no different from an entity name, except that the ActiveX object exposes certain properties that its AutoLISP counterpart does not. To convert the entity name into a vla-object, you use the function VLAX-ENAME->VLA-OBJECT, as shown here:

(setq vla-line (vlax-ename->vla-object (entlast)))

Visual LISP returns the following (your object name will be different):

#<VLA-OBJECT IAcadLine 03612b14>

As you can see by the return value of vlax-ename->vla-object, the value of the variable vla-line contains a vla-object. At this point, you can visually inspect the variable by selecting it and choosing View

(vlax-dump-object vla-line)

This causes Visual LISP to display the following:

; IAcadLine: AutoCAD Line Interface
; Property values:
;   Angle (RO) = 1.5708
;   Application (RO) = #<VLA-OBJECT IAcadApplication 00af9594>
;   Delta (RO) = (0.0 10.0 0.0)
;   Document (RO) = #<VLA-OBJECT IAcadDocument 038be900>
;   EndPoint = (15.0 5.0 0.0)
;   Handle (RO) = "89"
;   HasExtensionDictionary (RO) = 0
;   Hyperlinks (RO) = #<VLA-OBJECT IAcadHyperlinks 01011d44>
;   Layer = "0"
;   Length (RO) = 10.0
;   Linetype = "ByLayer"
;   LinetypeScale = 1.0
;   Lineweight = −1
;   Material = "ByLayer"
;   Normal = (0.0 0.0 1.0)
;   ObjectID (RO) = 2130009736
;   ObjectName (RO) = "AcDbLine"
;   OwnerID (RO) = 2130009336
;   PlotStyleName = "ByLayer"
;   StartPoint = (15.0 −5.0 0.0)
;   Thickness = 0.0
;   TrueColor = #<VLA-OBJECT IAcadAcCmColor 01015170>
;   Visible = −1
T

Note

If you are using a 64-bit release of AutoCAD, the ObjectID and OwnerID properties are listed as ObjectID32 and OwnerID32.

You'll probably have to resize the window to see all these properties. Notice the similarities between the named properties shown here, such as EndPoint and StartPoint, and the line's group codes that you retrieved by using AutoLISP. As you can see, one of the advantages of using an ActiveX-enabled object is that ActiveX exposes more information to the programmer than standard AutoLISP does. One of the benefits of using ActiveX is its interface. Previously, you queried and modified a line object's start point and endpoint by using the group 10 and 11 codes. Using ActiveX to query the start point and endpoint is very straightforward. However, ActiveX returns these points in a data type called a variant that you need to convert to the familiar coordinate format.

To get the start point of an object, use the VLA-GET-STARTPOINT function. In the current example, the line has been set to vla-line, so you would type the following expression:

(setq Starting (vla-get-startpoint vla-line)) 

Visual LISP responds as follows:

#<variant 8197 ...>

To convert the start point from the variant data type to a usable coordinate format, you would type the following line:

(safearray-value (vlax-variant-value Starting))

Visual LISP responds with a coordinate:

(15.0 −5.0 0.0)

To modify the StartPoint property of a line to (0,0,0), you would use the following expression:

(vla-put-startpoint vla-line (vlax-3d-point '(0.0 0.0 0.0)))

You can return to AutoCAD to check out the line. To verify the new StartPoint, you can also use the VLA-GET-STARTPOINT function:

(safearray-value (vlax-variant-value (vla-get-StartPoint vla-line)))

Visual LISP returns the start point of the line:

(0.0 0.0 0.0)

As you can see, this is very similar to the small routine that was developed in AutoLISP earlier in this chapter.

STEPS: Retrieving and Modifying Objects with ActiveX

1. To start a new drawing session, open AutoCAD. If AutoCAD is already open, close and re-open it.

2. Start a new drawing by using the acad.dwt template.

3. Draw any line. Neither the start point nor the endpoint should be 0,0,0.

4. Open the Visual LISP editor.

5. In the Console window, type (vl-load-com)

   

6. To convert the entity name into a vla-object, type (setq vla-line (vlax-ename->vla-object (entlast)))

   

7. To view the line's properties, type (vlax-dump-object vla-line)

   

8. To get the start point of the line, type (setq Starting (vla-get-startpoint vla-line))

   

9. To convert the start point from the variant data type to coordinate format, type (safearray-value (vlax-variant-value Starting))

   

10. To change the line's start point to 0,0,0, type (vla-put-startpoint vla-line (vlax-3d-point '(0.0 0.0 0.0 )))

    

11. Choose Activate AutoCAD on the Visual LISP View toolbar to check out the line. Its start point is now 0,0,0.

Creating objects with ActiveX

This section looks at functions that create objects. When you work with ActiveX, you need to retrieve objects in their hierarchical order. This hierarchy concept is discussed in more detail in the next chapter. For this chapter, you need to know that before you can retrieve an object, you need to retrieve the following:

• Acad-object. Represents the AutoCAD application.

• ActiveDocument. Represents the current drawing.

• ModelSpace/PaperSpace. Represents the type of space that you want to use within the current drawing.

In AutoLISP, you first retrieve the AutoCAD application, then your drawing, and finally the space (model or paper). Here you take the simple line command used earlier in this chapter and convert it by using ActiveX:

;;; This function creates a line using Visual LISP
;;; ActiveX and returns the line object as a vla-object.
(defun ax-make-aLine ()
  (vla-AddLine
    (vla-get-ModelSpace            ; retrieve the model
                                   ; space object
      (vla-get-ActiveDocument      ; get the current
                                   ; active document
        (vlax-get-acad-object)     ; get the acad object
      )
    )
    (vlax-3d-point '(5 5 0))       ; starting point
    (vlax-3d-point '(15 5 0))      ; ending point
  )
)

You can type this code in the Visual LISP editor and load it. To try it out, type the following in the Console window:

(ax-make-aLine)

Visual LISP responds with the following:

#<VLA-OBJECT IAcadLine 03614934>

This might seem a little cumbersome — as if it might be a lot of work to create a line — but it's actually quite flexible.

To locate other ActiveX functions that create objects, you need to look in the AutoCAD ActiveX and VBA Reference. In Visual LISP, choose Help

Tip

You immediately know whether the function is correct, because it turns from black to blue as you enter it.

Any time an error occurs, you can use the last break along with the Visual LISP Error Trace window. To display the Error Trace window, choose View

Figure 36.1. To help you debug your code, the Error Trace window displays every function call before the error, as well as where the error occurred.

The item numbered <5> in Figure 36.1 is what you entered in the Console. The item labeled [2] (+ 1 "a" 3) is where the error occurred, while <1> :ERROR-BREAK signaled the function's termination because of the error.

Visual LISP enables you to find the source position (the line of code that produced the error) and the call source point (the position in your code where the function was called) for the error. To find them, right-click the third item in the Error Trace window. From the shortcut menu, you can choose either Source Position or Call Source Point. Jumping to the position in your code where the function was called is extremely handy when debugging a large application.

Sometimes when you choose Last Break to highlight an error, you find that a great deal of code is highlighted, which is not very helpful for finding the error. This is where break points come in handy. Break points are locations in your code, specified by you, that signal Visual LISP to stop and wait until you're ready to continue processing the code. Visual LISP executes your code and stops at each break point to wait for your instructions. Break points enable you to break down your code into smaller pieces and watch what's going on piece by piece so that you can more easily find the error.

To place a break point, position your cursor to the left of an opening parenthesis or to the right of a closing parenthesis, and press F9. Visual LISP places a temporary red mark in your code.

After creating your break points, you need to reload your code to tell Visual LISP about your break points. Then try to execute the function again. Notice that the Debug toolbar buttons become available. Visual LISP executes your code up to the first break point.

You can use the Debug toolbar to help find your error. The first three buttons offer three different ways to move through your code:

To remove break points, choose View

Figure 36.2. Use the Breakpoints dialog box to remove, show, or disable break points.

In the Breakpoints dialog box, you can do the following:

STEPS: Working with Break Points

The Watch window enables you to examine expressions and variable values as they're being evaluated. To watch a variable, select it in the code and choose Debug

If you have a routine with arguments, you can execute the function with various arguments and see the results on your watched expressions and variables in the Watch window.

Furthermore, you can add any expression to the Watch window and alter the contents of any variable while debugging a function.

STEPS: Using the Watch Window

As you can see, Visual LISP is not just an editor; it's a full-featured, integrated development environment for AutoLISP.