226 AutoCAD Developer's Guide to Visual LISP

6
he Visual LISP environment was introduced into AutoCAD 2000 to fa-

cilitate the process of AutoLISP programming and debugging. Fig. 3.1

shows the Visual LISP for AutoCAD window that appears when the user

enters the VLISP command on the command line. Another form of this command

is VLIDE. The same window is displayed if you choose Visual LISP Editor from

the AutoLISP item of the Tools menu.

Fig. 3.1. The Visual LISP for AutoCAD window

The Visual LISP for AutoCAD window is an entire shell within AutoCAD, with its

own menus and toolbars. The toolbars can be docked into fixed positions (Fig. 3.1)

or float like in Fig. 3.2.

The working area contains windows for opening text files, the Visual LISP Console

for connection with AutoCAD, and the Trace window for program debugging. The

types of editable files are: LISP program files, dialog boxes’ DCL files, database

handling SQL files, and C program files.

 Chapter 3: The Visual LISP Environment 227

Fig. 3.2. Floating toolbars in the Visual LISP for AutoCAD window

3.1. A Review of the Visual LISP Menus

The Visual LISP environment includes 9 menus: File, Edit, Search, View, Project,
Debug, Tools, Window, and Help. All of them contain both fixed items and ones

that change their contents or disappear, depending on the program development

context.

3.1.1. The File Menu

The File menu (Fig. 3.3) is intended for file-handling operations. It includes the

items:

r New File r Save All r Print Setup

r Open File r Close r Make Application

r Reopen r Revert r Load File

r Save r Close All r Exit

r Save As r Print
 228 AutoCAD Developer's Guide to Visual LISP

The name of an item implies its purpose. The Revert item lets you restore the

contents of the file in the active window, just like the Reopen item. The Make
Application item is discussed in Section 3.4.3.

Fig. 3.3. The File menu

3.1.2. The Edit Menu

The Edit menu (Fig. 3.4) includes these items:

r Undo r Copy r Select All

r Redo r Paste r Parentheses Matching

r Cut r Delete r Extra Commands

Fig. 3.4. The Edit menu

 Chapter 3: The Visual LISP Environment 229

The first 7 items of the menu are typical for a Windows 95/98 application. The

Parentheses Matching item controls the following edit operations:

r Match Forward r Select Forward

r Match Backward r Select Backward

The first 2 operations find in the text the parenthesis (either closing or opening)

that matches the one immediately after or before the cursor. The last 2 operations

perform similar tasks, but highlight the text inside the parentheses as well.

3.1.3. The Search Menu

The Search menu (Fig. 3.5) is used for Visual LISP text editor operations (in par-

ticular, search and replace). It contains:

r Find r Bookmarks

r Replace r First Message

r Find/Replace Next r Next Message

r Complete Word by Match r Go to Line

r Complete Word by Apropos r Go to Last Edited

Fig. 3.5. The Search menu

Fig. 3.6. Using Complete Word by Apropos

 230 AutoCAD Developer's Guide to Visual LISP

Let's talk about the items that are not quite as self-evident. After choosing the

Complete Word by Match item, the Visual LISP editor finishes an already-begun

word using as a guide the last word found in the current window of the program

being edited that has a similar beginning. Complete Word by Apropos offers word

endings from the AutoLISP symbol list, which includes the built-in function

names (Fig. 3.6).

Bookmarks are useful for navigation through the text. To set a bookmark, to re-

move it, and to move to another bookmark, use the Toggle Bookmark, Next
Bookmark, Previous Bookmark, and Clear All Bookmarks operations from the

Bookmarks item. The Select to Next Bookmark and Select to Previous Bookmark
operations of the same item ease the task of selecting large portions of text.

3.1.4. The View Menu

The View menu (Fig. 3.7) is intended for viewing auxiliary information while a LISP

program runs, and for work with toolbars of the Visual LISP for AutoCAD window.

There are the following items in the menu:

r Inspect r Breakpoints Window

r Trace Stack r Output Window

r Error Trace r LISP Console

r Symbol Service r Browse Drawing Database

r Watch Window r Toolbars

r Apropos Window

Fig. 3.7. The View menu

 Chapter 3: The Visual LISP Environment 231

