AutoLisp

(1)

The

AutoLisp

Tutorials

(2)

Written and Compiled by Kenny Ramage [email protected]

http://www.afralisp.com

(3)

[email protected] http://www.afralisp.com

This publication, or parts thereof, may not be reproduced in any form, by any method, for any purpose, without prior explicit written consent and approval of the author.

The AUTHOR makes no warranty, either expressed or implied, including, but not limited to any implied warranties of merchantability or fitness for a particular purpose, regarding these materials and makes such materials available solely on an "AS -IS" basis. In no event shall the AUTHOR be liable to anyone for special, collateral, incidental, or consequential damages in connection with or arising out of purchase or use of these materials. The sole and

exclusive liability to the AUTHOR, regardless of the form of action, shall not exceed the purchase price of the materials described herein.

The Author reserves the right to revise and improve its products or other works as it sees fit. This publication describes the state of this technology at the time of its publication, and may not reflect the technology at all times in the future.

AutoCAD, AutoCAD Development System, AutoLISP, Mechanical Desktop, Map, MapGuide, Inventor, Architectural Desktop, ObjectARX and the Autodesk logo are registered trademarks of Autodesk, Inc. Visual LISP, ACAD, ObjectDBX and VLISP are trademarks of Autodesk, Inc. Windows, Windows NT, Windows 2000, Windows XP, Windows Scripting Host, Windows Messaging, COM, ADO®, Internet Explorer, ActiveX®, .NET®, Visual Basic, Visual Basic for Applications (VBA), and Visual Studio are registered trademarks of Microsoft Corp.

All other brand names, product names or trademarks belong to their respective holders.

(4)

The Basics in a Nutshell

So, you've never programmed in AutoLisp before!

You've tried to decipher some AutoLisp routines but, you are still totally confused!!! Let's see if we can't help you out.

This tutorial will try and teach you the very basics of AutoLisp programming without overwhelming you with double-gook.

Let's start up with something very simple and that will give you immediate results. Fire up AutoCad and type this at the command prompt:

(alert "Yebo Gogo")

Now press enter. This should appear on your screen :

Well Done, you've just used AutoLisp to make AutoCad do something.

By the way, most other programming tutorials use "Hello World" as a similar example. But, because this is an African site, I thought that I would use a very well known Zulu phrase instead.

As you noticed using the (alert) function results in a dialogue box being displayed on your screen.

Let's try something else. Type this at the command prompt and press enter : (setq a (getpoint))

Then choose a point anywhere on the screen.

A "list" of numbers, looking something like this, should appear in your command window.

(496.0 555.06 0.0)

This list, believe it or not, contains the x, y and z coordinates of the point you picked. x = 496.04

y = 555.06 z = 0.0

(7)

The AutoLisp coding :

(setq a (getpoint)) Means, in plain English :

Get a point from the user and store the x, y and z values as a list in variable "a".

Did you notice how everything is enclosed within parenthesis? All AutoLisp functions are surrounded by parenthesis.

As well, AutoLisp allows you to "nest" your functions.

This lets you write a function that evaluates another function.

Just remember, that you must leave the nest with an equal number of parenthesis. Here's an example :

(dosomething (dosomethingelse (andanotherthing))) You could also write the above statement like this to make it more readable : (dosomething

(dosomethingelse

(andanotherthing) )

)

Now you can see why "Lisp" is often known as "Lost in Stupid Parenthesis"

You can also add comments to your coding. Anything preceded with a semicolon is not evaluated by Autolisp and is treat as a comment, much the same way as the REM

statement in Basic is used. e.g. (dosomething

(dosomethingelse

(andanotherthing) ;This is a comment ) ;This is another comment

) ;and another comment

The statement we wrote earlier, told AutoLisp to get a point from the user and store the value in variable "a".

Now type this at the command line : !a

The point list should be returned. So, any time that you would like to inspect a variable, just precede the variable name with "!"

(8)

Our getpoint function worked, but it didn't really tell the user what was expected from him by way of input. Try this now :

(setq a ( getpoint "\nChoose a Point : "))

Did you notice how Autolisp now asks you for input (and what type of input is expected.) Let's write a programme.

Type in each of these lines, one at a time, pressing "Enter" at the end of each line, then choosing a point.

(setq a (getpoint "\nEnter First Point : ")) Press "Enter" then select a point.

(setq b (getpoint "\nEnter Second Point : ")) Again, Press "Enter" then select a second point.

(command "Line" a b "")

Press "Enter" again. A line should be drawn between the two points. The (command) function is used to tell AutoCad what you want it to do. "Line" Draw a Line

a From the point stored in variable "a" b To the point stored in variable "b" "" Enter to close the Line command.

Now this is very nice, but do we have to type in all this coding every time we want to use this routine?

Next we will discuss how to "store" your programs in a file.

(9)

We now need to be able to "store" our AutoLisp routines in a file. AutoLisp files are simple ASCII text files with the extension "lsp".

