Autolisp is the grand daddy of AutoCAD programming tools and you’d be amazed at the amount of Autolisp programming tools you can find on the Internet. Given a little knowledge you can integrate existing Autolisp routines into your own and gain tremendous power over your AutoCAD based installation.

The first thing to understand is that Autolisp has a couple of key files and a key function that perform startup operations for you. The key files are called ACAD.LSP and ACADDOC.LSP and the key function is called S::STARTUP and their operations are as summarized here:

ACAD.LSP – This file loads when AutoCAD starts up. Any programming you place within this file will be automatically loaded every time AutoCAD starts. The ACAD.LSP file is normally located in the SUPPORT subdirectory of the AutoCAD installation.

ACADDOC.LSP – This file loads every time a new drawing session is started in AutoCAD 2000, 2000i or 2002 based products. Therefore any programming you place in this file will be loaded automatically every time a drawing is opened or started. Note that while the ACAD.LSP file would load in the FIRST drawing of the AutoCAD 2000 type products only the ACADDOC.LSP file will load with subsequent drawings. Since AutoCAD R14 doesn’t support multiple drawing sessions you won’t have to worry about the ACADDOC.LSP file with R14. Like the ACAD.LSP file, ACADDOC.LSP is normally located in the SUPPORT subdirectory of the AutoCAD installation.

S::STARTUP function – This function is typically within the ACADDOC.LSP file (or ACAD.LSP file for AutoCAD R14 installations) and its sole job is to execute customized commands you need to initialize your new drawing environment. This function is the perfect place to set system variables like DIMSCALE, VIEWRES parameters, current layers, etc. The most powerful aspect of the S::STARTUP function is that it invokes automatically and it lets you control exactly how the AutoCAD environment is initialized.

Simple Examples

If you created an ACADDOC.LSP file in the SUPPORT subdirectory of your AutoCAD installation and placed the following text in it what do you think would happen?

(defun s::startup ()
(alert “Hello there!”)
(princ)
)

Well, the DEFUN statement simply DEfines a FUNction (see where the DEFUN comes from) called S::STARTUP which we already know will run every time AutoCAD starts/opens a drawing. The contents of the function are simply an ALERT box notification which will say “Hello there!” followed by a PRINC statement which is traditionally the last line of a function.

Save your new ACADDOC.LSP file checking the syntax carefully to be sure that it’s right and startup AutoCAD. Do you understand the result you get?

Let’s carry the example a bit further by trying this:

(defun s::startup ()
(setvar “textsize” 0.125)
(setvar “dimtxt” 0.125)
(princ)
)

This example sets the default text size and dimension text size to a value of 0.125 (or 1/8” if you prefer) every time a drawing opens or starts. The reason I used the decimal value is that your drawing may not always be in the architectural or fractional coordinate system and thus the decimal value is the most generic way to input a value. This example shows how the SETVAR statement can be used to set AutoCAD’s system variables and also shows how to set values using a generic coordinate system.

Let’s continue the example to a logical conclusion by saying that the TEXTSIZE value really should be 0.125 times the value of the DIMSCALE that is already set in the drawing. To complete this task we’ll need a new command called GETVAR that allows us to get variables (rather than set them) and a multiplication function (the normal * operator) within a single statement. Using a bit of imagination yields the following program:

(defun s::startup ()
(setvar “textsize” (* 0.125 (getvar “dimscale”)))
(setvar “dimtxt” 0.125)
(princ)
)

Note that the statement that sets the text size first gets the DIMSCALE value then multiplies it by 0.125 and only then sets the TEXTSIZE value. The order of the operations occurs from the inner most set of parenthesis out. Please also note there are three sets of parenthesis and that they always balance.

LSP files and functions

As you begin to write your own programs it becomes logical to keep your program code stored in files that can be edited individually. These files always have the .LSP file suffix and are typically edited in a Notepad/WordPad session or in the Visual Lisp editor (which we’ll talk about more in an upcoming issue). The location of the LSP files can be in any directory you want but the easiest way to assure the files will be located is to place them in the SUPPORT folder of your AutoCAD installation.