The Inspect item allows you to call special Inspect windows, which display the

state of variables, lists, selection sets, entities, and AutoLISP expressions.

The name of an object to inspect (or an expression) should be selected in the pro-

gram text beforehand. If nothing has been selected, a name is requested before

opening the next Inspect window. An example of an opened Inspect window is

given in Fig. 3.8; it displays a list of the circle’s properties.

Fig. 3.8. An Inspect window

The Trace Stack item displays a window of the same name. The last operations

performed are listed in this window (Fig. 3.9).

The buttons below the window title bar are:

r Refresh — clears the window contents

r Copy to Trace/Log — copies the text to a special Trace window, which, like

a protocol, accumulates information concerning the debugging of the program.

If you select a line in the Trace stack window, right-clicking on it will get you a

context menu with additional operations that can be performed on the trace stack

elements: Inspect, Print, Function Symbol, Copy, Local Variables, Source Posi-
tion, and Call Point Source (the context menu size can vary).

Fig. 3.9. The Trace stack window

 232 AutoCAD Developer's Guide to Visual LISP

Fig. 3.10. The Error trace window

The Error Trace item in the View menu displays a window of the same name

(Fig. 3.10) that informs you of program errors.

After selecting a line in the Error trace window, a context menu for getting addi-

tional information on the window element can be obtained by right-clicking. The

context menu includes the same items as the one in the Trace stack window. Fig.

3.11 shows an example of an additional window invoked by the Show Message

item of the context menu for the SYNTAX-ERROR line.

The Symbol Service item of the View menu opens a window of the same name

(Fig. 3.12). The window functions similar to the Inspect one, but for AutoLISP symbols.

Fig. 3.11. An Info dialog box providing additional information on an error

There are 2 fields in the window, Name and Value, as well as the Flags group of

checkboxes. The fields names are self-explanatory (symbol name and value), and

the Flags group consists of 4 boxes that can be checked (or unchecked) for the

selected symbol :

r Trace

r Debug on Entry (debugging upon entering a function)

r Protect Assign (protects special symbols from random assignments, for in-

stance, T, pi, etc.)

r Export to AutoCAD (exports a function to AutoCAD to make it accessible for

ObjectARX applications)
 Chapter 3: The Visual LISP Environment 233

Fig. 3.12. The Symbol Service dialog box

The Symbol Service window has 4 buttons under its title bar (left to right):

r Watch — adds the symbol to the Watch window

r Inspect — opens the Inspect window for the symbol

r Show Definition — calls a text editor window, and highlights in it the text of

a symbol that is a user function

r Help — calls Visual LISP Help for a symbol that is a built-in function

The Watch Window item of the View menu displays the Watch window (Fig. 3.13).

Fig. 3.13. The Watch window

This window displays the values of selected symbols while the program is being

executed. Symbols can be added to this window either with the Watch button of

the Symbol Service window, or with the Add Watch button in the Watch window.

The buttons in the Watch window are:

r Add Watch r Sort Expressions

r Clear Window r Copy to Trace/Log

 234 AutoCAD Developer's Guide to Visual LISP

The Apropos Window item of the View menu displays on screen the Apropos
options dialog box (Fig. 3.14).

Fig. 3.14. The Apropos options dialog box

The window lets you view the list of protected symbols (primarily, the built-in

function names). The list of names to display is formed basing on the sequence

of letters entered in the upper field (in Fig. 3.14, the only letter f is entered); the

letters must appear in all the symbol names on the list. The user can indicate with

checkbox whether the names must start with the sequence or just contain it, and

whether wildcard characters like * or # may be used, as in the wcmatch function

(see Section 2.8.8 ). Fig. 3.15 depicts the Apropos results window with symbols that have

the prefix F.

The Breakpoints Window item of the View menu opens the Breakpoints dialog box

(Fig. 3.16) which is used for program debugging.

The Output Window item opens the <Build Output> window for output of mes-

sages generated when developing applications (Fig. 3.17).

The LISP Console item of the View menu invokes the very important Visual LISP
Console window (Fig. 3.18). In Visual LISP, this window is analogous to the

AutoCAD command window. The Console is used to enter AutoLISP expressions,

to load and execute functions, and to retrieve values of variables. This is also where