Open up Notepad or any other simple text editor and type in the following : (defun testline ()

;define the function

(setq a (getpoint "\nEnter First Point : ")) ;get the first point

(setq b (getpoint "\nEnter Second Point : ")) ;get the second point

(command "Line" a b "") ;draw the line

) ;end defun

Now, save this file as "testline.lsp" remembering, to save it as a ASCII Text file and ensuring that it is saved in a directory in your AutoCAD's search path. Now open AutoCAD and type this :

(load "testline")

This will load the function into memory. (Did you notice that you do not have to stipulate the "lsp" extension?) Now type this :

(testline)

Your function should now run.

Let's edit this routine so that it acts like a standard AutoCAD command :

(defun c:testline ()

) ;end defun

By preceding the function name with c: we do not have to enclose the name with brackets when running. Re-load the function and run it again.

(10)

(load "testline") testline

Much better, Hey.

We do have one problem though. Did you notice that when we loaded the routine, an

annoying "nil" kept on popping up. We also got the same "nil" returned to us when we ran the routine. To suppress this "nil" when loading or

running, we can use the (princ) function. Here's what your routine would look like :

(defun c:testline ()

(princ)

;clean running ) ;end defun (princ)

;clean loading

For more details on the (defun) function, refer to The AfraLisp Tutorial :

Define Function (defun).

And for a more detailed expanation of loading AutoLisp routines, refer to the AfraLisp tutorial :

Loading AutoLisp Files.

Now it's time to make AutoLisp do some calculations for us.

Let's say we wanted AutoLisp to draw a beam, in elevation, for us.

First of all we would start by getting input from the user regarding certain parameters that we would need to draw the beam.

Here's what we are trying to draw, along with the values that the user needs to input.

(11)

The values that we need to retrieve from the user are as follows :

Insertion Point ip Length of Beam lb Height of Beam hb Flange Thickness wt End Plate Thickness ep Length of Notch nl Depth of Notch nd

Let's write a routine to retrieve these values first. (defun c:testbeam ()

;******************************************************** ;Get User Inputs

(setq lb (getdist "\nLength of Beam : ")) ;get the length of the beam

(setq hb (getdist "\nHeight of Beam : ")) ;get the height of the beam

(setq wt (getdist "\nFlange Thickness : ")) ;get the thickness of the flange

(setq ep (getdist "\nEnd Plate Thickness : ")) ;get the thickness of the end plate

(setq nl (getdist "\nLength of Notch : ")) ;get the length of notch

(setq nd (getdist "\nDepth of Notch : ")) ;get the depth of the notch

(12)

;End of User Inputs

;********************************************************* ;Get Insertion Point

(setq ip (getpoint "\nInsertion Point : ")) ;get the insertion point

;******************************************************** (princ)

;finish cleanly ) ;end of defun

;********************************************************** (princ) ;load cleanly

;**********************************************************

Load and run the routine. You will be prompted for all the values listed above. Enter some numbers and then check the value of all the variables by preceeding the value names with "!" (e.g. !ip).

O.K. we've got all the values we need from the user.

But first we need to do some calculations to determine the other points required before we can draw the beam.

(13)

Well, as you can see, we have quite a few points that we need to calculate. Fortunately, AutoLisp has a function to help us, the (polar) function.

The (polar) function works like this :

You pass it a point, an angle and a distance and (polar) will return a second point at the specified angle and distance from the first point.

But, we have one problem. All angles in AutoLisp MUST be given in radians.

Let's quickly write a function to do that. Add this function to your Testbeam.lsp file :

(defun dtr (x)

;define degrees to radians function (* pi (/ x 180.0))

;divide the angle by 180 then

;multiply the result by the constant PI ) ;end of function

O.K. thats our "degrees to radians" function taken care of. Now we'll have a look at the (polar) function in action.

(setq p2 (polar ip (dtr 180.0) (- (/ lb 2) nl)))

What we are saying here is :

"Set the variable "p2" to a point that, from the insertion point "ip", at an angle of 180.0 degrees (converted to radians), is at a distance of the length of the beam divided by 2, minus the length of the notch."

This will calculate and return the point "p2". Let's do the rest :

(14)

;******************************************************** ;Get User Inputs

;********************************************************

;Start of Polar Calculations

(setq p2 (polar ip (dtr 180.0) (- (/ lb 2) nl))) (setq p3 (polar p2 (dtr 270.0) wt))

(setq p4 (polar p2 (dtr 270.0) nd)) (setq p5 (polar p4 (dtr 180.0) nl)) (setq p6 (polar p5 (dtr 180.0) ep))

(setq p7 (polar p6 (dtr 270.0) (- hb nd))) (setq p8 (polar p7 (dtr 0.0) ep))

