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

Get Under the Hood of Visual LISP

One of the best ways to learn to customize AutoCAD is to poke around the engine of the VLIDE programming environment.

Some people are content to simply drive a car and put fuel in it when the gas gauge indicates the need. Others become curious about how the car works and venture into tinkering with the engine. Sometimes necessity is reason to develop a new skill -- for example, if your car is not functioning properly or to the level you desire.

Computers generate similar responses in people. Most users are content to simply run the computer and use built-in commands to get the job done. But some strive to get the computer to do more. If you're reading this newsletter, you're among that group. After unsuccessfully scouring the AutoCAD user manual and online forums for "magic" or "hidden" commands to address your needs, you have found yourself getting into programming. As you explore the possibilities for customizing your CAD system, things begin to get very interesting.

Dig In
Visual LISP contains more than 800 internal functions and is capable of growing many more through programming and importing object libraries. Some LISP functions -- such as SETQ and DEFUN -- are built in, used often and eventually become second nature. But what about the lesser-known functions? Learning those takes a lot of time and effort. For most programmers, learning them all would be impossible. Fortunately, the Visual LISP for AutoCAD Developer Environment, or VLIDE, contains some tools that make research easier when you do have the time available.

For those just getting started, the first step is to learn the basics of programming LISP inside AutoCAD. Numerous books and online articles are available to help, but the best way to really get started is to find and download a potentially useful LISP program, then open it in the VLIDE. When you open a LISP program in the VLIDE, the reserved function names -- the internal function known to LISP, such as DEFUN and SETQ -- display in blue so you can identify them immediately. If such functions are displaying in some other color, they might be part of a comment (gray background) or something could be wrong with the editor window (colors have been changed, computer has crashed, window is not actually displaying in the foreground or some other unusual circumstance).

The Help icon in Visual LISP.

Scanning through the text window of an open LISP file in the VLIDE, locate a blue symbol that you do not recognize. Highlight the symbol name by double-clicking on it, then click on the Visual LISP Help icon to bring up the online Help.

The symbol you highlighted should appear in the Visual LISP Help window. You've just opened the hood and can now see the engine parts.

Another avenue into the Visual LISP Help system is through the VLIDE pull-down menu. An alphabetical index of all documented LISP functions, known as the AutoLISP Reference, is displayed when you start into the Help system via the menu. Here, you will find the same descriptions of standard LISP internal functions.

Under V, you'll find an alphabetical list of the functions that start with that letter, including a long list of VL functions that were added when AutoLISP was enhanced into Visual LISP. The V list of functions is not complete; if it were, it would scare away most students of LISP.

The Apropos icon in Visual LISP.

To view a more complete list of the functions available for use in Visual LISP programming, click the Apropos icon.

Use the Apropos command to display a list of all known symbols given a filter. To find all VLA functions, type VLA in the Apropos Options dialog box.

Use the Apropos Options dialog box (above) to specify the search criteria for the symbols you wish to locate. Here, the user wants to display all VLA functions, which appear in the Apropos Results box (right).

The Apropos Results box displays a list of symbols matching filter input, as shown above. You can see that the number of functions found exceeds the available memory for Apropos to display after (VL-LOAD-COM) has been evaluated. That's quite a list!

Use Apropos to learn more about what is available inside Visual LISP at any given time, then call up the Help system to see if additional function details are available there -- in particular for items defined as symbols.

The Inspect icon in Visual LISP.

When you want to learn more about objects defined during run time, the Apropos command won't get you very far. Instead you will want to use the Inspect command.

After obtaining the result from some expression and placing it into a symbol, select the Inspect icon and enter the symbol name. If the symbol is an object reference, the details about the object will display. For example, type (setq A 1) in the Visual LISP console window and press Enter. Now inspect the symbol A to see that it evaluates to an integer value of 1. You can learn a lot about what is inside an object using this tool. Now we are really getting deep under the hood.

When you encounter a function that has a name starting with VLA-, that's a clue that you might find documentation for it in the ActiveX and VBA Reference Book. For example, note that the VLA-ADDARC function appears in the Apropos Results box shown above. However, this function is not documented in the Visual LISP references but rather in the ActiveX and VBA reference. To open these references, launch the Visual LISP Help system, go to the chapter panel and select ActiveX and VBA Reference Book. Now select the Methods section for a complete list of the available methods displayed in alphabetical order.

Translation, Please
Now the problem is learning how to convert what you see in the VBA references to something that works in Visual LISP. Actually, this is rather easy once you get the hang of it.

To go through an example of this process, let's open the ActiveX and VBA reference information for the method ADDARC.

ActiveX and VBA reference information for the method ADDARC.

To translate to the Visual LISP environment, add VLA- to the front of the method name. That's the easy part. Next look at the object found before the name ADDARC. In this case it is the object to which arcs can be added. That includes the model and paper space areas as well as blocks definitions. The object reference will become the first parameter for the VLA function.

Next, we can look at a Visual LISP snippet that uses the VLA-ADDARC function.

A snippet of LISP code that uses the VLA-ADDARC function.

Arcs are added to model space in this simple example. Also note here that you must convert point lists to VLA 3D points before sending them to the ActiveX function. As I said, with a little practice you will get the hang of this.

Baby Steps
You might wonder if it's worth all the effort to work with objects. Obviously adding an arc is a pretty simple thing in Visual LISP. You can use the COMMAND function and send the command strings directly to the system. You may opt to use the ENTMAKE approach and create an entity list. Or you can use the object approach and store your arcs in places other than just the active space. For example, you can add entity objects to block definitions if desired.

Exploring Visual LISP and the VLIDE requires a lot of tinkering under the hood, as I've described. And that requires something very precious to the Visual LISP programmer, who typically has a primary job function as a designer or CAD manager: time. The good news is that the powerful Visual LISP programming system comes with an environment that encourages you to explore and find out what's inside. To put it simply, the best way to improve at this craft is:

Keep on programmin'!