Visual LISP displays its messages.

The Browse Drawing Database item of the View menu includes the sub-

items: Browse All Entities, Browse Tables, Browse Blocks, Browse Selection, and

Inquire Extended Data; when selected, they call the respective windows
 Chapter 3: The Visual LISP Environment 235

for browsing databases of graphical and non-graphical entities of the current

drawing (Fig. 3.19).

Fig. 3.15. The Apropos results window

Fig. 3.16. The Breakpoints dialog box

236 AutoCAD Developer's Guide to Visual LISP

Fig. 3.17. The Build Output window

Fig. 3.18. The Visual LISP Console window

Fig. 3.19. Drawing database browse windows

 Chapter 3: The Visual LISP Environment 237

The Toolbars item of the View menu calls the Toolbars dialog box (Fig. 3.20),

which controls the visibility of the 5 Visual LISP environment toolbars.

Fig. 3.20. The Toolbars dialog box

The checkboxes in this window should be checked for any of the 5 toolbars

Standard, Search, Tools, Debug,

( and View) that you want to have displayed.

Changes can be made using the Hide All, Show All, and Apply buttons. The Close
button closes the Toolbars dialog box.

3.1.5. The Project Menu

The Project menu (Fig. 3.21) enables you to work with projects.

A project is a group of LISP programs combined into one application. That appli-

cation runs in the AutoCAD environment and is compiled into one file with the

FAS extension (there can be a FAS file created for each of the programs, although

it is not very convenient). Such an application is called a FAS application.

Fig. 3.21. The Project menu

 238 AutoCAD Developer's Guide to Visual LISP

The Project menu consists of the following items:

r New Project r Load Project FAS File

r Open Project r Load Project Source Files

r Close Project r Build Project FAS

r Project Properties r Rebuild Project FAS

These items are discussed in Section 3.4.2. The last lines in the menu show the

names of open projects, with the active project name checked.

3.1.6. The Debug Menu

The Debug menu (Fig. 3.22) serves to debug programs in the Visual LISP envi-

ronment.

Fig. 3.22. The Debug menu

The menu includes the items:

r Step Into r Reset to Top Level r Watch Last Evaluation

r Step Over
r Quit Current Level r Toggle Breakpoint
r Step Out
r Add Watch r Clear All Breakpoints
r Continue
 Chapter 3: The Visual LISP Environment 239

r Last Break Source r Stop Once r Animate

r Trace Command r Break On Error r Abort Evaluation

These items along with their corresponding operations are covered in Section 3.4.1.

3.1.7. The Tools Menu

The Tools menu (Fig. 3.23) is intended for auxiliary operations.

If the Visual LISP Console window is active in the Visual LISP environment, then

the Tools menu has the following items:

r AutoCAD Mode r Environment Options

r Window Attributes r Save Settings

Fig. 3.23. The Tools menu (the first option)

Fig. 3.24. The Color Style dialog box

The AutoCAD Mode item turns the mode that uses the Visual LISP Console win-

dow as an AutoCAD command line on or off (the Command : prompt appears).

This gives you the ability to enter AutoCAD commands in the console window.

If the mode is set to on, this menu item will have a checkmark to its left.

The Window Attributes item includes:

r Syntax Coloring r Set All Windows to Prototype

r Configure Current r Font

r Set Current Window to Prototype

 240 AutoCAD Developer's Guide to Visual LISP

Syntax Coloring is only available if there is a file with an extension other than LSP

in the active window. The Color Style dialog box is called (Fig. 3.24 shows

this dialog box for a DCL file), which allows you to choose one of the predefined

text editor color styles. We shall discuss text editor color styles in more detail in

Section 3.3.1.

Configure Current opens the Window Attributes dialog box (Fig. 3.25), where you

can correct the color settings for text elements. The elements are listed in a drop-

down list box.

Set Current Window to Prototype changes the active window settings to the pro-

totype ones; Set All Windows to Prototype performs the same operation on all

windows.

Fonts invokes the standard Font dialog box, offering a choice of fonts to be used in

windows (Fig. 3.26).

Fig. 3.25. The Window Attributes dialog box

The Environment Options item of the Tools menu contains:

r General Options

r Visual LISP Format Options