(setq p9 (polar p8 (dtr 90.0) wt)) (setq p10 (polar p9 (dtr 0.0) lb)) (setq p11 (polar p8 (dtr 0.0) lb)) (setq p12 (polar p11 (dtr 0.0) ep))

(setq p15 (polar p14 (dtr 180.0) nl))

(setq p16 (polar p15 (dtr 90.0) (- nd wt))) (setq p17 (polar p16 (dtr 90.0) wt))

(15)

;********************************************************** (princ) ;finish cleanly ) ;end of defun ;**********************************************************

;This function converts Degrees to Radians. (defun dtr (x)

;**********************************************************

Right, now that we've calculated all the points required to draw the beam, let us add a (command) function to do this task for us.

(defun c:testbeam ()

;******************************************************** ;Get User Inputs

(16)

;******************************************************** ;Start of Polar Calculations

;End of Polar Calculations

;**********************************************************

;Start of Command Function

(command "Line" ip p2 p4 p6 p7 p12 p13 p15 p17 "c" "Line" p3 p16 "" "Line" p9 p10 "" "Line" p5 p8 "" "Line" p11 p14 "" ) ;End Command

;End of Command Function ;********************************************************* (princ) ;finish cleanly ) ;end of defun ;********************************************************** ;This function converts Degrees to Radians.

(17)

(defun dtr (x)

;**********************************************************

O.K. Let's load the program and run it.

Now, depending on how your snap is set, the beam might be drawn correctly, or it may not. On my system it doesn't draw properly.

This is because my snap defaults to intersection and AutoCad keeps on snapping to the wrong point. I also have lot's of annoying "blips" on my screen. Now we'll discuss how to get around these problems.

(18)

Snap settings in AutoCad can cause havoc with an AutoLisp routine.

Therefore, it's a very good idea to switch off the snap at the beginning of any AutoLisp routine and only switch it on when it is required. Blips on your screen are also very annoying, so switch them off too. Please, just remember to return the AutoCad settings that you change, back to their original state before exiting your routine.

Let's edit our routine to include this : (defun c:testbeam ()

;********************************************************

;Save System Variables

(setq oldsnap (getvar "osmode")) ;save snap settings

(setq oldblipmode (getvar "blipmode")) ;save blipmode setting

;******************************************************** ;Switch OFF System Variables

(setvar "osmode" 0) ;Switch OFF snap

(setvar "blipmode" 0) ;Switch OFF Blipmode

;******************************************************** ;Get User Inputs

(19)

(setvar "osmode" 32) ;switch ON snap

(setvar "osmode" 0) ;switch OFF snap

;********************************************************** ;Start of Command Function

;End of Command Function

;**********************************************************

;Reset System Variable (setvar "osmode" oldsnap) ;Reset snap

(20)

;Reset blipmode ;********************************************************* (princ) ;finish cleanly ) ;end of defun ;********************************************************** ;This function converts Degrees to Radians.

(defun dtr (x)

;**********************************************************

Load and run the program. If you were having problems, they should now have

disappeared. (I hope!!). Did you notice how we switched on the snap just before asking for the insertion point?

This, of course, is to allow the user to snap to an insertion point.

We still have another problem though. What would happen if the user entered an illegal value, such as zero, or a negative number.

This could cause very strange results.

To guard against this we will use the (initget) function. Here's how it works :

(initget (+ 1 2 4))

(setq lb (getdist "\nLength of Beam : "))

This function works on the "sum of the bits" system.

1 = Disallows the user from pressing "Enter". 2 = Disallows the user from entering "Zero".

3 = Disallows the user from entering a "Negative Number".

The same function could have been written like this :

(21)

(setq lb (getdist "\nLength of Beam : "))

Let's add this function to our routine :

;******************************************************** ;Save System Variables

;******************************************************** ;Get User Inputs

(initget (+ 1 2 4)) ;check user input

(22)

(setvar "osmode" 32) ;switch ON snap

(command "Line" ip p2 p4 p6 p7 p12 p13 p15 p17 "c" "Line" p3 p16 ""

(23)

"Line" p9 p10 "" "Line" p5 p8 "" "Line" p11 p14 "" ) ;End Command

;********************************************************** ;Reset System Variable

(setvar "osmode" oldsnap) ;Reset snap

(setvar "blipmode" oldblipmode) ;Reset blipmode ;********************************************************* (princ) ;finish cleanly ) ;end of defun ;********************************************************** ;This function converts Degrees to Radians.

(defun dtr (x)

;**********************************************************

Now, everything should be running fine except for one thing.

What happens if we want to draw two beams with exactly the same values? We would have to go through the whole routine again, entering exactly the same inputs. We could, of course, set up each variable to default to the last value used, but we would still have to run through the whole routine. Here's a better way. We'll enclose the complete routine in a (while) loop. Have a look :

;******************************************************** ;Save System Variables

(24)

;******************************************************** ;Get User Inputs

(25)

;Get Insertion Point (setvar "osmode" 32) ;switch ON snap

(while

;start of while loop

;**********************************************************

(setvar "osmode" 32) ;Switch ON snap

(26)

;********************************************************** ;Reset System Variable

(setvar "osmode" oldsnap) ;Reset snap

(setvar "blipmode" oldblipmode) ;Reset blipmode ;********************************************************* (princ) ;finish cleanly ) ;end of defun ;********************************************************** ;This function converts Degrees to Radians.

(defun dtr (x)

;**********************************************************

The program will now repeat itself indefinitely, asking for an insertion point and drawing a beam, until the user presses enter.

This is how it works. The (while) function will continue to evaluate an expression until the expression evaluates to nil. As long as the user selects a point, the expression is true. But, when the user selects "Enter" the expression returns "nil" and the program moves out of the loop. (AutoLisp evaluates "Enter" as "nil")

I hope you have understood this tutorial and that it has given you a better understanding of AutoLisp. You will find a more detailed explanation of many of the functions used here in other tutorials within this manual

(27)

Loading AutoLISP Files.

Note!!

One of the most important things to remember about loading AutoLisp Routines is to ensure that your Lisp files and any support files (i.e DCL Files; DAT Files; etc) are in your AutoCad search path. (I dedicate a directory to all my Lisp files and relevant support files.

There are numerous ways of loading AutoLisp Files : Command Line Loading.

The simplest is from the AutoCad command line. The syntax for loading AutoLisp files is :

(load "filename")

The.lsp extension is not required. Menu Loading.

The following code samples are one way of loading AutoLisp files from a menu. Pull Down Menu's :

***POP12

T_Steel [Steel Menu]

T_Beams [Drawing Setup]^C^C^P+

(cond ((null C:DDSTEEL) (prompt "Please Wait...")(load "DDSTEEL"))) DDSTEEL

Toolbars : ***TOOLBARS **STEEL

TB_DDSTEEL [_Button("Steel", "STEEL.bmp", "STEEL32.bmp")]^C^C^P+ (cond ((null C:ddsteel) (prompt "Please Wait...")(load "ddsteel"))) ddsteel

This method of loading Lisp files first checks to see if the routine is already loaded. If it is, it runs the routine. If it is not, it first loads the routine, then runs it. Clever Hey... AcadDoc.Lsp File.

The AcadDoc.Lsp file is a useful way of loading a library of AutoLisp routines.

Each time you start a drawing AutoCad searches the library path for an AcadDoc.Lsp file. If it finds one, it loads the file into memory.

(28)

You could use the normal load function (load "filename") in your AcadDoc.Lsp file but if an error occurs whilst attempting to load one of your routines, the remainder of the file is ignored and is not loaded.

Therefore, you must use the on failure argument with the load function : (load "Lispfile1" "\nLispfile1 not loaded")

(load "Lispfile2" "\nLispfile2 not loaded") (load "Lispfile3" "\nLispfile3 not loaded") The .MNL File

The other type of file that AutoCad loads automatically is the .MNL file. If you have a partial menu file it can also have it's own .MNL file.

Just remember that the .MNL file must have exactly the same name as your partial menu file. (except for the .MNL extension, of course.)

You can load Lisp files from this file using the load function exactly the same as you did in the AcadDoc.Lsp file.

Command Autoloader

When you automatically load a command from your AcadDoc.Lsp file (or a .MNL file) the commands definition consumes your systems resources whether you actually use the command or not. The Autoload function makes a command available without loading the entire routine into memory.

(Autoload "Utils" '("Utils1" Utils2" "Utils3")) (Autoload "DDSteel" '("DDSteel"))

This would automatically load the commands Utils1, Utils2 and Utils3 from the Utils.Lsp file and DDSteel from the DDSteel.Lsp file.

S::Startup Function.

If the user defined function S::Startup is included in the AcadDoc.lsp or a .MNL file, it is called when you enter a new drawing or open an existing drawing.

e.g. Say that you wanted to override the standard AutoCad LINE and COPY commands with versions of your own, your AcadDoc.Lsp file would something like this :

(defun C:LINE () ...Your Definition... ) (defun C:COPY () ...Your Definition... ) (defun S::Startup ()

(29)

(command "Undefine" "COPY") )

Before the drawing is initialised, new definitions for LINE and COPY are defined. After the drawing is initialised, the S::Startup function is called and the standard definitions of LINE and COPY are undefined.

(30)

AutoCAD and Customizable Support Files

Table of Customizable Support Files

Order of support file loading when starting AutoCAD

Automatically Load and Execute AutoLISP Routines

Automatically Load ObjectARX Applications acad.lsp—Automatically Load AutoLISP acaddoc.lsp—Automatically Load AutoLISP Menu File Types

Load Menu Files

acad.mnl—Automatically Load AutoLISP Menu Functions

S::STARTUP Function—Post-Initialization Execution

Tips for Coding AutoLISP Startup Files Command Autoloader

acadvba.arx—Automatically Load VBA acad.dvb—Automatically Load a VBA Project Automatically Loading a VBA Project

Automatically Running a VBA Macro

Table of Customizable Support Files

AutoCAD uses support files for purposes such as storing menu definitions, loading AutoLISP and ObjectARX applications, and describing text fonts. Many support files are text files that you can modify with a text editor.

The following is a list of AutoCAD support files that can be edited. The support files are listed in alphabetical order by file extension. Please make backup copies of these files before modifying them.

Customizable support files File Description

asi.ini Database connectivity link conversion mapping file.

*.dcl AutoCAD Dialog Control Language (DCL) descriptions of dialog boxes. *.lin AutoCAD linetype definition files.

acad.lin The standard AutoCAD linetype library file. acadiso.lin The standard AutoCAD ISO linetype library file. *.lsp AutoLISP program files.

acad.lsp A user-defined AutoLISP routine that loads each time you start AutoCAD. acaddoc.lsp A user-defined AutoLISP routine that loads each time you start a drawing. *.mln A multiline library file.

*.mnl AutoLISP routines used by AutoCAD menus. A MNL file must have the same file name as the MNU file it supports.

acad.mnl AutoLISP routines used by the standard AutoCAD menu.

*.mns AutoCAD generated menu source files. Contains the command strings and macro syntax that define AutoCAD menus.

(31)

acad.mns Source file for the standard AutoCAD menu.

*.mnu AutoCAD menu source files. Contain the command strings and macro syntax that define AutoCAD menus.

acad.mnu Source file for the standard AutoCAD menu. *.pat AutoCAD hatch pattern definition files.

acad.pat The standard AutoCAD hatch pattern library file. acadiso.pat The standard AutoCAD ISO hatch pattern library file.

acad.pgp The AutoCAD program parameters file. Contains definitions for external commands and command aliases.

acad.psf AutoCAD PostScript Support file; the master support file for the PSOUT and PSFILL commands.

acad.rx Lists ObjectARX applications that load when you start AutoCAD.

*.scr AutoCAD script files. A script file contains a set of AutoCAD commands processed as a batch.

*.shp AutoCAD shape/font definition files. Compiled shape/font files have the extension .shx.

acad.unt AutoCAD unit definition file. Contains data that lets you convert from one set of units to another.

Order of support file loading when starting AutoCAD

You can understand the effects that one file may have on another if you know the order in which files are loaded when you start the software. For example, you have defined a function in an AutoLISP routine that is loaded from the acad.lsp file, but the function does not work when you start AutoCAD. This occurs because the function has been redefined by the acaddoc.lsp file, which is loaded after acad.lsp.

Following is a list of AutoCAD, Express Tools, and user-defined files in the order they are loaded when you first start the program.

File For use by:

acad2000.lsp AutoCAD

acad.rx User

acad.lsp User

acad2000doc.lsp AutoCAD

(32)

acaddoc.lsp User

mymenu.mnc User

mymenu.mnl User

acad.mnc AutoCAD

acad.mnl AutoCAD

acetmain.mnc Express Tools

acetmain.mnl Express Tools

s::startup User

Note: If the user-defined function S::STARTUP is included in the acad.lsp or acaddoc.lsp file or a MNL file, the function is called when you enter a new drawing or open an existing drawing. Thus, you can include a definition of S::STARTUP in the LISP startup file to perform any setup operations.

Automatically Load and Execute AutoLISP Routines

As you build a library of useful AutoLISP routines, you may want to load them each time you run AutoCAD. You may also want to execute certain commands or functions at specific times during a drawing session.

AutoCAD loads the contents of four user-definable files automatically: acad.rx, acad.lsp, acaddoc.lsp, and the .mnl file that accompanies your current menu. By default, the acad.lsp loads only once, when AutoCAD starts, while acaddoc.lsp loads with each individual document (or drawing). This lets you associate the loading of the acad.lsp file with application startup, and the acaddoc.lsp file with document (or drawing) startup. The default method for loading these startup files can be modified by changing the setting of the ACADLSPASDOC system variable.

If one of these files defines a function of the special type S::STARTUP, this routine runs immediately after the drawing is fully initialized. The S::STARTUP function is described in S::STARTUP

Function—Post-Initialization Execution. As an alternative, the APPLOAD command provides a Startup Suite option that loads the specified applications without the need to edit any files.

The acad.lsp and acaddoc.lsp startup files are not provided with AutoCAD. It is up to the user to create and maintain these files.

Automatically Load ObjectARX Applications

The acad.rx file contains a list of the ObjectARX program files that are loaded automatically when you start AutoCAD. You can edit this file with a text editor or word processor that produces files in ASCII text format. You can customize this file as you want, adding to or deleting from its contents and making the appropriate ObjectARX programs available for use. As an alternative, the APPLOAD command provides a Startup Suite option that loads the specified applications without the need to edit any files.

Because AutoCAD searches for the acad.rx file in the order specified by the library path, you can have a different acad.rx file in each drawing directory. This makes specific ObjectARX programs available for certain types of drawings. For example, you might keep 3D drawings in a directory called

(33)

AcadJobs/3d_dwgs. If that directory is set up as the current directory, you could copy the acad.rx file into that directory and modify it in the following manner:

myapp1 otherapp

If you place this new acad.rx file in the AcadJobs/3d_dwgs directory and you start AutoCAD with that as the current directory, these new ObjectARX programs are then loaded and are available from the

AutoCAD prompt line. Because the original acad.rx file is still in the directory with the AutoCAD program files, the default acad.rx file will be loaded if you start AutoCAD from another directory that does not contain an acad.rx file.

You can load ObjectARX programs from an .mnl file using the arxload function. This ensures that an ObjectARX program, required for proper operation of a menu, will be loaded when the menu file is loaded.

You can also autoload many ObjectARX-defined AutoCAD commands (see Command Autoloader and "autoarxload" in the AutoLISP Reference).

acad.lsp—Automatically Load AutoLISP

The acad.lsp file is useful if you want to load specific AutoLISP routines every time you start AutoCAD. When you start AutoCAD, the program searches the library path for an acad.lsp file. If it finds one, it loads the file into memory.

The acad.lsp file is loaded at each drawing session startup when AutoCAD is launched from the Windows desktop. Because the acad.lsp file is intended to be used for application-specific startup

routines, all functions and variables defined in an acad.lsp file are only available in the first drawing. You will probably want to move routines that should be available in all documents from your acad.lsp file into the new acaddoc.lsp file.

The recommended functionality of acad.lsp and acaddoc.lsp can be overridden with the

ACADLSPASDOC system variable. If the ACADLSPASDOC system variable is set to 0 (the default setting), the acad.lsp file is loaded just once; upon application startup. if ACADLSPASDOC is set to 1, the acad.lsp file is reloaded with each new drawing.

The ACADLSPASDOC system variable is ignored in SDI (single document interface) mode. When the SDI system variable is set to 1, the LISPINIT system variable controls reinitialization of AutoLISP between drawings. When LISPINIT is set to 1, AutoLISP functions and variables are valid in the current drawing only; each time you start a new drawing or open an existing one, all functions and variables are cleared from memory and the acad.lsp file is reloaded. Changing the value of LISPINIT when the SDI system variable is set to 0 has no effect.

The acad.lsp file can contain AutoLISP code for one or more routines, or just a series of load function calls. The latter method is preferable, because modification is easier. If you save the following code as an acad.lsp file, the files mysessionapp1.lsp, databasesynch.lsp, and drawingmanager.lsp are loaded every time you start AutoCAD.

(34)

(load "databasesynch") (load "drawingmanager")

Note: Do not modify the reserved acad2000.lsp file. Autodesk provides the acad2000.lsp file, which contains AutoLISP defined functions that are required by AutoCAD. This file is loaded into memory immediately before the acad.lsp file is loaded.

acaddoc.lsp—Automatically Load AutoLISP

The acaddoc.lsp file is intended to be associated with each document (or drawing) initialization. This file is useful if you want to load a library of AutoLISP routines to be available every time you start a new drawing (or open an existing drawing). Each time a drawing opens, AutoCAD searches the library path for an acaddoc.lsp file. If it finds one, it loads the file into memory. The acaddoc.lsp file is always loaded with each drawing regardless of the settings of ACADLSPASDOC and LISPINIT.

Most users will have a single acaddoc.lsp file for all document-based AutoLISP routines. AutoCAD searches for an acaddoc.lsp file in the order defined by the library path; therefore, with this feature, you can have a different acaddoc.lsp file in each drawing directory, which would load specific AutoLISP routines for certain types of drawings or jobs.

The acaddoc.lsp file can contain AutoLISP code for one or more routines, or just a series of load

function calls. The latter method is preferable, because modification is easier. If you save the following code as an acaddoc.lsp file, the files mydocumentapp1.lsp, build.lsp, and counter.lsp are loaded every time a new document is opened.

(load "mydocumentapp1") (load "build")

(load "counter")

AutoCAD searches for an acaddoc.lsp file in the order defined by the library path; therefore, you can have a different acaddoc.lsp file in each drawing directory. You can then load specific AutoLISP routines for certain types of drawings or jobs.

Note: Do not modify the reserved acad2000doc.lsp file. Autodesk provides the acad2000doc.lsp file, which contains AutoLISP-defined functions that are required by AutoCAD. This file is loaded into memory immediately before the acaddoc.lsp file is loaded.

Menu File Types

The term menu file actually refers to the group of files that work together to define and control the appearance and functionality of the menu areas. The following table describes the AutoCAD menu file types.

(35)

AutoCAD menu files File type Description MNU Template menu file.

MNC Compiled menu file. This binary file contains the command strings and menu syntax that defines the functionality and appearance of the menu.

MNR Menu resource file. This binary file contains the bitmaps used by the menu. MNS Source menu file (generated by AutoCAD).

MNT Menu resource file. This file is generated when the MNR file is unavailable, for example, read-only.

MNL Menu LISP file. This file contains AutoLISP expressions that are used by the menu file and are loaded into memory when a menu file with the same file name is loaded.

Load Menu Files

Use the MENU command to load a new menu. Use the MENULOAD and MENUUNLOAD commands to load and unload additional menus (called partial menus) and to add or remove individual menus from the menu bar.

AutoCAD stores the name of the last loaded menu in the system registry. This name is also saved with the drawing, but it is used only for backward compatibility. When you start AutoCAD, the last menu used is loaded. As of Release 14, AutoCAD no longer reloads the menu between drawings.

AutoCAD finds and loads the specified file according to the following sequence. (This sequence is also used when AutoCAD loads a new menu with the MENU command.)

AutoCAD looks for a menu source file (MNS) of the given name, following the library search procedure.

If an MNS file is found, AutoCAD looks for a compiled menu file (.mnc) of the same name in the same directory. If AutoCAD finds a matching MNC file with the same or later date and time as the MNS file, it loads the MNC file. Otherwise, AutoCAD compiles the MNS file, generating a new MNC file in the same directory, and loads that file.

If an MNS file is not found, AutoCAD looks for a compiled menu file (.mnc) of the given name, following the library search procedure. If AutoCAD finds the MNC file, it loads that file.

If AutoCAD doesn't find either a MNS or a MNC file, it searches the library path for a menu

template file (.mnc) of the given name. If this file is found, it compiles an MNC and MNS file, then loads the MNC file.

If AutoCAD doesn't find any menu files of the given names, an error message is displayed and you are prompted for another menu file name.

After finding, compiling, and loading the MNC file, AutoCAD looks for a menu LISP file (.mnl), using the library search procedure. If AutoCAD finds this file, it evaluates the AutoLISP expressions within that file.

The acad.mnl file contains AutoLISP code used by the standard menu file, acad.mnu. The acad.mnl file is loaded each time the acad.mnu file is loaded.

(36)

Each time AutoCAD compiles an MNC file it generates a menu resource file (MNR) which contains the bitmaps used by the menu. The MNS file is an ASCII file that is initially the same as the MNU file (without comments or special formatting). The MNS file is modified by AutoCAD each time you make changes to the contents of the menu file through the interface (such as modifying the contents of a toolbar).

Although the initial positioning of the toolbars is defined in the MNU or MNS file, changes to the show/hide and docked/floating status or changes to the toolbar positions are recorded in the system registry. After an MNS file has been created, it is used as the source for generating future MNC, and MNR files. If you modify the MNU file after an MNS file has been generated, you must use the MENU command to explicitly load the MNU file so that AutoCAD will generate new MNS and MNC files and your changes will be recognized.

Note: If you use the interface to modify the toolbars, you should cut and paste the modified portions of the MNS file to the MNU file before deleting the MNS file.

The MENU command initially requests the MNS or MNC file. To reload a modified MNU file, choose the Menu Template item from the file type list, and then choose the MNU file from the list of files. Doing so protects the MNS file from accidentally being rebuilt, thus losing any toolbar or partial menu

modifications done through the interface. While building and testing a menu file, you may find this procedure awkward. The following AutoLISP routine defines a new command, MNU, which reloads the current MNU file without going through all the prompts.

(defun C:MNU ()

(command "_menu" (strcat (getvar "menuname") ".mnu")) (princ)

)

If you add this code to your acad.lsp file, the MNU command is automatically defined when you restart AutoCAD.

acad.mnl—Automatically Load AutoLISP Menu Functions

The other type of file that AutoCAD loads automatically accompanies your current menu file and has the extension .mnl. When AutoCAD loads a menu file, it searches for an MNL file with a matching file name. If it finds the file, it loads the file into memory.

This function ensures that AutoCAD loads the AutoLISP functions that are needed for proper operation of a menu. As an example, the standard AutoCAD menu, acad.mnu, relies on the file acad.mnl being loaded properly. This file defines numerous AutoLISP functions used by the menu. The MNL file is loaded after the acaddoc.lsp file.

Note: If a menu file is loaded with the AutoLISP command function (with syntax similar to (command "menu" "newmenu") ), the associated MNL file is not loaded until the entire AutoLISP routine has run. For example, if you create a custom menu called newmenu.mnu and you need to load three AutoLISP files (new1.lsp, new2.lsp, and new3.lsp) for the menu to work properly, you should create an ASCII text file named newmenu.mnl as follows:

(37)

(load "new1") (load "new2") (load "new3")

(princ "\nNewmenu utilities... Loaded.") (princ)

In this example, calls to the princ function can be used to display status messages. The first use of princ displays the following on the command line:

Newmenu utilities... Loaded.

The second call to princ exits the AutoLISP function. Without this second call to princ, the message would be displayed twice. As mentioned previously, you can include the onfailure argument with calls to the load function as an extra precaution.

S::STARTUP Function—Post-Initialization Execution

The startup LISP files (acad.lsp, acaddoc.lsp, and .mnl) all load into memory before the drawing is completely initialized. Typically, this does not pose a problem, unless you want to use the command function, which is not guaranteed to work until after a drawing is initialized.

If the user-defined function S::STARTUP is included in an acad.lsp, acaddoc.lsp or a .mnl file, it is called when you enter a new drawing or open an existing drawing. Thus, you can include a definition of

S::STARTUP in the LISP startup file to perform any setup operations.

For example, if you want to override the standard HATCH command by adding a message and then switching to the BHATCH command, use an acaddoc.lsp file that contains the following:

(defun C:HATCH ( )

(alert "Using the BHATCH command!")

(princ "\nEnter OLDHATCH to get to real HATCH command.\n") (command "BHATCH")

(princ) )

(defun C:OLDHATCH ( ) (command ".HATCH")

(38)

(princ) )

(defun-q S::STARTUP ( )

(command "undefine" "hatch")

(princ "\nRedefined HATCH to BHATCH!\n") )

Before the drawing is initialized, new definitions for HATCH and OLDHATCH are defined with the defun function. After the drawing is initialized, the S::STARTUP function is called and the standard definition of HATCH is undefined.

Note: To be appended, the S::STARTUP function must have been defined with the defun-q function rather than defun.

Because an S::STARTUP function can be defined in many places (an acad.lsp, acaddoc.lsp, .mnl file, or any other AutoLISP file loaded from any of these), it's possible to overwrite a previously defined

S::STARTUP function. The following example shows one method of ensuring that your start-up function works with other functions.

(defun-q MYSTARTUP ( )

... your start-up function ... )

(setq S::STARTUP (append S::STARTUP MYSTARTUP))

The previous code appends your start-up function to that of an existing S::STARTUP function, and then redefines the S::STARTUP function to include your start-up code. This works properly regardless of the prior existence of an S::STARTUP function.

Tips for Coding AutoLISP Startup Files

If an AutoLISP error occurs while you are loading a startup file, the remainder of the file is ignored and is not loaded. Files specified in a startup file that do not exist or that are not in the AutoCAD library path generally cause errors. Therefore, you may want to use the onfailure argument with the load function. The following example uses the onfailure argument:

(princ (load "mydocapp1" "\nMYDOCAPP1.LSP file not loaded.")) (princ (load "build" "\nBUILD.LSP file not loaded."))

(39)

(princ)

If a call to the load function is successful, it returns the value of the last expression in the file (usually the name of the last defined function or a message regarding the use of the function). If the call fails, it returns the value of the onfailure argument. In the preceding example, the value returned by the load function is passed to the princ function, causing that value to be displayed on the command line. For example, if an error occurs while AutoCAD loads the mydocapp1.lsp file, the princ function displays the following message and AutoCAD continues to load the two remaining files:

MYDOCAPP1.LSP file not loaded.

If you use the command function in an acad.lsp, acaddoc.lsp or MNL file, it should be called only from within a defun statement. Use the S::STARTUP function to define commands that need to be issued immediately when you begin a drawing session. The S::STARTUP function is described in S::STARTUP Function—Post-Initialization Execution.

Command Autoloader

When you automatically load a command using the load or command functions, the command's definition takes up memory whether or not you actually use the command. The AutoLISP autoload function makes a command available without loading the entire routine into memory. Adding the

following code to your acaddoc.lsp file automatically loads the commands CMD1, CMD2, and CMD3 from the cmds.lsp file and the NEWCMD command from the newcmd.lsp file.

(autoload "CMDS" '("CMD1" "CMD2" "CMD3")) (autoload "NEWCMD" '("NEWCMD"))

The first time you enter an automatically loaded command at the Command prompt, AutoLISP loads the entire command definition from the associated file. AutoLISP also provides the autoarxload function for ObjectARX applications. See "autoload" and "autoarxload" in the AutoLISP Reference.

acadvba.arx—Automatically Load VBA

You cannot load VBA until an AutoCAD VBA command is issued. If you want to load VBA automatically every time you start AutoCAD include the following line in the acad.rx file:

acadvba.arx

You can automatically run a macro in the acad.dvb file by naming the macro AcadStartup. Any macro in your acad.dvb file called AcadStartup automatically executes when VBA loads.

acad.dvb—Automatically Load a VBA Project

AutoLisp

The

AutoLisp

Tutorials

Contents

The Basics in a Nutshell

Loading AutoLISP Files.

AutoCAD and Customizable Support Files