Within the LSP files you create you may store functions, which are simply programming routines that you can run over and over. A specific type of function, the C: function, allows you to actually add commands to AutoCAD’s vocabulary. By adding new commands, or C: functions, to AutoCAD’s command set your users simply think they have a new AutoCAD command they can use. Only you will know that they are actually using a custom AutoCAD function.

As you create your custom functions and save them as LSP files you’ll need to load in the files to be sure that the functions work. Once debugged the functions can be loaded from the ACAD.LSP file we talked about in Newsletter 61.

A Real World Example

I love keyed in shortcuts for commands like L for line, or E for erase. Some while back I wanted to create a command called FZ that would always give me a zero radius fillet command (for creating sharp corners) yet would still leave the default F fillet command at whatever value I last set it at.

Therefore the program I would write would have to do the following things:

• remember the old fillet radius (set in the FILLETRAD system variable)
• set the new fillet radius to zero
• invoke the fillet command and let me select the objects
• set the fillet radius back to it’s prior setting

The way I programmed this function looks like this:

(defun c:fz () ; line 1
(setq old_radius (getvar “filletrad”)) ; line 2
(setvar “filletrad” 0) ; line 3
(command “.fillet” pause pause) ; line 4
(setvar “filletrad” old_radius) ; line 5
) ; line 6

Example Explained

In the above example I’ve added comments at the end of each line to assign line numbers. You’ll note that each comment is preceded by a semi-colon character which means that the Autolisp interpreter will ignore everything after the semicolon. This method of commenting the program function allows you to store programming notes.

Now I’ll summarize what each line of the program is doing:

1. Defines a command function called FZ using the DEFUN statement.
2. Holds the default fillet radius value in a variable called OLD_RADIUS using the SETQ and GETVAR statements.
3. Sets the fillet radius in the AutoCAD session to 0 using the SETVAR statement.
4. Invokes the FILLET command and has PAUSE statements to wait for input from the user in the form of selecting two lines. Please note that AutoCAD commands are encased in quotation marks and that PAUSE instructions do not.
5. Sets the fillet radius back to its old value using the OLD_RADIUS value using the SETVAR statement.
6. A final parenthesis closes out the DEFUN statement begun in line 1.

Let’s Test It

Now you can create a file called FZ.LSP that contains the programming code from above and save it into AutoCAD’s support directory. Be very sure you’ve typed everything correctly before saving the file (or get the code from my web site which I mention at the end of the newsletter).

Now start your AutoCAD session and type the following at your command prompt:

(load “fz.lsp”)

Once the file is loaded into AutoCAD you should receive confirmation at the command line that will say C:FZ which is the name of the function.

You may now test the function by typing in FZ at the command line. Before you try the new FZ command though use the standard fillet command and set the radius to some non-zero value and fillet a couple of lines to be sure the command has been set properly. Now you should be able to fillet with normal radius values by using the normal fillet command but using FZ will always invoke a zero radius fillet.

That wasn’t so hard was it?

If you’d like you can now add the LOAD instruction line of (load “fz.lsp”) in your S::STARTUP function (mentioned earlier) and your new FZ function will load automatically upon starting AutoCAD. By loading the function from S::STARTUP you’ll take care of your users without them even knowing where the new FZ command came from.

The –Command Set

Some AutoCAD commands will require an addition of a leading “-“ character to invoke them from Autolisp commands because the command is normally manipulated via a dialog box. The layer command is a prime example of this concept that you can verify simply by typing in –LAYER at the command line. Now type in LAYER at the command line and you’ll get a very different result right?

Since AutoCAD commands pass through the Autolisp command interpreter with TYPED input you’ll need to always invoke the –LAYER command in Autolisp code like this:

(command “-layer”) instead of (command “layer”)

If you don’t believe me try it at the AutoCAD command line and see how it works. Other commands I frequently use the “-“ prefix with are –STYLE for text style manipulation and –PLOT for issuing plot commands via Autolisp. You’ll want to examine these commands simply by keying them in at the command line then making some notes about the prompts you can enter into the command line.