r Page Setup Options

The first, General Options, calls the General Options dialog box, which controls

Visual LISP environment settings. The dialog box has 2 tabs: General (Fig. 3.27)

and Diagnostic (Fig. 3.28).

 Chapter 3: The Visual LISP Environment 241

Fig. 3.26. The Font dialog box

Fig. 3.27. The General Options dialog box, General tab

The second point of the Environment Options item , Visual LISP Format Options,
opens the Format options dialog box (Fig. 3.29) for Visual LISP text editor format

settings.
 242 AutoCAD Developer's Guide to Visual LISP

Fig. 3.28. The General Options dialog box, Diagnostic tab

Fig. 3.29. The Format options dialog box

Page Setup Options, the third point of the Environment Options item, opens the

Page Setup dialog box for printing Visual LISP texts (Fig. 3.30).
 Chapter 3: The Visual LISP Environment 243

Fig. 3.30. The Page Setup dialog box

The Save Settings item of the Tools menu saves the Visual LISP desktop settings

(the windows last opened, window settings, etc.). To allow for automatic saving,

check the appropriate checkboxes from the DESKTOP group in the General
Options dialog box, General tab (Fig. 3.27).

If the active window of the Visual LISP environment is one that contains a pro-

gram text, the Tools menu will contain these extra items (Fig. 3.31):

r Load Selection r Format code in Selection

r Load Text in Editor r Format code in Editor

r Check Selection r Interface Tools

r Check Text in Editor

Fig. 3.31. The Tools menu (the second option)

 244 AutoCAD Developer's Guide to Visual LISP

The first 6 of these allow you to load for execution, to check, and to format either a pro-

gram text or a selected portion of one. More details are given in Sections 3.3.2 and 3.4.1.
The Interface Tools item includes:

r Preview DCL in Selection

r Preview DCL in Editor

These two load an edited DCL file or a selected portion of one for execution.

3.1.8. The Window Menu

The Window menu (Fig. 3.32) is typical for a Windows application. It controls the

positioning of Visual LISP windows.

The Activate AutoCAD item minimizes the Visual LISP for AutoCAD window; the

main AutoCAD window becomes available temporarily (for instance, for drafting

in a drawing). At the bottom of the Window menu is a list of opened windows,

with the active one checked.

Fig. 3.32. The Window menu

3.1.9. The Help Menu

The 2-item Help menu is the last menu (Fig. 3.33); it is intended to provide information.

Fig. 3.33. The Help menu

 Chapter 3: The Visual LISP Environment 245

3.2. Review of the Visual LISP Toolbars

There are 5 toolbars in the Visual LISP environment:

r Standard r Tools r View

r Search r Debug

As you can see, the names of the toolbars are similar to the names of the menus

we have just discussed. Their usage is similar too.

3.2.1. The Standard Toolbar

The Standard toolbar (Fig. 3.34) has the following buttons (left to right):

r New file r Cut r Redo

r Open file r Copy r Complete word

r Save file r Paste

r Print r Undo

Fig. 3.34. The Standard toolbar

The first 9 buttons are the same as the respective AutoCAD Standard toolbar but-

tons. The last, the Complete word button, corresponds to the Complete Word by
Apropos item of the Search menu; it allows you to complete a word you have be-

gun to type with appropriate matches from the standard symbols list.

3.2.2. The Search Toolbar

The Search toolbar (Fig. 3.35) has duties similar to those of the Search menu.

Fig. 3.35. The Search toolbar

The toolbar consists of 7 buttons:

r Find r Next bookmark

r Replace r Previous bookmark

r Find toolbar string r Clear all bookmarks

r Toggle bookmark
 246 AutoCAD Developer's Guide to Visual LISP

All the buttons but the 3

rd give access to the same operations as their counterparts

in the Search menu. The Find toolbar string button co-operates with a drop-down

list found in the Search toolbar; it searches for a symbol whose name has been

chosen from the list or added to it from the keyboard.

3.2.3. The Tools Toolbar

The Tools toolbar (Fig. 3.36) has 9 buttons:

r Load active edit window r Format selection

r Load selection r Comment block

r Check edit window r Uncomment block

r Check selection r Help

r Format edit window

