Vlispdev
Vlispdev
Vlispdev
AUTODESK, INC. 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 AUTODESK, INC. 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 AUTODESK, INC., REGARDLESS OF THE FORM OF ACTION, SHALL NOT EXCEED THE
PURCHASE PRICE OF THE MATERIALS DESCRIBED HEREIN.
Autodesk, Inc. reserves the right to revise and improve its products as it sees fit. This publication describes the state of this product
at the time of its publication, and may not reflect the product at all times in the future.
Autodesk Trademarks
The following are registered trademarks of Autodesk, Inc., in the USA and/or other countries: 3D Plan, 3D Props, 3D Studio, 3D
Studio MAX, 3D Studio VIZ, 3DSurfer, ActiveShapes, Actrix, ADE, ADI, Advanced Modeling Extension, AEC Authority (logo), AEC-
X, AME, Animator Pro, Animator Studio, ATC, AUGI, AutoCAD, AutoCAD Data Extension, AutoCAD Development System,
AutoCAD LT, AutoCAD Map, Autodesk, Autodesk Animator, Autodesk (logo), Autodesk MapGuide, Autodesk University,
Autodesk View, Autodesk WalkThrough, Autodesk World, AutoLISP, AutoShade, AutoSketch, AutoSurf, AutoVision, Biped,
bringing information down to earth, CAD Overlay, Character Studio, Design Companion, Drafix, Education by Design, Fire,
Flame, Flint, Frost, Generic, Generic 3D Drafting, Generic CADD, Generic Software, Geodyssey, Heidi, HOOPS, Hyperwire,
Inferno, Inside Track, Kinetix, MaterialSpec, Mechanical Desktop, Mountstone, Multimedia Explorer, NAAUG, ObjectARX, Office
Series, Opus, PeopleTracker, Physique, Planix, Powered with Autodesk Technology, Powered with Autodesk Technology (logo),
RadioRay, Rastation, Riot, Softdesk, Softdesk (logo), Solution 3000, Stone, Stream, Tech Talk, Texture Universe, The AEC
Authority, The Auto Architect, TinkerTech, Vapour, VISION, WHIP!, WHIP! (logo), Wire, Woodbourne, WorkCenter, and World-
Creating Toolkit.
The following are trademarks of Autodesk, Inc., in the USA and/or other countries: 3D on the PC, ACAD, Advanced User Interface,
AEC Office, AME Link, Animation Partner, Animation Player, Animation Pro Player, A Studio in Every Computer, ATLAST, Auto-
Architect, AutoCAD Architectural Desktop, AutoCAD Architectural Desktop Learning Assistance, AutoCAD Learning Assistance,
AutoCAD LT Learning Assistance, AutoCAD Simulator, AutoCAD SQL Extension, AutoCAD SQL Interface, Autodesk Animator
Clips, Autodesk Animator Theatre, Autodesk Device Interface, Autodesk Inventor, Autodesk PhotoEDIT, Autodesk Software
Developer's Kit, Autodesk View DwgX, AutoFlix, AutoPAD, AutoSnap, AutoTrack, Built with ObjectARX (logo), ClearScale,
Combustion, Concept Studio, Content Explorer, cornerStone Toolkit, Dancing Baby (image), Design 2000 (logo), DesignCenter,
Design Doctor, Designer's Toolkit, DesignProf, DesignServer, Design Your World, Design Your World (logo), Discreet, DWG
Linking, DWG Unplugged, DXF, Extending the Design Team, FLI, FLIC, GDX Driver, Generic 3D, Heads-up Design, Home Series,
Kinetix (logo), Lightscape, ObjectDBX, onscreen onair online, Ooga-Chaka, Photo Landscape, Photoscape, Plugs and Sockets,
PolarSnap, Pro Landscape, QuickCAD, SchoolBox, Simply Smarter Diagramming, SketchTools, Suddenly Everything Clicks,
Supportdesk, The Dancing Baby, Transform Ideas Into Reality, Visual LISP, Visual Syllabus, Volo, and Where Design Connects.
Third Party Trademarks
Élan License Manager is a trademark of Élan Computer Group, Inc. Microsoft, Visual Basic, Visual C++, and Windows are registered
trademarks and Visual FoxPro and the Microsoft Visual Basic Technology logo are trademarks of Microsoft Corporation in the
United States and other countries. All other brand names, product names, or trademarks belong to their respective holders.
Third Party Software Program Credits
ACIS ® © 1994, 1997, 1999 Spatial Technology, Inc., Three-Space Ltd., and Applied Geometry Corp. All rights reserved.
Active Delivery™ 2.0 © 1999-2000 Inner Media, Inc. All rights reserved.
© 2000 Microsoft Corporation. All rights reserved.
International CorrectSpell™ Spelling Correction System © 1995 by Lernout & Hauspie Speech Products, N.V. All rights reserved.
InstallShield™ 3.0. © 1997 InstallShield Software Corporation. All rights reserved.
Portions © 1991-1996 Arthur D. Applegate. All rights reserved.
Portions of this software are based on the work of the Independent JPEG Group.
Typefaces from the Bitstream ® typeface library © 1992.
Typefaces from Payne Loving Trust © 1996. All rights reserved.
The license management portion of this product is based on Élan License Manager © 1989, 1990, 1998 Élan Computer Group,
Inc. All rights reserved.
WexTech AnswerWorks © 2000 WexTech Systems, Inc. All rights reserved.
Wise for Installation System for Windows Installer © 2000 Wise Solutions, Inc. All rights reserved.
Autodesk would like to acknowledge and thank Perceptual Multimedia, Inc., for the creative and technical design and the
development of the Visual LISP Garden Path tutorial.
GOVERNMENT USE
Use, duplication, or disclosure by the U. S. Government is subject to restrictions as set forth in FAR 12.212 (Commercial Computer
Software-Restricted Rights) and DFAR 227.7202 (Rights in Technical Data and Computer Software), as applicable.
1 2 3 4 5 6 7 8 9 10
Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
AutoLISP and Visual LISP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
What Visual LISP Offers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Working with Visual LISP and AutoCAD . . . . . . . . . . . . . . . . . . . . . . 3
Using Visual LISP Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
iii
Loading and Running AutoLISP Programs . . . . . . . . . . . . . . . . . . . . . . . . . 18
Running Selected Lines of Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Using Extended AutoLISP Functions . . . . . . . . . . . . . . . . . . . . . . . . 20
Exiting Visual LISP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
iv | Contents
Using the Visual LISP Debugging Features . . . . . . . . . . . . . . . . . . . . . . . . . 69
Starting a Debugging Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Understanding Break Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Using Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Using Visual LISP Data Inspection Tools . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Using the Watch Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Understanding the Trace Stack Window . . . . . . . . . . . . . . . . . . . . . . 79
Using the Symbol Service Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . 86
Using Inspect Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Viewing AutoCAD Drawing Entities . . . . . . . . . . . . . . . . . . . . . . . . . 97
Contents | v
Optimizing Application Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Defining Build Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Choosing a Compilation Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Choosing a Link Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Understanding Safe Optimization . . . . . . . . . . . . . . . . . . . . . . . . . 150
vi | Contents
Part II Using the AutoLISP Language . . . . . . . . . . . . . . . . . . 213
Contents | vii
Chapter 9 Using AutoLISP to Communicate with AutoCAD . . . . . . . . . . . . . 253
Query and Command Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Command Submission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
System and Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . 257
Configuration Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Display Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Controlling Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Control of Graphics and Text Windows . . . . . . . . . . . . . . . . . . . . . 261
Control of Low-Level Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Getting User Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
The getxxx Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Control of User-Input Function Conditions. . . . . . . . . . . . . . . . . . 265
Geometric Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Object Snap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Text Extents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
String Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Angular Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
ASCII Code Conversion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Unit Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Coordinate System Transformations . . . . . . . . . . . . . . . . . . . . . . . 280
File Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
File Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Accessing Help Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Device Access and Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Accessing User Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Calibrating Tablets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
viii | Contents
Management of Extended Data Memory Use . . . . . . . . . . . . . . . . . 324
Handles in Extended Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Xrecord Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Symbol Table and Dictionary Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Symbol Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Dictionary Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Contents | ix
Chapter 12 Managing Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Controlling Dialog Boxes with AutoLISP Programs . . . . . . . . . . . . . . . . . 360
Quick Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Functions Restricted When a Dialog Box Is Open . . . . . . . . . . . . . 362
Action Expressions and Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
Action Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Callback Reasons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Handling Tiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Initializing Modes and Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Changing Modes and Values at Callback Time . . . . . . . . . . . . . . . 367
Handling Radio Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Handling Sliders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
Handling Edit Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Nesting Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Hiding Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Requesting a Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
List Boxes and Pop-Up Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
List Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Processing List Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Image Tiles and Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Creating Images. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Handling Image Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
Application-Specific Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
DCL Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Setting the Auditing Level to Affect Error Messages . . . . . . . . . . . . 382
Dialog Box Function Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Function Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
The Sample Block Definition Dialog Box . . . . . . . . . . . . . . . . . . . . 384
x | Contents
color. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
edit_limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
edit_width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
fixed_height. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
fixed_width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
fixed_width_font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
height . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
initial_focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
is_bold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
is_cancel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
is_default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
is_enabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
is_tab_stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
layout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
max_value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
min_value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
mnemonic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
multiple_select. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
password_char . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
small_increment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
tab_truncate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Functional Synopsis of DCL Tiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Predefined Active Tiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Tile Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Decorative and Informative Tiles . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Text Clusters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Dialog Box Exit Buttons and Error Tiles . . . . . . . . . . . . . . . . . . . . . 404
Restricted Tiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
DCL Tile Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
boxed_column. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
boxed_radio_column. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
boxed_radio_row . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
boxed_row . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
concatenation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
edit_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
errtile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Contents | xi
image. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
image_button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
list_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
ok_only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
ok_cancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
ok_cancel_help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
ok_cancel_help_errtile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
ok_cancel_help_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
paragraph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
popup_list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
radio_button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
radio_column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
radio_row . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
row . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
slider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
text_part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
toggle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
spacer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
spacer_0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
spacer_1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Programmable Dialog Box Function Synopsis . . . . . . . . . . . . . . . . . . . . . 421
Dialog Box Opening and Closing Functions . . . . . . . . . . . . . . . . . 421
Tile- and Attribute-Handling Functions . . . . . . . . . . . . . . . . . . . . . 421
List Box and Pop-Up List-Handling Functions . . . . . . . . . . . . . . . . 422
Image Tile-Handling Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
Application-Specific Data-Handling Functions . . . . . . . . . . . . . . . 423
xii | Contents
Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
Conversion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
Device Access Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Display Control Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
File-Handling Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
Geometric Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
Query and Command Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
User Input Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Selection Set, Object, and Symbol Table Functions . . . . . . . . . . . . . . . . . 445
Extended Data-Handling Functions . . . . . . . . . . . . . . . . . . . . . . . . 445
Object-Handling Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
Selection Set Manipulation Functions . . . . . . . . . . . . . . . . . . . . . . . 447
Symbol Table and Dictionary-Handling Functions . . . . . . . . . . . . . 448
Memory Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
Visual LISP Extensions to AutoLISP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
ActiveX Collection Manipulation Functions. . . . . . . . . . . . . . . . . . 450
ActiveX Data Conversion Functions . . . . . . . . . . . . . . . . . . . . . . . . 450
ActiveX Method Invocation Functions . . . . . . . . . . . . . . . . . . . . . . 452
ActiveX Object-Handling Functions . . . . . . . . . . . . . . . . . . . . . . . . 452
ActiveX Property-Handling Functions. . . . . . . . . . . . . . . . . . . . . . . 453
Curve Measurement Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Dictionary Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Object-Handling Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Reactor Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
VLX Namespace Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Namespace Communication Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 460
Windows Registry Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Contents | xiii
Appendix C AutoLISP Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
xiv | Contents
Introduction
For years, AutoLISP® has set the standard for In this chapter
customizing AutoCAD®. Now Visual LISPTM (VLISP) AutoLISP and Visual LISP
the language to interface with objects via the Microsoft Related Documents
customizing AutoCAD.
1
AutoLISP and Visual LISP
AutoLISP is a programming language designed for extending and customiz-
ing AutoCAD functionality. It is based on the LISP programming language,
whose origins date back to the late 1950s. LISP was originally designed for use
in Artificial Intelligence (AI) applications, and is still the basis for many AI
applications.
AutoCAD introduced AutoLISP as an application programming interface
(API) in Release 2.1, in the mid-1980s. LISP was chosen as the initial
AutoCAD API because it was uniquely suited for the unstructured design
process of AutoCAD projects, which involved repeatedly trying different
solutions to design problems.
Visual LISP (VLISP) is a software tool designed to expedite AutoLISP program
development. The VLISP integrated development environment (IDE) pro-
vides features to help ease the tasks of source-code creation and modification,
program testing, and debugging. In addition, VLISP provides a vehicle for
delivering standalone applications written in AutoLISP.
In the past, developing AutoLISP programs for AutoCAD meant supplying
your own text editor for writing code, then loading the code into AutoCAD
and running it. Debugging your program meant adding statements to print
the contents of variables at strategic points in your program. You had to fig-
ure out where in your program to do this, and what variables you needed to
look at. If you discovered you still didn’t have enough information to deter-
mine the error, you had to go back and change the code again by adding
more debugging points. And finally, when you got the program to work cor-
rectly, you needed to either comment out or remove the debugging code you
added.
2 | Introduction
Syntax Checker recognizes erroneous AutoLISP constructs and improper
arguments in calls to built-in functions.
File Compiler improves the execution speed and provides a secure and
efficient delivery platform.
Source Debugger, designed specifically for AutoLISP, supports stepping
through AutoLISP source code in one window while simultaneously dis-
playing the results of code execution in an AutoCAD drawing window.
Text File Editor uses AutoLISP and DCL color coding, as well as other
AutoLISP syntax support features.
AutoLISP Formatter restructures programs into an easily readable format.
Comprehensive Inspect and Watch features provide convenient access to
variable and expression values for data structure browsing and modifica-
tion. These features may be used to explore AutoLISP data and AutoCAD
drawing entities.
Context-sensitive Help provides information for AutoLISP functions and
a powerful Apropos feature for symbol name search.
Project Management system makes it easy to maintain multiple-file
applications.
Compiled AutoLISP files are packaged into a single module.
Desktop Save and Restore capabilities preserve and reuse the windowing
environment from any VLISP session.
Intelligent Console window introduces a new level of convenience and
efficiency for AutoLISP users. The basic functions of the Console corre-
spond to the AutoCAD Text Screen functions and provide a number of
interactive features, such as history scrolling and full-input line editing.
This Visual LISP Developer’s Guide assumes you have some experience with
AutoCAD and have basic user-level skills with Microsoft Windows®. Prior
experience with AutoLISP is not required, but it will make your learning
curve much smoother.
The Visual LISP Developer’s Guide is divided into the following sections:
4 | Introduction
If you are already familiar with AutoLISP, you may want to begin the Visual
LISP Tutorial after reading chapter 1. This is a matter of personal comfort: if
you feel you need to understand how everything works before using a tool,
you might be better off reading some or all of chapters 2 through 7 of this
guide before trying the tutorial.
Following are some guidelines to help you get the most out of the Visual LISP
Developer’s Guide:
Begin by reading chapter 1, “Getting Started”. This chapter tells you how
to invoke VLISP from AutoCAD, identifies what you’ll see when VLISP
first starts, and describes how to load and run existing AutoLISP programs
from VLISP. Chapter 1 introduces and briefly describes the windows you
will be working with in the VLISP IDE. Use this chapter to orient yourself
to the VLISP environment.
If you do not already know AutoLISP, read all of chapter 8, “AutoLISP
Basics”, and at least browse chapters 9 and 10, “Using AutoLISP to Com-
municate with AutoCAD” and “Using AutoLISP to Manipulate AutoCAD
Objects”, respectively. After that, you can either work through the tutorial
or read more chapters in the Visual LISP Developer’s Guide.
To search for a function that meets a particular programming need, refer
to appendix A, “AutoLISP Function Synopsis”, in this guide.
Chapter organization
2 Developing Programs with Shows you how to use the VLISP text
Visual LISP editor to enter AutoLISP program code,
format the code, and check the code for
AutoLISP syntax errors. Also shows you
how to run the code you’ve developed
from the VLISP editor window.
13 Programmable Dialog Box Reference Lists and describes all the DCL tiles and
their associated attributes, and
summarizes the AutoLISP functions
available tor work with programmable
dialog boxes.
6 | Introduction
Document Conventions
This document follows a number of stylistic and naming conventions when
describing actions or defining terms. Often, distinct typefaces are used to
distinguish items from the rest of the text. The following table lists some of
the conventions used in the Visual LISP Developer’s Guide.
Typographical conventions
Text you enter is shown in boldface. At the VLISP Console prompt, enter shape
File names and directory names are Double-click the file name drawline.lsp.
shown in italics when referred to in a The default install directory is
sentence. c:\program files\autocad 2000i\sample\visuallisp
In definitions that include variable text, A FAS file named appname-init.fas, where
the variable is in italics. appname is the application module name
AutoLISP and Visual LISP variable names Double-click on any occurrence of the variable
are in courier type. name origin-y
The *LAST-VALUE* IDE global variable
Related Documents
In addition to the AutoLISP Reference and the Visual LISP Tutorial, several
other AutoCAD publications may be required by users building applications
with Visual LISP:
Document Conventions | 7
AutoCAD Customization Guide contains basic information on creating
customized AutoCAD applications. For example, it includes information
on creating customized menus, linetypes, and hatch patterns. The
Customization Guide is available through the AutoCAD and Visual LISP
Help menus.
The DXF Reference describes drawing interchange format (DXFTM) and the
DXF group codes that identify attributes of AutoCAD objects. You may
need to refer to the DXF Reference when working with association lists
describing entity data. The DXF Reference is available through the
AutoCAD and Visual LISP Help menus.
The ObjectARX Reference contains information on using ObjectARXTM to
develop customized AutoCAD applications. AutoCAD reactor functional-
ity is implemented through ObjectARX. If you develop AutoLISP
applications that implement reactor functions, you may want to refer to
this manual.
The ObjectARX Reference is not included when you install AutoCAD. To
obtain the manual, download the ObjectARX SDK (Software Development
Kit) from the Autodesk World Wide Web site (http://www.autodesk.com).
Click on the Product Index link and look for ObjectARX under Develop-
ment Tools.
8 | Introduction
Part I
Using the Visual LISP
Environment
9
10
Getting Started
1
This chapter introduces you to the look and feel of the In this chapter
Visual LISP interactive development environment Starting Visual LISP
11
Starting Visual LISP
The Visual LISP (VLISP) interactive development environment runs in a
separate set of windows from the rest of AutoCAD. You must explicitly start
VLISP to work in the interactive development environment.
You can use either the menu or the vlisp command to return to the VLISP
IDE at any time.
Note that AutoCAD also recognizes the vlide command to start or return to
Visual LISP. This command name stands for “Visual LISP interactive develop-
ment environment.” AutoCAD issues the vlide command to call VLISP, and
as a result you may sometimes see “VLIDE” displayed in the AutoCAD Com-
mand window.
NOTE The sample files are only included in your installation if you chose Full
install, or if you chose Custom install and selected the Samples item. If you
previously installed AutoCAD and did not install the samples, rerun the install,
choose Custom, and select only the Sample item.
Note that the last items on the menu are Parentheses Matching and Extra
Commands.
Now click in the title bar of the VLISP Console window, then select the Edit
menu item again:
File Create a new AutoLISP program file for editing, open an existing file, save
changes to program files, build Visual LISP application files, and print
program files.
Edit Copy and paste text, undo the last change you made to text (or undo the
last command entered in the Console window), select text in the VLISP editor
or Console windows, match parentheses in expressions, and redisplay
previous commands entered in the Console window. See the chapter titled
“Developing Programs with Visual LISP” for more information on Edit
features.
Search Find and replace text strings, set bookmarks, and navigate among
bookmarked text. See “Using the Text Editor” on page 27 for information on
these topics.
View Find and display the value of variables and symbols in your AutoLISP code.
For more information on this topic, see chapter 3, “Debugging Programs”.
Project Work with projects and compile programs. See “Managing Multiple LISP
Files” on page 132, and “Compiling and Linking Programs” on page 104 for
information on these topics.
Debug Set and remove breakpoints in your program and step through program
execution one expression at a time. You can then check the state of variables
and the results of expressions. See chapter 3, “Debugging Programs”, for
more information on these features.
Tools Set VLISP options for text formatting and various environment options, such
as the placement of windows and toolbars.
Window Organize the windows currently displayed in your VLISP session, or activate
another VLISP or AutoCAD window.
Note that if you type text at the Console prompt but switch to the AutoCAD
window before pressing ENTER , the text will no longer be at the prompt
when you return to the VLISP window.
After you respond to the prompts, control returns to VLISP and you will once
again see the VLISP window.
When you enter commands in the VLISP Console window or run a program
loaded from the text editor, you may be frequently switching back and forth
between the VLISP and AutoCAD windows. Aside from using the standard
Windows methods of switching between windows, you can activate the
AutoCAD window by choosing Window Activate AutoCAD from the
VLISP menu, or by pressing the Activate AutoCAD button on the Run
toolbar. If you are in AutoCAD and want to return to the VLISP environment,
you can enter vlisp at the Command prompt, or choose Tools AutoLISP
Visual LISP Editor from the AutoCAD menu.
Running Selected Lines of Code
With VLISP, you can select lines of code in the text editor window and run
only the selected code, instead of the whole program.
This function first checks whether or not the AutoLISP extensions are already
loaded; if so, the function does nothing, otherwise it loads the extensions.
If you’re using the VLISP interactive development environment to develop
code, chances are you’ll want to use the AutoLISP extensions at some point.
It’s a good practice to issue vl-load-com when you start VLISP, or to include
a call to the function in your acaddoc.lsp file, so that it loads automatically.
But if you write programs that use any of the extended AutoLISP functions,
you need to call vl-load-com in those programs to ensure that the functions
are available to other users running your code.
21
Getting Organized
To develop an AutoLISP program with VLISP you must perform the following
steps:
Think about which tasks you want to accomplish with your program, and
how to approach those tasks.
Design the program.
Write the code.
Format the code for readability.
Check for errors in the program.
Test and debug the program.
This chapter provides you with information to help you accomplish writing,
formatting, and checking tasks. The “Debugging Programs” chapter
describes the debugging features of VLISP. The “Building Applications” and
“Maintaining Visual LISP Applications” chapters describe how to package
your programs into applications that can be run by other users, and how to
organize application components to facilitate future updates.
VLISP saves the text you enter and any output from executing the text. You
can then scroll through the Console window and see what transpired. You
can copy any text in the window and paste it at the Console prompt or in
another Windows application.
The VLISP Console window and the AutoCAD Command window differ in
the way they process the SPACEBAR and TAB keys. In the VLISP Console win-
dow, a space plays no special role and serves only as a separator. In the
AutoCAD Command window, pressing the SPACEBAR outside an expression
causes AutoCAD to process the text immediately, as if you had pressed
ENTER .
2 Press TAB again. The following command displays at the Console prompt:
_$ (setq origin-x (car origin))
2 Press TAB . VLISP searches for the last text you entered that began with
(command:
_$ (command "_.CIRCLE" origin radius)
If VLISP does not find a match, it does nothing (except possibly emit a beep).
Press SHIFT + TAB to reverse the direction of the associative search and find
progressively less-recent inputs.
Pressing SHIFT + ESC interrupts the command, and VLISP displays an “input
discarded” message like the following:
((_> ; <input discarded>
_$
(Note that in this example, you can also complete the command by entering
the missing close parentheses.)
If you type text at the Console prompt, but do not press ENTER , then pressing
ESC clears the text you typed. If you press SHIFT + ESC , VLISP leaves the text
you entered in the Console window but displays a new prompt without eval-
uating the text.
If you type part of a command at the Console prompt, but activate the
AutoCAD window before pressing ENTER , VLISP displays a new prompt when
you next activate the VLISP window. The text you typed is visible in the Con-
sole window history, so you can copy and paste it, but you cannot retrieve
the text by pressing TAB , because it was not added to the Console history
buffer.
Command Action
Cut Removes the selected text from the Console window and
moves it to the Windows Clipboard
AutoCAD Mode Transfers all input to the AutoCAD command line for
evaluation
Toggle Console Log Copies Console window output to the log file
Note also that you can cut and paste text between the VLISP Console window
and the AutoCAD Command window.
Editing a File
To open a new file in the VLISP text editor, choose FileNew File from the
menu bar. An empty editor window appears on the screen, and you can begin
entering text.
To start a new line, press ENTER . The text editor does not wrap your text
when it reaches the end of the visible text editor window, so everything you
type goes on the same line until you press ENTER .
You can indent lines of text manually, but VLISP automatically formats code
for you as you enter new lines of code. You can also copy text from another
file and have VLISP format the block of text you add. See “Formatting Code
with Visual LISP” on page 46 for details on using the VLISP code formatting
features.
When you exit VLISP, it notes which files are open and saves this informa-
tion for your next VLISP session. The next time you start VLISP, it automati-
cally opens the files for you.
Command Action
Go to Last Edited Moves the cursor to the position you last edited
Command Action
Correcting Text
You can delete words or lines using the following shortcuts:
To Press
Delete characters from the cursor position to the CTRL +E, then press E
end of the current line
You can also can use the overstrike mode to insert text. Overstrike mode is
toggled on and off by pressing INSERT. When in overstrike mode, each char-
acter you type replaces existing text. The cursor changes shape from vertical
to horizontal when in overstrike mode.
Selecting Text
The simplest method to select text is to double-click your left mouse button.
The amount of text selected depends on the location of your cursor.
To select specific text, press and hold the SHIFT key while pressing the direc-
tion (arrow) keys on the keyboard. Other keyboard methods of text selection
are listed in the following table:
To Press
Expand the selection to the next word, or abandon CTRL + SHIFT +RIGHT ARROW
selection of the next word, if it is currently selected
Expand the selection to the previous word, or CTRL + SHIFT +LEFT ARROW
abandon selection of the previous word, if it is
currently selected
Move the cursor to the other side of the selection ALT+ ENTER
To move Press
Indenting Shortcuts
Most indenting of program code is best handled by the VLISP automatic code
formatting and Smart Indent features, and by customizing the formatter’s
options (see “Formatting Code with Visual LISP”). But there are some things
you may want to do by yourself.
To indent selected lines of code, press TAB or press CTRL + E, and then choose
Indent Block. VLISP inserts a TAB character at the beginning of each line you
selected. You can control the indent amount of the TAB character by choos-
ing Tools Window Attributes
Configure Current and setting the Tab
Width value. You can also use the following keyboard shortcuts to adjust the
indentation of text.
To Do
Adjust the indent of the current selection to the Press SHIFT + TAB
preceding AutoLISP text.
Clear trailing SPACE and TAB characters, insert a Press SHIFT + ENTER
new line, and indent at the level of the previous
non-empty line.
Insert a new line without clearing trailing SPACE Press CTRL + ENTER
and TAB characters of the current line.
To copy the text instead of moving it, follow the same steps, but press CTRL
before releasing the mouse button in step 4.
You can also take selected text and copy it into a new file. With the text
selected, press CTRL + E to display a list of options, and choose Save Block As.
VLISP replies by displaying a dialog box for you to specify where you want to
save the text.
VLISP uses the Windows Clipboard for all cut and copy operations. There-
fore, you can exchange text with any other Windows application that
supports these functions. This also means you can copy and paste text
between the text editor and the VLISP Console window.
Remember that immediately after moving or copying text, you can change
your mind and reverse the action, using the Undo function.
To repeat a search you made earlier, click the pull-down arrow and select a
search term from the toolbar list. Press the Find Toolbar String button to con-
duct the search.
Replacing Text
The Search menu contains a Replace function that is used to replace the
search text with a text string that you specify.
The Replace dialog box is similar to the Find dialog box, but with fewer
options. It contains an additional Replace With entry field, in which you
specify the text you want VLISP to substitute for the search text. Specify the
search text in the Find What field.
You can take the following actions from the Replace dialog box:
Press Find Next to find the next occurrence of the search string.
Bookmarking Text
The bookmark feature helps you navigate through VLISP text editor windows
by letting you mark up to 32 positions (bookmarks) in each window. Once
32 bookmarks are set, adding a new bookmark results in the oldest bookmark
being removed.
Each text editor window maintains its own set of bookmarks, and the book-
mark navigation tools let you walk through the marks within each window
independently of the other windows. A set of bookmarks within a window is
known as a bookmark ring. You can step either forward or backward through
the ring, and eventually return to the starting point.
Whenever you step to a bookmark, VLISP automatically places a marker at
the location you are stepping from. In effect, the marker for the place you are
jumping to is moved to the place you jumped from. This makes it easy to
return to your original location just by stepping back in the opposite direc-
tion, or by cycling through all the bookmarks until you get back to the
starting point.
To add a bookmark
1 Move the cursor to the location you want to mark.
2 Press the Toggle Bookmark button on the toolbar, or press ALT + . ( ALT plus a
period).
Bookmarks may also be inserted automatically when using the Find com-
mand to search for text. See the discussion on search options in “Searching
for Text” on page 34 for more information on this feature.
In addition to jumping between bookmarks, you can also jump and select the
text between two bookmarks.
To remove a bookmark
1 Move the cursor to the bookmarked location.
2 Press the Toggle Bookmark button, or press ALT + . ( ALT plus a period).
The Toggle Bookmark command works as an on/off switch. If you issue the
command when a bookmark is set, Toggle Bookmark turns it off. Issue the
same command when there is no bookmark set, and Toggle Bookmark inserts
a bookmark.
3 To remove all the bookmarks in the active window, press the Clear All Book-
marks button on the toolbar, or choose Search
Bookmarks
Clear All Bookmarks from the VLISP menu.
Strings Magenta
Integers Green
Parentheses Red
The bottom of the Apropos results window contains a message area with
information about the results of the search. In the current example, the mes-
sage indicates the number of symbols Apropos found in its search.
If the Apropos results window is not large enough to show all the symbols
found, the window is displayed as scrollable. If the search returns over a
thousand matches, Apropos will not be able to list all the symbols, even in a
scrollable window. The message area in the results window warns you when
this occurs, as in the following example from a search on the prefix VL:
If your search results in too many symbols for Apropos to display in the
results window, you can use the Copy to Trace/Log feature to view the com-
plete list of symbols in the VLISP Trace window.
In other words, these are the last five commands that you entered from the
Console.
VLISP will keep searching for matching words each time you press
CTRL + SPACEBAR . If you keep pressing CTRL + SPACEBAR after VLISP finds the
last matching word, VLISP repeats the retrieval sequence. (Note that you can
also choose Search Complete Word by Match from the VLISP menu instead
of pressing CTRL + SPACEBAR to invoke the Match feature.)
If VLISP does not find any matching words, it does nothing.
VLISP found two matching words in the symbol table. The half-r symbol is
a variable you defined in the Console window, and the handent symbol rep-
resents an AutoLISP function.
3 Select the symbol you want to complete your typing. If you do not want to
select a symbol, press ESC .
Note that you can also choose Search Complete Word by Apropos from the
VLISP menu instead of pressing CTRL + SHIFT + SPACE to invoke the feature.
The message area of the Apropos options dialog box shows the value that
Apropos could not match. See “Using the Apropos Feature” on page 38 for
information on setting Apropos options and renewing your search.
If VLISP finds more than 15 matching names in the symbol table, it displays
the Apropos results dialog box. For example, type get at the Console prompt,
then press CTRL + SHIFT + SPACEBAR to invoke the Apropos feature. VLISP dis-
plays the following dialog box:
You can select a symbol from the results window and copy it into your code
using a shortcut menu. If you need additional help with copying the symbol
to your program code, or using other features of the Apropos results window,
see “Using the Results of an Apropos Search” on page 41.
If you select text to be formatted, the selection must contain valid AutoLISP
expressions or the formatter will issue an error message.
If the formatter finds unbalanced parentheses in your code, an alert box is
displayed. Choose Yes to have VLISP add parentheses where it thinks they
belong; choose No if you want to fix the parentheses on your own.
NOTE The VLISP formatter can balance the number of parentheses but usually
does not insert the additional parentheses in the right places. See “Checking the
Balance of Parentheses” on page 56 for more information on detecting and cor-
recting unmatched parentheses.
The VLISP Smart Indent feature works in the background as you type in the
text editor. The indent is evaluated up to the current AutoLISP parenthesis
nesting level. If the current expression is preceded by only a sequence of
For a general function call expression, the formatter applies one of the styles
in the following sections.
Plane Style
In the Plane style, all arguments are placed in the same line, separated by a
single space:
(autoload "appload" '("appload"))
The Plane style is applied to an expression when all the following conditions
are met:
The expression’s last character position does not exceed the value of the
Right Text Margin environment option.
The expression’s printing length is less than the value of the Approximate
Line Length environment option (that is, last character position minus
starting indentation position is less than this value).
The expression does not contain embedded comments with Newline
characters.
Narrow Style
In the Narrow style, the first argument is placed on the next line after the
function name, and other arguments are aligned in a column below the first
argument. The displacement of the first argument’s starting position relative
to the expression starting position is controlled by the value of the
Narrow Style Indentation environment option (in the following example,
this value is equal to 2):
(autoload
"appload"
'("appload")
)
The Narrow formatting style applies for progn expressions, and for those
instances when the Plane and Wide formatting styles cannot be applied.
Column Style
In the Column style, all elements are positioned in a column. This style is
appropriate for displaying quoted lists and COND-expression clauses. For
example, the following text:
'((10 "{insertion}") (1 "{string}")
(7 "{style}"))
Formatted text:
(autoarxload "image"
'("gifin" "pcxin" "riaspect"
"ribackg" "riedge" "rigamut"
"rigrey" "rithresh" "tiffin"
)
) ;_ end of autoarxload
Split Comments
When the Split Comments option is on, the formatter splits long comments
that extend past the right margin.
For the previous example, if the Right Text Margin setting is 60, and Single-
Semicolon comment indentation is 40, the formatter will split the comment
as follows:
(if (/= s "Function canceled")
(princ (strcat "\nError: " s)) ;single
;semicolon cmt
)
Single-Column formatting:
'("entdel"
"entmake"
"entmod"
"entnext"
"entsel"
"entupd"
)
Setting Effect
Formatted text:
(defun foo (x) ;|inline comment |;
(list 1 2 3) ;comment-column comment
;;current-column comment
;;; heading or 0-column comment
) ;_ function-closing comment
Formatter Restrictions
The following restrictions apply to the VLISP code formatter:
The formatter relies on a fixed window font and a particular tab size. To
change font settings, choose Window Attributes
Font; to change tab
settings, choose Window Attributes
Configure Current.
The formatter is available only within VLISP text editor windows.
Existing SPACE and TAB characters placed outside of inline comments and
strings will not influence the formatting result.
Option Effect
Indent Block Indents the selected block of text by adding a tab to the
beginning of each line.
Indent to Current Level Indents the current line to the same level as the previous line of
program code.
Prefix With Adds a text string to the beginning of the current line, or to
each line in a block of selected lines, after prompting you for
the string.
Option Effect
Append With Appends a text string to selected lines of text, after prompting
you for the string.
Capitalize Capitalizes the first letter of each word in the selected text.
Insert File Inserts the contents of a text file into the current editor window
at the cursor position.
Delete to EOL Erases everything from the cursor position to the end of the
current line.
Delete Blanks Deletes all blank spaces from the cursor position to the first
non-blank character in the line.
NOTE If you do not allow the formatter to add the balancing parentheses, it
won’t format your code either!
In any event, you must check the structure of your program to determine
where the parentheses are really missing. You can use these Parentheses
Matching items from the Edit menu to help you find unbalanced
parentheses:
Match Forward ( CTRL +])
Moves the insertion point (marked by the cursor) just past
the close parenthesis that matches an open parenthesis.
If the current cursor position is just before an open
parenthesis, VLISP matches that parenthesis with its
closing parenthesis. If the cursor position is in the middle
of an expression, VLISP matches the current expression’s
open parenthesis with its closing parenthesis.
Match Backward ( CTRL + [)
Moves the insertion point to just before the open
parenthesis that matches a close parenthesis.
If the current cursor position is just after a close
parenthesis, VLISP matches that parenthesis with its
opening parenthesis. If the cursor position is in the
middle of an expression, VLISP matches the current
expression’s close parenthesis with its open parenthesis.
(The line numbers are not part of the text; they are used to help explain the
example.)
Here is what happens if you load this code in VLISP and continually issue the
Match Forward command, starting with the insertion point at the beginning
of line 1.
In other words, the close parenthesis that matches the open parenthesis on
line 5 is the last parenthesis in the program. You know this is an error because
the last close parenthesis in an AutoLISP program should match the open
parenthesis of the program’s defun. Notice also that all the statements after
line 5 are indented in a manner unlike in the preceding program code. These
two clues indicate something is amiss at this point in the program. In fact,
the close parenthesis to the command that begins on line 5 is missing.
(This example also uses different fonts to represent different colors, so you
can differentiate between the fonts on a black and white printed page.)
If you use the standard VLISP syntactic colorations, systems functions such
as setq, defun, getdist, getpoint, and / are displayed in blue. The items
VLISP does not recognize, such as user-defined variables, are printed in black.
In this example, if you look at the unrecognized elements in the program, the
word iff might easily catch your eye. Change it to the correct spelling, if, and
the color immediately changes to blue.
Some syntax errors can only be determined at runtime and Check cannot
detect these errors. For example, if you call a function that expects an integer
argument and you supply a string, AutoLISP does not detect this until run-
time. As a result, this error will not be detected until you run your program.
The message indicates that an if function call contains too many arguments.
This error results from the last princ statement following the if . The if state-
ment only allows two arguments: the statement to execute if the expression
is true, and the statement to execute if the expression is false. The last princ
statement, which is used in this program to cause a quiet exit, belongs after
the close parenthesis that currently follows it. (See “Exiting Quietly” on page
230 for an explanation of a quiet exit.) If you move the statement to the cor-
rect location and run Check again, the code should pass as error-free.
61
Introducing Visual LISP Debugging Features
Debugging is usually the most time-consuming stage in the development of
any program. For this reason, VLISP includes a powerful debugger that pro-
vides the following features:
Learning by Example
This section takes you through a VLISP sample program and demonstrates
some VLISP debugging facilities along the way. You can find the sample pro-
gram, yinyang.lsp, in the Sample\VisualLISP directory under the AutoCAD
install directory path. Open the file in VLISP so that you can try the examples
in this section.
When you run the program, VLISP passes control to AutoCAD and you need
to respond to the prompts in the AutoCAD Command window.
VLISP evaluates AutoLISP programs by evaluating the expressions contained
in parentheses. These parenthetical expressions are similar to operators in
other programming languages such as C++ and Visual Basic®. The VLISP
debugger uses an expression-based approach, unlike the line-by-line
debuggers of languages such as C. In this approach, the debugger can sus-
pend program execution immediately before or after the evaluation of any
expression.
Debugging options are controlled from several different places within VLISP,
including the text editor, the System Console, and various menus.
Learning by Example | 63
Setting a Breakpoint to Interrupt Program Execution
Begin by entering some debugging information in the text editor window
containing the yinyang.lsp program.
breakpoint
Now look at the Step Indicator button on the Debug toolbar; it is the last
button on that toolbar.
The Step Indicator button is active when you are stepping through a pro-
gram. It indicates where you are in relation to the expression at the
breakpoint. The current symbol indicates that you are stopped just before an
open parenthesis.
Learning by Example | 65
2 Click the Step Into button again. The cursor moves to a position directly after
the evaluated expression, and the Step Indicator button indicates this.
3 Click the Step Into button again. The cursor moves to the end of the entire
statement (the expression and all nested expressions).
4 Click the Step Into button again and the cursor moves to a position just
before the beginning of the statement on the next line:
5 Now take a bigger step. Click the Step Over button, or choose
Debug Step Over from the menu, or press SHIFT + F8 to issue this
command:
With the Step Over command, VLISP evaluates an entire expression (and all
nested expressions), then stops at the end of the overall expression. The cur-
sor moves to the end of the evaluated expression.
VLISP displays the Watch window, which shows the value of the
*LAST-VALUE* IDE global variable. VLISP always stores the value of the last
evaluated expression in the *LAST-VALUE* variable.
2 In the text editor window containing yinyang.lsp, double-click on any occur-
rence of the variable name origin-y.
3 Click the Add Watch button in the Watch window. VLISP passes the
origin-y variable name to the Watch window and displays the current value
of the variable in the window:
If the Watch window is not already open and you want to view a variable’s
value, you can open the window by choosing View Watch Window from
the VLISP menu.
If you click the Watch window’s Add Watch button without double-clicking
on a variable name first, the following window appears:
In this window, you can enter the name of the variable you want to view.
VLISP may anticipate your choice by copying the name of the variable near-
est the cursor into the window. If this is not the one you want to view, simply
type over the name.
VLISP updates the variables in the Watch window after each execution step.
4 Click the Step Over button (or press SHIFT + F8 ) twice.
Learning by Example | 67
In the Watch window, note how the value of ORIGIN-Y changes. It was nil
at first, but after execution it took on the value corresponding to the point
you clicked in the AutoCAD window.
You can also interrupt animation by pressing BREAK (it’s the key next to
SCROLL—LOCK on most keyboards). Once animation is paused you can add
Watch values, set variables to new values, and add breakpoints.
To adjust the rate of animation, choose Tools Environment
Options General Options, and select the Diagnostic tab. The Animation
Delay setting defines the pause between program steps, in milliseconds.
To turn off Animate mode, choose Debug Animate from the VLISP menu
again.
Turning on the Stop Once mode and reaching an expression with debug-
ging information (that is, an expression that is loaded from source code,
as opposed to from a compiled .exe file)
Reaching a function marked for Debug on Entry
Reaching a breakpoint you set in the program
Entering a break loop by pressing the Pause button
Proceeding with a Step Over, Step Into, or Step Out command from the
previous break loop state
When the program is interrupted, you enter the break loop. This is apparent
if the VLISP Console window is active, because the prompt is changed to
reflect the current level of the break loop. In this suspended state, you have
read-write access to all variables in the environment in which the break
occurred. For example, if the break occurred within a function containing
several local variable declarations, those variables are accessible and you can
change their values by issuing setq assignments at the Console prompt.
When stopped at a breakpoint, you can control subsequent program execu-
tion by choosing one of the following items from the Debug menu, or by
pressing the equivalent toolbar button:
Reset to Top Level terminates all currently active break loops and returns
to the Console top-level (the top read-eval-print loop).
Quit Current Level terminates the current break loop and returns to a
break loop one level up. This may be another break loop or the top-level
read-eval-print loop.
Continue resumes normal program execution from the breakpoint.
The Step commands evaluate portions of program code before resuming sus-
pended mode:
After exiting the break loop to the Console top-level, the Console prompt
returns to its original form (without a number prefix).
Using Breakpoints
Breakpoints allow you to mark a position in a program at which program
execution should be interrupted. You can set breaks to occur before or after
parenthetical expressions. Breakpoints can only be set from a VLISP text
editor window.
To set a breakpoint
1 Move the cursor to the position at which you want to halt execution. For
example, to halt execution just before the open parenthesis of an expression,
place the cursor just to the left of that open parenthesis.
3 Click Yes to accept the breakpoint location, or No if that is not where you
want to set the break.
To remove a breakpoint
1 Position your cursor at the breakpoint you want to remove.
2 Press the Toggle Breakpoint toolbar button, or press F9 .
The Toggle Breakpoint works as an on/off switch. When no breakpoint exists,
Toggle Breakpoint adds a break; if a breakpoint already exists at the cursor
position, Toggle Breakpoint removes it. You can also use the Breakpoint Ser-
vice dialog to remove breakpoints; see “Listing and Viewing the Breakpoints
in Your Program” on page 74 for information on this procedure.
3 To remove all the breakpoints you have set, choose Debug Clear
All Breakpoints from the VLISP menu.
3 Click the Disable button in the Breakpoint Service dialog box to disable the
breakpoint temporarily.
VLISP changes the color of the breakpoint marker when it disables the break-
point. By default, it marks disabled breakpoints in blue. You can change this
color by resetting the :BPT-DISABLE option.
The Breakpoints window lists the breakpoints in all programs you are editing
in VLISP, not just the program in the active editor window. In the example
above, only one program ( yinyang) contains breakpoints. But you could have
breakpoints set in any number of files.
Each entry in the Breakpoints window shows the name of the source file con-
taining the breakpoint, and the location of the breakpoint in the source. A
leading + or - sign differentiates between active and disabled breakpoints.
The dialog box allows you to delete all breakpoints at once or to edit (or dis-
play) one breakpoint at a time. Press Show to display the source position of
the breakpoint. The Edit button opens the Breakpoint Service dialog, from
which you can disable the breakpoint.
Note also that if you modify a program’s code and run it without reloading
it (with the Load Active Edit Window command), the program will be inter-
rupted when a breakpoint is reached, but the exact source position will not
be shown. The following dialog box indicates this situation has occurred:
To enable the proper display of a source position, you must reload the code
and restart the program.
The Watch window displays the current value of any set of variables.
VLISP provides a logging feature that, when active, allows you to copy the
contents of a Data Inspection window to a log file.
If you reply Yes, VLISP appends new data to the current contents of the file.
If you reply No, VLISP overwrites the file and its original contents will be lost.
Choose Cancel to terminate the operation and specify a different file name.
4 To close the log file and quit the logging process, choose Toggle Trace Log
from the File menu again.
When Trace logging is turned on, any information displayed in the Trace
window is also written to the log file. Most VLISP data inspection tools pro-
vide a toolbar button for copying data to the Trace window.
The state of Trace logging is indicated in the Trace window’s title bar. If
logging is in effect, VLISP displays the name of the log file in the title bar. If
logging is off, no file name appears in the title bar.
The Watch window is updated at each step of a VLISP interactive session and
always shows the current environment state. In debugger mode, the Watch
window is refreshed automatically at the end of every expression evaluation.
Specify the name of the variable to be watched in this window, then click OK.
The Watch window retains its variables during a VLISP session. This means
that if you invoke Watch, add variables to the Watch window, and then close
the Watch window, the variables you added will appear in the Watch win-
dow, if you invoke Watch again during the current session.
The trace stack is used by VLISP to “remember its way out” of a nested series
of expressions. By viewing the stack, you can see what is happening within
your program as it is executing (within a suspended break mode) or immedi-
ately after it has crashed.
Before you invoke a function at the Console window or from AutoCAD, the
trace stack is empty. The action of invoking a function causes a record, or ele-
ment, to be placed on the stack. As that function calls additional nested
functions to perform the work of your program, additional elements may be
added to the stack. VLISP only needs to place elements on the stack when it
needs to remember its way out of nested functions.
There are two conditions where it is useful to examine trace stacks. The first
is when your program is in a suspended state, such as during a breakpoint
pause. The second is after an error occurs, causing your program to fail.
Function call frames show one individual function invocation. Each func-
tion call frame appears in the following format:
level (function-name {argument1 }...)
Arguments within this listing are displayed not by their local parameter
name, but by the values that were actually passed to the function.
Keyword frames are displayed at the very top and bottom of a trace stack.
They are displayed in the following form:
level :keyword – {o ptional-data}
The keyword indicates the type of the frame. The optional-data displays
additional information relating to the state of the program.
Special forms display the invocation of the foreach and repeat functions.
The arguments for these functions are not displayed. They appear as:
level (function-form ...)
Function call frames and keyword frames are discussed in more detail in the
following sections. These sections use the following code to demonstrate the
trace stack. If you wish, you can copy this code into a VLISP editor window,
set a breakpoint as indicated in the code comments, and run this sample:
(defun stack-tracing (indexVal maxVal)
(princ "At the top of the stack-tracing function, indexVal = ")
(princ indexVal)
(if (< indexVal maxVal)
(stack-tracing (1+ indexVal) maxVal)
(princ "Reached the maximum depth.") ; place a breakpoint
; at the beginning of
; this line
)
)
(defun c:trace-10-deep ()
(terpri)
(stack-tracing 1 10)
)
The Trace Stack window displayed above shows a function call frame for the
stack-tracing function. The second element, or frame, in the trace stack is
highlighted:
[2] (STACK-TRACING 10 10)
The number [2] simply identifies it as the second element in the stack. The
numbers following the stack-tracing function name (10 10) indicate the
actual values that were passed to the function.
The Frame Binding window displays information about the local variables in
the frame. In the example shown above, it lists the parameter names
(INDEXVAL , MAXVAL), along with the values assigned to these parameters.
These values were passed to the function. The parameters are listed in the
order they are defined within the function.
If you right-click on an entry in the Frame Binding window, VLISP displays a
shortcut menu containing the following items:
Inspect Calls the Inspect feature for the selected value.
Print Displays the selected value in the Console window.
Symbol Calls the Symbol Service dialog box for the selected
symbol.
Copy Copies the selected value into the IDE global variable
*obj*.
:TOP-COMMAND The VLISP IDE requested the action resulting in the first element
placed within the stack. This situation occurs, for example,
when a function is invoked directly from loading a selection or a
file.
:USER-INPUT The character string shown in the frame was entered from the
VLISP Console window. The frame immediately above the
keyword describes the expression as it was translated from the
user input. If the input string is too long, right-click to open a
context menu, and choose Show Message to view the entire
text. You can also choose the Inspect command to inspect the
entered string.
:BEFORE-EXP Debugger break upon entering the function. This message will
appear whenever you are stepping through using Step Into or
Step Over, and the step is entering an expression (as opposed
to just leaving an expression, which is indicated by the :AFTER-
EXP keyword).
:FUNCTION-ENTRY Debugger break upon entering the function. The stack element
following this message contains the call frame for the function
in which the break occurred.
:KBD-BREAK The PAUSE key was pressed, placing the program on hold.
This Frame Binding window identifies the user-supplied variable (N), the cur-
rent value of that variable (A), and the items remaining to be processed in the
list supplied to foreach (B C).
The REPEAT frame indicates a call to the repeat function. From the shortcut
menu, the Local Variables command displays the special name counter and
the current value of the repeat internal counter. The internal counter value
is initially set to the integer value passed to repeat , indicating the number of
iterations desired. The counter decreases by one at each loop iteration. It
shows the number of iterations remaining, minus one.
Note that each repeat expression possesses its own counter, but only one
such counter can be added to the Watch window.
AutoLISP functions such as if, cond , and, and setq do not appear on the
stack. They are not necessary because their call position may be viewed
within the source file in the VLISP text editor window.
The error trace is a copy of the trace stack as it appeared at the time the error
occurred. If the Break on Error debugging option is selected, the error trace
and the trace stack are identical immediately after an error occurs. You can
see this by selecting Break on Error from the Debug menu, intentionally caus-
ing an error (for example, issuing a function call that divides by zero), and
opening the two trace windows.
The toolbar on the Trace Stack window contains two buttons:
Refresh Refreshes contents of Trace Stack window.
Copy to Trace/ Copies the window contents to the Trace Stack window or
Log open log file.
When you issue a Reset command to exit a break loop (for example, Reset to
Top Level), pressing the Refresh button in the Trace Stack window replaces
that window’s contents with the latest trace stack data. In contrast, refresh-
ing the Error Trace window does not change the window’s contents, unless a
subsequent error has occurred.
A toolbar
A Name field, where you can enter or change the symbol to work on
A Value field that displays the symbol’s value or its initial substring
A series of check boxes for symbol flags
3 To update the value of the displayed symbol, enter an expression in the Value
field. When you press OK, VLISP evaluates the expression and assigns its
value to the symbol.
If the symbol you specified is a protected symbol, the Value field will be read-
only. To remove protection, clear the Protect Assign check box. See
“Understanding Symbol Flags” for more information on Protect Assign.
Use the OK and Cancel buttons to close the dialog box and to continue work-
ing in VLISP.
Enter the object or expression you want to inspect, then press OK to open the
Inspect window or press Cancel to cancel the action.
VLISP saves the last 15 items you enter in the Inspect prompt box. You can
choose a previously specified object for inspection by selecting it from the
drop-down list.
For example, to inspect the definition of the yinyang function, select the
name in the text editor window containing the yinyang.lsp, then press the
Inspect button to view the Inspect window:
element line
The caption of an Inspect dialog box shows the type of object being
inspected.
The object line shows a printed representation of the inspected object.
The element list displays the components of the inspected object.
VLISP expands an item in the element list if you double-click on it. For exam-
ple, the {Auxiliary} component in the sample Inspect window is itself a list.
Double-click on the {Auxiliary} item to open another Inspect window show-
ing the elements in the list:
LIST (for improper lists) Two elements: the car and cdr fields. It serves for all cases
that are not proper LISP lists, that is, where the last cdr is not
nil.
FILE The name of the corresponding file and the file’s opening
attributes.
SUBR, EXRXSUBR, and The name of the function (the name that was specified in
USUBR defun or at load time). SUBR refers to internal and compiled
functions, EXRXSUBR refers to external ARX functions, and
USUBR identifies user-defined functions.
ENAME (drawing entity) The fields in this element list correspond to the AutoCAD DXF
object list, as returned by the AutoLISP built-in function.
LIST Shows the car and cdr of an improper list. For example, a
(improper list) list constructed by (cons 4 '(5 . 0)) is represented as
follows:
VARIANT The VARIANT Inspect window shows the data type and
value of the variant. The following example shows an
Inspect window for a variant that contains an array of
doubles:
You can also use the Inspect feature to examine ActiveX objects. See “Using
the Inspect Tool to View Object Properties” on page 160 for an example of
this.
The title bar of this window identifies the drawing entity type. The object
line of the window displays the entity name.
<Entity name: 1cdf190>
The shortcut menu for the object line contains the common Inspect com-
mands Print, Copy, Log, and Update, plus some new items.
Modify If available, this command opens the standard AutoCAD
DDMODIFY dialog for the inspected entity.
The raw-data element shows the symbol table entries for the inspected block.
Double-click on the parts item to open an Inspect window listing the collec-
tion of entities residing within the block.
The raw-data and parts element lines occur in all block Inspect windows.
Other element lines, such as {name}, appear only if the Inspect Drawing
Objects Verbosely Diagnostic option is selected. See “Diagnostic Options” on
page 469 for information on setting VLISP diagnostic options.
create a single executable module that you can distrib- Designing for a Multiple
Document Environment
ute to users. The first part of this chapter provides basic
103
Compiling and Linking Programs
Each time you load AutoLISP source code, the code is translated into instruc-
tions the computer understands (executable code). The advantage of having
source code translated each time you load it is that you can make a change
and immediately try it out. This is useful for quickly testing new code, and
for debugging that code.
Once you are sure your program is working correctly, translating AutoLISP
source code each time it loads is time-consuming. VLISP provides a compiler
that generates executable machine code files from your source files. These
executable files are known as FAS files. Because the executable files contain
only machine-readable code, the source code you spent weeks or months
developing remains hidden even if you distribute your program to thousands
of users. Even strings and symbol names are encrypted by the VLISP file com-
piler.
VLISP also provides features for packaging more complex AutoLISP applica-
tions into VLISP executable (VLX) files. VLX files can include additional
resources files, such as VBA and DCL files, and compiled AutoLISP code. See
“Making Application Modules” on page 110 for instructions on building VLX
files.
Using VLX files, you can further control your application’s operating envi-
ronment by exposing only those functions you choose to expose, and by
maintaining a wall between your program’s variables and the variables users
can interact with in AutoCAD. For more information on controlling the
operating environment of a VLX, see “Designing for a Multiple Document
Environment” on page 120.
The VLISP project management feature allows you to tailor the optimization
options to the specific needs of your application. See “Choosing a Compila-
tion Mode” on page 148 to learn more about choosing optimization options.
For example, if you are compiling the yinyang.lsp program file that is in the
AutoCAD Sample\VisualLISP directory, and Support File Search Path is set as
indicated in the previous figure, you can issue the following command to
compile the program:
(vlisp-compile 'st "yinyang.lsp")
If the AutoCAD sample\visuallisp directory is not in the Support File Search
Path, you must include the entire path name when specifying the source file.
For example:
(vlisp-compile
'st "c:/program files/autocad 2000i/sample/visuallisp/
yinyang.lsp")
If you omit the file extension from a file name, VLISP assumes the .lsp
extension.
When specifying the file path name, replace the backslash symbol (\) you
normally use for file names with either a forward slash or a double backslash,
following the usual AutoCAD convention.
NOTE If you specify an output file name but do not specify a path name for
either the input or the output file, VLISP places the output file in the AutoCAD
install directory! This is probably not what you want.
In most instances, you’ll want to specify the full path name of the output file.
For example:
(vlisp-compile 'st "yinyang.lsp" "c:/program files/.../sample/
visuallisp/goodkarma")
This ensures that the output file is placed in the directory you want it to be.
Select Expert mode, so you can see all the possible Make options; then press
the Next button.
2 VLISP displays the following Application Directory dialog box, where you
name your application and specify where you want the application files built
by Make Application to reside:
The LISP Files to Include dialog box appears in both the Simple and Expert
Wizard modes.
You can specify AutoLISP source code files, compiled AutoLISP (FAS) files, or
a VLISP project file. Click the pull-down button to choose the type of file you
want to include, then press the Add button to display the following dialog
box for selecting the files:
You can also right-click and choose these actions from a shortcut menu.
Note that the load order of project files is specified when you define the
project. (See “Changing the Order in Which Visual LISP Loads Files” on page
137 of the “Maintaining Visual LISP Applications” chapter.)
When you have finished specifying your application’s AutoLISP files, press
Next to continue to the next step in the Make Application wizard.
All program files can be loaded by the VLX. If you choose a Visual LISP
project file, all files defined in the project files are compiled and included in
the VLX.
Click the pull-down button to choose the type of files you want to include,
then press the Add button to display the dialog box for selecting the files. In
the file selection dialog box, you can select multiple files using the standard
Windows file selection methods. After selecting file names, press Open to add
the files to your application.
To add more files of a different type, choose the file type from the pull-down
list and press Add again.
To remove resource files from your application, select the files you no longer
want and press the Remove button. You can also select one or more files,
right-click, and choose Remove from the shortcut menu.
After selecting resource files for your application, press Next to continue the
Make Application process.
VLISP saves all your application options in a Make (.prv) file. The Make file
also includes all the instructions that VLISP needs to build the application. If
you do not elect to build the application now, VLISP can use the Make file to
build the application later.
Press Finish to conclude the Make Application process.
The name and directory path of the source files being compiled.
The functions defined in the source file.
In the above example, four functions are identified: GP:GETPOINTINPUT,
GP:GETDIALOGINPUT, GP:DRAWOUTLINE, and C:GPATH.
The name and path of the output .fas files.
The VLISP Console window displays messages relating to the creation of the
application executable, the .vlx file. If the Make Application process succeeds,
the Console window displays the path and file name of the .vlx, as in the fol-
lowing example:
Rebuilding an Application
After changing application options or modifying source code, you need to
rebuild your application for the changes to take effect.
To rebuild an application
1 Choose File Make Application Rebuild Application from the VLISP
menu.
2 Specify the location of your application’s Make file.
3 Press Open to rebuild the application.
In rebuilding the application, VLISP recompiles all .lsp source files, applying
the specified compilation options, and packages your application files into a
new .vlx file. If your application contains many AutoLISP files, and you have
only changed the source code in one or two files, the Make Application
option can rebuild your application more efficiently. See the following sec-
tion for information on using this option.
Note that if you change application options (for example, from Standard
compile mode to Optimize and Link), you must use the Rebuild Application
menu option to create a new VLX with the changes you specified. The
Make Application command only checks for changes to AutoLISP source
code files, not to application options.
Understanding Namespaces
To prevent applications running in one drawing window from unintention-
ally affecting applications running in other windows, the concept of
namespaces was introduced in AutoCAD 2000. A namespace is a LISP envi-
ronment containing a set of symbols (for example, variables and functions).
Each open AutoCAD drawing document has its own namespace. Variables
and functions defined in one document namespace are isolated from vari-
ables and functions defined in other namespaces.
Dynamic Memory
Document 1 Document 2 (Doc 1)
Namespace Namespace foo
"A string"
foo foo
blit blit foo (Doc 2)
c:drawline 34.5
var1 c:drawline
45
The document’s title bar indicates which window is currently active. In the
preceding example, Drawing1.dwg is the current document.
3 Enter the following at the Command prompt:
(setq draw1foo "I am drawing 1")
This sets the draw1foo variable to a string.
Document 1
Namespace Dynamic Memory
foo (Doc 1)
foo Document 2 "A string"
blit Namespace
bar bar [Hangman]
NOTE When you load a VLX file that has not been defined as having its own
namespace, the environment is similar to that of a loaded file. All functions and
variables defined in the VLX are loaded in the document’s namespace.
(defun StartApp2 ()
(setq acadApp (vlax-get-acad-object))
(setq acadDoc (vla-Get-ActiveDocument acadApp))
(setq acadPrefs (vla-Get-Preferences acadApp))
(setq acadPrefFiles (vla-get-Files acadPrefs))
(setq hlpFile (vla-Get-HelpFilePath acadPrefFiles))
(startapp "winhlp32" hlpFile)
(princ)
)
(princ "\nStartApp2 is loaded, Type (StartApp2) to Run.")
(princ)
(defun StartApp2 ()
(setq acadApp (vlax-get-acad-object))
To set the value of a variable in all open document namespaces, use the
vl-propagate function. For example, the following function calls set a vari-
able named fooyall in all open document namespaces:
(setq fooyall "Go boldly and carry a soft stick")
(vl-propagate 'fooyall)
This command not only copies the value of fooyall into all currently open
document namespaces, but also causes fooyall to automatically be copied to
the namespace of any new drawings opened during the current AutoCAD
session.
The *example* variable is nil because it has not been set in the document
namespace.
4 Set *example* in the current document.
_$ (setq *example* -1)
-1
The *example* variable is set to -1 in the document namespace.
5 Check the current value of *example* in the blackboard.
_$ (vl-bb-ref '*example*)
0
The blackboard variable named *example* is still set to the value assigned in
step 1; setting the document variable of the same name in step 4 had no
effect on the blackboard.
VLISP also provides the vl-doc-set and vl-doc-ref functions to set and
retrieve document namespace variables from a separate-namespace VLX, and
vl-propagate to set the value of a variable in all open document namespaces.
Any instructions pending at the time the error occurred are flushed.
WARNING! If you do use ActiveX to work in MDI, be aware that if you close
all AutoCAD drawings you lose access to AutoLISP and will cause an exception.
131
Managing Multiple LISP Files
Many program examples you have seen in this document have been small,
standalone AutoLISP files. Typical AutoLISP applications, however, consist of
larger files with many lines of code. An application may include many source
code files. After compiling the programs in such an application, you also
have a number of FAS files to track.
As the number of application files grows, it becomes more difficult to main-
tain an application. Determining when you need to recompile files after
source code changes can be a challenge. VLISP provides functions that
greatly simplify the process of managing multiple-file applications.
Check which .lsp files in your application have changed, and automati-
cally recompile only the modified files. This procedure is known as a Make
procedure.
Simplify access to source files by listing all source files associated with a
project, making them accessible with a single-click.
Help you find code fragments by searching for strings when you do not
know which source files contain the text you’re looking for. VLISP limits
the search to files included in your project.
Optimize compiled code by directly linking the corresponding parts of
multiple source files.
Before discussing how to define and use VLISP projects, it may help to intro-
duce file types used in VLISP.
.prj Project definition Contains the location and names of all source
files that build the project, as well as certain
parameters and rules on how to create the final
FAS files.
.c, .cpp, Language source files Contain program source code. The VLISP editor
.cch, .hpp, recognizes the syntax of these files and color-
.hh codes reserved words, strings, and numbers.
.prv Make application Defines the files and options used to build a VLX
application with the VLISP Make Application
wizard.
.sql Structured query language Contains SQL statements. The VLISP text editor
recognizes this file type and color-codes the text
according to SQL syntax rules.
Defining a Project
To demonstrate the use of projects in VLISP, you can use the sample pro-
grams supplied with the VLISP Tutorial. This code is available on the
AutoCAD installation CD, but the tutorial files are only included in your
installation if you choose a Full install, or if you choose Custom install and
select the Samples item. If you have already installed AutoCAD and did not
install the samples, you can rerun the install, choose Custom, and select only
the Sample item.
The sample files used in this chapter are in the Tutorial\VisualLISP\Lesson5
folder of the AutoCAD install directory. The files are:
Gpmain.lsp
Gpdraw.lsp
Gp-io.lsp
Utils.lsp
To create a VLISP project, choose Project New Project from the VLISP
menu. VLISP displays a standard Windows dialog box for you to specify a file
path and name. For the example in this chapter, the project name is Tutorial.
VLISP assigns a .prj extension to the project file name.
VLISP lists all files in the directory having an .lsp extension (but does not dis-
play the extension in the list). The window is designed so that, by default,
you can select multiple file names by just choosing each name. You do not
have to press and hold CTRL to select more than one file. To clear a selected
name, just choose it again.
To remove a file from the project, select the file’s name in the right window
and click the left arrow button.
Identifying the Path Name of Project Files
The list of included files does not identify the path name of each file (nor
does the Look In field; this just identifies the path of the files listed in the left
window). Because you can include files from multiple directories in your
project, you need to be able to identify the path name of each file. You can
do this by highlighting one or more file names and right-clicking to display
a shortcut menu:
To display the full path name and the size (in bytes) of source files in the
project, choose Log Filenames and Size from the shortcut menu. The infor-
mation appears in a small, scrollable window near the bottom of the Project
Properties dialog box:
By default, VLISP lists the project members in the order in which they will be
loaded (as defined in the Project Properties dialog box). You can change this
order by choosing Arrange Files from the shortcut menu for this window (see
below).
The project name appears in the window title bar. Below the title bar are five
icons. Each icon is a button that performs a function. The buttons and their
functions are as follows:
Project Displays the Project Properties dialog box for the project.
Properties This allows you to view the full path name of each file in
the project, add, remove, and reorder project files, and
view and change project compiler options.
Load Project Loads all compiled (.fas) files for the project.
FAS
Load Source Loads all the project source files, making them available to
Files be run.
Build Project Compiles all project source files that have been modified
FAS since their last compile.
Rebuild Project Recompiles all project source files, whether or not they
FAS have changed since their last compile.
If you right-click within the file list of the Project Properties dialog box,
VLISP displays a shortcut menu. Many of the functions available from the
project shortcut menu can also be accomplished in other ways. For example,
you’ve already seen how to add files to projects and remove files from
projects. Choosing Remove File from the shortcut menu is a quick way of
removing a file from a project, while choosing Add File merely brings you to
the Project Properties dialog box.
If you click on the name GP-IO, then click on the name GPDRAW, both are
selected.
This is unlike the default Windows behavior, where selecting the second list
item cancels the first item’s selection, unless you press CTRL while selecting
the item.
You can also use the Project Properties dialog box shortcut menu to select all
members of the project or cancel selection of all members. If no members are
currently selected, right-click and choose [Un]Select All to select all the mem-
bers. If any or all members are already selected, [Un]Select All cancels all
selections.
NOTE The Lesson5 example from the VLISP Tutorial requires a DCL file to run
successfully. The DCL file is included in the Lesson5 folder, but you cannot define
a DCL file as part of a VLISP project. To run this example successfully you must
copy the DCL file to a directory in the AutoCAD Support File Search Path. You
can also define the DCL file as an application component, using the VLISP Make
Application wizard. Using this method, the file does not have to be in the
AutoCAD search path. “Including a Project in a Visual LISP Application” on page
145 demonstrates how to define an application composed of a VLISP project and
supporting files, such as DCL.
NOTE If the Multiple Selector option is not turned on, you can simply double-
click a member name to edit it.
NOTE If you close the Project Properties dialog box by clicking the Close but-
ton, this does not close the project itself. The Project is still open, and you can
reopen a Project window for it by choosing it from the Project menu, as
described in the next section, “Opening a Project.”
Opening a Project
To open an existing project, choose Project Open Project from the VLISP
menu:
At any time, only one of the projects is active. The check mark in front of the
project name indicates the active project. The commands in the Project
menu, such as Load and Build, apply to the active project. These commands
work the same when selected from a Project window, as described earlier in
this chapter.
If you attempt to open a project that has the same name as the active project
(that is, the project file has the same name, but is in a different directory than
the current active project), VLISP displays a message box asking you if you
want to “relocate the project definition.” If you choose “Yes,” VLISP loads the
new project file and replaces the active project. If you choose “No,” VLISP
does not load the new project file, leaving the current active project in place.
A Project selection field now appears at the bottom of the Find dialog box. If
the name of the project you want to search is not already displayed in this
field, choose it from the pull-down list. Choose the Find button to perform
the search. VLISP displays the results in a Find Output window like the
following:
The output shows that four files were searched (there are four source files in
the project), and four occurrences of gp:getPointInput were found. The
occurrences were found in two files; the defun for the function is in gp-io.lsp.
You can open an editor window for the file by double-clicking anywhere
within the highlighted text in the Find Output window. You can also press
SHIFT + F11 to display the first source location at which the text string was
found, and then repeatedly press F11 to view subsequent occurrences in the
source files.
Remember that any optimization will change program semantics. The com-
piler intends to preserve the behavior of project components relative to one
another. The compiler cannot guarantee unchanged behavior between your
project and external procedures. Typical effects of optimization include the
following:
Outer applications and the VLISP Console window lose access to program
functions and symbols.
Functions available from the Console window in interpreter mode are
unknown in compiled mode.
Functions are available from the Console window, but redefining them
does not change the program’s behavior.
Now there are two possible conditions. If the value assigned through setq is
intended to alter the definition of the function fishlips , direct linking will
prevent this from happening. The first definition will be referenced directly
and cannot be changed by the setq function. On the other hand, if the iden-
tical names are handled independently, fishlips can be linked without
creating incorrect code.
If safe optimizing is on, the compiler will always stay on the safe side, even
if you explicitly request that fishlips be directly linked. This may result in
less efficient code, but it ensures code correctness. If safe optimizing is off,
you can override the compiler’s recommendation to link fishlips indirectly.
You are responsible for the link option.
The Safe Optimize mode is on by default. Be sure you fully understand the
consequences before you turn it off.
155
Using ActiveX Objects with AutoLISP
ActiveX Automation is a new way to work programmatically with the con-
tents of an AutoCAD drawing. In many instances, ActiveX works faster than
traditional AutoLISP functions in manipulating AutoCAD drawing objects.
The ActiveX programming interface is usable from a number of languages
and environments, such as C++, Visual BasicTM, and DelphiTM. When you
work with ActiveX objects in AutoLISP, you work with the same object
model, properties, and methods that can be manipulated from other pro-
gramming environments.
Objects are the main building blocks of an ActiveX application. In some
ways, you are already familiar with this notion. For example, AutoCAD draw-
ing items such as lines, arcs, polylines, and circles have long been referred to
as objects. But in the ActiveX schema, the following AutoCAD components
are also represented as objects:
Even the drawing and the AutoCAD application itself are considered objects.
ActiveX includes much of the functionality provided by standard AutoLISP
functions such as entget, entmod, and setvar. Compared to these functions,
ActiveX runs faster and provides easier access to object properties. For exam-
ple, to access the radius of a circle with standard AutoLISP functions, you
must use entget to obtain a list of entities and assoc to find the property you
want. You must also know the code number (DXF key value) associated with
that property to obtain it with assoc , as shown in the following example:
(setq radius (cdr (assoc 40 (entget circle-entity))))
With an ActiveX function, you simply ask for the radius of a circle as follows:
(setq radius (vla-get-radius circle-object))
AutoCAD Application
Preferences
Documents
3DFace
Document
3DPoly
Blocks Block
3DSolid
Database
Arc
ModelSpace
Attribute
PaperSpace
AttributeRef
PViewport
BlockRef
XRecord Dim3PointAngular
DimAligned
DimStyles DimStyle
DimAngular
Groups Group
DimDiametric
Layers Layer
DimOrdinate
Hyperlinks
Layouts Layout
DimRadial
Hyperlink
Linetypes Linetype DimRotated
ExternalReference
RegisteredApps RegisteredApplication
Hatch
SelectionSets SelectionSet
Leader
TextStyles TextStyle
LightweightPolyline
MLine
Viewports Viewport
MText
DatabasePreferences
Point
Plot
PolyfaceMesh
Utility
Polyline
MenuBar
PolygonMesh
PopupMenu Raster
MenuGroups Ray
Region
MenuGroup
Shape
PopupMenus
Solid
PopupMenu
Spline
PopupMenuItem
Text
Toolbars
Tolerance
Toolbar Trace
ToolbarItem XLine
Object Properties
All objects in the AutoCAD object model have one or more properties. For
example, a circle object can be described by properties such as radius, area, or
linetype. An ellipse object also has area and linetype properties, but it cannot
be described in terms of its radius. Rather, you describe it in terms of its major
to minor axis ratio, a property named RadiusRatio. Property names are nec-
essary when accessing AutoCAD data through ActiveX functions.
Object Methods
ActiveX objects also contain methods, which are simply the actions available
for a particular kind of object. Some methods can be applied to most
AutoCAD drawing objects. For example, the Mirror method (creating a mir-
ror image copy of an object around a mirror axis), and the Move method
(moving a drawing object along a specified vector), can be applied to most
drawing objects. By contrast, the Offset method, which creates a new object
at a specified distance from an existing object, applies only to a few classes of
AutoCAD objects such as Arc, Circle, Ellipse, and Line.
In VLISP, ActiveX methods are implemented as AutoLISP functions. You’ll
see many references to ActiveX functions in VLISP documentation, but keep
in mind that in ActiveX terminology, they are always known as methods.
To determine which methods and properties apply to a specific type of
AutoCAD object, refer to the ActiveX and VBA Reference. This reference is
available from the VLISP and AutoCAD Help menus, or by opening the
acadauto.hlp file in the AutoCAD Help directory.
You will probably want to have the ActiveX and VBA Reference open at all
times when you are developing VLISP programs that use ActiveX. If you open
the acadauto.hlp file from the AutoCAD Help directory, you can keep the ref-
erence open when you use VLISP online help. If you open the reference by
selecting it from the AutoCAD Help menu, it closes when you choose an item
from the VLISP Help menu.
This function first checks if ActiveX support is already loaded; if so, the func-
tion does nothing. If ActiveX support is not already loaded, vl-load-com
loads ActiveX and other Visual LISP extensions to the AutoLISP language.
NOTE All applications that use ActiveX should begin by calling vl-load-com.
If your application does not call vl-load-com , the application will fail, unless the
user has already loaded ActiveX support.
After loading the ActiveX support functions, the first step in accessing
AutoCAD objects is to establish a connection to the AutoCAD Application
object. Use the vlax-get-acad-object function to establish this connection,
as in the following example:
(setq acadObject (vlax-get-acad-object))
You can readily identify many of the properties listed in the VLA-object
Inspect window. For example, FullName is the file name of the AutoCAD
executable file, Version is the current AutoCAD version, and Caption is the
contents of the AutoCAD window title bar. An [RO] following a property
name indicates the property is read-only; you cannot change it.
Any property identified as a #<VLA-OBJECT...> refers to another AutoCAD
ActiveX object. Look at the Preferences property, for example. If you refer to
the diagram of the AutoCAD object model, you’ll see that the Preferences
object is just below the Application object in the model hierarchy. To view
the properties associated with an object, double-click the object line in the
Inspect window (or right-click and choose Inspect). Here is the Inspect win-
dow for the Preferences object:
If you compare the properties shown in this window to the options available
under the Files tab in the AutoCAD Options dialog box, you’ll be able to see
the connection between the two. The following figure shows the Files
options:
AutoCAD
Application
Document
ModelSpace
Collection
Circle
VLISP also adds a set of ActiveX-related functions whose names are prefixed
with vlax-. These are more general ActiveX functions, each of which can be
applied to numerous methods, objects, or properties. For example, with the
vlax-get-property function, you can obtain any property of any ActiveX
object. If your drawing contains custom ActiveX objects, or if you need to
access objects from other applications, such as a Microsoft Excel spreadsheet,
you can use the vlax-invoke-method, vlax-get-property, and
vlax-put-property functions to access their methods and properties; you’ll
see examples using these functions in “Using ActiveX without Importing a
Type Library” on page 193.
Sometimes, as in this Circle entry, there is descriptive text that identifies the
method you need. Often, though, you’ll need to look through the list of
methods to find the one that matches the action you want to take.
Once you find the name of the method, add a vla- prefix to the method name
to get the name of the VLISP function that implements the method. In this
example, it is vla-AddCircle. Note in VLISP the function name is not case-
sensitive; vla-addcircle is the same as vla-AddCircle.
Note that you can also get to this page by choosing the Methods button near
the top of the Help window, then choosing AddCircle from a list of methods.
The syntax definitions in the reference were designed for Visual Basic users,
so they may take some getting used to. For AddCircle, the syntax is defined
as follows:
RetVal = object.AddCircle(Center, Radius)
Substituting the variable names used in this chapter’s examples, the
syntax is:
mycircle = mspace.AddCircle(Center, Radius)
The return value (RetVal , in Visual Basic) is straightforward. The ActiveX and
VBA Reference defines this as a Circle object. In VLISP, whenever an AutoCAD
object is returned by an ActiveX function, it is stored as a VLA object data
type.
The object referred to before the method name (object.AddCircle ) is always
the first argument in a vla function call. This is the AutoCAD object you are
viewing or modifying. For example, add a circle to the drawing model space
with the following:
_$ (vlax-safearray->list point)
(100.0 100.0 0.0)
If you do not specify a value for every element in the array,
vlax-safear-ray-fill results in an error.
Using vlax-safearray-put-element
The vlax-safearray-put-element function can be used to assign values to
one or more elements of a safearray. The number of arguments required by
this function depends on the number of dimensions in the array. The follow-
ing rules apply to specifying arguments to vlax-safearray-put-element:
The first argument always names the safearray to which you are assigning
a value.
The next set of arguments identifies index values pointing to the element
to which you are assigning a value. For a single-dimension array, specify
one index value; for a two-dimension array, specify two index values, and
so on.
The final argument is always the value to be assigned to the safearray
element.
To change the second element of the array to a value of 50, issue the follow-
ing command:
(vlax-safearray-put-element point 1 50)
The following example populates a two-dimension array of strings. The first
dimension of the array starts at index 0, while the second dimension starts
at index 1:
(vlax-safearray-put-element mat2 0 1 "a")
(vlax-safearray-put-element mat2 0 2 "b")
(vlax-safearray-put-element mat2 0 3 "c")
(vlax-safearray-put-element mat2 1 1 "d")
(vlax-safearray-put-element mat2 1 2 "e")
(vlax-safearray-put-element mat2 1 3 "f")
You can use vlax-safearray->list to confirm the contents of the array:
If you need to create a variant for an array containing anything other than
three doubles or a transformation matrix, you must build it yourself.
Safe- :vlax-true
Integer Real String VLA-object Variant array :vlax-false
Byte +
Boolean +
Integer +
Long +
Single + +
Double + +
Object +
String +
Variant +
Array +
These test functions return T if true, nil if false. The following examples test
a line object:
Determine whether the line is readable:
$ (vlax-read-enabled-p WhatsMyLine)
T
The following command determines whether or not the AddBox method can
be applied to the object:
_$ (vlax-method-applicable-p WhatsMyLine "AddBox")
nil
Like the foreach function, vlax-for returns the result of the last expression
evaluated inside the for loop. Note that modifying the collection (that is,
adding or removing members) while iterating through it may cause an error.
The following example defines a function that uses vlax-for to show color
statistics for each object in the active drawing:
(defun show-Color-Statistics (/ objectColor colorSublist colorList)
(setq modelSpace (vla-get-ModelSpace
(vla-get-ActiveDocument (vlax-get-Acad-Object))
)
)
(vlax-for obj modelSpace
(setq objectColor (vla-get-Color obj))
(if (setq colorSublist (assoc objectColor colorList))
(setq colorList
(subst (cons objectColor (1+(cdr colorSublist)))
colorSublist
colorList
)
)
(setq colorList (cons (cons objectColor 1) colorList))
)
)
(if colorList
(progn (setq
colorList (vl-sort colorList
'(lambda (lst1 lst2) (< (car lst1) (car lst2)))
)
)
(vlax-object-released-p object)
This function returns T if the object has been released, nil if it has not.
To find the handle associated with an ename, use the DXF 5 group of the
ename’s association list:
_$ (setq handle-circle (cdr (assoc 5 (entget ename-circle))))
"4F"
To find the ename associated with a handle, use the handent function:
_$ (handent handle-circle)
<Entity name: 27f0538>
To find the VLA-object associated with a handle, use the
vla-handleToObject function:
_$ (setq vla-circle (vla-handleToObject acadDocument
handle-circle))
#<VLA-OBJECT IAcadCircle 03642c24>
To find the handle associated with a VLA-object, use vla-get-handle to
obtain the handle property:
_$ (vla-get-handle vla-circle)
"4F"
To find the ARX Object ID of a VLA-object, use vla-get-objectid to get
the objectID property:
_$ (setq objid-Circle (vla-get-objectid vla-circle))
41878840
To find the VLA-object identified by an ARX Object ID, use the
ObjectID-toObject method on the AutoCAD Document object:
_$ (vla-ObjectIDtoObject acadDocument objid-circle)
#<VLA-OBJECT IAcadCircle 03642c24>
If this code were part of your application program, execution would halt at
this point.
vlax-invoke-method
vlax-get-property
vlax-put-property
194
Advanced Topics
7
VLISP not only makes program development easier and In this chapter
faster, it also provides new functionality to AutoLISP Attaching Reactors to
AutoCAD Drawings
applications. For example, you can attach reactors to
195
Attaching Reactors to AutoCAD Drawings
A reactor is an object you attach to AutoCAD drawing objects to have
AutoCAD notify your application when events you are interested in occur.
For example, if a user moves an entity that your application has attached a
reactor to, your application will receive notification that the entity has
moved. If you design it to do so, your application can react to this notifica-
tion with appropriate actions, such as moving other entities associated with
the one moved, or perhaps updating a text tag that records revision informa-
tion on the altered drawing feature.
A reactor communicates with your application by calling a function you
have associated with the reactor. Such a function is referred to as a callback
function. There isn’t anything particularly unusual about reactor callback
functions—they are like other functions you write with VLISP. They become
callback functions when you attach them to reactor events.
Before you can use reactor functions with AutoLISP, you must load the sup-
porting code that enables these functions. Issue the following function call
to load reactor support:
vl-load-com
This function first checks whether reactor support is already loaded; if reactor
support is loaded, the function does nothing, otherwise, it loads reactor sup-
port and other AutoLISP extended functions.
Beginning with AutoCAD 2000, the broad class of Editor reactors is broken
down into more specific reactor types. The :VLR-Editor-Reactor type is
retained for backward-compatibility, but any new Editor reactors introduced
with AutoCAD 2000 cannot be referenced through :VLR-Editor-Reactor. The
following table lists the types of Editor reactors available beginning with
AutoCAD 2000.
:VLR-Miscellaneous-Reactor Does not fall under any of the other editor reactor
types
Use the vlr-types function to return the complete list of reactor types.
NOTE If this or any other vlr-* command fails with a “no function definition”
message, you may have forgotten to call vl-load-com, the function that loads
AutoLISP reactor support functions.
You can print out a list of all available reactor events, sorted by reactor type,
by loading and running the following code in VLISP:
(defun print-reactors-and-events ()
(foreach rtype (vlr-types)
(princ (strcat "\n" (vl-princ-to-string rtype)))
(foreach rname (vlr-reaction-names rtype)
(princ (strcat "\n\t" (vl-princ-to-string rname)))))
(princ))
The AutoLISP Reference lists each event available for a reactor type. For each
reactor type, you can find this information by looking up the description of
the function you use to define a reactor of that type. These functions have
the same name as the reactor type, minus the leading colon. For example,
vlr-acdb-reactor creates a database reactor, vlr-toolbar-reactor creates a
toolbar reactor, and so on.
The first argument identifies the object that fired the notification.
The second argument identifies the Reactor object that called the
function.
The third argument is a list of parameters specific to the callback
condition.
Creating Reactors
You link a callback function to an event when you create a reactor. There is
an AutoLISP function for creating each type of reactor. These functions have
the same name as the reactor type, minus the leading colon. For example,
vlr-acdb-reactor creates a database reactor, vlr-toolbar-reactor creates a
toolbar reactor, and so on. Except for object reactors, the reactor creation
functions require the following arguments:
Editor reactors are notified each time the user issues a command, whether
through the AutoCAD Command line, a menu, a toolbar, or an AutoLISP
program. So, the callback function for this DWG reactor needs to determine
precisely what it is responding to. In the current example, save-drawingInfo
simply checks for the Save command.
Possible events for each reactor type are listed in the AutoLISP Reference. To
find the list of events for a reactor, refer to the entry in the AutoLISP Reference
that describes the function used to create the reactor. For example, to find
the list of possible events for a DWG reactor, refer to the entry for
vlr-DWG-reactor.
A list of VLA-objects identifying the drawing objects that are to fire noti-
fications to the reactor. These objects are referred to as the reactor owners.
AutoLISP data to be associated with the Reactor object.
A list of pairs naming the event and the callback function to be associated
with that event (event-name . callback_function).
The Reactor object is stored in variable circleReactor; you can refer to the
reactor using this variable, as described in “Querying, Modifying, and
Removing Reactors” on page 205.
When defining a list of owners, you must specify VLA-objects only; Ename
objects are not allowed. VLA-objects are required because callback functions
can only use ActiveX methods to modify AutoCAD objects, and ActiveX
methods require a VLA-object to work on.
Note that, although you cannot use objects obtained through functions such
as entlast and entget with callback reactors, you can convert these Ename
objects into VLA-objects using the vlax-ename->vla-object function. See
the AutoLISP Reference for more information on vlax-ename->vla-object.
This code uses vla-addCircle to draw a circle, assigning the return value to
variable myCircle. The return value is a VLA-object, which contains a pointer
to the Circle object drawn.
4 In the AutoCAD drawing window, select the circle and change its size. The
print-radius function will display a message in the AutoCAD Command
window. For example, if you use the STRETCH command to enlarge the circle,
the message looks like the following:
Specify stretch point or [Base point/Copy/Undo/eXit]: The radius is
3.75803
To specify that a reactor should execute its callback function even if the doc-
ument it was defined in is not active (for example, if an application in
another namespace triggers an event), issue the following function call:
(vlr-set-notification reactor-object 'all-documents)
In this case, the return value is a list containing one list. The one list identi-
fies pointers to two DWG reactors.
Inspecting Reactors
You can examine reactors using the VLISP Inspect tool. For example, the
object reactor defined in “Using Object Reactors” on page 202 was returned
to the variable circleReactor. If you open an Inspect window for this vari-
able, VLISP displays the following information:
Modifying Reactors
VLISP provides functions to modify reactor definitions:
Both the Arc and Circle objects are listed in the Inspect window.
vlr-owner-remove removes an Owner object from the list of reactor own-
ers. For example, the following command removes archie from the
circleReactor owner list:
$ (vlr-owner-remove circleReactor archie)
#<VLA-OBJECT IAcadArc 03ad0bcc>
_$ (vlr-pers-p circleReactor)
#<VLR-Object-Reactor>
The vlr-pers-p function returns the Reactor object if it is persistent, nil if it
is not.
213
214
AutoLISP Basics
8
This chapter introduces the basic concepts of the In this chapter
AutoLISP programming language. It describes the core AutoLISP Expressions
to be entered at the Visual LISP (VLISP) Console window Symbol and Function Handling
Error Handling
prompt (_$), while others are entered at the AutoCAD
215
AutoLISP Expressions
An AutoLISP program consists of a series of expressions. AutoLISP expres-
sions have the following form:
(function arguments)
Each expression begins with an open (left) parenthesis and consists of a func-
tion name and optional arguments to that function. Each argument can also
be an expression. The expression ends with a right parenthesis. Every expres-
sion returns a value that can be used by a surrounding expression. The value
of the last interpreted expression is returned to the calling expression.
For example, the following code example involves three functions:
(fun1 (fun2 arguments)(fun3 arguments))
If you enter this code at the Visual LISP Console prompt or the AutoCAD
Command prompt, the AutoCAD AutoLISP interpreter processes the code.
The first function, fun1, has two arguments, and the other functions, fun2
and fun3, each have one argument. The functions fun2 and fun3 are sur-
rounded by function fun1, so their return values are passed to fun1 as
arguments. Function fun1 evaluates the two arguments and returns the value
to the window from which you entered the code.
The following example shows the use of the * (multiplication) function,
which accepts one or more numbers as arguments:
_$ (* 2 27)
54
function name
required argument(s)
optional argument(s) in brackets
In this example, the foo function has one required argument, string, and
one optional argument, number. Additional number arguments can be pro-
vided. Frequently, the name of the argument indicates the expected data
type. The examples in the following table show both valid and invalid calls
to the foo function.
Integers
Integers are whole numbers that do not contain a decimal point. AutoLISP
integers are 32-bit signed numbers with values ranging from +2,147,483,647
to –2,147,483,648. (Note, however, that the getint function only accepts
16-bit numbers ranging from +32767 to -32678.) When you explicitly use an
integer in an AutoLISP expression, that value is known as a constant. Num-
bers such as 2, –56, and 1,200,196 are valid AutoLISP integers.
If you enter a number that is greater than the maximum integer allowed
(resulting in integer overflow), AutoLISP converts the integer to a real num-
ber. However, if you perform an arithmetic operation on two valid integers,
and the result is greater than the maximum allowable integer, the resulting
number will be invalid. The following examples illustrate how AutoLISP han-
dles integer overflow.
The largest positive integer value retains its specified value:
_$ 2147483647
2147483647
If you enter an integer that is greater than the largest allowable value,
AutoLISP returns the value as a real:
_$ 2147483648
2.14748e+009
Reals
A real is a number containing a decimal point. Numbers between –1 and 1
must contain a leading zero. Real numbers are stored in double-precision
floating-point format, providing at least 14 significant digits of precision.
Note that VLISP does not show you all the significant digits.
Reals can be expressed in scientific notation, which has an optional e or E fol-
lowed by the exponent of the number (for example, 0.0000041 is the same
as 4.1e-6). Numbers such as 3.1, 0.23, –56.123, and 21,000,000.0 are valid
AutoLISP reals.
Strings
A string is a group of characters surrounded by quotation marks. Within
quoted strings the backslash (\) character allows control characters (or escape
codes) to be included. When you explicitly use a quoted string in an
AutoLISP expression, that value is known as a literal string or a string
constant.
Examples of valid strings are “string 1” and “\nEnter first point:”.
Lists
An AutoLISP list is a group of related values separated by spaces and enclosed
in parentheses. Lists provide an efficient method of storing numerous related
values. AutoCAD expresses 3D points as a list of three real numbers.
Examples of lists are (1.0 1.0 0.0), (“this” “that” “the other”), and (1 “ONE”).
Entity Names
An entity name is a numeric label assigned to objects in a drawing. It is actu-
ally a pointer into a file maintained by AutoCAD, and can be used to find the
object’s database record and its vectors (if they are displayed). This label can
be referenced by AutoLISP functions to allow selection of objects for process-
ing in various ways. Internally, AutoCAD refers to objects as entities.
The following example uses the entlast function to get the name of the last
object entered into the drawing.
_$ (entlast)
<Entity name: 27f0540>
Entity names assigned to objects in a drawing are only in effect during the
current editing session. The next time you open the drawing, AutoCAD
assigns new entity names to the objects. You can use an object’s handle to
refer to it from one editing session to another; see “Entity Handles and Their
Uses” on page 301 for information on using handles.
VLA-objects
Objects in a drawing may be represented as Visual LISP ActiveX (VLA)
objects, a data type introduced with Visual LISP. When working with ActiveX
functions, you must refer to VLA-objects, not the ename pointer returned by
functions such as entlast. For information on working with ActiveX objects,
see “Using ActiveX Objects with AutoLISP” on page 156.
File Descriptors
A file descriptor is a pointer to a file opened by the AutoLISP open function.
The open function returns this pointer as an alphanumeric label. You supply
the file descriptor as an argument to other AutoLISP functions that read or
write to the file.
( (Open Parenthesis)
) (Close Parenthesis)
. (Period)
’ (Apostrophe)
; (Semicolon)
Be kind to yourself and to others who need to read your code. Choose mean-
ingful names for your program symbols and variables.
If you choose No, the symbol’s value is modified, and processing contin-
ues normally. If you choose Yes, processing is interrupted, and you enter
a Visual LISP break loop. Control switches to the Visual LISP Console
window. To set the symbol and continue processing, press the Continue
button on the Visual LISP toolbar; to abort modification, press Reset.
Error This option prohibits modification of protected symbols. Any
attempt to modify a protected symbol results in an error message.
Comments begin with one or more semicolons (;) and continue through the
end of the line.
; This entire line is a comment
(setq area (* pi r r)) ; Compute area of circle
Any text within ;| ... |; is ignored. Therefore, comments can be included
within a line of code or extend for multiple lines. This type of comment is
known as an in-line comment.
(setq tmode ;|some note here|; (getvar "tilemode"))
The following example shows a comment that continues for multiple lines:
(setvar "orthomode" 1) ;|comment starts here
and continues to this line,
but ends way down here|; (princ "\nORTHOMODE set On.")
It is recommended that you use comments liberally when writing AutoLISP
programs. The tutorial files provided with VLISP contain good examples of
commenting style. If you’ve installed the AutoCAD samples files, you’ll find
the VLISP tutorial code in the Tutorial\VisualLISP directory.
Color Coding
VLISP provides an additional solution to make AutoLISP text easier to read:
color coding. VLISP looks at each word of text and tries to determine what
type of AutoLISP language element the word represents (for example, a built-
in function, a number, or a string). Every type of element is assigned its own
AutoLISP Variables
An AutoLISP variable assumes the data type of the value assigned to it. Until
they are assigned new values, variables retain their original values. You use
the AutoLISP setq function to assign values to variables.
(setq variable_name1 value1 [variable_name2 value2 ...])
The setq function assigns the specified value to the variable name given. It
returns the value as its function result. If you issue setq at the Visual LISP
Console prompt, the result is displayed in the Console window:
_$ (setq val 3 abc 3.875)
3.875
_$ (setq layr "EXTERIOR-WALLS")
"EXTERIOR-WALLS"
_$
To display the value of a variable from the AutoCAD Command prompt, you
must precede the variable name with an exclamation point (!). For example:
Command: !abc
3.875
Predefined Variables
The following predefined variables are commonly used in AutoLISP applica-
tions:
PAUSE Defined as a string consisting of a double backslash (\\)
character. This variable is used with the command function
to pause for user input.
PI Defined as the constant π (pi). It evaluates to
approximately 3.14159.
T Defined as the constant T. This is used as a non-nil value.
NOTE You can change the value of these variables with the setq function.
However, other applications might rely on their values being consistent; there-
fore, it is recommended that you do not modify these variables. Visual LISP, by
default, protects these variables from redefinition. You can override this protec-
tion through the VLISP Symbol Service feature or by setting a VLISP environment
option.
String Handling
AutoLISP provides functions for working with string values. For example, the
strcase function returns the conversion of all alphabetic characters in a
string to uppercase or lowercase. It accepts two arguments: a string and an
optional argument that specifies the case in which the characters are
returned. If the optional second argument is omitted, it evaluates to nil and
strcase returns the characters converted to uppercase.
The strcat function combines multiple strings into a single string value.
This is useful for placing a variable string within a constant string. The fol-
lowing code sets a variable to a string value and then uses strcat to insert
that string into the middle of another string.
_$ (setq str "BIG") (setq bigstr (strcat "This is a " str " test."))
"This is a BIG test."
If the variable bigstr is set to the preceding string value, you can use the
strlen function to find out the number of characters (including spaces) in
that string.
_$ (strlen bigstr)
19
The substr function returns a substring of a string. It has two required argu-
ments and one optional argument. The first required argument is the string.
The second argument is a positive integer that specifies the first character of
the string you want to include in the substring. If the third argument is pro-
vided, it specifies the number of characters to include in the substring. If the
third argument is not provided, substr returns all characters including and
following the specified start character.
As an example, you can use the substr function to strip off the three-letter
extension from a file name (note that you can actually use the
vl-file-name-base function to do this). First, set a variable to a file name.
prin1
princ
print
prompt
These functions are discussed in the following sections. The remaining dis-
play functions are covered in chapter 9, “Using AutoLISP to Communicate
with AutoCAD”, beginning with the “Display Control” topic.
Displaying Messages
When entered from VLISP, the prompt function displays a message (a string)
in the AutoCAD Command window and returns nil to the VLISP Console
window. The princ, prin1, and print functions all display an expression
(not necessarily a string) in the AutoCAD Command window and return the
expression to the VLISP Console window. Optionally, these functions can
send output to a file. The differences are as follows:
The following examples demonstrate the differences between the four basic
output functions and how they handle the same string of text. If you enter
the examples from VLISP, the text following prints is what you see at the
AutoCAD Command prompt; text following returns appears within the VLISP
Console window or within an application. See the following section for an
explanation of the control characters used in the example.
Exiting Quietly
If you invoke the princ function without passing an expression to it, it
displays nothing and has no value to return. So if you write an AutoLISP
expression that ends with a call to princ without any arguments, the ending
nil is suppressed (because it has nothing to return). This practice is called
exiting quietly.
Code Description
\\ \ character
\e Escape character
\n Newline character
\r Return character
\t Tab character
You can also use the terpri function to cause a line break.
The return character (\r) returns to the beginning of the current line. This is
useful for displaying incremental information (for example, a counter show-
ing the number of objects processed during a loop).
The Tab character (\t) can be used in strings to indent or to provide align-
ment with other tabbed text strings. In this example, note the use of the
princ function to suppress the ending nil.
Name Office
––––– –––––
Sue 101
Joe 102
Sam 103
The following code checks whether or not matchme begins with the four char-
acters "this":
_$ (wcmatch matchme "this*")
T
The following code illustrates the use of brackets in the pattern. In this case,
wcmatch returns T if matchme contains "test4" , "test5" , "test6" (4-6), or
"test9" (note the use of the * character):
List Handling
AutoLISP provides functions for working with lists. This section provides
examples of the append, assoc , car, cons, list, nth, and subst functions. A
summary of all list-handling functions is in appendix A, “AutoLISP Function
Synopsis,” under the heading “List Manipulation Functions.” Each list-
handling function is described in the AutoLISP Reference.
Lists provide an efficient and powerful method of storing numerous related
values. After all, LISP is so-named because it is the LISt Processing language.
Once you understand the power of lists, you’ll find that you can create more
powerful and flexible applications.
Several AutoLISP functions provide a basis for programming two-
dimensional and three-dimensional graphics applications. These functions
return point values in the form of a list.
The list function provides a simple method of grouping related items. These
items do not need to be of similar data types. The following code groups
three related items as a list:
_$ (setq lst1 (list 1.0 "One" 1))
(1.0 "One" 1)
The cdr function returns all elements, except the first, from a list. For exam-
ple:
_$ (cdr lst1)
("One" 1)
The car function provides another way to extract items from a list. For more
examples using car and cdr, and combinations of the two, see “Point Lists”
on page 235.
Three functions let you modify an existing list. The append function returns
a list with new items added to the end of it, and the cons function returns a
list with new items added to the beginning of the list. The subst function
returns a list with a new item substituted for every occurrence of an old item.
These functions do not modify the original list, they return a modified list.
To modify the original list, you must explicitly replace the old list with the
new list.
The append function takes any number of lists and runs them together as one
list. Therefore, all arguments to this function must be lists. The following
code adds another "One" to the list lst1. Note the use of the quote (or ')
function as an easy way to make the string "One" into a list.
_$ (setq lst2 (append lst1 '("One")))
(1.0 "One" 1 "One")
The cons function combines a single element with a list. You can add another
string "One" to the beginning of this new list, lst2 , with the cons function.
_$ (setq lst3 (cons "One" lst2 ))
("One" 1.0 "One" 1 "One")
You can substitute all occurrences of an item in a list with a new item with
the subst function. The following code replaces all strings "One" with the
string "one".
_$ (setq lst4 (subst "one" "One" lst3))
("one" 1.0 "one" 1 "one")
The single quotation mark (') can be used as shorthand for the quote func-
tion. The following code produces the same result as the preceding code.
_$ (setq pt1 '(4.5 7.5))
(4.5 7.5)
The car function returns the first member of a list. In this example it returns
the X value of point pt to the x_val variable.
_$ (setq x_val (car pt))
1.5
The cadr function returns the second member of a list. In this example it
returns the Y value of the pt point to the y_val variable.
_$ (setq y_val (cadr pt))
3.2
The caddr function returns the third member of a list. In this example it
returns the Z value of point pt to the variable z_val.
_$ (setq z_val (caddr pt))
2.0
You can use the following code to define the lower-left and upper-right (pt1
and pt2) corners of a rectangle, as follows:
_$ (setq pt1 '(1.0 2.0) pt2 ' (3.0 4.0))
(3.0 4.0)
You can use the car and cadr functions to set the pt3 variable to the upper-
left corner of the rectangle, by extracting the X component of pt1 and the Y
component of pt2, as follows:
_$ (setq pt3 (list (car pt1) (cadr pt2)))
(1.0 4.0)
These concatenations are the equivalent of nested calls to car and cdr. Each
a represents a call to car, and each d represents a call to cdr. For example:
(caar x) is equivalent to (car (car x))
(cdar x) is equivalent to (cdr (car x))
(cadar x) is equivalent to (car (cdr (car x)))
(cadr x) is equivalent to (car (cdr x))
(cddr x) is equivalent to (cdr (cdr x))
(caddr x) is equivalent to (car (cdr (cdr x)))
Dotted Pairs
Another way AutoCAD uses lists to organize data is with a special type of list
called a dotted pair. This list must always contain two members. When rep-
resenting a dotted pair, AutoLISP separates the members of the list with a
period (.). Most list-handling functions will not accept a dotted pair as an
argument, so you should be sure you are passing the right kind of list to a
function.
Dotted pairs are an example of an "improper list." An improper list is one in
which the last cdr is not nil. In addition to adding an item to the beginning
of a list, the cons function can create a dotted pair. If the second argument
to the cons function is anything other than another list or nil, it creates a
dotted pair.
_$ (setq sublist (cons 'lyr "WALLS"))
(LYR . "WALLS")
The car, cdr , and assoc functions are useful for handling dotted pairs. The
following code creates an association list, which is a list of lists, and is the
method AutoCAD uses to maintain entity definition data. (Entity definition
data is discussed in chapter 10, “Using AutoLISP to Manipulate AutoCAD
Objects.”) The following code creates an association list of dotted pairs:
_$ (setq wallinfo (list sublist(cons 'len 240.0) (cons 'hgt 96.0)))
( (LYR . "WALLS") (LEN . 240.0) (HGT . 96.0) )
C:XXX Functions
If an AutoLISP function is defined with a name of the form C:XXX , it can be
issued at the AutoCAD Command prompt in the same manner as a built-in
AutoCAD command. This is true regardless of whether you define and load
the function in VLISP or at the AutoCAD Command prompt. You can use this
feature to add new commands to AutoCAD or to redefine existing
commands.
To use functions as AutoCAD commands, be sure they adhere to the
following rules:
The function name must use the form C:XXX (upper- or lowercase charac-
ters). The C: portion of the name must always be present; the XXX portion
is a command name of your choice. C:XXX functions can be used to
override built-in AutoCAD commands. (See “Redefining AutoCAD Com-
mands” on page 242.)
The function must be defined with no arguments. However, local vari-
ables are permitted and it is a good programming practice to use them.
Adding Commands
Using the C:XXX feature, you can define a command that displays a simple
message.
_$ (defun C:HELLO () (princ "Hello world. \n") (princ))
C:HELLO
HELLO is now defined as a command, in addition to being an AutoLISP func-
tion. This means you can issue the command from the AutoCAD Command
prompt.
Command: hello
Hello world.
This new command can be issued transparently because it does not call the
command function itself. At the AutoCAD Command prompt, you could do
the following:
Command: line
From point: ' hello
Hello world.
From point:
Remember: to run this function from the VLISP Console window, you need
to issue the function call with the parentheses because VLISP does not recog-
nize AutoCAD commands.
_$ (c:hello)
Hello world.
If you follow your function definition with a call to the setfunhelp function,
you can associate a Help file and topic with a user-defined command. When
help is requested during execution of the user-defined command, the topic
specified by setfunhelp displays. See the AutoLISP Reference for more infor-
mation on using setfunhelp.
Command: line
Shouldn’t you be using PLINE?
.LINE Specify first point: Specify first point:
Now if you enter line at the AutoCAD Command prompt, the following
displays:
Shouldn’t you be using PLINE?
Specify first point:
You can use this feature in a drawing management system, for example. You
can redefine the NEW , OPEN, and QUIT commands to write billing informa-
tion to a log file before you terminate the editing session.
It is recommended that you protect your menus, scripts, and AutoLISP pro-
grams by using the period-prefixed forms of all commands. This ensures that
your applications use the built-in command definitions rather than a rede-
fined command.
See the “Command Search Procedure” topic in the AutoCAD Customization
Guide for a description of the steps AutoCAD takes to evaluate command
names.
You can verify that the variables aaa and bbb are actually set to those values.
_$ aaa
1
_$ bbb
2
The ARGTEST function returns the desired value because AutoLISP always
returns the results of the last expression it evaluates. The last line in ARGTEST
uses strcat to concatenate the strings, and the resulting value is returned.
This is one example where you should not use the princ function to suppress
the return value from your program.
This type of function can be used a number of times within an application
to combine two variable strings with one constant string in a specific order.
Because it returns a value, you can save the value to a variable for use later in
the application.
_$ (setq newstr (ARGTEST "String 1" "String 2") )
"Constant string, String 1, String 2"
The newstr variable is now set to the value of the three strings combined.
Special Forms
Certain AutoLISP functions are considered special forms because they evalu-
ate arguments in a different manner than most AutoLISP function calls. A
typical function evaluates all arguments passed to it before acting on those
arguments. Special forms either do not evaluate all their arguments, or only
evaluate some arguments under certain conditions.
The following AutoLISP functions are considered special forms:
AND
COMMAND
COND
DEFUN
DEFUN-Q
FOREACH
FUNCTION
IF
LAMBDA
OR
PROGN
QUOTE
REPEAT
SETQ
TRACE
UNTRACE
VLAX-FOR
WHILE
You can read about each of these functions in the AutoLISP Reference.
Error Handling
The AutoLISP language provides several functions for error handling. You
can use these functions to do the following:
Each argument was evaluated successfully before AutoLISP passed the results
to inters and discovered that too few arguments were specified.
AutoLISP evaluated (foo) , then passed the result to inters. Since the result
was a valid 2D point list, AutoLISP proceeds to evaluate (bar) , where it deter-
mines that the evaluated result is a string, an invalid argument type for
inters.
In this message, text describes the error. However, if the *error* function is
defined (that is, if it is not nil), AutoLISP executes *error* instead of print-
ing the message. The *error* function receives text as its single argument.
If *error* is not defined or is nil, AutoLISP evaluation stops and displays a
traceback of the calling function and its callers. It is beneficial to leave this
error handler in effect while you debug your program.
A code for the last error is saved in the AutoCAD system variable ERRNO,
where you can retrieve it by using the getvar function. See appendix C,
“AutoLISP Error Codes,” for a list of error codes and their meaning.
Before defining your own *error* function, save the current contents of
*error* so that the previous error handler can be restored upon exit. When
an error condition exists, AutoCAD calls the currently defined *error* func-
tion and passes it one argument, which is a text string describing the nature
of the error. Your *error* function should be designed to exit quietly after
an ESC (cancel) or an exit function call. The standard way to accomplish this
is to include the following statements in your error-handling routine.
The function should issue the following prompt in the AutoCAD Command
window:
"An error occurred: divide by zero" Do you want to continue? (Y/N) ->
253
Query and Command Functions
The query and command functions described in this section provide direct
access to AutoCAD commands and drawing services. Their behavior depends
on the current state of the AutoCAD system and environment variables, and
on the drawing that is currently loaded. See “Query and Command Func-
tions” in appendix A, “AutoLISP Function Synopsis,” for a complete list of
query and command functions.
NOTE The AutoLISP examples in this chapter show code entered at the
AutoCAD Command prompt, not the Visual LISP Console window.
Command Submission
The command function sends an AutoCAD command directly to the AutoCAD
Command prompt. The command function has a variable-length argument
list. These arguments must correspond to the types and values expected by
that command’s prompt sequence; these may be strings, real values, integers,
points, entity names, or selection set names. Data such as angles, distances,
and points can be passed either as strings or as the values themselves (as
integer or real values, or as point lists). An empty string ("") is equivalent to
pressing the SPACEBAR or ENTER on the keyboard.
There are some restrictions on the commands that you can use with the
command function. See the AutoLISP Reference definition of this function for
information on these restrictions.
The following code fragment shows representative calls to command.
(command "circle" "0,0" "3,3")
(command "thickness" 1)
(setq p1 '(1.0 1.0 3.0))
(setq rad 4.5)
(command "circle" p1 rad)
If AutoCAD is at the Command prompt when these functions are called,
AutoCAD performs the following actions:
1 The first call to command passes points to the CIRCLE command as strings
(draws a circle centered at 0.0,0.0 and passes through 3.0,3.0).
2 The second call passes an integer to the THICKNESS system variable (changes
the current thickness to 1.0).
NOTE You can use a backslash instead of the PAUSE symbol. However, the
pause mechanism might require a different trigger value in future versions of
AutoLISP, so it is recommended that you always use the PAUSE symbol rather
than an explicit backslash. Also, if the command function is invoked from a menu
item, the backslash suspends the reading of the menu item, which results in par-
tial evaluation of the AutoLISP expression.
The preceding code fragment sets the current layer to NEW_LAY, pauses for
user selection of an insertion point for the block MY_BLOCK (which is
inserted with X and Y scale factors of 1), and pauses again for user selection
of a rotation angle. The current layer is then reset to the original layer.
If the command function specifies a PAUSE to the SELECT command and a
PICKFIRST set is active, the SELECT command obtains the PICKFIRST set with-
out pausing for the user.
Configuration Control
AutoCAD uses the acadxx.cfg file to store configuration information (the xx
in the file name refers to the AutoCAD release number). The AppData section
of this file is provided for users and developers to store configuration infor-
mation pertaining to their applications. The getcfg and setcfg functions
allow AutoLISP applications to inspect and change the value of parameters
in the AppData section.
Display Control
AutoLISP includes functions for controlling the AutoCAD display in both
text and graphics windows. Some functions prompt for, or depend on, input
from the AutoCAD user.
The prompt, princ, prin1 , and print functions are the primary text output
functions. These functions were described in the “AutoLISP Basics” chapter,
under the heading, “Basic Output Functions.”
See “Display Control Functions” in appendix A, “AutoLISP Function
Synopsis,” for a complete list of display control functions.
Controlling Menus
The menucmd function controls the display of the graphics window menus. It
displays, modifies, or queries one of the submenus of the current menu, and
accepts a string argument that specifies the submenu and the action to
perform on that submenu.
The menucmd function takes a string argument that consists of two fields,
separated by an equal sign, in the following form:
"menu_area=action"
NOTE Do not include the dollar sign that introduces the similar instructions in
a menu file in the string argument. Also, do not include the asterisks that pre-
cede submenu labels in the menu file in the action field of the string argument.
The following menucmd function call causes the **OSNAP screen submenu
defined in the current menu file to be displayed (assuming the screen menu
is currently enabled).
(menucmd "S=OSNAP")
In Windows, you can reference the menu group. This can be useful if there
are multiple menus loaded that contain the same submenu name. The fol-
lowing code displays the **OSNAP screen submenu in the ACAD menu group.
(menucmd "S=ACAD.OSNAP")
The menucmd function can load submenus into the BUTTONS and AUX menu
areas. You might want your digitizer buttons to function differently depend-
ing on whether Tablet mode is on or off. You can have two submenus defined
in the ***BUTTONS1 section, **DIG-BUTTONS and **TAB-BUTTONS, and switch
between them with the following code.
(menucmd "B1=DIG-BUTTONS") Enables the DIG-BUTTONS submenu
(menucmd "B1=TAB-BUTTONS") Enables the TAB-BUTTONS submenu
The following code loads the ***POP0 menu into the P0 (cursor) menu area
and displays it.
(menucmd "P0=POP0") Loads the ***POP0 menu into the P0 menu area
(menucmd "P0=*") Displays it
If your menu uses the disabling (graying-out) and marking features, you can
retrieve and change the state of a menu label with the menucmd function. The
following call retrieves the current state of the fourth label in the pull-down
menu P2.
(menucmd "P2.4=#?") If disabled returns "P2.4=~"
The following sequence restores the default graphics window display caused
by incorrect calls to grtext, grdraw, or grvecs:
(grtext) Restores standard text
(redraw)
getpoint A point value on the command line or selected from the screen
getcorner A point value (the opposite corner of a box) on the command line or
selected from the screen
getangle An angle value (in the current angle format) on the command line or
based on selected points on the screen
getorient An angle value (in the current angle format) on the command line or
based on selected points on the screen
NOTE Although the getvar, getcfg, and getenv functions begin with the let-
ters g, e, and t, they are not user-input functions. They are discussed in “Query
and Command Functions” on page 254.
The functions getint, getreal, and getstring pause for user input on the
AutoCAD command line. They return a value only of the same type as that
requested.
The getpoint, getcorner, and getdist functions pause for user input on the
command line or from points selected on the graphics screen. The getpoint
and getcorner functions return 3D point values, and getdist returns a real
value.
Both getangle and getorient pause for input of an angle value on the com-
mand line or as defined by points selected on the graphics screen. For the
getorient function, the 0 angle is always to the right: “East” or “3 o’clock.”
For getangle, the 0 angle is the value of ANGBASE, which can be set to any
angle. Both getangle and getorient return an angle value (a real) in radians
measured counterclockwise from a base (0 angle), for getangle equal to
ANGBASE, and for getorient to the right.
0 0.0 1.5708
90 4.71239 0.0
ANGBASE = 90
input
angle = -90 input
angle = 90
input
angle = 180
The getangle function honors the settings of ANGDIR and ANGBASE when
accepting input. You can use getangle to obtain a rotation amount for a
block insertion, because input of 0 degrees always returns 0 radians. The
getorient function honors only ANGDIR. You use getorient to obtain angles
such as the baseline angle for a text object. For example, given the preceding
settings of ANGBASE and ANGDIR, for a line of text created at an angle of 0,
getorient returns an angle value of 90.
This can be confusing, because the original prompt may have scrolled out of
the Command prompt area.
The AutoCAD user cannot typically respond to a user-input function by
entering an AutoLISP expression. If your AutoLISP routine makes use of the
initget function, arbitrary keyboard input is permitted to certain functions
that can allow an AutoLISP statement as response to a command imple-
mented in AutoLISP. This is discussed in “Arbitrary Keyboard Input” on page
267.
This sequence requests the user’s age. AutoCAD displays an error message
and repeats the prompt if the user attempts to enter a negative or zero value,
press ENTER only, or enter a string (the getint function rejects attempts to
enter a value that is not an integer).
Keyword Options
The optional string argument specifies a list of keywords recognized by the
next user-input function call.
The initget function allows keyword abbreviations to be recognized in
addition to the full keywords. The user-input function returns a predefined
keyword if the input from the user matches the spelling of a keyword (not
case sensitive), or if the user enters the abbreviation of a keyword. There are
two methods for abbreviating keywords; both are discussed in the initget
topic in the AutoLISP Reference.
The following user-defined function shows a call to getreal, preceded by a
call to initget , that specifies two keywords. The application checks for these
keywords and sets the input value accordingly.
(defun C:GETNUM (/ num)
(initget 1 "Pi Two-pi")
(setq num (getreal "Pi/Two-pi/<number>: "))
(cond
((eq num "Pi") pi)
((eq num "Two-pi") (* 2.0 pi))
(T num)
)
)
This initget call inhibits null input ( bits = 1) and establishes a list of two
keywords, "Pi" and "Two-pi". The getreal function is then used to obtain a
real number, issuing the following prompt:
Pi/Two-pi/<number>:
NOTE You can also use initget to enable entsel, nentsel, and nentselp to
accept keyword input. For more information on these functions, see “Object
Handling” on page 299 and the entsel, nentsel, and nentselp function defini-
tions in the AutoLISP Reference.
Geometric Utilities
A group of functions allows applications to obtain pure geometric informa-
tion and geometric data from the drawing. See “Geometric Functions” in
appendix A, “AutoLISP Function Synopsis,” for a complete list of geometric
utility functions.
The angle function finds the angle in radians between a line and the X axis
(of the current UCS), distance finds the distance between two points, and
polar finds a point by means of polar coordinates (relative to an initial
point). The inters function finds the intersection of two lines. The osnap
and textbox functions are described separately.
The following code fragment shows calls to the geometric utility functions:
(setq pt1 ’(3.0 6.0 0.0))
(setq pt2 ’(5.0 2.0 0.0))
(setq base ’(1.0 7.0 0.0))
(setq rads (angle pt1 pt2)) ; Angle in XY plane of current UCS
; (value is returned in radians)
(setq len (distance pt1 pt2)) ; Distance in 3D space
(setq endpt (polar base rads len))
The call to polar sets endpt to a point that is the same distance from (1,7) as
pt1 is from pt2, and at the same angle from the X axis as the angle between
pt1 and pt2.
Object Snap
The osnap function can find a point by using one of the AutoCAD Object
Snap modes. The Snap modes are specified in a string argument.
The following call to osnap looks for the midpoint of an object near pt1:
(setq pt2 (osnap pt1 "midp"))
Text Extents
The textbox function returns the diagonal coordinates of a box that encloses
a text object. It takes an entity definition list of the type returned by entget
(an association list of group codes and values) as its single argument. This list
can contain a complete association list description of the text object or just
a list describing the text string.
The points returned by textbox describe the bounding box (an imaginary
box that encloses the text object) of the text object, as if its insertion point
were located at (0,0,0) and its rotation angle were 0. The first list returned is
the point (0.0 0.0 0.0), unless the text object is oblique or vertical or it con-
tains letters with descenders (such as g and p). The value of the first point list
specifies the offset distance from the text insertion point to the lower-left
corner of the smallest rectangle enclosing the text. The second point list spec-
ifies the upper-right corner of that box. The returned point lists always
describe the bottom-left and upper-right corners of this bounding box,
regardless of the orientation of the text being measured.
The following example shows the minimum allowable entity definition list
that textbox accepts. Because no additional information is provided,
textbox uses the current defaults for text style and height.
The actual values returned by textbox will vary depending on the current
text style.
Command: (textbox e)
((0.0 0.0 0.0) (0.8 0.2 0.0))
The following figure shows the results of applying textbox to a text object
with a height of 1.0. The figure also shows the baseline and insertion point
of the text.
top right:
(5.5,1.0)
insertion
point: (0,0) baseline
If the text is vertical or rotated, pt1 is still the bottom-left corner and pt2 is
the upper-right corner; the bottom-left point may have negative offsets if
necessary.
The following figure shows the point values (pt1 and pt2) that textbox
returns for samples of vertical and aligned text. In both samples, the height
of the letters is 1.0. (For the aligned text, the height is adjusted to fit the
alignment points.)
pt1 = 0.263416,0.0,0.0
When using vertical text styles, the points are still returned in left-to-right,
bottom-to-top order as they are for horizontal styles, so that the first point
list will contain negative offsets from the text insertion point.
insertion
point: (0,0) pt2 = 1.0, 0.0
pt1 =
-0.5,-20.0
Regardless of the text orientation or style, the points returned by textbox are
such that the text insertion point (group code 10) directly translates to the
origin point of the object coordinate system (OCS) for the associated text
object. This point can be referenced when translating the coordinates
returned from textbox into points that define the actual extent of the text.
The two sample routines that follow use textbox to place a box around
selected text regardless of its orientation.
Conversions
The functions described in this section are utilities for converting data types
and units. See “Conversion Functions” in appendix A, “AutoLISP Function
Synopsis,” for a complete list of conversion functions.
String Conversions
The functions rtos (real to string) and angtos (angle to string) convert
numeric values used in AutoCAD to string values that can be used in output
or as textual data. The rtos function converts a real value, and angtos con-
verts an angle. The format of the result string is controlled by the value of
AutoCAD system variables: the units and precision are specified by LUNITS
and LUPREC for real (linear) values and by AUNITS and AUPREC for angular
values. For both functions, the dimensioning variable DIMZIN controls how
leading and trailing zeros are written to the result string.
The following code fragments show calls to rtos and the values returned
(assuming the DIMZIN system variable equals 0). Precision (the third argu-
ment to rtos) is set to 4 places in the first call and 2 places in the others.
(setq x 17.5)
(setq str "\nValue formatted as ")
(setq fmtval (rtos x 1 4)) ; Mode 1 = scientific
(princ (strcat str fmtval)) ; displays Value formatted as 1.7500E+01
(setq fmtval (rtos x 2 2)) ; Mode 2 = decimal
(princ (strcat str fmtval)) ; displays Value formatted as 17.50
(setq fmtval (rtos x 3 2)) ; Mode 3 = engineering
(princ (strcat str fmtval)) ; displays Value formatted as 1’-5.50"
(setq fmtval (rtos x 4 2)) ; Mode 4 = architectural
(princ (strcat str fmtval)) ; displays Value formatted as 1’-5 1/2"
(setq fmtval (rtos x 5 2)) ; Mode 5 = fractional
(princ (strcat str fmtval)) ; displays Value formatted as 17 1/2
Conversions | 273
When the UNITMODE system variable is set to 1, specifying that units are dis-
played as entered, the string returned by rtos differs for engineering (mode
equals 3), architectural (mode equals 4), and fractional (mode equals 5) units.
For example, the first two lines of the preceding sample output would be the
same, but the last three lines would appear as follows:
Value formatted as 1’5.50"
Value formatted as 1’5-1/2"
Value formatted as 17-1/2''
Because the angtos function takes the ANGBASE system variable into account,
the following code always returns "0" :
(angtos (getvar "angbase"))
There is no AutoLISP function that returns a string version (in the current
mode/precision) of either the amount of rotation of ANGBASE from true zero
(East) or an arbitrary angle in radians.
To find the amount of rotation of ANGBASE from AutoCAD zero (East) or the
size of an arbitrary angle, you can do one of the following:
Add the desired angle to the current ANGBASE, and then check to see if the
absolute value of the result is greater than 2π (2 * pi). If so, subtract 2π; if
the result is negative, add 2π, then use the angtos function on the result.
Store the value of ANGBASE in a temporary variable, set ANGBASE to 0, eval-
uate the angtos function, then set ANGBASE to its original value.
Subtracting the result of (atof (angtos 0)) from 360 degrees (2π radians or
400 grads) also yields the rotation of ANGBASE from 0.
The distof (distance to floating point) function is the complement of rtos.
Therefore, the following calls, which use the strings generated in the previ-
ous examples, all return the same value: 17.5. (Note the use of the backslash
(\) with modes 3 and 4.)
(distof "1.7500E+01" 1) ; Mode 1 = scientific
(distof "17.50" 2) ; Mode 2 = decimal
(distof "1’-5.50\"" 3) ; Mode 3 = engineering
(distof "1’-5 1/2\"" 4) ; Mode 4 = architectural
(distof "17 1/2" 5) ; Mode 5 = fractional
The following code fragments show similar calls to angtos and the values
returned (still assuming that DIMZIN equals 0). Precision (the third argument
to angtos) is set to 0 places in the first call, 4 places in the next three calls,
and 2 places in the last.
Angular Conversion
If your application needs to convert angular values from radians to degrees,
you can use the angtos function, which returns a string, and then convert
that string into a floating point value with atof .
(setq pt1 ’(1 1) pt2 ’(1 2))
(setq rad (angle pt1 pt2))
(setq deg (atof (angtos rad 0 2))) returns 90.0
However, a more efficient method might be to include a Radian->Degrees
function in your application. The following code shows this:
; Convert value in radians to degrees
(defun Radian->Degrees (nbrOfRadians)
(* 180.0 (/ nbrOfRadians pi))
)
Conversions | 275
After this function is defined, you can use the Radian->Degrees function
throughout your application, as in
(setq degrees (Radian->Degrees rad)) returns 90.0
You may also need to convert from degrees to radians. The following code
shows this:
; Convert value in degrees to radians
(defun Degrees->Radians (numberOfDegrees)
(* pi (/ numberOfDegrees 180.0))
) ;_ end of defun
Unit Conversion
The acad.unt file defines various conversions between real-world units such
as miles to kilometers, Fahrenheit to Celsius, and so on. The function cvunit
takes a value expressed in one system of units and returns the equivalent
value in another system. The two systems of units are specified by strings
containing expressions of units defined in acad.unt.
The cvunit function does not convert incompatible dimensions. For exam-
ple, it does not convert inches into grams.
The first time cvunit converts to or from a unit during a drawing editor ses-
sion, it must look up the string that specifies the unit in acad.unt. If your
application has many values to convert from one system of units to another,
it is more efficient to convert the value 1.0 by a single call to cvunit and then
use the returned value as a scale factor in subsequent conversions. This works
for all units defined in acad.unt, except temperature scales, which involve an
offset as well as a scale factor.
Conversions | 277
Converting from Inches to Meters
If the current drawing units are engineering or architectural (feet and inches),
the following routine converts a user-specified distance of inches into
meters:
(defun C:I2M ( / eng_len metric_len eng metric)
(princ "\nConverting inches to meters. ")
(setq eng_len
(getdist "\nEnter a distance in inches: "))
(setq metric_len (cvunit eng_len "inches" "meters"))
(setq eng (rtos eng_len 2 4)
metric (rtos metric_len 2 4))
(princ
(strcat "\n\t" eng " inches = " metric " meters."))
(princ)
)
You can make new units available by using a text editor to add their defini-
tions to acad.unt. A definition consists of two lines in the file—the unit name
and the unit definition. The first line must have an asterisk (*) in the first
column, followed by the name of the unit. A unit name can have several
abbreviations or alternate spellings, separated by commas. If a unit name has
singular and plural forms, you can specify these using the following format:
*[ [common] [ ( [singular.] plural) ] ]...
You can specify multiple expressions (singular and plural). They don’t have
to be located at the end of the word, and a plural form isn’t required. The fol-
lowing are examples of valid unit name definitions:
*inch(es)
*milleni(um.a)
*f(oot.eet) or (foot.feet)
The line following the *unit name line defines the unit as either fundamental
or derived.
( 1c x h x 1m ) x (4.1214856 x 1011)
Derived Units
A derived unit is defined in terms of other units. If the line following the
*unit name line begins with an equal sign (=), it defines derived units. Valid
operators in these definitions are * (multiplication), / (division),
+ (addition), – (subtraction), and ^ (exponentiation). You can specify a
predefined unit by naming it, and you can use abbreviations (if provided).
The items in a formula are multiplied together unless some other arithmetic
operator is specified. For example, the units database defines the dimension-
less multiple and submultiple names, so you can specify a unit such as
micro-inches by entering micro inch. The following are examples of derived
unit definitions.
Conversions | 279
; Units of area
*township(s)
=93239571.456 meter^2
The definition of a township is given as 93,239,571.456 square meters.
; Electromagnetic units
*volt(s),v
=watt/ampere
In this example, a volt is defined as a watt divided by an ampere. In the
acad.unt, both watts and amperes are defined in terms of fundamental units.
User Comments
To include comments, begin the line with a semicolon. The comment con-
tinues to the end of the line.
; This entire line is a comment.
List the acad.unt file itself for more information and examples.
The following AutoCAD coordinate systems can be specified by the from and
to arguments:
Conversions | 281
PSDCS Paper space DCS—this coordinate system can be
transformed only to or from the DCS of the currently
active model space viewport. This is essentially a 2D
transformation, where the X and Y coordinates are always
scaled and are offset if the disp argument is 0. The Z
coordinate is scaled but is never translated. Therefore, it
can be used to find the scale factor between the two
coordinate systems. The PSDCS (integer code 2) can be
transformed only into the current model space viewport.
If the from argument equals 3, the to argument must
equal 2, and vice versa.
Both the from and to arguments can specify a coordinate system in any of the
following ways:
As an integer code that specifies the WCS, current UCS, or current DCS (of
either the current viewport or paper space).
As an entity name returned by one of the entity name or selection set
functions described in “Using AutoLISP to Manipulate AutoCAD Objects.”
This specifies the OCS of the named object. For planar objects, the OCS
can differ from the WCS, as described in the AutoCAD User’s Guide. If the
OCS does not differ, conversion between OCS and WCS is an identity
operation.
As a 3D extrusion vector. Extrusion vectors are always represented in
World coordinates; an extrusion vector of (0,0,1) specifies the WCS itself.
The following table lists the valid integer codes that can be used as the to and
from arguments:
0 World (WCS)
The following example translates a point from the WCS into the current
UCS.
Point Transformations
If you are doing point transformations with the trans function and you need
to make that part of a program run faster, you can construct your own
transformation matrix on the AutoLISP side by using trans once to trans-
form each of the basis vectors (0 0 0), (1 0 0), (0 1 0), and (0 0 1). Writing
matrix multiplication functions in AutoLISP can be difficult, so it may not be
worthwhile unless your program is doing a lot of transformations.
File Handling
AutoLISP provides functions for handling files and data I/O. See “File-
Handling Functions” in appendix A, “AutoLISP Function Synopsis,” for a
complete list of file-handling functions.
File Search
An application can use the findfile function to search for a particular file
name. The application can specify the directory to search, or it can use the
current AutoCAD library path.
In the following code fragment, findfile searches for the requested file
name according to the AutoCAD library path:
(setq refname "refc.dwg")
(setq fil (findfile refname))
(if fil
(setq refname fil)
(princ (strcat "\nCould not find file " refname ". " ))
)
If the call to findfile is successful, the variable refname is set to a fully qual-
ified path name string, as follows:
"/home/work/ref/refc.dwg"
NOTE You cannot use !dfil in a dialog box. It is valid only at the command
line.
See the Customization Guide for information on creating and modifying help
files.
The setfunhelp function provides help for user-defined commands. After
the definition of your new command, adding a call to setfunhelp associates
a specific help file and topic with that command. The following example
assigns the help topic “Mycmd” in the file morehelp.hlp to the user-defined
MYCMD command:
(defun C:MYCMD ( )
.
. Command definition
.
)
(setfunhelp c:mycmd "morehelp.hlp" "mycmd")
NOTE The TABMODE system variable controls whether Tablet mode is turned
on (1) or off (0). You can control it by using the setvar function.
The following sample routine retrieves the current tablet calibration and
stores it in the variable tcal:
(defun C:TABGET ( )
(setq tcal (tablet 0))
(if tcal
(princ
(strcat "\nConfiguration saved, "
"use TABSET to retrieve calibration.")
)
(princ "\nCalibration not obtainable ")
)
(princ)
)
If the preceding routine was successful, the symbol tcal now contains the list
returned by the tablet function. This list might appear as follows:
(1 (0.00561717 -0.000978942 -7.5171)
(0.000978942 0.00561717 -9.17308)
(0.0 0.0 1.0)
(0.0 0.0 1.0)
)
To turn the resulting vector back into a 2D point, the first two components
are divided by the third component (the scale factor D’) yielding the point
(X’/D’,Y’/D’).
For projective transformations, the most general case, tablet does the full
calculation. But for affine and orthogonal transformations, M 20 and M21 are
both 0, so D’ would be 1.0. The calculation of D’ and the division are omit-
ted; the resulting 2D point is simply (X’,Y’).
NOTE When you set a calibration, the list returned does not equal the list pro-
vided if the direction isn’t normalized. AutoCAD normalizes the direction vector
before it returns it. Also, it ensures the third element in the third column
(row3[Z]) is equal to 1. This situation should not arise if you set the calibration
by using values retrieved from AutoCAD by means of tablet. However, it can
happen if your program calculates the transformation itself.
288
Using AutoLISP to
Manipulate AutoCAD
Objects
10
Most AutoLISP functions that handle selection sets and In this chapter
objects identify a set or an object by the entity name. Selection Set Handling
289
Selection Set Handling
AutoLISP provides a number of functions for handling selection sets. For a
complete list of selection set functions, see “Selection Set Manipulation
Functions” in appendix A, “AutoLISP Function Synopsis.”
The ssget function provides the most general means of creating a selection
set. It can create a selection set in one of the following ways:
Explicitly specifying the objects to select, using the Last, Previous, Win-
dow, Implied, WPolygon, Crossing, CPolygon, or Fence options
Specifying a single point
Selecting the entire database
Prompting the user to select objects
With any option, you can use filtering to specify a list of attributes and con-
ditions that the selected objects must match.
NOTE Selection set and entity names are volatile. That is, they apply only to
the current drawing session.
The first argument to ssget is a string that describes which selection option
to use. The next two arguments, pt1 and pt2, specify point values for the rel-
evant options (they should be left out if they don’t apply). A point list,
pt-list, must be provided as an argument to the selection methods that
allow selection by polygons (that is, Fence, Crossing Polygon, and Window
Polygon). The last argument, filter-list , is optional. If filter-list is sup-
plied, it specifies the list of entity field values used in filtering. For example,
you can obtain a selection set that includes all objects of a given type, on a
given layer, or of a given color. Selection filters are described in more detail
in “Selection Set Filter Lists” on page 292.
See the ssget entry in the AutoLISP Reference for a list of the available selec-
tion methods and the arguments used with each.
SSGET Examples
(setq pt1 '(0.0 0.0 0.0) Sets pt1, pt2, pt3, and pt4 to point values
pt2 '(5.0 5.0 0.0)
pt3 '(4.0 1.0 0.0)
pt4 '(2.0 6.0 0.0))
(setq ss1 (ssget)) Asks the user for a general object selection and
places those items in a selection set
(setq ss1 (ssget "P")) Creates a selection set from the most recently
created selection set
(setq ss1 (ssget "L")) Creates a selection set of the last object added to
the database that is visible on the screen
(setq ss1 (ssget "W" pt1 pt2)) Creates a selection set of the objects inside the
window from (0,0) to (5,5)
(setq ss1 (ssget "F" (list pt2 Creates a selection set of the objects crossing the
pt3 pt4))) fence and defined by the points (5,5), (4,1),
and (2,6)
(setq ss1 (ssget "WP" (list Creates a selection set of the objects inside the
pt1 pt2 pt3))) polygon defined by the points (0,0), (5,5),
and (4,1)
(setq ss1 (ssget "X")) Creates a selection set of all objects in the
database
(setq ss1 (ssget '((0 . "TEXT"))) Prompts for general object selection but
) adds only text objects to the selection set.
(setq ss1 (ssget "P" Creates a selection set containing all line
'((0 . "LINE"))) objects from the last selection set created.
)
(setq ss1 (ssget "W" pt1 pt2 Creates a selection set of all objects inside
'((8 . "FLOOR9"))) the window that are also on layer
) FLOOR9.
(setq ss1 (ssget "X" Creates a selection set of all objects in the
'((0 . "CIRCLE"))) database that are Circle objects.
)
(ssget "I" ‘((0 . "LINE") Creates a selection set of all blue Line
(62 . 5))) objects that are part of the Implied
selection set (those objects selected while
PICKFIRST is in effect).
Note that this filter picks up lines that
have been assigned color 5 (blue), but
not blue lines that have had their color
applied by the ByLayer or ByBlock
properties.
If both the code and the desired value are known, the list may be quoted as
shown previously. If either is specified by a variable, the list must be con-
structed using the list and cons function. For example, the following code
creates a selection set of all objects in the database that are on layer FLOOR3:
(setq lay_name "FLOOR3")
(setq ss1
(ssget "X"
(list (cons 8 lay_name))
)
)
If the filter-list specifies more than one property, an entity is included in
the selection set only if it matches all specified conditions, as in the following
example:
(ssget "X" (list (cons 0 "CIRCLE")(cons 8 lay_name)(cons 62 1)))
This code selects only Circle objects on layer FLOOR3 that are colored red.
This type of test performs a Boolean “AND” operation. Additional tests for
object properties are described in “Logical Grouping of Filter Tests” on page
296.
The ssget function filters a drawing by scanning the selected entities and
comparing the fields of each main entity against the specified filtering list. If
an entity’s properties match all specified fields in the filtering list, it is
included in the returned selection set. Otherwise, the entity is not included
in the selection set. The ssget function returns nil if no entities from those
selected match the specified filtering criteria.
When ssget filters a drawing, the selection set it retrieves might include
entities from both paper space and model space. However, when the selec-
tion set is passed to an AutoCAD command, only entities from the space that
is currently in effect are used. (The space to which an entity belongs is spec-
ified by the value of its 67 group. Refer to the Customization Guide for further
information.)
Operator Description
"=" Equals
The use of relational operators depends on the kind of group you are testing:
All relational operators except for the bitwise operators ("&" and "&=") are
valid for both real- and integer-valued groups.
Starting Ending
operator Encloses operator
The grouping operators are specified by –4 groups, like the relational opera-
tors. They are paired and must be balanced correctly in the filter list or the
ssget call will fail. An example of grouping operators in a filter list follows:
(ssget "X"
’(
(-4 . "<OR")
(-4 . "<AND")
(0 . "CIRCLE")
(40 . 1.0)
(-4 . "AND>")
(-4 . "<AND")
Grouping operators are not allowed within the –3 group. Multiple applica-
tion names specified in a –3 group use an implied AND operator. If you want
to test for extended data using other grouping operators, specify separate –3
groups and group them as desired. To select all circles having extended data
for either application "APP1" or "APP2" but not both, enter the following:
(ssget "X"
’((0 . "CIRCLE")
(-4 . "<XOR")
(-3 ("APP1"))
(-3 ("APP2"))
(-4 . "XOR>")
)
)
You can simplify the coding of frequently used grouping operators by setting
them equal to a symbol. The previous example could be rewritten as follows
(notice that in this example you must explicitly quote each list):
(setq <xor ’(-4 . "<XOR")
xor> ’(-4 . "XOR>") )
(ssget "X"
(list
’(0 . "CIRCLE")
<xor
’(-3 ("APP1"))
’(-3 ("APP2"))
xor>
)
)
As you can see, this method may not be sensible for short pieces of code but
can be beneficial in larger applications.
If you want the original selection set to be protected from garbage collection,
then you must not assign the return value of the ObjectARX application to
the AutoLISP variable that already references the selection set. Changing the
previous example prevents the selection set referenced by var1 from being
eligible for garbage collection.
(setq var1 (ssget))
(setq var2 (adsfunc var1))
Object Handling
AutoLISP provides functions for handling objects. The object-handling func-
tions are organized into two categories: functions that retrieve the entity
name of a particular object, and functions that retrieve or modify entity data.
See “Object-Handling Functions” in appendix A, “AutoLISP Function
Synopsis,” for a complete list of the object-handling functions.
(while one_ent
.
. ; Processes new entity.
.
(setq one_ent (entnext one_ent))
) ; Value of one_ent is now nil.
In another editing session with the same drawing, the fragment might
display an entirely different number. But in both cases the code would be
accessing the same entity.
The handent function has an additional use. Entities deleted from the data-
base (with entdel , described in the following section) are not purged until
the current drawing ends. This means that handent can recover the names of
deleted entities, which can then be restored to the drawing by a second call
to entdel.
Entities in drawings that are cross-referenced by way of XREF Attach are not
actually part of the current drawing; their handles are unchanged but cannot
be accessed by handent. However, when drawings are combined by means of
INSERT, INSERT *, XREF Bind (XBIND), or partial DXFIN, the handles of entities
in the incoming drawing are lost, and incoming entities are assigned new
handle values to ensure each handle in the current drawing remains unique.
Then, insert the block in a UCS rotated 45 degrees about the Z axis:
Command: ucs
Current ucs name: *WORLD*
Enter option[New/Move/orthoGraphic/Prev/Restore/Save/Del/Apply/?/World]
<World>: z
Specify rotation angle about Z axis <0>: 45
Command: -insert
Enter block name or [?]: square
Specify insertion point or [Scale/X/Y/Z/Rotate/PScale/PX/PY/PZ/PRotate]: 7,0
Enter X scale factor, specify opposite corner, or [Corner/XYZ] <1>: ENTER
Enter Y scale factor <use X scale factor>: ENTER
Specify rotation angle <0>: ENTER
NOTE This is the only AutoLISP function that uses a matrix of this type. The
nentselp function is preferred to nentsel because it returns a matrix similar to
those used by other AutoLISP and ObjectARX functions.
Using the entity name previously obtained with nentsel , the following
example illustrates how to obtain the MCS start point of a line (group
code 10) contained in a block definition:
Command: (setq edata (assoc 10 (entget (car ndata))))
Deleting an Entity
The entdel function deletes a specified entity. The entity is not purged from
the database until the end of the current drawing session, so if the applica-
tion calls entdel a second time during that session and specifies the same
entity, the entity is undeleted.
Layer is 0
Linetype is CONTINUOUS
Elevation is 0
The user has drawn a line with the following sequence of commands:
Command: line
From point: 1,2
To point: 6,6
To point: ENTER
An AutoLISP application can retrieve and print the definition data for the
line by using the following AutoLISP function:
(defun C:PRINTDXF ( )
(setq ent (entlast)) ; Set ent to last entity.
(setq entl (entget ent)) ; Set entl to association list of
; last entity.
(setq ct 0) ; Set ct (a counter) to 0.
(textpage) ; Switch to the text screen.
(princ "\nentget of last entity:")
(repeat (length entl) ; Repeat for number of members in list:
(print (nth ct entl)) ; Print a newline, then each list
; member.
(setq ct (1+ ct)) ; Increments the counter by one.
)
(princ) ; Exit quietly.
)
The –1 item at the start of the list contains the name of the entity. The entmod
function, which is described in this section, uses the name to identify the
entity to be modified. The individual dotted pairs that represent the values
can be extracted by using assoc with the cdr function.
Sublists for points are not represented as dotted pairs like the rest of the val-
ues returned. The convention is that the cdr of the sublist is the group’s
value. Because a point is a list of two or three reals, the entire group is a three-
(or four-) element list. The cdr of the group is the list representing the point,
so the convention that cdr always returns the value is preserved.
The codes for the components of the entity are those used by DXF. As with
DXF, the entity header items (color, linetype, thickness, the attributes-follow
flag, and the entity handle) are returned only if they have values other than
the default. Unlike DXF, optional entity definition fields are returned
whether or not they equal their defaults and whether or not associated X, Y,
and Z coordinates are returned as a single point variable, rather than as sep-
arate X (10), Y (20), and Z (30) groups.
All points associated with an object are expressed in terms of that object’s
object coordinate system (OCS). For point, line, 3D line, 3D face,
3D polyline, 3D mesh, and dimension objects, the OCS is equivalent to the
WCS (the object points are World points). For all other objects, the OCS can
be derived from the WCS and the object’s extrusion direction (its 210 group).
When working with objects that are drawn using coordinate systems other
than the WCS, you may need to convert the points to the WCS or to the cur-
rent UCS by using the trans function.
Modifying an Entity
The entmod function modifies an entity. It passes a list that has the same for-
mat as a list returned by entget but with some of the entity group values
(presumably) modified by the application. This function complements
entget. The primary mechanism by which an AutoLISP application updates
the database is by retrieving an entity with entget, modifying its entity list,
and then passing the list back to the database with entmod.
The following code fragment retrieves the definition data of the first entity
in the drawing and changes its layer property to MYLAYER.
(setq en (entnext)) ; Sets en to first entity name
; in the drawing.
(setq ed (entget en)) ; Sets ed to the entity data
; for entity name en.
(setq ed
(subst (cons 8 "MYLAYER")
(assoc 8 ed) ; Changes the layer group in ed.
ed ; to layer MYLAYER.
)
)
(entmod ed) ; Modifies entity en’s layer in
; the drawing.
There are restrictions on the changes to the database that entmod can make;
entmod cannot change the following:
The entmod function can modify subentities such as polyline vertices and
block attributes.
If you use entmod to modify an entity in a block definition, this affects all
INSERT or XREF references to that block. Also, entities in block definitions
cannot be deleted by entdel.
The first or second member in the list must specify the entity type. The
type must be a valid DXF group code. If the first member does not specify
the type, it can specify only the name of the entity: group –1 (the name is
not saved in the database).
AutoCAD must recognize all objects that the entity list refers to. There is
one exception: entmake accepts new layer names.
Any internal fields passed to entmake are ignored.
entmake cannot create viewport entities.
The following table identifies the entities that do not require subentity
marker entries in the list passed to entmake:
3DFACE ARC
ATTDEF ATTRIB
CIRCLE DIMENSION
INSERT LINE
SEQEND SHAPE
SOLID TEXT
TRACE VERTEX
VIEWPORT
NOTE Before you use entmake to create a block, you should use tblsearch to
ensure that the name of the new block is unique. The entmake function does not
check for name conflicts in the block definitions table, so it can redefine existing
blocks. See “Symbol Table and Dictionary Access” on page 326 for information
on using tblsearch.
You must also scan each block definition for instances of nested blocks.
Anonymous Blocks
The block definitions (BLOCK) table in a drawing can contain anonymous
blocks (also known as unnamed blocks), which AutoCAD creates to support
hatch patterns and associative dimensioning. The entmake function can cre-
ate anonymous blocks other than *Dnnn (dimensions) and *Xnnn (hatch
patterns). Unreferenced anonymous blocks are purged from the BLOCK defi-
nition table when a drawing is opened. Referenced anonymous blocks (those
that have been inserted) are not purged. You can use entmake to create a block
reference (insert object) to an anonymous block. (You cannot pass an anony-
mous block to the INSERT command.) Also, you can use entmake to redefine
the block. You can modify the entities in a block (but not the block object
itself) with entmod .
Symbol table entries can be created through entmake with few restrictions,
other than being valid record representations, and name conflicts can
only occur in the VPORT table. *ACTIVE entries cannot be created.
Symbol table entries cannot be deleted with entdel.
Symbol table and symbol table entry object states may be accessed with
entget by passing the entity name. The tblobjname function can be used
to retrieve the entity name of a symbol table entry.
Symbol tables themselves cannot be created with entmake, however,
symbol table entries can be created with entmake.
Handle groups (5, 105) may not be changed in entmod , nor specified in
entmake.
Symbol table entries that are not in the APPID table can have many of
their fields modified with entmod. To be passed to entmod, a symbol table
record list must include its entity name, which can be obtained from
entget but not from the tblsearch and tblnext functions. The 70 group
of symbol table entries is ignored in entmod and entmake operations.
VPORT *ACTIVE
LINETYPE CONTINUOUS
LAYER Entries may not be modified, except for xdata, but renaming is
allowed
The following entries may not be renamed but are otherwise modifiable, sub-
ject to restriction:
STYLE STANDARD
DIMSTYLE STANDARD
BLOCKS *MODEL_SPACE
BLOCKS *PAPER_SPACE
Dictionary Objects
The following rules apply to dictionary objects:
Dictionary objects can be examined with entget and their xdata modified
with entmod. Their entries cannot be altered with entmod. All access to
their entries are made through the dictsearch and dictnext functions.
Dictionary entry contents cannot be modified through entmod, although
xdata can be modified.
Dictionary entries that begin with ACAD* cannot be renamed.
Registration of an Application
To be recognized by AutoCAD, an application must register the name or
names that it uses. Application names are saved with the extended data of
each entity that uses them, and also in the APPID table. Registration is done
with the regapp function, which specifies a string to use as an application
name. If it successfully adds the name to APPID, it returns the name of the
application; otherwise it returns nil. A result of nil indicates that the name
is already present in the symbol table. This is not an actual error condition
but an expected return value, because the application name needs to be reg-
istered only once per drawing.
To register itself, an application should first check that its name is not already
in the APPID table. If the name is not there, the application must register it.
Otherwise, it can simply go ahead and use the data, as described later in this
section.
Entering the preceding code at the command line returns a list that looks
something like this:
((-1 . <Entity name: 600000c0>) (0 . "INSERT") (8 . "0") (2 . "*X0")
(10 0.0 0.0 0.0) (41 . 1.0) (42 . 1.0) (50 . 0.0) (43 . 1.0) (70 . 0) (71 . 0)
(44 . 0.0) (45 . 0.0) (210 0.0 0.0 1.0) (-3 ("ACAD" (1000 . "HATCH")
(1002 . "{") (1070 . 16) (1000 . "LINE") (1040 . 1.0) (1040 . 0.0)
(1002 . "}"))))
This fragment shows a typical sequence for retrieving xdata for two specified
applications. Note that the application argument passes application names
in list form:
NOTE Because the strings passed by application can include wild-card char-
acters, an application name of "*" will cause entget to return all extended data
attached to an entity.
Xrecord Objects
Xrecord objects are used to store and manage arbitrary data. They are com-
posed of DXF group codes with normal object groups (that is, non-xdata
group codes), ranging from 1 through 369 for supported ranges. This object
is similar in concept to xdata but is not limited by size or order.
Xrecord objects are designed to work in such a way as not to offend releases
R13c0 through R13c3. However, if read into a pre-R13c4 level of AutoCAD,
xrecord objects disappear.
The following examples provide methods for creating and listing xrecord
data.
(defun C:MAKEXRECORD( / xrec xname )
; create the xrecord’s data list.
(setq xrec ‘((0 . "XRECORD")(100 . "AcDbXrecord")
(1 . "This is a test xrecord list")
(10 1.0 2.0 0.0) (40 . 3.14159) (50 . 3.14159)
(62 . 1) (70 . 180))
)
(princ)
)
(princ)
)
Symbol Tables
Symbol table entries can also be manipulated by the following functions:
entdel
entget
entmake
entmod
handent
The tblnext function sequentially scans symbol table entries, and the
tblsearch function retrieves specific entries. Table names are specified by
strings. The valid names are LAYER , LTYPE, VIEW, STYLE, BLOCK , UCS, VPORT,
DIMSTYLE, and APPID. Both functions return lists with DXF group codes that
are similar to the entity data returned by entget.
The first call to tblnext returns the first entry in the specified table. Subse-
quent calls that specify the same table return successive entries, unless the
second argument to tblnext (rewind) is nonzero, in which case tblnext
returns the first entry again.
In the following example, the function GETBLOCK retrieves the symbol table
entry for the first block (if any) in the current drawing, and then displays it
in a list format.
Dictionary Entries
A dictionary is a container object, similar to the symbol tables in functions.
Dictionary entries can be queried with the dictsearch and dictnext func-
tions. Each dictionary entry consists of a text name key plus a hard owner-
ship handle reference to the entry object. Dictionary entries may be removed
by directly passing entry object names to the entdel function. The text name
key uses the same syntax and valid characters as symbol table names.
This sets the grpdict variable to the entity definition list of the
ACAD_GROUP dictionary and returns the following:
((-1 . <Entity name: 8dc10468>) (0 . "DICTIONARY") (5 . "D")
(102 . "{ACAD_REACTORS") (330 . <Entity name: 8dc10460>)
(102 . "}") (100 . "AcDbDictionary") (3 . "G1")
(350 . <Entity name: 8dc41240>))
The following code sets the variable group1 to the entity definition list of the
G1 group:
(setq group1 (dictsearch (cdar grpdict) "G1"))
It returns the following:
((-1 . <Entity name: 8dc10518>) (0 . "GROUP") (5 . "23")
(102 . "{ACAD_REACTORS") (330 . <Entity name: 8dc10468>)
(102 . "}") (100 . "AcDbGroup") (300 . "line and circle") (70 . 0) (71 . 1)
(340 . <Entity name: 8dc10510>)(340 . <Entity name: 8dc10550>) )
The 340 group codes are the entities that belong to the group.
329
330
Designing Dialog Boxes
11
Dialog boxes are defined by ASCII files written in dialog In this chapter
control language (DCL). The elements in a dialog box, Dialog Box Components
331
Dialog Box Components
The following figure shows a standard AutoCAD dialog box, with some of its
components labeled. In dialog box creation and customization these compo-
nents are known as tiles.
columns
edit boxes
toggles
radio buttons
buttons in a row
in a row
A dialog box consists of the box and the tiles within it. The basic tile types
are predefined by the programmable dialog box (PDB) facility.
You can create complex tiles, called subassemblies, by grouping tiles into
rows and columns, with or without an enclosing box or border. A row or col-
umn of tiles is referred to as a cluster. Subassemblies define groups of tiles or
clusters that can be used in many dialog boxes. For example, the OK, Cancel,
and Help buttons are grouped into a subassembly, defined as a row (cluster)
of three button tiles and some spacing separating the buttons.
Subassemblies are treated as single tiles. The tiles within a subassembly are
called children. DCL files are organized in a tree structure. At the top of the
tree is a (dialog ) tile that defines the dialog box itself. The following diagram
shows a DCL file structure:
toggle
boxed_column
edit box
edit box
row
button
button
the ok_cancel subassembly
text
@include “user1.dcl”
user3.dcl
In this figure, the user1.dcl and user2.dcl files are independent of each other,
but user3.dcl uses tiles defined in user1.dcl. The include directive has the form:
@include filename
where filename is a quoted string containing the full name of the other DCL
file. For example, the following directive includes a file named usercore.dcl:
@include "usercore.dcl"
If you specify only the file name, the PDB feature searches for the file first in
the current directory and then in the same directory as the DCL file itself (the
one that contains the include directive). If you specify a full path name, the
PDB feature searches only the directory specified in that path.
NOTE The DCL files you create cannot use the dialog boxes defined in
acad.dcl. You cannot specify @include "acad.dcl" . However, if you want to
create similar dialog boxes, you can cut and paste the definitions into your own
DCL file.
DCL Syntax
This section describes the DCL syntax for specifying tiles, tile attributes, and
attribute values.
New tiles are created by tile definitions. If a tile definition appears outside a
dialog box definition, it is a prototype or a subassembly. Prototypes and
subassemblies can be used in dialog box definitions by tile references. Each
reference to a definition inherits the attributes of the original tile. When
referring to prototypes, you can change the values of the inherited attributes
or add new attributes. When referring to subassemblies, you cannot change
or add attributes.
Tile Definitions
Tile definitions have the following form:
name : item1 [ : item2 : item3 ... ] {
attribute = value;
...
}
where each item is a previously defined tile. The new tile (name) inherits the
attributes of all the specified tiles (item1, item2, item3,…). The attribute def-
initions within the curly braces ( {}) either supplement, or, if the attribute’s
name is identical, replace the inherited definitions. When the definition has
multiple parents, attributes take precedence in left-to-right order. In other
words, if more than one item specifies the same attribute, the first one
encountered is the one used.
If the new definition contains no children, it is a prototype, and you can alter
or augment its attributes when referring to it. If it is a subassembly with
children, its attributes cannot be altered.
The name of a tile or tile prototype can contain only letters, numbers, or the
underscore character ( _ ), and must begin with a letter.
NOTE Tile names are case-sensitive. For example, bigbutton is not the same
as BigButton or BIGBUTTON. Be careful when using capitalization.
Tile References
Tile references have one of the following forms:
name;
or
: name {
attribute = value;
. . .
}
where name is the name of a previously defined tile. Tile names are case
sensitive. In the first instance, all the attributes defined in name are incorpo-
rated into the reference. In the second instance, the attribute definitions
within the curly braces either supplement or replace the definitions inherited
from name. Because this is a tile reference, as opposed to a definition, the
attribute changes apply only to this instance of the tile.
NOTE The format of the second instance can refer only to prototypes, not to
subassemblies.
The spacer tile is used for layout in a dialog box definition. It has no unique
attributes, so references to it specify only its name:
spacer;
Comments
A statement preceded by two forward slashes (//) is treated as a comment in
a DCL file. Anything that appears between the // and the end of the line is
ignored. DCL also allows C language style comments. These have the form /
* comment text */ . The starting /* and ending */ can be on separate lines.
Note how the text editor color codes the statements in the DCL file. The
default color coding scheme is shown in the following table:
Strings Magenta
Integers Green
Parentheses Red
Choose Tools Interface Tools Preview DCL in Editor to display the dia-
log box defined in the text editor window. Because you may have more than
one dialog box defined in a single .dcl file, VLISP prompts you to specify the
name of the dialog you want to view:
If your DCL file contains definitions for multiple dialog boxes, click the pull-
down arrow and choose the one you want to preview. There is only one
dialog box defined in hello.dcl, so choose OK to view it:
Press OK to clear the message from your screen. VLISP may display additional
error messages, like the following:
Level Description
0 No checking. Use only if the DCL files have been audited and have not
been touched since the audit.
1 Errors. Finds DCL bugs that may cause AutoCAD to terminate. This level of
checking is the default and involves almost no delay. Errors can include
using undefined tiles and circular prototype definitions.
2 Warnings. Finds DCL bugs that result in dialog boxes with undesired layout
or behavior. A modified DCL file should be audited at this level at least
once. The warning level catches mistakes such as missing required
attributes and inappropriate attribute values.
To get the most out of the auditing facility, you should keep the audit_level
at 3 during program development. Remember to strip out the dcl_settings
line before shipping DCL files to users.
Notice how the OK button occupies almost the full width of the dialog box.
To improve the appearance of this dialog box, you can edit the DCL file and
add two attributes to the button tile. To prevent the button from filling the
available space, add a fixed_width attribute and set it to true. This causes the
button’s border to shrink so that it is just slightly wider than the text inside.
To center the button, add an alignment attribute that specifies centered.
Tiles in a column are left-justified by default. Now the DCL description is as
follows:
Many common layout problems can be resolved with the techniques that
are described in the following subsections. If the default layout is not suitable
to the dialog box you are creating, adjust the layout by changing the defaults
at the prototype or subassembly level. Adjust individual tiles only when
necessary.
If the label is a single blank, any vertical space the text occupied inside
the box is lost, but any vertical space the label occupied above the box is
not lost.
If the label is a null string, all vertical space is lost, whether above the box
or inside it.
In the following DCL code, the top lines of the boxes around the first two
columns are guaranteed to line up (with the same Y location), and the top
line of the box around the third column is guaranteed to have no spacing
above or below it, except for the default margins:
destroy_button : retirement_button {
label = "&Destroy";
key = "destroy";
}
Notice the use of the ampersand (&) in the label attribute. This assigns a mne-
monic to the tile. In this case the letter D is underscored in the button label
and becomes the mnemonic.
Once you have defined a custom exit button, you need to embed it in a sub-
assembly that matches the appearance and functionality of the standard
clusters. The following example shows the current definition of
ok_cancel_help:
ok_cancel_help : column {
: row {
fixed_width = true;
alignment = centered;
ok_button;
: spacer { width = 2; }
cancel_button;
: spacer { width = 2; }
help_button;
}
}
Create a new subassembly that replaces the ok_button with the new button
as follows:
Because an attribute has been changed, the original Cancel button is used as
a prototype, requiring a colon in front of cancel_button.
WARNING! When the Cancel button and the Default button are the same
(both is_default and is_cancel are true) and you neglect to assign an action
that calls done_dialog to any other button, then no other button can exit the
dialog box and it will always be canceled.
Design Guidelines
To design a dialog box well, you must consider not only the practical purpose
of the box but also its aesthetics, the ergonomics of using it, and the GUI
standards for the Windows environment. The following subsections provide
some guidelines for GUI design, dialog box design, and predefined tiles and
clusters. Refer to the “Programmable Dialog Box Reference,” chapter 13, for
more examples of tiles and clusters.
User Control
Give users some control over how they access the dialog box to enter input.
One advantage of using dialog boxes instead of a command line interface is
that boxes don’t confine users to a strict sequence of prompts. In a dialog
box, users should be able to enter input in any sequence. Some constraints
are necessary—when selecting one option causes another to be unavailable,
for example— but build in only constraints that have underlying reasons in
the way your application works.
For example, the following figure shows the Object Grouping dialog box.
This dialog box contains a Group Name field, where users may enter a name
for a new group they are creating. If the Unnamed option is selected, a Group
Name cannot be specified.
Forgiving Errors
Make your dialog boxes forgiving, so users feel free to explore without fear of
making irreversible mistakes. Report minor errors by messages in an error tile
at the bottom of the dialog box. Report more serious errors by displaying an
alert box. The alert function displays a simple alert box (with a single OK
button). See “alert” in the AutoLISP Reference.
Nested dialog boxes that alert users should return to the previous dialog box.
Terminate the current nest of dialog boxes only in the case of serious or
potentially fatal errors.
Providing Help
You should provide a Help facility. How much online help you provide
depends on how complex your application is and how self-explanatory your
dialog boxes are. At the very least, it is recommended that the main dialog
box of your application have a Help button that displays a single dialog box
describing important information. In most cases, the Help button should call
the Help facility using the help function.
If your application is more sophisticated, consider developing a context-
sensitive Help facility with multiple Help dialog boxes, each associated with
a particular dialog box.
Using Capitalization
The following are some general guidelines for capitalizing text within dialog
boxes:
Dialog Boxes, Use headline capitalization: capitalize the first and last
Areas, and words, and all other words except articles, prepositions,
Column and coordinating conjunctions. However, if the dialog
Headings box is invoked from a menu (not from the Command
prompt), its title should match the menu item.
Control Labels Use headline capitalization for labels of control tiles such
as buttons. Do not follow labels with a period. Follow the
labels of a text box or a drop-down list with a colon (:).
You may want to use sentence-style capitalization (in
which you capitalize only the first word and proper
nouns) if the label is lengthy or phrased as a question.
Prompts and Use sentence-style capitalization.
Messages
Avoiding Abbreviations
Abbreviations can be ambiguous and difficult to translate. If space con-
straints require you to abbreviate terms, abbreviate them consistently within
a group (such as a boxed column). Be consistent. Don’t spell some terms in
full and abbreviate others.
NOTE Users may have a screen resolution as low as 640 × 480. If you are devel-
oping applications on displays using a higher resolution, remember to verify that
your dialog boxes display properly at lower resolutions.
By default, AutoCAD initially displays all dialog boxes in the center of the
graphics window. However, you can specify that dialog boxes display at an
alternate location (such as the last location specified by the user). The
new_dialog and done_dialog AutoLISP functions provide for dialog box
placement.
Disabling Tiles
If a tile or an area is unavailable or irrelevant given the current option set-
tings, disable it immediately so the tile or area is unavailable and the user
can’t select it. Try not to overuse the disabling tiles feature. Too many
unavailable tiles can be distracting.
If a tile displays a value, disabling the tile shouldn’t affect the value. The tile
should display the same value when it is enabled again. Values that change
magically create more work for the user, which is annoying and distracting.
Providing Defaults
Provide reasonable defaults for all entries and options. Well-chosen defaults
can help users complete a dialog box quickly and easily.
It is recommended that you update the default values— in other words, that
you save the user’s previous settings and use them as the new defaults— each
time the dialog box is used. Even if the user has to change some of these, it
is less work than starting from the beginning each time.
Entity creation modes Modes de création des objets Modus für Objekterzeugung
OK OK OK
Buttons
The action associated with a button should be visible to the user and should
take place immediately. The label of a button should be unambiguous. Usu-
ally, it should be a verb that describes the effect of pushing the button,
though another label—such as OK or Options—is acceptable if its meaning
is clear. For buttons that call other dialog boxes or hide the current dialog
box, see “Nesting Dialog Boxes” on page 351 and “Hiding Dialog Boxes” on
page 352.
Buttons in a column should be the same width. In other cases, buttons
should have a fixed width (either fixed_width = true;, or
children_fixed_width = true;) in their common parent cluster.
Clusters
A boxed cluster (a row or column) is called a group box or an area. An area
provides a visual cue to users by isolating and naming controls that work
together. The area can contain as many tiles, rows, and columns (unboxed)
as necessary. The label of an area should indicate its purpose.
If controls relate to each other, put them in an area. The Base Point cluster in
the Block Definition sample dialog box demonstrates this technique with an
area formed from a cluster with a label and a border:
However, do not overuse areas. White space is also an effective way to group
tiles. Do not put a box around a list box; this looks too busy.
List Boxes
Because DCL list boxes cannot be scrolled horizontally, the width of the list
box should accommodate the longest item in the list. Provide a label (or a
text tile) to explain the contents of the list box, unless the list box is the main
tile in the dialog box. In that case the dialog box’s label might be sufficient—
although you must give the list box a label if you want users to be able to
move to that list box by using a mnemonic.
Alphabetize the items in the list unless you have a logical reason to organize
them in some other way. If the length of the list is fixed and short, consider
using a radio column instead of a list box.
If an option selected elsewhere makes the choices in the radio row or radio
column invalid or irrelevant, then disable the whole row or column. In some
situations, an option selected elsewhere may make certain radio buttons
invalid or irrelevant. In situations like this, you can disable buttons individ-
ually.
Sliders
The granularity of a slider should not be too coarse. For example, if a slider is
assigned only four incremental values but is laid out in a two-inch section of
the dialog box, users would have to move half an inch to see a change. Avoid
jumpiness like this by scaling the size of the slider.
If users need to know the value controlled by the slider, your dialog box
should also display the slider’s current value. Update this value whenever the
slider is moved. It is recommended you also display an edit box that enables
users to enter the value rather than use the slider. If you use an edit box this
way, update its value; otherwise, display the value in a text tile. The following
figure shows a typical combination of slider and edit box:
Text
When labels are not sufficient, use text tiles to identify the purpose of indi-
vidual tiles or dialog box areas. You can also use text tiles to display status
messages or reminders, including error messages and warnings.
Text should be direct and unambiguous. Describe options and entry fields in
terms your users would use. For example, the error message “Invalid entry”
in a list box conveys little information. A message such as “Layer does not
exist” is more helpful.
Align messages with the control tiles they describe.
Put text that identifies a group of control tiles or a section of the dialog box
above the tiles that the text describes.
Error Handling
Dialog boxes can display error messages and warnings with a text tile known
as an error tile (errtile ), or with a nested alert box. The following guidelines
apply to both:
Error Tiles
Use an error tile for minor errors or warnings, especially those that arise from
typos and other input errors.
Do not display errors in text tiles used for status messages. These are easy to
overlook.
Error tiles should appear at the bottom of a dialog box. Use the standard
errtile described in “Dialog Box Exit Buttons and Error Tiles” on page 404.
Alert Boxes
You can display a standard alert box with a single OK button by calling the
alert function. Use alert boxes for serious or potentially fatal errors, but do
not overuse them. Alert boxes require user input. Therefore, they can be
annoying, especially when they report minor errors or obscure the entry that
needs to be corrected.
chapter shows some examples of DCL files, you may Image Tiles and Buttons
Application-Specific Data
find it helpful to read “Designing Dialog Boxes” before
DCL Error Handling
reading this chapter.
Dialog Box Function Summary
359
Controlling Dialog Boxes with AutoLISP
Programs
This chapter begins with an overview of the process you use to display dialog
boxes and respond to user input from an AutoLISP program.
Quick Overview
This example starts with a simple dialog box:
This DCL defines a dialog box labeled Sample Dialog Box that contains a text
tile and a single OK button. The DCL resides in a file named hello.dcl.
WARNING! In theory, the dialog box facility takes control of input at the time
you call start_dialog, but in Windows it takes control when you call
new_dialog . This has no effect on writing programs. However, if you invoke
these functions interactively (at the AutoCAD Command prompt or a VLISP win-
dow), you must enter them as one statement. Enclose them within a progn or
another function. If you don’t, the interactive call to new_dialog can freeze the
screen. Calling new_dialog and start_dialog interactively can be useful dur-
ing debugging. (For an example of using these functions interactively, see “DCL
Error Handling” on page 381.)
You can test the CMDACTIVE system variable to determine if a dialog box is
active. If CMDACTIVE is greater than 7, a dialog box is active. The CMDACTIVE
system variable has bit-coded values that indicate command, script, and dia-
log box activity.
NOTE If your application requires users to enter input based on the graphics
screen rather than on the dialog box itself (for example, to specify a point or
select an object), you must hide the dialog box. That is, you must call
done_dialog so the graphics screen is visible again, and then restart the dialog
box after the user has made the selection. For more information, see “Hiding
Dialog Boxes” on page 371.
The term_dialog function terminates all current dialog boxes as if the user
had canceled each of them. This function can be used to cancel a series of
nested dialog boxes.
Information relating to how the user has selected a tile or modified a tile’s
contents is returned to the action expression as a callback. In most cases,
every active tile within a dialog box can generate a callback. As with reactors,
the action expression that responds to the callback is often referred to as a
callback function. This function should perform validity checking on the
associated tile and should update information in the dialog box that pertains
to the value of the tile. Updating the dialog box can include issuing an error
message, disabling other tiles, and displaying the appropriate text in an edit
box or list box.
Only the OK button (or its equivalent) should query the tile values to perma-
nently save the settings that the user has finally selected. In other words, you
should update the variables associated with tile values within the callback for
the OK button, not the callback for an individual tile. If permanent variables
are updated within the individual tile callbacks, there is no way to reset the
values if the user selects the Cancel button. If the OK button’s callback
detects an error, it should display an error message and return focus to the
tile in error; it should not exit the dialog box.
When a dialog box includes several tiles whose handling is similar, it can be
convenient to associate those tiles with a single callback function. The prin-
ciple of not committing to the user’s changes until the user chooses OK still
applies.
There are two ways to define actions other than calling action_tile. You can
define a default action for the entire dialog box when you call new_dialog,
and you can define an action by using a tile’s action attribute. These alter-
native means of defining actions, and the order in which they occur, are
described in “Default and DCL Actions” on page 366.
Variable Description
$value The string form of the current value of the tile, such as the string from an
edit box, or a "1" or "0" from a toggle.
This variable applies to all actions.
If the tile is a list box (or pop-up list) and no item is selected, the $value
variable will be nil.
$data The application-managed data (if any) that was set just after new_dialog
time by means of client_data_tile.
This variable applies to all actions, but $data has no meaning unless your
application has already initialized it by calling client_data_tile. See
“Application-Specific Data” on page 380.
$reason The reason code that indicates which user action triggered the action.
Used with edit_box, list_box, image_button, and slider tiles.
This variable indicates why the action occurred. Its value is set for any kind
of action, but you need to inspect it only when the action is associated
with an edit_box, list_box, image_button, or slider tile. See
“Callback Reasons” in the following section for details.
If edit1 is a text box, the action expression in the following action_tile call
is evaluated when the user exits the text box:
(action_tile "edit1" "(setq ns $value)")
The $value contains the string that the user entered, and the expression
saves this in the ns variable.
The next example saves the name of the selected tile so that the program can
refer to it:
(action_tile "edit1" "(setq newtile $key)")
The newtile variable is set to the key name of the selected tile, in this case
"edit1". The $key variable is very useful within a function that serves as the
action for several separate tiles.
Callback Reasons
The callback reason, returned in the $reason variable, specifies why the
action occurred. Its value is set for any kind of action, but you need to inspect
it only when the action is associated with an edit_box, list_box,
image_button , or slider tile. The following table shows the possible values:
Code Description
1 This is the value for most action tiles. The user has selected the tile (possibly
by pressing ENTER, if the tile is the default and the platform recognizes
accelerator keys).
2 Edit boxes: The user has exited the edit box, but has not made a final
selection.
3 Sliders: The user has changed the value of the slider by dragging the indicator
but has not made a final selection.
4 List boxes and image buttons: This callback reason always follows a code 1. It
usually means “commit to the previous selection.” It should never undo the
previous selection ; this confuses and annoys the user.
Code 1 is described fully in the table. The following text describes the codes
2, 3, and 4 in greater detail.
Code 2—Edit Boxes
The user has exited the edit box— by pressing the TAB key or by choosing a
different tile— but has not made a final selection. If this is the reason for an
edit box callback, your application should not update the value of the asso-
ciated variable, but should check the validity of the value in the edit box.
Code 3—Sliders
The user has changed the value of the slider by dragging the indicator (or an
equivalent action), but has not made a final selection. If this is the reason for
a slider callback, your application should not update the value of the associ-
ated variable but should update the text that displays the slider’s status. For
more information, see “Sliders” on page 356. For code examples, see
“Handling Sliders” on page 369.
The default action specified by the new_dialog call (used only if no action
is explicitly assigned to the tile).
The action specified by the action attribute in the DCL file.
The action assigned by the action_tile call (highest priority).
Handling Tiles
Your program has some control over the tiles that are in the current dialog
box at initialization time and action (callback) time. This section introduces
the tile-handling functions and shows how to initialize and modify the tiles’
modes and values.
Value Description
0 Enable tile
1 Disable tile
When you use mode_tile to disable a tile that has the current focus, you must
call mode_tile again to set the focus to a different tile (in most cases, the next
tab stop in the dialog box). Otherwise, the focus will remain on a disabled
tile, which is illogical and can cause errors.
NOTE If you use get_attr to retrieve a value attribute, it gets the value
attribute saved in the DCL file (the initial value of the tile). The get_tile func-
tion, however, gets the current runtime value of the tile. The two values are not
necessarily the same.
These examples show each radio button associated with a single variable that
takes multiple values. These variables may also cause additional actions, such
as disabling selections in your dialog box. If the radio cluster is large, you can
store the associated values in a table. If you use a table, structure it so it
doesn’t depend on the order of the buttons within the cluster. The PDB fea-
ture does not impose this restriction, and the order can change if the DCL
definition changes.
Handling Sliders
When you handle actions and callbacks from sliders, your application should
check the reason code that it receives along with the callback. This is not
required, but it is a good idea because it can reduce processing.
A callback occurs when an increment boundary on a slider is crossed. For
example, if the slider is defined with a minimum value of 0, a maximum
value of 10, and both small and big increments of 1, a callback is issued
10 times as the user traverses from one end of the slider to the other.
The following function shows the basic scheme of a function to handle a
slider. It is called from an action expression associated with the slider tile.
The slider_info tile used by the function displays the slider’s current value
in decimal form . Often such a tile is an edit box as well, which gives users the
choice of either manipulating the slider or entering its value directly. If a user
enters a value in slider_info, your edit box callback should update the value
of the slider as follows:
The term_dialog function terminates all current dialog boxes as if the user
had canceled each of them. You can use this function if you need to cancel a
series of nested dialog boxes.
NOTE The term_dialog function terminates all dialog boxes at once but does
not return a status code, so there is no way for an application to distinguish
between hiding a nested box and canceling boxes due to an error condition.
Requesting a Password
The following examples show how to use a simple dialog box to request a
password from users.
The getpass.dcl file defines a dialog box named passdlg , which contains two
tiles: the edit_box tile where the user enters the password, and the ok_cancel
tile. It uses the password_char DCL attribute to mask the text a user enters:
// GETPASS.DCL
//
passdlg : dialog {
label = "Password Protected";
: edit_box {
label = "Password:";
edit_width = 20;
key = "password";
password_char = "?";
}
ok_cancel;
}
start_list
add_list
end_list
You set up the lists displayed in list boxes and pop-up lists by using a
sequence of calls to these functions.
List Operations
A dialog box list operation always begins with a start_list function call.
The function syntax is as follows:
(start_list key [operation [index]])
Value Description
The index argument is only used in change operations. The index indicates
the list item to change by a subsequent add_list call. The first item in a list
is index 0.
If you don’t specify operation, it defaults to 3 (create a new list). If you do
not specify an index, the index value defaults to 0.
You implement the list operations as follows:
Creating a After the start_list call, call add_list repeatedly to add
New List (3) new items to the list. End list handling by calling
end_list.
(start_list "selections" 2)
(mapcar ’add_list newnames)
(end_list)
Changing a single item requires only one add_list call. In this case, you
specify the index of the item to change:
(start_list "selections" 1 5) ;Change the sixth item in the list.
(add_list "SURPRISE!") ;Remember that the first index is 0.
(end_list)
You cannot delete a list item or insert an item without rebuilding the list
from scratch.
Creating Images
The calling sequence to create images for image tiles and image buttons is
similar to the list-handling sequence. The start_image function begins the
creation of an image, and end_image ends it. However, the type of image to
draw is specified in separate function calls, instead of arguments:
NOTE If you use slides with filled objects (such as wide polylines, solids, and
3D faces) in image tiles, the images will appear as outlines unless you make the
slides from an image created with the SHADEMODE command.
The slides you display with slide_image can be standalone slide (SLD) files,
or part of a slide library (SLB) file. If the slide is in an SLD file, you specify its
name without the .sld extension (for example, "frntview"). If the slide is in
a slide library, you specify the name of the library, followed by the name of
the slide enclosed in parentheses. Note that the library and slide names are
also specified without extensions—for example, "allviews(frntview)". The
slide_image function searches for the slide or slide library file according to
the current AutoCAD library search path. (See “load” in the AutoLISP Refer-
ence.)
In the following example, the slide is in a single file called topview.sld:
(setq x (dimx_tile "view")
y (dimy_tile "view"))
(start_image "view")
( slide_image 0 0 x y "topview")
(end_image)
Vectors in slides are often drawn in white (color number 7), which is the
default background color of an image. If your image tile is blank when you
first display a slide, try changing its color attribute to graphics_background.
(You can also change the background of the image by preceding the
slide_image call with a fill_image call.)
Application-Specific Data
The client_data_tile function assigns application-specific data to a tile.
The data is available at callback time as the $data variable and must be a
string. Client data is not represented in DCL; it is valid only while your appli-
cation is running. Using client data is comparable to using user-defined
attributes. The main difference is that user-defined attributes are read-only,
while client data can change at runtime. Also, end-users can inspect user-
defined attributes in the application’s DCL file, but client data is invisible to
them.
You can inspect the contents of acad.dce to find the problem. AutoCAD
places the acad.dce file in the current working directory. When AutoCAD
reads a DCL file successfully, it deletes the acad.dce file.
If your application uses multiple DCL files, the acad.dce file is overwritten (or
deleted if no errors occur) when each new file is loaded. When you test the
program, acad.dce shows errors (if any) from only the DCL file most recently
read. It is recommended that you use the VLISP DCL Preview feature to debug
your DCL files (see “Displaying Dialog Boxes with Visual LISP” on page 338).
See “Functions Restricted When a Dialog Box Is Open” on page 362 for infor-
mation on which functions are restricted.
Function Sequence
The following demonstrates the typical function sequence:
1 Load the DCL file with a load_dialog call.
2 Call new_dialog to display a particular dialog box.
Be sure to check the value returned by new_dialog. Calling start_dialog
when the new_dialog call has failed can have unpredictable results.
3 Initialize the dialog box by setting up tile values, lists, and images. Initialize
also when you call action_tile to set up action expressions or callback func-
tions. Other functions typically called at this time are set_tile and
mode_tile for general tile values and states, start_list, add_list, and
end_list for list boxes, and the dimension functions with start_image ,
vector_image , fill_image , slide_image, and end_image for images. At this
time you can also call client_data_tile to associate application-specific
data with the dialog box and its components.
4 Call start_dialog to turn control over to the dialog box, so that the user can
enter input.
5 Process user input from within your actions (callbacks). Process input when
you are most likely to use get_tile, get_attr, set_tile, and mode_tile.
The user presses an exit button, causing an action to call done_dialog, which
causes start_dialog to return a value. At this point, unload the DCL file by
calling unload_dialog.
384
Programmable Dialog
Box Reference
13
This chapter lists and describes all the dialog control In this chapter
language (DCL) tiles and their associated attributes, and Tile Attributes
385
Tile Attributes
A tile’s attributes define its layout and functionality. An attribute is similar to
a programming language variable: it consists of a name and a value.
Attribute Types
The value of an attribute must be one of the following data types:
Integer Numeric values (both integers and real numbers) that
represent distances, such as the width or height of a tile,
are expressed in character-width or character-height
units.
Real Number A fractional real number must have a leading digit: for
example, 0.1, not .1.
Quoted String A quoted string consists of text enclosed in quotation
marks (""). Attribute values are case-sensitive: B1 is not
the same as b1. If the string must contain a quotation
mark, precede the quotation mark character with a
backslash (\"). Quoted strings can contain other control
characters as well. The characters recognized by DCL are
shown in the following table:
Control Meaning
character
\\ backslash
\n newline
\t horizontal tab
Restricted Attributes
Do not use the following tile attributes in your DCL files:
horizontal_margin
vertical_margin
type
User-Defined Attributes
When defining tiles, you can assign your own attributes. The name of the
attribute can be any valid name that does not conflict with the standard, pre-
defined attributes described in the previous subsection and summarized in
“Synopsis of Predefined Attributes” on page 388. An attribute name, like a
keyword, can contain letters, numbers, or the underscore (_), and must begin
with a letter.
If a user-defined attribute name conflicts with a predefined attribute, the PDB
feature does not recognize the attribute as a new one, and attempts to use the
value you assign it with the standard attribute. This can be very hard to
debug.
The values you assign to the attribute, and their meanings, are defined by
your application. Values for user-defined attributes must conform to the
types described in “Tile Attributes” on page 386.
The word Invalid and the trailing period (.) are supplied by the error handler.
User-defined attributes also can be used for limits on the value of a tile and
the name of a subdialog box that the tile activates (see “Nesting Dialog
Boxes” on page 371).
Predefined attributes
action
action = "(function)";
Specifies an AutoLISP expression to perform an action when this tile is
selected. Also known as a callback. For some kinds of tiles, an action can also
occur when the user switches focus to a different tile.
The possible value is a quoted string that is a valid AutoLISP expression. A tile
can have only one action. If the application assigns it an action (with
action_tile ), this overrides the action attribute.
NOTE You cannot call the AutoLISP command function from the action
attribute.
alignment
alignment = position;
Specifies the horizontal or vertical positioning (justification) of a tile within
its cluster.
For a tile that is a child of a column, the possible values are left , right, or
centered (default is left).
For a tile that is a child of a row, the possible values are top, bottom, or
centered (default is centered ).
You cannot specify the alignment along the long axis of a cluster. The first
and last tiles in the cluster always align themselves with the ends of the col-
umn or row. Other tiles in the cluster are distributed evenly unless you adjust
the distribution by using padding insertion points (see “spacer_0” on page
420).
aspect_ratio
aspect_ratio = real;
Specifies the ratio of the width of the image to its height (width divided by
height). If zero (0.0), the tile is fitted to the size of the image.
Possible values are floating-point values (default: none).
big_increment
big_increment = integer;
Specifies the value used by the slider’s incremental controls. The default
value of big_increment is one-tenth of the total range. The value must be
within the range specified by min_value and max_value.
children_alignment
children_alignment = position;
Specifies the default alignment (similar to alignment) for all tiles in a cluster.
Does not override a child’s alignment attribute, if alignment is specified
explicitly.
For columns, possible values are left, right, or centered (default: left).
For rows, possible values are top , bottom, or centered (default: centered).
children_fixed_width
children_fixed_width = true-false;
Specifies the default width (similar to width ) for all tiles in a cluster. Does not
override a child’s width attribute, if it is specified explicitly.
Possible values are true or false (default: false).
color
color = colorname;
Specifies the background (fill) color of the image. Possible values are an inte-
ger or reserved word (default: 7) specified as an AutoCAD color number or as
one of the symbolic names shown in the following table:
children_fixed_height | 393
Symbolic names for colors (continued)
edit_limit
edit_limit = integer;
Specifies the maximum number of characters a user is allowed to enter in the
edit box. A possible value is an integer (default: 132 ). When the user reaches
this limit, AutoCAD rejects additional characters (except for BACKSPACE or
DEL ). The maximum edit limit allowed is 256 characters.
fixed_height
fixed_height = true-false;
Specifies if a tile’s height is allowed to fill the available space. If this attribute
is true, the tile does not fill the extra space that becomes available in the lay-
out/alignment process.
Possible values are true or false (default: false).
fixed_width
fixed_width = true-false;
Specifies if a tile’s width is allowed to fill the available space. If this attribute
is true, the tile does not fill the extra space that becomes available in the lay-
out/alignment process.
Possible values are true or false (default: false).
fixed_width_font
fixed_width_font = true-false;
Specifies whether a list box or pop-up list will display text in a fixed pitch
font. This allows for easier spacing and tab alignment of columns.
Possible values are true or false (default: false).
edit_width | 395
height
height = number;
Specifies the height of a tile. Possible values are an integer or a real number
representing the distance in character height units. Do not specify this value
unless the assigned defaults do not have an acceptable appearance. You must
specify, however, the height of image tiles and image buttons.
The height attribute specifies the minimum height of a tile. This dimension
can be expanded when the tile is laid out, unless the height is fixed by one
of the fixed_ attributes. Defaults are dynamically assigned based on layout
constraints.
Character-height units are defined as the maximum height of screen charac-
ters (including line spacing).
initial_focus
initial_focus = "string";
Specifies the key of the tile within the dialog box that receives the initial key-
board focus. Possible value is a quoted string (no default).
is_bold
is_bold = true-false;
Specifies whether the text is displayed in bold characters. Possible values are
true or false (default: false). If true , the text is displayed in bold
characters.
is_cancel
is_cancel = true-false;
Specifies whether the button is selected when the user presses the ESC key.
Possible values are true or false (default: false).
If the action expression for buttons with the is_cancel attribute set to true
does not exit the dialog box (does not call done_dialog ), the dialog box is
automatically terminated after the action expression has been carried out,
and the DIASTAT system variable is set to 0.
Only one button in a dialog box can have the is_cancel attribute set to true.
is_enabled
is_enabled = true-false;
Specifies whether or not the tile is initially available. Possible values are
true or false (default: true). If false , the tile is unavailable and appears
grayed out.
is_tab_stop
is_tab_stop = true-false;
Specifies whether the tile receives keyboard focus when the user moves
between tiles by pressing the TAB key. Possible values are true or false
(default: true). If the tile is disabled, it is not a tab stop even if this attribute
is true. If false, the tile is not a tab stop.
key
key = "string";
Specifies a name that the program uses to refer to this specific tile. Possible
value is a quoted string (no default). Within a particular dialog box, each key
value must be unique. This string is case-sensitive: if you specify the key as
BigTile, you cannot reference it as bigtile.
is_default | 397
Because the value of a key is not visible to the user, its name can be whatever
you choose (as long as it is unique to the dialog box). For the same reason,
key attributes do not need to be translated for applications offered in multi-
ple languages.
label
label = "string";
Specifies the text displayed within the tile. Possible value is a quoted string
(default: a blank string, " "). The placement of label text is tile-specific.
The label attribute can specify a mnemonic character for the tile. The mne-
monic is underlined in the tile’s label.
If a character in the label string is preceded by an ampersand (&), that char-
acter becomes the mnemonic. The character doesn’t have to be unique to the
dialog box. If more than one tile has the same mnemonic, the user presses
that key to cycle through the tiles sequentially.
Mnemonics change focus but do not select a tile. If the user specifies a mne-
monic key for a tile that contains a group of items, such as a cluster or a list
box, the focus is put on the first item in the tile that is a tab stop. Any active
tile is a tab stop unless its is_tab_stop attribute is set to false .
layout
layout = position;
Specifies the orientation of a slider. Possible values are horizontal or
vertical (default: horizontal). For horizontal sliders, the value increases
from left to right. For vertical sliders, the value increases from bottom to top.
list
list = "string";
Specifies the initial set of lines (choices) to be placed in the popup_list or
list_box. Possible value is a quoted string (no default). Lines are separated
by a new line symbol (\n). Tab characters (\t) can occur within each line.
min_value
min_value = integer;
Specifies the lower range of values that a slider returns. Default minimum
value is 0. This value must be a signed, 16-bit integer no less than -32768 . The
min_value can be greater than the max_value.
mnemonic
mnemonic = "char";
Specifies a keyboard mnemonic character for the tile. The mnemonic is
underlined in the tile’s label. A possible value is a quoted string of a single
character (no default). The character must be one of the letters in the tile’s
label. The character doesn’t have to be unique to the dialog box. If more than
one tile has the same mnemonic, the user presses that key to cycle through
the tiles sequentially.
From the user’s point of view, mnemonics aren’t case-sensitive. For example,
if a button’s mnemonic character is A, entering a or A both gives the A but-
ton focus. However, in the DCL file the mnemonic must be one of the char-
acters in the tile’s label, and it must be capitalized as it appears in the label
string.
Mnemonics change focus. If the user specifies a mnemonic key for a tile that
contains a group of items, such as a cluster or a list box, the focus is put on
the first item in the tile that is a tab stop. Any active tile is a tab stop unless
its is_tab_stop attribute is set to false .
max_value | 399
multiple_select
multiple_select = true-false;
Specifies whether multiple items in the list_box can be selected (high-
lighted) at the same time. Possible values are true or false (default: false ).
If true, multiple items can be selected at a time.
password_char
password_char = "char";
Specifies the character to be used to mask user input. If password_char is
specified and is not null, that character is displayed in the edit box instead of
the characters entered by the user. The use of this attribute has no effect on
your application’s retrieval of the value entered by the user; it alters only the
display of the characters in the edit box.
For an example of using the password_char attribute in an application, see
“Requesting a Password” on page 373.
small_increment
small_increment = integer;
Specifies the value used by the slider’s incremental controls. Default value of
small_increment is one one-hundredth the total range. The value must be
within the range specified by min_value and max_value. This attribute is
optional.
tabs
tabs = "string";
Specifies the placement of tabs in character width units. Possible value is a
quoted string containing integers or floating-point numbers, separated by
spaces (no default). These values are used for vertically aligning columns of
text in a popup_list or list_box.
For example, the following code specifies a tab stop at every 8 characters.
tabs = "8 16 24 32";
value
value = "string";
Specifies the initial value of a tile. Possible value is a quoted string. The mean-
ing of a tile’s value varies depending on the kind of tile. The value of a tile
can change at runtime through user input or set_tile calls.
The value attribute of a tile is not considered when the dialog box is laid out.
After the layout is finished and the dialog box has been displayed,
new_dialog uses the value attributes to initialize each tile in the dialog box.
A tile’s value attribute has no effect on the size or spacing of tiles in the
dialog box.
width
width = number;
Specifies the width of a tile. Possible values are an integer or a real number
representing the distance in character-width units. Do not specify this value
unless the assigned defaults don’t provide acceptable appearance. You must
specify, however, the width of image tiles and image buttons.
The width of a tile specifies a minimum width. This dimension can be
expanded when the tile is laid out unless the width is fixed by one of the
fixed_ attributes. Defaults are dynamically assigned based on layout
constraints.
Character width units is defined as the average width of all uppercase and
lowercase alphabetic characters, or the screen width divided by 80, which-
ever is less (average width is (width(A .. Z) + width (a .. z)))/52 ).
tab_truncate | 401
Functional Synopsis of DCL Tiles
This section presents the DCL tiles in functional groupings.
button popup_list
edit_box radio_button
image_button slider
list_box toggle
Tile Clusters
You can group tiles into composite rows or columns (known collectively as
clusters). For layout purposes, a cluster is treated as a single tile. The row or
column can be boxed, with an optional label (a cluster without a box cannot
be labeled).
Users cannot select a cluster, only individual tiles within the cluster. Clusters
cannot have actions assigned to them, with the exception of radio rows and
radio columns. The following tiles define clusters:
boxed_column dialog
boxed_radio_column radio_column
boxed_row row
column
image spacer_0
text spacer_1
spacer
Text Clusters
A text tile is surrounded by margin space (like any other kind of tile), which
presents a problem when you want to combine pieces of text. For example,
assume you want to display the following message:
The time is now 0800 hours and 37 seconds.
The actual values (0800 and 37) are supplied by your program. You can do
this by creating a concatenated line of text built out of text_part tiles. You
can also use text parts vertically to create a paragraph that doesn’t have too
much space between the lines.
The following text cluster tiles are prototypes defined in the base.dcl file.
concatenation text_part
paragraph
errtile ok_cancel_help
ok_only ok_cancel_help_errtile
ok_cancel ok_cancel_help_info
You can customize the text in these buttons by using the prototype
retirement_button as described in “Customizing Exit Button Text” on page
345.
Restricted Tiles
Your DCL files should not use the tiles cluster or tile. Also, do not use the
basic exit button types (cancel_button, help_button, info_button, and
ok_button) unless you redefine the standard exit button subassemblies as
described in this section in “Dialog Box Exit Buttons and Error Tiles” on page
404.
boxed_column
: boxed_column {
alignment children_alignment
children_fixed_height children_fixed_width
fixed_height fixed_width height label width
}
boxed_radio_column
: boxed_radio_column {
alignment children_alignment
children_fixed_height children_fixed_width
fixed_height fixed_width height label width
}
A boxed radio column has a border around it. Treat the label the same way
that you would treat the label of a boxed column.
label Appears as a title. If the label is absent, blank (the default),
or null (""), only the box appears. Spacing between a
blank and a null label might be different. (See “Fixing the
Spacing Around a Boxed Row or Column” on page 344.)
value Specifies the key of the currently selected radio button
(the one whose value is "1" ).
boxed_radio_column | 405
boxed_radio_row
: boxed_radio_row {
alignment children_alignment
children_fixed_height children_fixed_width
fixed_height fixed_width height label width
}
A boxed radio row has a border around it. You treat the label the same way
that you would treat the label of a boxed row.
label Appears as a title. If the label is absent, blank (the default),
or null (""), only the box appears. Spacing between a
blank and a null label might be different. (See “Fixing the
Spacing Around a Boxed Row or Column” on page 344.)
value Specifies the key of the currently selected radio button
(the one whose value is "1").
boxed_row
: boxed_row {
alignment children_alignment
children_fixed_height children_fixed_width
fixed_height fixed_width height label width
}
A boxed row has a border around it. If a boxed row has a label, the label
appears embedded in it.
label Appears as a title. If the label is absent, blank (the default),
or null (""), only the box appears. Spacing between a
blank and a null label might be different. (See “Fixing the
Spacing Around a Boxed Row or Column” on page 344.)
A button tile resembles a push button. The button’s label specifies text that
appears inside the button. Buttons are appropriate for actions that are imme-
diately visible to the user such as leaving the dialog box, or going into a sub-
dialog box.
Dialog boxes must include an OK button (or its equivalent) for the user to
press after using (or reading) the box. Many dialog boxes also include a
Cancel button that enables the user to leave the dialog box without making
any changes.
Dialog boxes should use the standard exit button subassemblies described in
“Dialog Box Exit Buttons and Error Tiles” on page 404. These subassemblies
guarantee that the attributes described in this section are correctly assigned.
NOTE If you make the default button and the cancel button the same, you
must make sure at least one other exit button is associated with an action that
calls done_dialog. Otherwise, the dialog box is always canceled.
column
: column {
alignment children_alignment
children_fixed_height children_fixed_width
fixed_height fixed_width height label width
}
button | 407
Tiles in a column are laid out vertically in the order in which they appear in
the DCL file. A column can contain any kind of tile (except for solitary radio
buttons), including rows and other columns.
A column without a box has no additional attributes beyond the standard
layout attributes.
concatenation
: concatenation {
}
A concatenation is a line of text made up of multiple, concatenated
text_part tiles. This is useful when you want to insert text that can change
at runtime into a standard message. There is a margin around the
concatenation as a whole.
The concatenation tile is defined in the base.dcl file. See “paragraph” on page
413 for an example that uses concatenation .
dialog
: dialog {
initial_focus label value
}
A dialog is the tile that defines the dialog box. You should not specify both a
label and value attribute: the value attribute overrides the label attribute.
label Specifies the optional title displayed in the title bar of the
dialog box.
value Specifies a string to display as the optional dialog box title.
However, the value isn’t inspected at layout time, so if you
assign the title this way, make sure the dialog box is wide
enough or the text might be truncated.
For a dialog, the label and value are equivalent except
for layout considerations. To change the title at runtime,
use the set_tile function (see “set_tile” in the AutoLISP
Reference).
initial_focus
An edit box is a field that enables the user to enter or edit a single line of text.
An optional label can appear to the left of the box. If the entered text is
longer than the length of the edit box, the edit box scrolls horizontally.
Left-justifying the label and right-justifying the edit box makes it easier to
align edit_box tiles vertically.
label Appears as a title. If specified, the label is left-justified
within the width of the edit_box tile.
value The initial ASCII value placed in the box. It is displayed
left-justified within the edit (input) part of the box. The
value of an edit box is terminated by the null character. If
the user enters more characters than the edit_limit and
the string is truncated, the null character is appended.
errtile
errtile;
An error tile is a text tile that appears at the bottom of a dialog box. By default
it is blank, but programs can display messages in it by setting the value of the
tile whose key is "error". For example:
(set_tile "error" "You can only select one option")
The errtile tile is defined in the base.dcl file.
edit_box | 409
image
: image {
action alignment aspect_ratio color
fixed_height fixed_width height is_enabled
is_tab_stop key mnemonic value width
}
image_button
: image_button {
action alignment allow_accept aspect_ratio
color fixed_height fixed_width height
is_enabled is_tab_stop key mnemonic width
}
The image button tile is a button that displays a graphic image rather than a
label.
list_box
: list_box {
action alignment allow_accept fixed_height
fixed_width height is_enabled is_tab_stop
key label list mnemonic multiple_select tabs
value width
}
A list box contains a list of text strings, arranged in rows. Usually the list is
of variable length, but list boxes can be used for fixed-length lists when a dif-
ferent kind of tile, such as a set of radio buttons, takes up too much space in
the dialog box. When users select a row, it is highlighted. A list box can con-
tain more rows than can fit in the box, so a scroll bar always appears to the
right of the list box. (The scroll bar is enabled only if the list has more items
than can appear at once.) By dragging the scroll bar cursor or clicking on its
arrows, users can scroll through the list box items. Some applications may
allow users to select multiple rows.
See “List Boxes and Pop-Up Lists” on page 374 for instructions on how to
manage lists for list boxes and pop-up lists.
label Text displayed above the list box.
list_box | 411
value A quoted string containing zero ("" ) or more integers,
separated by spaces (no default). Each integer is a zero-
based index that indicates a list item that is initially
selected. If multiple_select is false, value cannot
contain more than one integer.
If the value string is empty (""), then no items in the list
are initially selected. In this case, you don’t need to
specify the value attribute at all.
ok_only
ok_only;
The ok_only tile is a solitary OK button, such as the kind that alert boxes use.
The key of the OK button is "accept" .
The ok_only tile is defined in the base.dcl file.
ok_cancel
ok_cancel;
The ok_cancel tile is a combination of the OK and Cancel buttons, and is the
standard combination for dialog boxes that can originate changes to data.
The key of the Cancel button is "cancel".
The ok_cancel tile is defined in the base.dcl file.
ok_cancel_help
ok_cancel_help;
This tile is the ok_cancel cluster combined with the Help button. The key of
the Help button is "help". Help buttons are recommended for the main dia-
log box of an application and for complex dialog boxes. The function that
ok_cancel_help_errtile
ok_cancel_help_errtile;
ok_cancel_help_info
ok_cancel_help_info;
paragraph
: paragraph {
}
ok_cancel_help_errtile | 413
The illustration above was generated with the following DCL:
: paragraph
{
: concatenation
{
: text_part
{
label = "One";
}
: text_part
{
label = "good turn";
}
}
: text_part {
label = "Deserves another";
}
}
popup_list
: popup_list {
action alignment edit_width fixed_height
fixed_width height is_enabled is_tab_stop
key label list mnemonic tabs value width
}
radio_button
: radio_button {
action alignment fixed_height fixed_width
height is_enabled is_tab_stop key label
mnemonic value width
}
radio_button | 415
value A quoted string (no default). If the value is "1", the
radio_button is on; if it is "0", the radio_button is off; all
other values are equivalent to "0".
If by some chance more than one radio_button in a radio
cluster has value = "1", only the last one is turned on.
(This can happen in a DCL file. Once the dialog box starts,
the PDB feature manages radio buttons and ensures that
only one per cluster is turned on at a time.)
radio_column
: radio_column {
alignment children_alignment
children_fixed_height children_fixed_width
fixed_height fixed_width height label width
}
A radio column contains radio button tiles, only one of which can be selected
at a time. Radio columns present the user with a fixed set of mutually exclu-
sive choices. Radio columns, unlike ordinary columns, can be assigned an
action.
value A quoted string containing the key of the currently
selected radio button (the one whose value is "1").
radio_row
: radio_row {
alignment children_alignment
children_fixed_height children_fixed_width
fixed_height fixed_width height label width
}
A radio row, like a radio column, contains radio button tiles, only one of
which can be selected at a time. Radio rows can be assigned an action.
NOTE Radio rows are not as easy to use as radio columns, because the mouse
has to travel farther. Use radio rows only if they specify two to four options, or if
the labels are short.
row
: row {
alignment children_alignment
children_fixed_height children_fixed_width
fixed_height fixed_width height label width
}
A row is like a column, but its tiles are laid out horizontally instead of verti-
cally, in the order they appear in the DCL file.
A row without a box has no additional attributes beyond the standard layout
attributes.
slider
: slider {
action alignment big_increment fixed_height
fixed_width height key label layout
max_value min_value mnemonic small_increment
value width
}
A slider obtains a numeric value. The user can drag the slider’s indicator to
the left or right (or up or down) to obtain a value whose meaning depends
on the application. This value is returned as a string containing a signed inte-
ger within a specified range (the integer is a 16-bit value, so the maximum
range is –32,768 to 32,767). The application can scale this value as required.
value A quoted string that contains the current (integer) value
of the slider (default: min_value).
row | 417
text
: text {
alignment fixed_height fixed_width height
is_bold key label value width
}
A text tile displays a text string for titling or informational purposes.
Because most tiles have their own label attribute for titling purposes, you
don’t always need to use text tiles. But a text tile that you usually keep blank
is a useful way to display feedback about user actions, error messages, or
warnings.
Alert boxes and error tiles are discussed in “Dialog Box Exit Buttons and Error
Tiles” on page 404 and “DCL Error Handling” on page 381.
If you intend the message to be static, specify it in the label attribute and
don’t specify a width or value . If you intend the message to change at run-
time, specify it in the value attribute and assign a width long enough to con-
tain any strings that you plan to assign the value . Once the dialog box is laid
out, the size of its tiles can’t change, so if you use set_tile to assign a string
longer than the width, the displayed text is truncated.
label The displayed text. When a text tile is laid out, its width
is the larger of either its width attribute, if that is specified
in the DCL, or the width required by its label attribute, if
specified. At least one of these attributes must be
specified.
value Like label, the value attribute specifies a string to display
in the text tile. However, it has no effect on the tile’s
layout.
text_part
: text_part {
label
}
A text part is a text tile that is part of a larger piece of text. The margins of a
text_part are suppressed, so it can be combined with other text_parts into
a concatenation or paragraph tile.
The text_part tile is defined in the base.dcl file. See “paragraph” on page 413
for an example that uses text_part.
A toggle controls a Boolean value ("0" or "1" ). A toggle appears as a small box
with an optional label to the right of the box. A check mark or X appears (or
disappears) when the user selects the box. Toggles enable the user to view or
change the state of on/off options. Toggles are also known as check boxes.
label The text displayed to the right of the toggle box.
value A quoted string containing an integer (default: "0") and
specifying the initial state of the toggle. If the string is
"0", the toggle box is blank (without a check mark). If it is
"1", the box contains a check mark (or an X).
spacer
: spacer {
alignment fixed_height fixed_width
height width
}
A spacer is a blank tile. It is used only for layout purposes to affect the size
and layout of adjacent tiles. To ensure consistency with other dialog boxes,
use spacer tiles only in special cases, because the PDB feature handles spacing
automatically. See “Adjusting the Layout of Dialog Boxes” on page 341.
The spacer tile has no additional attributes beyond the standard layout
attributes.
toggle | 419
spacer_0
spacer_0;
A spacer_0, demonstrated in the following figure, is a spacer that normally
has no width. However, it indicates a point in a tile group where you want
space to be inserted, if the group has to be stretched during layout. If the
spacer_0 tiles in a group are assigned a positive width, all of them are
assigned an equal share of the spacing.
The spacer_0 tile is defined in the base.dcl file.
spacer_1
spacer_1;
The spacer_1 tile, demonstrated in the following figure, is a spacer whose
width and height both equal one. It is used for the smallest kind of spacer
that will still be obvious to the user.
The spacer_1 tile is defined in the base.dcl file.
(new_dialog dlgname dcl_id Begins a new dialog box and displays it, and can
[action [screen-pt]]) also specify a default action
(start_list key [operation [index]]) Starts the processing of a list in the list box or in
the pop-up list dialog box tile
(dimx_tile key) and (dimy_tile key) Retrieves the dimensions of a tile in dialog box
units
(fill_image x1 y1 wid hgt color) Draws a filled rectangle in the currently active
dialog box image tile
(slide_image x1 y1 wid hgt sldname) Displays an AutoCAD slide in the currently active
dialog box image tile
425
426
AutoLISP Function
Synopsis
A
To find a function without knowing its name, use the In this chapter
listings in this appendix. The AutoLISP functions in this Category Summary
427
Category Summary
Functions in this synopsis are organized into the following categories:
Note that programmable dialog box functions are listed in the “Programma-
ble Dialog Box Reference” section of this manual.
Functions are grouped by data type and by the action they perform. Detailed
information on each Visual LISP function is provided in the alphabetical list-
ings in the AutoLISP Reference.
Note that any functions not described here or in other parts of the documen-
tation are not officially supported and are subject to change in future
releases.
Basic Functions
Application-Handling Functions (see page 430)
Arithmetic Functions (see page 431)
Equality and Conditional Functions (see page 432)
Error-Handling Functions (see page 433)
Function-Handling Functions (see page 434)
List Manipulation Functions (see page 435)
String-Handling Functions (see page 437)
Basic Functions
The basic functions consist of the arithmetic, string-handling, equality and
conditional, list manipulation, symbol-handling, function-handling, error-
handling, and application-handling functions.
Application-handling functions
Function Description
(initdia [dialogflag]) Forces the display of the next command's dialog box
Arithmetic functions
Function Description
(– (subtract) [number number] ...) Subtracts the second and following numbers from the
first and returns the difference
(/ (divide) [number number] ...) Divides the first number by the product of the
remaining numbers and returns the quotient
(~ (bitwise NOT) int) Returns the bitwise NOT (1’s complement) of the
argument
(fix number) Returns the conversion of a real into the nearest smaller
integer
(logand [int int ...]) Returns the result of the logical bitwise AND of a list of
integers
Function Description
(logior [int int ...]) Returns the result of the logical bitwise inclusive OR of a
list of integers
(max [number number ...]) Returns the largest of the numbers given
(min [number number ...]) Returns the smallest of the numbers given
(rem [num1 num2 ...]) Divides the first number by the second, and returns the
remainder
Function Description
(= (equal to) numstr [numstr] ...) Returns T if all arguments are numerically equal, and
returns nil otherwise
(/= (not equal to) numstr [numstr] Returns T if the arguments are not numerically equal,
...) and nil if the arguments are numerically equal
(< (less than) numstr [numstr] ...) Returns T if each argument is numerically less than the
argument to its right, and returns nil otherwise
(<= (less than or equal to) numstr Returns T if each argument is numerically less than or
[numstr] ...) equal to the argument to its right, and returns nil
otherwise
Function Description
(> (greater than) numstr [numstr] Returns T if each argument is numerically greater than
...) the argument to its right, and returns nil otherwise
(>= (greater than or equal to) Returns T if each argument is numerically greater than
numstr [numstr] ...) or equal to the argument to its right, and returns nil
otherwise
(Boole func int1 [int2 ...]) Serves as a general bitwise Boolean function
(cond [(test result ...) ...]) Serves as the primary conditional function for AutoLISP
(equal expr1 expr2 [fuzz]) Determines whether two expressions are equal
(repeat int [expr ...]) Evaluates each expression a specified number of times,
and returns the value of the last expression
(while testexpr [expr ...]) Evaluates a test expression, and if it is not nil, evaluates
other expressions; repeats this process until the test
expression evaluates to nil
Error-Handling Functions
The following table provides summary descriptions of the AutoLISP error-
handling functions.
Error-handling functions
Function Description
(alert string) Displays an alert dialog box with the error or warning
message passed as a string
Function Description
Function-Handling Functions
The following table provides summary descriptions of the AutoLISP func-
tion-handling functions.
Function-handling functions
Function Description
(progn [expr] ...) Evaluates each expression sequentially, and returns the
value of the last expression
(untrace function ...) Clears the trace flag for the specified functions
Function Description
(append lst ...) Takes any number of lists and runs them together as one
list
(assoc item alist) Searches an association list for an element and returns
that association list entry
(cdr lst) Returns the specified list, except for the first element of
the list
(foreach name lst [expr ...]) Evaluates expressions for all members of a list
(list [expr ...]) Takes any number of expressions and combines them
into one list
(mapcar function list1 ... listn) Returns a list of the result of executing a function with
the individual elements of a list or lists supplied as
arguments to the function
Function Description
(subst newitem olditem lst) Searches a list for an old item and returns a copy of the
list with a new item substituted in place of every
occurrence of the old item
(vl-every predicate-function list Checks whether the predicate is true for every element
[more-lists]...) combination
(vl-member-if predicate-function Determines whether the predicate is true for one of the
list) list members
(vl-member-if-not predicate- Determines whether the predicate is nil for one of the
function list) list members
(vl-position symbol list) Returns the index of the specified list item
(vl-remove-if predicate-function Returns all elements of the supplied list that fail the test
list) function
(vl-remove-if-not predicate- Returns all elements of the supplied list that pass the test
function list) function
(vl-some predicate-function list Checks whether the predicate is not nil for one element
[more-lists]...) combination
String-handling functions
Function Description
(read [string]) Returns the first list or atom obtained from a string
(strcase string [which]) Returns a string where all alphabetic characters have
been converted to uppercase or lowercase
(strcat [string1 [string2] ...) Returns a string that is the concatenation of multiple
strings
(vl-string-mismatch str1 str2 Returns the length of the longest common prefix for
[pos1 pos2 ignore-case-p]) two strings, starting at specified positions
(vl-string-position char-code str Looks for a character with the specified ASCII code in a
[start-pos [from-end-p]]) string
(vl-string-subst new-str pattern Substitutes one string for another, within a string
string [start-pos])
Function Description
(vl-string-trim char-set str) Removes the specified characters from the beginning
and end of a string
Symbol-Handling Functions
The following table provides summary descriptions of the AutoLISP symbol-
handling functions.
Symbol-handling functions
Function Description
Conversion Functions
The following table provides summary descriptions of the AutoLISP conver-
sion functions.
Conversion functions
Function Description
(angtos angle [mode [precision]]) Converts an angular value in radians into a string
(cvunit value from to) Converts a value from one unit of measurement to
another
Function Description
(grread [track] [allkeys [curtype]]) Reads values from any of the AutoCAD input devices
(tablet code [row1 row2 row3 Retrieves and sets digitizer (tablet) calibrations
direction])
Function Description
(grdraw from to color [highlight]) Draws a vector between two points, in the current
viewport
(grtext [box text [highlight]]) Writes text to the status line or to screen menu areas
Function Description
File-Handling Functions
The following table provides summary descriptions of the AutoLISP file-han-
dling functions.
File-handling functions
Function Description
(findfile filename) Searches the AutoCAD library path for the specified file
(open filename mode) Opens a file for access by the AutoLISP I/O functions
(read-line [file-desc]) Reads a string from the keyboard or from an open file
Function Description
(vl-filename-base "filename") Returns the name of a file, after stripping out the
directory path and extension
(write-char num [file-desc]) Writes one character to the screen or to an open file
Geometric Functions
The following table provides summary descriptions of the AutoLISP geomet-
ric functions.
Geometric functions
Function Description
(inters pt1 pt2 pt3 pt4 [onseg]) Finds the intersection of two lines
(polar pt ang dist) Returns the UCS 3D point at a specified angle and
distance from a point
Function Description
Function Description
(acad_colordlg colornum [flag]) Displays the standard AutoCAD Color Selection dialog
box
(setcfg cfgname cfgval) Writes application data to the AppData section of the
acad.cfg file
(setfunhelp "c:fname" ["helpfile" Registers a user-defined command with the Help facility
["topic" ["command"]]]) so the appropriate help file and topic are called when
the user requests help on that command
Function Description
Function Description
(getangle [pt] [msg]) Pauses for user input of an angle, and returns that angle
in radians
(getfiled title default ext flags) Prompts the user for a file name with the standard
AutoCAD file dialog box, and returns that file name
(getint [msg]) Pauses for user input of an integer, and returns that
integer
(getkword [msg]) Pauses for user input of a keyword, and returns that
keyword
(getorient [pt] [msg]) Pauses for user input of an angle, and returns that angle
in radians
(getpoint [pt] [msg]) Pauses for user input of a point, and returns that point
Function Description
(getreal [msg]) Pauses for user input of a real number, and returns that
real number
(getstring [cr] [msg]) Pauses for user input of a string, and returns that string
(initget [bits] [string]) Establishes keywords for use by the next user input
function call
Function Description
(xdroom ename) Returns the amount of extended data (xdata) space that
is available for an object (entity)
(xdsize lst) Returns the size (in bytes) that a list occupies when it is
linked to an object (entity) as extended data
Object-handling functions
Function Description
(entnext [ename]) Returns the name of the next object (entity) in the
drawing
Function Description
Function Description
(ssget [mode] [pt1 [pt2]] [pt-list] Prompts the user to select objects (entities), and returns
[filter-list]) a selection set
(ssname ss index) Returns the object (entity) name of the indexed element
of a selection set
Function Description
(sssetfirst gripset [pickset]) Sets which objects are selected and gripped
Function Description
(dictadd ename symbol newobj) Adds a non-graphical object to the specified dictionary
(snvalid sym_name) Checks the symbol table name for valid characters
(tblobjname table-name symbol) Returns the entity name of a specified symbol table
entry
Function Description
(vlax-ldata-get dict key [default- Retrieves LISP data from a drawing dictionary
data]) NOTE VLISP extension: requires vl-load-com
Function Description
NOTE Before you can use the AutoLISP extensions, you must issue the follow-
ing command:
(vl-load-com)
Function Description
Function Description
Function Description
(vlax-variant-change-type var Returns the value of a variant after changing it from one
type) data type to another
Function Description
Function Description
Property-handling functions
Function Description
(vlax-get-property obj property) Low-level property get function. May be used for
custom ActiveX object
Function Description
Function Description
Dictionary functions
Function Description
Object-Handling Functions
The following table provides summary descriptions of the AutoLISP object-
handling functions.
Object-handling functions
Function Description
Function Description
Reactor Functions
Reactor functions define, query, and delete reactors and reactor properties.
NOTE Before you can use these functions, you must load AutoLISP reactor
support by issuing the following command:
(vl-load-com)
Reactor functions
Function Description
Function Description
(vlr-deepclone-reactor obj data) Constructs an editor reactor object that notifies of deep
clone events
(vlr-owner-add reactor owner) Adds an object to the list of owners of an object reactor
Function Description
(vlr-reaction-name reactor-type) Returns a list of all callback conditions for this reactor
type
Function Description
Function Description
(vl-doc-set symbol value) Sets the value of a variable in the associated document’s
namespace
(vl-exit-with-error “msg”) Passes control from a VLX error handler to the *error*
function of the associated document namespace
Function Description
Function Description
(vl-bb-set ’variable value) Sets the value of a variable in the blackboard namespace
(vl-load-all “filename”) Loads a file into all open AutoCAD documents, and into
any document subsequently opened during the current
AutoCAD session
(vl-propagate ’variable) Copies the value of a variable into all open AutoCAD
documents, and into any document subsequently
opened during the current AutoCAD session
Function Description
(vl-registry-delete reg-key Deletes the specified key or value from the Windows
[val-name]) Registry
(vl-registry-descendents reg-key Returns a list of subkeys or value names for the specified
[val-names]) Registry key
(vl-registry-read reg-key Returns data stored in the Windows Registry for the
[val-name]) specified key/value pair
output.
463
Window Attributes
The Window Attributes submenu includes selections for customizing the
VLISP windowing environment, controlling attributes such as colors, fonts,
and code formatting. The Syntax Coloring, Current to Prototype, and All to
Prototype items are available only for text editor windows.
VLISP allows you to define prototype configurations for text editor windows.
The prototype becomes the default configuration for these windows. For
example, when you open a new file in the VLISP text editor, the editor
window assumes the attributes and properties of the prototype editor config-
uration. The window prototype includes
Color scheme
Lexical coloring flag
Tab size
Left margin indent
Every time you change and save any text editor window attribute settings,
VLISP will ask you if the modified setting should be used as a prototype for
this window type.
Syntax Coloring
The Syntax Coloring item determines the type of syntax coloring that will be
used for the current file being edited. This option is available when you edit
a file whose file type is not .lsp. When chosen, Syntax Coloring displays the
Color Style dialog box, which provides the following options:
None No color coding.
AutoLISP Use LISP syntax color coding. This color coding scheme is
used for all files of type .lsp.
C++ Use C++ syntax color coding. This is the default for all files
of type .cpp, .c++, .c, .hpp, .h++, and .h.
DCL Use DCL syntax color coding. This is the default for all
files of type .dcl.
SQL Use SQL syntax color coding. This is the default for all files
of type .sql.
NOTE All formatting and “smart” indent features require the AutoLISP lexical
coloring style.
Configure Current
This command allows you to configure the attributes of the current window.
It is applicable to the VLISP text editor and Console windows. The Configure
Current command displays the Window Attributes dialog box:
This dialog box lets you customize the tab width and left margin sizes, cus-
tomize various text colors defined for the current window type, and control
the lexical coloring for that window (if applicable). To select the color with
the aid of the color selection control, click the mouse button in the rectangle
that is painted with the color you want to set.
Text Colors The upper row of rectangles indicates foreground color,
the lower row indicates background color. When you
select a color, the color palette changes its color with
respect to your choice. Use the pull-down list to select the
attribute of the window whose colors you want to change.
:LEX-SPACE. Spaces.
:LEX-STR. Strings.
:LEX-SYM. Symbols.
:LEX-NUM. Reserved for future use.
:LEX-INT. Integers.
:LEX-REAL. Real numbers.
:LEX-COMM. Reserved for future use.
:LEX-COMM1. Comments that begin with one or more
semicolons.
:LEX-COMM2. Inline and multi-line comments
(comments that begin with ;| and end with |;).
:LEX-PAREN. Parentheses.
:LEX-SPEC. Reserved for future use.
:LEX-SPEC1. Reserved for future use.
:LEX-UNKN. Unknown items.
Font
This option opens a standard Windows Font dialog box for selecting the font
to be used in VLISP windows.
Note that for code formatting to work correctly, you must use a fixed (non-
proportional) font.
Environment Options
The Environment Options menu item allows you to set session-wide VLISP
options. For example, you can tell VLISP whether to save text editor files at
set intervals automatically, whether to create automatic backup files, and
how you want to treat attempts to modify protected symbols. Environment
Options is also where you set diagnostic options, such as what statistics to
report during syntax checking, and what level of detail to display when
inspecting drawing objects. You can also set formatting options for AutoLISP
code, and page layout options for printed output.
General Options
The General Options menu item displays a tabbed dialog box containing
General and Diagnostic tabs.
Diagnostic Options
The Diagnostic Options tab displays the following dialog box:
Save Settings
The Save Settings tools option saves the desktop configuration and options
settings. Note that the desktop configuration concerning the child windows
attributes (their presence on the screen, color, position, files loaded) is saved
only when the Save Editor Windows Settings option is on. This option is
available through the Desktop Options tab of the General Options
dialog box.
477
Error Codes
The following table shows the values of error codes generated by AutoLISP.
The ERRNO system variable is set to one of these values when an AutoLISP
function call causes an error that AutoCAD detects. AutoLISP applications
can inspect the current value of ERRNO with (getvar "errno").
The ERRNO system variable is not always cleared to zero. Unless it is inspected
immediately after an AutoLISP function has reported an error, the error that
its value indicates may be misleading. This variable is always cleared when
starting or opening a drawing.
NOTE The possible values of ERRNO, and their meanings, may change in future
releases of AutoCAD.
Value Meaning
0 No error
Value Meaning
13 Invalid handle
Value Meaning
53 Duplicate APPID
Value Meaning
Value Meaning
483
ActiveX (continued) ActiveX (continued)
object properties, 158 converting AutoLISP data types to
AutoLISP functions and , 156 ActiveX data types, 168–174
connecting to application objects, 159 converting object references, 184–185
connecting to applications, 190 determining function needed, 166,
data types 167
converting from AutoLISP to ActiveX, determining how to call functions,
168–174 166–168
enabling AutoLISP support for, 20 determining if method or property
errors, handling of using AutoLISP , applies to object, 180 –181
186–187 determining if object is available for
interacting with other applications, updating, 177 –178
188–194 listing object properties and methods,
calling ActiveX methods with 179–181
vlax-invoke-method , 193 reading object properties, 175
establishing connection to releasing objects and freeing memory,
application, 190 183–184
importing a type library, 188–189 updating object properties, 175 –178
obtaining properties with using ActiveX methods that return
vlax-get-property, 194 values in arguments,
overview, 188 178–179
sample application, 190–192 vla- functions, 165
updating properties with vla-get functions, 165
vlax-put-property, 194 vla-put functions, 165
without importing a type library, vlax- functions, 165
193–194 working with collection objects,
intercepting errors returned from, 186 –187 181–183
languages and environments supporting, variants, using, 169–170
156 changing data type of, 169
loading ActiveX support for AutoLISP , 20 , creating, 169 –170
159 returning data type of, 169
methods, 158 –168, 193 returning value of, 169
in ActiveX and VBA Reference, 158, safearrays and, 173
166–168 , 188 ActiveX and VBA Developer's Guide, 188
objects. See objects ActiveX and VBA Reference, 7, 158, 166–168 ,
overview, 156 188
properties of objects Add File command (Project window shortcut
in ActiveX and VBA Reference, 158 menu), 139
changing, 175–178 Add Lisp Source Files to Project dialog box, 113
getting, 175 Add to Watch command
listing, 179 –181 Apropos results window shortcut menu, 43
reading , 175 Frame Binding window shortcut menu, 82
updating, 175–178 Add Watch command
viewing, 175 Console window shortcut menu, 26
safearrays, using text editor shortcut menu, 30
creating, 170–171 add_list function, 375–376
creating variants containing, 173 adsfunc function, 299
displaying contents of, 171 aesthetics in dialog box design, 347
populating with data, 170–172 :AFTER-EXP trace keyword frame, 84
with variants, 173 alert function, 249, 348 , 357
using AutoLISP functions with ActiveX alignment (DCL attribute), 391–420
methods, 165 –185 All (Apropos filter value), 39
applying object's property to new allow_accept (DCL attribute), 392
object, 175 angles
AutoLISP data types accepted in place of converting radians and degrees, 275–276
ActiveX data type, 174 converting to strings, 274
changing X axis of circle, 176 –178 finding angle between line and X axis, 268
484 | Index
angtof function, 275 Arrange Files command (Project window shortcut
angtos function, 274, 275 menu), 139
angular values, converting radians or degrees, arranging files in Project window, 139
275–276 arrays. See safearrays
Animate command (VLISP Debug menu), 68 ARX applications. See ObjectARX applications
Animate mode, 68 ARX Object ID, 184, 185
anonymous blocks, 313 –314 ASCII code conversions, 276–277
append function, 234 aspect_ratio (DCL attribute), 392
Append With text formatting option , 54 assoc function, 237, 238
appending information to existing Console log association lists, 237
file, 27 associative searches. See searching
Application Compilation Options dialog box , asterisk (*)
116 as Apropos wild-card character, 39
Application Directory dialog box, 111 by file name in text editor status bar, 13
application modules, making. See making atoi function, 376, 377
application modules attaching data
Application Option dialog box, 112 extended data to entities, 323 –324
Application Properties dialog box , 118 to reactor objects, 204
Application Wizard. See Make Application Wizard attaching reactors to AutoCAD drawings. See
application-handling functions, 430 reactors
applications attributes, DCL. See DCL
building. See building applications AutoCAD
managing. See managing VLISP applications accessing AutoCAD groups, 328
running, 108–109, 118 active document, 25
separate-namespace, 123–130 blocks, viewing with VLISP, 99–100
Apropos dialog box, 39–40 calibrating tablets, 286–288
Apropos dialog box options, 39–40 commands
Apropos feature, 38 –43 issuing with AutoLISP, 254 –255
Apropos dialog box, 39–40 redefining, 242 –243
calling from Watch window, 78 configuration control, 258
Complete Word by Apropos feature, 44 –45 coordinate systems, 280–282
Copy to Trace/Log feature, 41 device access and control functions,
Downcase Symbols option, 39 285–288
Filter Flags option, 39 display control, 258–262
Filter Values option, 39 graphics and text windows, 261
inserting symbols from results window, 41 low-level graphics, 261–262
invoking from Console window shortcut overview, 258
menu, 26 entities, viewing with VLISP, 97–98
invoking from text editor shortcut menu, exiting, 20
30 foreign-language support, 255
invoking from Watch window shortcut geometric utilities, 268–273
menu, 78 finding angle between line and X axis,
Match by Prefix option, 40 268
opening Apropos window, 26 , 30, 39 finding distance between two points,
overview, 38 268
results window, 41–43 finding intersection of two lines, 268
searching for AutoLISP symbols by prefix, finding polar coordinates of points,
40 268
shortcut menu options, 42–43 overview, 268
Use WCMATCH option, 39 getting user input from, 285
using search results, 41–43 handling user input, 262 –268
Apropos Window command (VLISP View pausing for input, 255–256
menu), 38 help files, accessing, 284 –285
arbitrary data management, 325–326 inspecting and changing system and
arithmetic functions, 431 –432 environment variables, 257 –258
:ARQ-SUBR-CALLBACK trace keyword frame, 84 menus, controlling, 258–261
object snap, 268 –269
Index | 485
AutoCAD (continued) AutoCAD object model, 156 –159
objects, manipulating, 289 –328 collections of objects, 159
extended data, 318–325 object methods, 158
object-handling, 299–317 object properties, 158
selection set handling, 290–299 AutoCAD objects. See objects
symbol table and dictionary access, AutoCAD Runtime Extension. See ARX
326–328 Autodesk World Wide Web site, 8
xrecord objects, 325–326 AutoLISP
passing pick points to commands, 256–257 accessing AutoCAD groups, 328
pausing for user input, 255 –256 accessing user input with, 285
query and command functions, 254–258 application-handling functions, 430
receiving user input from, 285 arithmetic functions, 431–432
redefining AutoCAD commands, 242–243 AutoCAD display control, 258 –262
related publications, 7–8 graphics and text windows, 261
running with VLISP, 3, 19 low-level graphics, 261–262
sending commands to AutoCAD prompt, menus, 258–261
254–255 overview, 258
text extents, 269–273 calibrating tablets with, 286–288
undoing commands issued with command closing files in programs, 221
function, 257 collection manipulation functions, 450
user input functions, 262–268 comments in program files, 224
accessing user input from devices, 285 communicating with AutoCAD, 253 –288
allowable input, 262–263 converting data types and units,
arbitrary keyboard input, 267 273–283
controlling user-input function device access and control, 285–288
conditions, 265–268 display control, 258–262
getting user input, 262 –265 file-handling functions, 283–285
getxxx functions, 262 –265 geometric utilities, 268–273
input options, 265 –266 getting user input, 262–268
keyword options, 266–267 query and command functions,
pausing for user input, 255 –256 254–258
validating input, 268 compiling and linking AutoLISP programs,
viewing drawing entities, 97–102 104–110
blocks in the drawing database, Application Compilation Options
99–100 dialog box, 116
controlling amount of Inspect choosing a compilation mode, 105,
information, 97 147, 148
entities in the drawing database, choosing build options, 137, 146 –148
97–98 compile example, 107–108
extended data associated with objects, compiling programs from files,
98, 101–102 105–107
selected objects in drawings, 100–101 defining build options, 146–148
symbol tables in the drawing linking function calls, 105, 110 , 152
database, 99 loading and running compiled
AutoCAD command window programs, 108–109
Console window compared to, 16, 23, 25 localizing variables, 148
starting Visual LISP , 12 Make Application output, 117
AutoCAD drawing database, viewing Merge Files mode, 147
blocks in, 99–100 naming an output file, 107
entities in , 97 –98 optimization during compiling, 105
extended data, 101–102 project source files, 139 –141
selected objects in drawings, 100–101 recompiling project source files, 141
symbol tables in, 99 report detail level, 148
AutoCAD groups, accessing, 328 safe optimization, 148, 150–153
AutoCAD mode command (Console window using Application Wizard, 110–116
shortcut menu), 26 using the compiler, 104
486 | Index
AutoLISP (continued) AutoLISP (continued)
using VLISP integrated project Stop Once mode, 69, 70
management facilities, 104 Top-Level debugging mode, 69
conditional branching and looping, 233 using Frame Binding window, 82–86
control characters in strings, 230 –231 using Inspect windows, 88 –102
controlling dialog boxes with, 360–362 using Symbol Service dialog box,
converting data types and units, 273–283 86–88
angular values from radians or using Trace Stack window, 79–86
degrees, 275–276 using Watch window, 77 –78
ASCII code conversions, 276–277 VLISP debugging features, 62–63
coordinate system transformations, developing AutoLISP programs, 22–60
280–283 basic steps, 22
measurement unit conversions, checking for syntax errors, 55–60
277–280 formatting code, 46–55
point transformations, 283 using coding aids, 37–46
string conversions, 273–275 using the Console window, 22–27
synopsis of functions, 439 , 450–451 using the text editor, 27–37
curve measurement functions, 453–454 device access and control functions,
data types, 218–222 285–288
entity names, 220 synopsis of, 440
file descriptors, 220 –221 dialog box management, 359–384
integers, 218–219 action expressions and callbacks,
lists, 219 362–366
reals, 219 application-specific data, 380–381
selection sets, 220 controlling dialog boxes with AutoLISP
strings, 219 programs, 360–362
symbols and variables, 221 –222 DCL error handling, 381–383
VLA-objects, 220 function sequence, 383–384
debugging AutoLISP code handling tiles, 366 –370
break loop process, 70 hiding dialog boxes, 371–374
Break on Error option, 69 image tiles and buttons, 377–380
breakpoint life cycle, 75 list boxes and pop-up lists, 374 –377
checking for syntax errors, 55 –60 nesting dialog boxes, 371
continuable break loops, 71–72 sample block definition dialog box,
continuing program execution, 68, 71 384
Debug-on-Entry flag, 69, 88 dictionary functions, 328 , 455
disabling breakpoints temporarily, 73 display-control functions, 440–441
displaying breakpoints, 74 displaying messages with, 229–230
example, 63–68 dotted pairs, 237–238
highlight colors for breakpoints, 73 equality and conditional functions,
listing breakpoints, 74 432–433
monitoring evaluation results of an equality verification, 233
expression, 67–68 error codes, 477, 478
non-continuable break loops, 72 error-handling, 246–249, 433–434
optimization and bug introduction, exiting quietly, 230
149 expressions, 216–217
Quit Current Level option , 71 extended data functions
removing breakpoints, 73 attaching extended data to entities,
Reset to Top Level option, 71 323–324
running in Animate mode, 68 filtering selection sets for extended
semantic auditing of DCL files, data, 294
340–341 , 382 –383 group codes for extended data, 318
setting breakpoints, 64 –65, 72 handles in extended data, 324–325
starting debugging sessions, 70 managing memory use, 324
starting Trace logging, 76 organization of extended data,
stepping through programs from 319–321
breakpoints, 65–66, 71 registration of applications, 321 –322
Index | 487
AutoLISP (continued) AutoLISP (continued)
retrieving extended data , 318 , adding items to list beginning, 234,
322–323 234
synopsis of, 445 combining lists, 234
file-handling functions dotted pairs, 237–238
accessing help files, 284 –285 grouping related items, 233
file search , 283 –284 point lists, 235–237
synopsis of, 441–442 retrieving items from lists, 233–234
foreign-language support, 255 returning all but first element, 234
formatting code, 223 substituting items, 234, 234
function synopsis (summary), 427–453 synopsis of, 435–436
basic functions, 429–438 loading from text editor, 18
category summary, 428 –429 manipulating AutoCAD objects, 289–328
memory management functions, 449 extended data, 318 –325
namespace communication object-handling, 299–317
functions, 460 selection set handling, 290–299
reactor functions, 456–459 symbol table and dictionary access,
selection set, object, and symbol table 326–328
functions, 445–449 xrecord objects, 325 –326
utility functions, 439–445 matching parentheses, 216–217
Visual LISP extended functions, 450 MDI (multiple document interface), and
VLX namespace functions, 459 –460 AutoLISP, 120–128
Windows Registry functions, 461 error-handling in MDI environment,
function syntax, 217 129–130
function-handling, 238–246 limitations, 130
adding commands, 241 –242 namespaces overview, 120–123
c:xxx functions, 240–243 running an application in its own
defining functions, 238–239 namespace, 122–124
defining functions with arguments, sharing data between namespaces,
245–246 127–128
defun function, 238–246 memory management functions, 449
defun-q function, 239 method invocation functions, 452
local variables in functions, 243–245 namespace communication functions, 460
redefining AutoCAD commands, number handling, 227
242–243 object-handling functions, 299–317
special forms, 246 blocks and, 302–305
synopsis of functions, 434 entity access functions, 305
functions, as lists, 239 entity data functions, 305–315
geometric utilities, 268 –273 entity name functions, 299–305
finding angle between line and X axis, extended data, 318 –325
268 non-graphic object-handling,
finding distance between two points, 316–317
268 polylines (old-style and lightweight),
finding intersection of two lines, 268 315
finding polar coordinates of points, selection sets, 290–299
268 symbol table and dictionary entries,
object snap, 268–269 326–328
overview, 268 synopsis of, 446–447, 455–456
synopsis of, 442–443 xrecord objects, 325 –326
text extents, 269–273 output functions, 229–233
history of, 2 control characters in quoted strings,
integer overflow handling, 218 –219 230–231
interacting with users, 285 displaying messages, 229–230
issuing commands from Console window, wild-card matching, 232 –233
13 overview, 2
list processing functions, 237–238 predefined variables, 226
program files, 223–225
488 | Index
AutoLISP (continued) AutoLISP (continued)
color coding, 224 –225 getting user input, 262–265
comments, 224 getxxx functions, 262 –265
creating new source files, 223 input options, 265–266
editing code in VLISP, 223 keyword options, 266 –267
formatting code, 223 pausing for user input, 255–256
property-handling functions, 453 synopsis of, 444–445
protected symbols, 88, 222 validating input, 268
query and command functions, 254–258 utility functions, 439 –445
configuration control, 258 conversion functions, 439
foreign-language support, 255 device access functions, 440
inspecting and changing system and display-control functions, 440–441
environment variables, file-handling functions, 441–442
257–258 geometric functions, 442 –443
passing pick points to AutoCAD query and command functions,
commands, 256 –257 443–444
pausing for user input, 255 –256 user input functions, 444–445
sending commands to AutoCAD variables
prompt, 254–255 assigning values to, 221, 225
synopsis of, 443–444 data type, 221–222, 225
undoing commands issued with displaying value of, 225
command function, 257 nil variables, 226
reactor functions, 456–459 predefined, 226
referring to entities for multiple sessions, Visual LISP extended functions, 20 , 450
220 collection manipulation functions,
relationship to Visual LISP, 1, 3 450
running from Console prompt, 18–19 curve measurement functions,
running selected lines of code, 19 453–454
selection set handling functions, 290 –299 data conversion functions, 450–451
adding entities, 297 –298 defined, 20
creating selection sets, 290–292 dictionary functions, 455
deleting entities, 297, 298 loading extended functions, 20
finding number of entities, 298 method invocation functions, 452
passing selection sets between AutoLISP object-handling functions, 455–456
and ObjectARX property-handling functions, 453
applications, 299 running, 20
returning entity names, 298 vl-load-com and, 20
selection set filter lists, 292–298 VLX namespace functions, 459–460
synopsis of, 447–448 Windows Registry functions, 461
testing whether an entity is a member, xrecord objects, 325 –326
298 AutoLISP Format Options command (VLISP Tools
selection set, object menu), 47 –54
and symbol table functions, 445 –449 AutoLISP functions. See functions
spaces in code, 223 AutoLISP Reference, 4, 199
special forms, 246 automatically backing up text editor files, 28–29
string-handling, 227–229 , 437–438 :AXVLO-IO-CALLBACK trace keyword frame, 84
symbol and function-handling, 238–246
symbol table access functions, 326–328 B
symbol-handling, 238 , 438 backing up
undoing commands issued with command files in text editor automatically, 28–29
function, 257 restoring from backup files, 29
user input functions backslash (\)
accessing user input from devices, 285 for control characters in quoted strings,
allowable input, 262–263 230–231
arbitrary keyboard input, 267 using within quoted strings, 231
controlling user-input function balance of parentheses, checking in VLISP,
conditions, 265–268 56–60, 216–217
Index | 489
base.dcl file breakpoints (continued)
default_button definition , 336 disabling temporarily, 73
overview, 334 highlight colors for, 73
beeping your PC, 200 life cycle of, 75
:BEFORE-EXP trace keyword frame, 84 listing and viewing, 74
big_increment (DCL attribute), 392 monitoring evaluation results of an
blackboard namespace, 127–128 expression, 67 –68
blackboard variables, 128 Prompt to enter break loop option for
blocks protected symbols, 222
viewing with VLISP , 99–100 removing, 73
working with, 313 Reset to Top Level option, 71, 86
blocks in the drawing database, 99–100 resuming execution from, 71
blocks of text setting, 64–65, 72
converting code to comments, 55 stepping through programs from, 65–66,
converting comments to active text, 55 71
indenting or unindenting, 54 Stop Once mode, 69, 70
saving to new file, 33 , 55 Toggle Breakpoint command, 30
sorting , 55 turning on, 69–71
bold courier type in this manual, 7 Breakpoints window, 74
boldface type in this manual, 7 Browse All Entities command (VLISP View
bookmarking text, 36–37 menu), 97
adding bookmarks, 36 Browse Blocks command (VLISP View menu), 99
clearing, 37 Browse Selection command (VLISP View menu),
deleting bookmarks, 37 100
moving to bookmarks, 36 –37 Browse Tables command (VLISP View menu), 99
overview, 36 browsing. See displaying
selecting text using bookmarks, 37 Build Options dialog box, 147
boxed_column tile, 404 –405 Build Output window
boxed_radio_column tile, 405 error messages in, 60
boxed_radio_row tile, 406 finding location of syntax errors, 60
boxed_row tile, 406 Make Application output, 117
break loops Build Project FAS button (Project window), 138,
Break on Error option, 69 141
Break on Function Entry, 69 , 88 building applications, 103–130
continuable break loops, 71–72 compiling and linking programs, 104–109
continuing program execution, 68, 71 compile example, 107–108
Debug-on-Entry flag, 69, 88 compiling programs from files,
entering, 69–71 105–107
exiting, 68, 71 linking function calls, 105, 110 , 152
non-continuable break loops, 72 loading and running compiled
overview of, 70 programs, 108–109
Prompt to enter break loop option for using the compiler, 104
protected symbols, 222 designing for multiple document
Quit Current Level option, 71 environments, 120–123
stepping through programs in, 65–66, 71 error-handling in MDI environment,
turning on, 69–71 129–130
Break on Error command (VLISP Debug menu), namespaces overview, 120–122
69 running an application in its own
Break on Function Entry command (VLISP Debug namespace, 123–124
menu), 69 sharing data between namespaces,
Breakpoint Service dialog box, 74 127–128
:BREAK-POINT trace keyword frame, 84 making application modules, 110
breakpoints changing application options,
clearing, 73 118–119
continuing program execution, 68, 71 including projects, 145
Debug-on-Entry flag, 69, 88 loading and running VLISP
described , 62 applications, 118
490 | Index
building applications (continued) changing X axis of circle, 176–178
rebuilding applications, 119 Check command, 59 –60
updating applications, 120 errors detected by, 59–60
Built-in function (Apropos filter value), 39 finding location of errors, 60
button tile, 407 running, 60
buttons (dialog box). See tiles (dialog box) Check Selection command (VLISP Tools menu),
60
C Check Syntax command (Project window
.c files, 134 shortcut menu), 139
c:xxx functions, 240–243 Check Text in Editor command (VLISP Tools
caddr function, 236 menu), 60
cadr function, 236, 237 checking for syntax errors, 56–60
calibrating tablets, 286 –288 balance of parentheses, 56–58
Call Point Source command (Trace Stack window from Project window, 139
shortcut menu), 82 using Check command, 59–60
call stack, 62 using color coding, 58
callback events for reactors, 198–199 children_alignment (DCL attribute), 392
callback functions for dialog boxes. See dialog box children_fixed_height (DCL attribute), 393
management, action expressions and children_fixed_width (DCL attribute), 393
callbacks circles
callback functions for reactors, 199–201 changing X axis, 176–178
calling ActiveX methods, 158 –168, 193 returning minimum and maximum
capitalization. See case bounding points, 179
Capitalize option, 55 Clear All Bookmarks command (VLISP Search
car function menu), 37
handling dotted pairs, 237 Clear All Breakpoints command (VLISP Debug
for point lists, 236, 237 menu), 73
retrieving items from lists, 234 Clear Console window command (Console
case (of text and symbols) window shortcut menu), 26
Assign-Protect flag and, 52 clear language in dialog box design, 347
automatic changing of by AutoLISP, 52, 227 clearing. See deleting
conversion by Apropos, 44 client_data_tile function, 380–381
converting selected text, 55 Clipboard
converting with strcase function, 227 –228 Console window shortcut menu
DCL attributes and, 387 commands, 26
dialog box design guidelines, 350 text editor shortcut menu commands,
equality checking and, 233 29–30
symbols, automatic case changing of, 52 , VLISP support for, 33
227 See also copying; moving text
tile names, 336 close function, 221
case sensitivity Close Parenthesis Style options (Format Options
of Apropos search, 44 dialog box), 49
comparison functions and, 233 Close Project command (Project window shortcut
of Complete Word by Match, 44 menu), 139
of DCL attribute names and values, 338 closing
of DCL tile names, 337 all Inspect windows, 97
of equality functions, 233 AutoCAD, 20
of grouping operators, 297 Console log file, 27
of input functions, 266 dialog box closing functions, 421
of mnemonics (in DCL tiles), 399 files in AutoLISP programs, 221
of reserved words (in DCL tiles), 386 projects, 142
of search in text editor, 34 Visual LISP, 20
of symbol names, 221 coding aids
.cch files, 134 Apropos feature, 38–43
cdr function color coding, 17, 38, 58
handling dotted pairs, 237 Complete Word by Apropos feature, 44–45
returning all but first list element, 234 Complete Word by Match feature, 43–44
Index | 491
coding aids (continued) compiling and linking programs
formatting code, 46–55 Application Compilation Options dialog
See also formatting text box, 116
collection objects build options, choosing, 137, 146–148
applying function to every object in, choosing a compilation mode, 105, 147,
181–183 148
collection manipulation functions, 450 compile example, 107–108
evaluating series of functions with each compiling programs from files, 105–107
object in , 181 , 182–183 defining build options, 146–148
overview, 159 identifying the input file, 106
retrieving member objects, 183 linking function calls, 105, 110 , 152
working with, 181–183 loading and running compiled programs,
color (DCL attribute), 393–394 108–109
color coding localizing variables, 148
for AutoLISP code, 224 –225 Make Application output, 117
changing colors, 38 Merge Files mode, 147
of DCL files, 339 optimization during compiling, 105
of files in text editor, 17, 38 output file, naming, 107
scheme for AutoLISP code, 38 project source files, 138 –141
for syntax error detection, 58 recompiling project source files, 132,
colors for breakpoints, 73 138–139, 141
Column style, 48 report detail level, 148
column tile, 407–408 safe optimization, 148, 150–153
combining lists, 234 source files, identifying, 106–107
combining strings in AutoLISP, 228 using Application Wizard, 111
command function using the compiler, 104
foreign-language support, 255 using VLISP integrated project management
passing pick points to AutoCAD facilities, 104
commands, 256 –257 vlisp-compile function, 105–107
pausing for user input, 255 –256 See also Application Wizard; optimizing
sending commands to AutoCAD prompt, application code
254–255 Complete Word by Apropos feature, 44–45
undoing commands, 257 Complete Word by Match feature, 43–44
command prompt, starting Visual LISP from, 12 concatenating strings in AutoLISP , 228
commands concatenation tile, 408
Console window shortcut menu COND-expression clauses, Column style for, 48
commands, 26 conditional branching and looping in AutoLISP,
descriptions on status bar, 13 233
interrupting, 25 configuration control, 258
issuing from Console window, 13 Configure Current command (VLISP Tools
issuing from VLISP menus, 14 menu), 38 , 73
retrieving previous commands, 17 , 24 connecting with ActiveX
text editor shortcut menu commands, to application objects, 159
29–30 to applications, 190
See also specific commands cons function
Comment Block option, 55 adding items to list beginning, 234, 234
comments creating dotted pairs, 237
in AutoLISP program files, 224 consistency in dialog box design, 347
in dialog control language (DCL), 338 Console prompt
Insert Form-Closing Comment option, 50 changing active document, 25
shortcut keys for, 55 clearing, 17, 25
Split Comments option, 51 copying symbol name from Apropos
in unit definition file, 280 window, 42
VLISP comment styles, 53 copying text within the Console window,
Compilation mode option (Build Options dialog 22
box), 147 displaying new prompt without evaluating
compilation report detail level, 148 text, 17, 25
492 | Index
Console prompt (continued) conversion functions (continued)
illustrated, 22 ASCII code conversions, 276–277
pasting text at, 22 coordinate system transformations,
resetting, 17, 25 280–283
running AutoLISP programs from, 18–19 AutoCAD coordinate systems,
Console prompt, displaying variable values, 225 280–282
Console window overview, 280
AutoCAD command window compared to, point transformations, 283
16, 23, 25 specifying coordinate systems, 282
changing active document, 25 valid integer codes, 282
clearing Console prompt, 17 measurement unit conversions, 277–280
color coding of text, 37, 38 point transformations, 283
Complete Word by Apropos feature, 44 –45 string conversions, 273–275
Complete Word by Match feature, 43–44 synopsis of, 439
continuing expression on new line, 23 converting AutoLISP data types to ActiveX data
copying text to the prompt, 23 types, 168 –174
displaying new prompt without evaluating ActiveX and VBA Reference, 168
text, 17, 25 AutoLISP data types accepted in place of
ENTER key and , 22 –23 ActiveX data type, 174
entering multiple expressions before other AutoLISP data types, 174
processing, 23 using safearrays with variants, 173
features, 16 –17 working with safearrays, 170 –173
interactive programming in, 22 working with variants, 169 –170
interrupting commands, 25 converting object references, 184–185
loading AutoLISP programs from text enames and VLA-objects, 184–185
editor, 18 obtaining one object identifier from
logging activity, 27 another, 185
Make Application output, 117 converting string case, 55, 227–228
multiple AutoCAD drawings with , 25 coordinate system transformations
overview, 13, 16–17, 22–23 AutoCAD coordinate systems, 280 –282
printing Frame Binding window value to, entity context and coordinate transform
82 data, 301–305
printing Inspect window object to, 96 overview, 280
printing stack element to, 81 point transformations, 283
printing Watch window variable values, 78 specifying coordinate systems, 282
retrieving previous commands, 17 , 25 valid integer codes, 282
running AutoLISP programs, 18 –19 Copy command
searching input history, 17, 24 Apropos results window shortcut menu, 42
shortcut menu commands, 25 Console window shortcut menu, 26
context-sensitive help. See help feature Frame Binding window shortcut menu, 82
continuable break loops, 71–72 text editor shortcut menu, 30
Continue command (VLISP Debug menu), 68 , Trace Stack window shortcut menu, 81
71 Copy to Clipboard command (Apropos results
continuing expression on new line in Console window shortcut menu), 42
window, 23 Copy to Trace/Log feature (Apropos window), 42
control characters Copy Value command (Watch window shortcut
in DCL strings, 386 menu), 78
in quoted strings, 230–231 copying
controlling amount of Inspect information, 97 Apropos search results to Trace window and
controlling AutoCAD display, 258 –262 log, 42
graphics and text windows, 261 by dragging in text editor, 33
low-level graphics, 261–262 Clipboard support for, 33
menus, 258–262 from Console window, 22
overview, 258 from Frame Binding window to *obj* system
conversion functions, 273 –283 variable, 82
angular values from radians or degrees, from Inspect window to *obj* system
275–276 variable, 96
Index | 493
copying (continued) data types (continued)
from Inspect window to Trace window and strings, 219
log, 96 symbols, 221–222
from output windows, 14 variables, 221–222, 225
selected text to new file, 33, 55 VLA-objects, 220
stack elements to *obj* system variable, 81 converting AutoLISP data types to ActiveX
symbol names from Apropos results data types, 168 –174
window, 42 ActiveX and VBA Reference, using, 168
symbols from Apropos results window, 42 other AutoLISP data types, 174
undoing copy actions, 33 using safearrays with variants, 173
using Console window shortcut menu, 26 working with safearrays, 170 –173
using text editor shortcut menu, 30 working with variants, 169 –170
from Watch window to *obj* system element list formats and, 91–95
variable, 78 extended data organization, 319 –321
from Watch window to Trace window and for tile attribute values, 386
log, 78 Database reactors, 196
See also printing date
correcting text. See text editor changing format for, 55
Courier type in this manual, 7 inserting current date, 55
.cpp files, 134 DCL (dialog control language)
creating acad.dcl file, 334
applications, 111–116 actions, 366
complex entities, 311–313 adjusting layout, 341–346
Console log file, 27 centering buttons, 341–342
new instance of application object, 190 customizing exit button text, 345 –346
new source files, 28, 223 distributing tiles in a cluster, 342–343
reactors, 201–204 example, 341 –342
safearrays, 170–171 space around boxed row or column,
selection sets, 290–292 344–345
variant with an array of four doubles, 173 space at right side or bottom, 344
variants, 169 , 169 –170 space between tiles, 343
Current File option (Find dialog box), 34 attributes, 386 –388
Current Selection option (Find dialog box), 34 case-sensitivity, 387
curve measurement functions, 453–454 data types for values, 386
curve-fit polylines, processing, 315 naming, 387
Customization Guide, 8 numeric values and, 387
Cut command, text editor shortcut menu, 29 overview, 386–388
cutting. See deleting; moving restricted attributes, 387
cvunit function, 277 –278 synopsis of predefined attributes,
388–390
D syntax, 338
data inspection tools. See Frame Binding window; user-defined attributes, 387 –388
Inspect feature; Symbol Service dialog attributes listed by function
box; Trace Stack window action expression specification, 391
data types aligning horizontally or vertically in a
AutoLISP cluster, 391 –420
accepted in place of ActiveX data type, aspect ratio specification, 392
174 background color of image, 393–394
converting to ActiveX data types, bold text specification, 396
168–174 button is selected with ESC key (or
entity names, 220 not), 396
file descriptors, 220 –221 callback specification, 391
integers, 218–219 character used to mask user input, 400
lists, 219 character width units for edit box
overview, 218–222 input, 395
reals, 219 default alignment for all tiles in a
selection sets, 220 cluster, 392
494 | Index
DCL (dialog control language) (continued) DCL (dialog control language) (continued)
default button specification , 397 initial_focus, 396
default height for all tiles in a cluster, is_bold, 396
393 is_cancel, 396
default width for all tiles in a cluster, is_default, 397
393 is_enabled, 397
fixed pitch font for list boxes or pop-up is_tab_stop, 397
lists, 395 key, 397–398
initial availability of tile, 397 label, 398
initial choices for list box or pop-up layout, 398
list, 398 list, 398
initial value of tile, 401 max_value, 399
key of tile to receive initial keyboard min_value, 399
focus, 396 mnemonic, 399
keyboard mnemonic character for tile, multiple_select, 400
399 password_char, 400
maximum characters for edit box small_increment, 400
input, 394 tab_truncate, 401
maximum value for slider, 399 tabs, 400
minimum value for slider, 399 value, 401
multiple selections allowed in list box width, 401
(or not), 400 base.dcl file, 334
slider incremental control value control characters in DCL strings, 386
specification, 392, 400 DCL files, 334–335
slider orientation specification, 398 DCL syntax, 335 –338
specifying if tile is activated , 392 attributes and attribute values, 338
tab placement in character width comments, 338
units, 400 semantic auditing of DCL files,
text larger than tab stop truncated in 340–341
list box or pop-up list (or tile definitions, 336–337
not), 401 tile references, 337
tile height allowed to fill space (or defining dialog boxes, 334–338
not), 395 DCL syntax, 335 –338
tile height specification , 396 referencing DCL files, 334
tile name specification , 397 –398 displaying dialog boxes with VLISP,
tile receives focus with TAB key (or 338–341
not), 397 color coding in text editor, 339
tile text (label) specification , 398 example, 338
tile width allowed to fill space (or not), preview error handling, 340
395 selecting a dialog box from multiple
tile width specification, 401 definitions, 336
attributes listed by name, 391–401 semantic auditing of DCL files,
action, 391 340–341, 382–383
alignment, 391 –420 error handling
allow_accept, 392 alert boxes, 348 , 357–358
aspect_ratio, 392 error tile guidelines, 357
big_increment, 392 forgiving errors, 348–349
children_alignment, 392 preview error handling, 340
children_fixed_height, 393 semantic auditing of DCL files,
children_fixed_width, 393 340–341
color, 393–394 referencing DCL files, 334
edit_limit, 394 symbolic names for colors, 393–394
edit_width, 395 tiles in functional groupings, 402–404
fixed_height, 395 decorative and informative tiles, 403
fixed_width, 395 dialog box exit buttons and error tile,
fixed_width_font, 395 404
height, 396 predefined active tiles, 402
Index | 495
DCL (dialog control language) (continued) Debug menu (VLISP) (continued)
restricted tiles, 404 Step Into command, 65, 72
text clusters, 403 Step Out command, 72
tile clusters, 402 Step Over command, 66, 72
tiles listed by name, 404–420 Stop Once command, 69, 70
boxed_column , 404 –405 Toggle Breakpoint command, 64 , 73
boxed_radio_column, 405 Debug toolbar
boxed_radio_row, 406 Continue button, 71
boxed_row, 406 Quit Current Level button, 71
button, 407 Reset to Top Level button, 71, 86
column, 407–408 Step Indicator button, 65
concatenation, 408 Step Into button, 65, 72
DCL (dialog control language), 420 Step Out button, 72
dialog, 408 Step Over button, 66 , 72
edit_box, 409 Toggle Breakpoint button, 64, 73
errtile, 409 Debug Top-Level mode command (VLISP Debug
image, 410 menu), 69
image_button, 410–411 debugging programs
list_box , 411 –412 break loop process, 70
ok_cancel, 412 Break on Error option, 69
ok_cancel_help, 412–413 breakpoint life cycle, 75
ok_cancel_help_errtile, 413 breakpoints
ok_cancel_help_info, 413 clearing, 73
ok_only, 412 continuing program execution, 68, 71
paragraph, 413–414 Debug-on-Entry flag, 69, 88
popup_list, 414–415 described, 62
radio_button, 415–416 disabling temporarily, 74
radio_column , 416 duration of, 75
radio_row, 416 –417 highlight colors for, 73
row, 417 life cycle of, 75
slider, 417 listing and viewing, 74
spacer, 419 monitoring evaluation results of an
spacer_0, 420 expression, 67 –68
text, 418 Prompt to enter break loop option for
text_part, 418 protected symbols, 222
toggle, 419 removing, 73
DCL files Reset to Top Level option, 71
acad.dcl, 334 resuming execution from, 71
base.dcl, 334 setting, 64–65, 72
color coding, 339 stepping through programs from,
overview, 334–335 65–66, 71
parts of, 334 Stop Once mode, 69, 70
referencing, 334 turning on, 69–71
semantic auditing of, 340–341, 382–383 checking for syntax errors, 56–60
specifying in VLISP, 339 continuable break loops, 71–72
:DCL-ACTION trace keyword frame, 83 continuing program execution, 68, 71
De symbol flag, 88 Debug-on-Entry flag, 69, 88
Debug menu (VLISP) disabling breakpoints temporarily, 74
Animate command , 68 displaying breakpoints, 74
Break on Error command , 69 example, 63 –68
Break on Function Entry command, 69, 88 highlight colors for breakpoints, 73
Clear All Breakpoints command , 73 listing breakpoints, 74
Continue command, 68, 71 monitoring evaluation results of an
Debug Top-Level mode command, 69 expression, 67 –68
overview, 16 non-continuable break loops, 72
Quit Current Level command, 71 optimization and bug introduction, 149
Reset to Top Level command, 71, 86 Quit Current Level option, 71
496 | Index
debugging programs (continued) deleting (continued)
removing breakpoints, 73 spaces from cursor to first non-blank
Reset to Top Level option, 71, 86 character, 55
running in Animate mode, 68 stripping file extensions, 228
semantic auditing of DCL files, 340–341 , text from cursor to end of line, 55
382–383 trailing spaces, 32
setting breakpoints, 64 –65 trailing tab characters, 32
starting debugging sessions, 70 using text editor shortcut keys, 30
starting Trace logging, 76 variables from Watch window, 78
stepping through programs from derived units, 279 –280
breakpoints, 65–66, 71 Descend command (Inspect window shortcut
Stop Once mode, 69 , 70 menu), 96
Top-Level debugging mode, 69 designing dialog boxes. See dialog box design
using Frame Binding window, 82–86 designing for multiple document environments
using Inspect windows, 88–102 AutoLISP limitations, 130
using Symbol Service dialog box, 86–88 error-handling in MDI environment, 129 ,
using Trace Stack window, 79–86 130
using Watch window, 77–78 limitations using AutoLISP, 130
VLISP debugging features, 62 –63 namespaces overview, 120–122
See also break loop mode; checking for running an application in its own
syntax errors; errors; Frame namespace, 123–124
Binding window; Inspect feature; sharing data between namespaces, 127–128
Symbol Service dialog box; Trace detecting syntax errors. See checking for syntax
Stack window errors
Debug-on-Entry symbol flag , 69 , 88 developing programs, 22 –60
defining callback functions, 199–201 basic steps, 22
defining functions. See defun function checking for syntax errors, 56–60
defining new units, 278 formatting code, 46–55
defining projects, 134–142 using coding aids, 38–46
assigning properties, 135–137 using the Console window, 22–27
overview, 134 using the text editor, 27
sample files, 134 device access and control functions, 285 –288
using the Project window, 138 –142 accessing user input, 285
defun function, 238–246 calibrating tablets, 286–288
adding commands, 241 –242 synopsis of, 440
c:xxx functions, 240–243 dialog box design, 331 –358
compatibility with AutoCAD versions, 239 acad.dcl file, 334
defining functions, 238–239 adjusting layout, 341–346
with arguments, 245 –246 centering buttons, 341–342
local variables in functions, 243–245 customizing exit button text, 345 –346
redefining AutoCAD commands, 242–243 distributing tiles in a cluster, 342–343
defun-q function, 275 –276 example, 341 –342
degrees, converting to radians, 276 layout guidelines, 351
Delete Blanks option, 55 space around boxed row or column,
Delete to EOL option, 55 344–345
deleting space at right side or bottom, 344
bookmarks, 37 space between tiles, 343
breakpoints, 73 base.dcl file, 334
clearing Console prompt, 17 defining dialog boxes, 334–338
determining if objects were erased, DCL syntax, 335 –338
177–178 referencing DCL files, 334
disabling reactors, 209 tile definitions, 335–337
entities, 305–306 dialog box components, 332–333
project members, 138–139 displaying dialog boxes with VLISP,
reactor owner objects, 208 338–341
selection set entities, 297 , 298 color coding in text editor, 339
example, 338
Index | 497
dialog box design (continued) dialog box management (continued)
preview error handling , 340 for image buttons, 380
selecting a dialog box from multiple nesting dialog boxes, 371
definitions, 336 overview, 362–366
semantic auditing of DCL files, processing list elements, 376–377
340–341 , 382 –383 for radio clusters, 368–369
error handling for sliders, 369 –370
alert boxes, 348, 357–358 variables, 364
error tile guidelines, 357 application-specific data, 380–381
forgiving errors, 348–349 functions handling, 423
preview error handling , 340 callback reasons, 365–366
semantic auditing of DCL files, edit boxes, 365
340–341 , 382 –383 image buttons, 366
guidelines, 346–358 list boxes, 366
abbreviations, avoiding, 350 reason codes, 365
capitalization, 350 sliders, 365
consistency, 347 canceling dialog boxes
disabling tiles, 351 all dialog boxes, 362, 371, 373
error handling, 357 –358 if Cancel button and Default button the
forgiving errors, 348–349 same, 346
handling keyboard input, 352–353 hiding dialog boxes and, 371
hiding dialog boxes, 352 ok_cancel tiles, 337
international language controlling dialog boxes with AutoLISP
considerations, 353–354 programs, 360–362
layout, 351 displaying the dialog box and
nesting dialog boxes, 351–352 responding to the user,
placement of dialog boxes, 351 360–361
predefined tiles and clusters, 354–358 functions restricted when dialog box is
providing defaults, 352 open, 362
providing help, 349 overview, 360–361
size of dialog boxes, 351 DCL error handling, 381–383
user control over input, 347 –348 auditing level for error messages,
for users with disabilities, 349–350 382–383
planning the design, 333 for multiple DCL files, 381 –382
predefined tiles and clusters, 354–358 testing dialog boxes with programs,
buttons, 354 382
clusters, 354 when loading first time, 381
edit boxes, 355 dialog box opening and closing functions,
image buttons and image tiles, 355 421
list boxes, 355 displaying the dialog box and responding to
radio buttons, radio rows, and radio the user, 360–361
columns, 353 –356 function sequence, 383–384
sliders, 356 function synopsis, 421–423
text, 356 application-specific data handling
toggles, 357 functions, 423
user input dialog box opening and closing
handling keyboard input, 352–353 functions, 421
user control over, 347–348 image tile handling functions, 423
for users with disabilities, 349–350 list box and pop-up list handling
dialog box management, 359–384 functions, 422
action expressions and callbacks tile and attribute handling functions,
for application-specific data, 380–381 421
callback reasons, 365 –366 functions restricted when dialog box is
DCL actions, 366 open, 362
default actions, 366 handling tiles, 366 –370
for edit boxes, 370 changing modes and values at callback
hiding dialog boxes, 372 –373 time, 367–368
498 | Index
dialog box management (continued) directories (continued)
edit boxes, 370 project source directory, 135
initializing modes and values, searching for text in, 34
366–367 Tmp directory for project files, 147
mode codes for mode_tile function , disabling
367 breakpoints temporarily, 73
radio clusters, 368–369 reactors, 209
sliders, 369–370 display control functions, 440 –441
hiding dialog boxes, 371 –374 Display Coordinate System, 281
canceling all dialog boxes, 373 displaying
requesting a password, 373–374 AutoCAD drawing entities, 97–102
user input and, 371 –373 breakpoints, 74
image tiles and buttons, 377 –380 controlling AutoCAD display, 258–262
color attributes, 378 graphics and text windows, 261
creating images, 377–379 low-level graphics, 261–262
handling image buttons, 380 menus, 258–262
image tile handling functions, 423 overview, 258
list boxes and pop-up lists, 374–377 current trace stack, 81
appending list items, 375–376 current value of variables, 16 , 23
changing list items, 375–376 dialog boxes with VLISP, 338 –341
creating lists, 374 –376 color coding in text editor, 339
deleting list items, 376 example, 338
functions handling, 374, 422 preview error handling, 340
inserting list items, 376 selecting a dialog box from multiple
list operations, 374–376 definitions, 336
operation codes for start_list function, semantic auditing of DCL files,
375 340–341, 382–383
processing list elements, 376 –377 display control functions, 440 –441
nesting dialog boxes error trace stack, 86
canceling all dialog boxes, 362, 371 , Frame Binding window for local variables,
373 82
managing, 371 function call stack, 62
overview, 360–361 function definition for Symbol Service
requesting passwords from users, 373 –374 dialog box, 87
sample block definition dialog box, 384 messages in AutoLISP, 229 –230
dialog boxes new Console prompt without evaluating
all dialog boxes, 362 , 371, 373 text, 17, 25
if Cancel and Default button are the same, position of caller expression in Trace Stack
346 window, 82
hiding dialog boxes and, 371 shortcut menus, 26
ok_cancel tiles, 337 source text for functions, 82
dialog control language. See DCL trace stack element information, 81–82
dialog tile, 408 variable values, 225
dictionary and symbol table handling See also Inspect feature; printing
functions, 448–449 distof function, 274
dictionary functions, 328, 455 Document object, 162
dictionary objects, 317 Document reactors, 196
dictnext function , 328 dollar sign ($) prompt. See Console prompt
dictsearch function, 328 done_dialog function
DIESEL string expressions, 261 hiding dialog boxes and, 371
digitizing tablets, calibrating, 286–288 nested dialog boxes and, 371
directories for OK button, 360
application directory, 111 start_dialog calls and, 361
for Console log file, 27 user input based on graphics screen and,
for .fas files, 147 362
Make Application output, 117 Windows and, 361
project home directory, 135 dotted pairs, 237–238
Index | 499
Down option (Find dialog box), 34 Edit toolbar
Downcase option, 55 New File button, 28
Downcase Symbols option (Apropos dialog Open button, 29
box), 39 Redo button, 28
dragging text in text editor, 33 Undo button, 28
drawings edit_box tile, 409
adding entities to, 309–311 edit_limit (DCL attribute), 394
AutoCAD drawing database edit_width (DCL attribute), 395
viewing blocks in, 99–100 editing. See text editor
viewing entities in, 97–98 Editor reactors, 197 –198
viewing extended data , 101 –102 enabling reactors, 209
viewing selected objects in drawings, ENAME Inspect window, 94
100–101 enames
viewing symbol tables in, 99 converting to and from VLA-objects,
multiple AutoCAD drawings with Console 184–185
window, 25 searching for associated handle, 185
opening drawings containing persistent end_image function, 377
reactors, 210 end_list function, 375–376
viewing drawing entities, 97–102 entdel function, 305–306
blocks in the drawing database, ENTER key and Console window processing,
99–100 22–23
controlling amount of Inspect entget function, 160, 306–308, 318 , 322–323
information, 97 entities
entities in the drawing database, adding to drawings, 309–311
97–98 blocks, 313
extended data associated with objects, changing, 308 –309
98, 101–102 complex, 305–306, 311
selected objects in drawings, 100–101 handles and use of, 301
shortcut menu for object line, 98 modifying, 308 –309
symbol tables in the drawing names, obtaining, 299–300
database, 99 obtaining information on, 306 –308
drawline function referring to across multiple sessions, 220
loading from text editor, 18 viewing in drawing database, 97–98
running from Console prompt, 18–19 entity access functions, 305
Drop directives and Safe Optimization, 151, 152 entity data functions, 305–315
.dsk files, 133 adding entities to drawings, 309 –311
:DWF trace keyword frame, 84 anonymous blocks, 313–314
:DWG trace keyword frame, 84 creating complex entities, 311–313
DXF codes. See DXF Reference deleting entities, 305–306
DXF object list (ENAME Inspect window), 94 graphics screen and, 314–315
DXF Reference, 8 modifying entities, 308–309
obtaining entity information, 306 –308
E working with blocks, 313
Ea symbol flag, 88 entity filter lists for selection sets, 292 –298
edit boxes. See tiles (dialog box) examples, 292–293
Edit command (Project window shortcut filtering for extended data, 294
menu), 139 logical grouping of filter tests, 296–297
Edit Global Declarations option (Build Options overview, 292–294
dialog box), 147 relational tests, 295 –296
Edit menu (VLISP) selection set manipulation, 297–298
Match Backward command, 56–58 wild-card patterns in, 294
Match Forward command, 56–58 entity name data type
overview, 15 defined, 220
Redo command , 28 overview, 220
Select Backward command, 56 referring to entities across multiple
Select Forward command, 57 sessions, 220
Undo command, 28 entity name functions, 299–305
500 | Index
entity name functions (continued) errors (continued)
entity access functions, 305 Inspect command error handling, 97
entity context and coordinate transform intercepting with vl-catch-all-apply,
data, 301–305 249–251
entity handles and their uses, 301 MDI environment error-handling, 129–130
overview, 299–300 safe optimization warning messages, 151
retrieving entity names, 299 –300 separate-namespace VLX error handling,
setting entity name to variable name, 300 129–130
entlast function, 300 viewing error trace stack, 86
entmake function, 309–314, 316 vl-catch-all-apply, using, 249–251
entmod function VLX error handling, 129–130
dictionary objects and, 317 See also debugging programs
graphics screen and, 314 escape codes in strings, 230–231
modifying entities, 308–309 establishing ActiveX connection to application,
non-graphic object handling, 316 190
polylines and, 315 events, callback
symbol table objects and, 316 defining callback functions, 199–201
entnext function, 300 , 315 overview, 198–199
:ENTRY-NAMESPACE trace keyword frame, 84 exclamation point (!), for viewing AutoCAD
entsel function, 299–300 variable values, 16, 23
entupd function, 314–315 executing. See loading; running; starting
environment variables, inspecting and Existing Application Properties command (VLISP
changing, 258 File menu), 118
equality and conditional functions, 432–433 exiting
equality verification in AutoLISP , 233 AutoCAD, 20
erasing. See deleting quietly in AutoLISP, 230
ergonomics in dialog box design, 347 Visual LISP, 20
ERRNO system variable, 478 See also closing
error codes expanding
AutoLISP , 477 element list items in Inspect window, 90
Error option for protected symbols, 222 selections using shortcut keys, 31
:ERROR-BREAK trace keyword frame, 84 Expert Wizard mode, 112 , 113
errors exporting functions
AutoLISP error handling, 246–249 to ACAD, 150
bug introduction during optimization, 149 to document namespaces, 123–126
catching and continuing execution, Export-to-ACAD symbol flag, 88
249–251 exposing functions. See exporting functions
checking for syntax errors, 55 –60 expressions
continuing after, 249 –251 AutoLISP, 216–217
dialog box error handling form for, 216
alert boxes, 348, 357–358 formatting styles for, 47
error tile guidelines, 357 function syntax, 217
forgiving errors, 348–349 matching parentheses, 216–217
for multiple DCL files, 381–382 monitoring evaluation results of, 67–68
preview errors, 340 quotation marks and parentheses, 217
semantic auditing of DCL files, EXRXSUBR Apropos filter value, 39
340–341 , 382 –383 EXRXSUBR Inspect window, 91, 94
testing dialog boxes with programs, extended data, 318 –325
382 associated with objects, 98, 101–102
when loading first time, 381 attaching to entities, 323–324
*error* function, 129, 248 filtering selection sets for, 294
error-handling functions, 129 –130, group codes for, 318
246–249 , 433 handles in, 324 –325
from ActiveX function calls, 186–187 managing memory use, 324
handling for ActiveX methods, 186–187 organization of, 319–321
handling for VLX application in its own registration of applications, 321 –322
namespace, 129–130 retrieving, 318 , 322–323
Index | 501
extended data (continued) files (continued)
synopsis of, 445 copying text to new file, 33
viewing associated with objects, 98, creating Console log file, 27
101–102 DCL files, 334–335
extensions to AutoLISP. See Visual LISP, extended acad.dcl, 334
functions base.dcl, 334
color coding, 339
F overview, 334–335
FAS Directory option (Build Options dialog parts of, 334
box), 147 referencing, 334
.fas files semantic auditing of, 340 –341 ,
described , 132 –133 382–383
directory for, 147 specifying in VLISP, 339
loading, 132 FILE Inspect window, 91, 93
loading from project, 138–141 file-handling functions, 283–285, 441 –442
file descriptor data type accessing help files, 284–285
defined, 220 file search, 283–284
overview, 220–221 synopsis of, 441–442
file extensions global declarations file, 147
additional file types, 132–133 input file for compiler, 106
.fas, 132, 133 inserting into text editor window, 55
.lsp, 132, 133 LISP files to include in applications, 114
for project files, 133 loading, 18
.vlx, 117, 119, 133 managing multiple LISP files, 132–134
file extensions, stripping, 228 navigating in text editor, 32
FILE Inspect window, 91 , 93 opening in text editor, 29
File menu (VLISP) output file from compiler, 107
Load File command, 108 , 118–119 resource files to include in applications, 115
Make Application submenu restoring from backups, 29
Existing Application Properties searching for text in, 34
command, 118 stripping file extensions, 228
Make Application command, 119 Support File Search Path, 106
New Application Wizard command, temporary files for projects, 147
111, 145 types, 132 –134
Rebuild Application command , 119 typographical conventions in this manual,
New File command, 28 7
Open File command, 13 unit definition file, 278–280
overview, 15 .vlx files, 117, 119
Toggle Console Log command, 27 See also DCL files
Toggle Trace Log command, 76 fill_image function, 378–379, 380
file-handling functions, 283 –285, 441–442 Filter Flags option (Apropos dialog box), 39
accessing help files, 284–285 filter lists for selection sets, 292–298
file search , 283 –284 examples, 292–293
synopsis of, 441–442 filtering for extended data, 294
files logical grouping of filter tests, 296–297
AutoLISP program files, 223–225 overview, 292–294
color coding, 224 –225 relational tests, 295 –296
comments, 224 selection set manipulation, 297–298
creating new source files, 223 wild-card patterns in, 294
editing code in VLISP, 223 Filter Values option (Apropos dialog box), 40
formatting code, 223 Find command
backing up automatically in text editor, Console window shortcut menu, 26
28–29 text editor shortcut menu, 30
closing in AutoLISP programs, 221 VLISP Search menu, 34
color coding in text editor, 17, 38 Find dialog box, 34–35
compiling programs from, 105 –107 Cancel button, 34
Console log file, 26 Direction options, 34
502 | Index
Find dialog box (continued) formatting AutoLISP code (continued)3
Find button, 34 options, 470–474
Find What field, 34 overriding session settings, 54
illustrated, 34 Plane style, 47
Mark Instances option, 35 preserving existing line breaks, 50–51
Match Case option, 35 saving formatting options, 54
Match Whole Word Only option, 35 selected text, 46
opening, 34 shortcut keys for, 54–55
Search options, 34 Smart Indent feature, 46
See also searching splitting long comments, 51
Find in Files option (Find dialog box), 34 text editor feature, 17
Find in Project option (Find dialog box), 34 Wide style, 48
Find toolbar Frame Binding window, 82–86
Clear All Bookmarks button, 37 adding symbol to Watch window, 82
Next Bookmark button, 36, 37 calling Inspect feature, 82
Previous Bookmark button, 36, 37 calling Symbol Service dialog box, 82
Repeat Search button, 35 copying value to *obj* system variable, 82
Replace button, 35 described, 76
Search button, 34 displaying for local variables, 82
Toggle Bookmark button , 36 displaying value in Console, 82
Find What field (Find dialog box), 34 keyword frames, 83 –85
findfile function, 283 –284 printing value to Console window, 82
finding. See searching shortcut menu commands, 82
fixed_height (DCL attribute), 395 special function call frames, 85
fixed_width (DCL attribute), 395 freeing memory and releasing objects, 183 –184
fixed_width_font (DCL attribute), 395 function call frames, 80
floating point numbers Function symbol command (Trace Stack window
REAL Inspect window, 91 , 92 shortcut menu), 81
floating point numbers, distance to floating point :FUNCTION-ENTRY trace keyword frame, 84
function, 274 function-handling functions, 238–246
forcing line breaks in strings, 231 adding commands, 241–242
foreach function, 80 c:xxx functions, 240 –243
foreign-language support, 255 , 353 –354 defining functions, 238 –239
Format Code in Editor command (VLISP Tools defining functions with arguments,
menu), 46 245–246
Format Date/Time option, 55 defun function, 238–246
Format Options dialog box, 47–52 defun-q function, 243–245
Close Parenthesis Style options, 49 local variables in functions, 243 –245
illustrated, 47 redefining AutoCAD commands, 242–243
Insert Form-Closing Comment option, 50 special forms, 246
Long List Format Style options, 51–52 synopsis of, 434
More Options button, 47 functions
opening, 47 ActiveX versus ename, 156
Preserve Existing Line Breaks option, 50–51 application-handling, 430
Setting Case for Symbols options, 52 Apropos filter value, 39
Split Comments option, 51 arithmetic, 431–432
formatting AutoLISP code, 46–55, 223 as AutoCAD commands, 240 –243
blocks of text, 46 c:xxx functions, 240 –243
Close Parenthesis style, 49 call stack, 62
Column style, 48 callback functions for reactors, 199–201
comment styles, 54 collection manipulation, 450
Format Options dialog box, 47–52 controlling AutoCAD display, 258–262
formatter restrictions, 54 graphics and text windows, 261
in active editor window, 46 –47 low-level graphics, 261–262
inserting form-closing comments, 50 menus, 258–262
long lists, 51 –52 overview, 258
Narrow style, 48 conversion functions
Index | 503
functions (continued) functions (continued)
angular values from radians or creating complex entities, 311–313
degrees, 275–276 deleting entities, 305–306
ASCII code conversions, 276–277 graphics screen and, 314–315
coordinate system transformations, modifying entities, 308–309
280–283 obtaining entity information,
data conversion functions, 450 –451 306–308
measurement unit conversions, working with blocks, 313
277–280 entity name functions, 299–305
point transformations, 283 entity access functions, 305
string conversions, 273–275 entity context and coordinate
synopsis of, 439 transform data, 301 –305
curve measurement, 453–454 entity handles and their uses, 301
Debug-on-Entry flag, 69, 88 overview, 299–300
device access and control retrieving entity names, 299–300
synopsis of, 440 setting entity name to variable name,
device access and control functions, 300
285–288 equality and conditional, 432–433
accessing user input, 285 error-handling, 433–434
calibrating tablets, 286 –288 exporting
dialog box function synopsis, 421–423 to document namespaces, 123–126
application-specific data handling exposing. See functions, exporting
functions, 423 EXRXSUBR Inspect window, 91, 94
dialog box opening and closing extended data functions, 318–325
functions, 421 attaching extended data to entities,
image tile handling functions, 423 323–324
list box and pop-up list handling filtering selection sets for extended
functions, 422 data, 294
tile and attribute handling functions, group codes for extended data, 318
421 handles in extended data, 324–325
dialog box management functions, managing memory use, 324
359–384 organization of extended data,
action expressions and callbacks, 319–321
362–366 registration of applications, 321 –322
application-specific data, 380–381 retrieving extended data, 318,
controlling dialog boxes with AutoLISP 322–323
programs, 360 –362 synopsis of, 445
DCL error handling, 381–383 file-handling functions, 283–285
function sequence, 383 –384 accessing help files, 284–285
handling tiles, 366–370 file search, 283–284
hiding dialog boxes, 371 –374 synopsis of, 441–442
image tiles and buttons, 377 –380 function-handling
list boxes and pop-up lists, 374–377 synopsis of, 434
nesting dialog boxes, 371 function-handling functions, 238–246
sample block definition dialog box, adding commands, 241–242
384 c:xxx functions, 240–243
dictionary functions, 328, 455 defining functions, 238 –239
display control functions, 440–441 defining functions with arguments,
displaying definition for Symbol Service 245–246
dialog box, 87 local variables in functions, 243 –245
displaying source text for, 82 redefining AutoCAD commands,
Drop directives and safe optimization, 151, 242–243
152 special forms, 246
entity access functions, 305 geometric utilities, 268–273
entity data functions, 305–315 finding angle between line and X axis,
adding entities to drawings, 309–311 268
anonymous blocks, 313 –314
504 | Index
functions (continued) functions (continued)
finding distance between two points, foreign-language support, 255
268 inspecting and changing system and
finding intersection of two lines, 268 environment variables,
finding polar coordinates of points, 257–258
268 passing pick points to AutoCAD
object snap, 268–269 commands, 256–257
overview, 268 pausing for user input, 255–256
synopsis of, 442–443 sending commands to AutoCAD
text extents, 269–273 prompt, 254–255
help for, 46 synopsis of, 443–444
linking function calls, 105, 110, 152 undoing commands issued with
list handling command function, 257
synopsis of, 435–436 querying reactors using function calls, 207
list handling functions, 237–238 reactor callback functions, 199 –201
adding items to list beginning, 234 , reactor functions, 456–459
234 restrictions when dialog box is open, 362
combining lists, 234 running from Console prompt, 18–19
dotted pairs, 237 –238 selection set handling functions
grouping related items, 233 adding entities, 297–298
point lists, 235–237 creating selection sets, 290–292
retrieving items from lists, 233 –234 deleting entities, 297–298
returning all but first element, 234 finding number of entities, 298
substituting items, 234 , 234 passing selection sets between AutoLISP
as lists, 240–243 and ObjectARX
local variables in, 243 –245 applications, 299
Make Application output, 117 returning entity names, 298
making available selection set filter lists, 292–298
as AutoCAD commads, 240–243 synopsis of, 447–448
to documents, 125–126 testing whether an entity is a member,
to ObjectARX applications, 88 298
to other VLX applications, 126 special forms, 246
making available to documents, 126 string-handling, 437–438
memory management functions, 449 SUBR Inspect window, 91, 94
method invocation functions, 452 summary of
multiple namespaces affect on, 122 basic functions, 429 –438
namespace communication functions, 460 category summary, 428–429
number handling in AutoLISP, 227 memory management functions, 449
object-handling functions namespace communication
entity access functions, 305 functions, 460
entity data functions, 305–315 reactor functions, 456–459
entity name functions, 299–305 selection set, object, and symbol table
non-graphic object-handling, functions, 445 –449
316–317 symbol-handling functions, 438
polylines, old-style and lightweight, utility functions, 439 –445
315 Visual LISP extended functions,
synopsis of, 446–447 , 455–456 450–453
output functions, 229–233 VLX namespace functions, 459–460
control characters in quoted strings, Windows Registry functions, 461
230–231 symbol table access functions, 326–328
displaying messages, 229–230 syntax conventions in AutoLISP, 217
wild-card matching, 232–233 trace stack and, 79
output windows for, 14 tracing user-defined functions, 88
property-handling functions, 453 typographical conventions in this manual,
protected symbols and , 88 7
query and command functions user input functions
configuration control, 258 accessing user input from devices, 285
Index | 505
functions (continued) functions (continued)
allowable input, 262–263 defined, 20
arbitrary keyboard input, 267 dictionary functions, 455
controlling user-input conditions, loading extended functions, 20
265–268 method invocation functions, 452
getting user input, 262 –265 object-handling functions, 455–456
getxxx functions, 262–265 property-handling functions, 453
input options, 265 –266 running, 20
keyword options, 266–267 vl-load-com and, 20
pausing for user input, 255 –256 VLX namespace functions, 459–460
restrictions when dialog box is open, VLX namespace functions, 459–460
362 Windows Registry functions, 461
synopsis of, 444–445 functions (Apropos filter value), 39
validating input, 268 fundamental units, 279
user-defined
defining with defun, 238–246 G
protected symbols and , 88 geometric utilities, 268–273 , 442 –443
tracing, 88 finding
using with ActiveX methods, 165 –185 angle between line and X axis, 268
applying object's property to new distance between two points, 268
object, 175 intersection of two lines, 268
AutoLISP data types accepted in place of polar coordinates of points, 268
ActiveX data type, 174 object snap, 268 –269
changing X axis of circle, 176 –178 overview, 268
converting AutoLISP data types to synopsis of, 442–443
ActiveX data types, 168 –174 text extents, 269 –273
converting object references, 184–185 get_attr function, 368
determining function needed, getangle function, 263 –264
165–167 GetBoundingBox method , 178
determining how to call functions, getcorner function, 262–263
166–168 getdist function, 263
determining if method or property getenv function, 258
applies to object, 180–181 getfiled function, 284
determining if object is available for getint function, 262 –263
updating, 177–178 getkword function , 263 , 264
listing object properties and methods, getorient function, 263–264
179–181 getpoint function , 262 –263
reading object properties, 175 getreal function, 262 , 263
releasing objects and freeing memory, getstring function, 262, 263
183–184 getting user input, 262–268
updating object properties, 175–178 accessing user input from devices, 285
using ActiveX methods that return allowable input, 262 –263
values in arguments, arbitrary keyboard input, 267
178–179 controlling user-input function
vla- functions, 165 conditions, 265 –268
vla-get functions, 165 getxxx functions, 262 –265
vla-put functions, 165 input options, 265–266
vlax- functions, 165 keyword options, 266 –267
working with collection objects, pausing for user input, 255–256
181–183 validating input, 268
USUBR Inspect window, 91 , 94 getvar function, 257 –258
Visual LISP extensions, 20, 450–456 getxxx functions, 262 –268
collection manipulation functions, Global Declarations file for projects, 147
450 Go to Last Edited command (text editor shortcut
curve measurement functions, menu), 30
453–454 graphics screen and entity data functions,
data conversion functions, 450 –451 314–315
506 | Index
graphscr function, 261 input, user. See dialog box design, user input;
grdraw function, 261–262 getting user input
group codes for regular and extended data , 318 Inquire Extended Data command
grread function, 285 Inspect window shortcut menu, 98
grtext function, 261–262 VLISP View menu, 101
grvecs function, 261–262 Insert Date option, 55
Insert File option, 55
H Insert Form-Closing Comment option (Format
handent function, 301 , 324 Options dialog box), 50
handles Insert Time option, 55
entity handles and their uses, 301 inserting
in extended data, 324–325 files into text editor window, 55
searching for ename associated with, 185 form-closing comments, 50
searching for object associated with, 185 shortcut keys for, 55
searching for, associated with ename, 185 symbols from Apropos results window, 42
searching for, associated with object, 185 using text editor overstrike mode, 30
height (DCL attribute), 396 Inspect command
Help command (Apropos results window shortcut Apropos results window shortcut menu, 42
menu), 43 Console window shortcut menu, 26
help feature error handling, 97
accessing Help files, 284–285 Frame Binding window shortcut menu, 82
for ActiveX object methods, 158 Inspect window shortcut menu, 95
described , 3 text editor shortcut menu, 30
for Apropos results, 42 Trace Stack window shortcut menu, 81
for AutoLISP functions, 46 Inspect Drawing Objects Verbosely option, 97
providing dialog box help, 349 Inspect feature
Symbol Service dialog box , 87 caption (title bar) of window, 89
help function, 284–285 closing all Inspect windows, 97
Help menu (VLISP), 16 copying Inspect window contents to Trace
.hh files, 134 window and log, 96
hiding dialog boxes copying objects to *obj* system variable, 96
canceling and , 371 described, 3, 62, 76
design guidelines, 352 element list content, 89 –90
handling, 371 –374 element list formats, 91–95
highlight colors for breakpoints, 73 error handling, 97
history of Console input expanding element list items, 90
retrieving previous commands, 17 , 24 Inspect window contents, 89–90
searching, 17, 24 inspecting reactors, 206
.hpp files, 134 invoking
for symbol in Apropos results window,
I 42
from Frame Binding window, 82
IDE. See integrated development environment from Symbol Service dialog box, 87
(IDE)
from Trace Stack window, 81
image tiles. See tiles (dialog box) from Watch window, 78
image_button tile, 410–411
Symbol Service feature, 96
importing type libraries, 188–189 maximum element lines per window, 90
improper lists, 237
navigating multiple pages, 90
inches, converting to meters, 278 object line of window, 89
Indent Block option, 54
opening Inspect window, 26, 29 , 89
Indent to Current Level option, 54 opening text editor window containing
indenting code
selected text, 96
shortcut keys for, 54 overview, 88–89
using text editor shortcut keys, 32
passing element values as argument, 96
initget function, 264 , 265–267 printing Inspect window object to Console
initial_focus (DCL attribute), 396
window, 96
input history. See history of Console input shortcut menu commands, 95 , 98
Index | 507
Inspect feature (continued) keyboard shortcuts. See shortcut keys
updating Inspect window, 96 keyword frames (in trace stack)
viewing AutoCAD drawing entities, 97–102 overview, 80, 83
blocks in the drawing database, types at bottom of stack, 83
99–100 types at top of stack, 84–85
controlling amount of Inspect
information, 97 L
entities in the drawing database, label (DCL attribute), 398
97–98 lambda forms, 80
extended data associated with objects, lambda function, 80
98, 101–102 language in dialog box design
selected objects in drawings, 100–101 avoiding abbreviations, 350
symbol tables in the drawing capitalization, 350
database, 99 clarity, 347
viewing AutoCAD object properties, international language considerations,
160–163 353–354
Inspect Next Entity command (Inspect window languages, supporting foreign, 255 , 353–354
shortcut menu), 98 layout (DCL attribute), 398
Inspect Raw Data command (Inspect window layout of dialog boxes, 341 –346
shortcut menu), 98 adjusting space at right side or bottom, 344
Inspect Value command (Watch window shortcut adjusting space between tiles, 343
menu), 78 centering buttons, 341–342
Inspect window. See Inspect feature customizing exit button text, 345 –346
:INSPECT-EVAL trace keyword frame, 83 distributing tiles in a cluster, 342–343
inspecting. See displaying; Inspect feature example, 341 –342
inspection tools. See Frame Binding window; fixing spacing around boxed row or
Inspect feature; Symbol Service dialog column, 344 –345
box; Trace Stack window life cycle of breakpoints, 75
:INSPECT-VERBOSE trace keyword frame, 83 lines (graphic)
INT Inspect window, 92 finding angle between line and X axis, 268
integer data type finding intersection of two lines, 268
for DCL attribute values, 386 old-style and lightweight polylines, 315
defined, 218 processing curve-fit and spline-fit
number handling in AutoLISP, 227 polylines, 315
overflow handling by AutoLISP , 218 –219 lines (text)
overview, 218–219 deleting from cursor to end of line, 55
integrated development environment (IDE) forcing line breaks in strings, 231
components, 2–3 navigating in text editor, 32
returning to, 12 Preserve Existing Line Breaks option, 50–51
starting Visual LISP , 12 , 20 running selected lines of code, 19
Visual LISP as, 1 starting new lines in text editor, 28
interactive programming in Console window, 22 Link mode option (Build Options dialog box),
intercepting program errors, 249–251 148
international language considerations, 255, Linker reactors, 197
353–354 linking
interrupting commands, 25 choosing a link mode, 148, 150
is_bold (DCL attribute), 396 function calls, 105, 110
is_cancel (DCL attribute), 396 safe optimization and, 151 , 152
is_default (DCL attribute), 397 See also compiling and linking programs
is_enabled (DCL attribute), 397 LISP Files to Include dialog box , 113, 145
is_tab_stop (DCL attribute), 397 LISP, reasons for choosing, 2
italic type in this manual, 7 list (DCL attribute), 398
list boxes. See tiles (dialog box)
K list data type
:KBD-BREAK trace keyword frame, 84 defined, 219
key (DCL attribute), 397 –398 overview, 219
keyboard input and dialog box design , 352 –353
508 | Index
list function loading (continued)
forming point lists, 235 project .fas files, 139–141
grouping related items, 233 project source files, 138 –140
list handling reactor support, 196 , 199
adding items to list beginning, 234 selected lines of code, 19
association lists, 237 VLX applications, 118
combining lists, 234 See also opening; running; starting
creating lists, 233 –238 loading compiled programs, 108
dotted pairs, 237 –238 loading VLX applications, 118
grouping related items, 233 local variables, 243–245
improper lists, 237 Local Variables command (Trace Stack window
viewing, 91, 93 shortcut menu), 82
point lists, 235–237 Localize directives and safe optimization, 151 ,
proper lists, 237 153
viewing, 91, 93 Localize Variables option (Build Options dialog
retrieving items from lists, 233 –234 box), 148
returning all but first element, 234 Log command (Inspect window shortcut
substituting items, 234 menu), 96
synopsis of, 435–436 logging Console window activity, 27
LIST Inspect window, 91, 93 appending information to existing file, 27
list_box tile, 411 –412 creating log files, 27
listing quitting the logging process, 27
breakpoints, 74 replacing existing file, 27
condition-function pairs for reactors, 207 logging Trace activity
functions exported by applications, 126 copying Apropos search results to log file,
object properties and methods, 179–181 42
objects that fire notifications to reactors, turning on and off, 76
207 Long List Format Style options (Format Options
reactor callback events, 199 dialog box), 51 –52
reactor types, 198 long lists
reactors of given type, 205 –206 defined, 51
separate-namespace applications associated format style options, 51 –52
with documents, 126 lsa compiler mode parameter, 105
lists, AutoLISP. See list handling lsm compiler mode parameter, 105
Load Application command (VLISP Tools .lsp files
menu), 118 described, 132–133
Load command (Project window shortcut finding strings in, 144
menu), 139 loading from project, 138–139
Load File command (VLISP File menu), 108, 118
load function M
loading compiled programs, 108 Make Application command (VLISP File menu),
loading VLX applications, 118 119
Load Project FAS button (Project window), 138 , Make Application Wizard, 111–116, 145
140 application directory, 111
Load Source command (Project window shortcut application options, 112
menu), 139 building the application, 117
Load Source Files button (Project window), 141 compilation options, 116
Load Text command (VLISP Tools menu), 18 including projects in applications, 145
load_dialog function, 360, 381 LISP files to include, 113, 145
loading naming applications, 112
ActiveX support, 159 order for loading application files, 114
application in its own namespace, 122–123 resource files to include, 115, 145
AutoLISP programs from text editor, 18 Wizard mode, 111
compiled programs, 108 making application modules
dialog boxes, 360, 381 changing application options, 118–119
order for application file loading, 114 creating new applications, 111
order for project file loading , 137 including projects, 145
Index | 509
making application modules (continued) MDI (multiple document interface), and
loading and running VLISP applications, AutoLISP (continued)
118 namespaces overview, 120–122
Make Application output, 117 running an application in its own
object directory for, 119 namespace, 123–124
rebuilding applications, 119 sharing data between namespaces, 127–128
updating applications, 120 measurement unit conversions, 277–280
using Make Application Wizard. See Make memory
Application Wizard freeing, 299, 449
managing dialog boxes. See dialog box garbage collection, 299, 449
management managing extended data memory use, 324
managing VLISP applications, 131–153 memory management functions, 449
defining projects, 134–142 releasing objects and freeing memory,
assigning project properties, 135–137 183–184
overview, 134 menucmd function, 258 –262
using the Project window, 138 –142 menus (VLISP)
managing multiple LISP files, 132–134 See also specific menus
optimizing application code, 146–153 menus (AutoCAD)
choosing a Compilation mode, controlling, 258–262
148–149 customizing. See AutoCAD Customization
choosing a Link mode, 148 , 150 Guide
defining build options, 146–148 menus (VLISP)
safe optimization, 150 –153 issuing VLISP commands from, 14
working with existing projects, 142–145 overview, 12, 14–16
finding strings in project source files, shortcut menus
144 Apropos results window, 42–43
including projects in VLISP Console window, 26
applications, 145 displaying, 26
opening projects, 142 Frame Binding window, 82
manipulating AutoCAD objects, 289–328 Inspect window, 95
extended data, 318–325 Project window, 139
object-handling, 299–317 text editor, 29–30
selection set handling, 290–299 Trace Stack window, 81–82
symbol table and dictionary access, Watch window, 78
326–328 variable contents of, 14–15
xrecord objects, 325–326 Merge Files mode option (Build Options dialog
mapchar function, 376 box), 147
Match Backward command (VLISP Edit menu), Message mode option (Build Options dialog
56–58 box), 148
Match by Prefix option (Apropos dialog box), 38 messages,safe optimization warning, 151
Match Case option (Find dialog box), 35 meters, converting inches to, 278
Match Forward command (VLISP Edit menu), method invocation functions, 452
56–58 methods, ActiveX. See ActiveX, methods
Match Whole Word Only option (Find dialog min_value (DCL attribute), 399
box), 35 mnemonic (DCL attribute), 399
matching parentheses mode codes for, 367
in AutoLISP code, 17 mode_tile function, 367–368
matching parentheses in AutoLISP code, 56–58, Modify command (Inspect window shortcut
216–217 menu), 98
matching wild-cards in strings, 232–233 monitoring
max_value (DCL attribute), 399 evaluation results of an expression, 67 –68
MDI (multiple document interface), and variables during program execution, 67–68
AutoLISP , 120–128 monospace font conventions in this manual, 7
AutoLISP limitations, 130 mouse
error-handling in MDI environment, Console window shortcut menus, 26
129–130 displaying shortcut menus, 26
limitations, AutoLISP, 130 dragging text in text editor, 33
510 | Index
mouse (continued) navigating
See also dialog box design, user input; getting going to position last edited, 32
user input Inspect window pages, 90
moving around. See navigating moving insertion point to parentheses,
moving text 56–58
by dragging in text editor, 33 using bookmarks, 36 –37
Clipboard support for, 33 using text editor shortcut keys, 32
undoing move actions, 33 nentsel function, 299 –300 , 301–305
using Console window shortcut menu, 26 nentselp function, 301 –302, 304
using text editor shortcut menu, 29–30 nesting dialog boxes
multiple document environment canceling all dialog boxes, 362, 371, 373
designing for. See designing for multiple design guidelines, 351–352
document environments managing, 371
multiple documents. See MDI New Application Wizard command (VLISP File
multiple LISP files, managing, 132–134 menu), 104 , 111–116, 125, 145
multiple namespaces. See namespaces New File command (VLISP File menu), 28, 223
Multiple Selection command (Project window new_dialog function
shortcut menu), 139 default actions, 363, 366
multiple_select (DCL attribute), 400 error handling, 382
nested dialog boxes and, 371
N nil values and, 361
names/naming passing dialog name and ID, 360
DCL attributes, 361 –363 Windows and, 361
entity name functions, 299–305 newline character, 231
input file for compiler, 105–106 Next Bookmark command (VLISP Search
Make Application output, 117 menu), 36 , 37
output file from compiler, 107 nil variables
setting entity name to variable name, 300 exiting quietly, 230
stripping file extensions, 228 overview, 226
symbol naming restrictions, 221 non-continuable break loops, 72
symbol table entries that cannot be Nonull (Apropos filter value), 40
renamed, 317 notifications, reactor, 198–199
tiles (dialog box), 336, 337 nth function, 233 –234
typographical conventions in this manual, ntmod function, anonymous blocks and, 313
7 Null (Apropos filter value), 40
variables, 221 number handling in AutoLISP, 227
namespaces
blackboard , 127 –128 O
defined, 120 .ob files, 133
error-handling in MDI environment, Object Coordinate System, 281
129–130 object directory, for applications, 119
functions and multiple, 122–123 Object ID, ARX, 184, 185
making functions available to documents, object model, AutoCAD. See AutoCAD object
125–126 model
making functions available to other VLX Object reactors
applications, 126 attaching data to reactor objects, 204
namespace communication functions, 460 defining callback functions, 201
overview, 120 overview, 197
referencing variables in document to see how an object reactor works,
namespaces, 127 203–204
running an application in its own Object Snap modes, 268–269
namespace, 123–124 ObjectARX applications
sharing data between, 127 –128 called from AutoLISP programs, 149
variables and multiple, 120 –122 making functions available to, 88
VLX namespace functions, 459 –460 passing selection sets between AutoLISP
Narrow formatting style, 48 and, 299
ObjectARX Reference, 8
Index | 511
objects objects (continued)
accessing in ActiveX, 159–163 extended data, 318 –325
circle object example, 163 object-handling, 299–317
moving forward from the application selection set handling, 290–299
object, 162–163 symbol table and dictionary access,
overview, 159–160, 163 326–328
returning pointer to AutoCAD object, xrecord objects, 325 –326
159 methods, 158
specifying VLA-object type, 160 modifying
using Inspect tool to view object with ActiveX, 175–178
properties, 160–163 collection objects, 181–182
ActiveX objects, 156 with entmod, 308–309
applying properties to new object, 175 object-handling functions, 299–317
ARX Object ID of, 184, 185 entity access functions, 305
attaching data to reactor objects, 204 entity data functions, 305–315
changing. See objects, modifying entity name functions, 299–305
collection objects non-graphic object-handling,
collection manipulation functions, 316–317
450 polylines, old-style and lightweight,
evaluating series of functions with each 315
object in , 182 –183 synopsis of, 446–447, 455–456
overview, 159 obtaining one object identifier from
retrieving member objects, 183 another, 185
working with, 181–183 PICKSET Inspect window, 91, 95
converting between enames and properties of, in ActiveX and VBA
VLA-objects, 184–185 Reference, 158
converting object references, 184–185 changing with ActiveX, 175 –178
creating new instance of application defined, 158
object, 190 getting, 175
determining availability for updating , listing, 179–181
177–178 modifying with ActiveX, 175 –178
determining if method or property applies, reading, 175
180–181 updating with ActiveX, 175–178
dictionary objects, 317 viewing, 175
entity access functions, 305 reading object properties, 175
entity data functions, 305–315 releasing objects and freeing memory,
adding entities to drawings, 309–311 183–184
anonymous blocks, 313 –314 searching for handle associated with, 185
creating complex entities, 311–313 searching for object associated with
deleting entities, 305–306 handle, 185
graphics screen and, 314 –315 selection set handling functions
modifying entities, 308–309 adding entities, 297–298
obtaining entity information, creating selection sets, 290–292
306–308 deleting entities, 297, 298
working with blocks, 313 finding number of entities, 298
entity name functions, 299–305 passing selection sets between AutoLISP
entity access functions, 305 and ObjectARX
entity context and coordinate applications, 299
transform data, 301–305 returning entity names, 298
entity handles and their uses, 301 selection set filter lists, 292–298
overview, 299–300 synopsis of, 447–448
retrieving entity names, 299 –300 testing whether an entity is a member,
setting entity name to variable name, 298
300 symbol table objects, 316–317
identifying ARX Object ID of, 185 testing, availability for modification, 177
listing properties and methods, 179–181 availability for reading, 177, 178
manipulating AutoCAD objects, 289–328 availability for updating, 177–178
512 | Index
objects (continued) output functions (continued)
whether erased or not, 177, 178 , 178 displaying messages, 229–230
whether method applies to, 180 wild-card matching, 232 –233
whether property applies to, 180 –181 overriding format settings, 54
whether released or not, 184 overstrike mode in text editor, 30
translating from ARX Object ID to object,
185 P
updating object properties, 175–178 Pa symbol flag, 88
VLA-object type specification , 160 Paper Space DCS, 282
xrecord objects, 325–326 paragraph tile, 413–414
obtaining entity information, 306–308 parentheses
obtaining user input. See getting user input checking balance, 17 , 56–58
ok_cancel tile, 337, 412 Close Parenthesis Style options, 49
ok_cancel_help tile, 412 –413 matching in AutoLISP code, 17 , 56–58,
ok_cancel_help_errtile tile, 413 216–217
ok_cancel_help_info tile, 413 moving insertion point to, 56–58
ok_only tile, 412 navigating in text editor, 32
Open File command (VLISP File menu), 13 selecting text between cursor and, 57
Open Project command (VLISP Project menu), selecting text in text editor and, 30
142, 146 Smart Indent feature and, 46
opening unbalanced, found by formatter, 46
Apropos window, 26 , 30 passing pick points to AutoCAD commands,
AutoLISP source files in text editor, 13 256–257
dialog box opening functions, 421 passing selection sets between AutoLISP and
drawings containing persistent ObjectARX applications, 299
reactors, 210 password_char (DCL attribute), 373 , 400
files in text editor, 29 passwords, requesting from users, 373 –374
Format Options dialog box, 47 Paste command
Inspect window, 26, 29, 87, 89 Console window shortcut menu, 26
new files in text editor, 28 text editor shortcut menu, 30
Project Properties dialog box , 135 , 138 pasting. See copying; moving text
projects, 142 paths
selecting text before opening files, 29 Make Application output, 117
source files in text editor, 13 for project files, 136, 137
starting Visual LISP , 12 , 20 for source files, 105 –106
Symbol Service dialog box, 26, 30 , 42 , 82 , Support File Search Path, 106
86, 96 PAUSE symbol, 226, 255 –256
Watch window, 26 , 30 pausing for user input, 255–256
operators, relational, for selection set filter lists, .pdb files, 133
295–296 persistent reactors
optimizing application code, 146–153 defined, 209
analyzing for optimization correctness, 149 making, 209
bug introduction during, 149 opening drawings containing, 210
choosing a compilation mode, 105, 147 , transient reactors versus, 209 –210
148 PI variable, 226
choosing a Link mode, 148 , 150 pick points, passing to AutoCAD commands,
defining build options, 146–148 256–257
safe optimization, 150 –153 PICKSET Inspect window, 91, 95
See also safe optimization placement of dialog boxes, 351
order for loading Plane style, 47
application files, 114 point lists, 235–237
program files, 108 points
project AutoLISP files, 137 coordinate system transformations,
osnap function, 268–269 280–283
output functions, 229–233 finding distance between, 268
control characters in quoted strings, finding polar coordinates of, 268
230–231 transformations, 283
Index | 513
polylines .prj files
old-style and lightweight, 315 closing, 142
processing curve-fit and spline-fit described, 133
polylines, 315 progn expressions, Narrow style for, 48
populating safearrays with data , 170 –173 programs. See AutoLISP programs
popup_list tile, 414–415 Project menu (VLISP)
predefined attributes, synopsis of, 388 –390 Open Project command, 142 , 146
predefined tiles and clusters (dialog box design overview, 15
guidelines), 354 –358 Project Properties button (Project window), 138,
buttons, 354 146
clusters, 354 Project Properties dialog box
edit boxes, 355 changing order for loading files, 137
image buttons and image tiles, 355 compiler build options, 137, 146–148
list boxes, 355 identifying path name of files, 136 –137
radio buttons, radio rows opening, 141, 146
and radio columns, 353 –356 selecting files to include in project,
sliders, 356 135–136
text, 356 Project window
toggles, 357 adding files to project, 139
predefined variables, AutoLISP , 226 arranging files, 139
Prefix With option , 54 buttons, 138
Preserve Existing Line Breaks option (Format checking syntax of source code, 139
Options dialog box), 50–51 closing projects, 142
Pretty Print command (Inspect window shortcut compiling project files, 141
menu), 96 editing source code, 139, 142
Preview DCL in Editor command (VLISP Tools loading compiled files, 139–141
menu), 339 loading source files, 139
Previous Bookmark command (VLISP Search recompiling project files, 141
menu), 37 removing members, 139
prin1 function, 229–230 saving projects, 139, 142
princ function selecting multiple members, 139–140
exiting quietly, 230 shortcut menu commands, 138
output display from, 16, 229–230 projects
Print command adding files, 139
Apropos results window shortcut menu, 42 checking syntax of source code, 139
Frame Binding window shortcut menu, 82 closing, 142
Inspect window shortcut menu, 96 compiler build options, 137, 146–148
Trace Stack window shortcut menu, 81 compiling source files, 138, 141
print function, 16, 229 –230 defining, 134–142
Print message option for protected symbols, 222 assigning project properties, 135–137
Print Value command (Watch window shortcut overview, 134
menu), 78 using the Project window, 138–142
printing editing source code, 139, 142
files, 15 file types, 132–134
Frame Binding window value to Console finding strings in project source files, 144
window, 82 global declarations file, 147
Inspect window object to Console window, home directory, 135
96 including in VLISP applications, 145
list of arguments to Trace window, 200 loading compiled files, 138–141
messages in AutoLISP, 229–230 loading source files, 138, 139
stack element to Console window, 81 opening, 142
symbol name from Apropos in Console order for loading files, 137
window, 42 overview, 132
Watch window variable values in Console path name of files, 136–137
window, 78 recompiling source files, 138, 141
removing members, 139
saving, 139, 142
514 | Index
projects (continued) radio_row tile, 416–417
searching for text in, 34 random access memory (RAM). See memory
selecting files to include, 135–136 :REACTOR-CALLBACK trace keyword frame, 84
selecting multiple members, 139 –140 reactors
source directory, 135 adding owner object, 208
prompt function, 229 –230 attaching data to reactor objects, 204
Prompt to enter break loop option for protected beeping your PC, 200
symbols, 222 callback events, 198–199
proper lists, 237 callback functions, defining, 199 –201
properties of objects. See objects, properties changing application-specific data
property-handling functions, 453 associated with, 208
Protect-Assign symbol flag, 88 changing callback function link, 207
:PROTECT-ASSIGN trace keyword frame, 84 communicating with applications, 196
protected symbols, 222 creating, 201 –204
prototypes. See tiles (dialog box) defined, 196
defining callback functions, 199–201
Q determining if active, 209
query and command functions determining if persistent or transient, 210
configuration control, 258 disabling, 209
foreign-language support, 255 enabling, 209
inspecting and changing system and events, 198–199
environment variables, 257–258 function reactors, summary, 456–459
passing pick points to AutoCAD function synopsis, 456–459
commands, 256 –257 guidelines for using, 210 –211
pausing for user input, 255 –256 inspecting, 206
sending commands to AutoCAD prompt, listing
254–255 all reactors of given type, 205–206
synopsis of, 443–444 callback events, 199
undoing commands issued with command condition-function pairs, 207
function, 257 objects that fire notifications, 207
querying reactors reactor types, 198
listing all reactors of given type, 205–206 loading support for, 196, 199
using function calls, 207 making persistent, 209
using Inspect tool, 206 modifying definitions, 207 –208
Quit Current Level command (VLISP Debug notifications, 198 –199
menu), 71 opening drawings containing persistent
quitting. See exiting reactors, 210
quotation marks (") persistence, 209–210
and parentheses in expressions, 217 printing list of arguments to Trace window,
using within quoted strings, 231 200
quote function, forming point lists, 235 querying
quoted lists for application-specific data value, 207
Column style for, 48 listing all reactors of given type,
Long List Format Style options, 51–52 205–206
quoted strings listing condition-function pairs, 207
control characters in , 230 –231, 386 listing objects that fire notifications,
for DCL attribute values, 386 207
for name of event triggering callback
R function, 207
for reactor type, 207
radians using function calls, 207
converting degrees to, 275–276
using Inspect tool, 206
converting to degrees, 275–276 removing, 209
radio buttons, radio rows, and radio columns. See
removing owner object, 208
tiles (dialog box) transient versus persistent, 209–210
radio_button tile, 415–416
types, 196 –198
radio_column tile, 416 Database reactors, 196
Index | 515
reactors (continued) replacing (continued)
Document reactors, 196 text using search-and-replace, 35
Editor reactors, 197–198 requesting passwords from users, 373–374
Linker reactors, 197 reserved words for DCL attribute values, 386
listing all types, 198 Reset to Top Level command (VLISP Debug
Object reactors, 197 menu), 71 , 86
using Object reactors, 202–204 Resource Files to Include dialog box, 115, 145
read function, 376 restoring from backup files in text editor, 29
read-char function, 285 restrictions
:READ-ERROR trace keyword frame, 84 formatter, 54
reading object properties, 175 functions restricted when dialog box is
read-line function, 285 open, 362
real data type restricted characters, 221
converting to string, 273–274 restricted DCL attributes, 387
for DCL attribute values, 386 symbol naming restrictions, 221
defined, 219 retrieving
number handling in AutoLISP, 227 commands in Console window
overview, 219 searching for specific commands, 17,
scientific notation for, 219 24
REAL Inspect window, 91, 92 using TAB key, 17, 24
Rebuild Application command (VLISP File entity names, 299 –300
menu), 119 extended data, 98, 101 –102 , 318, 322–323
Rebuild Project FAS button (Project window), items from lists, 233 –234
138 member objects in collections, 183
rebuilding applications, 119 variable values from document namespace,
recompiling project source files, 138 , 141 127
redefining AutoCAD commands, 242–243 return character in quoted strings, 231
Redo command returning to the VLISP IDE, 12
Console window shortcut menu, 26 row tile, 417
text editor shortcut menu, 30 rtos function, 273–274
VLISP Edit menu, 28 Run toolbar
redraw function , 261 Activate AutoCAD button, 19
referencing Load Active Edit Window button, 18
DCL files, 334 Load Selection button, 19
tiles (dialog box), 337 running
variables in document namespaces, 127 application in its own namespace, 123–124
refreshing Trace Stack window contents, 86 applications, 108 –109, 118
regapp function, 321 –323 AutoCAD with Visual LISP, 3, 19
registration of applications, 321–322 AutoLISP programs from Console prompt,
Registry functions for Windows, 461 18–19
relational operators for selection set filter lists Check command, 60
logical grouping of, 296–297 compiled programs, 108 –109
overview, 295–296 in Animate mode, 68
releasing objects and freeing memory, 183–184 selected lines of code, 19
Remove File command (Project window shortcut separate-namespace applications, 123–126
menu), 139 starting Visual LISP, 12, 20
Remove from Watch command (Watch window See also loading; opening; starting
shortcut menu), 78
removing. See deleting S
repeat function, 80 safe optimization, 150–153
repeating earlier searches, 35 build option, 148
Replace command (VLISP Search menu), 35 compiler checking of conditions, 152
Replace dialog box, 35 conditions bypassed by, 151
replacing overview, 150
Console log file, 27 warning messages, 151
list items, 234, 234 Safe Optimize option (Build Options dialog
text using overstrike mode, 30 box), 148
516 | Index
SAFEARRAY Inspect window, 91, 95 searching (continued)
safearrays using Find dialog box, 34 –35
converting to lists, 171 for object associated with handle, 185
creating, 170–171 Select All command (Project window shortcut
creating variant with an array of four menu), 139
doubles, 173 Select Backward command (VLISP Edit menu),
displaying contents of, 171 57
populating with data, 170–172 Select Forward command (VLISP Edit menu), 57
using with variants, 173 selected objects in drawings, 100–101
working with, 170–173 selecting
sample files, AutoLISP , 13 copying selected text to new file, 33, 55
Save Block As option, 33, 55 cursor location and, 30
Save Project As command (Project window entities, 299, 301 –305
shortcut menu), 139 files to include in projects, 135–137
Save Settings command (VLISP Tools menu), 53 multiple members from Project window,
saving 139–140
changes to code when exiting AutoCAD, 20 objects, 299, 301–305
formatting options, 54 running selected lines of code, 19
projects, 139, 142 searching highlighted text, 34
scientific notation for reals, 219 text before opening files, 30
Search menu (VLISP) text between cursor and, 57
Bookmarks submenu using bookmarks, 37
Clear All Bookmarks command, 37 using text editor shortcut keys, 31
Next Bookmark command, 36 selection set data type
Previous Bookmark command, 37 defined, 220
Complete Word by Apropos command, selection set handling functions, 290–299,
44–45 447–448
Complete Word by Match command , 43 selection sets
Find command, 34 adding entities to, 297–298
overview, 15 creating, 290 –292
Replace command, 35 deleting entities from, 297–298
search order, for loading program files, 108 filter lists, 292–298
searching examples, 292–293
Complete Word by Apropos feature, 44 –45 filtering for extended data, 294
Complete Word by Match feature, 43–44 logical grouping of filter tests,
Console input history, 17, 24 296–297
Console window, 26 overview, 292–294
for ename associated with handle, 185 relational tests, 295 –296
for file names, 283 –284 selection set manipulation, 297–298
for strings in project source files, 144 wild-card patterns in, 294
for symbols using Apropos feature, 38–43 finding number of entities, 298
Apropos dialog box options, 39–40 passing between AutoLISP and ObjectARX
Copy to Trace/Log feature, 42 applications, 299
inserting symbols from results returning entity names, 298
window, 42 synopsis of functions for handling,
opening Apropos window, 26 , 30, 39 447–448
overview, 38 testing whether an entity is a member, 298
by prefix, 40 semantic auditing of DCL files, 340–341,
shortcut menu options, 42–43 382–383
using search results, 41–43 semicolon (;) VLISP comment styles, 53
for handle associated with ename, 185 sending commands to AutoCAD prompt,
for handle associated with object, 185 254–255
in text editor, 34–35 set_tile function, 367
overview, 18 setfunhelp function, 285
repeating earlier searches, 35 setq function, 225
replacing text, 35 setting
shortcut menu command , 30 breakpoints, 64–65
Index | 517
setting (continued) spacing in dialog boxes (continued)
variable values in document namespace, fixing spacing around boxed row or
128 column, 344 –345
Setting Case for Symbols options (Format Options special characters
dialog box), 52 control characters in DCL strings, 386
setvar function , 257 –258 control characters in quoted strings,
sharing data between namespaces, 127–129 230–231
shortcut keys relational operators for selection set filter
Complete Word by Apropos feature, 44 lists, 295 –296
Complete Word by Match feature, 43 special forms, 246
text editor special function call frames, 85
for code indentation, 32 spline-fit polylines, processing, 315
for correcting text, 30 Split Comments option (Format Options dialog
for formatting text, 54–55 box), 51
for navigation , 32 SQL, 464
for selecting text, 31 .sql files, 134
shortcut menus ssadd function, 297 –298
Apropos results window, 41 , 42–43 ssdel function, 297 –299
Console window, 26 ssget function
displaying, 26 creating selection sets, 290–292
Frame Binding window, 82 restrictions when dialog box is open, 362
Inspect window, 95, 98 selection set filter lists, 292–298
for object line, 98 sslength function, 298
Project window, 139 ssmemb function , 298
text editor, 29 –30 ssname function, 298
Trace Stack window, 81–82 st compiler mode parameter, 105
Watch window, 78 stack elements
single quotation mark ('), forming point lists, calling Inspect feature for, 81
235 defined, 79
size of dialog boxes, 351 printing to Console window, 81
slashes (//) for DCL comments, 338 types of, 80
slide_image function, 378 , 379 See also Trace Stack window
slider tile, 417 start_dialog function
sliders. See tiles (dialog box) functions restricted during, 362
small_increment (DCL attribute), 400 hiding dialog boxes and, 371
Smart Indent feature, 46 nested dialog boxes and, 371
Snap modes, 268–269 passing dialog control to AutoCAD, 361
Sort Block option, 55 Windows and, 361
sorting start_image function, 377
blocks of text, 55 start_list function , 374 –376
variables in Watch window, 78
Source Position command, Trace Stack window starting
shortcut menu, 82 Animate mode, 68
spacer tiles (dialog box), 337, 420 break loop mode, 69 –71
spaces debugging session, 70
AutoCAD command window versus VLISP See also loading; opening; running
Console window, 23 Trace logging, 76
in AutoLISP code, 223 Visual LISP, 12 , 20
clearing in text editor, 32 status bar (VLISP)
deleting from cursor to first non-blank asterisk next to file names, 13
character, 55 menu command descriptions on, 13
spacing in dialog boxes overview, 13
adjusting space at right side or bottom, 344 toolbar button explanations on, 12
adjusting space between tiles, 343 Step Indicator button , 65
centering buttons, 341 –342 Step Into command (VLISP Debug menu), 65, 72
distributing tiles in a cluster, 342 –343 Step Out command (VLISP Debug menu), 72
518 | Index
Step Over command (VLISP Debug menu), 66, Symbol Service dialog box (continued)
72 opening Inspect window, 87
stepping through programs from breakpoints, overview, 86–87
65–66, 71 symbol flags, 88
Stop Once command (VLISP Debug menu), 69, toolbar, 87
70 updating symbols, 87
storing arbitrary data , 325 –326 symbol table
strcase function, 227–228 names, 233
strcat function, 228 symbol table objects, 316–317
string data type symbol tables in the drawing database, 99
defined, 219 symbolic names for colors, 393–394
overview, 219 symbols
STRING Inspect window, 91, 92 AutoLISP data type, 221–222
strings AutoLISP symbol-handling, 238
ASCII code conversions, 276–277 case setting by VLISP formatter, 52
AutoLISP output functions, 229–233 case setting of, 221, 233
AutoLISP string-handling, 227 –229 Debug-on-Entry flag, 69, 88
concatenating, 228 defined, 221
control characters in quoted strings, finding using Apropos feature, 38–43
230–231 Apropos dialog box options, 39–40
converting angles to, 274 Copy to Trace/Log feature, 42
converting case, 227–228 inserting symbols from results
converting reals to, 273 –274 window, 42
DIESEL string expressions, 261 –262 opening Apropos window, 26, 30, 39
displaying messages, 229–230 overview, 38
finding number of characters, 228 shortcut menu options, 42–43
forcing line breaks in , 231 using search results, 41–43
returning substrings, 228 with prefix, 40
string conversions, 273–275 flags, 88
string-handling functions, 437–438 inserting from Apropos results window, 42
stripping file extensions, 228 naming restrictions, 221
wild-card matching, 232–233 PAUSE symbol, 255–256
stripping file extensions, 228 protected, 222
strlen function, 228 restricted characters, 221
stylistic conventions in this manual, 7 SYMBOL Inspect window, 91, 92–93
subassemblies. See tiles (dialog box) symbol table
SUBR Inspect window, 91 , 94 access functions, 326–328
subst function, 234, 234 entries that cannot be modified, 317
substituting list items, 234, 234 entries that cannot be renamed, 317
substr function, 228 and dictionary handling functions,
Support File Search Path, 105–106 448–449
Symbol command objects, 316–317
Apropos results window shortcut menu, 42 symbol-handling functions, 438
Frame Binding window shortcut menu, 82 using Apropos search results, 41–43
Watch window shortcut menu, 78 syntax checking
symbol flags, 88 balance of parentheses, 56–58
SYMBOL Inspect window, 92 –93 from Project window, 139
Symbol Service command in text editor, 18
Console window shortcut menu, 26 using Check command, 59–60
Inspect window shortcut menu, 96 using color coding, 58
text editor shortcut menu, 30 Syntax Coloring command (VLISP Tools menu),
Symbol Service dialog box 37, 38
adding symbol to Watch window, 87 :SYNTAX-ERROR trace keyword frame, 85
described , 76 system variables
displaying function definition, 87 ERRNO, 478
help feature, 87 specifying values, 257–258
opening, 26, 30 , 42, 82, 86, 96 TABMODE, 286
Index | 519
T text extents, 269 –273
T symbol, 226 text tile, 418
TAB character in quoted strings, 231 text_part tile, 418
TAB key textbox function, 269–273
clearing TAB characters in text editor, 32 textpage function, 261
for Console window history, 23–24 textscr function, 261
tab_truncate (DCL attribute), 401 tiles (dialog box)
tablet function, 286–288 adjusting layout, 341–346
tablets, calibrating, 286–288 centering buttons, 341–342
TABMODE system variable, 286 customizing exit button text, 345 –346
tabs (DCL attribute), 400 distributing tiles in a cluster, 342–343
tblnext function, 326–328 example, 341 –342
tblsearch function, 326–328 fixing spacing around boxed row or
temporary file directory for projects, 147 column, 344 –345
term_dialog function, 362, 371, 373 layout guidelines, 351
terpri function, 231 space at right side or bottom, 344
text editor, Visual LISP , 27 –37 space between tiles, 343
backing up files automatically, 28–29 alert boxes, 348 , 357–358
bookmarking text, 36–37 attributes
color coding of files, 17, 38, 339 case-sensitivity, 387
converting code to comments, 55 data types for values, 386
converting comments to active text, 55 functions handling, 421
copying text, 33 naming, 387
described , 3 numeric values and, 387
editing files, 28 overview, 387
editing project file source code, 139 , 142 restricted attributes, 387
features, 17 –18 synopsis of predefined attributes,
formatting text in active window, 46–47 388–390
indenting or unindenting blocks of text, 54 syntax, 338
loading AutoLISP programs from, 18 user-defined attributes, 387 –388
moving text, 33 attributes listed by function
need for, 27 action expression specification, 391
opening aligning horizontally or vertically in a
existing files, 29 cluster, 391 –420
LISP programs, 13 aspect ratio specification, 392
new files, 28 background color of image, 393–394
window containing text selected from bold text specification, 396
Inspect window, 96 button is selected with ESC key (or
overstrike mode, 30 not), 396
overview, 13, 17–18, 27 callback specification, 391
replacing text, 35 character used to mask user input, 400
restoring from backup files, 29 character width units for edit box
running selected lines of code, 19 input, 395
saving text to new file, 33, 55 default alignment for all tiles in a
searching for text, 34–35 cluster, 392
shortcut keys default button specification, 397
for code indentation, 32 default height for all tiles in a cluster,
for correcting text, 30 393
for formatting text, 54–55 default width for all tiles in a cluster,
for navigation , 32 393
for selecting text, 31 fixed pitch font for list boxes or pop-up
shortcut menu commands, 29–30 lists, 395
sorting text, 55 initial availability of tile, 397
starting new lines, 28 initial choices for list box or pop-up
undoing last edit, 28 list, 398
window prototyping, 467 initial value of tile, 401
See also formatting text
520 | Index
tiles (dialog box) (continued) tiles (dialog box) (continued)
key of tile to receive initial keyboard min_value, 399
focus, 396 mnemonic, 399
keyboard mnemonic character for tile, multiple_select, 400
399 password_char, 400
maximum characters for edit box small_increment, 400
input, 394 tab_truncate, 401
maximum value for slider, 399 tabs, 400
minimum value for slider, 399 value, 401
multiple selections allowed in list box width, 401
(or not), 400 buttons
slider incremental control value when Cancel and Default button are
specification, 392, 400 the same, 346
slider orientation specification, 398 centering, 341–342
specifying if tile is activated , 392 customizing exit button text, 345 –346
tab placement in character width default_button definition, 336–337
units, 400 defining, 336–337
text larger than tab stop truncated in design guidelines, 353–355 , 356
list box or pop-up list (or radio buttons, 353–356
not), 401 callback reason codes, 365
tile height allowed to fill space (or children tiles, 332
not), 395 cluster design guidelines, 354
tile height specification , 396 clusters, handling radio clusters, 368–369
tile name specification , 397 –398 DCL syntax
tile receives focus with TAB key (or attributes and attribute values, 338
not), 397 tile definitions, 336–337
tile text (label) specification , 398 tile references, 337
tile width allowed to fill space (or not), defined, 332
395 disabling, 351
tile width specification, 401 edit boxes
attributes listed by name, 391–401 callback reasons, 365
action, 391 design guidelines, 355
alignment, 391 –420 handling actions and callbacks, 370
allow_accept, 392 error tiles, 357
aspect_ratio, 392 functional groupings, 402 –404
big_increment, 392 decorative and informative tiles, 403
children_alignment, 392 dialog box exit buttons and error tile,
children_fixed_height, 393 404
children_fixed_width, 393 predefined active tiles, 402
color, 393–394 restricted tiles, 404
edit_limit, 394 text clusters, 403
edit_width, 395 tile clusters, 402
fixed_height, 395 handling, 366–370
fixed_width, 395 changing modes and values at callback
fixed_width_font, 395 time, 367–368
height, 396 edit boxes, 370
initial_focus, 396 initializing modes and values,
is_bold, 396 366–367
is_cancel, 396 mode codes for mode_tile function,
is_default, 397 367
is_enabled, 397 radio clusters, 368 –369
is_tab_stop, 397 sliders, 369–370
key, 397–398 image buttons
label, 398 callback reason code, 365
layout, 398 callback reasons, 366
list, 398 color attributes, 378, 379
max_value, 399 creating images, 377–379
Index | 521
tiles (dialog box) (continued) tiles (dialog box) (continued)
design guidelines, 355 predefined tiles and clusters, 354 –358
handling, 380 buttons, 354
image tiles clusters, 354
color attributes, 378, 379 edit boxes, 355
creating images, 377–379 image buttons and image tiles, 355
design guidelines, 355 list boxes, 355
dialog box management, 377–380 radio buttons, radio rows, and radio
functions handling, 423 columns, 353–356
list boxes sliders, 356
appending list items, 375–376 text, 356
callback reason code, 365 toggles, 357
changing list items, 375–376 prototypes
creating lists, 374 –376 naming, 336
deleting list items, 376 overview, 333
design guidelines, 355 tile definitions for, 335–336, 336
functions handling, 374, 422 radio buttons, radio rows, and radio columns
handling, 374 –377 design guidelines, 353–356
inserting list items, 376 handling actions and callbacks,
list operations, 374–376 368–369
operation codes for start_list function, referencing tiles, 337
375 sliders
processing list elements, 376 –377 callback reason code, 365
listed by name, 404–420 design guidelines, 356
boxed_column , 404 –405 handling actions and callbacks,
boxed_radio_column, 405 369–370
boxed_radio_row, 406 spacer tiles, 337, 420
boxed_row, 406 subassemblies
button, 407 children tiles, 332
column, 407–408 overview, 332
concatenation, 408 tile definitions for, 335–336
dialog, 408 toggles, design guidelines, 357
edit_box, 409 typical tiles, 332
errtile, 409 tiles listed by name
image, 410 spacer_1, 420
image_button, 410–411 time
list_box , 411 –412 changing format for, 55
ok_cancel, 412 inserting current, 55
ok_cancel_help, 412–413 Tmp Directory option (Build Options dialog
ok_cancel_help_errtile, 413 box), 147
ok_cancel_help_info, 413 Toggle Breakpoint command
ok_only, 412 text editor shortcut menu, 30
paragraph, 413–414 toolbar button, 64
popup_list, 414–415 VLISP Debug menu, 64, 73
radio_button, 415–416 Toggle Console Log command
radio_column , 416 Console window shortcut menu, 26
radio_row, 416 –417 VLISP File menu, 27
row, 417 toggle tile, 419
slider, 417 Toggle Trace Log command (VLISP File menu),
spacer, 419 76
spacer_0, 420 toggles (dialog box). See tiles (dialog box)
spacer_1, 420 toolbars (VLISP)
text, 418 Apropos results window, 42
text_part, 418 Debug, 64–65
toggle, 419 Edit, 27
naming , 336 , 337 Find, 34, 35
ok_cancel tile, 337 Project window, 138
522 | Index
toolbars (VLISP) (continued) Trace Stack window (continued)
Run, 18, 19 keyword frames, 83 –85
Symbol Service, 87 printing stack elements to Console
Tools, 46 window, 81
Trace Stack window toolbar, 86 refreshing contents, 86
Watch, 78 shortcut menu commands, 81 –82
See also specific toolbars special function call frames, 85
Tools menu (AutoCAD), AutoLISP submenu, stack element lists, 80
Visual LISP Editor command , 12 toolbar, 86
Tools menu (VLISP) trace stack overview, 79
Check Selection command, 60 using the Frame Binding window, 82 –86
Check Text in Editor command, 60 viewing current trace stack, 81
Environment Options submenu viewing error trace stack, 86
AutoLISP Format Options command, See also Frame Binding window
47, 54 Trace symbol flag, 88
General Options command, 28, 69, 97 Trace window
Format Code in Editor command , 46 copying Apropos search results to, 42
Load Application command, 118 copying Inspect window contents to, 96
Load Text command , 18 copying Watch window contents to, 78
overview, 16 described, 63
Save Settings command, 53 messages during start-up, 13
Window Attributes submenu turning Trace logging on and off, 76
Configure Current command, 37, 38, Trace window, printing list of arguments to, 200
73 trans function, 280–283
Syntax Coloring command, 38 transient reactors, 209 –210
Tools menu (VLISP), Interface Tools submenu, Transparent option for protected symbols, 222
Preview DCL in Editor command, 339 turning on. See starting
Tools toolbar type libraries
Format Edit window button , 46 importing, 188 –189
Format Selection button, 46 using ActiveX without importing, 193–194
Help button, 46 typographical conventions in this manual, 7
top forms, 80
:TOP-COMMAND trace keyword frame, 83 U
Touch command (Project window shortcut unbalanced parentheses
menu), 139 checking in VLISP, 56 –58
Tr symbol flag, 88 text editor formatter and, 46
trace function. See AutoLISP Reference unbalanced parentheses, checking in AutoLISP,
Trace log file 216–217
copying Apropos search results to, 42 Uncomment Block option, 55
copying Inspect window contents to, 96 underscore (_)
copying Watch window contents to, 78 for foreign-language support, 255
turning Trace logging on and off, 76 for VLISP comments, 53
Trace Stack command (VLISP View menu), 81 Undo command
Trace Stack window, 79–86 Console window shortcut menu, 26
calling Inspect feature for stack elements, text editor shortcut menu, 30
81 VLISP Edit menu, 28
calling Symbol Service feature for undoing
functions, 81 commands issued with command
copying stack elements to *obj* system function, 257
variable, 81 copy actions, 33
described , 62 , 76 in Console window, 26
displaying Frame Binding window for local in text editor, 28
variables, 82 move actions, 33
displaying position of caller expression, 82 Unindent option, 54
displaying source text for functions, 82 unit conversions, 277–280
displaying stack element information, inches to meters, 278
81–82 overview, 277
Index | 523
unit conversions (continued) V
unit definition file, 278–280 valid name definitions, 278
unit definition file, 278–280 value (DCL attribute), 401
defining new units, 278 variables
derived units, 279–280 action expression variables, 364
fundamental units, 279 adding to Watch window, 78
user comments, 280 assigning values, 221 , 225
valid name definitions, 278 AutoLISP, 225–226
unload_dialog function, 361 AutoLISP data type, 221–222
[Un]Select All command (Project window blackboard variables, 127–128
shortcut menu), 139 case sensitivity of, 221
Up option (Find dialog box), 34 clearing from Watch window, 78
Upcase option, 55 defined, 221
Update command (Inspect window shortcut displaying values, 225
menu), 96 environment variables, inspecting and
updating changing, 258
ActiveX property with vlax-put-property, local variables in functions, 243–245
194 localizing, 148, 152 , 153
applications, 120 monitoring during program execution,
determining if objects available for 67–68
updating, 177–178 multiple namespaces affect on, 121 –122
entities, 308–309 names, case and, 221
object properties, 175–178 naming, 221
symbols in Symbol Service dialog box , 87 nil variables, 226
Use WCMATCH option (Apropos dialog box), 40 predefined, 226
user comments, 280 printing values from Watch window, 78
User Coordinate System, 281 referencing in document namespaces, 127
User function (Apropos filter value), 40 sorting in Watch window, 78
user input functions system variables
accessing user input from devices, 285 specifying values, 257–258
allowable input, 262–263 TABMODE, 286
arbitrary keyboard input, 267 typographical conventions in this manual,
controlling user-input conditions, 265–268 7
getting user input, 262 –265 viewing current value of, 16, 23
getxxx functions, 262–265 VARIANT Inspect window, 91 , 95
input options, 265 –266 variants
keyword options, 266–267 changing data type of, 169
pausing for user input, 255 –256 creating, 169 , 169 –170
restrictions when dialog box is open, 362 creating with an array of four doubles, 173
synopsis of, 444–445 returning data type of, 169
validating input, 268 returning value of, 169
user-defined DCL attributes, 387 –388 using safearrays with, 173
user-defined functions working with, 169 –170
defining with defun function, 238–246 vector_image function, 378
adding commands, 241 –242 vertical bar (|) for VLISP comments, 53
c:xxx functions, 240–243 View menu (VLISP)
compatibility with AutoCAD versions, Apropos Window command, 38
239 Browse Drawing Database submenu
local variables in functions, 243–245 Browse All Entities command, 97
redefining AutoCAD commands, Browse Blocks command, 99
242–243 Browse Selection command, 100
with arguments, 245 –246 Browse Tables command, 99
protected symbols and , 88 Inquire Extended Data command, 101
tracing, 88 overview, 15
:USER-INPUT trace keyword frame, 83 Trace Stack command, 81
USUBR Inspect window, 91 , 94 View Source command (Inspect window shortcut
menu), 96
524 | Index
viewing. See displaying; Inspect feature vla-put functions, 165
Visual LISP vlax- functions, 165
closing, 20 vlax-3d-point function, 173
creating new source files, 223 vlax-create-object function, 190
DCL file references, 339 vlax-dump-object function, 179 –180
exiting, 20 vlax-ename->vla-object function, 184 –185
extended functions, 20, 450 –456 vlax-erased-p function, 177–178
collection manipulation functions, vlax-for function, 182 –183
450 vlax-get-acad-object function, 159
curve measurement functions, vlax-get-object function, 190
453–454 vlax-get-property function, 194
data conversion functions, 450 –451 vlax-import-type-library function, 188–189
dictionary functions, 455 vlax-invoke-method function, 193
method invocation functions, 452 vlax-make-safearray function, 170 –171
object-handling functions, 455 –456 vlax-make-variant function, 169, 169–170
property-handling functions, 453 vlax-map-collection function, 181 –182
IDE components, 2–3 vlax-method-applicable-p function, 180
issuing commands from Console window, vlax-object-released-p function, 184
13 vlax-property-available-p function, 180 –181
overview, 1–3 vlax-put-property function, 194
relationship to AutoCAD, 3 vlax-read-enabled-p function, 177, 178
relationship to AutoLISP , 1, 3 vlax-release-object function, 184
running AutoCAD with, 3, 19 vlax-safearray-fill function, 170, 171–172
starting, 12, 20 vlax-safearray-put-element function, 172–173
user interface, 12–14 vlax-variant-change-type function, 169
Visual LISP Developer’s Guide vlax-variant-type function, 169
additional publications, 4, 7–8 vlax-variant-value function, 169
experience requirements, 4 vlax-write-enabled-p function, 177
guidelines for using, 5 vl-bb-ref function, 127 –128
organization of, 4–5 vl-bb-set function, 127–128
sections of, 4 vl-catch-all-apply, 249
typographical conventions, 7 vl-doc-export function, 125–126, 129
Visual LISP Editor command, AutoCAD Tools vl-doc-import function, 126
menu, 12 vl-doc-ref function, 127, 128
Visual LISP extended functions, 20, 450–456 vl-doc-set function, 127–128
collection manipulation functions, 450 vl-exit-with-error function, 129 –130
curve measurement functions, 453–454 vl-exit-with-value function, 129 –130
data conversion functions, 450 –451 vlide command, 12
defined, 20 vlisp command, 12
dictionary functions, 455 VLISP text editor. See text editor
loading extended functions, 20 VLISP. See Visual LISP
method invocation functions, 452 vlisp-compile function, 104–107 , 110
object-handling functions, 455 –456 compiler modes, 105
property-handling functions, 453 example using, 107–108
running, 20 identifying the input file, 106
vl-load-com and, 20 naming an output file, 107
VLX namespace functions, 459 –460 overview, 104
Visual LISP Tutorial, 4 syntax, 105
vla- functions, 165 vl-list-exported-function, 126
vla-get functions, 165, 175 vl-list-loaded-vlx function, 126
vla-get-center function, 175 vl-load-all function, 122
VLA-objects vl-load-com function, 159
ActiveX and, 160 –163 vl-load-reactors function, 196 , 199
converting between enames and vl-propagate function, 127
VLA-objects, 184–185 vlr-add function, 209
data type, 220 vlr-added-p function, 209
defined, 220 vlr-beep-reaction function, 200
Index | 525
vlr-current-reaction-name function, 207 Watch window (continued)
vlr-data function, 207 opening, 26, 30
vlr-data-set function, 208 overview, 77–78
vlr-owner-add function, 208 printing variable values, 78
vlr-owner-remove function, 208 removing variables, 78
vlr-owners function, 207 shortcut menu commands, 78
vlr-pers function, 209 sorting variables, 78
vlr-pers-p function, 210 toolbar, 78
vlr-pers-release function, 209 :WATCH-EVAL trace keyword frame, 83
vlr-reaction-names function, 198–199 wcmatch function, 232–233
vlr-reactions function, 207 Web site for Autodesk, 8
vlr-reaction-set function, 207 Wide style, 48
vlr-reactors function , 205 –206 width (DCL attribute), 401
vlr-remove function, 209 wild-card characters
vlr-remove-all function, 209 in filter lists for selection sets, 294
vlr-trace-reaction function, 200 in Apropos searches, 39
vlr-type function, 207 matching in strings, 232–233
vlr-types function, 198 Window menu (VLISP), 16
vl-unload-vlx function, 123, 126 windows
.vlx files, 108 –110, 112, 117, 119 , 133 Console, 13, 16–17
VLX namespace functions, 459 –460 controlling AutoCAD graphics and text
windows, 261
W copying text from output windows, 14
warning messages for safe optimization , 151 for VLISP function output, 14
Watch window, 77 –78 menu content variations and, 14–15
Add Watch button, 67 navigating in text editor, 32
adding symbol from Apropos results Trace, 13
window, 43 Windows Registry functions, 461
adding symbol from Frame Binding Wizard Mode dialog box, 111
window, 82 word completion
adding symbol from Symbol Service dialog Complete Word by Apropos feature, 44–45
box, 87 Complete Word by Match feature, 43–44
adding variables, 78 working with existing projects, 142 –145
calling Apropos feature, 78 finding strings in project source files, 144
calling Symbol Service dialog box, 78 including projects in VLISP applications,
clearing all variables, 78 145
copying contents to Trace window, 78 opening projects, 142
copying variable value to *obj* system World Coordinate System, 280
variable, 78 World Wide Web site for Autodesk, 8
described , 3 , 62 , 75
invoking Inspect feature, 78 X
monitoring evaluation results of an X axis of circle, changing, 176 –178
expression, 67–68 xdata. See extended data
monitoring variables during program xdroom function, 324
execution, 67–68 xdsize function , 324
xrecord objects, 325 –326
526 | Index