In almost all cases with Autolisp commands you’ll need to know how the AutoCAD commands operate and understand the sequence of how to input parameters into the command to write successful functions. If you already type in commands in AutoCAD you should be all set, if not you’ve got some exploring to do. A nice way to document the various keyed in information you use in AutoCAD is to simply copy the text out of the text history window which you access using the F2 key. Then simply use the COPY function to copy the history text into your Notepad programming session.

Errors

When you inadvertently forget parenthesis, quote marks or some other key piece of code in your LSP file you will experience a variety of problems. To see these problems demonstrated try loading in the following programming examples and see what happens.

(defun c:fz ()
(setq old_radius (getvar “filletrad))
(setvar “filletrad” 0)
(command “.fillet” pause pause)
(setvar “filletrad” old_radius)
)

The error here is a missing ” after the word FILLETRAD in the second line. You should see the Autolisp interpreter asking for a ” mark.

(defun c:fz ()
(setq old_radius (getvar “filletrad”))
(setvar “filletrad” 0)
(command “.fillet” pause pause)
(setvar “filletrad” old_radius)

The error here is a missing ) at the end of the program to close the DEFUN statement. You should see the Autolisp interpreter asking for a closing parenthesis.

(defun c:fz ()
(setq old_radius (getvar “filletrad”))
(setvar “filletrad” 0)
(command “.filllet” pause pause)
(setvar “filletrad” old_radius)
)

The error here is an extra L in the word FILLLET. You’ll notice that the function will actually run but will halt when the fillet command should run.

Input and Selection Sets

In the first two installments of our programming series I covered how to store variables, manipulate system variables and use the COMMAND statement to pass instructions to the AutoCAD editor. While these skills are key to writing basic programs you’ll find that to write truly flexible programs you’ll need to be able to:

• Prompt your users for input values (numbers, text, points)
• Prompt your users for sets of data (using selection set identification)
• Filter the AutoCAD database for certain entity types
• Work with entity points (line endpoints, circle centers, etc)

The commands we’ll be utilizing to achieve these goals are as follows:

• GETREAL (to GET a user defined REAL number)
• GETINT (to GET a user defined INTeger number)
• GETSTRING (to GET a user defined STRING of text)
• GETPOINT (to GET a user defined POINT)
• SSGET (to GET a user defined Selection Set)
• SSGET with the “X” option (to filter the database for objects)
• CAR, CADR and CADDR (to break points into X, Y and Z components)

As in past installments I’ll use short pieces of programming code to illustrate the concepts and ramp up the level of complexity gradually until you can understand even complex examples.

Getting Values from the User

Getting user supplied values is straightforward in Autolisp as can be seen with these statements:

(setq var1 (getreal “\nPlease input a REAL number: “))
(setq var2 (getint “\nPlease input an INTEGER number: “))
(setq var3 (getstring “\nPlease input a piece of text: “))

Try pasting these examples into your AutoCAD command line to run the statements interactively and you’ll see immediately what’s happening. The interesting thing to note is that when using the GETINT statement that you can’t input a real number or a piece of text. You’ll also notice that a prompt is generated by the command so the user knows what information to input.

Note: The \n character is simply a line feed that assures you that the prompt to the user will be placed on a new command prompt line in the AutoCAD session!

The result of these statements will be a stored variable VAR1, VAR2 or VAR3 that can be used in other programs. Here’s a simple example of a program you can run interactively that prompts the user then makes use of the stored variable:

(setq dimtxt_height (getreal “\nDimension text height: “))
(setvar “dimtxt” dimtxt_height)

While this is a very simple example it illustrates the concept perfectly. Just acquire a value from the user then use the variable name in other commands instead of fixed values. (See examples from the previous newsletter issues if you have any questions on the SETVAR statement.)

Getting and Working with Points

While getting a point from the AutoCAD user is very simple using this form:

(setq point1 (getreal “\nPlease select a POINT location: “))

Working with the points isn’t easy because the point is actually three pieces of data that must be picked apart. Point data is really a list of X, Y and Z coordinates lumped together which can be decomposed using CAR, CADR and CADDR functions as follows:

