Autolisp Developer's Guide
Total Page:16
File Type:pdf, Size:1020Kb
AutoCAD 2013 AutoLISP Developer's Guide January 2012 © 2012 Autodesk, Inc. All Rights Reserved. Except as otherwise permitted by Autodesk, Inc., this publication, or parts thereof, may not be reproduced in any form, by any method, for any purpose. Certain materials included in this publication are reprinted with the permission of the copyright holder. Trademarks The following are registered trademarks or trademarks of Autodesk, Inc., and/or its subsidiaries and/or affiliates in the USA and other countries: 123D, 3ds Max, Algor, Alias, Alias (swirl design/logo), AliasStudio, ATC, AUGI, AutoCAD, AutoCAD Learning Assistance, AutoCAD LT, AutoCAD Simulator, AutoCAD SQL Extension, AutoCAD SQL Interface, Autodesk, Autodesk Homestyler, Autodesk Intent, Autodesk Inventor, Autodesk MapGuide, Autodesk Streamline, AutoLISP, AutoSketch, AutoSnap, AutoTrack, Backburner, Backdraft, Beast, Beast (design/logo) Built with ObjectARX (design/logo), Burn, Buzzsaw, CAiCE, CFdesign, Civil 3D, Cleaner, Cleaner Central, ClearScale, Colour Warper, Combustion, Communication Specification, Constructware, Content Explorer, Creative Bridge, Dancing Baby (image), DesignCenter, Design Doctor, Designer's Toolkit, DesignKids, DesignProf, DesignServer, DesignStudio, Design Web Format, Discreet, DWF, DWG, DWG (design/logo), DWG Extreme, DWG TrueConvert, DWG TrueView, DWFX, DXF, Ecotect, Evolver, Exposure, Extending the Design Team, Face Robot, FBX, Fempro, Fire, Flame, Flare, Flint, FMDesktop, Freewheel, GDX Driver, Green Building Studio, Heads-up Design, Heidi, Homestyler, HumanIK, IDEA Server, i-drop, Illuminate Labs AB (design/logo), ImageModeler, iMOUT, Incinerator, Inferno, Instructables, Instructables (stylized robot design/logo),Inventor, Inventor LT, Kynapse, Kynogon, LandXplorer, LiquidLight, LiquidLight (design/logo), Lustre, MatchMover, Maya, Mechanical Desktop, Moldflow, Moldflow Plastics Advisers, Moldflow Plastics Insight, Moldflow Plastics Xpert, Moondust, MotionBuilder, Movimento, MPA, MPA (design/logo), MPI, MPI (design/logo), MPX, MPX (design/logo), Mudbox, Multi-Master Editing, Navisworks, ObjectARX, ObjectDBX, Opticore, Pipeplus, Pixlr, Pixlr-o-matic, PolarSnap, PortfolioWall, Powered with Autodesk Technology, Productstream, ProMaterials, RasterDWG, RealDWG, Real-time Roto, Recognize, Render Queue, Retimer, Reveal, Revit, RiverCAD, Robot, Scaleform, Scaleform GFx, Showcase, Show Me, ShowMotion, SketchBook, Smoke, Softimage, Softimage|XSI (design/logo), Sparks, SteeringWheels, Stitcher, Stone, StormNET, Tinkerbox, ToolClip, Topobase, Toxik, TrustedDWG, U-Vis, ViewCube, Visual, Visual LISP, Voice Reality, Volo, Vtour, WaterNetworks, Wire, Wiretap, WiretapCentral, XSI. All other brand names, product names or trademarks belong to their respective holders. Disclaimer THIS PUBLICATION AND THE INFORMATION CONTAINED HEREIN IS MADE AVAILABLE BY AUTODESK, INC. "AS IS." AUTODESK, INC. DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE REGARDING THESE MATERIALS. Contents Chapter 1 Introduction . 1 Introduction . 1 AutoLISP . 1 About Related AutoLISP Documents . 2 Chapter 2 Using the AutoLISP Language . 3 AutoLISP Basics . 3 AutoLISP Expressions . 3 AutoLISP Function Syntax . 5 AutoLISP Data Types . 6 Integers . 6 Reals . 7 Strings . 8 Lists . 8 Selection Sets . 8 Entity Names . 8 File Descriptors . 9 Symbols and Variables . 10 AutoLISP Program Files . 11 Formatting AutoLISP Code . 11 Comments in AutoLISP Program Files . 11 AutoLISP Variables . 12 Displaying the Value of a Variable . 13 iii Nil Variables . 13 Predefined Variables . 13 Number Handling . 14 String Handling . 14 Basic Output Functions . 16 Displaying Messages . 17 Control Characters in Strings . 18 Wild-Card Matching . 20 Equality and Conditional . 21 List Handling . 21 Point Lists . 23 Dotted Pairs . 26 Symbol and Function Handling . 28 Using defun to Define a Function . 28 C:XXX Functions . 30 Local Variables in Functions . 34 Functions with Arguments . 36 Error Handling in AutoLISP . 38 Using the *error* Function . 39 Catching Errors and Continuing Program Execution . 41 Using AutoLISP to Communicate with AutoCAD . 42 Accessing Commands and Services . 42 Command Submission . 43 System and Environment Variables . 47 Configuration Control . 47 Display Control . 47 Control of Graphics and Text Windows . 48 Control of Low-Level Graphics . 48 Getting User Input . 49 The getxxx Functions . 49 Control of User-Input Function Conditions . 52 Geometric Utilities . 55 Object Snap . 56 Text Extents . 56 Conversions . 61 String Conversions . 61 Angular Conversion . 64 ASCII Code Conversion . 65 Unit Conversion . 67 Coordinate System Transformations . 70 File Handling . 72 File Search . 73 Device Access and Control . 74 Accessing User Input . 74 Using AutoLISP to Manipulate AutoCAD Objects . 74 Selection Set Handling . 75 iv | Contents Selection Set Filter Lists . 77 Passing Selection Sets between AutoLISP and ObjectARX Applications . 85 Object Handling . 86 Entity Name Functions . 86 Entity Data Functions . 92 Entity Data Functions and the Graphics Screen . 102 Old-Style Polylines and Lightweight Polylines . 103 Non-Graphic Object Handling . 104 Extended Data - xdata . 106 Organization of Extended Data . 107 Registration of an Application . 109 Retrieval of Extended Data . 110 Attachment of Extended Data to an Entity . 111 Management of Extended Data Memory Use . 112 Handles in Extended Data . 112 Xrecord Objects . 113 Symbol Table and Dictionary Access . 114 Symbol Tables . 114 Dictionary Entries . 116 Chapter 3 Appendixes . 119 AutoLISP Function Synopsis . 119 Category Summary . 119 Basic Functions . 121 Application-Handling Functions . 121 Arithmetic Functions . 122 Equality and Conditional Functions . 125 Error-Handling Functions . 126 Function-Handling Functions . 127 List Manipulation Functions . 128 String-Handling Functions . 131 Symbol-Handling Functions . 133 Utility Functions . 134 Conversion Functions . 134 Device Access Functions . 135 Display Control Functions . 136 File-Handling Functions . 137 Geometric Functions . 139 Query and Command Functions . 139 User Input Functions . 141 Selection Set, Object, and Symbol Table Functions . 142 Extended Data-Handling Functions . 143 Object-Handling Functions . 143 Selection Set Manipulation Functions . 145 Symbol Table and Dictionary-Handling Functions . 146 Contents | v Memory Management Functions . 147 VLX Namespace Functions . 147 Namespace Communication Functions . 148 Property List (Plist) Functions . 149 AutoLISP Error Codes . 149 Error Codes . 149 Index . 157 vi | Contents Introduction 1 Introduction ® For years, AutoLISP has set the standard for customizing AutoCAD® on Windows®. AutoCAD also supports AutoLISP, but does not support many of ® the Visual LISP functions or the Microsoft ActiveX Automation interface. AutoCAD does not have an integrated development environment like AutoCAD on Windows does, so the creation and editing of LSP files must be done with text editor such as TextEdit. AutoLISP AutoLISP is a programming language designed for extending and customizing the functionality of AutoCAD. 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. AutoLISP was introduced as an application programming interface (API) in AutoCAD 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. Developing AutoLISP programs for AutoCAD is done by writing code in a text editor, then loading the code into AutoCAD and running it. Debugging your program is handled by adding statements to print the contents of variables at strategic points in your program. You must figure out where in your program to do this, and what variables you need to look at. If you discover you do not have enough information to determine the error, you must go back and change 1 the code by adding more debugging points. And finally, when you get the program to work correctly, you need to either comment out or remove the debugging code you added. About Related AutoLISP Documents In addition to the AutoLISP Reference, several other AutoCAD publications may be required by users building applications with AutoLISP: ■ AutoCADCustomization Guide contains basic information on creating customized AutoCAD applications..