Fig. 3.36. The Tools toolbar

The first 6 buttons do the same as the first 6 Tools menu items when the user edits

a program text or a fragment of one (see Fig. 3.31).

The Comment block and Uncomment block buttons allow you to easily make or

delete a comment on selected lines of text in a program (using a semicolon).

The Help button provides Help information.

3.2.4. The Debug Toolbar

The Debug toolbar (Fig. 3.37) has the buttons:

r Step into r Continue r Toggle breakpoint

r Step over r Quit r Add watch

r Step out r Reset r Last break

Fig. 3.37. The Debug toolbar

 Chapter 3: The Visual LISP Environment 247

Besides, one more button appears on the toolbar when you run a program in the

debug mode with breakpoints (this button is shown in Fig. 3.37, but in normal

mode it is not visible). The button indicates where the cursor is during the current

break (before the parentheses or after them).

Program debugging modes are discussed in Section 3.4.1.

3.2.5. The View Toolbar

The View toolbar (Fig. 3.38) contains the buttons:

r Activate AutoCAD r Inspect r Apropos

r Select window r Trace r Watch window

r Visual LISP Console r Symbol service

Fig. 3.38. The View toolbar

As the button names indicate, these are the same operations we encountered when

talking about the pull-down menus: AutoCAD Mode from the Tools menu;

choosing a window using the windows list from the Window menu; LISP Console,
Inspect, Trace Stack, Symbol Service, Apropos Window, and Watch Window from

the View menu.

3.3. The Visual LISP Text Editor

In the Visual LISP environment, you can create, open, and edit text files of the

following types in a separate window using the New File and Open File items of

the File menu:

r LISP programs (LSP extension)

r dialog box DCL files (DCL extension)

r database operation SQL files (SQL extension)

r C++ programs (C, CPP extensions)

The text editor included in the environment essentially facilitates writing files of

these types. From the very first input of text, it checks the syntax, indicating pa-

rentheses, operators, operands, comments, etc., in a different color font. The parse

results are displayed in the same color as the text at issue.

 248 AutoCAD Developer's Guide to Visual LISP

3.3.1. Text Editor Settings

The Visual LISP text editor color settings can be defined (with respect to the file

type) using the Syntax Coloring option of the Window Attributes item from the

Tools menu (Fig. 3.24). By default, the editor is set to work with LISP program

texts.

The colors normally applied for LISP program parsing are the following:

r blue — AutoLISP protected symbols (built-in function names, etc.)

r magenta — quoted text strings

r green — integers and real numbers

r magenta on gray — comments

r red — opening and closing parentheses

r black — all the rest (user-defined variables, etc.)

Fig. 3.39 shows a text editor window with a portion of a LISP source code colored

in a standard color scheme (comments have a dark background).

Fig. 3.39. The text editor dialog window

 Chapter 3: The Visual LISP Environment 249

You can change the colors to fit your preferences with the Configure Current op-

tion of the Window Attributes item in the Tools menu (see Fig. 3.25).

The Environment Options item of the Tools menu (see Section 3.1.6 ) can also help

to make a large number of changes to accommodate the desires of a user.

3.3.2. Using Text Editor

In a text that you edit in the Visual LISP environment you can highlight blocks of

text. To do so, drag the mouse over the text with its left button pressed, or use the

keyboard combinations <Shift>+<Left>, <Shift>+<Right>, <Shift>+<Up>, and

<Shift>+<Down> just like in Microsoft Word.

The Comment block and Uncomment block buttons of the Tools toolbar are ex-

tremely convenient for quickly commenting on a selected portion of text, or can-

celing the comment altogether.

The text of a whole file or a selected portion of it can be checked for syntax errors

using the Check Selection or Check Text in Editor items of the Tools menu, or the

analogous buttons of the Tools toolbar.

The Parentheses Matching item of the Edit menu is good for checking to make

sure every parenthesis has its complement.

When saving an edited LSP file, Visual LISP reserves a backup copy under the

original name (the copy has the extension _LS).

3.4. Application Design

Visual LISP simplifies the creation of entire applications rather than detached pro-

grams. In Section 3.4.2, the project tools that allows you to create applications

consisting only of LSP files (FAS applications) is discussed. If an application needs