(setq point1_x (car point1))
(setq point1_y (cadr point1))
(setq point1_z (caddr point1))

Note that an intermediate variable called POINT1 stored the point while variables POINT1_X, POINT1_Y and POINT1_Z contact the actual values for the x, y and z coordinates, respectively.

This CAR, CADR, CADDR approach requires equal components of memorization and getting used to, but you will find that you’ll grow accustomed to its usage faster than you think.

Working with Sets

Yet another component of AutoCAD programming is that AutoCAD tends to operate on sets (AutoCAD calls them selection sets) of objects. AutoCAD users provide selection sets in commands like MOVE, COPY, ROTATE, ERASE, etc. The rule of thumb is that if a command ever asks you to SELECT OBJECTS that command is making use of a selection set.

To make your programs acquire selection sets you’ll need to use the SSGET command. The most basic form of the command works like this:

(setq set1 (ssget))

or, alternately:

(setq set2 (ssget “\nPlease select objects for your set: “))

the only difference being a user prompt in the second example.

The resulting set will be stored in a variable (SET1 or SET2 in the above examples) that you can manipulate with a COMMAND style instruction. A simple program illustrates the trick:

(setq erase_set (ssget “\nPlease select objects to erase: “))
(command “.erase” erase_set “”)

This example illustrates how a selection can be obtained, stored and processed using only two lines of code!

Note: The final “” is simply an extra ENTER which you’d ordinarily have to hit manually to complete the erase command in AutoCAD.

More Sets

Lets say that you wanted to author a program that would erase all text in a drawing automatically. You will need to use the SSGET command but not for user input, rather you’ll need to filter the AutoCAD drawing for TEXT objects. The example code here looks pretty nasty but you’ll have to trust me when I tell you there isn’t a better way in standard Autolisp:

(setq text_set (ssget “x” (list (cons 0 “TEXT”))))

• Where the “x” parameter denotes the filter
• The “0” parameter is the entity type flag
• The “TEXT” parameter is the entity type you’re selecting

Another example where you would select only text that is on the layer called ANNOTATIONS would look like this:

(setq text_set (ssget “x” (list (cons 0 “TEXT”) (cons 8 “ANNOTATIONS”))))

I’ll admit that this syntax isn’t very user friendly, but you will get used to it. Now simply combine one of the above statements with an ERASE command and you have a program that deletes a give entity type from the drawing automatically:

(setq text_set (ssget “x” (list (cons 0 “TEXT”))))
(command “.erase” text_set “”)

To be really thorough you may also want to trap MTEXT objects as well as TEXT objects by simply adding another SSGET function and modifying the ERASE function call like this:

(setq text_set (ssget “x” (list (cons 0 “TEXT”))))
(setq mtext_set (ssget “x” (list (cons 0 “MTEXT”))))
(command “.erase” text_set mtext_set “”)

As you can see you’ve gained a lot of power in this example using only a few lines of code. For more information on how to filter for more complex sets of objects consult the Developer’s Help section of AutoCAD’s electronic help files and search on the SSGET Autolisp function – you’ll find syntax examples a plenty there.

You should first understand that Visual Lisp began its life as an add-on product and has wound up as a native AutoCAD function with the AutoCAD 2000 release. This means that Visual Lisp support is not standard for AutoCAD R14 platforms so you should be careful not to build Visual Lisp commands into your Lisp routines if R14 support is an issue.

Having exposed Visual Lisp’s only major restriction I can now summarize some of the enhanced features Visual Lisp brings to the table:

Color coding of syntax – Correctly spelled Lisp functions will show as blue while incorrectly spelled functions will remain black, as an example. The color coded environment makes it much easier to detect errors than working with a standard text editor.

Parenthesis matching – A great feature for newer Autolisp programmers (and handy for those of us who’ve been at it a while) that alerts you to mismatched parentheses and quote marks. This feature combined with the color coding mentioned above can save hours on each project.

Compilers – Visual Lisp supports compiling LSP code to a secured “fast load” FAS file format. By compiling your code you’ll discourage user tampering, protect your programming code, and your routines will even load faster due to the compression (roughly 60%) over standard LSP file types.

