autocad-2004-activex-and-vba-developer-s-guide
February 2003 AutoCAD ® ActiveX and VBA Developers’ Guide 2004 Copyright © 2003 Autodesk, Inc. All Rights Reserved This publication, or parts thereof, may not be reproduced in any form, by any method, for any purpose. AUTODESK, INC., MAKES NO WARRANTY, EITHER EXPRESS 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 Props, 3D Studio, 3D Studio MAX, 3D Studio VIZ, 3DSurfer, ActiveShapes, ActiveShapes (logo), Actrix, ADI, AEC Authority (logo), AEC-X, Animator Pro, Animator Studio, ATC, AUGI, AutoCAD, AutoCAD LT, AutoCAD Map, Autodesk, Autodesk Inventor, Autodesk (logo), Autodesk MapGuide, Autodesk University (logo), Autodesk View, Autodesk WalkThrough, Autodesk World, AutoLISP, AutoSketch, Biped, bringing information down to earth, CAD Overlay, Character Studio, Cinepak, Cinepak (logo), Codec Central, Combustion, Design Your World, Design Your World (logo), Discreet, EditDV, Education by Design, gmax, Heidi, HOOPS, Hyperwire, i-drop, Inside Track, Kinetix, MaterialSpec, Mechanical Desktop, NAAUG, ObjectARX, PeopleTracker, Physique, Planix, Powered with Autodesk Technology (logo), RadioRay, Revit, Softdesk, Texture Universe, The AEC Authority, The Auto Architect, VISION, Visual, Visual Construction, Visual Drainage, Visual Hydro, Visual Landscape, Visual Roads, Visual Survey, Visual Toolbox, Visual TugBoat, Visual LISP, Volo, WHIP!, and WHIP! (logo). The following are trademarks of Autodesk, Inc., in the USA and/or other countries: 3ds max, AutoCAD Architectural Desktop, AutoCAD Learning Assistance, AutoCAD LT Learning Assistance, AutoCAD Simulator, AutoCAD SQL Extension, AutoCAD SQL Interface, Autodesk Map, Autodesk Streamline, AutoSnap, AutoTrack, Built with ObjectARX (logo), Burn, Buzzsaw, Buzzsaw.com, Cinestream, Cleaner, Cleaner Central, ClearScale, Colour Warper, Content Explorer, Dancing Baby (image), DesignCenter, Design Doctor, Designer's Toolkit, DesignProf, DesignServer, Design Web Format, DWF, DWG Linking, DXF, Extending the Design Team, GDX Driver, gmax (logo), gmax ready (logo),Heads-up Design, IntroDV, jobnet, ObjectDBX, onscreen onair online, Plans & Specs, Plasma, PolarSnap, ProjectPoint, Reactor, Real-time Roto, Render Queue, Visual Bridge, Visual Syllabus, and Where Design Connects. Autodesk Canada Inc. Trademarks The following are registered trademarks of Autodesk Canada Inc. in the USA and/or Canada, and/or other countries: discreet, fire, flame, flint, flint RT, frost, glass, inferno, MountStone, riot, river, smoke, sparks, stone, stream, vapour, wire. The following are trademarks of Autodesk Canada Inc., in the USA, Canada, and/or other countries: backburner, backdraft, Multi-Master Editing. Third Party Trademarks All other brand names, product names or trademarks belong to their respective holders. Third Party Software Program Credits ACIS Copyright © 1989-2001 Spatial Corp. Portions Copyright © 2002 Autodesk, Inc. Copyright © 1997 Microsoft Corporation. All rights reserved. International CorrectSpell™ Spelling Correction System © 1995 by Lernout & Hauspie Speech Products, N.V. All rights reserved. InstallShield™ 3.0. Copyright © 1997 InstallShield Software Corporation. All rights reserved. PANTONE ® Colors displayed in the software application or in the user documentation may not match PANTONE-identified standards. Consult current PANTONE Color Publications for accurate color. PANTONE ® and other Pantone, Inc. trademarks are the property of Pantone, Inc. © Pantone, Inc., 2002 Pantone, Inc. is the copyright owner of color data and/or software which are licensed to Autodesk, Inc., to distribute for use only in combination with certain Autodesk software products. PANTONE Color Data and/or Software shall not be copied onto another disk or into memory unless as part of the execution of this Autodesk software product. Portions Copyright © 1991-1996 Arthur D. Applegate. All rights reserved. Portions of this software are based on the work of the Independent JPEG Group. RAL DESIGN © RAL, Sankt Augustin, 2002 RAL CLASSIC © RAL, Sankt Augustin, 2002 Representation of the RAL Colors is done with the approval of RAL Deutsches Institut für Gütesicherung und Kennzeichnung e.V. (RAL German Institute for Quality Assurance and Certification, re. Assoc.), D-53757 Sankt Augustin." Typefaces from the Bitstream ® typeface library copyright 1992. Typefaces from Payne Loving Trust © 1996. All rights reserved. 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. iii Contents Introduction . . . . . . . . . . . . . . . . . 1 Overview of AutoCAD ActiveX Technology . . . . . . . . . . 2 Overview of AutoCAD Visual Basic for Applications (VBA) Interface . . 3 How VBA Is Implemented in AutoCAD . . . . . . . . . . 3 Dependencies and Restrictions . . . . . . . . . . . . 4 AutoCAD ActiveX and VBA Together . . . . . . . . . . . . 4 How This Guide Is Organized . . . . . . . . . . . . . . . 5 Conventions Used in This Guide. . . . . . . . . . . . . . 5 Sample Code . . . . . . . . . . . . . . . . . . . . 6 Migrating Automation Projects . . . . . . . . . . . . . . 6 New Objects . . . . . . . . . . . . . . . . . . 7 Changed Items . . . . . . . . . . . . . . . . . 7 Removed Items . . . . . . . . . . . . . . . . . 8 How to Migrate Projects. . . . . . . . . . . . . . . 8 Chapter 1 Getting Started with VBA . . . . . . . . . . . . . 11 Understand Embedded and Global VBA Projects . . . . . . . . 12 Organize Your Projects with the VBA Manager . . . . . . . . 13 Load an Existing Project . . . . . . . . . . . . . 13 Unload a Project . . . . . . . . . . . . . . . . 14 Embed a Project into a Drawing . . . . . . . . . . . 14 Extract a Project from a Drawing . . . . . . . . . . . 15 Create a New Project . . . . . . . . . . . . . . . 15 Save Your Project . . . . . . . . . . . . . . . . 15 iv | Contents Handle Your Macros. . . . . . . . . . . . . . . . . 16 Use the Macros Dialog Box . . . . . . . . . . . . . 16 Run a Macro . . . . . . . . . . . . . . . . . 17 Edit a Macro . . . . . . . . . . . . . . . . . 17 Step into a Macro . . . . . . . . . . . . . . . . 18 Set the Project Options . . . . . . . . . . . . . . 18 Edit Your Projects with the VBA IDE . . . . . . . . . . . 19 View Project Information . . . . . . . . . . . . . 19 Define the Components in a Project . . . . . . . . . . 20 Import Existing Components . . . . . . . . . . . . 21 Edit Components . . . . . . . . . . . . . . . . 22 Name Your Project . . . . . . . . . . . . . . . 24 Save Your Project . . . . . . . . . . . . . . . . 25 Reference Other VBA Projects . . . . . . . . . . . . 25 Set the VBA IDE Options . . . . . . . . . . . . . 26 Perform an Introductory Exercise . . . . . . . . . . . . 28 More Information . . . . . . . . . . . . . . . . . 29 Review AutoCAD VBA Project Terms . . . . . . . . . . . 29 AutoCAD VBA Commands. . . . . . . . . . . . . . . 30 Chapter 2 ActiveX Automation Basics . . . . . . . . . . . . 31 Understand the AutoCAD Object Model . . . . . . . . . . 32 The Application Object . . . . . . . . . . . . . . 34 The Document Object . . . . . . . . . . . . . . 34 The Collection Objects . . . . . . . . . . . . . . 35 The Graphical and Nongraphical Objects . . . . . . . . 36 The Preferences, Plot, and Utility Objects . . . . . . . . 36 Access the Object Hierarchy . . . . . . . . . . . . . . 38 Reference Objects in the Object Hierarchy . . . . . . . . 38 Access the Application Object . . . . . . . . . . . . 39 Collection Objects . . . . . . . . . . . . . . . . . 39 Access a Collection . . . . . . . . . . . . . . . 40 Add a New Member to a Collection Object. . . . . . . . 41 Iterate through a Collection Object . . . . . . . . . . 41 Delete a Member of a Collection Object . . . . . . . . 42 Understand Properties and Methods . . . . . . . . . . . 42 Understand Parent Objects . . . . . . . . . . . . . . 43 Locate the Type Library. . . . . . . . . . . . . . . . 43 Contents | v Use Variants in Methods and Properties . . . . . . . . . . . 44 What Is a Variant? . . . . . . . . . . . . . . . . 44 Use Variants for Array Data . . . . . . . . . . . . . 44 Convert Arrays to Variants . . . . . . . . . . . . . 45 Interpret Variant Arrays . . . . . . . . . . . . . . 46 Using Other Programming Languages . . . . . . . . . . . . 46 Convert the VBA Code to VB. . . . . . . . . . . . . 47 Chapter 3 Control the AutoCAD Environment . . . . . . . . . 51 Open, Save, and Close Drawings . . . . . . . . . . . . . 52 Set AutoCAD Preferences . . . . . . . . . . . . . . . . 53 Database Preferences . . . . . . . . . . . . . . . 54 Control the Application Window . . . . . . . . . . . . . 55 Control the Drawing Windows . . . . . . . . . . . . . . 56 Position and Size the Document Window. . . . . . . . . 56 Use Zoom . . . . . . . . . . . . . . . . . . . 57 Use Named Views . . . . . . . . . . . . . . . . 60 Use Tiled Viewports . . . . . . . . . . . . . . . 61 Update the Geometry in the Document Window . . . . . . 64 Reset Active Objects . . . . . . . . . . . . . . . . . 64 Set and Return System Variables . . . . . . . . . . . . . 65 Draw with Precision . . . . . . . . . . . . . . . . . 65 Adjust Snap and Grid Alignment . . . . . . . . . . . 66 Use Ortho Mode. . . . . . . . . . . . . . . . . 66 Draw Construction Lines . . . . . . . . . . . . . . 67 Calculate Points and Values . . . . . . . . . . . . . 70 Calculate Areas . . . . . . . . . . . . . . . . . 71 Prompt for User Input . . . . . . . . . . . . . . . . . 73 GetString Method . . . . . . . . . . . . . . . . 73 GetPoint Method . . . . . . . . . . . . . . . . 74 GetKeyword Method . . . . . . . . . . . . . . . 74 Control User Input . . . . . . . . . . . . . . . . 75 Access the AutoCAD Command Line . . . . . . . . . . . . 76 Work with No Documents Open . . . . . . . . . . . . . 77 Import Other File Formats . . . . . . . . . . . . . . . 78 Export to Other File Formats. . . . . . . . . . . . . . . 78 vi | Contents Chapter 4 Create and Edit AutoCAD Entities . . . . . . . . . . 81 Create Objects . . . . . . . . . . . . . . . . . . 82 Determine the Container Object . . . . . . . . . . . 82 Create Lines . . . . . . . . . . . . . . . . . 83 Create Curved Objects . . . . . . . . . . . . . . 83 Create Point Objects . . . . . . . . . . . . . . . 84 Create Solid-Filled Areas . . . . . . . . . . . . . 86 Work with Regions . . . . . . . . . . . . . . . 87 Create Hatches . . . . . . . . . . . . . . . . 90 Work with Selection Sets . . . . . . . . . . . . . . . 93 Create a Selection Set . . . . . . . . . . . . . . 94 Add Objects to a Selection Set . . . . . . . . . . . . 94 Define Rules for Selection Sets. . . . . . . . . . . . 95 Display Information About a Selection Set . . . . . . . . 102 Remove Objects from a Selection Set . . . . . . . . . 103 Edit Objects . . . . . . . . . . . . . . . . . . . 104 Work with Named Objects . . . . . . . . . . . . . 104 Copy Objects . . . . . . . . . . . . . . . . . 105 Offset Objects . . . . . . . . . . . . . . . . . 109 Mirror Objects . . . . . . . . . . . . . . . . . 110 Array Objects . . . . . . . . . . . . . . . . . 112 Move Objects . . . . . . . . . . . . . . . . . 115 Rotate Objects . . . . . . . . . . . . . . . . . 116 Delete Objects . . . . . . . . . . . . . . . . . 117 Scale Objects . . . . . . . . . . . . . . . . . 118 Transform Objects . . . . . . . . . . . . . . . 119 Extend and Trim Objects . . . . . . . . . . . . . 122 Explode Objects . . . . . . . . . . . . . . . . 123 Edit Polylines . . . . . . . . . . . . . . . . . 124 Edit Splines. . . . . . . . . . . . . . . . . . 126 Edit Hatches . . . . . . . . . . . . . . . . . 128 Use Layers, Colors, and Linetypes . . . . . . . . . . . . 132 Work with Layers . . . . . . . . . . . . . . . . 133 Work with Colors. . . . . . . . . . . . . . . . 138 Work with Linetypes. . . . . . . . . . . . . . . 139 Assign Layers, Colors, and Linetypes to Objects . . . . . . 141 Save and Restore Layer Settings . . . . . . . . . . . . . 144 Understand How AutoCAD Saves Layer Settings . . . . . . 144 Use the LayerStateManager to Manage Layer Settings . . . . 146 Contents | vii Add Text to Drawings . . . . . . . . . . . . . . . . 150 Work with Text Styles . . . . . . . . . . . . . . 151 Use Line Text (Text) . . . . . . . . . . . . . . 157 Use Multiline Text (Mtext) . . . . . . . . . . . . 161 Use Unicode Characters, Control Codes, and Special Characters 164 Substitute Fonts . . . . . . . . . . . . . . . . 166 Check Spelling . . . . . . . . . . . . . . . . 166 Chapter 5 Dimensions and Tolerances . . . . . . . . . . . . 169 Dimensioning Concepts . . . . . . . . . . . . . . . 170 Parts of a Dimension . . . . . . . . . . . . . . 170 Define the Dimension System Variables . . . . . . . . 171 Set Dimension Text Styles. . . . . . . . . . . . . 172 Understand Leader Lines . . . . . . . . . . . . . 172 Understand Associative Dimensions . . . . . . . . . 173 Create Dimensions . . . . . . . . . . . . . . . . . 173 Create Linear Dimensions. . . . . . . . . . . . . 173 Create Radial Dimensions. . . . . . . . . . . . . 174 Create Angular Dimensions . . . . . . . . . . . . 176 Create Ordinate Dimensions . . . . . . . . . . . . 177 Edit Dimensions . . . . . . . . . . . . . . . . . 179 Override Dimension Text . . . . . . . . . . . . . 179 Work with Dimension Styles . . . . . . . . . . . . . 180 Create, Modify, and Copy Dimension Styles . . . . . . . 181 Override the Dimension Style . . . . . . . . . . . 182 Dimension in Model Space and Paper Space . . . . . . . . . 187 Create Leaders and Annotation . . . . . . . . . . . . . 187 Create a Leader Line . . . . . . . . . . . . . . 187 Add the Annotation to a Leader Line . . . . . . . . . 189 Leader Associativity. . . . . . . . . . . . . . . 189 Edit Leader Associativity . . . . . . . . . . . . . 190 Edit Leaders . . . . . . . . . . . . . . . . . 191 Use Geometric Tolerances . . . . . . . . . . . . . . 191 Create Geometric Tolerances . . . . . . . . . . . . 191 Edit Tolerances . . . . . . . . . . . . . . . . 192 Chapter 6 Customize Toolbars and Menus . . . . . . . . . . . 193 Understand the MenuBar and MenuGroups Collections . . . . . 194 Load Menu Groups. . . . . . . . . . . . . . . . . 195 Create New Menu Groups . . . . . . . . . . . . . . 196 viii | Contents Change the Menu Bar . . . . . . . . . . . . . . . . 196 Insert Menus in the Menu Bar . . . . . . . . . . . . 197 Remove Menus from the Menu Bar . . . . . . . . . . 198 Rearrange Menu Items on the Menu Bar . . . . . . . . 198 Create and Edit Pull-Down and Shortcut Menus . . . . . . . . 199 Create New Menus . . . . . . . . . . . . . . . 200 Add New Menu Items to a Menu . . . . . . . . . . . 200 Add Separators to a Menu . . . . . . . . . . . . . 202 Assign an Accelerator Key to a Menu Item . . . . . . . . 203 Create Cascading Submenus . . . . . . . . . . . . 203 Delete Menu Items from a Menu . . . . . . . . . . . 205 Explore the Properties of Menu Items . . . . . . . . . 206 Create and Edit Toolbars . . . . . . . . . . . . . . . 209 Create New Toolbars . . . . . . . . . . . . . . . 209 Add New Toolbar Buttons to a Toolbar . . . . . . . . . 210 Add Separators to a Toolbar . . . . . . . . . . . . 212 Define the Toolbar Button Image . . . . . . . . . . . 212 Create Flyout Toolbars . . . . . . . . . . . . . . 213 Float and Dock Toolbars . . . . . . . . . . . . . 215 Delete Toolbar Buttons from a Toolbar . . . . . . . . . 216 Explore the Properties of Toolbar Items . . . . . . . . . 216 Create Macros. . . . . . . . . . . . . . . . . . . 218 Macro Characters Mapped to ASCII Equivalents . . . . . . 219 Macro Termination . . . . . . . . . . . . . . . 220 Pause for User Input . . . . . . . . . . . . . . . 221 Cancel a Command . . . . . . . . . . . . . . . 222 Macro Repetition . . . . . . . . . . . . . . . . 223 Use of Single Object Selection Mode . . . . . . . . . . 223 Create Status-Line Help for Menu Items and Toolbar Items . . . . 224 Add Entries to the Right-Click Menu . . . . . . . . . . . 225 Chapter 7 Use Events . . . . . . . . . . . . . . . . . 227 Understand the Events in AutoCAD . . . . . . . . . . . . 228 Guidelines for Event Handlers . . . . . . . . . . . . . 228 Handle Application Level Events . . . . . . . . . . . . . 230 Enable Application Level Events . . . . . . . . . . . 231 Handle Document Level Events . . . . . . . . . . . . . 233 Enable Document Level Events in Environments Other Than VBA 236 Code Document Level Events in Environments Other Than VBA 237 Code Document Level Events in VBA . . . . . . . . . 237 Handle Object Level Events . . . . . . . . . . . . . . 238 Enable the Object Level Event . . . . . . . . . . . . 238 Contents | ix Chapter 8 Work in Three Dimensional Space . . . . . . . . . . 241 Specify 3D Coordinates . . . . . . . . . . . . . . . 242 Define a User Coordinate System . . . . . . . . . . . . 244 Convert Coordinates . . . . . . . . . . . . . . . . 245 Create 3D Objects . . . . . . . . . . . . . . . . . 248 Create Wireframes . . . . . . . . . . . . . . . 249 Create Meshes . . . . . . . . . . . . . . . . 249 Create a Polyface Mesh . . . . . . . . . . . . . 250 Create Solids . . . . . . . . . . . . . . . . . 252 Edit in 3D . . . . . . . . . . . . . . . . . . . 253 Rotate in 3D . . . . . . . . . . . . . . . . . 253 Array in 3D . . . . . . . . . . . . . . . . . 255 Mirror in 3D . . . . . . . . . . . . . . . . . 255 Edit 3D Solids . . . . . . . . . . . . . . . . . . 257 Chapter 9 Define Layouts and Plot . . . . . . . . . . . . . 261 Model Space and Paper Space . . . . . . . . . . . . . 262 Layouts . . . . . . . . . . . . . . . . . . . . 262 Layouts and Blocks . . . . . . . . . . . . . . . 262 Plot Configurations. . . . . . . . . . . . . . . 263 Layout Settings . . . . . . . . . . . . . . . . 263 Viewports. . . . . . . . . . . . . . . . . . . . 265 Floating Viewports . . . . . . . . . . . . . . . 265 Switch to a Paper Space Layout . . . . . . . . . . . 267 Switch to the Model Space Layout . . . . . . . . . . 268 Create Paper Space Viewports . . . . . . . . . . . 268 Change Viewport Views and Content . . . . . . . . . 272 Scale Views Relative to Paper Space . . . . . . . . . . 272 Scale Pattern Linetypes in Paper Space . . . . . . . . . 274 Hide Lines in Plotted Viewports . . . . . . . . . . . 274 Plot Your Drawing . . . . . . . . . . . . . . . . . 275 Perform Basic Plotting . . . . . . . . . . . . . . 275 Plot from Model Space . . . . . . . . . . . . . . 276 Plot from Paper Space . . . . . . . . . . . . . . 277 Chapter 10 Advanced Drawing and Organizational Techniques . . . . 279 Work with Raster Images . . . . . . . . . . . . . . . 280 Attach and Scale a Raster Image . . . . . . . . . . . 280 Manage Raster Images . . . . . . . . . . . . . . 281 Modify Images and Image Boundaries . . . . . . . . . 282 Clip Images . . . . . . . . . . . . . . . . . 285 x | Contents Use Blocks and Attributes . . . . . . . . . . . . . . . 286 Work with Blocks. . . . . . . . . . . . . . . . 287 Work with Attributes . . . . . . . . . . . . . . 292 Use External References. . . . . . . . . . . . . . . . 299 Update Xrefs . . . . . . . . . . . . . . . . . 300 Attach Xrefs . . . . . . . . . . . . . . . . . 300 Detach Xrefs . . . . . . . . . . . . . . . . . 301 Reload Xrefs . . . . . . . . . . . . . . . . . 302 Unload Xrefs . . . . . . . . . . . . . . . . . 303 Bind Xrefs . . . . . . . . . . . . . . . . . . 304 Clip Blocks and Xrefs . . . . . . . . . . . . . . 305 Demand Loading and Xref Performance . . . . . . . . 306 Assign and Retrieve Extended Data . . . . . . . . . . . . 307 Chapter 11 Develop Applications with VBA . . . . . . . . . . 309 More VBA Terminology. . . . . . . . . . . . . . . . 310 Forms in VBA . . . . . . . . . . . . . . . . . . . 310 Design and Run Mode . . . . . . . . . . . . . . 311 Add Controls to a Form . . . . . . . . . . . . . . 312 Display and Hide Forms. . . . . . . . . . . . . . 313 Load and Unload Forms. . . . . . . . . . . . . . 314 Modal Forms . . . . . . . . . . . . . . . . . 315 Handle Errors . . . . . . . . . . . . . . . . . . . 316 Define Application Error Types . . . . . . . . . . . 316 Trap Runtime Errors . . . . . . . . . . . . . . . 317 Respond to Trapped Errors . . . . . . . . . . . . . 319 Respond to AutoCAD User Input Errors . . . . . . . . . 319 Encrypt VBA Code Modules . . . . . . . . . . . . . . 319 Run a VBA Macro from a Toolbar or Menu . . . . . . . . . 320 Automatically Load a VBA Project . . . . . . . . . . . . 320 Automatically Run a VBA Macro . . . . . . . . . . . . . 320 Automatically Open the VBA IDE Whenever a Project Is Loaded. . . 321 Work in a Zero Document State . . . . . . . . . . . . . 321 Distribute Your Application . . . . . . . . . . . . . . 322 Distribute Visual Basic Applications . . . . . . . . . . 322