to contain dialog box DCL files or auxiliary text files, use a tool for complex ap-

plication design (VLX applications, see Section 3.4.3 ). Means of debugging are

covered in Section 3.4.1.

3.4.1. Program Loading and Debugging

In the Visual LISP environment, the special Visual LISP Console window plays

the same role for the user as the AutoCAD command window. In the Console
 250 AutoCAD Developer's Guide to Visual LISP

window, you can enter AutoLISP expressions and load and execute functions. Vis-

ual LISP and AutoCAD messages are displayed in this window too.

If you have an open LISP program file in the text editor current window, you can

load it (just as you would load a file with the AutoLISP load function) by selecting

the Load Text in Editor item of the Tools menu, or by pressing the Load active

edit window button of the Tools toolbar. Shown in Fig. 3.40 is a file load message

generated by Visual LISP.

A program can be run in the step mode, with the user selecting and loading text

fragments one by one. To do so, use the Load Selection item from the Tools menu

or the corresponding button on the Tools toolbar.

The Visual LISP Console window user prompt is _$ . So, if, for example, you have

loaded a rcl.lsp file with a program of the same name in the previous step, you can

execute it by entering

(rcl)
in the console window.

Visual LISP will execute the program, and if it contains no errors, will display the

result in the console window (Fig. 3.41).

Global variable values can be read from the console directly. If you type a variable

name at the console prompt, Visual LISP will indicate its current value (Fig. 3.42

shows the value of the list_rad variable).

NOTE
To read a variable value in Visual LISP, unlike in AutoCAD, you don’t have to precede

the variable name with an exclamation mark (see Section 2.1.2).

Fig. 3.40. A file load message in the Visual LISP Console window
 Chapter 3: The Visual LISP Environment 251

Fig. 3.41. A file execution message in the Visual LISP Console window

Fig. 3.42. Reading a global variable value in the Visual LISP Console window

When debugging a program, it’s convenient to trace the values of selected vari-

ables. The Inspect, Symbol Service, and Watch Window items we talked about

when discussing the View menu show the corresponding windows (see Figs. 3.8,

3.12, and 3.13), where the current values of selected variables or expressions are

indicated. The contents of these windows can be copied to the Trace window for

subsequent summarizing.

In case of errors, use the Trace Stack and Error Trace items, which display win-

dows of the same name (see Figs. 3.9 and 3.10).

Setting program breakpoints is an effective debugging tool. It is realized with the

use of the Toggle breakpoint item of the Debug menu, or the button of the same

name from the Debug toolbar. Upon reaching a breakpoint, the program pauses

for user directions for further execution. To continue, use the Step Into, Step
Over, Step Out, Continue, Reset to Top Level, or Quit Current Level item of the

Debug menu, or the corresponding buttons from the Debug toolbar.

Combining breakpoints with an open Watch window (Fig. 3.13) is particularly ef-

fective. Executing your program portion by portion, you can keep an eye on the

monitored variables.
 252 AutoCAD Developer's Guide to Visual LISP

The Animation item of the Debug menu allows you to trace program execution

along the source text; Visual LISP will highlight the program expressions being

executed at the moment.

3.4.2. Projects
A number of jointly executed LISP programs can be grouped into a project. Every

such project is an independent application; it can work in the form of source texts

or in the form of compiled files (with the FAS extension). Besides, all the files of

a project can be compiled into one FAS application file, which is preferable con-

sidering the time it takes to load and execute.

Project operations are grouped in the Project menu. A new project can be created

using the New Project item, which opens the New project... window (Fig. 3.43).

Fig. 3.43. A New project… window

The name for the project data file should be entered in this window. The file is

created automatically. It keeps information on the project’s programs and compi-

lation modes. The project file extension is PRJ. After the project name is entered,

a Project properties dialog box appears (Fig. 3.44).

This dialog box has 2 tabs: Project Files and Build Options. In the first one,

choose the LSP files folder for the Look in field; from the list of found files that

appears, transfer the names of the necessary files to the right side using the > but-

ton. If the project files are collected in more than one folder, you can change the

folder name to retrieve the next portion of files to be included. Right-clicking on

 Chapter 3: The Visual LISP Environment 253

a file name produces a context menu, whose Log filenames and size item displays