Reactors – Much like Visual Basic, Visual Lisp reactors have the capability to trigger programs based on what the user is doing at the moment. A useful example would be to trigger a certain procedure when a user saves a drawing to set layers and variables correctly. In Autolisp the only way to accomplish this task would be to redefine the SAVE, SAVEAS and QUIT functions (relatively messy) but in Visual Lisp the VLR reactor commands allow you to seamlessly detect what the user is doing and REACT to it.

Let’s Get Rolling

Start up AutoCAD and type in VLISP or VLIDE at the command line and wait for the Visual Lisp window to activate. You’ll now be able to start a new file using the File menu’s New File command. You may now start typing Autolisp code into the window. For our purposes we’ll start with the following:

(setq variable1 28.4)

Note how the components of the syntax are colored? The color coding will help you differentiate functions from variables. Now type in the following intentionally incorrect syntax and see what happens:

(seta variable1 28.4)

Note that the SETA will not be colored blue but rather black. This is your clue that the SETA is not being recognized as a function. See how that works? You may now feel free to mistype functions and see how the colors change to assist you with debugging.

Save the Results

Now you’ll simply use the File menu’s SAVEAS command to save your programming work in an LSP file format. Please note where the LSP file is stored because its location will be important in just a moment!

After saving the LSP file you can compile your programming code to the FAS file format by using the Visual Lisp Console (you’ll see it in the Visual Lisp for AutoCAD window) to execute the VLISP-COMPILE command as follows:

(vlisp-compile ‘st “filename.lsp”)

Where:

• The ‘ST parameter denotes the standard compile build method which creates a FAS type file.
• The FILENAME.LSP is the input file you wish to have compiled to FILENAME.FAS

I should point out that there are other options you can use with the VLISP-COMPILE function that I’ve not mentioned. The easiest way to see all the options are to use the AutoCAD Developer’s Help and search on VLISP-COMPILE for all the syntax options. I think you’ll find that the form of the command I’ve covered is useful in 99% of the cases you’ll likely need though.

Hint: As an extension of the above topic why not fire up the Visual Lisp VLIDE and simply compile your old LSP files to FAS files to gain the speed and security advantages that Visual Lisp has to offer?

Load It Up!

Now that you have compiled FAS files you may need to modify other Autolisp routines or menus to load the newly compiled formats. The rule of thumb is to look for LOAD instructions like this one:

(load “myprogram.lsp”)

and change them to:

(load “myprogram.fas”)

All the same rules regarding paths and file loading are exactly the same for Visual Lisp FAS files as they are for LSP so your biggest challenge will be searching your existing code and substituting FAS for LSP.

Programming with Reactors

In the last issue of the newsletter I promised we’d have a look at Visual Lisp reactors in this issue. Simply put, Visual Lisp reactors are a set of functions that understand what you are doing within the AutoCAD session and then react by running instructions you program, thus the name reactors.

Getting reactors running requires a few overhead steps which we must go over before we actually try to program something. Those steps are listed here:

• Load the necessary reactor code from the ACADDOC.LSP or the ACAD.LSP file by inserting the following line into the code:

(vl-load-com)

Note that this code must execute BEFORE any other functions having to do with reactors. Also note that this only works with AutoCAD 2000 or later, not with AutoCAD R14.

• Define your particular commands using names that indicate what the functions will do. I offer the following two examples, one will run just prior to saving while the other will run just after saving:

(defun DoThisAfterSave (Caller CmdSet)
(alert “You just saved the drawing!”)
(princ)
)

(defun DoThisBeforeSave (Caller CmdSet)
(alert “You are about to save the drawing!”)
(princ)
)

Note the syntax for the input arguments to the functions, CALLER and CMDSET which cannot be omitted. In both these cases the only result of the function will be an ALERT box. We’ll substitute in some more useful command syntax in a while.

• Now create your own reactor set as follows using the VLR-DWG-REACTOR function as shown:

(setq MyReactor1
(vlr-dwg-reactor
nil
‘((:vlr-BeginSave . DoThisBeforeSave)
(:vlr-SaveComplete . DoThisAfterSave)
)
)
)