in the lower part of the dialog box the full name and the size of each selected file

(Fig. 3.45).

When a complete list of the new project components is formed, it can be arranged

with the use of the Top, Up, Down, and Bottom buttons. Normally, such a rear-

ranging is not necessary; however, sometimes it is essential (for example, if there

are special initialization files, they must be put on the top in order to be loaded

first).

The Build Options tab of the Project properties dialog box (Fig. 3.46) defines the

modes for compiling and linking. In particular, the Merge files mode determines

whether every LSP file will result in a FAS file, or whether the whole project will

be compiled into one file (a FAS application). The folders for storing FAS files

and temporary files can be defined here as well.

When you have finished, click the Apply button. The OK button closes the dialog

box, and the window of the opened project appears on the screen. Fig. 3.47 con-

tains an example of a newp project consisting of 3 files.

Fig. 3.44. The Project properties dialog box, Project Files tab
254 AutoCAD Developer's Guide to Visual LISP

Fig. 3.45. The project files’ full names and sizes

Fig. 3.46. The Project properties dialog box, Build Options tab
 Chapter 3: The Visual LISP Environment 255

Fig. 3.47. A project window

There are 5 project operation buttons in the upper part of the window (left to

right):

r Project Properties r Build Project FAS

r Load Project FAS r Rebuild Project FAS

r Load Source Files

The button names are analogous to the Project menu item names. Formerly cre-

ated projects can be modified, and loaded either already compiled or as source

code.

3.4.3. VLX Applications

Another type of application is a VLX application, which can include:

r LSP files

r Dialog box DCL files (for dialog box design, see Chapter 5)

r FAS files (LISP program or compiled project files)

r DVB files (applications created in the Visual Basic for Applications environ-

ment)

r TXT files (text files)

All included components are grouped into one application file with the VLX ex-

tension. The application properties are kept in the file of the same name with the

PRV extension used for application rebuilding.

To create a new complex application, use the Make Application item of the File
menu. The item includes:

r New Application Wizard r Make Application

r Existing Application Properties r Rebuild Application

 256 AutoCAD Developer's Guide to Visual LISP

To create a new application, choose New Application Wizard, which opens the

Wizard Mode dialog box (Fig. 3.48).

The mode determining the application type, Simple or Expert, should be set in

this window. A simple application can consist of LISP program files only (resem-

bling a FAS application); an expert one can include DCL files, DVB files, etc.

Fig. 3.48. The Wizard Mode dialog box

Let’s look at an example of creating an expert application. After we choose the

Expert option and click the Next button, the Application Directory dialog box is

opened (Fig. 3.49).

Fig. 3.49. The Application Directory dialog box

 Chapter 3: The Visual LISP Environment 257

The Application Name field should be filled in here (the Target File panel will form

the new application name with the VLX extension), and in the Application Location
field you should put the full name of the folder where the application file (with the

extension VLX) and the application property file (extension PRV — the base of the

file name is inherited from the application name) will reside. The folder can be also

chosen using the Browse button. After the parameters are set and the Next button is

pressed, we proceed to the Application Options dialog box (Fig. 3.50).

Fig. 3.50. The Application Options dialog box

By default, the Separate Namespace checkbox is not checked in this dialog box.

This means that the functions and global variables of your application will be avail-

able for other applications. If our application had nothing to do with the other

ones, we would check the checkbox to eliminate compatibility problems.

NOTE
Although a VLX application is created with a separate namespace, it is still possible to
export its functions to a document namespace with the use of the vl-doc-export func-
tion; its global variables can be exported with the vl-doc-set function. There is also

the possibility of function and variable import from the document into a VLX application
namespace (see Section 2.17.32).

If the Separate Namespace checkbox is checked, the user has access to the

ActiveX Support checkbox (by default, the support is enabled).

Another dialog box, LISP Files to Include (Fig. 3.51), is for describing all files

with extensions LSP (source code), FAS (compiled files), and PRV (project files)

that should be integrated in the application being created.

 258 AutoCAD Developer's Guide to Visual LISP

The Add and Remove buttons let you add and remove components. The order of

including LISP program elements in the application is controlled by the Top, Up,

Down, and Bottom buttons. There is a drop-down list of 3 lines: LISP source files,

Compiled LISP files, and Visual LISP project files, which assists in adding com-

ponents of the proper type to an application.

The next dialog box is Resource Files to Include (Fig. 3.52); it will not appear

if the Simple application mode has been selected (Fig. 3.48).

Fig. 3.51. The LISP Files to Include dialog box

Fig. 3.52. The Resource Files to Include dialog box

 Chapter 3: The Visual LISP Environment 259

Elements from the drop-down list can be added to the application as supplementary

resources (the first 3 types could have been selected in the previous dialog box):

r LISP source files r DCL files

r Compiled LISP files r DVB files

r Visual LISP project files r Text files

DCL files are dialog box files, the structure of which is discussed in Chapter 5. DVB
files are application files created in the Visual Basic for Applications language (the

design of these applications is a subject for a separate book). Text files are any text

files with the TXT extension where the user keeps subsidiary information that the

application may occasionally need.

After defining all supplementary resources we proceed to the next window — the

Application Compilation Options dialog box (Fig. 3.53).

Fig. 3.53. The Application Compilation Options dialog box

In this dialog box we have to choose either the Standard or the Optimize and Link
compilation mode. Optimization decreases the amount of object code and applica-

tion load time; however, improper use of protected symbols can cause the applica-

tion or AutoCAD to function incorrectly.

The Review Selections / Build Application dialog box (Fig. 3.54) is the last one the

New Application Wizard provides access to.

If in this dialog box we leave the Build Application checkbox checked and click

the Finish button, Visual LISP will create an application file (extension VLX)
 260 AutoCAD Developer's Guide to Visual LISP

and an application property file (extension PRV). If we uncheck Build Application

and click Finish, only the PRV file will be created. To build the application with

this file later, choose Make Application from the same item of the File menu.

Fig. 3.54. The Review Selections / Build Application dialog box

Existing Application Properties of the Make Application item lets you review and

modify the application’s options or composition, while Rebuild Application under

the same item lets you recompile the application after some of its components

(DCL files, LSP files, etc.) have been modified.

3.4.4. Loading Applications

In the Visual LISP environment, an already-built application can be loaded in the

console with the use of the load AutoLISP function, or the Load File item from

the File menu.

If an application needs to be loaded in the AutoCAD session without a Visual

LISP environment, use either the load function, or Load from the AutoLISP item

of the Tools AutoCAD menu, or the Load Application item of the same menu,

which will all open the Load/Unload Applications dialog box (Fig. 3.55).

If you wish your application to be loaded automatically at AutoCAD startup or

when the drawing is opened, add the corresponding AutoLISP line in the acad.lsp

or acaddoc.lsp file; for example:

(load “rcl.vlx”)
 Chapter 3: The Visual LISP Environment 261

Your rcl.vlx application will be loaded when loading the file you modified (acad.lsp

or acaddoc.lsp). The acaddoc.lsp file is auto-loaded upon opening every drawing

(drawings are AutoCAD documents), and the acad.lsp file is loaded on AutoCAD

startup. To provide access for AutoCAD to your acad.lsp and acaddoc.lsp files,

include their prefixes in the Support File Search Path (see Section 1.3 ), or place

the files in the AutoCAD working directory that is defined in the settings of the

AutoCAD shortcut on the Windows desktop (see Section 1.4 ).

Fig. 3.55. The Load/Unload Applications dialog box

If you have to have your application both auto-loaded and auto-run, add one more

line calling your application’s main function to the acad.lsp or acaddoc.lsp file, for

example:

(rcl)
Another way of automatically loading is to use the autoload function (see

Section 2.17 ).
 262 AutoCAD Developer's Guide to Visual LISP

The most convenient auto-load method is to enter the application names in a spe-

cial portfolio. In the right lower part (Fig. 3.55) of the Load/Unload Applications
dialog box you’ll find Startup Suite, which could be called an auto-load portfolio.
Clicking the Contents button, the Startup Suite dialog box opens (Fig. 3.56).

Using the Add button in this dialog box, you can add to the startup list the names

of application files that must auto-run at AutoCAD startup. The Remove button

excludes selected files from the startup list.

Fig. 3.56. The Startup Suite dialog box