Note the “:” characters before the VLR functions which are very easy to miss. Note that the instruction for each reactor is simply the one of the functions you defined in step 2. There are additional drawing reactors available besides the two I’ve illustrated, those being :vlr-beginClose, :vlr-databaseConstructed, :vlr-databaseToBeDestroyed, vlr-beginDwgOpen, :vlr-endDwgOpen and :vlr-dwgFileOpened.

• Last, define removal tools to unload your reactors and/or all reactors should you want to return AutoCAD to its default state. Simply use the following code segments to accomplish both removal tasks:

(defun Clear_My_Reactors ()
(if (and MyReactor1 (vlr-added-p MyReactor1))
(vlr-remove MyReactor1)
)
)

(defun Clear_All_Reactors ( / TMP)
(vlr-remove-all :vlr-dwg-reactor)
)

Note that it the CLEAR_MY_REACTORS function that the MyReactor1 argument must agree with the reactor function you created in step 3.

Try It

Using the sample code from the steps above create an ACADDOC.LSP file and place it in your support directory. Now restart AutoCAD so that the code will be loaded into AutoCAD upon startup. There will be no evidence that you’ve actually created the reactors if everything goes well, however, if you have any typos or errors in your ACADDOC.LSP file you will see error codes at AutoCAD’s command line.

Assuming no errors you may now draw a couple of objects in the drawing and proceed to save your work. After you specify a name for the drawing you should receive an alert that:

“You are about to save the drawing!”

after actual saving you’ll receive another alert that:

“You just saved the drawing!”

These alert messages are proof that your custom reactors are functioning. We may now proceed to add some code that performs more useful functions that simply alerting you.

Beefing up the Code

Let’s say you defined one of your reactor functions like this:

(defun DoThisBeforeSave (Caller CmdSet)
(command “-purge” “a” “*” “n”)
(princ)
)

This function would mean that just before any save was executed that a purge of all purgable objects would happen automatically! You’ll never have to remind people to purge again.

How about this reactor function:

(defun DoThisBeforeSave (Caller CmdSet)
(command “.zoom” “e”)
(princ)
)

This function would automatically zoom to extents before any drawing was saved!

It doesn’t take a whole lot of imagination to see what you can do with reactors does it? I bet you’re already thinking of what you can accomplish, right?

Other Reactors

Besides the vlr-dwg-reactor you may want to investigate the vlr-dxf-reactor and the vlr-editor-reactor for functions that allow you to control dxf file writes/reads and to eavesdrop on the editing session, respectively. These reactor elements are very powerful and far easier to use than command definitions in conventional Autolisp.

You may even find that customization using reactors makes moving away from the tried and true R14 platform worth it if nothing else has. I encourage you to explore these reactor elements, you’ll find it worthwhile.

Two key characteristics of AutoCAD scripts should be pointed out before we proceed:

• Scripts may only invoke commands that can be typed into AutoCAD’s Command: prompt. Therefore any task that requires dialog style commands is not a good candidate for scripting.
• Scripts allow AutoCAD to run unattended thus permitting great productivity for repetitive operations like purging or plotting batches of drawings. They key strength is that scripts can open, save and quit drawings thus hopping between drawing sessions with ease.

Here’s a simple script example. Open a Notepad session and type in EXACTLY the following:

line 0,0 5,0 5,5 0,5 close zoom w -1,-1 6,6

Save the file to your hard drive as TESTING.SCR then start a session of AutoCAD and key in SCRIPT at the command line. When prompted for the name of the script file to run select the TESTING.SCR file you saved previously.

Other possibilities for scripting include using the -LAYER command to build long lists of layers. This script would add a layer called SKY and color it blue and set it to be the current layer:

-layer m sky c blue sky

I also like using the -PLOT command for detailed plotting configuration. From AutoCAD’s dialog line type in -plot and see where it takes you. You can then write scripts using the technique.

Lastly, a very nice script can be used to purge and zoom extents like this:

purge a * n zoom e

Note: AutoCAD scripts (file type SCR) should not be confused with Visual Basic Script (file type VBS), as the two have nothing in common.