AutoCAD

ActiveX and VBA

Developers Guide

2004
February 2003

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 fr Gtesicherung 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.

Contents

Introduction .

Overview of AutoCAD ActiveX Technology . . . . . . . .

Overview of AutoCAD Visual Basic for Applications (VBA) Interface
How VBA Is Implemented in AutoCAD . . . . . . . .
Dependencies and Restrictions . . . . . . . . . .
AutoCAD ActiveX and VBA Together . . . . . . . . . .
How This Guide Is Organized . . . . . . . . . . . . .
Conventions Used in This Guide . . . . . . . . . . . .
Sample Code . . . . . . . . . . . . . . . . . .
Migrating Automation Projects . . . . . . . . . . . .
New Objects . . . . . . . . . . . . . . . .
Changed Items . . . . . . . . . . . . . . .
Removed Items . . . . . . . . . . . . . . .
How to Migrate Projects. . . . . . . . . . . . .

Chapter 1

Getting Started with VBA .

Understand Embedded and Global VBA Projects .

Organize Your Projects with the VBA Manager .
Load an Existing Project . . . . . .
Unload a Project . . . . . . . . .
Embed a Project into a Drawing . . . .
Extract a Project from a Drawing . . . .
Create a New Project . . . . . . . .
Save Your Project . . . . . . . . .

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

1
.2
.3
.3
.4
.4
.5
.5
.6
.6
.7
.7
.8
.8

. 11
.
.
.
.
.
.
.
.

12
13
13
14
14
15
15
15

iii

Handle Your Macros . . . . . . . . .

Use the Macros Dialog Box . . . . .
Run a Macro . . . . . . . . .
Edit a Macro . . . . . . . . .
Step into a Macro . . . . . . . .
Set the Project Options . . . . . .
Edit Your Projects with the VBA IDE . . .
View Project Information . . . . .
Define the Components in a Project . .
Import Existing Components . . . .
Edit Components . . . . . . . .
Name Your Project . . . . . . .
Save Your Project . . . . . . . .
Reference Other VBA Projects . . . .
Set the VBA IDE Options . . . . .
Perform an Introductory Exercise . . . .
More Information . . . . . . . . .
Review AutoCAD VBA Project Terms . . .
AutoCAD VBA Commands. . . . . . .

Chapter 2

ActiveX Automation Basics

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

Understand the AutoCAD Object Model . . .

The Application Object . . . . . . .
The Document Object . . . . . . .
The Collection Objects . . . . . . .
The Graphical and Nongraphical Objects .
The Preferences, Plot, and Utility Objects .
Access the Object Hierarchy . . . . . . .
Reference Objects in the Object Hierarchy .
Access the Application Object . . . . .
Collection Objects . . . . . . . . . .
Access a Collection . . . . . . . .
Add a New Member to a Collection Object.
Iterate through a Collection Object . . .
Delete a Member of a Collection Object .
Understand Properties and Methods . . . .
Understand Parent Objects . . . . . . .
Locate the Type Library. . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

16
16
17
17
18
18
19
19
20
21
22
24
25
25
26
28
29
29
30

. 31
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

32
34
34
35
36
36
38
38
39
39
40
41
41
42
42
43
43

Use Variants in Methods and Properties

What Is a Variant? . . . . .
Use Variants for Array Data . .
Convert Arrays to Variants . .
Interpret Variant Arrays . . .
Using Other Programming Languages .
Convert the VBA Code to VB. .

Chapter 3

Control the AutoCAD Environment

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

Open, Save, and Close Drawings . . . . . . .

Set AutoCAD Preferences . . . . . . . . . .
Database Preferences . . . . . . . . .
Control the Application Window . . . . . . .
Control the Drawing Windows . . . . . . . .
Position and Size the Document Window. . .
Use Zoom . . . . . . . . . . . . .
Use Named Views . . . . . . . . . .
Use Tiled Viewports
. . . . . . . . .
Update the Geometry in the Document Window
Reset Active Objects . . . . . . . . . . .
Set and Return System Variables . . . . . . .
Draw with Precision . . . . . . . . . . .
Adjust Snap and Grid Alignment . . . . .
Use Ortho Mode . . . . . . . . . . .
Draw Construction Lines . . . . . . . .
Calculate Points and Values . . . . . . .
Calculate Areas . . . . . . . . . . .
Prompt for User Input . . . . . . . . . . .
GetString Method . . . . . . . . . .
GetPoint Method . . . . . . . . . .
GetKeyword Method . . . . . . . . .
Control User Input . . . . . . . . . .
Access the AutoCAD Command Line . . . . . .
Work with No Documents Open . . . . . . .
Import Other File Formats . . . . . . . . .
Export to Other File Formats. . . . . . . . .

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.

. 44
. 44
. 44
. 45
. 46
. 46
. 47

. 51
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

Contents
v

. 52
. 53
. 54
. 55
. 56
. 56
. 57
. 60
. 61
. 64
. 64
. 65
. 65
. 66
. 66
. 67
. 70
. 71
. 73
. 73
. 74
. 74
. 75
. 76
. 77
. 78
. 78

Chapter 4

Create and Edit AutoCAD Entities

Create Objects . . . . . . . . . . . . . .
Determine the Container Object . . . . . . .
Create Lines . . . . . . . . . . . . .
Create Curved Objects . . . . . . . . . .
Create Point Objects . . . . . . . . . . .
Create Solid-Filled Areas . . . . . . . . .
Work with Regions . . . . . . . . . . .
Create Hatches . . . . . . . . . . . .
Work with Selection Sets . . . . . . . . . . .
Create a Selection Set . . . . . . . . . .
Add Objects to a Selection Set . . . . . . . .
Define Rules for Selection Sets . . . . . . . .
Display Information About a Selection Set . . . .
Remove Objects from a Selection Set . . . . .
Edit Objects . . . . . . . . . . . . . . .
Work with Named Objects . . . . . . . . .
Copy Objects . . . . . . . . . . . . .
Offset Objects . . . . . . . . . . . . .
Mirror Objects . . . . . . . . . . . . .
Array Objects . . . . . . . . . . . . .
Move Objects . . . . . . . . . . . . .
Rotate Objects . . . . . . . . . . . . .
Delete Objects . . . . . . . . . . . . .
Scale Objects . . . . . . . . . . . . .
Transform Objects . . . . . . . . . . .
Extend and Trim Objects . . . . . . . . .
Explode Objects . . . . . . . . . . . .
Edit Polylines . . . . . . . . . . . . .
Edit Splines . . . . . . . . . . . . . .
Edit Hatches . . . . . . . . . . . . .
Use Layers, Colors, and Linetypes . . . . . . . .
Work with Layers . . . . . . . . . . . .
Work with Colors. . . . . . . . . . . .
Work with Linetypes. . . . . . . . . . .
Assign Layers, Colors, and Linetypes to Objects . .
Save and Restore Layer Settings . . . . . . . . .
Understand How AutoCAD Saves Layer Settings . .
Use the LayerStateManager to Manage Layer Settings

vi |
Contents

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. 81
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

82
82
83
83
84
86
87
90
93
94
94
95
102
103
104
104
105
109
110
112
115
116
117
118
119
122
123
124
126
128
132
133
138
139
141
144
144
146

Add Text to Drawings . . . . . . . . . . . .

Work with Text Styles . . . . . . . . . .
Use Line Text (Text)
. . . . . . . . . .
Use Multiline Text (Mtext) . . . . . . . .
Use Unicode Characters, Control Codes, and Special
Substitute Fonts . . . . . . . . . . . .
Check Spelling . . . . . . . . . . . .

Chapter 5

Dimensions and Tolerances .

Dimensioning Concepts . . . . . . . .
Parts of a Dimension . . . . . . .
Define the Dimension System Variables .
Set Dimension Text Styles. . . . . .
Understand Leader Lines . . . . . .
Understand Associative Dimensions . .
Create Dimensions . . . . . . . . . .
Create Linear Dimensions. . . . . .
Create Radial Dimensions . . . . . .
Create Angular Dimensions . . . . .
Create Ordinate Dimensions . . . . .
Edit Dimensions . . . . . . . . . .
Override Dimension Text . . . . . .
Work with Dimension Styles
. . . . . .
Create, Modify, and Copy Dimension Styles
Override the Dimension Style . . . .
Dimension in Model Space and Paper Space . .
Create Leaders and Annotation . . . . . .
Create a Leader Line . . . . . . .
Add the Annotation to a Leader Line . .
Leader Associativity. . . . . . . .
Edit Leader Associativity . . . . . .
Edit Leaders . . . . . . . . . .
Use Geometric Tolerances . . . . . . .
Create Geometric Tolerances . . . . .
Edit Tolerances . . . . . . . . .

Chapter 6

Customize Toolbars and Menus . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. . . .
. . . .
. . . .
. . . .
Characters
. . . .
. . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

Understand the MenuBar and MenuGroups Collections .

Load Menu Groups. . . . . . . . . . . . .
Create New Menu Groups . . . . . . . . . .

.
.
.

.
.
.

. 169
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.

150
151
157
161
164
166
166

170
170
171
172
172
173
173
173
174
176
177
179
179
180
181
182
187
187
187
189
189
190
191
191
191
192

. 193
.
.
.

Contents
vii

194
195
196

Chapter 7

Change the Menu Bar . . . . . . . . . . . .

Insert Menus in the Menu Bar . . . . . . . .
Remove Menus from the Menu Bar . . . . . .
Rearrange Menu Items on the Menu Bar . . . .
Create and Edit Pull-Down and Shortcut Menus . . . .
Create New Menus . . . . . . . . . . .
Add New Menu Items to a Menu . . . . . . .
Add Separators to a Menu . . . . . . . . .
Assign an Accelerator Key to a Menu Item . . . .
Create Cascading Submenus . . . . . . . .
Delete Menu Items from a Menu . . . . . . .
Explore the Properties of Menu Items . . . . .
Create and Edit Toolbars . . . . . . . . . . .
Create New Toolbars . . . . . . . . . . .
Add New Toolbar Buttons to a Toolbar . . . . .
Add Separators to a Toolbar . . . . . . . .
Define the Toolbar Button Image . . . . . . .
Create Flyout Toolbars . . . . . . . . . .
Float and Dock Toolbars . . . . . . . . .
Delete Toolbar Buttons from a Toolbar . . . . .
Explore the Properties of Toolbar Items . . . . .
Create Macros . . . . . . . . . . . . . . .
Macro Characters Mapped to ASCII Equivalents . .
Macro Termination . . . . . . . . . . .
Pause for User Input . . . . . . . . . . .
Cancel a Command . . . . . . . . . . .
Macro Repetition . . . . . . . . . . . .
Use of Single Object Selection Mode . . . . . .
Create Status-Line Help for Menu Items and Toolbar Items
Add Entries to the Right-Click Menu . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

Use Events .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

196
197
198
198
199
200
200
202
203
203
205
206
209
209
210
212
212
213
215
216
216
218
219
220
221
222
223
223
224
225

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

viii |
Contents

Chapter 8

Chapter 9

Work in Three Dimensional Space .

Specify 3D Coordinates . . .
Define a User Coordinate System
Convert Coordinates . . . .
Create 3D Objects . . . . .
Create Wireframes . . .
Create Meshes . . . .
Create a Polyface Mesh
.
Create Solids . . . . .
Edit in 3D . . . . . . .
Rotate in 3D . . . . .
Array in 3D . . . . .
Mirror in 3D . . . . .
Edit 3D Solids . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.

Define Layouts and Plot

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

Model Space and Paper Space . . . . .

Layouts . . . . . . . . . . . .
Layouts and Blocks . . . . . . .
Plot Configurations . . . . . . .
Layout Settings . . . . . . . .
Viewports. . . . . . . . . . . .
Floating Viewports . . . . . . .
Switch to a Paper Space Layout . . .
Switch to the Model Space Layout . .
Create Paper Space Viewports . . .
Change Viewport Views and Content .
Scale Views Relative to Paper Space . .
Scale Pattern Linetypes in Paper Space .
Hide Lines in Plotted Viewports . . .
Plot Your Drawing . . . . . . . . .
Perform Basic Plotting . . . . . .
Plot from Model Space . . . . . .
Plot from Paper Space . . . . . .

Chapter 10

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

Advanced Drawing and Organizational Techniques

Work with Raster Images . . . . . . .

Attach and Scale a Raster Image . . .
Manage Raster Images . . . . . .
Modify Images and Image Boundaries .
Clip Images . . . . . . . . .

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

. 241
.
.
.
.
.
.
.
.
.
.
.
.
.

242
244
245
248
249
249
250
252
253
253
255
255
257

. 261
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

262
262
262
263
263
265
265
267
268
268
272
272
274
274
275
275
276
277

. 279
.
.
.
.
.

280
280
281
282
285

Contents
ix

Use Blocks and Attributes . . . . . . .

Work with Blocks . . . . . . . .
Work with Attributes . . . . . .
Use External References. . . . . . . .
Update Xrefs . . . . . . . . .
Attach Xrefs . . . . . . . . .
Detach Xrefs . . . . . . . . .
Reload Xrefs . . . . . . . . .
Unload Xrefs . . . . . . . . .
Bind Xrefs . . . . . . . . . .
Clip Blocks and Xrefs . . . . . .
Demand Loading and Xref Performance
Assign and Retrieve Extended Data . . . .

Chapter 11

Develop Applications with VBA .

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

More VBA Terminology. . . . . . . . . . .

Forms in VBA . . . . . . . . . . . . . .
Design and Run Mode . . . . . . . . .
Add Controls to a Form . . . . . . . . .
Display and Hide Forms . . . . . . . . .
Load and Unload Forms. . . . . . . . .
Modal Forms . . . . . . . . . . . .
Handle Errors . . . . . . . . . . . . . .
Define Application Error Types . . . . . .
Trap Runtime Errors . . . . . . . . . .
Respond to Trapped Errors . . . . . . . .
Respond to AutoCAD User Input Errors . . . .
Encrypt VBA Code Modules . . . . . . . . .
Run a VBA Macro from a Toolbar or Menu . . . .
Automatically Load a VBA Project . . . . . . .
Automatically Run a VBA Macro . . . . . . . .
Automatically Open the VBA IDE Whenever a Project Is
Work in a Zero Document State . . . . . . . .
Distribute Your Application . . . . . . . . .
Distribute Visual Basic Applications . . . . .

Contents

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
Loaded .
. . .
. . .
. . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

286
287
292
299
300
300
301
302
303
304
305
306
307

309
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

310
310
311
312
313
314
315
316
316
317
319
319
319
320
320
320
321
321
322
322

Chapter 12

Interact with Other Applications and Windows APIs .

Interact with Visual LISP Applications. . . . . . . . . .

Interact with Other Windows Applications . . . . . . . .
Reference the ActiveX Object Library of Other Applications .
Create an Instance of the Other Application . . . . . .
Program with Objects from Other Applications . . . . .
Access Windows APIs from VBA . . . . . . . . . . .

Chapter 13

Design the Garden PathAn ActiveX/VBA Tutorial

Check Your Environment . . . . . . . . .

Define the Goal . . . . . . . . . . . . .
Write the First Function . . . . . . . . . .
Get Input . . . . . . . . . . . . . . .
Declare Variables . . . . . . . . . .
Enter the gpuser Subroutine . . . . . . .
Draw the Path Outline . . . . . . . . . .
Draw the Tiles . . . . . . . . . . . . .
Tie It All Together . . . . . . . . . . . .
Step Through the Code . . . . . . . . . .
Execute the Macro . . . . . . . . . . . .
Add a Dialog Box Interface . . . . . . . . .
Create the Dialog Box . . . . . . . . .
Use the Project Window to Navigate Your Project
Update the Existing Code . . . . . . . .
Add Code to the Dialog Box . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

Appendix A Visual LISP and ActiveX/VBA Comparison

AutoLISP and ActiveX/VBA Comparison .

Index .

.
.

.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. 323
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. 331
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

324
324
325
326
326
329

332
332
333
334
334
335
338
339
342
343
344
344
345
348
348
350

. 353

354

. 365

Contents
xi

xii

Introduction

This introduction describes the concept of exposing

In this chapter

AutoCAD objects through an ActiveX Automation

Overview of

interface and programming those objects using the

Visual Basic for Applications programming environment. Also included is an introduction to all the
documentation and sample code provided for AutoCAD
ActiveX and VBA.

AutoCAD ActiveX
Technology
Overview of AutoCAD

Visual Basic for

Applications (VBA)
Interface
AutoCAD ActiveX and

VBA Together
How This Guide Is

Organized
Conventions Used in This

Guide
Sample Code
Migrating Automation

Projects

Overview of AutoCAD ActiveX

Technology
AutoCAD ActiveX enables you to manipulate AutoCAD programmatically
from within or outside AutoCAD. It does this by exposing AutoCAD objects
to the outside world. Once these objects are exposed, they can be
accessed by many different programming languages and environments and
by other
applications such as Microsoft Word VBA or Excel VBA.
C++

Visual Basic

Java

Delphi
MS Word VBA

AutoCAD VBA

Excel VBA

AutoCAD ActiveX Objects

AutoCAD Application
drawing.dwg

There are two advantages to implementing an ActiveX interface for

AutoCAD:

Programmatic access to AutoCAD drawings is opened up to many

more programming environments. Before ActiveX Automation,
developers were limited to an AutoLISP or C++ interface.
Sharing data with other Windows applications, such as Microsoft Excel
and Word, is made dramatically easier.

An object is the main building block of any ActiveX application. Each

exposed object represents a precise part of AutoCAD. There are many different types of objects in the AutoCAD ActiveX interface. For example

2 |
Introduction

Graphical objects such as lines, arcs, text, and dimensions are objects.
Style settings such as linetypes and dimension styles are objects.

Organizational structures such as layers, groups, and blocks are objects.

The drawing displays such as view and viewport are objects.
Even the drawing and the AutoCAD application are considered objects.

Overview of AutoCAD Visual Basic for

Applications (VBA) Interface
Microsoft VBA is an object-oriented programming environment designed to
provide rich development capabilities similar to those of Visual Basic (VB).
The main difference between VBA and VB is that VBA runs in the same
process space as AutoCAD, providing an AutoCAD-intelligent and very fast
programming environment.
VBA also provides application integration with other VBA-enabled applications. This means that AutoCAD, using other application object libraries,
can be an Automation controller for other applications such as Microsoft
Word or Excel.
The standalone development editions of Visual Basic, which must be purchased separately, complement AutoCAD VBA with additional components,
such as an external database engine and report-writing capabilities.
There are four advantages to implementing VBA for AutoCAD:

The Visual Basic programming environment is easy to learn and use.

VBA runs in-process with AutoCAD. This translates to very fast
program execution.
Dialog construction is quick and effective. This allows developers to
prototype applications and quickly receive feedback on designs.
Projects can be standalone or imbedded in drawings. This choice
allows developers great flexibility in the distribution of their
applications.

How VBA Is Implemented in AutoCAD

VBA sends messages to AutoCAD by the AutoCAD ActiveX Automation interface. AutoCAD VBA permits the VBA environment to run simultaneously
with AutoCAD and provides programmatic control of AutoCAD through the
ActiveX Automation interface. This coupling of AutoCAD, ActiveX
Automation, and VBA provides an extremely powerful interface not only for
manipulating AutoCAD objects, but for sending data to or retrieving data
from other applications.

There are three fundamental elements that define ActiveX and VBA
program- ming in AutoCAD. The first is AutoCAD itself, which has a rich set
of objects that encapsulates AutoCAD entities, data, and commands. Because
AutoCAD was designed as an open-architecture application with multiple
levels of interface, familiarity with AutoCAD programmability is highly
desirable in
order to use VBA effectively. If youve used AutoLISP to control AutoCAD
programmatically, you already have a good understanding of the AutoCAD
facilities. However, you will find the VBA object-based approach to be quite
different from that of AutoLISP.
The second element is the AutoCAD ActiveX Automation interface, which
establishes messages (communication) with AutoCAD objects. Programming
in VBA requires a fundamental understanding of ActiveX Automation. A
description of the AutoCAD ActiveX Automation interface can be found in
the ActiveX and VBA Reference. Even the experienced VB programmer will
find the AutoCAD ActiveX Automation interface invaluable for understanding and developing AutoCAD VBA applications.
The third element is the VBA programming environment (IDE) which has its
own set of objects, keywords, constants, and so forth that provides program
flow, control, debugging, and execution. Microsofts own extensive online
Help for VBA is included with the AutoCAD VBA and is accessible from the
VBA IDE by any of the following methods:

Pressing F1 on the keyboard

Choosing Help from the VBA IDE menu bar
Clicking the Question Mark icon on the VBA IDE toolbar

Dependencies and Restrictions

If you install, reinstall, or uninstall Microsoft Office or other VBA applications after installing AutoCAD, reinstall AutoCAD and reboot your system.

AutoCAD ActiveX and VBA

Together
The AutoCAD ActiveX/VBA interface represents several advantages over
other AutoCAD API environments:

Speed
Running in-process with VBA, ActiveX applications are faster than either
AutoLISP or ADS applications.

Ease of Use
The programming language and development environment are easy to
use and come installed with AutoCAD.

Windows Interoperability
ActiveX and VBA are designed to be used with other Windows applications and provide an excellent path for communication of information
across applications.

Rapid Prototyping
The rapid interface development of VBA provides the perfect environment for prototyping applications, even if those applications will
eventually be developed in another language.

Programmer Base
There are millions of Visual Basic programmers around the world.
AutoCAD ActiveX and VBA technology open up AutoCAD
customization and application development to these programmers and
the many more who will learn Visual Basic in the future.

How This Guide Is Organized

This guide provides information regarding the development of ActiveX and
VBA applications for use with AutoCAD. Information specific to developing
applications using VBA can be found in Getting Started with VBA and
Develop Applications with VBA. Programmers using ActiveX from a development environment other than VBA can skip these two chapters. However,
be aware that all of the example code in this guide is presented in VBA.

Conventions Used in This Guide

This guide assumes you have a working knowledge of the Visual Basic
programming language, and does not attempt to duplicate or replace the
abundance of documentation available on Visual Basic. If you need more
information on the Visual Basic language or development environment
usage, see the Visual Basic for Applications Help file developed by Microsoft,
available from the Help menu in the interactive development
environment (IDE).

How This Guide Is

Organized | 5

Sample Code
This manual and the ActiveX and VBA Reference together contain over 800
example VBA subroutines that demonstrate the usage of ActiveX methods,
properties, and events.
There are also many sample applications provided in the AutoCAD Sample
directory. These sample applications show a wide range of fuctionality, from
extracting AutoCAD drawing data into Microsoft Excel spreadsheets to drawing and performing stress analysis on an electrical transmission tower.
These samples also show how to combine the versatility of the Visual Basic
for Applications programming environment with the power of the AutoCAD
ActiveX interface to create customized applications.
Additionally, example code in the ActiveX and VBA Developers Guide and
ActiveX and VBA Reference can be copied from the Help files, pasted directly
into the AutoCAD VBA environment, and then executed with one requirement: the current active drawing in AutoCAD must be a blank drawing
open to model space.
To run the examples from the Help files
1 Copy the example from the Help file into an empty VBA code module.
2 Verify that AutoCAD has a blank drawing open to model space.
3 Open the Macros dialog box by entering the command VBARUN.
4 Choose the macro and press Run.
More information on running macros and the Macros dialog box is
available in Run a Macro on page 17.

Migrating Automation Projects

AutoCAD 2004 includes changes to the ActiveX Automation interface used
by Visual Basic for Applications (VBA) and Visual Basic (VB). This
section lists new, removed, and changed items in the interface.

6 |
Introduction

New Objects
The following section lists new objects and their new methods, events, and
properties.
New methods, properties, and events since AutoCAD 2002
Object

Method/Property/Event name

AcCmColor

Blue, Bookname, ColorIndex, ColorMethod, ColorName,

Delete, EntityColor, Green, Red, SetColorBookColor,
SetNames, SetRGB

FileDependencies

Application, CreateEntry, IndexOf, Item, RemoveEntry,

UpdateEntry

FileDependency

AffectsGraphics, Feature, FileName, FileSize, FingerprintGuid,

FoundPath, FullFileName, Index, IsModified, ReferenceCount,
TimeStamp, VersionGuid

SecurityParams

Action, Algorithm, Comment, Issuer, KeyLength, Password,

ProviderName, ProviderType, SerialNumber, Subject,
TimeServer

Changed Items
The following section describes existing items that have changed.
Changed methods and properties
AutoCAD 2002 item

AutoCAD 2004 item

Description of change

AddHatch method

AddHatch method

Additional, optional parameter to

set the hatch type as classic or
gradient.

AddMInsertBlock method

AddMInsertBlock method

Additional, optional parameter for a

password.

AttachExternalReference method

AttachExternalReference method

Additional, optional parameter for a

password.

Color property

TrueColor property

Replaced by the TrueColor

property; the Color property is
obsolete and its signature will be
removed in a future (post-AutoCAD
2004) version.

Migrating Automation
Projects | 7

Changed methods and properties (continued)

AutoCAD 2002 item

AutoCAD 2004 item

Description of change

InsertBlock method

InsertBlock Method

Additional, optional parameter for a

password.

ObjectARXPath property

ObjectARXPath property

Obsolete; signature to be removed

in a future (post-AutoCAD 2004)
version.

Open method

Open method

Additional, optional parameter for a

password.

SaveAs method

SaveAs method

Additional, optional parameter for

security information.

Removed Items
The following items were removed in AutoCAD 2004:

XMLDatabase object
LicenseServer property

How to Migrate Projects

Before you migrate your automation project, create a backup of your
current project file. Then you can migrate the project using one of the
following procedures.
To migrate an automation project to AutoCAD 2004
1 Create a backup of your project (DVB) file, and name it <project name>backup.dvb, where <project name> is the original name of the project
file.
This ensures that you have a copy to use with previous releases of
AutoCAD, if needed.
2 Open the project (DVB) file in AutoCAD 2004, in the VBA programming
environment (IDE).
3 If a CreateObject or GetObject function uses a version-independent
ProgID, change the function to use a version-dependent ProgID. For
AutoCAD 2004, use version-dependent ProgIDs.
For example, if you are using CreateObject for AutoCAD 2004, you
replace CreateObject ("AutoCAD.Application") with CreateObject
("AutoCAD.Application.16").

8 |
Introduction

Additionally, if a GetInterfaceObject method uses a version-independent

ProgID, the method must be changed to use a version-dependent ProgID.

Note To use CreateObject, GetObject, or GetInterfaceObject for previous

releases of AutoCAD, you would use the appropriate version. For example,
for AutoCAD 2002, you would replace CreateObject ("AutoCAD.Application") with CreateObject ("AutoCAD.Application.15").
4 Save the project under the same name.
To migrate a Visual Basic automation project to AutoCAD 2004
1 Create a backup of the folder containing your Visual Basic automation
source files.
This ensures that you have a copy of the source files to use with previous
releases of AutoCAD, if needed.
2 Open the Project (VBP) file in Visual Basic, and then on the Project
menu, click References.
3 In the References dialog box, remove the reference to the type library
named acad.tlb, which by default is located in c:\program files\autocad
2002.
4 In the References dialog box, add a reference to the type library named
acax16enu.tlb, which by default is located in c:\program files\common
files\autodesk shared, and then click OK.
5 If a CreateObject or GetObject function uses a version-independent
ProgID, change the function to use a version-dependent ProgID. For
AutoCAD 2004, use version-dependent ProgIDs.
For example, if you are using CreateObject for AutoCAD 2004, you
replace CreateObject ("AutoCAD.Application") with CreateObject
("AutoCAD.Application.16").
Additionally, if a GetInterfaceObject method uses a version-independent
ProgID, the method must be changed to use a version-dependent ProgID.

Note To use CreateObject, GetObject, or GetInterfaceObject for previous

releases of AutoCAD, you use the appropriate version. For example, for
AutoCAD 2002, you replace CreateObject ("AutoCAD.Application") with
CreateObject ("AutoCAD.Application.15").
6 Save the Project file and recompile it.

Migrating Automation
Projects | 9

10

Getting Started with

VBA

This chapter introduces you to AutoCAD VBA projects

In this chapter

and the VBA IDE. Although most VBA environments

Understand Embedded

are similar in behavior, the AutoCAD VBA IDE has

some unique features. There are also several AutoCAD
commands that can be used to load projects, run
projects, or open the VBA IDE. This chapter defines the
use of VBA projects, VBA commands, and the VBA IDE
in general.

and
Global VBA Projects
Organize Your Projects

with the VBA Manager

Handle Your Macros
Edit Your Projects with

the VBA IDE

Perform an Introductory

Exercise
More Information
Review AutoCAD VBA

Project
Terms
AutoCAD VBA Commands

11

Understand Embedded and

Global VBA Projects
An AutoCAD VBA project is a collection of code modules, class modules,
and forms that work together to perform a given function. Projects can be
stored within an AutoCAD drawing, or as a separate file.
Embedded projects are stored within an AutoCAD drawing. These projects
are automatically loaded whenever the drawing in which they are contained
is opened in AutoCAD, making the distribution of projects very convenient.
Embedded projects are limited and not able to open or close AutoCAD drawings because they function only within the document where they reside.
Users of embedded projects are no longer required to find and load project
files before they run a program. A time log that is triggered when the
drawing is opened is an example of a project embedded in a drawing. With
this macro users can log in and record the length of time they worked on
the drawing. The user does not have to remember to load the project before
opening the drawing; it simply is done automatically.
Global projects are stored in separate files and are more versatile because
they can work in, open, and close any AutoCAD drawing, but are not
automati- cally loaded when a drawing is opened. Users must know which
project file contains the macro they need and then load that project file
before they can run the macro. However, global projects are easier to share
with other users, and they make excellent libraries for common macros. An
example of a project you may store in a project file is a macro that collects
a bill of mate- rials from many drawings. This macro can be run by an
administrator at the end of a work cycle and can collect information from
many drawings.
At any given time, users can have both embedded and global projects loaded
into their AutoCAD session.
AutoCAD VBA projects are not binary compatible with standalone Visual
Basic projects. However, the forms, modules, and classes can be exchanged
between projects using the IMPORT and EXPORT VBA commands in the VBA
IDE. For more information about the VBA IDE, see Edit Your Projects with
the VBA IDE on page 19.
The use of Visual Studio .NET to drive and customize AutoCAD through
COM Automation is supported.

12 | Chapter 1 Getting Started with

VBA

Organize Your Projects with

the VBA Manager
You can view all the VBA projects loaded in the current AutoCAD session
by using the VBA Manager. It is an AutoCAD tool that allows you to load,
unload, save, create, embed, and extract VBA projects.
To open the VBA Manager
1 From the Tools menu choose Macro VBA Manager.
2 Or, in AutoCAD invoke the VBAMAN command.

Load an Existing Project

When you load a project into AutoCAD, all the public subroutines, also
called macros, become available for use. Projects embedded in a drawing are
loaded whenever the drawing is opened. Projects stored in DVB files must be
loaded explicitly.
Anytime a project is loaded, any other projects that are referenced by the
first project will be loaded automatically. Additionally, AutoCAD will
automati- cally load at startup any project file with the name acad.dvb.
To load an existing VBA project file
1 In the VBA Manager, use the Load option to bring up the Open VBA
Project dialog box.
2 In the Open VBA Project dialog box, select the project file to open. The
VBA Project dialog box will allow you to open only valid DVB files. If you
attempt to open a different type of file, you will receive an error message.
3 Select Open.
You can also load a project file using one of the following methods:

Enter the VBALOAD command, which opens the Open VBA Project
dialog box.
Drag a DVB file from Windows Explorer and drop it into an open
drawing in the AutoCAD window.

Organize Your Projects with the VBA

Manager | 13

Virus Alert
Each time you load a project you are given the option of enabling or disabling the code within that project as a protection against viruses. If you
enable the code, viruses in the code can begin executing. If you disable the
code, the project will still be loaded, but all code within that project is prevented from running. The virus alert is not displayed when you load a
project by dragging a DVB file from Windows Explorer and dropping it into
an open drawing in the AutoCAD window.
More information about the virus alert is available in Set the Project
Options on page 18.

Unload a Project
Unloading a project frees up memory and keeps the list of loaded projects at
a length that is easy to manage.
You cannot unload embedded projects or projects that are referenced by
other loaded projects.
To unload a VBA project
1 In the VBA Manager, select the project you want to unload.
2 Choose Unload.
3 Or, use the VBAUNLOAD command, which prompts you for the project to
be unloaded.

Embed a Project into a Drawing

When you embed a project you place a copy of the project in the drawing
database. The project is then loaded or unloaded whenever the drawing containing it is opened or closed.
A drawing can contain only one embedded project at a time. If a drawing
already contains an embedded project you must extract it before a different
project can be embedded into the drawing.
To embed a project in an AutoCAD drawing
1 Open the VBA Manager and select the project you want to embed.
2 Choose Embed.

14 | Chapter 1 Getting Started with

VBA

Extract a Project from a

Drawing
When you extract a project you remove the project from the drawing database and are given the opportunity to save the project in an external project
file. If you do not save the file in an external project file, the project data
will be deleted.
To extract a project from an AutoCAD drawing
1 Open the VBA Manager and select the drawing from which the project
is to be extracted.
2 Choose Extract.
3 If you want to save the project information in an external project file,
choose Yes to the prompt Do you want to export the VBA project
before removing it? The Save As dialog box will be displayed, allowing
you to save the file.
If you do not want to save the project information in an external file,
choose No to the prompt Do you want to export the VBA project
before removing it? The project information will be removed from the
drawing and will not be saved.

Create
Project

New

New projects are created as unsaved global projects. Once a project has been
created, you can then embed the project in a drawing, or save the project
out to a project file.
To create
project
1
Open
Manager.

new
the

VBA
VBA

2 Choose New.
A new project will be created with the default name of ACADProject. To
change the project name you must go into the VBA IDE. For more information on naming your project in the VBA IDE, see Name Your
Project on page 24.

Save
Project

Your

Embedded projects are saved whenever the drawing is saved. Global

projects must be saved using the VBA Manager or the VBA IDE.

Organize Your Projects with the VBA

Manager | 15

To save your project using the VBA Manager

1 Open the VBA Manager and select the project to be saved.
2 Choose Save As. The Save As dialog box will open.
3 Select the file name for the project to be saved in.
4 Choose Save.

Handle Your
Macros
A macro is a public (executable) subroutine. Each project usually contains at
least one macro.

Use the Macros Dialog Box

The Macros dialog box allows you to run, edit, delete, and create macros as
well as set the VBA project options. Open the Macros dialog box from the
AutoCad Tools menu by choosing Macro Macros, or issue VBARUN at the
AutoCAD Command prompt.
The names of all macros in the valid range are displayed in this dialog box.
You can change the valid range by using the Macros In drop-down list. This
list specifies the projects or drawings whose macros are displayed. You can
choose to display the macros in

All drawings and projects

All drawings
All projects
Any individual drawing currently open in AutoCAD
Any individual project currently loaded in AutoCAD

By limiting the valid range you can control how many macro names appear
in the list. This will help you in the cases when many macros are available in
the loaded drawings and projects.
To create a new macro
1 Open the Macros dialog box and enter the name for the new macro.
2 In the Macros In drop-down list, select a project to create the new macro
in.
3 Choose Create.
If a macro with the specified name already exists, you will be asked if you
want to replace the existing macro.

16 | Chapter 1 Getting Started with

VBA

If you select Yes at the prompt, the code in the existing macro will be
deleted and a new, empty macro will be created with the specified name.
If you select No at the prompt, you will be returned to the Macros dialog box
to enter a new name for the macro.
If you select Cancel at the prompt, the Macros dialog box will be dismissed
and no new macro will be created.
To delete a macro
1 Open the Macros dialog box and select the macro to delete.
2 Choose Delete. You will be prompted to confirm the delete.
3 At the prompt, choose Yes to delete the macro, or No to cancel the delete.

Run a Macro
Running a macro executes the macro code within the context of the current
AutoCAD session. The current active drawing is considered to be the open
drawing that has the focus when macro execution begins. All VBA
references to the ThisDrawing object will refer to the current active drawing
for macros in global projects. For macros in embedded projects, the
ThisDrawing object always refers to the drawing in which the macro is
embedded.
To run a macro from the Macros dialog box
1 Open the Macros dialog box and select the macro to run.
2 Choose Run.
To run a macro from the VBA IDE

From the Run menu, use the Run Macro menu option.
If no macro or form is current, a dialog box will display allowing you to
choose the macro to run.
If a given macro is current (the cursor is in a procedure), that macro will
be executed.

Edit a Macro
Editing a macro will open the VBA IDE with the chosen macro open in the
Code window. For more information on editing macros in the VBA IDE see
Edit Your Projects with the VBA IDE on page 19.

Handle Your Macros

17

To edit a macro
1 Open the Macros dialog box and select the macro to edit.
2 Choose Edit.

Step into a Macro

Stepping into a macro begins execution of the macro and then halts the
execution on the first line of code. The VBA IDE is opened with the chosen
macro open in the Code window at the line of execution.
To step into a macro
1 In the Macros dialog box, select the macro to step into.
2 Choose Step Into.

Set the Project Options

There are three options that can be set for AutoCAD VBA projects:

Enable Auto Embedding

Allow Break on Errors
Enable Macro Virus Protection

To set the AutoCAD VBA project options

1 From the Tools menu choose Macro Macros to open the VBA
Macros dialog box.
2 From the VBA Macros dialog box, choose Options to open the Options
dialog box.
3 From the Options dialog box, select the options you want to enable.
4 Choose OK.
Enable Auto Embedding
The auto embed feature automatically creates an embedded VBA project for
all drawings when the drawing is opened.
Allow Break on Errors
This option allows VBA to enter Break mode when an error is encountered.
Break mode is a temporary suspension of program execution in the interactive development environment. In Break mode, you can examine, debug,
reset, step through, or continue program execution.

18 | Chapter 1 Getting Started with

VBA

When this option is enabled, unhandled errors found during the execution
of a VBA macro will suspend the execution of the macro and display the
VBA IDE at the point of the error in the macro.
When this option is disabled, untrapped errors found during the execution
of a VBA macro will display a message box alerting you to the error, and
then end execution of the macro.
Enable
Macro
Virus
Protection
The virus protection mechanism displays a built-in warning message whenever you open a drawing that may contain macro viruses.

Edit Your Projects with the VBA IDE

Once a project has been loaded into AutoCAD, you can edit the code, forms,
and references for that project using the VBA interactive development environment. You can also debug and run projects from the VBA IDE. Once
open, the VBA IDE provides access to all loaded projects.
To open the VBA IDE on demand
You can open the VBA IDE from the command line or from the menu
bar.
From the command line, enter VBAIDE, or from the Tools menu,
choose
Macro Visual Basic Editor.

View
Information

Project

The VBA IDE contains a window called the Project window, which displays a
list of all loaded VBA projects. It also displays the code, class, and form modules included in the project, the document associated with the project, all
other VBA projects referenced from the project, and the physical location
(path) of the project.
The Project window has its own toolbar, which can be used to open various
project components for editing. Use the View Code button to open the code
for a selected module. Use the View Object button to display selected
objects such as forms.

Edit Your Projects with the VBA

IDE | 19

View Object
View Code

The Project window is visible by default. If it is not visible, select

Project window from the View menu, or press CTRL + R .

Define the Components in a Project

Each project can contain many different components. The different
components a project can contain are objects, forms, standard modules,
class modules, and references.

Objects
The object component represents the type of object, or document, that the
VBA code will access. For AutoCAD VBA projects, this object represents the
current AutoCAD drawing.

Forms
The form component contains the custom dialog boxes you constructed for
use with your project.

Standard Modules
The code module component contains your generic procedures and
functions. A standard module is also referred to as a code module, or as
simply a module.

Class Modules
The class module component contains all your own objects, which are
defined as classes.

20 | Chapter 1 Getting Started with

VBA

References
The reference component contains all your references to other projects or
libraries.

Add New Components

Adding new components creates a blank component in your project. You can
add new modules, forms, and class modules to your project. You are responsible for updating all the properties of the component (such as the name of
the component) and for filling in the appropriate code. When naming new
components, remember that other developers may want to use your
compo- nents in future applications. Follow the appropriate naming
conventions for your development team.
To add a new component to your project
1 In the Project window of the VBA IDE, select the project to which you will
be adding the component.
2 From the Insert menu, select UserForm, Module, or Class Module to add
the new component to your project.
The new component will be added to your project and will appear in the
Project window.

Import Existing Components

Importing allows you to add an existing component to your project. You can
import forms, modules, or class modules. Forms are imported as FRM files,
modules are imported as BAS files, and class modules are imported as CLS
files.
When you import a component file, a copy of the file you are importing is
added to the project. The original file is left intact. Changes you make to the
imported component do not alter the original component file.
If you import a component with the same name as an existing one, the file
is added to your project with a number appended to it.
The imported component will be added to your project and will appear in the
Project window. To edit the properties of the component, select that component in the Project window. The properties for the selected component will
be listed and can be edited in the Properties window.

Edit Your Projects with the VBA

IDE | 21

To import an existing component to your project

1 In the Project window of the VBA IDE, select the project to which you will
be adding the component.
2 From the File menu, select Import File to open the Import File dialog box.
3 From the Import File dialog box, select the file to import and press Open.

Edit Components
You can edit standard modules, class modules, and forms in the VBA IDE.
Standard and class modules are edited in a Code window. Forms are edited in
the UserForm window using a special toolbox.
You can open as many Code windows as you have modules, so you can
easily view the code in different forms or modules, and copy and paste
between them.
To edit a component in your project
1 In the Project window of the VBA IDE, select the component you want to
edit.
2 Select the View Code button in the Project window to open a
Code window.
3

Select the View Object button in the

UserForm window and associated toolbox.

Project window to open a

To access the code associated with a form

To access the code associated with a control, double-click on any

control in the Form window. The code associated with that control will
open in a Code window.

Use the Code Window

The Code window contains two drop-down lists, a split bar, a margin indicator bar, and the full view and procedure view icons.
The two drop-down lists at the top of the Code window display the current
object and procedure. You can move about your project by changing the
object or procedure in these drop-down lists.
The split bar on the right side of the Code window allows you to split the
window horizontally. Simply drag this bar down to create another window
pane. This feature allows you to view two parts of code simultaneously in the
same module. To close the pane, drag the split bar back to its original
location.

22 | Chapter 1 Getting Started with

VBA

The margin indicator bar is located down the left side of the Code window.
It is used to display margin indicators that are used during code editing and
debugging.
The full view and procedure view icons are located at the bottom-left
corner of the Code window and toggle the display from only one
procedure at a time to viewing the entire module at one time.
current object

current procedure

margin
indicator
bar

split bar

Procedure/
Full View
buttons

Use
the
Window

UserForm

The UserForm window allows you to create custom dialog boxes in your
project.
To add a control simply drag the desired control from the toolbox and place
it on the form. You can set your controls to align with the grid of your
form from the General tab of the Options dialog box. You can view the
form grid and determine the size of the gridlines from the General tab of
the Options dialog box. (See Set the VBA IDE Options on page 26 for more
information on the Options dialog box.)
Each form you design will automatically have a Maximize, Minimize, and
Close button. These buttons have already been implemented for you.
To add code to the control, simply double-click on the control once it has
been placed on the form. This will open a Code window for the control.

Edit Your Projects with the VBA

IDE | 23

Name Your Project

The project name and the name of the .dvb file where the project is stored
are two different values. You establish the name of the .dvb file the project
is stored in when you save the project. The project name is set in the
Properties window of the VBA IDE.
If you do not set the project name and file name, AutoCAD automatically
assigns the following default names:
Project name: ACADProject
File name: Project.dvb
To change the name of a project
1 In the Project window of the VBA IDE, select the project to change.
2 In the Properties window, edit the Name property for the project.

To change the file name for a project

1 In the VBA IDE, select the Save option from the File menu.

2 In the Save As dialog box, enter the new name and location for the
project file.

Save Your Project

There is no explicit SAVE command in AutoCAD for VBA projects. Instead,
the SAVE command resides in the File menu of the VBA IDE and in the
VBA Manager. Any changes to a VBA project will access a standard Save
VBA Project dialog box when one of these events occurs:

You pick the SAVE command from the VBA IDE.

You choose the Save As option in the VBA Manager.
Your AutoCAD session is about to end or quit and the VBA project is
not saved.

Note Before you save a project, it is assigned the default file name
project.dvb. It is important that you assign a new name to your project file
when you save the project. If you save a project with the default file name
project.dvb, you will no longer be able to create new empty projects. Each time
you create a new project, you will actually be loading the saved project called
project.dvb.

Reference Other VBA Projects

Referencing one VBA project from another allows developers to share code
more easily. Developers can create libraries of commonly used macros and
then reference the library when needed. This keeps the shared code
centrally located and supported, while allowing a large number of developers
to utilize the code.
Once another project has been successfully referenced, you will notice a new
folder in the Projects window of the VBA IDE. This new folder is titled
References and contains the name of the project referenced.
Once you have referenced a project, you can use any public code or form
component in that project.
When a project that references another project is loaded into AutoCAD, the
referenced project is automatically loaded into AutoCAD as well. The referenced project cannot be closed until all projects that reference it are closed
first.
You cannot make circular references. That is, you cannot reference a
project that contains a reference back to the first project. If you accidentally
create a circular reference, you will be notified by VBA.

Project referencing is a standard feature of Microsoft VBA. There is no additional work in AutoCAD to extend this functionality. You can find more
information on referencing projects in the Microsoft Visual Basic help file.
You can open the Microsoft Visual Basic help file from the Help menu in the
VBA IDE.

Note You cannot reference embedded projects or VBA projects from

other applications.
To reference another VBA project
1 In the Project window of the VBA IDE, select the project to which you will
be adding the reference.
2 From the Tools menu, select the References option to open the
References dialog box.
3 From the References dialog box, press the Browse button to open the Add
Reference dialog box.
4 From the Add Reference dialog box, select the project file you want to reference and then press the Open button.
5 From the Add Reference dialog box, select the OK button to complete the
reference addition.

Set the VBA IDE Options

You can change the characteristics of the VBA IDE using the Options dialog
box. To open the Options dialog box, use the Tools menu and select
Options.
The Options dialog box contains four tabs: Editor, Editor Format, General,
and Docking.

Editor
The Editor tab specifies the Code window and Project window settings.
Code settings include

Auto Syntax Check

Require Variable Declaration
Auto List Member
Auto Quick Info
Auto Data Tips
Auto Indent
Tab Width

Window settings include

Drag and Drop Text Editing

Default to Full Module View
Procedure Separator Display

Editor Format
The Editor Format tab specifies the appearance of your Visual Basic code.
You can

Change color of the code

Change text list items
Change foreground
Change background
Change margin indicators
Change text font and size
Display or hide the margin indicator
Display or hide sample text for your settings

General
The General tab specifies the settings, error handling, and compile settings
for your current Visual Basic project.
You can

Change the grid settings for the form grid

Display or hide tooltips
Set the automatic collapse of windows
Choose to receive state loss notifications
Determine how errors are handled
Set the project to compile on demand or perform
background compilations

Docking
The Docking tab allows you to choose which windows you want to be
dockable.

Perform an Introductory
Exercise
Now that you have learned the basics of programming in AutoCAD VBA,
lets try creating a simple Hello World exercise. In this exercise you will
create a new AutoCAD drawing, add a line of text to that drawing, then
save the drawing, all from VBA.
Create the Hello World text object
1 Open the VBA IDE by entering the following command from the
AutoCAD command line:
Command: VBAIDE
2 Open the Code window by selecting the Code option from the View
menu in the VBA IDE.
3 Create a new procedure in the project by selecting the Procedure option
from the Insert menu in the VBA IDE.
4 When prompted for the procedure information, enter a name such as
HelloWorld. Make sure the Type selected is Sub, and the Scope selected is
Public.
5 Choose OK.
6 Enter the following code (that opens a new drawing) between the lines
Public Sub HelloWorld() and End Sub.
ThisDrawing.Application.Documents.Add

7 Enter the following code (that creates the text string and defines its insertion location) immediately following the code entered in step 6.
Dim
Dim
Dim
Dim

insPoint(0
textHeight
textStr As
textObj As

insPoint(0) = 2
insPoint(1) = 4
insPoint(2) = 0

To 2) As Double
As Double
String
AcadText

'Declare
'Declare
'Declare
'Declare

insertion point
text height
text string
text object

'Set insertion point x coordinate

'Set insertion point y coordinate
'Set insertion point z coordinate

textHeight = 1
textStr = "Hello World!"

'Set text height to 1.0

'Set the text string

'Create the Text object

Set textObj = ThisDrawing.ModelSpace.AddText _
(textStr, insPoint, textHeight)

8 Enter the code (that saves the drawing) immediately following the code
entered in step 7.
ThisDrawing.SaveAs("Hello.dwg")

9 Run your program by selecting the Run Sub/UserForm option from the
Run menu in the VBA IDE.
When the program finishes running, bring the AutoCAD application to the
front. You should see your text Hello World! visible in your drawing. The
drawing name should be Hello.dwg.

More Information
More information on the VBA IDE and the Visual Basic programming language is available in the Help files provided by Microsoft. To access the
Microsoft Help files, choose Microsoft Visual Basic Help from the Help
menu in the VBA IDE.

Review AutoCAD VBA Project Terms

Global Project

A VBA project stored in a .dvb file.

Embedded
Project

A VBA project stored in an AutoCAD drawing.

Regular
Document

An AutoCAD drawing that does not contain VBA

embedded projects.

Smart Document

An AutoCAD drawing that contains one or more VBA

embedded projects.

Current Project

The project currently selected in the VBA IDE.

ThisDrawing

ThisDrawing is a VBA programming term used to

represent the current drawing. For global projects,
ThisDrawing always refers to the active document in
AutoCAD. For embedded projects, ThisDrawing always
refers to the document containing the project.

VBA IDE

The VBA interactive development environment. This

application allows you to edit the code and forms in
your project, or copy code and forms from other
projects. It also allows you to set references to other
application Object Models.

More Information
29

VBA Manager

The VBA Manager allows you to manage your projects.

You can create, delete, embed, or extract projects. You
can also view which projects, if any, are embedded in an
open drawing.

Macros Dialog
Box

The Macros dialog box allows you to run, delete, and

create new macros, and provides access to the VBA
project options.

AutoCAD VBA Commands

VBAIDE

Brings up the VBA IDE.

The VBA IDE allows you to edit, run, and debug
programs interactively. Although the VBA IDE is
invoked only when AutoCAD is running, it can be
minimized, opened, and closed independent of the
AutoCAD Application window.

VBALOAD

Loads a VBA project into the current AutoCAD session.

VBARUN

Runs a VBA macro from the Macros dialog box or from

the AutoCAD command line.

VBAUNLOAD

Unloads a VBA project from the current AutoCAD

session.
If the VBA project is modified but not saved, the user is
asked to save it with the Save Project dialog box (or
command line equivalent).

VBAMAN

Displays the VBA Manager allowing you to view,

create, load, close, embed, and extract projects.

VBASTMT

Executes a VBA statement from the AutoCAD

command line.

ActiveX Automation
Basics

To use AutoCAD ActiveX Automation effectively you

In this chapter

should be familiar with the AutoCAD entities, objects,

Understand the

and features relating to the type of application you are

AutoCAD Object
Model

developing. The greater your knowledge of an objects

Access the Object

graphical and nongraphical properties, the easier it is

Collection Objects

for you to manipulate them through AutoCAD

ActiveX Automation.

Hierarchy

Understand Properties

and
Methods

Understand Parent

Remember that the

AutoCAD ActiveX Automation

Help file is availablejust press

F1

. If you are having

Objects

Locate the Type Library

Use Variants in Methods

trouble with a particular object, method, or property,

and
Properties

highlight the object, method, or property in the VBA

Using Other

IDE and

Programming
Languages

press

F1 .

31

Understand the AutoCAD Object

Model
An object is the main building block of the AutoCAD ActiveX interface. Each
exposed object represents a precise part of AutoCAD. There are many different types of objects in the AutoCAD ActiveX interface. For example

Graphical objects such as lines, arcs, text, and dimensions are objects.
Style settings such as linetypes and dimension styles are objects.
Organizational structures such as layers, groups, and blocks are objects.
The drawing display such as view and viewport are objects.
Even the drawing and the AutoCAD application are considered objects.

The objects are structured in a hierarchical fashion, with the Application

object at the root. The view of this hierarchical structure is referred to as the
Object Model. The Object Model shows you which object provides access
to the next level of objects.

32 | Chapter 2 ActiveX Automation

Basics

Understand the AutoCAD Object

Model | 33

The Application Object

The Application object is the Root object for the AutoCAD ActiveX
Automation Object Model. From the Application object, you can access any
of the other objects, or the properties or methods assigned to any object.
For example, the Application object has a Preferences property that returns
the Preferences object. This object provides access to the registry-stored settings in the Options dialog box. (Drawing-stored settings are contained in
the DatabasePreferences object, which will be discussed later.) Other properties of the Application object give you access to application-specific data such
as the application name and version, and the AutoCAD size, location, and
visibility. The methods of the Application object perform application-specific
actions such as listing, loading, and unloading ADS and ARX applications,
and quitting AutoCAD.
The Application object also provides links to the AutoCAD drawings
through the Documents collection, the AutoCAD menus and toolbars
through the MenuBar and MenuGroups collections, and the VBA IDE
through a property called VBE.
AutoCAD Application
Preferences
Documents
MenuBar
MenuGroups

The Application object is also the Global object for the ActiveX interface.
This means that all the methods and properties for the Application object
are available in the global name space.

The Document Object

The Document object, which is actually an AutoCAD drawing, is found in
the Documents collection and provides access to all of the graphical and
most of the nongraphical AutoCAD objects. Access to the graphical objects
(lines, circles, arcs, and so forth) is provided through the ModelSpace and
PaperSpace collections, and access to nongraphical objects (layers, linetypes,
text styles, and so forth) is provided through like-named collections such as

34 | Chapter 2 ActiveX Automation

Basics

Layers, Linetypes, and TextStyles. The Document object also provides access
to the Plot and Utility objects.

The Collection Objects

AutoCAD groups most objects in collections. Although these collections
contain different types of data, they can be processed using similar techniques. Each collection has a method for adding an object to the collection.
Most collections use the Add method for this purpose. However, entity
objects are usually added using a method titled Add<Entityname>. For
exam- ple, to add a line you would use the AddLine method.

Understand the AutoCAD Object

Model | 35

Collections also have some other methods and properties in common. The
Count property can be used to obtain a zero-based count of the objects in a
collection. The Item method can be used to obtain any object within a
collection.

The Graphical and Nongraphical Objects

Graphical objects, also known as entities, are the visible objects (lines,
circles, raster images, and so forth) that make up a drawing. To create these
objects, use the appropriate Add<Entityname> method. To modify or query
these objects, use the methods or properties of the object itself. Each
graphical object has methods that allow an application to perform most of
the AutoCAD editing commands such as Copy, Erase, Move, Mirror, and so
forth. These objects also have methods for setting and retrieving extended
data (xdata), highlighting and updating, and retrieving the bounding box
of the object. Graphical objects have typical properties such as Layer,
Linetype, Color, and Handle. They also have specific properties, depending
on their object type, such as Center, Radius, and Area.
Nongraphical objects are the invisible (informational) objects that are part
of a drawing, such as Layers, Linetypes, DimStyles, SelectionSets, and so
forth. To create these objects, use the Add method of the parent Collection
object. To modify or query these objects, use the methods or properties of
the object itself. Each nongraphical object has methods and properties
specific to its purpose; all have methods for setting and retrieving extended
data (xdata), and deleting themselves.

The Preferences, Plot, and Utility

Objects
Under the Preferences object is a set of objects, each corresponding to a tab
in the Options dialog box. Together, these objects provide access to all the
registry-stored settings in the Options dialog box. Drawing-stored settings
are contained in the DatabasePreferences object. You can also set and
modify options (and system variables that are not part of the Options
dialog box) with the SetVariable and GetVariable methods. For more
information about setting options see Set AutoCAD Preferences on page
53.

36 | Chapter 2 ActiveX Automation

Basics

AutoCAD Application
Preferences

PreferencesDisplay
PreferencesDrafting
PreferencesFiles
PreferencesOpenSave
PreferencesOutput
PreferencesProfile
PreferencesSelection
PreferencesSystem

PreferencesUser

Documents
Document
DatabasePreferences
Plot
Utility

The Plot object provides access to settings in the Plot dialog box and gives an
application the ability to plot the drawing using various methods. For more
information on plotting, see Plot Your Drawing on page 275.
The Utility object provides user input and conversion functions. The user
input functions are methods that prompt the user on the AutoCAD command line for input of various types of data, such as strings, integers, reals,
points, and so forth. The conversion functions are methods that operate on
AutoCAD-specific data types such as points and angles, in addition to string
and number handling. For more information on the user input functions,
see Prompt for User Input on page 73.

Understand the AutoCAD Object

Model | 37

Access the Object

Hierarchy
Accessing the object hierarchy is easy from within VBA. This is because VBA
is running in-process with the current AutoCAD session so there is no additional step needed to connect it to the application.
VBA provides a link to the active drawing in the current AutoCAD session
through the ThisDrawing object. By using ThisDrawing you gain
immediate access to the current Document object and all of its methods and
properties, and all of the other objects in the hierarchy.
When used in global projects, ThisDrawing always refers to the active
docu- ment in AutoCAD. When used in embedded projects, ThisDrawing
always refers to the document containing the project. For example, the
following line of code in a global project saves whatever drawing is
currently active in AutoCAD:
ThisDrawing.Save

Reference Objects in the Object

Hierarchy
You can reference objects directly or through a user-defined variable. To reference the objects directly, include the object in the calling hierarchy. For
example, the following statement adds a line to the model space. Notice that
the hierarchy starts with ThisDrawing, goes to the ModelSpace object, and
then calls the AddLine method:
Dim startPoint(0 To 2) As Double, endPoint(0 To 2) As Double
Dim LineObj as AcadLine
startPoint(0) = 0: startPoint(1) = 0: startPoint(2) = 0
endPoint(0) = 30: endPoint(1) = 20: endPoint(2) = 0
Set LineObj = ThisDrawing.ModelSpace.AddLine(startPoint,endPoint)

To reference the objects through a user-defined variable, define the variable

as desired type, then set the variable to the appropriate object. For example,
the following code defines a variable (moSpace) of type AcadModelSpace and
sets the variable equal to the current model space:
Dim moSpace As AcadModelSpace
Set moSpace = ThisDrawing.ModelSpace

The following statement then adds a line to the model space using the userdefined variable:
Dim startPoint(0 To 2) As Double, endPoint(0 To 2) As Double
Dim LineObj as AcadLine
startPoint(0) = 0: startPoint(1) = 0: startPoint(2) = 0
endPoint(0) = 30: endPoint(1) = 20: endPoint(2) = 0
Set LineObj = moSpace.AddLine(startPoint,endPoint)

38 | Chapter 2 ActiveX Automation

Basics

Retrieving the first entity in model space

The following example returns the first entity object in model space.
Similar code can do the same for paper space entities:
Sub Ch2_FindFirstEntity()
' This example returns the first entity in model space
On Error Resume Next
Dim entity As AcadEntity
If ThisDrawing.ModelSpace.count <> 0 Then
Set entity = ThisDrawing.ModelSpace.Item(0)
MsgBox entity.ObjectName + _
" is the first entity in model space."
Else
MsgBox "There are no objects in model space."
End If
End Sub

Access the Application Object

Because the ThisDrawing object provides a link to the Document object, you
may be wondering how you access the root object (Application object),
which is situated above the Document object in the object hierarchy. The
Document object has a property called Application that provides a link to
the Application object.
For example, the following line of code updates the application:
ThisDrawing.Application.Update

Collection
Objects
A Collection object is a predefined object that contains (is a parent object
for) all instances of a similar object. There is a Collection object for the
following objects:
Documents
Collection

Contains all documents open in the current AutoCAD

session.

ModelSpace
Collection

Contains all graphical objects (entities) in model space.

PaperSpace
Collection

Contains all graphical objects (entities) in the active

paper space layout.

Block Object

Contains all entities within a specific block definition.

Blocks Collection

Contains all blocks in the drawing.

Collection Objects
39

Dictionaries
Collection
DimStyles
Collection
Groups
Collection

Contains all dictionaries in the drawing.

Contains all dimension styles in the drawing.
Contains all groups in the drawing.
Contains all hyperlinks for a given entity.

Hyperlinks
Collection
Layers Collection

Contains all layers in the drawing.

Layouts
Collection

Contains all layouts in the drawing.

Linetypes
Collection
MenuBar
Collection
MenuGroups
Collection
RegisteredApplic
ations Collection
SelectionSets
Collection

Contains all linetypes in the drawing.

Contains all menus currently displayed in AutoCAD.
Contains all menus and toolbars currently loaded in
AutoCAD.
Contains all registered applications in the drawing.
Contains all selection sets in the drawing.
Contains all text styles in the drawing.

TextStyles
Collection
UCSs Collection

Contains all user coordinates systems (UCS) in the

drawing.

Views Collection

Contains all views in the drawing.

Viewports
Collection

Contains all viewports in the drawing.

Access a Collection
Most collection objects are accessed through the Document object. The
Document object contains a property for each of the Collection objects. For
example, the following code defines a variable and sets it to the Layers collection of the current drawing:

Dim layerCollection as AcadLayers

Set layerCollection = ThisDrawing.Layers

The Documents collection, MenuBar collection, and MenuGroups

collection are accessed through the Application object. The Application
object contains a property for each of these collections. For example, the
following code defines a variable and sets it to the MenuGroups collection
for the application:
Dim MenuGroupsCollection as AcadMenuGroups
Set MenuGroupsCollection = ThisDrawing.Application.MenuGroups

Add a New Member to a Collection

Object
To add a new member to the collection, use the Add method. For example,
the following code creates a new layer and adds it to the Layers collection:
Dim newLayer as AcadLayer
Set newLayer = ThisDrawing.Layers.Add("MyNewLayer")

Iterate through a Collection

Object
To select a specific member of a Collection object, use the Item method. The
Item method requires an identifier as either an index number specifying the
location of the item within the collection or a string representing the name
of the item.
The Item method is the default method for a collection. If you do not specify
a method name when referring to a collection, Item is assumed. The following statements are equivalent:
ThisDrawing.Layers.Item("ABC")
ThisDrawing.Layers("ABC")

Note Do not use the entity edit methods (Copy, Array, Mirror, and so forth)
on any object while simultaneously iterating through a collection using the For
Each mechanism. Either finish your iteration before you attempt to edit an
object in the collection or create a temporary array and set it equal to the
collection. Then you can iterate through the copied array and perform your
edits.
Iterate through the Layers collection
The following example iterates through a collection and displays the
names of all layers in the collection:

Sub Ch2_IterateLayer()
' Iterate through the collection
On Error Resume Next
Dim
Dim
msg
For

I As Integer
msg As String
= ""
I = 0 To ThisDrawing.Layers.count - 1
msg = msg + ThisDrawing.Layers.Item(I).Name + vbCrLf

Next
MsgBox msg
End Sub

Find the layer named MyLayer

The following example refers to layer named MyLayer, and issues a
message if the layer does not exist:
Sub Ch2_FindLayer()
' Use the Item method to find a layer named MyLayer
On Error Resume Next
Dim ABCLayer As AcadLayer
Set ABCLayer = ThisDrawing.Layers("MyLayer")
If Err <> 0 Then
MsgBox "The layer 'MyLayer' does not exist."
End If
End Sub

Delete a Member of a Collection Object

To delete a specific dimension style, use the Delete method found on the
member object. For example, the following code deletes the layer ABC:
Dim ABCLayer as AcadLayer
Set ABCLayer = ThisDrawing.Layers.Item("ABC")
ABCLayer.Delete

Once an object has been deleted, you must never attempt to access the
object again later in the program.

Understand Properties and

Methods
Each object has associated properties and methods. Properties describe
aspects of the individual object, while methods are actions that can be
performed on the individual object. Once an object is created, you can
query and edit the object through its properties and methods.

For example, a Circle object has the Center property. This property
represents the 3D World Coordinate System coordinate at the center of
that circle. To change the center of the circle, simply set this property to the
new coordi- nate. The Circle object also has a method called Offset. This
method creates a new object at a specified offset distance from the existing
circle. To see a list of all properties and methods for the Circle object, refer
to the Circle object in the AutoCAD ActiveX and VBA Reference.

Understand Parent Objects

Each object has a parent object to which it is permanently linked. All
objects originate from a single parent object called the root object. You can
access all the objects in the interface by following the links from the root to
the
child objects. Additionally, all objects have a property called
Application that links directly back to the root object.
The root object for the AutoCAD interface is the AutoCAD application.

Locate the Type Library

The objects, properties, and methods exposed by automation objects are contained in a type library. A type library is a file or part of a file that describes
the type of one or more objects.
Type libraries do not store objects; they store information. By accessing a
type library, applications and browsers can determine the characteristics of
an object, such as the interfaces supported by the object and the names and
addresses of the members of each interface.
Before you can use the automation object exposed by an application, you
must reference its type library. The reference is automatically set in AutoCAD
VBA. For other interactive development environments you must create a reference to the AutoCAD type library, acax16enu.tlb, which by default is
located at c:\program files\common files\autodesk shared.
You can use an applications objects without referencing the applications
type library. However, it is preferable to add the type library reference for the
following reasons:

Understand Parent Objects

| 43

Globally accessible functions may be accessed directly

without qualification.
Invocation of functions, properties, and methods can be checked at
compile time for correctness, and therefore will execute more quickly at
runtime.
It is possible to declare variables of the types defined in the library,
which increases runtime reliability and readability.

Use Variants in Methods and

Properties
AutoCAD ActiveX Automation uses variants to pass arrays of data. Although
this may seem confusing to a novice user, it is not difficult once you learn
the basics. In addition, AutoCAD ActiveX Automation provides utilities to
help you convert your data types.

What Is a Variant?
A variant is a special data type that can contain any kind of data except
fixed- length string data and user-defined types. A variant can also contain
the special values Empty, Error, Nothing, and NULL. You can determine how
the data in a variant is treated using the VarType or TypeName Visual Basic
functions.
You can use the Variant data type in place of most any data type to work
with data in a more flexible way.

Use Variants for Array Data

Variants are used to pass array data in and out of AutoCAD ActiveX
Automa- tion. This means that your arrays must be a variant to be accepted
by AutoCAD ActiveX Automation methods and properties. In addition,
array data output from AutoCAD ActiveX Automation must be handled as a
variant.

Note In AutoCAD, VBA input arrays are automatically converted to variants.

This means that you dont have to provide a variant array as input to the
ActiveX Automation methods and properties when using them from VBA.
However, all the output arrays will be in the form of variants, so remember to
handle them appropriately.

44 | Chapter 2 ActiveX Automation

Basics

Convert Arrays to Variants

AutoCAD ActiveX Automation provides a utility method to convert an array
of data into a variant. This method is the CreateTypedArray method, which
creates a variant that contains an array of integers, floating numbers, doubles, and so forth. You can pass the resulting variant into any AutoCAD
method or property that accepts an array of numbers as a variant.
The CreateTypedArray method takes as input the type of values that are in
the array, and the array of data to be converted. It returns the array of values
as a variant.
Create a spline with the CreateTypedArray method
The following code converts three arrays using CreateTypedArray: the coordinates for a splines fit points, and the start and end tangent of the spline.
It then passes the variant into the AddSpline method to create the spline.
Sub Ch2_CreateSplineUsingTypedArray()
' This example creates a spline object in model space
' using the CreateTypedArray method.
Dim splineObj As AcadSpline
Dim startTan As Variant
Dim endTan As Variant
Dim fitPoints As Variant
Dim utilObj As Object
' late bind the Utility object
Set utilObj = ThisDrawing.Utility
' Define the Spline Object
utilObj.CreateTypedArray _
startTan, vbDouble, 0.5, 0.5, 0
utilObj.CreateTypedArray _
endTan, vbDouble, 0.5, 0.5, 0
utilObj.CreateTypedArray _
fitPoints, vbDouble, 0, 0, 0, 5, 5, 0, 10, 0, 0
Set splineObj = ThisDrawing.ModelSpace.AddSpline _
(fitPoints, startTan, endTan)
' Zoom in on the newly created spline
ZoomAll
End Sub

Use Variants in Methods and

Properties | 45

Interpret Variant Arrays

Array information passed back from AutoCAD ActiveX Automation is
passed back as a variant. If you know the data type of the array, you can
simply access the variant as an array. If you dont know the data type
contained in the variant, use the VBA functions VarType or Typename. These
functions return the type of data in the variant. If you need to iterate
through the array, you can use the VBA For Each statement.
Calculate the distance between two points
The following code demonstrates calculating the distance between two
points input by the user. In this example, the data type is known because all
coordinates are doubles. 3D coordinates are a three-element array of
doubles and 2D coordinates are a two-element array of doubles.
Sub Ch2_CalculateDistance()
Dim point1 As Variant
Dim point2 As Variant
' Get the points from the user
point1 = ThisDrawing.Utility.GetPoint
(, vbCrLf & "First point:
point2 = ThisDrawing.Utility.GetPoint
(point1, vbCrLf & "Second

_
")
_
point: ")

' Calculate the distance between point1 and point2

Dim x As Double, y As Double, z As Double
Dim dist As Double
x = point1(0) - point2(0)
y = point1(1) - point2(1)
z = point1(2) - point2(2)
dist = Sqr((Sqr((x ^ 2) + (y ^ 2)) ^ 2) + (z ^ 2))
'Display the resulting distance
MsgBox "The distance between the points is: " _
& dist, , "Calculate Distance"
End Sub

Using Other Programming

Languages
This manual is written for the VBA programming language. The programming examples and sample applications are written in VBA. To use the code
in other programming environments, you must update it for the chosen
environment.
Use the documentation for your development environment to help you
convert the example code.

46 | Chapter 2 ActiveX Automation

Basics

Note The registry key for COM application access for AutoCAD 2004 is
AutoCAD.Application.16.

Convert the VBA Code to VB

To update the coding examples for use with VB, you must first reference the
AutoCAD type library. To do this in VB, select the References option from the
Project menu to launch the Reference dialog box. From the References
dialog box, choose the type library for AutoCAD, and then click OK.
Next, in the code example replace all references to ThisDrawing with a userspecified variable referencing the active document. To do this, define a
variable for the AutoCAD application (acadApp) and for the current document (acadDoc). Then, set the application variable to the current AutoCAD
application.
If AutoCAD is running, the VB GetObject function retrieves the AutoCAD
Application object when you specify the AutoCAD version number. If
AutoCAD is not running, an error occurs that (in this example) is trapped,
then cleared. The CreateObject function then attempts to create an
AutoCAD Application object. If it succeeds, AutoCAD is started; if it fails, a
message box displays a description of the error.
When running multiple sessions of AutoCAD, the GetObject function will
return the first instance of AutoCAD in the Windows Running Object Table.
See the Microsoft Visual Basic documentation on the Running Object Table
(ROT) and the GetObject function for more information on verifying the
ses- sion returned by GetObject.
You must set the AutoCAD applications Visible property to TRUE in order
to display the AutoCAD drawing window.
If GetObject creates a new instance of AutoCAD (that is, AutoCAD was not
already running when you issued GetObject), failure to set Visible to TRUE
results in an invisible AutoCAD application; AutoCAD will not even appear
on the Windows taskbar.

Note Use version-dependent ProgIDs. If a CreateObject or GetObject

function uses a version-independent ProgID, change the function to use a
version-depen- dent ProgID. For example, if you are using CreateObject, you
change CreateOb- ject ("AutoCAD.Application") to CreateObject
("AutoCAD.Application.16"). Additionally, if a GetInterfaceObject method uses a
version-independent ProgID, the method must be changed to use a versiondependent ProgID.

Using Other Programming

Languages | 47

Connect to AutoCAD from Visual Basic

The following code example uses the Clear and Description properties of Err.
If your coding environment does not support these properties, you will
need to modify the example appropriately:
Sub Ch2_ConnectToAcad()
Dim acadApp As AcadApplication
On Error Resume Next
Set acadApp = GetObject(, "AutoCAD.Application.16")
If Err Then
Err.Clear
Set acadApp = CreateObject("AutoCAD.Application.16")
If Err Then
MsgBox Err.Description
Exit Sub
End If
End If
MsgBox "Now running " + acadApp.Name + _
" version " + acadApp.Version
End Sub

Next, set the document variable to the Document object in the AutoCAD
application. The Document object is returned by the ActiveDocument property of the Application object.
Dim acadDoc as AcadDocument
Set acadDoc = acadApp.ActiveDocument

From this point on, use the acadDoc variable to reference the current
AutoCAD drawing.

48 | Chapter 2 ActiveX Automation

Basics

VBA versus VB Comparison Code Example

The following code example demonstrates creating a line in both VBA and
VB.
Creating a line using VBA:
Sub Ch2_AddLineVBA()
' This example adds a line
' in model space
Dim lineObj As AcadLine
Dim startPoint(0 To 2) As Double
Dim endPoint(0 To 2) As Double
' Define the start and end
' points for the line
startPoint(0) = 1
startPoint(1) = 1
startPoint(2) = 0
endPoint(0) = 5
endPoint(1) = 5
endPoint(2) = 0
' Create the line in model space
Set lineObj = ThisDrawing. _
ModelSpace.AddLine _
(startPoint, endPoint)
' Zoom in on the newly created line
ZoomAll
End Sub

Using Other Programming

Languages | 49

Creating a line using VB:

Sub Ch2_AddLineVB()
On Error Resume Next
' Connect to the AutoCAD application
Dim acadApp As AcadApplication
Set acadApp = GetObject _
(, "AutoCAD.Application.16")
If Err Then
Err.Clear
Set acadApp = CreateObject _
("AutoCAD.Application.16")
If Err Then
MsgBox Err.Description
Exit Sub
End If
End If
' Connect to the AutoCAD drawing
Dim acadDoc As AcadDocument
Set acadDoc = acadApp.ActiveDocument
' Establish the endpoints of the line
Dim lineObj As AcadLine
Dim startPoint(0 To 2) As Double
Dim endPoint(0 To 2) As Double
startPoint(0) = 1
startPoint(1) = 1
startPoint(2) = 0
endPoint(0) = 5
endPoint(1) = 5
endPoint(2) = 0
' Create a Line object in model space
Set lineObj = acadDoc.ModelSpace.AddLine _
(startPoint, endPoint)
ZoomAll
acadApp.visible = True
End Sub

50

Control the AutoCAD

Environment

This chapter describes the fundamentals for developing

an

application in AutoCAD. It explains how to

control and work

environment.

effectively in

the

AutoCAD

In this chapter
Open, Save, and Close

Drawings
Set AutoCAD Preferences
Control the Application

Window
Control the Drawing

Windows

Reset Active Objects

Set and Return System

Variables
Draw with Precision
Prompt for User Input
Access the

AutoCAD
Command Line
Work with No Documents

Open
Import Other File Formats
Export to Other File

Formats

51

Open, Save, and Close

Drawings
The Documents collection and Document object provide access to the
AutoCAD file functions.
To create a new drawing, or open an existing drawing, use the methods on
the Documents collection. The Add method creates a new drawing and adds
that drawing to the Documents collection. The Open method opens an existing drawing. There is also a Close method on the Documents collection that
closes all the drawings open in the AutoCAD session.
Use either the Save or SaveAs methods to save a drawing. Occasionally you
will want to check if the active drawing has any unsaved changes. It is a
good idea to do this before you quit the AutoCAD session or start a new
drawing. Use the Saved property to make sure that the current drawing does
not con- tain any unsaved changes.
To import and export drawings, use the Import and Export methods on the
Document object.
Open an existing drawing
This example uses the Open method to open an existing drawing. The Visual
Basic Dir function is used to check for the existence of the file before trying
to open it. You should change the drawing file name or path to specify an
existing AutoCAD drawing file on your system.
Sub Ch3_OpenDrawing()
Dim dwgName As String
dwgName = "c:\campus.dwg"
If Dir(dwgName) <> "" Then
ThisDrawing.Application.Documents.Open dwgName
Else
MsgBox "File " & dwgName & " does not exist."
End If
End Sub

Create a new drawing

This example uses the Add method to create a new drawing based on the
default template.
Sub Ch3_NewDrawing()
Dim docObj As AcadDocument
Set docObj = ThisDrawing.Application.Documents.Add
End Sub

52 | Chapter 3 Control the AutoCAD

Environment

Save the active drawing

The following example saves the active drawing under its current name and
again under a new name.
Sub Ch3_SaveActiveDrawing()
' Save the active drawing under the current name
ThisDrawing.Save
' Save the active drawing under a new name
ThisDrawing.SaveAs "MyDrawing.dwg"
End Sub

Test if a drawing has unsaved changes

This example checks to see if there are unsaved changes and verifies with
the user that it is OK to save the drawing (if it is not OK, skip to the end). If
OK, use the Save method to save the current drawing, as shown here:
Sub Ch3_TestIfSaved()
If Not (ThisDrawing.Saved) Then
If MsgBox("Do you wish to save this drawing?", _
vbYesNo) = vbYes Then
ThisDrawing.Save
End If
End If
End Sub

Set AutoCAD
Preferences
There are nine objects pertaining to options, each representing a tab on the
Options dialog box. These objects provide access to all of the registry-stored
options in the Options dialog box. You can customize many of the
AutoCAD settings by using properties found on these objects. These objects
are

PreferencesDisplay
PreferencesDrafting
PreferencesFiles
PreferencesOpenSave
PreferencesOutput
PreferencesProfiles
PreferencesSelection
PreferencesSystem
PreferencesUser

These objects are accessible via the Preferences object. To gain access to the
Preferences object, use the Preferences property of the Application object:
Dim acadPref as AcadPreferences
Set acadPref = ThisDrawing.Application.Preferences

You can then access any of the specific Preferences objects using the
Display, Drafting, Files, OpenSave, Output, Profile, Selection, System, and
User properties.
Set the crosshairs to full screen
Sub Ch2_PrefsSetCursor()
' This example sets the crosshairs of the AutoCAD drawing
cursor
' to full screen.
' Access the Preferences object
Dim acadPref As AcadPreferences
Set acadPref = ThisDrawing.Application.Preferences
' Use the CursorSize property to set the size of the
crosshairs acadPref.Display.CursorSize = 100
End Sub

Display the screen menu and scroll bars

Sub Ch2_PrefsSetDisplay()
' This example enables the screen menu and disables the scroll
' bars with the DisplayScreenMenu and DisplayScrollBars
' properties.
' Access the Preferences object
Dim acadPref As AcadPreferences
Set acadPref = ThisDrawing.Application.Preferences
' Display the screen menu and disable scroll bars
acadPref.Display.DisplayScreenMenu = True
acadPref.Display.DisplayScrollBars = False
End Sub

Database Preferences
In addition to the nine Preferences objects, the DatabasePreferences object
contains all the options stored in the drawing. This separate object was provided to make the drawing-stored options available to applications accessing
AutoCAD drawings without first starting the AutoCAD application
(ObjectDBXTM applications).
The DatabasePreferences object is found under the Document object.

Control the Application Window

The ability to control the Application window allows developers the flexibility to create effective and intelligent applications. There will be times when
it is appropriate for your application to minimize the AutoCAD window,
perhaps while your code is performing work in another application such as
Excel. Additionally, you will often want to verify the state of the AutoCAD
window before performing such tasks as prompting for input from the user.
Using methods and properties found on the Application object, you can
change the position, size, and visibility of the Application window. You can
also use the WindowState property to minimize, maximize, and check the
current state of the Application window.
Position and size the Application window
This example uses the WindowTop, WindowLeft, Width, and Height properties to position the AutoCAD Application window in the upper-left corner of
the screen and size it to 400 pixels wide by 400 pixels high.
Sub Ch3_PositionApplicationWindow()
ThisDrawing.Application.WindowTop = 0
ThisDrawing.Application.WindowLeft = 0
ThisDrawing.Application.width = 400
ThisDrawing.Application.height = 400
End Sub

Maximize the Application window

Sub Ch3_MaximizeApplicationWindow()
ThisDrawing.Application.WindowState = acMax
End Sub

Minimize the Application window

Sub Ch3_MinimizeApplicationWindow()
ThisDrawing.Application.WindowState = acMin
End Sub

Find the current state of the Application window

This example queries the state of the Application window and displays the
state in a message box to the user.

Control the Application Window

| 55

Sub Ch3_CurrentWindowState()
Dim CurrWindowState As Integer
Dim msg As String
CurrWindowState = ThisDrawing.Application.WindowState
msg = Choose(CurrWindowState, "normal", _
"minimized", "maximized")
MsgBox "The application window is " + msg
End Sub

Make the Application window invisible

The following code uses the Visible property to make the AutoCAD application invisible to the end user.
Sub Ch3_HideWindowState()
ThisDrawing.Application.Visible = False
End Sub

Control the Drawing

Windows
Like the AutoCAD Application window, you can minimize, maximize, reposition, resize, and check the state of any Document window. But you can also
change the way the drawing is displayed within a window by using views,
viewports, and zooming methods.
AutoCAD ActiveX provides many ways to display views of your drawing.
You can control the drawing display to move quickly to different areas of
your drawing while you track the overall effect of your changes. You can
zoom to change magnification or pan to reposition the view in the graphics
area, save a view and then restore it when you need to plot or refer to
specific details, or display several views at one time by splitting the screen
into several tiled viewports.

Position and Size the Document Window

Use the Document object to modify the position and size of any document
window. The Document window can be minimized or maximized by using
the WindowState property, and you can find the current state of the Document window by using the WindowState property.
Position a Document window
This example uses the Width and Height properties to set the active
docu- ment window to 400 pixels wide by 400 pixels high.

56 | Chapter 3 Control the AutoCAD

Environment

Sub Ch3_SizeDocumentWindow()
ThisDrawing.Width = 400
ThisDrawing.Height = 400
End Sub

Maximize the active Document window

Sub Ch3_MaximizeDocumentWindow()
ThisDrawing.WindowState = acMax
End Sub

Minimize the active Document window

Sub Ch3_MinimizeDocumentWindow()
ThisDrawing.WindowState = acMin
End Sub

Find the current state of the active document window

Sub Ch3_CurrentWindowState()
Dim CurrWindowState As Integer
Dim msg As String
CurrWindowState = ThisDrawing.WindowState
msg = Choose(CurrWindowState, "normal", _
"minimized", "maximized")
MsgBox "The document window is " + msg
End Sub

Use Zoom
A view is a specific magnification, position, and orientation of a drawing.
The most common way to change a view is to use one of the many
AutoCAD Zoom options, which increases or decreases the size of the image
displayed in the graphics area. For more information on zooming in
AutoCAD, see Magnify a View (Zoom) in the Users Guide.

Define a Zoom Window

You can quickly zoom in on an area by specifying the corners that define it.
To zoom in on an area by specifying its boundaries, use either the
ZoomWindow or ZoomPickWindow method. The ZoomWindow method
allows you to define two points representing the Zoom window
programmat- ically. The ZoomPickWindow requires the user to pick two
points. These two picked points become the Zoom window.

Control the Drawing Windows

| 57

Zoom the active drawing to a window defined by two points

Sub Ch3_ZoomWindow()
' ZoomWindow
MsgBox "Perform a ZoomWindow with:" & vbCrLf & _
"1.3, 7.8, 0" & vbCrLf & _
"13.7, -2.6, 0", , "ZoomWindow"
Dim point1(0 To 2) As Double
Dim point2(0 To 2) As Double
point1(0) = 1.3: point1(1) = 7.8: point1(2) = 0
point2(0) = 13.7: point2(1) = -2.6: point2(2) = 0
ThisDrawing.Application.ZoomWindow point1, point2
' ZoomPickWindow
MsgBox "Perform a ZoomPickWindow", , "ZoomPickWindow"
ThisDrawing.Application.ZoomPickWindow
End Sub

Scale a View
If you need to increase or decrease the magnification of the image by a
precise scale, you can specify a zoom scale in three ways:

Relative to the drawing limits

Relative to the current view
Relative to paper space units

To scale a view, use the ZoomScaled method. This method takes two
param- eters as input: the scale and the type of scale. The scale is simply a
number. How that number gets interpreted by AutoCAD depends on the
type of scale you choose.
The type of scale determines if the scale value is created relative to the drawing limits, the current view, or the paper space units. To scale relative to the
drawing limits, use the constant acZoomScaledAbsolute. To scale the view
relative to the current view, use the constant acZoomScaledRelative. To scale
relative to paper space units, use the constant
acZoomScaledRelativePSpace.

58 | Chapter 3 Control the AutoCAD

Environment

Zoom in on the active drawing using a specified scale

Sub Ch3_ZoomScaled()
MsgBox "Perform a ZoomScaled using:" & vbCrLf & _
"Scale Type: acZoomScaledRelative" & vbCrLf & _
"Scale Factor: 2", , "ZoomScaled"
Dim scalefactor As Double
Dim scaletype As Integer
scalefactor = 2
scaletype = acZoomScaledRelative
ThisDrawing.Application.ZoomScaled scalefactor, scaletype
End Sub

Center Objects
You can move a specific point in your drawing to the center of the graphics
area. The ZoomCenter method is useful for resizing an object and bringing
it to the center of the viewport. With ZoomCenter, you can specify a scale
size by entering a magnification relative to the current view.
Zoom in on the active drawing to a specified center
The following example shows the effects of using ZoomCenter to display a
view at the same size and at twice the size:
Sub Ch3_ZoomCenter()
MsgBox "Perform a ZoomCenter using:" & vbCrLf & _
"Center 3, 3, 0" & vbCrLf & _
"Magnification: 10", , "ZoomCenter"
Dim Center(0 To 2) As Double
Dim magnification As Double
Center(0) = 3: Center(1) = 3: Center(2) = 0
magnification = 10
ThisDrawing.Application.ZoomCenter Center, magnification
End Sub

Display Drawing Limits and Extents

To display a view based on the drawing boundaries or the extents of the
objects in the drawing, use the ZoomAll, ZoomExtents, or ZoomPrevious
methods.

Control the Drawing Windows

| 59

ZoomAll displays the entire drawing. If the objects extend beyond the limits,
ZoomAll displays the extents of the objects. If the objects are drawn within
the limits, ZoomAll displays the limits.
ZoomExtents calculates zooms based on the extents of the active viewport,
not the current view. Usually the active viewport is entirely visible, so the
results are obvious and intuitive. However, when using the Zoom methods
in model space while working in a paper space viewport, if you are zoomed
in beyond the paper space viewports borders, some of the area zoomed may
not be visible.
ZoomExtents changes the view to encompass the entity extents for the current drawing. In some cases (for both ZoomAll and ZoomExtents), this may
cause a regeneration. Regeneration will not occur on layers that are frozen
or turned off. If your drawing has no objects, ZoomExtents displays the
drawing limits.
For 3D views, ZoomAll and ZoomExtents have the same effect. Infinite construction lines (xlines) and rays do not affect either option.
ZoomPrevious zooms the current viewport to its previous extents.
See Magnify a View (Zoom) in the Users Guide for illustrations of how
zooming works.
Zoom in on the active drawing to all contents and to the drawing extents
Sub Ch3_ZoomAll()
' ZoomAll
MsgBox "Perform a ZoomAll", , "ZoomAll"
ThisDrawing.Application.ZoomAll
' ZoomExtents
MsgBox "Perform a ZoomExtents", , "ZoomExtents"
ThisDrawing.Application.ZoomExtents
End Sub

Use Named Views

You can name and save a view you want to reuse. When you no longer
need the view, you can delete it.
To create a new view, use the Add method to add a new view to the Views
collection. When you save the drawing, the viewing position and scale of the
view are saved.
You name the view when you create it. The name of the view can be up to
255 characters long and contain letters, digits, and the special
characters dollar sign ($), hyphen (), and underscore (_).

60 | Chapter 3 Control the AutoCAD

Environment

To delete a named view, simply use the Delete method. The Delete
method for the View object lies on the View object, not its parent.
Add a View object
Sub Ch3_AddView()
' Add a named view to the views collection
Dim viewObj As AcadView
Set viewObj = ThisDrawing.Views.Add("View1")
End Sub

Delete a View object

The following example deletes a View object (viewObj).
Sub Ch3_DeleteView()
Dim viewObj As AcadView
Set viewObj = ThisDrawing.Views("View1")
' Delete the view
viewObj.Delete
End Sub

Delete a named view from the Views collection

This example deletes a named view from the Views collection.
Sub Ch3_DeleteViewFromCollection()
ThisDrawing.Views("View1").Delete
End Sub

Use Tiled Viewports

AutoCAD usually begins a new drawing using a single viewport that fills the
entire graphics area. You can split the graphics area to display several viewports simultaneously. For example, if you keep both the full and the detail
views visible, you can see the effects of your detail changes on the entire
drawing. In each tiled viewport, you can do the following:

Zoom, set the Snap, Grid, and UCS icon modes, and restore named
views in individual viewports
Draw from one viewport to another when executing a command
Name a configuration of viewports so you can reuse it

You can display tiled viewports in various configurations. How you display
the viewports depends on the number and size of the views you need to
see.
For further information and illustrations describing viewports, see Set
Model Tab Viewports in the Users Guide.

Control the Drawing Windows

| 61

Split the Active Viewport

To split the active viewport, use the Split method. This method takes one
parameter, the type of configuration to split the viewport into. To specify the
window configuration, use one of the following constants that correspond
to the default configurations previously shown: acViewport2Horizontal,
acViewport2Vertical, acViewport3Left, acViewport3Right,
acViewport3Horizontal, acViewport3Vertical, acViewport3Above,
acViewport3Below, or acViewport4.
For further information on changing viewport configuration, see Set Model
Tab Viewports in the Users Guide.
Split a viewport into two horizontal windows
The following example creates a new viewport and then splits the viewport
into two horizontal windows.
Sub SplitAViewport()
' Create a new viewport
Dim vportObj As AcadViewport
Set vportObj = ThisDrawing.Viewports.Add("TEST_VIEWPORT")
' Split vportObj into 2 horizontal windows
vportObj.Split acViewport2Horizontal
' Now set vportObj to be the active viewport
ThisDrawing.ActiveViewport = vportObj
End Sub

Make Another Tiled Viewport Current

You enter points and select objects in the current viewport. To make a viewport current, use the ActiveViewport property.
You can iterate through existing viewports to find a particular viewport. To
do this, first identify the name of the viewport configuration on which the
desired viewport resides using the Name property. Additionally, if the
viewport configuration has been split, each individual viewport on the
configuration can be identified through the LowerLeftCorner and
UpperRightCorner properties.
The LowerLeftCorner and UpperRightCorner properties represent the
graphic placement of the viewport on the display. These properties are
defined as follows (using a four-way split as an example):

62 | Chapter 3 Control the AutoCAD

Environment

0,1

1,1

.5,.5

0,0

1,0

In this example:

Viewport 1-LowerLeftCorner = (0, .5), UpperRightCorner = (.5,

1)

Viewport 2-LowerLeftCorner = (.5, .5), UpperRightCorner = (1,

1)

Viewport 3-LowerLeftCorner = (0, 0), UpperRightCorner = (.5, .

5)

Viewport 4-LowerLeftCorner = (.5, 0), UpperRightCorner = (1, .

5)
Split
a viewport, then iterate through the
windows
This example splits a viewport into four windows. It then iterates through all
the viewports in the drawing and displays the viewport name and the lowerleft and upper-right corner for each viewport.
Sub Ch3_IteratingViewportWindows()
' Create a new viewport and make it active
Dim vportObj As AcadViewport
Set vportObj = ThisDrawing.Viewports.Add("TEST_VIEWPORT")
ThisDrawing.ActiveViewport = vportObj
' Split vport into 4 windows
vportObj.Split acViewport4
' Iterate through the viewports,
' highlighting each viewport and displaying
' the upper right and lower left corners
' for each.
Dim vport As AcadViewport
Dim LLCorner As Variant
Dim URCorner As Variant
For Each vport In ThisDrawing.Viewports
ThisDrawing.ActiveViewport = vport
LLCorner = vport.LowerLeftCorner
URCorner = vport.UpperRightCorner
MsgBox "Viewport: " & vport.Name & " is now active." & _
vbCrLf & "Lower left corner: " & _
LLCorner(0) & ", " & LLCorner(1) & vbCrLf & _
"Upper right corner: " & _
URCorner(0) & ", " & URCorner(1)
Next vport
End Sub

Control the Drawing Windows

| 63

Update the Geometry in the Document

Window
Many of the actions you perform through AutoCAD ActiveX Automation
modify what is displayed in the AutoCAD drawing. Not all of these actions
immediately update the display of the drawing. This is designed so you can
make several changes to the drawing without waiting for the display to
update after every single action. Instead, you can bundle your actions
together and make a single call to update the display when you have
finished.
The methods that will update the display are Update and Regen.
The Update method updates the display of a single object only. The Regen
method regenerates the entire drawing and recomputes the screen coordinates and view resolution for all objects. It also reindexes the drawing
database for optimum display and object selection performance.
Update the display of a single object
This example creates a circle and then colors the circle red. It then updates
the circle using the Update method so that the circle is visible in AutoCAD.
Sub Ch3_UpdateDisplay()
Dim circleObj As AcadCircle
Dim center(0 To 2) As Double
Dim radius As Double
center(0) = 1: center(1) = 1: center(2) = 0
radius = 1
' Create the circle and then color it red
Set circleObj = ThisDrawing.ModelSpace.AddCircle(center, radius)
circleObj.Color = acRed
' Update the circle
circleObj.Update
End Sub

Reset Active Objects

Changes to most active objects, such as the active layer and active linetype,
will appear immediately. However, there are several active objects that
must be reset for changes to appear. These objects are the active text style,
the active UCS, and the active viewport. If changes are made to any of
these objects, the object must be reset, and the Regen method must be
called for the changes to appear.

64 | Chapter 3 Control the AutoCAD

Environment

To reset these objects, simply set the ActiveTextStyle, ActiveUCS, or ActiveViewport property, using the updated object.
Reset the active viewport
The following example changes the display of the grid in the active
viewport and then resets the viewport as the active viewport to display the
change.
Sub Ch3_ResetActiveViewport()
' Toggle the setting of the grid display
' for the active viewport
ThisDrawing.ActiveViewport.GridOn = _
Not (ThisDrawing.ActiveViewport.GridOn)
' Reset the active viewport
ThisDrawing.ActiveViewport = ThisDrawing.ActiveViewport
End Sub

Set and Return System Variables

The Document object provides the SetVariable and GetVariable methods for
setting and retrieving AutoCAD system variables. For example, to assign an
integer to the MAXSORT system variable, use the following code:
ThisDrawing.SetVariable "MAXSORT", 100

Draw with Precision

With AutoCAD you can create your drawings with precise geometry
without performing tedious calculations. Often you can specify precise
points with- out knowing the coordinates. Without leaving the drawing
screen, you can perform calculations on your drawing and display various
types of status information.
At this time, AutoCAD ActiveX Automation does not provide a method for
the following AutoCAD capabilities:

Setting object snaps

Specifying measured intervals on objects or dividing objects into
segments

For more information about this topic, see Use Precision Tools in the Users
Guide.

Set and Return System

Variables | 65

Adjust Snap and Grid Alignment

You can use the grid as a visual guideline and turn on Snap mode to
restrict cursor movement. In addition to setting the spacing, you can adjust
the snap and grid alignment. You can rotate the alignment, or you can set it
for use with isometric drawings.
If you need to draw along a specific alignment or angle, you can rotate the
snap angle. The center point of the snap angle rotation is the snap base
point. If you need to align a hatch pattern, you can change this point,
which is nor- mally set to 0,0.
To rotate the snap angle, use the SnapRotationAngle property. To change
the base point of the snap angle rotation, use the SnapBasePoint property.

Note Both properties require a call to the Update method to update the
AutoCAD display.
See Adjust Grid and Grid Snap in the Users Guide for more information on
using and setting snaps and grids.
Change the snap base point and rotation angle
This example changes the snap base point to (1,1) and the snap rotation
angle to 30 degrees. The grid is turned on so that the changes are visible.
Sub Ch3_ChangeSnapBasePoint()
' Turn on the grid for the active viewport
ThisDrawing.ActiveViewport.GridOn = True
' Change the snap base point to 1, 1
Dim newBasePoint(0 To 1) As Double
newBasePoint(0) = 1: newBasePoint(1) = 1
ThisDrawing.ActiveViewport.SnapBasePoint = newBasePoint
' Change the snap rotation angle to 30 degrees (0.575 radians)
Dim rotationAngle As Double
rotationAngle = 0.575
ThisDrawing.ActiveViewport.SnapRotationAngle = rotationAngle
' reset the viewport
ThisDrawing.ActiveViewport = ThisDrawing.ActiveViewport
End Sub

Use Ortho Mode

As you draw lines or move objects, you can use Ortho mode to restrict the
cursor to the horizontal or vertical axis. (The orthogonal alignment
depends

66 | Chapter 3 Control the AutoCAD

Environment

on the current snap angle or UCS.) Ortho mode works with activities that
require you to specify a second point. You can use Ortho not only to
establish vertical or horizontal alignment but also to enforce parallelism or
create reg- ular offsets.
By allowing AutoCAD to impose orthogonal restraints, you can draw more
quickly. For example, you can create a series of perpendicular lines by
turning on Ortho mode before you start drawing. Because the lines are
constrained to the horizontal and vertical axes, you can draw faster,
knowing that the lines are perpendicular.

ortho mode on

ortho mode off

As you move the cursor, a rubber-band line that defines the displacement follows the horizontal or vertical axis, depending on which axis is nearest to the
cursor. AutoCAD ignores Ortho mode in perspective views, or when you
enter coordinates on the command line or specify an object snap.
To turn Ortho mode on or off, use the OrthoOn property. This property
requires a Boolean for input. Set to TRUE to turn Ortho mode on, and to
FALSE to turn Ortho mode off. For example, the following statement turns
Ortho mode on for the active viewport:
ThisDrawing.ActiveViewport.OrthoOn = True

Draw Construction Lines

You can create construction lines that extend to infinity in one or both
direc- tions. Construction lines that extend in one direction are known as
rays. Construction lines that extend in both directions are known as xlines.
These construction lines can be used as a reference for creating other
objects. For example, you can use construction lines to find the center of a
triangle, pre- pare multiple views of the same item, or create temporary
intersections that you can use for object snaps.
For more information about construction lines, see Draw Construction and
Reference Geometry in the Users Guide.

Draw with Precision

67

Create Construction XLines

A construction xline can be placed anywhere in 3D space and extends to
infinity in both directions. To create an xline, use the AddXLine method.
This method specifies the line by the two-point method, you enter or select
two points to define the orientation. The first point, the root, is considered
the midpoint of the construction line.
For more information on creating construction xlines, see Draw Construction and Reference Geometry in the Users Guide.
Add a construction line
The following example code creates an XLine object using the two points
(5, 0, 0) and (1, 1, 0).
Sub Ch3_AddXLine()
Dim xlineObj As AcadXline
Dim basePoint(0 To 2) As Double
Dim directionVec(0 To 2) As Double
' Define the xline
basePoint(0) = 2#: basePoint(1) = 2#: basePoint(2) = 0#
directionVec(0) = 1#: directionVec(1) = 1#: directionVec(2) =
0#
' Create the xline in model space
Set xlineObj = ThisDrawing.ModelSpace.AddXLine _
(basePoint, directionVec)
ThisDrawing.Application.ZoomAll
End Sub

Query Construction XLines

Once created, you can query the first point of a constuction xline using the
BasePoint property. The second point used to create the xline is not stored
with the object. Instead, use the DirectionVector property to obtain the directional vector for the xline.
Query a construction line
This example finds the base point and directional vector for the xline created
in Add a construction line.
Dim BPoint As Variant
Dim Vector As Variant
BPoint = xlineObj.basePoint
Vector = xlineObj.DirectionVector

68 | Chapter 3 Control the AutoCAD

Environment

Create Rays
A ray is a line in 3D space that starts at a point you specify and extends to
infinity. Unlike xline construction lines, which extend in two directions,
rays extend in only one direction. As a result, rays help reduce the visual
clutter caused by numerous construction lines.
Like construction lines, rays are ignored by commands that display the drawing extents.
For more information on rays, see Draw Construction Lines (and Rays) in
the Users Guide.

Query Rays
Once created, you can query the first point of a ray using the BasePoint property. The second point used to create the ray is not stored with the object.
Instead, use the DirectionVector property to obtain the directional vector for
the ray.
Add, query, and edit a Ray object
The following example code creates a Ray object using the two points
(5, 0, 0) and (1, 1, 0). It then queries the current base point and direction
vector and displays the results in a message box. The direction vector is then
changed and the base point and new direction vector are queried and
displayed.

Draw with Precision

69

Sub Ch3_EditRay()
Dim rayObj As AcadRay
Dim basePoint(0 To 2) As Double
Dim secondPoint(0 To 2) As Double
' Define the ray
basePoint(0) = 3#: basePoint(1) = 3#: basePoint(2) = 0#
secondPoint(0) = 4#: secondPoint(1) = 4#: secondPoint(2) = 0#
' Creates a Ray object in model space
Set rayObj = ThisDrawing.ModelSpace.AddRay _
(basePoint, secondPoint)
ThisDrawing.Application.ZoomAll
' Find the current status of the Ray
MsgBox "The base point of the ray is: " & _
rayObj.basePoint(0) & ", " & _
rayObj.basePoint(1) & ", " & _
rayObj.basePoint(2) & vbCrLf & _
"The directional vector for the ray is: " & _
rayObj.DirectionVector(0) & ", " & _
rayObj.DirectionVector(1) & ", " & _
rayObj.DirectionVector(2), , "Edit Ray"
' Change the directional vector for the ray
Dim newVector(0 To 2) As Double
newVector(0) = -1
newVector(1) = 1
newVector(2) = 0
rayObj.DirectionVector = newVector
ThisDrawing.Regen False
MsgBox "The base point of the ray is: " & _
rayObj.basePoint(0) & ", " & _
rayObj.basePoint(1) & ", " & _
rayObj.basePoint(2) & vbCrLf & _
"The directional vector for the ray is: " & _
rayObj.DirectionVector(0) & ", " & _
rayObj.DirectionVector(1) & ", " & _
rayObj.DirectionVector(2), , "Edit Ray"
End Sub

Calculate
Values

Points

and

By using the methods provided by the Utility object, you can quickly solve
a mathematical problem or locate points on your drawing. By using
methods on the Utility object, you can do the following:
Find the angle of a line from the X axis with the AngleFromXAxis
method
Convert an angle as a string to a real (double) value with the
AngleToReal method

70 | Chapter 3 Control the AutoCAD

Environment

Convert an angle from a real (double) value to a string with the

AngleToString method
Convert a distance from a string to a real (double) value with the
DistanceToReal method
Create a variant that contains an array of integers, floating
numbers, doubles, and so forth, with the CreateTypedArray method
Find the point at a specified angle and distance from a given point
with the PolarPoint method
Translate a point from one coordinate system to another
coordinate system with the TranslateCoordinates method
Find the distance between two points entered by the user with the
GetDistance method

Find the distance between two points with the GetDistance method
This example uses the GetDistance method to obtain the point coordinates,
and the MsgBox function to display the calculated distance.
Sub Ch3_GetDistanceBetweenTwoPoints()
Dim returnDist As Double
' Return the value entered by user. A prompt is provided.
returnDist = ThisDrawing.Utility.GetDistance _
(, "Pick two points.")
MsgBox "The distance between the two points is: " & returnDist
End Sub

Calculate Areas
You can find the area of an arc, circle, ellipse, lightweight polyline,
polyline, region, or planar-closed spline by using the Area property.
If you need to calculate the combined area of more than one object, you can
keep a running total as you add or use the Boolean method on a series of
regions to obtain a single region representing the desired area. From this single region you can use the Area property to obtain its area.
The calculated area differs according to the type of object you query. For an
explanation of how area is calculated for each object type, see Obtain Area
Information in the Users Guide.

Calculate a Defined Area

You can measure an arbitrary closed region defined by the 2D or 3D points
specified by the user. The points must be coplanar.

Draw with Precision

71

To obtain the area specified by points from the user

1 Use the GetPoint method in a loop to obtain the points from the
user.
2 Create a lightweight polyline from the points provided by the user. Use
the AddLightweightPolyline method to create the polyline.
3 Use the Area property to obtain the area of the newly created polyline.
4 Erase the polyline using the Erase method.
Calculate the area defined by points entered from the
user
This example prompts the user to enter five points. A polyline is then
created out of the points entered. The polyline is closed, and the area of the
polyline is displayed in a message box.
Sub Ch3_CalculateDefinedArea()
Dim p1 As Variant
Dim p2 As Variant
Dim p3 As Variant
Dim p4 As Variant
Dim p5 As Variant
' Get the points from the user
p1 = ThisDrawing.Utility.GetPoint(, vbCrLf & "First point: ")
p2 = ThisDrawing.Utility.GetPoint(p1, vbCrLf & "Second point:
")
p3 = ThisDrawing.Utility.GetPoint(p2, vbCrLf & "Third point:
")
p4 = ThisDrawing.Utility.GetPoint(p3, vbCrLf & "Fourth point:
")
p5 = ThisDrawing.Utility.GetPoint(p4, vbCrLf & "Fifth point:
")
' Create the 2D polyline from the points
Dim polyObj As AcadLWPolyline
Dim vertices(0 To 9) As Double
vertices(0) = p1(0): vertices(1) = p1(1)
vertices(2) = p2(0): vertices(3) = p2(1)
vertices(4) = p3(0): vertices(5) = p3(1)
vertices(6) = p4(0): vertices(7) = p4(1)
vertices(8) = p5(0): vertices(9) = p5(1)
Set polyObj = ThisDrawing.ModelSpace.AddLightWeightPolyline _
(vertices)
polyObj.Closed = True
ThisDrawing.Application.ZoomAll
' Display the area for the polyline
MsgBox "The area defined by the points is " & _
polyObj.Area, , "Calculate Defined Area"
End Sub

72 | Chapter 3 Control the AutoCAD

Environment

Prompt for User Input

The Utility object, which is a child of the Document object, defines the user
input methods. The user input methods display a prompt on the AutoCAD
command line and request input of various types. This type of user input is
most useful for interactive input of screen coordinates, entity selection,
and short-string or numeric values. If your application requires the input of
numerous options or values, a dialog box may be more appropriate than
individual prompts.
Each user input method displays a prompt on the AutoCAD command line
and returns a value specific to the type of input requested. For example,
GetString returns a string, GetPoint returns a variant (which contains a
three- element array of doubles), and GetInteger returns an integer value.
You can further control the input from the user with the InitializeUserInput
method. This method lets you control things such as NULL input (pressing
ENTER ), input of zero or negative numbers, and input of arbitrary text
values.
To force the prompt to display on a line by itself, use the carriage
return/line- feed constant (vbCrLf) at the beginning of your prompt
strings.

GetString Method
The GetString method prompts the user for input of a string at the
AutoCAD Command prompt. This method accepts two parameters. The first
parameter controls the input of spaces in the input string. If it is set to 0,
spaces are not allowed ( SPACEBAR terminates the input); if set to 1, the
string can contain spaces ( ENTER must be used to terminate the input). The
second parameter is the prompt string.
Get a string value from the user at the AutoCAD command line
The following example displays the Enter Your Name prompt, and requires
that the input from the user be terminated by pressing ENTER (spaces are
allowed in the input string). The string value is stored in the retVal
variable and is displayed using a message box.
Sub Ch3_GetStringFromUser()
Dim retVal As String
retVal = ThisDrawing.Utility.GetString _
(1, vbCrLf & "Enter your name: ")
MsgBox "The name entered was: " & retVal
End Sub

The GetString method does not honor a prior call to the

InitializeUserInput method.

Prompt for User Input

73

GetPoint Method
The GetPoint method prompts the user for the specification of a point at the
AutoCAD Command prompt. This method accepts two parameters, an
optional from point and the prompt string. If the from point is provided,
AutoCAD draws a rubber-band line from that point. To control the user
input, this method can be preceded by a call to the InitializeUserInput
method.
Get a point selected by the user
The following example prompts the user for two points, then draws a line
using those points as the start point and endpoint.
Sub Ch3_GetPointsFromUser()
Dim startPnt As Variant
Dim endPnt As Variant
Dim prompt1 As String
Dim prompt2 As String
prompt1 = vbCrLf & "Enter the start point of the line: "
prompt2 = vbCrLf & "Enter the end point of the line: "
' Get the first point without entering a base point
startPnt = ThisDrawing.Utility.GetPoint(, prompt1)
' Use the point entered above as the base point
endPnt = ThisDrawing.Utility.GetPoint(startPnt, prompt2)
' Create a line using the two points entered
ThisDrawing.ModelSpace.AddLine startPnt, endPnt
ThisDrawing.Application.ZoomAll
End Sub

GetKeyword Method
The GetKeyword method prompts the user for input of a keyword at the
AutoCAD Command prompt. This method accepts only one parameter,
which is the prompt string. The keywords and input parameters are defined
with a call to the InitializeUserInput method.
Get a keyword from the user at the AutoCAD command line
The following example forces the user to enter a keyword by setting the first
parameter of InitializeUserInput to 1, which disallows NULL input (pressing
ENTER ). The second parameter establishes the list of valid keywords.

74 | Chapter 3 Control the AutoCAD

Environment

Sub Ch3_KeyWord()
Dim keyWord As String
ThisDrawing.Utility.InitializeUserInput 1, "Line Circle Arc"
keyWord = ThisDrawing.Utility.GetKeyword _
(vbCrLf & "Enter an option (Line/Circle/Arc): ")
MsgBox keyWord, , "GetKeyword Example"
End Sub

A more user-friendly keyword prompt is one that provides a default value

if the user presses ENTER (NULL input). Notice the minor modifications to
the following example:
Sub Ch3_KeyWord2()
Dim keyWord As String
ThisDrawing.Utility.InitializeUserInput 0, "Line Circle Arc"
keyWord = ThisDrawing.Utility.GetKeyword _
(vbCrLf & "Enter an option (Line/Circle/<Arc>): ")
If keyWord = "" Then keyWord = "Arc"
MsgBox keyWord, , "GetKeyword Example"
End Sub

Control User Input

You can use the InitializeUserInput method to define keywords or restrict the
type of input to the user input method. The use and parameter values are
similar to the AutoLISP initget function. InitializeUserInput can be used
with the following methods: GetAngle, GetCorner, GetDistance, GetInteger,
GetKeyword, GetOrientation, GetPoint, and GetReal. InitializeUserInput
cannot be used with the GetString method. Use the GetInput method to
retrieve the string value (keyword or arbitrary input) when the user input
method does not return a string value.
The InitializeUserInput method accepts two parameters. The first
parameter is a bit-coded integer value that determines the input options for
the user input method. The second parameter is a string that defines the
valid keywords.
Get an integer value or a keyword from the user at the AutoCAD
command line
The following example prompts the user for a positive, non-negative integer
value or a keyword:

Prompt for User Input

75

Sub Ch3_UserInput()
' The first parameter of InitializeUserInput (6)
' restricts input to positive and non-negative
' values. The second parameter is the list of
' valid keywords.
ThisDrawing.Utility.InitializeUserInput 6, "Big Small Regular"
' Set the prompt string variable
Dim promptStr As String
promptStr = vbCrLf & "Enter the size or (Big/Small/<Regular>):"
' At the GetInteger prompt, entering a keyword or pressing
' ENTER without entering a value results in an error. To allow
' your application to continue and check for the error
' description, you must set the error handler to resume on
error.
On Error Resume Next
' Get the value entered by the user
Dim returnInteger As Integer
returnInteger = ThisDrawing.Utility.GetInteger(promptStr)
' Check for an error. If the error number matches the
' one shown below, then use GetInput to get the returned
' string; otherwise, use the value of returnInteger.
If Err.Number = -2145320928 Then
Dim returnString As String
Debug.Print Err.Description
returnString = ThisDrawing.Utility.GetInput()
If returnString = "" Then
'ENTER returns null string
returnString = "Regular"
'Set to default
End If
Err.Clear
Else
'Otherwise,
returnString = returnInteger
'Use the value entered
End If
' Display the result
MsgBox returnString, , "InitializeUserInput Example"
End Sub

Access the AutoCAD Command

Line
You can send commands directly to the AutoCAD command line by using
the SendCommand method. The SendCommand method sends a single
string to the command line. The string must contain the arguments to the
command listed in the order expected by the prompt sequence of the
executed command. A blank space or the ASCII equivalent of a carriage
return in the string is equivalent to pressing ENTER on the keyboard. Unlike

76 | Chapter 3 Control the AutoCAD

Environment

the AutoLISP environment, invoking the SendCommand method with no

argument is invalid.
Send a command to the AutoCAD command line
The following example creates a circle with a center of (2, 2, 0) and a radius
of 4. The drawing is then zoomed to all the geometry in the drawing.
Notice that there is a space at the end of the string which represents the
final ENTER to begin execution of the command.
Sub Ch3_SendACommandToAutoCAD()
ThisDrawing.SendCommand "_Circle 2,2,0 4 "
ThisDrawing.SendCommand "_zoom a "
End Sub

Work with No Documents

Open
AutoCAD always starts up with a new or existing document open. It is possible, however, to close all documents during the current session.
If you close all the documents in the AutoCAD user interface, you will notice
a few changes to the application window. The available menus are reduced
to simply the File, View, Window, and Help menus. These menus also have
reduced available options on them. You will also notice that there is no
com- mand line.
Similarly, the ActiveX interface only allows the following actions when no
documents are open:

You
You
You
You

can
can
can
can

open a document.
create a new document.
import a document.
exit out of AutoCAD.

These actions are all available from the Documents collection. The methods
and properties of the Documents collection, in addition to a limited set of
methods and properties of the Application object, are the only valid
interface available when there are no documents open. If you perform any
other action, such as attempting to access user options, your actions will
result in an error.
Use the Count property on the Documents collection to determine if
AutoCAD is in a zero document state. If Documents.Count = 0, then
AutoCAD is in a zero document state. If Documents.Count > 0, then there
is at least one drawing open.

Work with No Documents Open

| 77

It is also important to note that in VBA the ThisDrawing object is not

defined when AutoCAD is in a zero document state. This makes sense since
ThisDrawing normally refers to the active drawing and in the zero
document state there are no drawings open. Attempting to execute a
macro that uses ThisDrawing will result in a runtime error. To avoid the
error, use the VBA GetObject function, and specify the AutoCAD version,
to obtain a connec- tion to AutoCAD when there are no documents open.

Import Other File Formats

You can use drawings or images from other applications by opening them in
specific formats. AutoCAD handles some form of conversion for DXF, SAT,
and WMF files. For all versions, you can import the file by using the Import
method. This method takes three values as input: the name of the file to
import, the insertion point in the drawing to place the file, and the scale
factor to use when placing the imported drawing.

Export to Other File Formats

If you need to use an AutoCAD drawing in another application, you can convert it to a specific format by using the Export method. This method exports
the AutoCAD drawing to a WMF, SAT, EPS, DXF, or BMP format. The
Export method takes three values as input: the name for the new file to be
created, the extension for the new file, and the selection set of objects to
export.
When exporting to WMF, SAT, or BMP formats, you must provide a nonempty selection set. This selection set specifies the objects from the
drawing to export. If no selection set is specified, nothing is exported and a
trappable invalid argument error results.
When exporting to EPS and DXF formats, Export ignores the selection set
argument, but it is still required. The entire drawing is automatically
exported for these formats.
Export a drawing as a DXF file and import it again
This example creates a circle in the current drawing. It then exports the drawing to a file called DXFExprt.DXF, opens a new drawing, and imports the file.
Note that an empty selection set is provided as an argument to Export. The
Export method ignores selection set information when exporting a DXF file,
but a syntax error results if the argument is omitted.

78 | Chapter 3 Control the AutoCAD

Environment

Sub Ch3_ImportingAndExporting()
' Create the circle for visual representation
Dim circleObj As AcadCircle
Dim centerPt(0 To 2) As Double
Dim radius As Double
centerPt(0) = 2: centerPt(1) = 2: centerPt(2) = 0
radius = 1
Set circleObj = ThisDrawing.ModelSpace.AddCircle _
(centerPt, radius)
ThisDrawing.Application.ZoomAll
' Create an empty selection set
Dim sset As AcadSelectionSet
Set sset = ThisDrawing.SelectionSets.Add("NEWSSET")
'Export the current drawing to a DXF file in the
' AutoCAD temporary file directory
Dim tempPath As String
Dim exportFile As String
Const dxfname As String = "DXFExprt"
tempPath = _
ThisDrawing.Application.preferences.Files.TempFilePath
exportFile = tempPath & dxfname
ThisDrawing.Export exportFile, "DXF", sset
' Delete the empty selection set
ThisDrawing.SelectionSets.Item("NEWSSET").Delete
' Open a new drawing
ThisDrawing.Application.Documents.Add "acad.dwt"
' Define the import
Dim importFile As String
Dim insertPoint(0 To 2) As Double
Dim scalefactor As Double
importFile = tempPath & dxfname & ".dxf"
insertPoint(0) = 0: insertPoint(1) = 0: insertPoint(2) = 0
scalefactor = 2#
' Import the file
ThisDrawing.Import importFile, insertPoint, scalefactor
ThisDrawing.Application.ZoomAll
End Sub

Export to Other File Formats

| 79

80

Create and Edit

AutoCAD Entities

You can create a range of objects, from simple lines and

In this chapter

circles to spline curves, ellipses, and associative hatch

Create Objects

areas. In general, you add objects to model space using

one of the Add methods. You can also create objects in
paper space, or in a block.
Once an object is created, you can change the layer,
color, and linetype of the object. You can also add text

Work with Selection Sets

Edit Objects
Use Layers, Colors, and

Linetyp
es
Save and Restore Layer

Settings
Add Text to Drawings

to annotate your drawing.

81

Create Objects
While there are often several different ways to create the same graphical
object in AutoCAD, ActiveX Automation offers only one creation method
per object. For example, in AutoCAD there are four different ways you can
create a circle: (1) by specifying the center and radius, (2) by two points
defin- ing the diameter, (3) by three points defining the circumference, or
(4) by two tangents and a radius. However, in ActiveX Automation there is
only one creation method provided to create a circle, and that method uses
the center and radius.

Note The VB and VBA methods of creating objects using either CreateObject
or Dim with the New keyword can only be used to create the AutoCAD Application object. All other AutoCAD objects must be created using the Add or
Add<objectname> methods provided in the AutoCAD interface.

Determine the Container Object

Graphical objects are created in either the ModelSpace collection,
PaperSpace collection, or a Block object.
The ModelSpace collection is returned by the ModelSpace property and the
PaperSpace collection by the PaperSpace property.
You can reference these objects directly, or through a user-defined variable.
To reference the objects directly, include the object in the calling hierarchy.
For example, the following statement adds a line to the model space:
Set lineObj = ThisDrawing.ModelSpace.AddLine(startPoint,endPoint)

To reference the objects through a user-defined variable, define the variable

as type AcadModelSpace or AcadPaperSpace, and then set the variable to the
appropriate property of the active document. The following example
defines two variables and sets them equal to the current model space and
paper space, respectively:
Dim
Dim
Set
Set

moSpace
paSpace
moSpace
paSpace

As AcadModelSpace
As AcadPaperSpace
= ThisDrawing.ModelSpace
= ThisDrawing.PaperSpace

The following statement adds a line to the model space using the userdefined variable:
Set lineObj = moSpace.AddLine(startPoint,endPoint)

82 | Chapter 4 Create and Edit AutoCAD

Entities

Create Lines
The line is the most basic object in AutoCAD. You can create a variety of
linessingle lines, and multiple line segments with and without arcs. In
general, you draw lines by specifying coordinate points. The default
linetype is CONTINUOUS, an unbroken line, but various linetypes are
available that use dots and dashes.
To create a line, use one of the following methods:
AddLine

Creates a line passing through two points.

AddLightweightPolyline
Creates a 2D lightweight polyline from a list of vertices.
AddMLine

Creates a multiline.

AddPolyline

Creates a 2D or 3D polyline.

Standard lines and multilines are created on the XY plane of the WCS.
Polylines and Lightweight Polylines are created in the Object Coordinate
Sys- tem (OCS). For information about converting OCS coordinates, see
Convert Coordinates on page 245.
Create a Polyline object
This example uses the AddLightweightPolyline method to create a simple
two-segment polyline using the 2D coordinates (2,4), (4,2), and (6,4).
Sub Ch4_AddLightWeightPolyline()
Dim plineObj As AcadLWPolyline
Dim points(0 To 5) As Double
' Define the 2D polyline
points(0) = 2: points(1)
points(2) = 4: points(3)
points(4) = 6: points(5)

points
= 4
= 2
= 4

' Create a light weight Polyline object in model space

Set plineObj = ThisDrawing.ModelSpace. _
AddLightWeightPolyline(points)
ThisDrawing.Application.ZoomAll
End Sub

Create Curved Objects

You can create a variety of curved objects with AutoCAD, including spline
curves, circles, arcs, and ellipses. All curves are created on the XY plane of the
current WCS.

Create Objects
83

To create a curve, use one of the following methods:

AddArc

Creates an arc given the center, radius, start and end

angles.

AddCircle

Creates a circle given the center point and radius.

AddEllipse

Creates an ellipse given the center point, a point on the

major axis, and the radius ratio.

AddSpline

Creates a quadratic or cubic NURBS (nonuniform

rational B-spline) curve.

Create a Spline object

This example creates a spline in model space using three points (0, 0, 0),
(5, 5, 0), and (10, 0, 0). The spline has start and end tangents of (0.5, 0.5,
0.0).
Sub Ch4_CreateSpline()
' This example creates a spline object in model space.
' Declare the variables needed
Dim splineObj As AcadSpline
Dim startTan(0 To 2) As Double
Dim endTan(0 To 2) As Double
Dim fitPoints(0 To 8) As Double
' Define the variables
startTan(0) = 0.5: startTan(1) = 0.5: startTan(2) = 0
endTan(0) = 0.5: endTan(1) = 0.5: endTan(2) = 0
fitPoints(0) = 1: fitPoints(1) = 1: fitPoints(2) = 0
fitPoints(3) = 5: fitPoints(4) = 5: fitPoints(5) = 0
fitPoints(6) = 10: fitPoints(7) = 0: fitPoints(8) = 0
' Create the spline
Set splineObj = ThisDrawing.ModelSpace.AddSpline _
(fitPoints, startTan, endTan)
ZoomAll
End Sub

For more information about splines, see the Spline object and AddSpline
method documentation in the AutoCAD ActiveX and VBA Reference.

Create Point Objects

Point objects can be useful, for example, as node or reference points that
you can snap to and offset objects from. You can set the style of the point
and its size relative to the screen or in absolute units.
The PDMODE and PDSIZE system variables control the appearance of Point
objects. The PDMODE values 0, 2, 3, and 4 specify a figure to draw through
the point. A value of 1 selects nothing to be displayed.

84 | Chapter 4 Create and Edit AutoCAD

Entities

Adding 32, 64, or 96 to the previous value selects a shape to draw around the
point in addition to the figure drawn through it:

32

33

34

35

36

64

65

66

67

68

96

97

98

99

100

PDSIZE controls the size of the point figures, except for PDMODE values 0 and

1. A 0 setting generates the point at 5 percent of the graphics area height. A

positive PDSIZE value specifies an absolute size for the point figures. A negative value is interpreted as a percentage of the viewport size. The size of all
points is recalculated when the drawing is regenerated.
After you change PDMODE and PDSIZE, the appearance of existing points
changes the next time the drawing is regenerated.
To set PDMODE and PDSIZE, use the SetVariable method.
Create a Point object and change its appearance
The following code example creates a Point object in model space at the coordinate (5, 5, 0). The PDMODE and PDSIZE system variables are then updated.
Sub Ch4_CreatePoint()
Dim pointObj As AcadPoint
Dim location(0 To 2) As Double
' Define the location of the point
location(0) = 5#: location(1) = 5#: location(2) = 0#
' Create the point
Set pointObj = ThisDrawing.ModelSpace.AddPoint(location)
ThisDrawing.SetVariable "PDMODE", 34
ThisDrawing.SetVariable "PDSIZE", 1
ZoomAll
End Sub

Create Objects
85

Create Solid-Filled Areas

You can create triangular and quadrilateral areas filled with a color. For
quicker results, create these areas with the FILLMODE system variable off,
then turn FILLMODE on to fill the finished area.
When you create a quadrilateral solid-filled area, the sequence of the third
and fourth points determines its shape. Compare the following illustrations:
1

The first two points define one edge of the polygon. The third point is
defined diagonally opposite from the second. If the fourth point is set equal
to the third point, then a filled triangle is created.
To create a solid-filled area, use the AddSolid method.
For more information about filling solids, see Create Solid-Filled Areas in
the Users Guide.
Create a solid-filled object
The following code example creates a quadrilateral solid in model space
using the coordinates (0, 0, 0), (5, 0, 0), (5, 8, 0), and (0, 8, 0).
Sub Ch4_CreateSolid()
Dim solidObj As AcadSolid
Dim point1(0 To 2) As Double
Dim point2(0 To 2) As Double
Dim point3(0 To 2) As Double
Dim point4(0 To 2) As Double
' Define the solid
point1(0) = 0#: point1(1) = 0#: point1(2) = 0#
point2(0) = 5#: point2(1) = 0#: point2(2) = 0#
point3(0) = 5#: point3(1) = 8#: point3(2) = 0#
point4(0) = 0#: point4(1) = 8#: point4(2) = 0#
' Create the solid object in model space
Set solidObj = ThisDrawing.ModelSpace.AddSolid _
(point1, point2, point3, point4)
ZoomAll
End Sub

Work with Regions

Regions are two-dimensional enclosed areas you create from closed shapes
called loops. A loop is a curve or a sequence of connected curves that defines
an area on a plane with a boundary that does not intersect itself. Loops can
be combinations of lines, lightweight polylines, circles, arcs, ellipses, elliptical arcs, splines, 3D faces, traces, and solids. The objects that make up the
loops must either be closed or form closed areas by sharing endpoints with
other objects. They must also be coplanar (on the same plane). The loops
that make up a region must be defined as an array of objects.
For more information about working with regions, see Create and
Combine Areas (Regions) in chapter 16, Draw Geometric Objects, in the
Users Guide.

Create Regions
To create a region, use the AddRegion method. This method will create a
region out of every closed loop formed by the input array of curves.
AutoCAD converts closed 2D and planar 3D polylines to separate regions,
then con- verts polylines, lines, and curves that form closed planar loops. If
more than two curves share an endpoint, the resulting region might be
arbitrary. Because of this, several regions may actually be created when
using the AddRegion method. Use a variant to hold the newly created array
of regions.
To calculate the total number of Region objects created, use the UBound and
LBound Visual Basic functions, as in the following example:
UBound(objRegions) - LBound(objRegions) + 1

where objRegions is a variant containing the return value from

AddRegion. This statement will calculate the total number of regions
created.
Create a simple region
The following code example creates a region from a single circle.

Sub Ch4_CreateRegion()
' Define an array to hold the
' boundaries of the region.
Dim curves(0 To 0) As AcadCircle
' Create a circle to become a
' boundary for the region.
Dim center(0 To 2) As Double
Dim radius As Double
center(0) = 2
center(1) = 2
center(2) = 0
radius = 5#
Set curves(0) = ThisDrawing.ModelSpace.AddCircle _
(center, radius)
' Create the region
Dim regionObj As Variant
regionObj = ThisDrawing.ModelSpace.AddRegion(curves)
ZoomAll
End Sub

Create Composite Regions

You can create composite regions by subtracting, combining, or finding the
intersection of regions or 3D solids. You can then extrude or revolve
compos- ite regions to create complex solids. To create a composite region,
use the Boolean method.
When you subtract one region from another, you call the Boolean method
from the first region. This is the region from which you want to subtract.
For example, to calculate how much carpeting is needed for a floorplan, call
the Boolean method from the outer boundary of the floor space and use the
uncarpeted areas, such as pillars and counters, as the object in the Boolean
parameter list.

Create a composite region

Sub Ch4_CreateCompositeRegions()
' Create two circles, one representing a room,
' the other a pillar in the center of the room
Dim RoomObjects(0 To 1) As AcadCircle
Dim center(0 To 2) As Double
Dim radius As Double
center(0) = 4
center(1) = 4
center(2) = 0
radius = 2#
Set RoomObjects(0) = ThisDrawing.ModelSpace. _
AddCircle(center, radius)
radius = 1#
Set RoomObjects(1) = ThisDrawing.ModelSpace. _
AddCircle(center, radius)
' Create a region from the two circles
Dim regions As Variant
regions = ThisDrawing.ModelSpace.AddRegion(RoomObjects)
' Copy the regions into the region variables for ease of use
Dim RoundRoomObj As AcadRegion
Dim PillarObj As AcadRegion
If regions(0).Area > regions(1).Area Then
' The first region is the room
Set RoundRoomObj = regions(0)
Set PillarObj = regions(1)
Else
' The first region is the pillar
Set PillarObj = regions(0)
Set RoundRoomObj = regions(1)
End If
' Subtract the pillar space from the floor space to
' get a region that represents the total carpet area.
RoundRoomObj.Boolean acSubtraction, PillarObj
' Use the Area property to determine the total carpet area
MsgBox "The carpet area is: " & RoundRoomObj.Area
End Sub

Find the area of the resulting region with the Area property.

Unite Regions
To unite regions, call the Boolean method and enter the constant acUnion
for the operation instead of acSubtraction. You can combine regions in
any order to unite them.

Find the Intersection of Two Regions

To find the intersection of two regions, use the constant acIntersection.
You can combine regions in any order to intersect them.

Create Hatches
Hatching fills a specified area in a drawing with a pattern.
When creating a hatch, you do not initially specify the area to be filled.
First you must create the Hatch object. Once this is done, you can specify
the outer loop, which is the outermost boundary for the hatch. You can
then continue to specify any inner loops that may exist in the hatch.
For more information about working with hatches, see Overview of Hatch
Patterns and Fills in chapter 18, Hatches, Fills, and Wipeouts, in the
Users Guide.

Create the Hatch Object

When creating the Hatch object, you specify the hatch pattern type, the
hatch pattern name, and the associativity. Once the Hatch object has been
created, you will not be able to change the hatch associativity.
To create a Hatch object, use the AddHatch method.

Associate a Hatch
You can create associative or nonassociative hatches. Associative hatches
are linked to their boundaries and updated when the boundaries are
modified. Nonassociative hatches are independent of their boundaries.
Associativity can only be set when a hatch is created. Once a hatch has been
created, you can unassociate it, but you cannot associate it again.
To make a hatch associative, set the Associativity parameter of the
AddHatch method to TRUE. To make a hatch nonassociative, set the
Associativity parameter of the AddHatch method to FALSE.

Assign the Hatch Pattern Type and Name

AutoCAD supplies a solid-fill and more than fifty industry-standard hatch
patterns. Hatch patterns highlight a particular feature or area of a drawing.
For example, patterns can help differentiate the components of a 3D object
or represent the materials that make up an object.
You can use a pattern supplied with AutoCAD or one from an external pattern library. For a table of the hatch patterns supplied with AutoCAD, see the
AutoCAD Command Reference.

To specify a unique pattern, you must enter both a pattern type and a
pattern name when creating the Hatch object. The pattern type specifies
where to look up the pattern name. When entering the pattern type, use
one of the following constants:
acHatchPatternTypePredefined
Selects the pattern name from those defined in the
acad.pat file
acHatchPatternTypeUserDefined
Defines a pattern of lines using the current linetype
acHatchPatternTypeCustomDefined
Selects the pattern name from a PAT other than the
acad.pat file
When entering the pattern name, use a name that is valid for the file specified by the pattern type.

Define the Hatch Boundaries

Once the Hatch object is created, the hatch boundaries can be added.
Bound- aries can be any combination of lines, arcs, circles, 2D polylines,
ellipses, splines, and regions.
The first boundary added must be the outer boundary, which defines the
outer most limits to be filled by the hatch. To add the outer boundary, use
the AppendOuterLoop method.
Once the outer boundary is defined, you can continue adding inner boundaries. Add inner boundaries with the AppendInnerLoop method.
Inner boundaries define islands within the hatch. How these islands are
han- dled by the Hatch object depends on the setting of the HatchStyle
property. The HatchStyle property can be set to one of the following
conditions:
Hatch style definitions
HatchStyle

Condition

Description

Normal

Specifies standard style, or normal. This option

hatches inward from the outermost area
boundary. If AutoCAD encounters an internal
boundary, it turns off hatching until it encounters
another boundary. This is the default setting for
the HatchStyle property.

Hatch style definitions (continued)

HatchStyle

Condition

Description

Outer

Fills the outermost areas only. This style also

hatches inward from the area boundary, but it
turns off hatching if it encounters an internal
boundary and does not turn it back on again.

Ignore

Ignores internal structure. This option hatches

through all internal objects.

When you have finished defining the hatch it must be evaluated before it
can be displayed. Use the Evaluate method to do this.
Create a Hatch object
This example creates an associate hatch in model space. Once the hatch has
been created, you can change the size of the circle that the hatch is
associated with. The hatch will change to match the current circle size.

Sub Ch4_CreateHatch()
Dim hatchObj As AcadHatch
Dim patternName As String
Dim PatternType As Long
Dim bAssociativity As Boolean
' Define the hatch
patternName = "ANSI31"
PatternType = 0
bAssociativity = True
' Create the associative Hatch object
Set hatchObj = ThisDrawing.ModelSpace.AddHatch _
(PatternType, patternName, bAssociativity)
' Create the outer boundary for the hatch. (a circle)
Dim outerLoop(0 To 0) As AcadEntity
Dim center(0 To 2) As Double
Dim radius As Double
center(0) = 3: center(1) = 3: center(2) = 0
radius = 1
Set outerLoop(0) = ThisDrawing.ModelSpace. _
AddCircle(center, radius)
' Append the outerboundary to the hatch
' object, and display the hatch
hatchObj.AppendOuterLoop (outerLoop)
hatchObj.Evaluate
ThisDrawing.Regen True
End Sub

Work with Selection

Sets
A selection set is a group of AutoCAD objects specified for processing as a
single unit. A selection set can consist of a single object, or it can be a more
complex grouping: for example, the set of objects of a certain layer.
Defining a selection set is a two-step process. First, you must create a new
selection set and add it to the SelectionSets collection. Once created, you
then populate the selection set with the objects you want to process.

Work with Selection Sets

93

Create a Selection
Set
To create a named selection set, use the Add method. This method requires
only a single parameterthe name of the selection set.
If a selection set of the same name already exists, AutoCAD returns an error
message. It is a good programming practice to delete a selection set when
you no longer need it. Use the Delete method to delete a selection set, as in
the following example:
ThisDrawing.SelectionSets.Item("NewSelectionSet").Delete

Create an empty selection set

This example creates a new selection set.
Sub Ch4_CreateSelectionSet()
Dim selectionSet1 As AcadSelectionSet
Set selectionSet1 = ThisDrawing.SelectionSets. _
Add("NewSelectionSet")
End Sub

Add Objects to a Selection Set

You can add objects to the active selection set by using any of the following
methods:
AddItems

Adds one or more objects to the specified selection set.

Select

Selects objects and places them into the active

selection set. You can select all objects, objects within
and crossing a rectangular area, objects within and
crossing a polygon area, all objects crossing a fence,
the most recently created object, the objects in the
most recent selection set, objects within a window, or
objects within a window polygon.

SelectAtPoint

Selects objects passing through a given point and places

them into the active selection set.

SelectByPolygon

Selects objects within a fence and adds them to the

active selection set.

SelectOnScreen

Prompts the user to pick objects from the screen and

adds them into the active selection set.

Add selected objects to a selection set

This example prompts the user to select objects, then adds those objects to
the selection set.

94 | Chapter 4 Create and Edit AutoCAD

Entities

Sub Ch4_AddToASelectionSet()
' Create a new selection set
Dim sset As AcadSelectionSet
Set sset = ThisDrawing.SelectionSets.Add("SS1")
' Prompt the user to select objects
' and add them to the selection set.
' To finish selecting, press ENTER.
sset.SelectOnScreen
End Sub

Define Rules for Selection Sets

You can limit selection sets by property or by object type using filter lists.
For example, you can copy only the blue objects in a circuit board drawing,
or only objects on a certain layer. You can also combine selection criteria in
your filter list. For example, you can tell AutoCAD to include an object in a
selection set only if it is a blue circle on a specific layer. Filter lists can be specified for the Select, SelectAtPoint, SelectByPolygon, and SelectOnScreen
methods.

Note Filtering recognizes only linetypes explicitly assigned to objects,

not those inherited by the layer.

Use Filter Lists to Define Selection Set Rules

Filter lists are composed of pairs of arguments. The first argument identifies
the type of filter (for example, an object), and the second argument specifies
the value you are filtering on (for example, circles). The filter type is a DXF
group code that specifies which filter to use. A few of the most common
filter types are listed here.
DXF codes for common filters
DXF code

Filter type

Object Type (String)

Such as Line, Circle, Arc, and so forth.

Object Name (String)

The table (given) name of a named object.

Layer Name (String)

Such as Layer 0.

Work with Selection Sets

95

DXF codes for common filters (continued)

DXF code

Filter type

60

Object Visibility (Integer)

Use 0 = visible, 1 = invisible.

62

Color Number (Integer)

Numeric index values ranging from 0 to 256.
Zero indicates the BYBLOCK. 256 indicates BYLAYER. A negative value
indicates that the layer is turned off.

67

Model/paper space indicator (Integer)

Use 0 or omitted = model space, 1 = paper space.

For a complete list of DXF group codes, see Group Codes in Numerical
Order in the DXF Reference.
The filter arguments are declared as arrays. The filter type is declared as an
integer and the filter value as a variant. Each filter type must be paired with
a filter value. For example:
FilterType(0) = 0
'Indicates filter refers to an object
type
FilterData(0) = "Circle"
'Indicates the object type is "Circle"

Specify a single selection criterion for a selection set

The following code prompts users to select objects to be included in a selection set, but only adds the selected object if it is a Circle:
Sub Ch4_FilterMtext()
Dim sstext As AcadSelectionSet
Dim FilterType(0) As Integer
Dim FilterData(0) As Variant
Set sstext = ThisDrawing.SelectionSets.Add("SS2")
FilterType(0) = 0
FilterData(0) = "Circle"
sstext.SelectOnScreen FilterType, FilterData
End Sub

Specify Multiple Criteria in a Selection Set Filter

List
To specify multiple selection criteria, declare an array containing enough
elements to represent each criterion, and assign each criterion to an
element.
Select objects that meet three criteria
The following code specifies three criteria: the object must be blue, it must
be a Circle, and it must reside on Layer 0. The code declares FilterType and
FilterData as arrays of three elements, and assigns each criterion to an
element:

96 | Chapter 4 Create and Edit AutoCAD

Entities

Sub Ch4_FilterBlueCircleOnLayer0()
Dim sstext As AcadSelectionSet
Dim FilterType(2) As Integer
Dim FilterData(2) As Variant
Set sstext = ThisDrawing.SelectionSets.Add("SS4")
FilterType(0) = 0
FilterData(0) = "Circle"
FilterType(1) = 62
FilterData(1) = acBlue
FilterType(2) = 8
FilterData(2) = "0"
sstext.SelectOnScreen FilterType, FilterData
End Sub

Add Complexity to Your Filter List Conditions

When you specify multiple selection criteria, AutoCAD assumes the
selected object must meet each criterion. But you can qualify your criteria
in other ways. For numeric items, you can specify relational operations (for
example, the radius of a circle must be greater than or equal to 5.0). And for
all items, you can specify logical operations (for example, Text or Mtext).
Use a -4 DXF code to indicate a relational operator in your
filter
specification. Specify the operator as a string. The allowable relational
operators are shown in the following table.
Relational operators for selection set
filter lists
Operator

Description

"*"

Anything goes (always true)

"="

Equals

"!="

Not equal to

"/="

Not equal to

"<>"

Not equal to

"<"

Less than

"<="

Less than or equal to

">"

Greater than

Work with Selection Sets

97

Relational operators for selection set filter lists

Operator

Description

">="

Greater than or equal to

"&"

Bitwise AND (integer groups only)

"&="

Bitwise masked equals (integer groups only)

Logical operators in filter lists are also indicated by a 4 group code, and the
operator is a string, but the operators must be paired. The opening operator
is preceded by a less-than symbol (<), and the closing operator is followed
by a greater-than symbol (>). The following table lists the logical operators
allowed in selection set filtering.
Logical grouping operators for selection set filter lists
Starting
operator

Encloses

Ending
operator

"<AND"

One or more operands

"AND>"

"<OR"

One or more operands

"OR>"

"<XOR"

Two operands

"XOR>"

"<NOT"

One operand

"NOT>"

Select a circle whose radius is greater than or equal to 5.0

The following code specifies that the selected object must be a circle whose
radius is greater than or equal to 5.0:

98 | Chapter 4 Create and Edit AutoCAD

Entities

Sub Ch4_FilterRelational()
Dim sstext As AcadSelectionSet
Dim FilterType(2) As Integer
Dim FilterData(2) As Variant
Set sstext = ThisDrawing.SelectionSets.Add("SS5")
FilterType(0)
FilterData(0)
FilterType(1)
FilterData(1)
FilterType(2)
FilterData(2)

=
=
=
=
=
=

0
"Circle"
-4
">="
40
5#

sstext.SelectOnScreen FilterType, FilterData

End Sub

Select either Text or Mtext

The following example specifies that either Text or Mtext objects can be
selected:
Sub Ch4_FilterOrTest()
Dim sstext As AcadSelectionSet
Dim FilterType(3) As Integer
Dim FilterData(3) As Variant
Set sstext = ThisDrawing.SelectionSets.Add("SS6")
FilterType(0) = -4
FilterData(0) = "<or"
FilterType(1) = 0
FilterData(1) = "TEXT"
FilterType(2) = 0
FilterData(2) = "MTEXT"
FilterType(3) = -4
FilterData(3) = "or>"
sstext.SelectOnScreen FilterType, FilterData
End Sub

Use Wild-Card Patterns in Selection Set Filter

Criteria
Symbol names and strings in filter lists can include wild-card patterns.
The following table identifies the wild-card characters recognized by
AutoCAD, and what each means in the context of a string:
Wild-card characters
Character

Definition

(pound)

Matches any single numeric digit

(at)

Matches any single alphabetic character

Wild-card characters (continued)

Character

Definition

(period)

Matches any single nonalphanumeric character

(asterisk)

Matches any character sequence, including an empty one, and

it can be used anywhere in the search pattern: at the
beginning, middle, or end

(question mark)

Matches any single character

(tilde)

If it is the first character in the pattern, it matches anything

except the pattern

[...]

Matches any one of the characters enclosed

[~...]

Matches any single character not enclosed

(hyphen)

Used inside brackets to specify a range for a single character

(comma)

Separates two patterns

(reverse quote)

Escapes special characters (reads next character literally)

Use a reverse quote (`) to indicate that a character is not a wild-card, but is
to be taken literally. For example, to specify that only an anonymous block
named *U2 be included in the selection set, use the following filter
arguments:
FilterType(0) = 2
FilterData(0) = "`*U2"

Select Mtext where a specific word appears in the text

The following code defines the selection criteria as any Mtext in which
The appears in the text string. This example also demonstrates use of the
Select- ByPolygon selection method:

Sub Ch4_FilterPolygonWildcard()
Dim sstext As AcadSelectionSet
Dim FilterType(1) As Integer
Dim FilterData(1) As Variant
Dim pointsArray(0 To 11) As Double
Dim mode As Integer
mode = acSelectionSetWindowPolygon
pointsArray(0) = -12#: pointsArray(1) = -7#: pointsArray(2)
pointsArray(3) = -12#: pointsArray(4) = 10#: pointsArray(5)
pointsArray(6) = 10#: pointsArray(7) = 10#: pointsArray(8) =
pointsArray(9) = 10#: pointsArray(10) = -7#: pointsArray(11)
0
Set sstext = ThisDrawing.SelectionSets.Add("SS10")
FilterType(0)
FilterData(0)
FilterType(1)
FilterData(1)

=
=
=
=

= 0
= 0
0
=

0
"MTEXT"
1
"*The*"

sstext.SelectByPolygon mode, pointsArray, FilterType, FilterData

End Sub

Filter for Extended

Data
External applications can attach data such as text strings, numeric values,
3D points, distances, and layer names to AutoCAD objects. This data is
referred to as extended data, or xdata. You can filter entities containing
extended data for a specified application.
See Assign and Retrieve Extended Data on page 307 for more information
about extended data.
Select circles that contain xdata
The following example filters for circles containing xdata added by the
MY_APP application:

Sub Ch4_FilterXdata()
Dim sstext As AcadSelectionSet
Dim mode As Integer
Dim pointsArray(0 To 11) As Double
mode = acSelectionSetWindowPolygon
pointsArray(0) = -12#: pointsArray(1) = -7#: pointsArray(2) = 0
pointsArray(3) = -12#: pointsArray(4) = 10#: pointsArray(5) = 0
pointsArray(6) = 10#: pointsArray(7) = 10#: pointsArray(8) = 0
pointsArray(9) = 10#: pointsArray(10) = -7#: pointsArray(11) = 0
Dim FilterType(1) As Integer
Dim FilterData(1) As Variant
Set sstext = ThisDrawing.SelectionSets.Add("SS9")
FilterType(0)
FilterData(0)
FilterType(1)
FilterData(1)

=
=
=
=

0
"Circle"
1001
"MY_APP"

sstext.SelectByPolygon mode, pointsArray, FilterType, FilterData

End Sub

Display Information About a Selection

Set
To refer to an existing selection set whose name you know, refer to it by
name. The following example refers to a selection set named SS10:
Sub GetObjInSet()
Dim selset As AcadSelectionSet
Set selset = ThisDrawing.SelectionSets("SS10")
MsgBox ("Selection set " & selset.Name & " contains " & _
selset.Count & " items")
End Sub

Each selection set in a drawing is a member of the SelectionSets collection.

You can use the For Each statement to iterate through a drawings SelectionSets collection and collect information about each selection set.

Display the name of each selection set in a drawing

The following code displays the name of each selection set in a drawing,
and lists the types of objects included in each selection set:
Sub ListSelectionSets()
Dim selsetCollection As AcadSelectionSets
Dim selset As AcadSelectionSet
Dim ent As Object
Dim i, j As Integer
Set selsetCollection = ThisDrawing.SelectionSets
' Find each selection set in the drawing
i = 0
For Each selset In selsetCollection
MsgBox "Selection set " & CStr(i) & " is: " & selset.Name
' Now find each
is j = 0
For Each ent In
MsgBox "Item
& "is: " &
j = j + 1
Next
i = i + 1
Next

object in the selection set, and say what it

selset
" & CStr(j + 1) & " in " & selset.Name _
ent.EntityName

End Sub

Remove Objects from a Selection Set

After you create a selection set, you can choose to remove individual
objects, or all the objects from that set. For example, you can select an
entire group of densely grouped objects and remove specific objects within
the group, leaving only the objects you want to be in the set.
Use the following methods to remove items from the selection set:
RemoveItems

The RemoveItems method removes one or more items

from a selection set. The removed items still exist, but
they no longer reside in the selection set.

Clear

The Clear method will empty the selection set. The

selection set will still exist, but contains no items. The
items that previously resided in the selection still exist,
but they no longer reside in the selection set.

Erase

The Erase method deletes all items in a selection set.

The selection set still exists, but will contain no items.
The items that previously resided in the selection set no
longer exist.

Delete

The Delete method deletes a selection set and all items

in the selection set. Neither the selection set, nor the
items previously in the selection set will exist after a
call to the Delete method.

Edit Objects
To modify an existing object, use the methods and properties associated
with that object. If you modify a visible property of a graphic object, use the
Update method to redraw the object onscreen.
This section describes how to edit 2D objects.

Work with Named Objects

In addition to the graphic objects used by AutoCAD, there are several types
of nongraphic objects stored in drawing files. These objects have descriptive
designations associated with them, for example, blocks, layers, groups, and
dimension styles. In most cases, you name objects as you create them, and
rename them later. Names are stored in symbol tables. When you specify a
named object, you are referencing the name and associated data of the
object in the symbol table.

Purge Named Objects

You can purge unused, unreferenced named objects from a drawing at any
time during an editing session. Purging reduces drawing size. You cannot
purge objects that are referenced by other objects. For example, a font file
might be referenced by a text style. A layer is referenced by the objects on the
layer.
To purge a drawing, use the PurgeAll method, as follows:
ThisDrawing.PurgeAll

Rename Objects
As your drawings become more complex, you can rename objects to keep the
names meaningful or to avoid conflicts with names in other drawings you
have inserted in the main drawings.
You can rename any named object except those that AutoCAD names
by default, for example, layer 0 or the CONTINUOUS linetype.

Names can be up to 255 characters long. In addition to letters and numbers,

names can contain spaces (although AutoCAD removes spaces that appear
directly before and after a name) and any special character not used by
Microsoft Windows or AutoCAD for other purposes. Special characters that
you cannot use include less-than and greater-than symbols (< >), forward
slashes and backslashes (/ \), quotation marks ("), colons (:), semicolons (;),
question marks (?), commas (,), asterisks (*), vertical bars (|), equal signs (=),
and backquotes ('). You also cannot use special characters created with
Unicode fonts.
To rename an object, use the Name property for that object.
Rename a layer
This example creates a layer called NewLayer and then renames the layer
to MyLayer.
Sub Ch4_RenamingLayer()
' Create a layer
Dim layerObj As AcadLayer
Set layerObj = ThisDrawing.Layers.Add("NewLayer")
' Change the name of the layer
layerObj.Name = "MyLayer"
End Sub

Copy Objects
You can copy single or multiple objects within the current drawing. Offsetting creates new objects at a specified distance from selected objects, or
through a specified point. Mirroring creates a mirror image of objects in a
specified mirror line. Arraying creates sets of copied objects in a rectangular
or circular pattern.
For more information about copying objects, see Copy, Offset, or Mirror
Objects in the Users Guide.

Note You cannot perform any of the copy methods while simultaneously
iter- ating through a collection. An iteration will open the workspace for a readonly operation while these methods attempt to perform a read-write operation.
Complete any iteration of a collection before you call these methods.

Edit Objects
105

Copy an Object to the Same Location

To copy a single object, use the Copy method provided for that object. This
method creates a new object that is a duplicate of the original object. The
new object is located at the same position as the original, and is returned by
the method.

Copy Multiple Objects

To copy multiple objects, use the CopyObjects method or create an array of
objects to use with the Copy method. (To copy the objects in a selection set,
iterate through the selection set and save the objects into an array.) Iterate
through the array, copying each object individually, and collect the newly
created objects in a second array.
To copy multiple objects to a different drawing, use the CopyObjects
method and set the Owner parameter to the drawings model space.
Copy two circle objects
This example creates two Circle objects and uses the CopyObjects method to
make a copy of the circles.

106 | Chapter 4 Create and Edit AutoCAD

Entities

Sub Ch4_CopyCircleObjects()
Dim DOC1 As AcadDocument
Dim circleObj1 As AcadCircle
Dim circleObj2 As AcadCircle
Dim circleObj1Copy As AcadCircle
Dim circleObj2Copy As AcadCircle
Dim centerPoint(0 To 2) As Double
Dim radius1 As Double
Dim radius2 As Double
Dim radius1Copy As Double
Dim radius2Copy As Double
Dim objCollection(0 To 1) As Object
Dim retObjects As Variant
' Define the Circle object
centerPoint(0) = 0: centerPoint(1) = 0: centerPoint(2) = 0
radius1 = 5#: radius2 = 7#
radius1Copy = 1#: radius2Copy = 2#
' Create a new drawing
Set DOC1 = ThisDrawing.Application.Documents.Add
' Add two circles to the drawing
Set circleObj1 = DOC1.ModelSpace.AddCircle _
(centerPoint, radius1)
Set circleObj2 = DOC1.ModelSpace.AddCircle _
(centerPoint, radius2)
ZoomAll
' Put the objects to be copied into a form
' compatible with CopyObjects
Set objCollection(0) = circleObj1
Set objCollection(1) = circleObj2
' Copy object and get back a collection of
' the new objects (copies)
retObjects = DOC1.CopyObjects(objCollection)
' Get newly created object and apply
' new properties to the copies
Set circleObj1Copy = retObjects(0)
Set circleObj2Copy = retObjects(1)
circleObj1Copy.radius = radius1Copy
circleObj1Copy.Color = acRed
circleObj2Copy.radius = radius2Copy
circleObj2Copy.Color = acRed
ZoomAll
End Sub

Copy objects to another drawing

This example creates Circle objects, then uses the CopyObjects method to
copy the circles into a new drawing.

Edit Objects
107

Sub Ch4_Copy_to_New_Drawing()
Dim DOC0 As AcadDocument
Dim circleObj1 As AcadCircle, circleObj2 As AcadCircle
Dim centerPoint(0 To 2) As Double
Dim radius1 As Double, radius2 As Double
Dim radius1Copy As Double, radius2Copy As Double
Dim objCollection(0 To 1) As Object
Dim retObjects As Variant
' Define the Circle object
centerPoint(0) = 0: centerPoint(1) = 0: centerPoint(2) = 0
radius1 = 5#: radius2 = 7#
radius1Copy = 1#: radius2Copy = 2#
' Add two circles to the current drawing
Set circleObj1 = ThisDrawing.ModelSpace.AddCircle _
(centerPoint, radius1)
Set circleObj2 = ThisDrawing.ModelSpace.AddCircle _
(centerPoint, radius2)
ThisDrawing.Application.ZoomAll
' Save pointer to the current drawing
Set DOC0 = ThisDrawing.Application.ActiveDocument
' Copy objects
'
' First put the objects to be copied into a form compatible
' with CopyObjects
Set objCollection(0) = circleObj1
Set objCollection(1) = circleObj2
' Create a new drawing and point to its model space
Dim Doc1MSpace As AcadModelSpace
Dim DOC1 As AcadDocument
Set DOC1 = Documents.Add
Set Doc1MSpace = DOC1.ModelSpace
' Copy the objects into the model space of the new drawing. A
' collection of the new (copied) objects is returned.
retObjects = DOC0.CopyObjects(objCollection, Doc1MSpace)
Dim circleObj1Copy As AcadCircle, circleObj2Copy As AcadCircle
' Get the newly created object collection and apply new
' properties to the copies.
Set circleObj1Copy = retObjects(0)
Set circleObj2Copy = retObjects(1)
circleObj1Copy.radius = radius1Copy
circleObj1Copy.Color = acRed
circleObj2Copy.radius = radius2Copy
circleObj2Copy.Color = acRed
ThisDrawing.Application.ZoomAll

108 | Chapter 4 Create and Edit AutoCAD

Entities

MsgBox "Circles copied."

End Sub

Offset Objects
Offsetting an object creates a new object at a specified offset distance from
the original object. You can offset arcs, circles, ellipses, lines, lightweight
polylines, polylines, splines, and xlines.
To offset an object, use the Offset method provided for that object. The
only input to this method is the distance to offset the object. If this
distance is negative, it is interpreted by AutoCAD as being an offset to make
a smaller curve (that is, for an arc it would offset to a radius that is the
given distance less than the starting curves radius). If smaller has no
meaning, then AutoCAD would offset in the direction of smaller X,Y,Z
WCS coordinates. If the offset distance is invalid then an error is returned.

offset polylines

For many objects, the result of this operation will be a single new curve
(which may not be of the same type as the original curve). For example,
offsetting an ellipse will result in a spline because the result does fit the
equa- tion of an ellipse. In some cases it may be necessary for the offset
result to be several curves. Because of this, the method returns the new
object, or array of objects, as a variant.
For more information about offsetting objects, see Copy, Offset, or Mirror
Objects in the Users Guide.
Offset a polyline
This example creates a lightweight polyline and then offsets the polyline.

Edit Objects
109

Sub Ch4_OffsetPolyline()
' Create the polyline
Dim plineObj As AcadLWPolyline
Dim points(0 To 11) As Double
points(0) = 1: points(1) = 1
points(2) = 1: points(3) = 2
points(4) = 2: points(5) = 2
points(6) = 3: points(7) = 2
points(8) = 4: points(9) = 4
points(10) = 4: points(11) = 1
Set plineObj = ThisDrawing.ModelSpace. _
AddLightWeightPolyline(points)
plineObj.Closed = True
ZoomAll
' Offset the polyline
Dim offsetObj As Variant
offsetObj = plineObj.Offset(0.25)
ZoomAll
End Sub

Mirror Objects
Mirroring creates a mirror image copy of an object around an axis or mirror
line. You can mirror all drawing objects.
To mirror an object, use the Mirror method provided for that object. This
method requires two coordinates as input. The two coordinates specified
become the endpoints of the mirror line around which the base object is
reflected. In 3D, this line orients a mirroring plane perpendicular to the XY
plane of the UCS containing the mirror line.
Unlike the mirror command in AutoCAD, this method places the reflected
image into the drawing and retains the original object. (To remove the original object, use the Erase method.)

selected objects

mirror line

mirrored object

To manage the reflection properties of Text objects, use the MIRRTEXT

system variable. The default setting of MIRRTEXT is On (1), which causes Text
objects to be mirrored just as any other object. When MIRRTEXT is off (0),
text is not mirrored. Use the GetVariable and SetVariable methods to query
and set the MIRRTEXT setting.

110 | Chapter 4 Create and Edit AutoCAD

Entities

before mirroring

after mirroring
(MIRRTEXT=1)

after mirroring
(MIRRTEXT=0)

You can mirror a Viewport object in paper space, although doing so has no
effect on its model space view or on model space objects.
For more information about mirroring objects, see Copy, Offset, or Mirror
Objects in the Users Guide.
Mirror a polyline about an axis
This example creates a lightweight polyline and mirrors that polyline about
an axis. The newly created polyline is colored blue.
Sub Ch4_MirrorPolyline()
' Create the polyline
Dim plineObj As AcadLWPolyline
Dim points(0 To 11) As Double
points(0) = 1: points(1) = 1
points(2) = 1: points(3) = 2
points(4) = 2: points(5) = 2
points(6) = 3: points(7) = 2
points(8) = 4: points(9) = 4
points(10) = 4: points(11) = 1
Set plineObj = ThisDrawing.ModelSpace. _
AddLightWeightPolyline(points)
plineObj.Closed = True
ZoomAll
' Define the mirror axis
Dim point1(0 To 2) As Double
Dim point2(0 To 2) As Double
point1(0) = 0: point1(1) = 4.25: point1(2) = 0
point2(0) = 4: point2(1) = 4.25: point2(2) = 0
' Mirror the polyline
Dim mirrorObj As AcadLWPolyline
Set mirrorObj = plineObj.Mirror(point1, point2)
Dim col As New AcadAcCmColor
Call col.SetRGB(125, 175, 235)
mirrorObj.TrueColor = col
ZoomAll
End Sub

Array Objects
You can copy an object in polar or rectangular arrays. For polar arrays, you
control the number of copies of the object and the angle to fill the array to.
For rectangular arrays, you control the number of rows and columns and the
distance between them.
For more information about arrays, see Create an Array of Objects in the
Users Guide.

Create Polar Arrays

You can array all drawing objects. To create a polar array, use the ArrayPolar
method provided for that object. This method requires you to provide the
number of objects to create, the angle-to-fill, and the center point for the
array. The number of objects must be a positive integer greater than 1. The
angle-to-fill must be in radians. A positive value specifies counterclockwise
rotation. A negative value specifies clockwise rotation. An error is returned
for an angle that equals 0. The center point is a variant array containing
three doubles. These doubles represent the 3D WCS coordinate specifying
the cen- ter point for the polar array.
polar array

(0,0,0)

AutoCAD determines the distance from the arrays center point to a

reference point on the original object. The reference point used depends on
the type of object. AutoCAD uses the center point of a circle or arc, the
insertion point of a block or shape, the start point of text, and one endpoint
of a line or trace.
This method does not support the Rotate While Copying option of the
AutoCAD ARRAY command.
Create a polar array
This example creates a circle, and then performs a polar array of the circle.
This creates four circles filling 180 degrees around a base point of (4, 4, 0).

Sub Ch4_ArrayingACircle()
' Create the circle
Dim circleObj As AcadCircle
Dim center(0 To 2) As Double
Dim radius As Double
center(0) = 2#: center(1) = 2#: center(2) = 0#
radius = 1
Set circleObj = ThisDrawing.ModelSpace. _
AddCircle(center, radius)
ZoomAll
' Define the polar array
Dim noOfObjects As Integer
Dim angleToFill As Double
Dim basePnt(0 To 2) As Double
noOfObjects = 4
angleToFill = 3.14
' 180 degrees
basePnt(0) = 4#: basePnt(1) = 4#: basePnt(2) = 0#
' The following example will create 4 copies
' of an object by rotating and copying it about
' the point (3,3,0).
Dim retObj As Variant
retObj = circleObj.ArrayPolar _
(noOfObjects, angleToFill, basePnt)
ZoomAll
End Sub

Create Rectangular Arrays

To create a 2D or 3D rectangular array, use the ArrayRectangular method
provided for that object. This method requires you to provide the number
of rows, number of columns, distance between rows, and distance between
columns. When creating a 3D array, you must also specify the number of
levels and distance between levels as well.
A rectangular array is constructed by replicating the object in the selection
set the appropriate number of times. If you define one row, you must
specify more than one column and vice versa.
The original object is assumed to be in the lower-left corner, and the array is
generated up and to the right. If the distance between rows is a negative
number, rows are added downward. If the distance between columns is a
negative number, the columns are added to the left.

rectangular array

a
base object
b

AutoCAD builds the rectangular array along a baseline defined by the

current snap rotation angle. This angle is 0 by default, so the rows and
columns of a rectangular array are orthogonal with respect to the X and Y
drawing axes. You can change this angle and create a rotated array by
setting the snap rotation angle to a nonzero value. To do this, use the
SnapRotationAngle property.
Create a rectangular array
This example creates a circle and then performs a rectangular array of the
circle, creating five rows and five columns of circles.

Sub Ch4_ArrayRectangularExample()
' Create the circle
Dim circleObj As AcadCircle
Dim center(0 To 2) As Double
Dim radius As Double
center(0) = 2#: center(1) = 2#: center(2) = 0#
radius = 0.5
Set circleObj = ThisDrawing.ModelSpace. _
AddCircle(center, radius)
ZoomAll
' Define the rectangular array
Dim numberOfRows As Long
Dim numberOfColumns As Long
Dim numberOfLevels As Long
Dim distanceBwtnRows As Double
Dim distanceBwtnColumns As Double
Dim distanceBwtnLevels As Double
numberOfRows = 5
numberOfColumns = 5
numberOfLevels = 2
distanceBwtnRows = 1
distanceBwtnColumns = 1
distanceBwtnLevels = 1
' Create the array of objects
Dim retObj As Variant
retObj = circleObj.ArrayRectangular _
(numberOfRows, numberOfColumns, numberOfLevels, _
distanceBwtnRows, distanceBwtnColumns, distanceBwtnLevels)
ZoomAll
End Sub

Move Objects
You can move objects along a vector without changing their orientation or
size. You can also rotate objects around a base point.
For more information about moving objects, see Move Objects in the Users
Guide.

Move Objects Along a Vector

You can move all drawing objects and attribute reference objects along a
specified vector.
To move an object, use the Move method provided for that object. This
method requires two coordinates as input. These coordinates define a displacement vector indicating how far the given object is to be moved and in
what direction.

1
select object

2
select object with two points indicated

moved object

Move a circle along a vector

This example creates a circle and then moves that circle two units along the
X axis.
Sub Ch4_MoveCircle()
' Create the circle
Dim circleObj As AcadCircle
Dim center(0 To 2) As Double
Dim radius As Double
center(0) = 2#: center(1) = 2#: center(2) = 0#
radius = 0.5
Set circleObj = ThisDrawing.ModelSpace. _
AddCircle(center, radius)
ZoomAll
' Define the points that make up the move vector.
' The move vector will move the circle 2 units
' along the x axis.
Dim point1(0 To 2) As Double
Dim point2(0 To 2) As Double
point1(0) = 0: point1(1) = 0: point1(2) = 0
point2(0) = 2: point2(1) = 0: point2(2) = 0
' Move the circle
circleObj.Move point1, point2
circleObj.Update
End Sub

Rotate Objects
You can rotate all drawing objects and attribute reference objects.
To rotate an object, use the Rotate method provided for that object. This
method requires as input a base point and a rotation angle. The base point
is a variant array with three doubles. These doubles represent a 3D WCS
coor- dinate specifying the point through which the axis of rotation is
defined. The angle of rotation is specified in radians. This angle determines
how far an object rotates around the base point relative to its current
location.

selected objects

rotation angle

rotated object

For more information about rotating objects, see Rotate Objects in the
Users Guide.
Rotate a polyline about a base point
This example creates a closed lightweight polyline, and then rotates the
polyline 45 degrees about the base point (4, 4.25, 0).
Sub Ch4_RotatePolyline()
' Create the polyline
Dim plineObj As AcadLWPolyline
Dim points(0 To 11) As Double
points(0) = 1: points(1) = 2
points(2) = 1: points(3) = 3
points(4) = 2: points(5) = 3
points(6) = 3: points(7) = 3
points(8) = 4: points(9) = 4
points(10) = 4: points(11) = 2
Set plineObj = ThisDrawing.ModelSpace. _
AddLightWeightPolyline(points)
plineObj.Closed = True
ZoomAll
' Define the rotation of 45 degrees about a
' base point of (4, 4.25, 0)
Dim basePoint(0 To 2) As Double
Dim rotationAngle As Double
basePoint(0) = 4: basePoint(1) = 4.25: basePoint(2) = 0
rotationAngle = 0.7853981
' 45 degrees
' Rotate the polyline
plineObj.Rotate basePoint, rotationAngle
plineObj.Update
End Sub

Delete Objects
You can delete individual objects by using the Delete method.

Note The Collection objects in ActiveX Automation have a Delete method

due to the manner in which these objects have been defined in the type library.
How- ever, the Collection objects, such as ModelSpace collection, Layers
collection, and Dictionaries collection, should never be deleted. An error will
result if you attempt to delete a collection.
Create and delete a polyline
This example creates a lightweight polyline, then deletes it.
Sub Ch4_DeletePolyline()
' Create the polyline
Dim lwpolyObj As AcadLWPolyline
Dim vertices(0 To 5) As Double
vertices(0) = 2: vertices(1) = 4
vertices(2) = 4: vertices(3) = 2
vertices(4) = 6: vertices(5) = 4
Set lwpolyObj = ThisDrawing.ModelSpace. _
AddLightWeightPolyline(vertices)
ZoomAll
' Erase the polyline
lwpolyObj.Delete
ThisDrawing.Regen acActiveViewport
End Sub

Scale Objects
You scale an object by specifying a base point and a length, which is used as
a scale factor based on the current drawing units. You can scale all the drawing objects, as well as attribute reference objects.
To scale an object, use the ScaleEntity method provided for that object. This
method scales the object equally in the X, Y, and Z directions. It takes as
input the base point for the scale and a scale factor. The base point is a
variant array with three doubles. These doubles represent a 3D WCS
coordinate spec- ifying the point from which the scale begins. The scale
factor is the factor by which to scale the object. The dimensions of the
object are multiplied by the scale factor. A scale factor greater than 1
enlarges the object. A scale factor between 0 and 1 reduces the object.

scale factor = .5

scale factor = 2

For more information about scaling, see Resize or Reshape Objects in the
Users Guide.
Scale a polyline
This example creates a closed lightweight polyline and then scales the
polyline by 0.5.
Sub Ch4_ScalePolyline()
' Create the polyline
Dim plineObj As AcadLWPolyline
Dim points(0 To 11) As Double
points(0) = 1: points(1) = 2
points(2) = 1: points(3) = 3
points(4) = 2: points(5) = 3
points(6) = 3: points(7) = 3
points(8) = 4: points(9) = 4
points(10) = 4: points(11) = 2
Set plineObj = ThisDrawing.ModelSpace. _
AddLightWeightPolyline(points)
plineObj.Closed = True
ZoomAll
' Define the scale
Dim basePoint(0 To 2) As Double
Dim scalefactor As Double
basePoint(0) = 4: basePoint(1) = 4.25: basePoint(2) = 0
scalefactor = 0.5
' Scale the polyline
plineObj.ScaleEntity basePoint, scalefactor
plineObj.Update
End Sub

Transform Objects
You move, scale, or rotate an object given a 4 4 transformation matrix
using the TransformBy method.
The following table demonstrates the transformation matrix configuration,
where R = Rotation and T = Translation:
Transformation matrix configuration
R00

R01

R02

T0

R10

R11

R12

T1

R20

R21

R22

T2

To transform an object, first initialize the transformation matrix. The following example shows a transformation matrix, assigned to the variable
tMatrix, which will rotate an entity by 90 degrees about the point (0, 0, 0):
tMatrix(0,0)
tMatrix(0,1)
tMatrix(0,2)
tMatrix(0,3)
tMatrix(1,0)
tMatrix(1,1)
tMatrix(1,2)
tMatrix(1,3)
tMatrix(2,0)
tMatrix(2,1)
tMatrix(2,2)
tMatrix(2,3)
tMatrix(3,0)
tMatrix(3,1)
tMatrix(3,2)
tMatrix(3,3)

=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=

0.0
-1.0
0.0
0.0
1.0
0.0
0.0
0.0
0.0
0.0
1.0
0.0
0.0
0.0
0.0
1.0

After the transformation matrix is complete, apply the matrix to the object
using the TransformBy method. The following line of code demonstrates
applying a matrix (tMatrix) to an object (anObj):
anObj.TransformBy tMatrix

Rotate a line with a transformation matrix

This example creates a line and rotates it 90 degrees using a transformation
matrix.

Sub Ch4_TransformBy()
' Create a line
Dim lineObj As AcadLine
Dim startPt(0 To 2) As Double
Dim endPt(0 To 2) As Double
startPt(0) = 2
startPt(1) = 1
startPt(2) = 0
endPt(0) = 5
endPt(1) = 1
endPt(2) = 0
Set lineObj = ThisDrawing.ModelSpace. _
AddLine(startPt, endPt)
ZoomAll
' Initialize the transMat variable with a
' transformation matrix that will rotate
' an object by 90 degrees about the point(0,0,0)
Dim transMat(0 To 3, 0 To 3) As Double
transMat(0, 0) = 0#: transMat(0, 1) = -1#
transMat(0, 2) = 0#: transMat(0, 3) = 0#
transMat(1, 0) = 1#: transMat(1, 1) = 0#
transMat(1, 2) = 0#: transMat(1, 3) = 0#
transMat(2, 0) = 0#: transMat(2, 1) = 0#
transMat(2, 2) = 1#: transMat(2, 3) = 0#
transMat(3, 0) = 0#: transMat(3, 1) = 0#
transMat(3, 2) = 0#: transMat(3, 3) = 1#
' Transform the line using the defined transformation matrix
lineObj.TransformBy transMat
lineObj.Update
End Sub

The following are more examples of transformation matrices:

Rotation Matrix: 90 degrees about point (0, 0, 0)
0.0

1.0

0.0

0.0

1.0

0.0

0.0

0.0

0.0

0.0

1.0

0.0

0.0

0.0

0.0

1.0

Rotation Matrix: 45 degrees about point (5, 5,

0)

0.707107

0.707107

0.0

5.0

0.707107

0.707107

0.0

2.071068

Rotation Matrix: 45 degrees about point (5, 5, 0)

0.0

0.0

1.0

0.0

0.0

0.0

0.0

1.0

Translation Matrix: move an entity by (10, 10,

0)

1.0

0.0

0.0

10.0

0.0

1.0

0.0

10.0

0.0

0.0

1.0

0.0

0.0

0.0

0.0

1.0

Scaling Matrix: scale by 10,10 at point (0, 0,

0)

10.0

0.0

0.0

0.0

0.0

10.0

0.0

0.0

0.0

0.0

10.0

0.0

0.0

0.0

0.0

1.0

Scaling Matrix: scale by 10,10 at point (2, 2,

0)

10.0

0.0

0.0

18.0

0.0

10.0

0.0

18.0

0.0

0.0

10.0

0.0

0.0

0.0

0.0

1.0

Extend and Trim Objects

You can change the angle of arcs and you can change the length of open
lines, arcs, open polylines, elliptical arcs, and open splines. The results are
similar to both extending and trimming objects.

You can extend or trim an object by editing its properties. For example, to
lengthen a line, simply change the coordinates of the StartPoint or
EndPoint properties. To change the angle of an arc, change the StartAngle or
EndAngle properties of the arc. Once you have altered an objects property
or proper- ties, use the Update method to see your changes in the drawing.
For more information about extending and trimming objects, see Resize or
Reshape Objects in the Users Guide.
Lengthen a line
This example creates a line then changes the endpoint of that line resulting
in a longer line.
Sub Ch4_LengthenLine()
' Define and create the line
Dim lineObj As AcadLine
Dim startPoint(0 To 2) As Double
Dim endPoint(0 To 2) As Double
startPoint(0) = 0
startPoint(1) = 0
startPoint(2) = 0
endPoint(0) = 1
endPoint(1) = 1
endPoint(2) = 1
Set lineObj = ThisDrawing.ModelSpace. _
AddLine(startPoint, endPoint)
lineObj.Update
' Lengthen the line by changing the
' endpoint to 4, 4, 4
endPoint(0) = 4
endPoint(1) = 4
endPoint(2) = 4
lineObj.endPoint = endPoint
lineObj.Update
End Sub

Explode Objects
Exploding objects converts the objects from single objects to their constituent parts but has no visible effect. For example, exploding forms simple lines
and arcs from 3D polygons, polylines, polygon meshes, and regions. It
replaces a block reference with copies of the simple objects that compose
the block.
For more information about exploding objects, see Disassociate Compound
Objects (Explode) in the Users Guide.

Explode a polyline
This example creates a lightweight polyline object. It then explodes the
polyline into separate objects. The example then loops through the
resulting objects and displays a message box containing the name of each
object and its index in the list of exploded objects.
Sub Ch4_ExplodePolyline()
Dim plineObj As AcadLWPolyline
Dim points(0 To 11) As Double
' Define the 2D polyline points
points(0) = 1: points(1) = 1
points(2) = 1: points(3) = 2
points(4) = 2: points(5) = 2
points(6) = 3: points(7) = 2
points(8) = 4: points(9) = 4
points(10) = 4: points(11) = 1
' Create a light weight Polyline object
Set plineObj = ThisDrawing.ModelSpace. _
AddLightWeightPolyline(points)
' Set the bulge on one segment to vary the
' type of objects in the polyline
plineObj.SetBulge 3, -0.5
plineObj.Update
' Explode the polyline
Dim explodedObjects As Variant
explodedObjects = plineObj.Explode
' Loop through the exploded objects
' and display a message box with
' the type of each object
Dim I As Integer
For I = 0 To UBound(explodedObjects)
explodedObjects(I).Color = acRed
explodedObjects(I).Update
MsgBox "Exploded Object " & I & ": " & _
explodedObjects(I).ObjectName
explodedObjects(I).Color = acByLayer
explodedObjects(I).Update
Next
End Sub

Edit Polylines
2D and 3D polylines, rectangles, polygons, and 3D polygon meshes are all
polyline variants and are edited in the same way.

AutoCAD recognizes both fit polylines and spline-fit polylines. A spline-fit

polyline uses a curve fit, similar to a B-spline. There are two kinds of splinefit polylines: quadratic and cubic. Both polylines are controlled by the
SPLINETYPE system variable. A fit polyline uses standard curves for curve fit
and utilizes any tangent directions set on any given vertex.
To edit a polyline, use the properties and methods of the LightweightPolyline
or Polyline objects. Use the following properties and methods to open or
close a polyline, change the coordinates of a polyline vertex, or add a vertex:
Closed property

Opens or closes the polyline.

Coordinates
property

Specifies the coordinates for each vertex in the polyline.

AddVertex
method

Adds a vertex to a lightweight polyline.

Use the following methods to update the bulge or width of a polyline:

SetBulge

Sets the bulge of a polyline, given the segment index.

SetWidth

Sets the start and end width of a polyline, given the

segment index.

For more information about editing polylines, see Modify or Join

Polylines
in
the
Users
Guide.
Edit a polyline
This example creates a lightweight polyline. It then adds a bulge to the third
segment of the polyline, appends a vertex to the polyline, changes the
width of the last segment, and finally closes the polyline.

Sub Ch4_EditPolyline()
Dim plineObj As AcadLWPolyline
Dim points(0 To 9) As Double
' Define the 2D polyline
points(0) = 1: points(1)
points(2) = 1: points(3)
points(4) = 2: points(5)
points(6) = 3: points(7)
points(8) = 4: points(9)

points
= 1
= 2
= 2
= 2
= 4

' Create a light weight Polyline object

Set plineObj = ThisDrawing.ModelSpace. _
AddLightWeightPolyline(points)
' Add a bulge to segment 3
plineObj.SetBulge 3, -0.5
' Define the new vertex
Dim newVertex(0 To 1) As Double
newVertex(0) = 4: newVertex(1) = 1
' Add the vertex to the polyline
plineObj.AddVertex 5, newVertex
' Set the width of the new segment
plineObj.SetWidth 4, 0.1, 0.5
' Close the polyline
plineObj.Closed = True
plineObj.Update
End Sub

Edit Splines
Use the following editable properties to change splines:
Closed

Opens or closes the spline.

ControlPoints

Specifies the control points of a spline.

EndTangent

Specifies the end tangent of the spline as a directional

vector.

FitPoints

Specifies all the fit points of a spline.

FitTolerance

Refits the spline to the existing points with new

tolerance values.

Knots

Specifies the knots vector for the spline.

StartTangent

Specifies the start tangent for the spline.

In addition, you can use the following methods to edit splines:

AddFitPoint

Adds a single fit point to the spline at a given index.

DeleteFitPoint

Deletes the fit point of a spline at a given index.

ElevateOrder

Elevates the order of the spline to the given order.

GetFitPoint

Gets the fit point of the spline at a given index. (Gets

one fit point only. To query all the fit points of the
spline, use the FitPoints property.)

Reverse

Reverses the direction of a spline.

SetControlPoint

Sets the control point of the spline at a given index.

SetFitPoint

Sets the fit point of the spline at a given index. (Sets one
fit point only. To change all the fit points of the spline,
use the FitPoints property.)

SetWeight

Sets the weight of the control point at a given index.

Use the following read-only properties to query splines:

Degree

Gets the degree of the splines polynomial

representation.

Area

Gets the enclosed area of a spline.

IsPeriodic

Specifies if the given spline is periodic.

IsPlanar

Specifies if the given spline is planar.

IsRational

Specifies if the given spline is rational.

NumberOfControlPoints
Gets the number of control points of the spline.
NumberOfFitPoints
Gets the number of fit points of the spline.
For more information about editing splines, see Modify Splines in the
Users Guide.

Change a control point on a spline

This example creates a spline and then changes the first control point for the
spline.
Sub Ch4_ChangeSplineControlPoint()
' Create the spline
Dim splineObj As AcadSpline
Dim startTan(0 To 2) As Double
Dim endTan(0 To 2) As Double
Dim fitPoints(0 To 8) As Double
startTan(0) = 0.5: startTan(1) = 0.5: startTan(2) = 0
endTan(0) = 0.5: endTan(1) = 0.5: endTan(2) = 0
fitPoints(0) = 1: fitPoints(1) = 1: fitPoints(2) = 0
fitPoints(3) = 5: fitPoints(4) = 5: fitPoints(5) = 0
fitPoints(6) = 10: fitPoints(7) = 0: fitPoints(8) = 0
Set splineObj = ThisDrawing.ModelSpace. _
AddSpline(fitPoints, startTan, endTan)
splineObj.Update
' Change the coordinate of the first fit point
Dim controlPoint(0 To 2) As Double
controlPoint(0) = 0
controlPoint(1) = 3 controlPoint(2) = 0
splineObj.SetControlPoint 0, controlPoint
splineObj.Update
End Sub

Edit Hatches
You can edit both hatch boundaries and hatch patterns. If you edit the
boundary of an associative hatch, the pattern is updated as long as the editing results in a valid boundary. Associative hatches are updated even if
theyre on layers that are turned off. You can modify hatch patterns or
choose a new pattern for an existing hatch, but associativity can only be set
when a hatch is created. You can check to see if a Hatch object is associative
by using the AssociativeHatch property. (See the AddHatch method for more
information on creating a hatch.)
You must re-evaluate a hatch using the Evaluate method to see any edits
to the hatch.
For more information about editing hatches, see Modify Hatches and SolidFilled Areas in the Users Guide.

Edit Hatch Boundaries

You can append or insert loops into the hatch boundaries. Associative
hatches are updated to match any changes made to their boundaries. Nonassociative hatches are not updated.
To edit a hatch boundary, use one of the following methods:
AppendInnerLoop
Appends an inner loop to the hatch.
AppendOuterLoop
Appends an outer loop to the hatch.
InsertLoopAt

Inserts a loop at a given index of a hatch.

Append an inner loop to a hatch

This example creates an associative hatch. It then creates a circle
and appends the circle as an inner loop to the hatch.

Sub Ch4_AppendInnerLoopToHatch()
Dim hatchObj As AcadHatch
Dim patternName As String
Dim PatternType As Long
Dim bAssociativity As Boolean
' Define and create the hatch
patternName = "ANSI31"
PatternType = 0
bAssociativity = True
Set hatchObj = ThisDrawing.ModelSpace. _
AddHatch(PatternType, patternName, bAssociativity)
' Create the outer loop for the hatch.
Dim outerLoop(0 To 1) As AcadEntity
Dim center(0 To 2) As Double
Dim radius As Double
Dim startAngle As Double
Dim endAngle As Double
center(0) = 5: center(1) = 3: center(2) = 0
radius = 3
startAngle = 0
endAngle = 3.141592
Set outerLoop(0) = ThisDrawing.ModelSpace. _
AddArc(center, radius, startAngle, endAngle)
Set outerLoop(1) = ThisDrawing.ModelSpace. _
AddLine(outerLoop(0).startPoint, outerLoop(0).endPoint)
' Append the outer loop to the hatch object
hatchObj.AppendOuterLoop (outerLoop)
' Create a circle as the inner loop for the hatch.
Dim innerLoop(0) As AcadEntity
center(0) = 5: center(1) = 4.5: center(2) = 0
radius = 1
Set innerLoop(0) = ThisDrawing.ModelSpace. _
AddCircle(center, radius)
' Append the circle as an inner loop to the hatch
hatchObj.AppendInnerLoop (innerLoop)
' Evaluate and display the hatch
hatchObj.Evaluate
ThisDrawing.Regen True
End Sub

Edit Hatch Patterns

You can change the angle or spacing of an existing hatch pattern or replace
it with a solid-fill or one of the predefined patterns that AutoCAD offers. The
Pattern option in the Boundary Hatch dialog box displays a list of these patterns. To reduce file size, the hatch is defined in the drawing as a single
graphic object.
Use the following properties and methods to edit the hatch patterns:
PatternAngle

Specifies the angle of the hatch pattern.

PatternDouble

Specifies if the user-defined hatch is double-hatched.

PatternName

Specifies the hatch pattern name (does not change the

pattern type).

PatternScale

Specifies the hatch pattern scale.

PatternSpace

Specifies the user-defined hatch pattern spacing.

SetPattern

Sets the pattern name and pattern type for the hatch.

Change the pattern spacing of a hatch

This example creates a hatch. It then adds two to the current pattern
spacing for the hatch.

Sub Ch4_ChangeHatchPatternSpace()
Dim hatchObj As AcadHatch
Dim patternName As String
Dim PatternType As Long
Dim bAssociativity As Boolean
' Define the hatch
patternName = "ANSI31"
PatternType = 0
bAssociativity = True
' Create the associative Hatch object
Set hatchObj = ThisDrawing.ModelSpace. _
AddHatch(PatternType, patternName, bAssociativity)
' Create the outer loop for the hatch.
Dim outerLoop(0 To 0) As AcadEntity
Dim center(0 To 2) As Double
Dim radius As Double
center(0) = 5
center(1) = 3
center(2) = 0
radius = 3
Set outerLoop(0) = ThisDrawing.ModelSpace. _
AddCircle(center, radius)
hatchObj.AppendOuterLoop (outerLoop)
hatchObj.Evaluate
' Change the spacing of the hatch pattern by
' adding 2 to the current spacing
hatchObj.patternSpace = hatchObj.patternSpace + 2
hatchObj.Evaluate
ThisDrawing.Regen True
End Sub

Use Layers, Colors, and

Linetypes
Layers are like transparent overlays on which you organize and group different kinds of drawing information. The objects you create have properties
including layers, colors, and linetypes. Color helps you distinguish similar
elements in your drawings, and linetypes help you differentiate easily
between different drafting elements, such as centerlines or hidden lines.
Organizing layers and objects on layers makes it easier to manage the information in your drawings.
For more information about this topic, see Control the Properties of
Objects, in the Users Guide.

Work with Layers

You are always drawing on a layer. It may be the default layer or a layer you
create and name yourself. Each layer has an associated color and linetype.
For example, you can create a layer on which you draw only centerlines and
assign the color blue and the linetype CENTER to that layer. Then, whenever
you want to draw centerlines you can switch to that layer and start drawing.
All layers and linetypes are kept within their parent Collection objects.
Layers are kept within the Layers collection, and linetypes are kept within
the Linetypes collection.
For more information about working with layers, see Work with Layers in
the Users Guide.

Sort Layers and Linetypes

You can iterate through the Layers and Linetypes collections to find all the
layers and linetypes in a drawing.
Iterate through the Layers collection
The following code iterates through the Layers collection to gather the
names of all the layers in the drawing. The names are then displayed in a
message box.
Sub Ch4_IteratingLayers()
Dim layerNames As String
Dim entry As AcadLayer
layerNames = ""
For Each entry In ThisDrawing.Layers
layerNames = layerNames + entry.Name + vbCrLf
Next
MsgBox "The layers in this drawing are: " + _
vbCrLf + layerNames
End Sub

Create and Name Layers

You can create new layers and assign color and linetype properties to those
layers. Each individual layer is part of the Layers collection. Use the Add
method to create a new layer and add it to the Layers collection.
You can assign a name to a layer when it is created. To change the name of
a layer after it has been created, use the Name property. Layer names can
include up to thirty-one characters and contain letters, digits, and the
special characters dollar sign ($), hyphen (), and underscore (_) but cannot
include blank spaces.

Use Layers, Colors, and Linetypes

| 133

For more information about creating layers, see Create and Name Layers
in the Users Guide.
Create a new layer, assign it the color red, and add an object to the layer
The following code creates a circle and a new layer. The new layer is
assigned the color red. The circle is assigned to the layer, and the color of
the circle changes accordingly.
Sub Ch4_NewLayer()
' Create a circle
Dim circleObj As AcadCircle
Dim center(0 To 2) As Double
Dim radius As Double
center(0) = 2: center(1) = 2: center(2) = 0
radius = 1
Set circleObj = ThisDrawing.ModelSpace. _
AddCircle(center, radius)
' Assign the circle the color "ByLayer" so
' that the circle will automatically pick
' up the color of the layer on which it resides
circleObj.Color = acByLayer
' Create a new layer called "ABC"
Dim layerObj As AcadLayer
Set layerObj = ThisDrawing.Layers.Add("ABC")
' Assign the "ABC" layer the color red
layerObj.Color = acRed
' Assign the circle to the "ABC" layer
circleObj.Layer = "ABC"
circleObj.Update
End Sub

Make a Layer Active

You are always drawing on the active layer. When you make a layer active,
you can create new objects on that layer. If you make a different layer
active, any new objects you create are created on that new active layer and
use its color and linetype. You cannot make a layer active if it is frozen.
To make a layer active, use the ActiveLayer property. This property is set on
the current drawing. For example
Dim newlayer As AcadLayer
Set newlayer = ThisDrawing.Layers.Add("LAYER1")
ThisDrawing.ActiveLayer = newlayer

134 | Chapter 4 Create and Edit AutoCAD

Entities

Turn Layers On and Off

Turned-off layers are regenerated with the drawing but are not displayed or
plotted. By turning layers off, you avoid regenerating the drawing every
time you thaw a layer. When you turn a layer on that has been turned off,
AutoCAD redraws the objects on that layer.
To turn layers on and off, use the LayerOn property. If you input a value of
TRUE to this property, the layer is turned on. If you input a value of FALSE,
the layer is turned off.
For more information about turning layers on and off, see Control the Visibility of Objects on a Layer in the Users Guide.
Turn off a layer
This example creates a new layer, adds a circle to the layer, then turns off the
layer so that the circle is no longer visible.
Sub Ch4_LayerInvisible()
' Create a circle
Dim circleObj As AcadCircle
Dim center(0 To 2) As Double
Dim radius As Double
center(0) = 2: center(1) = 2: center(2) = 0
radius = 1
Set circleObj = ThisDrawing.ModelSpace. _
AddCircle(center, radius)
circleObj.Color = acByLayer
' Create a new layer called "ABC"
Dim layerObj As AcadLayer
Set layerObj = ThisDrawing.Layers.Add("ABC")
layerObj.Color = acRed
' Assign the circle to the "ABC" layer
circleObj.Layer = "ABC"
circleObj.Update
' Turn off layer "ABC"
layerObj.LayerOn = False
ThisDrawing.Regen acActiveViewport
End Sub

Freeze and Thaw Layers

You can freeze layers to speed up display changes, improve object selection
performance, and reduce regeneration time for complex drawings. AutoCAD
does not display, plot, or regenerate objects on frozen layers. Freeze layers
that you want to be invisible for long periods. When you thaw a frozen
layer, AutoCAD regenerates and displays the objects on that layer.

Use Layers, Colors, and Linetypes

| 135

To freeze or thaw a layer, use the Freeze property. If you input a value of
TRUE to this property, the layer is frozen. If you input a value of FALSE, the
layer is thawed.
For more information about freezing and thawing layers, see Control the
Visibility of Objects on a Layer in the Users Guide.
Freeze a layer
This example creates a new layer called ABC and then freezes the layer.
Sub Ch4_LayerFreeze()
' Create a new layer called "ABC"
Dim layerObj As AcadLayer
Set layerObj = ThisDrawing.Layers.Add("ABC")
' Freeze layer "ABC"
layerObj.Freeze = True
End Sub

Lock and Unlock Layers

You cannot edit the objects on a locked layer; however, they are still visible
if the layer is on and thawed. You can make a locked layer current and you
can add objects to it. You can freeze and turn off locked layers and change
their associated colors and linetypes.
To lock or unlock a layer, use the Lock property. If you input a value of TRUE
to this property, the layer is locked. If you input a value of FALSE, the layer is
unlocked.
For more information about locking and unlocking layers, see Control
Whether Objects on a Layer Can Be Modified in the Users Guide.
Lock a layer
This example creates a new layer called ABC and then locks the layer.
Sub Ch4_LayerLock()
' Create a new layer called "ABC"
Dim layerObj As AcadLayer
Set layerObj = ThisDrawing.Layers.Add("ABC")
' Lock layer "ABC"
layerObj.Lock = True
End Sub

Assign Color to a Layer

You can assign color to a layer. When specifying a color, you can enter the
name of the color or its AutoCAD Color Index (ACI) number. Standard
color names are available only for colors 1 to 7.

136 | Chapter 4 Create and Edit AutoCAD

Entities

By default, AutoCAD assigns color number 7 (white or black, depending on

your drawing background) to newly created layers. You can assign an object
a color that is different from the layer color.
To assign color to a layer, use the Color property.
Colors can be set and read as numeric index values ranging from 0 to 256.
Constants have been provided for the standard seven colors, and
BYBLOCK and BYLAYER designations.
If you use acByBlock, AutoCAD draws new objects in the default color
(white or black, depending on your configuration) until they are grouped
into the block. When the block is inserted in the drawing, the objects in the
block inherit the current setting of the Color property.
If you use acByLayer, new objects assume the color of the layer upon which
they are drawn.

Assign a Linetype to a Layer

When youre defining layers, linetypes provide another way to convey
visual information. A linetype is a repeating pattern of dashes, dots, and
blank spaces you can use to distinguish the purpose of one line from
another.
The linetype name and definition describe the
particular dash-dot
sequence, the relative lengths of dashes and blank spaces, and the
characteristics of any included text or shapes.
To assign a linetype to a layer, use the Linetype property. This property
takes the name of the linetype as input.
See also Work with Linetypes on page 139.

Delete Layers
To delete a layer, use the Delete method.
You can delete a layer at any time during a drawing session. You cannot
delete the current layer, layer 0, an xref-dependent layer, or a layer that contains objects.

Note

Layers referenced by block definitions, along with the special

layer named DEFPOINTS, cannot be deleted even if they do not contain
visible objects.

Use Layers, Colors, and Linetypes

| 137

Work with Colors

You can assign true colors to individual objects in a drawing using the
AcCmColor object. Using an RGB value in the AcCmColor object, you can
choose from millions of colors when you set the color of lines, circles, and
other individual objects. The AcCmColor object also contains methods and
properties for specifying color names, color books, color indexes, color
values, and color methods.
You can also assign colors to layers. Each color is identified by a name or an
AutoCAD Color Index (ACI) number, an integer from 1 through 255. Any
number of objects and layers can have the same color number. You can
assign each color number to a different pen on a pen plotter or use the
color num- bers to identify certain objects in the drawing, even though you
cant see the colors on your screen.
When specifying a color, you can enter the name of the color or its ACI
num- ber. The ACI provides 255 color numbers. Standard color names are
available only for colors 1 to 7.
Colors 1 to 7
Color number

Color name

Red

Yellow

Green

Cyan

Blue

Magenta

Black/White

Colors 8 to 255 must be assigned by a number or by selecting the color in a

dialog box. The default color (7) is either white or black, depending on your
background color.
For more information about working with colors, see Work with Colors in
the Users Guide.

138 | Chapter 4 Create and Edit AutoCAD

Entities

Work with Linetypes

A linetype is a repeating pattern of dashes, dots, and blank spaces. A
complex linetype is a repeating pattern of symbols. To use a linetype you
must first load it into your drawing. A linetype definition must exist in a
LIN library file before a linetype can be loaded into a drawing. To load a
linetype into your drawing, use the Load method.
For more information about working with linetypes, see Overview of Linetypes in the Users Guide.

Note The linetypes used internally by AutoCAD should not be confused with
the hardware linetypes provided by some plotters. The two types of dashed
lines produce similar results. Do not use both types at the same time, however,
because the results can be unpredictable.
Load a linetype into AutoCAD
This example attempts to load the linetype CENTER from the acad.lin file.
If the linetype already exists, or the file does not exist, then a message is
displayed.
Sub Ch4_LoadLinetype()
On Error GoTo ERRORHANDLER
Dim linetypeName As String
linetypeName = "CENTER"
' Load "CENTER" line type from acad.lin file
ThisDrawing.Linetypes.Load linetypeName, "acad.lin"
Exit Sub
ERRORHANDLER:
MsgBox Err.Description
End Sub

Make a Linetype Active

To use a linetype to draw on the current layer, you must make it active. All
newly created objects are drawn using the active linetype.

Note Xref-dependent linetypes cannot be made active.

To make a linetype active, use the ActiveLinetype property. This property is
set on the current drawing. For example

Use Layers, Colors, and Linetypes

| 139

ThisDrawing.ActiveLinetype = ThisDrawing. _
Linetypes.Item("CONTINUOUS")

For more information about activating a linetype, see Set the Current Linetype in the Users Guide.

Rename Linetypes
To rename a linetype, use the Name property. When you rename a linetype,
you are renaming only the linetype definition in your drawing. The name in
the LIN library file is not being updated to reflect the new name.

Delete Linetypes
To delete a linetype, use the Delete method. You can delete a linetype at any
time during a drawing session; however, linetypes that cannot be deleted
include BYLAYER, BYBLOCK, CONTINUOUS, the current linetype, and xrefdependent linetypes. Also, linetypes referenced by block definitions cannot
be deleted, even if they are not used by any objects.
For more information about deleting linetypes, see Load Linetypes in the
Users Guide.

Change Linetype Descriptions

Linetypes can have a description associated with them. The description provides an ASCII representation of the linetype. You can assign or change a
linetype description by using the Description property.
A linetype description can have up to forty-seven characters. The
description can be a comment or a series of underscores, dots, dashes, and
spaces to show a simple representation of the linetype pattern. For example
ThisDrawing.ActiveLinetype.Description = "Exterior Wall"

Specify Linetype Scale

You can specify the linetype scale for objects you create. The smaller the
scale, the more repetitions of the pattern are generated per drawing unit. By
default, AutoCAD uses a global linetype scale of 1.0, which is equal to one
drawing unit. You can change the linetype scale for all drawing objects,
attribute references, and groups.
To change the linetype scale, use the LinetypeScale property.
The CELTSCALE system variable sets the linetype scale for newly created
objects. LTSCALE globally changes the linetype scale of existing objects as
well as new objects. To change the values of system variables using
AutoCAD ActiveX Automation, use the SetVariable method.

140 | Chapter 4 Create and Edit AutoCAD

Entities

For more information about linetype scales, see Control Linetype Scale in
the Users Guide.
Change the linetype scale for a circle
Sub Ch4_ChangeLinetypeScale()
' Save the current linetype
Set currLineType = ThisDrawing.ActiveLinetype
' Change the active linetype to Border, so the scale change will
' be visible.
' First see if the Border linetype is already loaded
On Error Resume Next
'Turn on error trapping
ThisDrawing.ActiveLinetype = ThisDrawing.Linetypes.Item("BORDER")
If Err.Number = -2145386476 Then
' Error indicates linetype is not currently loaded, so load it.
ThisDrawing.Linetypes.Load "BORDER", "acad.lin"
ThisDrawing.ActiveLinetype = _
ThisDrawing.Linetypes.Item("BORDER")
End If
On Error GoTo 0
'Turn off error trapping
' Create a circle object in model space
Dim center(0 To 2) As Double
Dim radius As Double
Dim circleObj As AcadCircle
center(0) = 2
center(1) = 2
center(2) = 0
radius = 4
Set circleObj = ThisDrawing.ModelSpace.AddCircle(center, radius)
circleObj.Update
MsgBox ("Here is the circle with the original linetype")
' Set the linetype scale of a circle to 3
circleObj.LinetypeScale = 3#
circleObj.Update
MsgBox ("Here is the circle with the new linetype")
' Restore original active linetype
ThisDrawing.ActiveLinetype = currLineType
End Sub

Assign Layers, Colors, and Linetypes to

Objects
Once youve defined layers, colors, and linetypes, you can assign them to
objects in your drawing. You can group associated components of a drawing
by assigning objects to layers. You can control layer visibility, color, and linetype and specify whether objects on a layer can be edited. You can move
objects from one layer to another and change the name of a layer.

Use Layers, Colors, and Linetypes

| 141

The number of layers in a drawing and the number of objects per layer are
virtually unlimited. You can assign a name to each layer and select any combination of layers for display.
You can define blocks from objects that were originally drawn on different
layers with different colors and linetypes. You can preserve the layer, color,
and linetype information of objects in a block. Then, each time you insert
the block, you have each object drawn on its original layer with its original
color and linetype.

Change an Objects Layer

Once you have created an object and assigned layer, color, and linetype
prop- erties to it, you may wish to change the objects layer. Changing an
objects layer is useful if you accidentally create an object on the wrong layer
or decide to change your layer organization later.
To change an objects layer, use the Layer property provided for that object.
The Layer property takes the name of the layer as input.
Move an object to a different layer
This example creates a circle on the active layer and then creates a new layer
called ABC. It then moves the circle to the new layer.
Sub Ch4_MoveObjectNewLayer()
' Create a circle
Dim circleObj As AcadCircle
Dim center(0 To 2) As Double
Dim radius As Double
center(0) = 2: center(1) = 2: center(2) = 0
radius = 1
Set circleObj = ThisDrawing.ModelSpace. _
AddCircle(center, radius)
' Create a new layer called "ABC"
Dim layerObj As AcadLayer
Set layerObj = ThisDrawing.Layers.Add("ABC")
' Assign the circle to the "ABC" layer
circleObj.Layer = "ABC"
circleObj.Update
End Sub

Change an Objects Color

To change an objects color, use the TrueColor property provided for that
object. You can assign colors to individual objects in a drawing. Each color
is identified by an AcCmColor object. This object can hold an RGB value,
an ACI number (an integer from 1 to 255), or a named color. Using an RGB
value, you can choose from millions of colors.

142 | Chapter 4 Create and Edit AutoCAD

Entities

Setting a color for the object overrides the color setting for the layer on
which the object resides. If you want to retain an object on a specific layer
but you dont want it to keep the color of that layer, you can change the
objects color.
Change the color of a circle
This example creates a circle and then colors the circle blue.
Sub Ch4_ColorCircle()
Dim color As AcadAcCmColor
Set color = _
AcadApplication.GetInterfaceObject("AutoCAD.AcCmColor.16")
Call color.SetRGB(80, 100, 244)
Dim circleObj As AcadCircle
Dim centerPoint(0 To 2) As Double
Dim radius As Double
centerPoint(0) = 0#: centerPoint(1) = 0#: centerPoint(2) = 0#
radius = 5#
Set circleObj = _
ThisDrawing.ModelSpace.AddCircle(centerPoint, radius)
circleObj.TrueColor = color
ZoomAll
End Sub

Change an Objects Linetype

By default, objects inherit the linetype of the layer on which they are
created. To change an objects linetype, use the Linetype property provided
for that object. The Linetype property takes the name of the linetype to
assign to the object as input.

Note Before you can assign a linetype to an object, the linetype must be
loaded into the current drawing. To load a linetype into the drawing, use the
Load method.
For more information about linetypes, see Overview of Linetypes in the
Users Guide.
Change the linetype of a circle
This example creates a circle. It then attempts to load the linetype CENTER
from the acad.lin file. If the linetype already exists, or the file does not exist,
then a message is displayed. Finally, it sets the linetype for the circle to be
CENTER.

Use Layers, Colors, and Linetypes

| 143

Sub Ch4_ChangeCircleLinetype()
On Error Resume Next
' Create a circle
Dim circleObj As AcadCircle
Dim center(0 To 2) As Double
Dim radius As Double
center(0) = 2: center(1) = 2: center(2) = 0
radius = 1
Set circleObj = ThisDrawing.ModelSpace. _
AddCircle(center, radius)
Dim linetypeName As String
linetypeName = "CENTER"
' Load "CENTER" line type from acad.lin file
ThisDrawing.Linetypes.Load linetypeName, "acad.lin"
If Err.Description <> "" Then MsgBox Err.Description
' Assign the circle the linetype "CENTER"
circleObj.Linetype = "CENTER"
circleObj.Update
End Sub

Save and Restore Layer Settings

You can save layer settings in a drawing and restore them later. This makes
it easy to return to specified settings for all layers during different stages
when completing a drawing or when plotting a drawing.
Layer settings include whether or not a layer is turned on, frozen, locked,
plotted, and automatically frozen in new viewports, and the layers color,
linetype, lineweight, and plot style. You can specify which settings you
want to save, and you can save different groups of settings for a drawing.
A special object, the LayerStateManager, provides functions for working
with layer settings using ActiveX.
For more information about saving layer settings, see Save and Restore Layer
Settings in the Users Guide.

Understand How AutoCAD Saves Layer

Settings
AutoCAD saves layer setting information in an extension dictionary in a
drawings Layers collection. When you first save layer settings in a drawing,
AutoCAD does the following:

144 | Chapter 4 Create and Edit AutoCAD

Entities

Creates an extension dictionary in the Layers collection.

Creates a Dictionary object named ACAD_LAYERSTATE in the
extension dictionary.
Stores the properties of each layer in the drawing in an XRecord object
in the ACAD_LAYERSTATE dictionary. AutoCAD stores all layer settings in
the XRecord, but identifies the specific settings you chose to save. When
you restore the layer settings, AutoCAD restores only the settings you
chose to save.

Each time you save another layer setting in the drawing, AutoCAD creates
another XRecord object describing the saved settings and stores the XRecord
in the ACAD_LAYERSTATE dictionary. The following diagram illustrates the
process.
AutoCAD Document
Object

Layers Collection

ACAD_LAYERSTATE
Ext Dictionary

layer1

layer2

layer3

Dictionary Object

COLOR_LINETYPE
layer settings
PLOTSTYLE_LINEWEIGHT
layer settings

XRecord
XRecord

You do not need (and should not try) to interpret XRecords when
working with layer settings using ActiveX. Use the functions of the
LayerStateMan- ager object to access saved layer settings.
List the saved layer settings in a drawing
If layer settings have been saved in the current drawing, the following code
lists the names of all saved layer settings:

Save and Restore Layer

Settings | 145

Sub Ch4_ListStates()
On Error Resume Next
Dim oLSMDict As AcadDictionary
Dim XRec As Object
Dim layerstateNames As String
layerstateNames = ""
' Get the ACAD_LAYERSTATES dictionary, which is in the
' extension dictionary in the Layers object.
Set oLSMDict = ThisDrawing.Layers. _
GetExtensionDictionary.Item("ACAD_LAYERSTATES")
' List the name of each saved layer setting. Settings are
' stored as XRecords in the dictionary.
For Each XRec In oLSMDict
layerstateNames = layerstateNames + XRec.Name + vbCrLf
Next XRec
MsgBox "The saved layer settings in this drawing are: " + _
vbCrLf + layerstateNames
End Sub

Use the LayerStateManager to Manage

Layer
Settings
The LayerStateManager object is similar to the AutoCAD Utility object in that
it provides a set of functions for manipulating data. These functions are
methods for working with saved layer settings. Use the following
LayerState- Manager methods to work with saved layer settings:
Delete

Deletes a saved layer setting.

Export

Exports the specified saved layer setting to a file.

Import

Imports a saved layer setting from the specified file.

Rename

Renames a saved layer setting.

Restore

Restores the specified layer setting in the current

drawing.

Save

Saves the specified layer states and properties.

SetDataBase

Associates an AutoCAD database with the

LayerStateManager.

To access the LayerStateManager object, use the GetInterfaceObject method.

Dim oLSM As AcadLayerStateManager
Set oLSM = ThisDrawing.Application. _
GetInterfaceObject("AutoCAD.AcadLayerStateManager.16")

After you retrieve the LayerStateManager object, you must associate a database with it before you can access the objects methods. Use the
SetDatabase method to associate a database with the LayerStateManager.
oLSM.SetDatabase ThisDrawing.Database

Save Layer Settings

Use the Save method to save a set of layer settings in a drawing. The Save
method accepts two parameters. The first parameter is a string naming the
layer settings you are saving. The second parameter identifies the layer properties you want to save. Use the constants in the following table to identify
layer properties.
Constants for layer
properties Constant name Layer
property acLsAll

All layer settings

acLsColor

Color

acLsFrozen

Frozen or thawed

acLsLineType

Linetype

acLsLineWeight

Lineweight

acLsLocked

Locked or unlocked

acLsNewViewport

New viewport layers frozen or thawed

acLsNone

None

acLsOn

On or off

acLsPlot

Plotting on or off

acLsPlotStyle

Plot style

Add the constants together to specify multiple properties.

If you try to save layer settings under a name that already exists, an error is
returned. You must rename or delete the existing saved layer settings
before you can reuse the name.

Save a layers color and linetype settings

The following code saves the color and linetype settings of the current layer
under the name ColorLinetype.
Sub Ch4_SaveLayerColorAndLinetype()
Dim oLSM As AcadLayerStateManager
' Access the LayerStateManager object
Set oLSM = ThisDrawing.Application. _
GetInterfaceObject("AutoCAD.AcadLayerStateManager.16")
' Associate the current drawing database with LayerStateManager
oLSM.SetDatabase ThisDrawing.Database
oLSM.Save "ColorLinetype", acLsColor + acLsLineType
End Sub

Rename a saved layer setting

The following code renames the ColorLinetype layer settings to
OldColor- Linetype.
Sub Ch4_RenameLayerSettings()
Dim oLSM As AcadLayerStateManager
Set oLSM = ThisDrawing.Application. _
GetInterfaceObject("AutoCAD.AcadLayerStateManager.16")
oLSM.SetDatabase ThisDrawing.Database
oLSM.Rename "ColorLinetype", "OldColorLinetype"
End Sub

Delete a saved layer setting

The following code deletes layer settings that were saved under the name
ColorLinetype.
Sub Ch4_DeleteColorAndLinetype()
Dim oLSM As AcadLayerStateManager
Set oLSM = ThisDrawing.Application. _
GetInterfaceObject("AutoCAD.AcadLayerStateManager.16")
oLSM.SetDatabase ThisDrawing.Database
oLSM.Delete "ColorLinetype"
End Sub

Restore Layer Settings

The Restore method resets all layer settings in the current drawing to values
that were saved earlier. For example, if you save the drawings color and linetype settings under the name ColorLinetype and subsequently change
those settings, restoring ColorLinetype resets the layers to the colors and
linetypes they had when ColorLinetype was saved. If you add new layers
to the drawing after saving ColorLinetype, those new layers are not
affected when you restore ColorLinetype.

Restore the color and linetype settings of a drawings layers

Assuming that the color and linetype settings of the layers in the current
drawing were previously saved under the name ColorLinetype, the following code resets the color and linetype settings of each layer in the drawing to
the value they had when ColorLinetype was saved.
Sub Ch4_RestoreLayerSettings()
Dim oLSM As AcadLayerStateManager
Set oLSM = ThisDrawing.Application. _
GetInterfaceObject("AutoCAD.AcadLayerStateManager.16")
oLSM.SetDatabase ThisDrawing.Database
oLSM.Restore "ColorLinetype"
End Sub

Export and Import Saved Layer Settings

You can export and import saved layer settings to use those settings in
other drawings. Use the LayerStateManagers Export method to save layer
settings to a file; use the Import method to import saved layer settings into a
drawing.

Note Importing layer settings does not restore them; you must use the
Restore method to set the layers in your drawing to the imported settings.
The Export method accepts two parameters. The first parameter is a string
identifying the saved layer settings you are exporting. The second parameter
is the name of the file you are exporting the settings to. If you do not
specify a path for the file, it is saved in the AutoCAD installation directory.
If the file name you specified already exists, the existing file is overwritten.
Use a .las extension when naming files; this is the extension AutoCAD
recognizes for exported layer setting files.
The Import method accepts one parameter: a string naming the file that contains the layer settings you are importing.
When you are importing layer settings, an error condition is raised if any
properties referenced in the saved settings are not available in the drawing
youre importing to. The import is completed, however, and default properties are used. For example, if an exported layer is set to a linetype that is not
loaded in the drawing it is being imported into, an error condition is raised
and the drawings default linetype is substituted. Your code should account
for this error condition and continue processing if it is raised.
If the imported file defines settings for layers that do not exist in the
current drawing, those layers are created in the current drawing. When you
use the Restore method, the properties specified when the settings were
saved are assigned to the new layers; all other properties of the new layers
are assigned default settings.

Export saved layer settings

The following code exports saved layer settings to a file named Colortype.las.
Sub Ch4_ExportLayerSettings()
Dim oLSM As AcadLayerStateManager
Set oLSM = ThisDrawing.Application. _
GetInterfaceObject("AutoCAD.AcadLayerStateManager.16")
oLSM.SetDatabase ThisDrawing.Database
oLSM.Export "ColorLinetype", "c:\my documents\ColorLType.las"
End Sub

Import saved layer settings

The following code imports layer settings from a file named Colortype.las.
Sub Ch4_ImportLayerSettings()
Dim oLSM As AcadLayerStateManager
Set oLSM = ThisDrawing.Application. _
GetInterfaceObject("AutoCAD.AcadLayerStateManager.16")
oLSM.SetDatabase ThisDrawing.Database
' If the drawing you're importing to does not contain
' all the linetypes referenced in the saved settings,
' an error is returned. The import is completed, though,
' and the default linetype is used.
On Error Resume Next
oLSM.Import "c:\my documents\ColorLType.las"
If Err.Number = -2145386359 Then
' Error indicates a linetype is not defined
MsgBox ("One or more linetypes specified in the imported " +
_
"settings is not defined in your drawing")
End If
On Error GoTo 0
End Sub

Add Text to
Drawings
Text conveys important information in your drawing. Use text for title
blocks, to label parts of the drawing, to give specifications, or to make
annotations.
AutoCAD provides various ways to create text. For short, simple entries, use
line text. For longer entries with internal formatting, use multiline text
(mtext). Although all entered text uses the current text style, which establishes the default font and format settings, you can use several methods to
customize the text appearance.
For more information about working with text, see Notes and Labels, in
the Users Guide.

Work with Text Styles

All text in an AutoCAD drawing has a style associated with it. When you
enter text, AutoCAD uses the current text style, which sets the font, size,
angle, orientation, and other text characteristics. You can use or modify the
default style or create and load a new style. Once youve created a style, you
can modify its attributes or delete it when you no longer need it.
For more information about text styles, see Work with Text Styles in the
Users Guide.

Create and Modify Text Styles

New text inherits height, width factor, obliquing angle, and text generation
properties from the current text style. To create a text style, use the Add
method to create a new TextStyle object and add it to the TextStyles collection. The Add method takes a TextStyle name as input. Once created, you
cannot change the name of a text style through AutoCAD ActiveX
Automation.
Style names can contain letters, numbers, and the special characters dollar
sign ($), underscore (_), and hyphen (). AutoCAD converts the characters to
uppercase. If you dont enter a style name, AutoCAD automatically names
the style Stylen, where n is a number that starts at 1. Each new style is
shown in increments of 1.
You can modify an existing style by changing the properties of the
TextStyle object. You can also update existing text of that style type to
reflect the changes. Use the following properties to modify a TextStyle
object:
FontFile

Specifies the file associated with a font (character style).

BigFontFile

Specifies the special shape definition file used for a nonASCII character set.

Height

Specifies the character height.

Width

Specifies the expansion or compression of the

characters.

ObliqueAngle

Specifies the slant of the characters.

TextGenerationFlag
Specifies backward text, upside-down text, or both.

Add Text to Drawings

151

If you change an existing styles font or orientation, all text using that style
is changed to use the new font or orientation. Changing text height, width
factor, and oblique angle does not change existing text but does change subsequently created text objects.

Note You must call the Regen or Update methods to see any changes to
the above properties.
For more information about creating text styles, see Create and Modify Text
Styles in the Users Guide.

Assign Fonts
Fonts define the shapes of the text characters that make up each character
set. A single font can be used by more than one style. To assign a font to a
text style, use the FontFile property of the TextStyle object. By entering the
font file containing an AutoCAD-compiled SHX font, you assign that font to
the text style.
For more information about assigning fonts to text styles, see Assign Text
Fonts in the Users Guide.
Set text fonts
This example gets the current font values for the active text style and then
changes the typeface for the font to PlayBill. The new font is then set
using the SetFont method. To see the effects of changing the typeface, add
some MText or Text to your current drawing before running the example.
Note that, if you dont have the PlayBill font on your system, you need to
substi- tute a font you do have in order for this example to work.

152 | Chapter 4 Create and Edit AutoCAD

Entities

Sub Ch4_UpdateTextFont()
MsgBox ("Look at the text now...")
Dim
Dim
Dim
Dim
Dim
Dim

typeFace As String
SavetypeFace As String
Bold As Boolean
Italic As Boolean
charSet As Long
PitchandFamily As Long

' Get the current settings to fill in the

' default values for the SetFont method
ThisDrawing.ActiveTextStyle.GetFont typeFace, _
Bold, Italic, charSet, PitchandFamily
' Change the typeface for the font
SavetypeFace = typeFace
typeFace = "PlayBill"
ThisDrawing.ActiveTextStyle.SetFont typeFace, _
Bold, Italic, charSet, PitchandFamily
ThisDrawing.Regen acActiveViewport
MsgBox ("Now see how it looks after changing the font...")
'Restore the original typeface
ThisDrawing.ActiveTextStyle.SetFont SavetypeFace, _
Bold, Italic, charSet, PitchandFamily
ThisDrawing.Regen acActiveViewport
End Sub

Use
Fonts

TrueType

TrueType fonts always appear filled in your drawing, however, when you
plot, the TEXTFILL system variable controls whether the fonts are filled. By
default TEXTFILL is set to 1 to plot the filled-in fonts. When you export the
drawing to PostScript format with the Export method and print it on
a
PostScript device, the font is plotted as designed.
For more information about using TrueType fonts, see Assign Text Fonts
in the Users Guide.

Use Unicode and Big

Fonts
AutoCAD supports the Unicode character-encoding standard. A Unicode
font can contain 65,535 characters, with shapes for many languages. All
AutoCAD SHX shape fonts are now Unicode fonts.
The text files for some alphabets contain thousands of non-ASCII characters.
To accommodate such text, AutoCAD supports a special type of shape
defini- tion known as a Big Font file. You can set a style to use both regular
and Big Font files. Specify normal fonts using the FontFile property. Specify
Big Fonts using the BigFontFile property.

Add Text to Drawings

153

Note Font file names cannot contain commas.

AutoCAD provides ways to substitute one font for another or to specify a
default font. For more information see Substitute Fonts on page 166.
For more information about using Unicode and Big Fonts, see Assign Text
Fonts in the Users Guide.
Change font files
This example changes the FontFile and BigFontFile properties. You need to
replace the path information listed in this example with path and file
names appropriate for your system.
Sub Ch4_ChangeFontFiles()
ThisDrawing.ActiveTextStyle.BigFontFile = _
"C:/AutoCAD/Fonts/bigfont.shx"
ThisDrawing.ActiveTextStyle.fontFile = _
"C:/AutoCAD/Fonts/italic.shx"
End Sub

Set Text Height

Text height determines the size in drawing units of the letters in the font
you are using. The value usually represents the size of the uppercase letters,
with the exception of TrueType fonts.
For TrueType fonts, the value specified for text height might not represent
the height of uppercase letters. The height specified represents the height of
a capital letter plus an accent area reserved for accent marks and other marks
used in non-English languages. The relative portion of areas assigned to capital letters and accent characters is determined by the font designer at the
time the font is designed, and, consequently, will vary from font to font.
In addition to the height of a capital letter and the ascent area that make up
the height specified by the user, TrueType fonts have a descent area for portions of characters that extend below the text insertion line. Examples of
such characters are y, j, p, g, and q.
You specify the text height using the Height property. This property
accepts positive numbers only.
For more information about setting text height, see Set Text Height in the
Users Guide.
Change the height of a Text object
This example creates a line of text and then changes the height of the text.

154 | Chapter 4 Create and Edit AutoCAD

Entities

Sub Ch4_ChangeTextHeight()
Dim textObj As AcadText
Dim textString As String
Dim insertionPoint(0 To 2) As Double
Dim height As Double
' Define the text object
textString = "Hello, World."
insertionPoint(0) = 3
insertionPoint(1) = 3
insertionPoint(2) = 0
height = 0.5
' Create the text object in model space
Set textObj = ThisDrawing.ModelSpace. _
AddText(textString, insertionPoint, height)
' Change the value of the Height to 1
textObj.height = 1
textObj.Update
End Sub

Set Obliquing Angle

The obliquing angle determines the forward or backward slant of the text.
The angle represents the offset from its vertical axis (90 degrees). To set the
obliquing angle, use the ObliqueAngle property. The obliquing angle must
be provided in radians. A positive angle denotes a lean to the right, a
negative value will have 2*PI added to it to convert it to its positive
equivalent.
For more information about the oblique angle, see Set Text Obliquing
Angle in the Users Guide.
Create oblique text
This example creates a Text object then slants the text 45 degrees.

Add Text to Drawings

155

Sub Ch4_ObliqueText()
Dim textObj As AcadText
Dim textString As String
Dim insertionPoint(0 To 2) As Double
Dim height As Double
' Define the text object
textString = "Hello, World."
insertionPoint(0) = 3
insertionPoint(1) = 3
insertionPoint(2) = 0
height = 0.5
' Create the text object in model space
Set textObj = ThisDrawing.ModelSpace. _
AddText(textString, insertionPoint, height)
' Change the value of the ObliqueAngle
' to 45 degrees (.707 radians)
textObj.ObliqueAngle = 0.707
textObj.Update
End Sub

Set Text Generation Flag

The text generation flag specifies if the text is displayed backward or upsidedown. To set the text generation flag, use the TextGenerationFlag property.
To make the text display backward, enter acTextFlagBackward for this
prop- erty. To make the text display upside-down, enter
acTextFlagUpsideDown for this property. To make the text display both
backward and upside-down, add the two constants together by entering
acTextFlagBackward+acTextFlagUpsidedown for this property.
Display text backward
This example creates a line of text, then sets it to display backward using the
TextGenerationFlag property.

156 | Chapter 4 Create and Edit AutoCAD

Entities

Sub Ch4_ChangingTextGenerationFlag()
Dim textObj As AcadText
Dim textString As String
Dim insertionPoint(0 To 2) As Double
Dim height As Double
' Create the text object
textString = "Hello, World."
insertionPoint(0) = 3
insertionPoint(1) = 3
insertionPoint(2) = 0
height = 0.5
Set textObj = ThisDrawing.ModelSpace. _
AddText(textString, insertionPoint, height)
' Change the value of the TextGenerationFlag
textObj.TextGenerationFlag = acTextFlagBackward
textObj.Update
End Sub

Use Line Text (Text)

The text you add to your drawings conveys a variety of information. It may
be a complex specification, title block information, a label, or even part of
the drawing. For shorter entries that do not require multiple fonts or lines,
create line text using the Text object. Line text is more convenient for labels.
For more information about this topic, see Create Single-Line Text in the
Users Guide.

Create Line Text

Each individual line of text is a distinct object when using line text. To
create a line text object, use the AddText method. This method requires three
values as input: the text string, the insertion point, and the height of the
text.
The text string is the actual text to be displayed. Unicode, control code, and
special characters are accepted. The insertion point is a variant array
contain- ing three doubles representing the 3D WCS coordinate in the
drawing to place the text. The height of the text is a positive number
representing the height of the uppercase text. Height is measured in the
current units.
Create Line Text
This example creates a line of text in model space, at the coordinate (2, 2, 0).

Add Text to Drawings

157

Sub Ch4_CreateText()
Dim textObj As AcadText
Dim textString As String
Dim insertionPoint(0 To 2) As Double
Dim height As Double
' Create the text object
textString = "Hello, World."
insertionPoint(0) = 2
insertionPoint(1) = 2
insertionPoint(2) = 0
height = 0.5
Set textObj = ThisDrawing.ModelSpace. _
AddText(textString, insertionPoint, height)
textObj.Update
End Sub

Format Line Text

A Text object is created using the active text style. You can change the
formatting of the Text object by changing the text style associated with it,
or by editing the properties of the Text object. You cannot apply formats to
individual words and characters.
To change a text style associated with an individual Text object, set the
StyleName property to a new text style. Once you have changed the text
style, use the Update method for the Text object to see the changes in your
drawing.
In addition to the standard editable properties for entities (color, layer, linetype, and so forth), other properties that you can change on a Text object
include the following:
Alignment

Specifies the horizontal and vertical alignment for the

text.

InsertionPoint

Specifies the insertion point for the text.

ObliqueAngle

Specifies the oblique angle of the individual text object.

Rotation

Specifies the rotation angle in radians for the text.

ScaleFactor

Specifies the scale factor for the text.

TextAlignmentPoint
Specifies the alignment point for the text.
TextGenerationFlag
Specifies whether the text is displayed backward,
upside-down, or both simultaneously.
TextString

Specifies the actual text string displayed.

158 | Chapter 4 Create and Edit AutoCAD

Entities

Once you have changed a property, use the Update method to see the
changes in your drawing.

Note For a complete list of methods and properties, see the Text object
docu- mentation in the AutoCAD ActiveX and VBA Reference.
For more information about formatting line text, see Work with Text Styles
in the Users Guide.

Align Line Text

You can justify line text with one of the horizontal and vertical alignment
options shown in the following illustration. Left alignment is the default. To
set the horizontal and vertical alignment options, use the Alignment
property.
For more information about aligning line text, see Align Single-Line Text
in the Users Guide.
Realign text
This example creates a Text object and a Point object. The Point object is set
to the text alignment point, and is changed to a red crosshair so that it is
visible. The text alignment is changed and a message box is displayed so
that the macro execution is halted. This allows you to see the impact of
changing the text alignment.

Sub Ch4_TextAlignment()
Dim textObj As AcadText
Dim textString As String
Dim insertionPoint(0 To 2) As Double
Dim height As Double
' Define the new Text object
textString = "Hello, World."
insertionPoint(0) = 3
insertionPoint(1) = 3
insertionPoint(2) = 0
height = 0.5
' Create the Text object in model space
Set textObj = ThisDrawing.ModelSpace. _
AddText(textString, insertionPoint, height)
' Create a point over the text alignment point,
' so we can better visualize the alignment process
Dim pointObj As AcadPoint
Dim alignmentPoint(0 To 2) As Double
alignmentPoint(0) = 3
alignmentPoint(1) = 3
alignmentPoint(2) = 0
Set pointObj = ThisDrawing.ModelSpace. _
AddPoint(alignmentPoint)
pointObj.Color = acRed
' Set the point style to crosshair
ThisDrawing.SetVariable "PDMODE", 2
' Align the text to the Left
textObj.Alignment = acAlignmentLeft
ThisDrawing.Regen acActiveViewport
MsgBox "The Text object is now aligned left"
' Align the text to the Center
textObj.Alignment = acAlignmentCenter
' Align the text to the point (necessary for
' all but left aligned text.)
textObj.TextAlignmentPoint = alignmentPoint
ThisDrawing.Regen acActiveViewport
MsgBox "The Text object is now centered"
' Align the text to the Right
textObj.Alignment = acAlignmentRight
ThisDrawing.Regen acActiveViewport
MsgBox "The Text object is now aligned right"
End Sub

Change Line Text

Like any other object, Text objects can be moved, rotated, erased, and
copied. You also can mirror text. If you do not want the text to be reversed
when you mirror it, you can set the MIRRTEXT system variable to 0.
The following list represents a few of the methods a Text object has for use
in editing. For a complete list, see the Text object documentation in the
AutoCAD ActiveX and VBA Reference.
ArrayPolar

Creates a polar array.

ArrayRectangular
Creates a rectangular.
Copy

Copies the Text object.

Erase

Erases the Text object.

Mirror

Mirrors the Text object.

Move

Moves the Text object.

Rotate

Rotates the Text object.

Use Multiline Text (Mtext)

For long, complex entries, create multiline text (mtext). Multiline text fits a
specified width but can extend vertically to an indefinite length. You can
for- mat individual words or characters within the mtext.
For more information about this topic, see Create Multiline Text in the
Users Guide.

Create Multiline Text

You can create a multiline text object (MText object) by using the
AddMText method. This method requires three values as input: the text
string, the insertion point in the drawing to place the text, and the width
of the text bounding box.
The text string is the actual text to be displayed. Unicode, control code, and
special characters are accepted. The insertion point is a variant array
contain- ing three doubles representing the 3D WCS coordinate in the
drawing to place the text. The width of the text is a positive number
representing the width of the bounding box for the text. Width is measured
in the current units.

Once the MText object is created, you can apply the text height,
justification, rotation angle, and style to the MText object, or apply
character formatting to selected characters.
Refer to the entry on MText in the ActiveX and VBA Reference for a list of
methods and properties that apply to the MText object.
For more information about creating multiline text, see Create Multiline
Text in the Users Guide.
Create Multiline Text
The following code creates an MText object in model space, at the
coordinate
(2, 2, 0).
Sub Ch4_CreateMText()
Dim mtextObj As AcadMText
Dim insertPoint(0 To 2) As Double
Dim width As Double
Dim textString As String
insertPoint(0) = 2
insertPoint(1) = 2
insertPoint(2) = 0
width = 4
textString = "This is a text string for the mtext object."
' Create a text Object in model space
Set mtextObj = ThisDrawing.ModelSpace. _
AddMText(insertPoint, width, textString)
ZoomAll
End Sub

Format Multiline Text

New text automatically assumes the characteristics of the current text style.
The STANDARD text style is the default. You can override the default text
style by applying formatting to individual characters and applying
properties to the Text object. You also can indicate formatting or special
characters using the methods described in this section.
Orientation options such as style, justification, width, and rotation affect all
text within the mtext text boundary, not specific words or characters. Use the
AttachmentPoint property to change the justification of MText, and the
Rotation property to control the angle of rotation of the text boundary.

The StyleName property sets the default fonts and formatting

characteristics for new text. As you create text, you can select which style
you want to use from a list of existing styles. When you change the style of
an MText object that has character formatting applied to any portion of the
text, the style is applied to the entire object, and some formatting of
characters might not be retained. For instance, changing from a TrueType
style to a style using an SHX font or to another TrueType font causes the
text to use the new font for the entire object, and any character formatting
is lost.
Formatting options such as underlining, stacked text, or fonts can be applied
to individual words or characters within a paragraph. You also can change
color, font, and text height. You can change the spaces between text characters or increase the width of the characters.
Use curly braces ({ }) to apply a format change only to the text within the
braces. You can nest braces up to eight levels deep.
You also can enter the ASCII equivalent for control codes within lines or
paragraphs to indicate formatting or special characters, such as tolerance or
dimensioning symbols.
The following control characters can be used to create the text in the
illustra- tion. (For the ASCII equivalent of this string see the example
below.)
{{\H1.5x; Big text} \A2; over text\A1;/\A0; under text}

Big text over text/under text

For more information about formatting multiline text, see Format Characters Within Multiline Text in the Users Guide.
Use control characters to format text
This example creates and formats an MText object.

Sub Ch4_FormatMText()
Dim mtextObj As AcadMText
Dim insertPoint(0 To 2) As Double
Dim width As Double
Dim textString As String
insertPoint(0) = 2
insertPoint(1) = 2
insertPoint(2) = 0
width = 4
' Define the ASCII characters for the control characters
Dim OB As Long ' Open Bracket {
Dim CB As Long ' Close Bracket }
Dim BS As Long ' Back Slash
\
Dim FS As Long ' Forward Slash /
Dim SC As Long ' Semicolon
;
OB = Asc("{")
CB = Asc("}")
BS = Asc("\")
FS = Asc("/")
SC = Asc(";")
' Assign the text string the following line of control
' characters and text characters:
' {{\H1.5x; Big text}\A2; over text\A1;/\A0; under text}
textString = Chr(OB) + Chr(OB) + Chr(BS) + "H1.5x" _
+ Chr(SC) + "Big text" + Chr(CB) + Chr(BS) + "A2" _
+ Chr(SC) + "over text" + Chr(BS) + "A1" + Chr(SC) _
+ Chr(FS) + Chr(BS) + "A0" + Chr(SC) + "under text" _
+ Chr(CB)
' Create a text Object in model space
Set mtextObj = ThisDrawing.ModelSpace. _
AddMText(insertPoint, width, textString)
ZoomAll
End Sub

Use Unicode
Codes, and
Special
Characters

Characters,

Control

You can use Unicode characters, control codes, and special characters in your
text string to represent symbols. (All non-text characters must be entered as
their ASCII equivalent.)

You can create special characters by entering the following Unicode

character strings:
Unicode character descriptions
Unicode character

Description

\U+00B0

Degree symbol

\U+00B1

Plus/minus tolerance symbol

\U+2205

Diameter dimensioning symbol

In addition to using Unicode characters for special characters, you can

specify a special character by including control information in the text
string. Use a pair of percent signs (%%) to introduce each control sequence.
For example, the following control code works with standard AutoCAD text
and PostScript fonts to draw character number nnn:
%%nnn

In a VB or VBA text string, the example above would be entered as

Dim percent as Long
percent = ASC("%")
TextString = chr(percent) + chr(percent) + "nnn"

These control codes work with standard AutoCAD text fonts only:
Control code descriptions
Control code

Description

%%o

Toggles overscore mode on and off

%%u

Toggles underscore mode on and off

%%d

Draws degree symbol

%%p

Draws plus and minus tolerance symbol

%%c

Draws diameter dimensioning symbol

%%%

Draws single percent sign

Substitute Fonts
You can designate fonts to be substituted for other fonts or as defaults when
AutoCAD cannot find a font specified in a drawing.
The fonts used for the text in your drawing are determined by the text style
and, for mtext, by individual font formats applied to sections of text.
You can use font mapping tables to ensure that your drawing uses only certain fonts, or to convert the fonts you used to other fonts. You can use
these font mapping tables to enforce corporate font standards, or to
facilitate offline printing. AutoCAD comes with a default font mapping
table. You can edit this file using any ASCII text editor. You also can specify
a different font mapping table file by using the FontFileMap property on
the Preferences object.
For more information about font mapping tables and substituting fonts, see
Substitute Fonts in the Users Guide.

Specify an Alternative Default Font

If your drawing specifies a font that is not currently on your system,
AutoCAD automatically substitutes the font designated as your alternate
font. By default, AutoCAD uses the simplex.shx file. However, you can
specify a different font if necessary. Use the AltFontFile property on the
Preferences object to set the alternative font file name.
If you use a text style that uses a Big Font, you can map it to another font
using the AltFontFile property. This system variable uses a default font file
pair of txt.shx, bigfont.shx.
If AutoCAD cannot find a font file when a drawing is opened, it applies a
default set of font substitution rules. For a description of the default rules,
see Specify an Alternative Font in the Users Guide.

Check Spelling
During a spelling check, AutoCAD matches the words in the drawing to the
words in the current main dictionary. Any words you add are stored in the
custom dictionary that is current at the time of the spelling check. For
exam- ple, you can add proper names so that AutoCAD no longer identifies
them as misspelled words.

To check spelling in another language, you can change to a different main

dictionary.
There is no method for checking spelling provided in AutoCAD ActiveX
Automation. However, you can specify a different main dictionary using the
MainDictionary property, or a different custom dictionary using the
CustomDictionary property on the Preferences object.
For more information about spellings checks, see Check Spelling in the
Users Guide.

168

Dimensions and
Tolerances

Dimensions add measurements to a drawing.

In this chapter

Tolerances specify by how much a dimension can vary.

Dimensioning Concepts

With ActiveXAutomation, dimensions can be

managed with dimension styles and overrides.

Create Dimensions
Edit Dimensions
Work with Dimension

Styles
Dimension in Model

Space and
Paper
Space

Create Leaders and

Annotation

Use Geometric Tolerances

169

Dimensioning Concepts
Dimensions show the geometric measurements of objects, the distances or
angles between objects, or the X and Y coordinates of a feature. AutoCAD
provides three basic types of dimensioning: linear, radial, and angular.
Linear
dimensions include aligned, rotated, and
ordinate
dimensions.
angular

horizontal

aligned
diameter

vertical

radius
continued

baseline

You can create dimensions for lines, multilines, arcs, circles, and polyline
seg- ments, or you can create dimensions that standalone.
AutoCAD draws dimensions on the current layer. Every dimension has a
dimension style associated with it, whether its the default or one you
define. The style controls characteristics such as color, text style, and
linetype scale. Thickness information is not supported. Style families allow
for subtle mod- ifications to a base style for different types of dimensions.
Overrides allow for style modifications to a specific dimension.
For more information about dimensions, see Dimensions and Tolerances,
in the Users Guide.

Parts of a Dimension
This section briefly defines the parts of a dimension.

170 | Chapter 5 Dimensions and

Tolerances

dimension text
continued
arrowhead
dimension line
extension line

leader

A dimension line is a line that indicates the direction and extent of a

dimen- sion. For an angular dimension, the dimension line is an arc.
Extension lines, also called projection lines or witness lines, extend from the
feature being dimensioned to the dimension line. Arrowheads, also called
symbols of ter- mination or just termination, are added to each end of the
dimension line. Dimension text is a text string that usually indicates the actual
measurement. The text may also include prefixes, suffixes, and tolerances. A
leader is a solid line leading from some annotation to the referenced feature.
A center mark is a small cross that marks the center of a circle or arc.
Centerlines are broken lines that mark the center of a circle or arc.
center
lines
center
mark

See Parts of a Dimension in the Users Guide for more information about
the parts of a dimension.

Define the Dimension System Variables

The dimensioning system variables control the appearance of dimensions.
The dimension system variables include: DIMAUNIT, DIMUPT, DIMTOFL,
DIMFIT, DIMTIH, DIMTOH, DIMJUST, and DIMTAD. You can set these
variables by using the SetVariable method. For example, the following line
of code sets the DIMAUNIT system variable (the units format for angular
dimensions) to radians (3):
ThisDrawing.SetVariable "DIMAUNIT", 3

See Use Dimension Styles in the Users Guide for more information about
the dimensioning system variables.

Set Dimension Text Styles

Dimension text refers to any kind of text associated with dimensions,
includ- ing measurements, tolerances (both lateral and geometric), prefixes,
suffixes, and textual notes in single-line or paragraph form. You can use the
default measurement computed by AutoCAD as the text, supply your own
text, or suppress the text entirely. You can use dimension text to add
information, such as special manufacturing procedures or assembly
instructions.

Single-line dimension text uses the active text style as specified by the
ActiveTextStyle property. Paragraphs of text use the active text style with
any modifications you make in your text string.
For more information about dimension text, see Control Dimension Text
in the Users Guide.

Understand Leader Lines

A default leader line is a straight line with an arrowhead that refers to a feature in a drawing. Usually, a leaders function is to connect annotation with
the feature. Annotation in this case means paragraph text, blocks, or feature
control frames. Such leader lines are different from the simple leader lines
AutoCAD creates automatically for radial, diameter, and linear dimensions
whose text wont fit between extension lines.
leader

Leader objects are associated with the annotation, so when the annotation
is edited, the leader is updated accordingly. You can copy annotation used
elsewhere in a drawing and append it to a leader, or you can create a new
annotation. You can also create a leader with no annotation appended.
For more information about leaders, see Overview of Creating Text and
Leaders in the Users Guide.

Understand Associative Dimensions

Associative dimensions automatically adjust their locations, orientations,
and measurement values when the geometric objects associated with them
are modified. The DIMASSOC system variable controls associative dimensioning. Set DIMASSOC to 2 to turn on associative dimensioning.
For more information about associative dimensions, see Associative
Dimen- sions in the Users Guide.

Create Dimensions
You can create linear, radial, angular, and ordinate dimensions.
When creating dimensions, the active dimension style is used. Once
created, you can modify the extension line origins, the dimension text
location, and the dimension text content and its angle relative to the
dimension line. You can also change the dimension style used by the
dimension.
For more information about creating dimensions, see Dimensions and Tolerances in the Users Guide.

Create Linear Dimensions

Linear dimensions can be aligned or rotated. Aligned dimensions have the
dimension line parallel to the line along which the extension line origins lie.
Rotated dimensions have the dimension line placed at an angle to the extension line origins.
To create a linear dimension, use the AddDimAligned or AddDimRotated
method. After you create linear dimensions, you can modify the text, the
angle of the text, or the angle of the dimension line. In the following illustrations, the extension line origins are designated explicitly. The resulting
dimension line location is also shown:

Create Dimensions
173

horizontal

vertical

aligned

rotated 315 degrees

To create an aligned dimension, use the AddDimAligned method. This

method requires three coordinates as input: the origin of both
extension lines and the text position.
To create a rotated dimension, use the AddDimRotated method. This
method requires three coordinates and the angle of the dimension line as
input. The three coordinates are the origin of both extension lines and the
text position. The angle must be provided in radians and represents the
angle of rotation for the dimension line.
For additional information about creating linear dimensions, see Create
Linear Dimensions in the Users Guide.

Create Radial Dimensions

Radial dimensions measure the radii and diameters of arcs and circles. To
create a radial dimension, use the AddDimRadial method.
Different types of radial dimensions are created depending on the size of the
circle or arc, the TextPosition property, and the values in the DIMUPT,
DIMTOFL, DIMFIT, DIMTIH, DIMTOH, DIMJUST, and DIMTAD dimension
system variables. (System variables can be queried or set using the
GetVariable and SetVariable methods.)

174 | Chapter 5 Dimensions and

Tolerances

For horizontal dimension text, if the angle of the dimension line is more
than 15 degrees from horizontal, and is outside the circle or arc, AutoCAD
draws a hook line, also called a landing or dogleg. The hook line is one
arrow- head long, and is placed next to the dimension text, as shown in the
follow- ing illustrations:

To create radial dimensions, use the AddDimRadial or AddDimDiametric

methods. These methods require three values as input: the coordinate of the
circle or arcs center, the coordinate for the leader attachment, and the
length of the leader.
These methods use the LeaderLength parameter as the distance from the
ChordPoint to the point where the dimension will do a horizontal hook line
to the annotation text (or stop if no hook line is necessary).
For additional information about creating radial dimensions, see Create
Radial Dimensions in the Users Guide.
Create a radial dimension
This example creates a radial dimension in model space.

Create Dimensions
175

Sub Ch5_CreateRadialDimension()
Dim dimObj As AcadDimRadial
Dim center(0 To 2) As Double
Dim chordPoint(0 To 2) As Double
Dim leaderLen As Integer
' Define the dimension
center(0) = 0
center(1) = 0
center(2) = 0
chordPoint(0) = 5
chordPoint(1) = 5
chordPoint(2) = 0
leaderLen = 5
' Create the radial dimension in model space
Set dimObj = ThisDrawing.ModelSpace. _
AddDimRadial(center, chordPoint, leaderLen)
ZoomAll
End Sub

Note The LeaderLength setting is only used during the creation of the
dimen- sion (and even then only if the dimension is set to use the default text
position value). After the dimension is closed for the first time, changing the
Leader- Length value will not affect how the dimension displays, but the new
setting will be stored and will show up in DXF, LISP, and ADSRX applications.

Create Angular Dimensions

Angular dimensions measure the angle between two lines or three points.
For example, you can use them to measure the angle between two radii of a
circle. The dimension line forms an arc.
To create an angular dimension, use the AddDimAngular method. This
method requires three values as input: the angle vertex, the origins of the
extension lines, and the text location. The AngleVertex is the center of the
circle or arc, or the common vertex between the two lines being dimensioned. The origins of the extension lines are the points through which the
two extension lines pass.
The AngleVertex can be the same as one of the origin points. If you need
extension lines they will be added automatically.
For additional information about creating angular dimensions, see Create
Angular Dimensions in chapter 20, Dimensions and Tolerances, in the
Users Guide.

176 | Chapter 5 Dimensions and

Tolerances

Create an angular dimension

This example creates an angular dimension in model space.
Sub Ch5_CreateAngularDimension()
Dim dimObj As AcadDimAngular
Dim angVert(0 To 2) As Double
Dim FirstPoint(0 To 2) As Double
Dim SecondPoint(0 To 2) As Double
Dim TextPoint(0 To 2) As Double
' Define the dimension
angVert(0) = 0
angVert(1) = 5
angVert(2) = 0
FirstPoint(0) = 1
FirstPoint(1) = 7
FirstPoint(2) = 0
SecondPoint(0) = 1
SecondPoint(1) = 3
SecondPoint(2) = 0
TextPoint(0) = 3
TextPoint(1) = 5
TextPoint(2) = 0
' Create the angular dimension in model space
Set dimObj = ThisDrawing.ModelSpace. _
AddDimAngular(angVert, FirstPoint, SecondPoint, TextPoint)
ZoomAll
End Sub

Create
Dimensions

Ordinate

Ordinate, or datum, dimensions measure the perpendicular distance from an

origin point, called the datum, to a dimensioned feature, such as a hole in a
part. These dimensions prevent escalating errors by maintaining accurate
off- sets of the features from the datum.

Create Dimensions
177

Ordinate dimensions consist of an X or Y ordinate with a leader line.

X-datum ordinate dimensions measure the distance of a feature from the
datum along the X axis. Y-datum ordinate dimensions measure the same distance along the Y axis. AutoCAD uses the origin of the current UCS to determine the measured coordinates. The absolute value of the coordinate is used.
The text is aligned with the ordinate leader line regardless of the text orientation defined by the current dimension style. You can accept the default
text or supply your own.
To create an ordinate dimension, use the AddDimOrdinate method. This
method requires three values as input: a coordinate specifying the point to
be dimensioned (A), a coordinate specifying the end of the leader (B), and a
Boolean flag specifying whether the dimension is an X-datum ordinate
dimension or a Y-datum ordinate dimension. If you enter TRUE for the
Boolean flag, the method will create an X-datum ordinate dimension. If you
enter FALSE, it will create a Y-datum ordinate dimension.
For additional information about creating ordinate dimensions, see Create
Ordinate Dimensions in chapter 20, Dimensions and Tolerances, in the
Users Guide.
Create an ordinate dimension
This example creates an ordinate dimension in model space.
Sub Ch5_CreatingOrdinateDimension()
Dim dimObj As AcadDimOrdinate
Dim definingPoint(0 To 2) As Double
Dim leaderEndPoint(0 To 2) As Double
Dim useXAxis As Long
' Define the dimension
definingPoint(0) = 5
definingPoint(1) = 5
definingPoint(2) = 0
leaderEndPoint(0) = 10
leaderEndPoint(1) = 5
leaderEndPoint(2) = 0
useXAxis = 5
' Create an ordinate dimension in model space
Set dimObj = ThisDrawing.ModelSpace. _
AddDimOrdinate(definingPoint, _
leaderEndPoint, useXAxis)
ZoomAll
End Sub

178 | Chapter 5 Dimensions and

Tolerances

Edit Dimensions
As with other graphical objects in AutoCAD, you can edit dimensions using
the standard methods and properties provided for the object.
The following properties are available for most dimension objects:
Rotation

Specifies the rotation angle in radians for the

dimension line.

StyleName

Specifies the name of the dimension style.

TextOverride

Specifies the text string for the dimension.

TextPosition

Specifies the dimension text position.

TextRotation

Specifies the rotation angle of the dimension text.

Measurement

Specifies the actual measurement for the dimension.

In addition, certain dimension objects provide properties for editing the

extension line origins and leader length.
The following methods are included for dimension object editing:
ArrayPolar

Creates a polar array.

ArrayRectangular

Creates a rectangular array.

Copy

Copies the dimension object.

Erase

Erases the dimension object.

Mirror

Mirrors the dimension object.

Move

Moves the dimension object.

Rotate

Rotates the dimension object.

ScaleEntity

Scales the dimension object.

For more information about editing dimensions, see Modify Existing

Dimensions in chapter 20, Dimensions and Tolerances, in the
Users Guide.

Override Dimension Text

The dimension value that is displayed can be replaced using the
TextOverride property. Using this property you can completely replace the
displayed value of the dimension, or you can append text to the value.

Edit Dimensions
179

Modify dimension text

This example appends some text to the value so that both the string and the
dimension value are displayed.
Sub Ch5_OverrideDimensionText()
Dim dimObj As AcadDimAligned
Dim point1(0 To 2) As Double
Dim point2(0 To 2) As Double
Dim location(0 To 2) As Double
' Define the dimension
point1(0) = 5#: point1(1) = 3#: point1(2) = 0#
point2(0) = 10#: point2(1) = 3#: point2(2) = 0#
location(0) = 7.5: location(1) = 5#: location(2) = 0#
' Create an aligned dimension object in model space
Set dimObj = ThisDrawing.ModelSpace. _
AddDimAligned(point1, point2, location)
' Change the text string for the dimension
dimObj.TextOverride = "The value is <>"
dimObj.Update
End Sub

Work with Dimension Styles

A named dimension style is a group of settings that determines the appearance of the dimension. Using named dimension styles, you can establish
and enforce drafting standards for drawings.
All dimensions are created using the active dimension style. If you dont
define or apply a style before creating dimensions, AutoCAD applies the
default style, STANDARD. To set the active dimension style, use the
ActiveDimStyle property.
To set up a parent dimension style, you begin by naming and saving a style.
The new style is based on the current style and includes all subsequent
changes to the layout of the dimension parts, the positioning of text, and the
appearance of annotation. Annotation in this case means primary and alternate units, tolerances, and text.
For more information about dimension styles, see Use Dimension Styles in
chapter 20, Dimensions and Tolerances, in the Users Guide.

180 | Chapter 5 Dimensions and

Tolerances

Create, Modify, and Copy Dimension

Styles
To create a new dimension style, use the Add method. This method requires
as input the name of the new dimension style.
AutoCAD ActiveX Automation allows you to add new dimension styles, and
to change the active dimension style. You can also change the dimension
style associated with a given dimension through the StyleName property.
You can also copy an existing style or set of overrides. Use the CopyFrom
method to copy a dimension style from a source object to a newly dimension
style. The source object can be another DimStyle object, a dimension, Tolerance, or Leader object, or even a Document object. If you copy the style settings from another dimension style, the style is duplicated exactly. If you
copy the style settings from a dimension, Tolerance, or Leader object, the
cur- rent settings, including any object overrides, are copied to the new
style. If you copy the style of a Document object, the active dimension style,
plus any drawing overrides, are copied to the new style.
Copy dimension styles and overrides
This example creates three new dimension styles and copies the current settings for the document, a given dimension style, and a given dimension to
each new dimension style respectively. By following the appropriate setup
before running this example, you will find that different dimension styles
have been created.
1 Create a new drawing and make it the active drawing.
2 Create a linear dimension in the new drawing. This dimension should be
the only object in the drawing.
3 Using the OPM, change the color of the dimension line to yellow.
4 Change the DIMCLRD system variable to 5 (blue).
5 Run the following example:

Work with Dimension Styles

181

Sub Ch5_CopyDimStyles()
Dim newStyle1 As AcadDimStyle
Dim newStyle2 As AcadDimStyle
Dim newStyle3 As AcadDimStyle
Set newStyle1 = ThisDrawing.DimStyles.Add _
("Style 1 copied from a dim")
Call newStyle1.CopyFrom(ThisDrawing.ModelSpace(0))
Set newStyle2 = ThisDrawing.DimStyles.Add _
("Style 2 copied from Style 1")
Call newStyle2.CopyFrom(ThisDrawing.DimStyles.Item _
("Style 1 copied from a dim"))
Set newStyle2 = ThisDrawing.DimStyles.Add _
("Style 3 copied from the running drawing values")
Call newStyle2.CopyFrom(ThisDrawing)
End Sub

Open the DIMSTYLE dialog. You should now have 3 dimension styles
listed. Style 1 should have a yellow dimension line. Style 2 should be the
same as Style 1. Style 3 should have a blue dimension line.

Override the Dimension Style

Each dimension has the capability of overriding settings in the dimension
style for that dimension. The following properties are available for most
dimension objects:
AltRoundDistance
Specifies the rounding of alternate units.
AngleFormat

Specifies the unit format for angular dimensions.

Arrowhead1Block, Arrowhead2Block
Specifies the block to use as the custom arrowhead for
the dimension line.
Arrowhead1Type, Arrowhead2Type
Specifies the type of arrowhead for the dimension line.
ArrowheadSize

Specifies the size of dimension line arrowheads, leader

line arrowheads, and hook lines.

CenterMarkSize

Specifies the size of the center mark for radial and

diameter dimensions.

CenterType

Specifies the type of center mark for radial and

diameter dimensions.

182 | Chapter 5 Dimensions and

Tolerances

DecimalSeparator
Specifies the character to be used as the decimal
separator in decimal dimension and tolerance values.
DimensionLineColor
Specifies the color of the dimension line for a
dimension, leader, or tolerance object.
DimensionLineWeight
Specifies the lineweight for the dimension lines.
DimLine1Suppress, DimLine2Suppress
Specifies the suppression of the dimension lines.
DimLineInside

Specifies the display of dimension lines inside the

extension lines only.

ExtensionLineColor
Specifies the color for dimension extension lines.
ExtensionLineExtend
Specifies the distance the extension line extends
beyond the dimension line.
ExtensionLineOffset
Specifies the distance the extension lines are offset
from the origin points.
ExtensionLineWeight
Specifies the lineweight for the extension lines.
ExtLine1EndPoint, ExtLine2EndPoint
Specifies the endpoint of extension lines.
ExtLine1StartPoint, ExtLine2StartPoint
Specifies the start point of extension lines.
ExtLine1Suppress, ExtLine2Suppress
Specifies the suppression of extension lines.
Fit

Specifies the placement of text and arrowheads inside

or outside extension lines.

Work with Dimension Styles

183

ForceLineInside
Specifies if a dimension line is drawn between the
extension lines even when the text is placed outside the
extension lines.
FractionFormat
Specifies the format of fractional values in dimensions
and tolerances.
HorizontalTextPosition
Specifies the horizontal justification for dimension
text.
LinearScaleFactor
Specifies a global scale factor for linear dimensioning
measurements.
PrimaryUnitsPrecision
Specifies the number of decimal places displayed for the
primary units of a dimension or tolerance.
SuppressLeadingZeros, SuppressTrailingZeros
Specifies the suppression of leading and trailing zeros in
dimension values.
SuppressZeroFeet, SuppressZeroInches
Specifies the suppression of a zero foot and zero inch
measurement in dimension values.
TextColor

Specifies the color of the text for dimension and

tolerance objects.

TextGap

Specifies the distance between the dimension text and

the dimension line when you break the dimension line
to accommodate dimension text.

TextHeight

Specifies the height for the dimension or tolerance text.

TextInside

Specifies if the dimension text is to be drawn inside the

extension lines.

TextInsideAlign
Specifies the position of dimension text inside the
extension lines for all dimension types except ordinate.

TextMovement
Specifies how dimension text is drawn when text is
moved.
TextOutsideAlign
Specifies the position of dimension text outside the
extension lines for all dimension types except ordinate.
TextPosition

Specifies the dimension text position.

TextPrecision

Specifies the precision of angular dimension text.

TextPrefix

Specifies the dimension value prefix.

TextRotation

Specifies the rotation angle of the dimension text.

TextSuffix

Specifies the dimension value suffix.

ToleranceDisplay
Specifies if tolerances are displayed with the
dimension text.
ToleranceHeightScale
Specifies a scale factor for the text height of tolerance
values relative to the dimension text height.
ToleranceJustification
Specifies the vertical justification of tolerance values
relative to the nominal dimension text.
ToleranceLowerLimit
Specifies the minimum tolerance limit for dimension
text.
TolerancePrecision
Specifies the precision of tolerance values in primary
dimensions.
ToleranceSuppressLeadingZeros
Specifies the suppression of leading zeros in tolerance
values.
ToleranceSuppressTrailingZeros
Specifies the suppression of trailing zeros in dimension
values.

ToleranceUpperLimit
Specifies the maximum tolerance limit for dimension
text.
UnitsFormat

Specifies the unit format for all dimensions except

angular.

VerticalTextPosition
Specifies the vertical position of text in relation to the
dimension line.
Enter a user-defined suffix for an aligned dimension
This example creates an aligned dimension in model space and uses the
TextSuffix property to allow the user to change the text suffix for the
dimension.
Sub Ch5_AddTextSuffix()
Dim dimObj As AcadDimAligned
Dim point1(0 To 2) As Double
Dim point2(0 To 2) As Double
Dim location(0 To 2) As Double
Dim suffix As String
' Define the dimension
point1(0) = 0: point1(1) = 5: point1(2) = 0
point2(0) = 5: point2(1) = 5: point2(2) = 0
location(0) = 5: location(1) = 7: location(2) = 0
' Create an aligned dimension object in model space
Set dimObj = ThisDrawing.ModelSpace. _
AddDimAligned(point1, point2, location)
ThisDrawing.Application.ZoomAll
' Allow the user to change the text suffix for the dimension
suffix = InputBox("Enter a new text suffix for the dimension" _
, "Set Dimension Suffix", ":SUFFIX")
' Apply the change to the dimension
dimObj.TextSuffix = suffix
ThisDrawing.Regen acAllViewports
End Sub

Dimension in Model Space and Paper

Space
You can draw dimensions in both paper space and model space. However,
if the geometry youre dimensioning is in model space, its better to draw
dimensions in model space, because AutoCAD places the definition points in
the space where the geometry is drawn.
If you draw a dimension in paper space that describes geometry in your
model, the paper space dimension does not change when you use editing
commands or change the magnification of the display in the model space
viewport. The location of the paper space dimensions also stays the same
when you change a view from paper space to model space.
If youre dimensioning in paper space and the global scale factor for linear
dimensioning (the DIMLFAC system variable) is set at less than 0, the
distance measured is multiplied by the absolute value of DIMLFAC. If youre
dimen- sioning in model space, the value of 1.0 is used even if DIMLFAC is
less than
0. AutoCAD computes a value for DIMLFAC if you change the variable at the
Dim prompt and select the Viewport option. AutoCAD calculates the scaling
of model space to paper space and assigns the negative of this value to
DIMLFAC.

Create Leaders and Annotation

A leader is a line that connects some annotation to a feature in a drawing.
Leaders and their annotation are associative, which means if you modify the
annotation, the leader updates accordingly. Dont confuse the Leader object
with the leader line AutoCAD automatically generates as part of a dimension
line.
For more information about leaders, see Create Text with Leaders in
chap- ter 19, Notes and Labels, in the Users Guide.

Create a Leader Line

You can create a leader line from any point or feature in a drawing and control its appearance as you draw it. Leaders can be straight line segments or
smooth spline curves. Leader color is controlled by the current dimension
line color. Leader scale is controlled by the overall dimension scale set in the
active dimension style. The type and size of the arrowhead, if one is present,
is controlled by the first arrowhead defined in the active style.

Dimension in Model Space and Paper

Space | 187

A small line known as a hook line usually connects the annotation to the
leader. Hook lines appear with mtext and feature control frames if the last
leader line segment is at an angle greater than 15 degrees from horizontal.
The hook line is the length of a single arrowhead. If the leader has no annotation, it has no hook line.
hook line
leader line

To create a leader line, use the AddLeader method. This method requires
three values as input: the array of coordinates to create the leader at, the
annotation object (or NULL if the leader is to have no annotation), and the
type of leader to create. The type of leader specifies whether the leader is to
be a straight line or a smooth spline curve. It also determines whether or not
the leader is to have arrows. Use one of the following constants to specify the
type of leader: acLineNoArrow, acLineWithArrow, acSplineNoArrow, or
acSplineWithArrow. These constants are mutually exclusive of each other.
Create a leader line
This example creates a leader line in model space. There is no annotation
associated with the leader line.
Sub Ch5_CreateLeader()
Dim leaderObj As AcadLeader
Dim points(0 To 8) As Double
Dim leaderType As Integer
Dim annotationObject As AcadObject
points(0) = 0: points(1) = 0: points(2) = 0
points(3) = 4: points(4) = 4: points(5) = 0
points(6) = 4: points(7) = 5: points(8) = 0
leaderType = acLineWithArrow
Set annotationObject = Nothing
' Create the leader object in model space
Set leaderObj = ThisDrawing.ModelSpace. _
AddLeader(points, annotationObject, leaderType)
ZoomAll
End Sub

188 | Chapter 5 Dimensions and

Tolerances

Add the Annotation to a Leader Line

Leader annotations can be a Tolerance, MText, or BlockRef object. You can
create a new annotation, or you can append a copy of an existing annotation. Annotation is added to the leader only when it is created.
To add an annotation when a leader is being created, input the annotation
to the AddLeader method.

Leader Associativity
Leaders are associated with their annotation so that when the annotation
moves, the endpoint of the leader moves with it. As you move text and
feature control frame annotation, the final leader line segment alternates
between attaching to the left side and to the right side of the annotation
according to the relation of the annotation to the penultimate (second to
last) point of the leader. If the midpoint of the annotation is to the right of
the penultimate leader point, then the leader attaches to the right;
otherwise, it attaches to the left.
Removing either object from the drawing using either the Erase, Add (to add
a block), or WBlock method will break associativity. If the leader and its
annotation are copied together in a single operation, the new copy is
associa- tive. If they are copied separately, they will not be associative. If
associativity is broken for any reason, for example, by copying only the
Leader object or by erasing the annotation, the hook line will be removed
from the leader.
Associate a leader to the annotation
This example creates an MText object. A leader line is then created using the
MText object as its annotation.

Create Leaders and Annotation

| 189

Sub Ch5_AddAnnotation()
Dim leaderObj As AcadLeader
Dim mtextObj As AcadMText
Dim points(0 To 8) As Double
Dim insertionPoint(0 To 2) As Double
Dim width As Double
Dim leaderType As Integer
Dim annotationObject As Object
Dim textString As String, msg As String
' Create the MText object in model space
textString = "Hello, World."
insertionPoint(0) = 5
insertionPoint(1) = 5
insertionPoint(2) = 0
width = 2
Set mtextObj = ThisDrawing.ModelSpace. _
AddMText(insertionPoint, width, textString)
' Data for Leader
points(0) = 0: points(1) = 0: points(2) = 0
points(3) = 4: points(4) = 4: points(5) = 0
points(6) = 4: points(7) = 5: points(8) = 0
leaderType = acLineWithArrow
' Create the Leader object in model space and associate
' the MText object with the leader
Set annotationObject = mtextObj
Set leaderObj = ThisDrawing.ModelSpace. _
AddLeader(points, annotationObject, leaderType)
ZoomAll
End Sub

Edit Leader Associativity

Except for the associativity relation between the leader and annotation, the
leader and its annotation are entirely separate objects in your drawing. Editing of the leader does not affect the annotation, and editing of the annotation does not affect the leader.
Although text annotation is created using the DIMCLRT, DIMTXT, and
DIMTXSTY system variables to define its color, height, and style, it cannot be
changed by these system variables because it is not a true dimension object.
Text annotation must be edited the same way as any other MText object.
Use the Evaluate method to evaluate the relation of the leader to its associated annotation. This method will update the leader geometry if necessary.

190 | Chapter 5 Dimensions and

Tolerances

Edit Leaders
Any modifications to leader annotation that change its position affect the
position of the endpoint of the associated leader. Also, rotating the annotation causes the leader hook line (if any) to rotate.
To resize a leader, you can scale it. Scaling updates only the scale of the
selected object. For example, if you scale the leader, the annotation stays in
the same position relative to the leader endpoint but isnt scaled.
In addition to scaling, you can also move, mirror, and rotate a leader. Use the
ScaleEntity, Move, Mirror, and Rotate methods to edit the leader. You can
also change the text style associated with the annotation by using the StyleName property.
For more information about editing leaders, see Change Text with a Leader
in the Users Guide.

Use Geometric Tolerances

Geometric tolerancing shows deviations of form, profile, orientation, location, and runout of a feature. You add geometric tolerances in feature
control frames. These frames contain all the tolerance information for a
single dimension.
For more information about using feature control frames and working with
geometric tolerances, see Add Geometric Tolerances in chapter 20,
Dimensions and Tolerances, in the Users Guide.

Create Geometric Tolerances

To create a geometric tolerance use the AddTolerance method. This method
requires three values as input: the text string comprising the tolerance
symbol, the location in the drawing to place the tolerance, and a directional
vector specifying the direction of the tolerance. You can also copy, move,
erase, scale, and rotate tolerances.
Create a geometric tolerance
This example creates a simple geometric tolerance in model space.

Use Geometric Tolerances

191

Sub Ch5_CreateTolerance()
Dim toleranceObj As AcadTolerance
Dim textString As String
Dim insertionPoint(0 To 2) As Double
Dim direction(0 To 2) As Double
' Define the tolerance object
textString = "Here is the Feature Control Frame"
insertionPoint(0) = 5
insertionPoint(1) = 5
insertionPoint(2) = 0
direction(0) = 1
direction(1) = 1
direction(2) = 0
' Create the tolerance object in model space
Set toleranceObj = ThisDrawing.ModelSpace. _
AddTolerance(textString, insertionPoint, direction)
ZoomAll
End Sub

Edit Tolerances
Tolerances are influenced by several system variables: DIMCLRD controls the
color of the feature control frame; DIMCLRT controls the color of the tolerance text; DIMGAP controls the gap between the feature control frame and
the text; DIMTXT controls the size of the tolerance text; and DIMTXTSTY
controls the style of the tolerance text. Use the SetVariable method to set the
values of system variables.

192 | Chapter 5 Dimensions and

Tolerances

Customize Toolbars and

Menus

AutoCAD ActiveX Automation gives you extensive

In this chapter

control over the customization of menus and toolbars

Understand the MenuBar

in the current AutoCAD session.

Using AutoCAD ActiveX/VBA, you can edit or augment
the existing menu structure, or you can completely
replace the current menu structure. You can also
manip- ulate toolbars and right-click menus.
Menu customization can improve productivity by
exposing application-specific tasks or by condensing
tasks with multiple steps into a single menu selection.
For information about customizing menus and toolbars
in addition to the information in this section, see the

and
MenuGroups
Collections
Load Menu Groups
Create New Menu Groups
Change the Menu Bar
Create and Edit Pull-

Down and
Shortcut Menus

Create and Edit Toolbars

Create Macros
Create Status-Line Help

for
Menu Items and Toolbar
Items
Add Entries to the Right-

Click
Menu

Customization Guide.

193

Understand the MenuBar and

MenuGroups
Collections
AutoCAD ActiveX provides several menu-related objects. The two most
important are the MenuBar collection and the MenuGroups collection. The
MenuBar collection contains all the menus that are displayed in the
AutoCAD menu bar.
AutoCAD Application

MenuBar
PopupMenu
MenuGroups
MenuGroup
PopupMenus
Toolbars

The MenuGroups collection contains the menu groups that are loaded in the
current AutoCAD session. These menu groups contain all the menus that are
available to the AutoCAD session, some or all of which may be displayed on
the AutoCAD menu bar. In addition to the menus, the menu groups also
con- tain all the toolbars that are available to the current AutoCAD session.
Menu groups may also represent tile menus, screen menus, or tablet menus.
Each menu group contains a PopupMenus collection and a Toolbars collection. The PopupMenus collection contains all the menus within the menu
group. Likewise, the Toolbars collection contains all the toolbars within the
menu group.
Each PopupMenu is actually a collection that contains an individual object
for each menu item that appears on that menu. Likewise, each Toolbar is
also a collection that contains an individual object for each toolbar item
that appears on that toolbar.

194 | Chapter 6 Customize Toolbars and

Menus

AutoCAD Application

MenuBar
PopupMenu
MenuGroups
MenuGroup
PopupMenus
PopupMenu
PopupMenuItem
Toolbars
Toolbar
ToolbarItem

Load Menu Groups

Menu groups are loaded into AutoCAD using the Load method. For
example, the following code loads the menu file acad.mnc:
ThisDrawing.Application.MenuGroups.Load "acad.mnc"

When using the Load method, set the BaseMenu parameter to TRUE to load
a new menu group to the menu bar. This will load the menu group as a
base menu in the same manner as the MENU command in AutoCAD.
To load a new menu group as a partial menu, omit the BaseMenu
parameter. This will load the menu group in the same manner as the
MENULOAD com- mand in AutoCAD. Once loaded into the MenuGroups
collection, partial menus can be inserted into the menu bar by using the
InsertMenuIn- MenuBar method, or the InsertInMenuBar method.
Once a menu group has been loaded, all the menus and toolbars defined by
that menu group are available for use. You can

Load Menu Groups

195

Add new menus to the menu bar

Remove menus from the menu bar
Rearrange menus on the menu bar
Add new items to an existing menu or toolbar
Remove items from an existing menu or toolbar
Create new menus and toolbars
Float or dock toolbars
Enable or disable menu and toolbar items
Check or uncheck a menu item
Change the tag, label, or help string of a menu or toolbar item
Reassign the macros associated to a menu or toolbar item

Note

You cannot edit image tile menu items, screen menus, or tablet
menus using ActiveX Automation. However, you can load and unload these
menu types using ActiveX Automation.

Create New Menu Groups

AutoCAD ActiveX does not allow you to create new (empty) menu groups
programmatically. However, you can load an existing menu group and save
it out again with a new name and to a new menu file. For example, the following code saves the first menu group in the menu groups collection to a
file called MyMenu.mnc:
ThisDrawing.Application.MenuGroups.Item(0). _
SaveAs "MyMenu.mnc", acMenuFileCompiled

You can then edit the menu group to contain the exact configuration you
desire. This process of creating new menu groups based on existing menu
groups has the advantage of automatically providing you with basic menus
such as File, Window, and Help.

Change the Menu Bar

As you have already seen, the menu bar can be completely replaced by a new
menu group if that group is loaded as the base menu. Additionally, individual menus on the menu bar can be added, removed, or rearranged.

196 | Chapter 6 Customize Toolbars and

Menus

Insert Menus in the Menu Bar

To insert an existing menu to the menu bar, use the InsertMenuInMenuBar
or the InsertInMenuBar method. Both methods accomplish the same goal
they insert an existing menu into the menu bar.
The difference between the two methods is the object from which they are
called. The InsertMenuInMenuBar method is called from the PopupMenus
collection. Using this method you can insert any menu from the collection
into a specified location on the menu bar. This method requires as input the
name of the menu to insert and the location on the menu bar to insert it.
The InsertInMenuBar method is called directly from the PopupMenu object
to be inserted. The only input this method requires is a location on the
menu bar. The name of the menu is not needed because you are calling the
method directly from the object to be inserted.
You should use whichever method is more convenient for your application.
Insert a menu in the menu bar
This example creates a new menu called TestMenu and inserts a menu item
into it. The menu item is assigned the OPEN command. The menu is then
dis- played on the menu bar.
Sub Ch6_InsertMenu()
' Define a variable for the current menu group
Dim currMenuGroup As AcadMenuGroup
Set currMenuGroup = ThisDrawing.Application. _
MenuGroups.Item(0)
' Create a new menu
Dim newMenu As AcadPopupMenu
Set newMenu = currMenuGroup.Menus.Add("TestMenu")
' Declare the variables for the menu item
Dim newMenuItem As AcadPopupMenuItem
Dim openMacro As String
' Assign the macro string the VB equivalent of
' "ESC ESC _open " and create the menu item
openMacro = Chr(vbKeyEscape) + Chr(vbKeyEscape) + "_open "
Set newMenuItem = newMenu.AddMenuItem(newMenu.Count + 1, _
"Open", openMacro)
' Display the menu on the menu bar
currMenuGroup.Menus.InsertMenuInMenuBar "TestMenu", ""
End Sub

Change the Menu Bar

197

Remove Menus from the Menu Bar

To remove a menu from the menu bar, use the
RemoveMenuFromMenuBar or the RemoveFromMenuBar method. Both
methods accomplish the same goalthey remove a menu from the menu
bar.
The difference between the two methods is the object from which they are
called. The RemoveMenuFromMenuBar method is called from the PopupMenus collection. This method requires as input the name of the menu to
remove, or the location on the menu bar of the menu to remove. For example, the following statement removes the menu added in Insert a menu in
the menu bar:
currMenuGroup.Menus.RemoveMenuFromMenuBar ("TestMenu")

The RemoveFromMenuBar method is called directly from the PopupMenu

object to be removed. This method does not require any input. The name of
the menu is not needed because you are calling the method directly from
the object to be removed.
You should use whichever method is more convenient for your application.

Note Menus that have been removed from the menu bar are still available
in their designated menu group. They are simply no longer visible to the user.

Rearrange Menu Items on the Menu Bar

To rearrange menus on the menu bar, insert and remove menus until the
desired configuration is achieved.
Move the first menu to the end of the menu bar
This example removes the first menu on the menu bar and inserts it as the
last menu on the menu bar.

198 | Chapter 6 Customize Toolbars and

Menus

Sub Ch6_MoveMenu()
' Define a variable to hold the menu to be moved
Dim moveMenu As AcadPopupMenu
Dim MyMenuBar As AcadMenuBar
Set MyMenuBar = ThisDrawing.Application.menuBar
' Set moveMenu equal to the first menu displayed
' on the menu bar
Set moveMenu = MyMenuBar.Item(0)
' Remove the first menu from the menu bar
MyMenuBar.Item(0).RemoveFromMenuBar
' Add the menu back into the menu bar
' in the last position on the bar
moveMenu.InsertInMenuBar (MyMenuBar.count)
End Sub

Create and Edit Pull-Down and

Shortcut
Menus
AutoCAD ActiveX/VBA has the ability to customize two types of AutoCAD
menus: pull-down menus and shortcut menus (sometimes called cursor
menus). Both pull-down and shortcut menus are displayed as cascading
menus. The shortcut menu can provide quick access to frequently used
menu items such as Object Snap modes.
A pull-down menu can contain up to 999 menu items. A shortcut menu can
contain up to 499 menu items. Both limits include all menus in the hierarchy. If the number of menu items in a menu exceeds these limits,
AutoCAD ignores the extra items. If a pull-down or shortcut menu is taller
than the available space on the graphics screen, it is truncated to fit on the
screen.
Pull-down menus are always pulled down from the menu bar, but the
shortcut menu is always displayed at or near the crosshairs on the graphics
screen. The handling for both menu types is the same except the shortcut
menu caption isnt included on the menu bar. The shortcut menu caption
is not displayed at all. Access to the shortcut menu is through a single menu
in the base menu group. The shortcut menu can be identified with the
ShortcutMenu property. If the ShortcutMenu property returns TRUE, then
the queried menu is the shortcut menu for the group.

Create and Edit Pull-Down and Shortcut

Menus | 199

Create New Menus

To create a new menu, use the Add method to add a new PopupMenu object
to the PopupMenus collection.
To create a new shortcut menu, you must delete an existing shortcut menu.
There can be only one shortcut menu per menu group. If there is no other
shortcut menu in a menu group, you can add a menu with the label
POP0. This will tell AutoCAD you want to create a shortcut menu.
The Add method requires as input the name (label) of the menu to add. This
name becomes the title for the menu when it is loaded on the menu bar. The
name is also the easiest way of identifying the menu within the collection.
The menu name can be a simple string or it can contain special codes. You
can change the name of a menu once it has been created. To change the
name of an existing menu, use the Name property for that menu.
Create a new popup menu
This example creates a new popup menu called TestMenu in the first
menu group of the MenuGroups collection.
Sub Ch6_CreateMenu()
Dim currMenuGroup As AcadMenuGroup
Set currMenuGroup = ThisDrawing.Application.MenuGroups.Item(0)
' Create the new menu
Dim newMenu As AcadPopupMenu
Set newMenu = currMenuGroup.Menus.Add("TestMenu")
End Sub

Add New Menu Items to a Menu

To add a new menu item to a menu use the AddMenuItem method. This
method creates a new PopupMenuItem object and adds it to the designated
menu.
The AddMenuItem method takes four parameters as input: Index, Label,
Tag, and Macro.

Specify the Index Parameter

The Index parameter is an integer that specifies the position of the new
menu item within the menu. The index begins with position zero (0) as the
first position on the menu after the title. To add the new menu item to the
end of a menu, set the Index parameter equal to the Count property of the
menu. (The Count property of the menu represents the total number of
menu items on that menu.)

200 | Chapter 6 Customize Toolbars and

Menus

menu name
index 0
index 1
index 2
index 3
index 4
index 5
index 6

The first index position is zero (0) and the separators are listed as individual
menu items with their own index position. The Count property for the
menu pictured would be six (6). To add a menu item between Tile
Horizontally and Tile Vertically, set the Index parameter to two (2), which
is the index of the Tile Vertically menu item. This inserts your new menu
item into index two (2) and bumps all the remaining menu items down one
index position.
Once a menu item has been created, you cannot change the index of the
menu item through the Index property. To change the index of an existing
menu item you must delete and re-add the menu item to a different
position, or add or delete surrounding menu items until a proper
placement is achieved.

Specify the Label Parameter

A label is a string that defines the content and formatting of menu items.
Menu item labels can contain DIESEL string expressions that conditionally
alter the labels each time they are displayed.
In addition to the DIESEL string expressions, the label may contain special
codes. For example, an ampersand (&) placed directly before a character
spec- ifies that character as the accelerator key.
The text the user sees displayed for the menu item is called the Caption, and
it is derived from the label by interpreting all the DIESEL string expressions
and special codes contained in the label. For example, the label &Edit produces the caption Edit.
Once a menu item has been created, you can change the label for the menu
item using the Label property.

Specify the Tag Parameter

The tag, or name tag, is a string consisting of alphanumeric and underscore
(_) characters. This string uniquely identifies the menu item within a given
menu.
Once a menu item has been created, you can change the tag for the menu
item using the TagString property.

Create and Edit Pull-Down and Shortcut

Menus | 201

Specify the Macro Parameter

A macro is a series of commands that executes specific actions when a menu
item is selected. Menu macros can simply be recordings of keystrokes that
accomplish a task, or they can be a complex combination of commands,
AutoLISP, DIESEL, or ActiveX programming code.
Once a menu item has been created, you can change the macro for the
menu item using the Macro property.
Add menu items to a popup menu
This example creates a new menu called TestMenu and inserts a menu
item. The menu item is given the name Open, and the macro assigned to
the menu item is the OPEN command.
Sub Ch6_AddAMenuItem()
Dim currMenuGroup As AcadMenuGroup
Set currMenuGroup = ThisDrawing.Application.MenuGroups.Item(0)
' Create the new menu
Dim newMenu As AcadPopupMenu
Set newMenu = currMenuGroup.Menus.Add("TestMenu")
' Add a menu item to the new menu
Dim newMenuItem As AcadPopupMenuItem
Dim openMacro As String
' Assign the macro the VBA equivalent of "ESC ESC _open "
openMacro = Chr(vbKeyEscape) + Chr(vbKeyEscape) + "_open "
Set newMenuItem = newMenu.AddMenuItem _
(newMenu.count + 1, "Open", openMacro)
' Display the menu on the menu bar
newMenu.InsertInMenuBar _
(ThisDrawing.Application.menuBar.count + 1)
End Sub

Add Separators to a Menu

To add a separator to a menu use the AddSeparator method. This method
cre- ates a new PopupMenuItem object and adds it to the designated menu.
This kind of PopupMenuItem object is assigned the type of acSeparator. The
type of a menu item can be found through the Type property.
The AddSeparator method takes the Index parameter as its only input. The
Index parameter is an integer that specifies the position of the separator
within the menu. The index begins with position zero (0) as the first
position on the menu after the title.

202 | Chapter 6 Customize Toolbars and

Menus

See Enable and disable menu items on page 208 for an example on
adding separators to a menu.

Assign an Accelerator Key to a Menu

Item
To assign the accelerator key for a menu item through AutoCAD ActiveX/
VBA, use the Label property of the given menu item. To specify an
accelerator key, insert the ASCII equivalent of an ampersand (&) in the label
directly in front of the character to be used as the accelerator. For example,
the label Chr(Asc("&")) + "Edit" will be displayed as Edit, with the
character E being used as the accelerator key.
Add accelerator keys to menus
This example repeats the example from Add menu items to a popup
menu on page 202, adding accelerator keys for both the TestMenu and
Open menus. The s is used as the accelerator key for the TestMenu
menu and the O is used as the accelerator key for the Open menu.
Sub Ch6_AddAMenuItem()
Dim currMenuGroup As AcadMenuGroup
Set currMenuGroup = ThisDrawing.Application.MenuGroups.Item(0)
' Create the new menu
Dim newMenu As AcadPopupMenu
Set newMenu = currMenuGroup.Menus.Add _
("Te" + Chr(Asc("&")) + "stMenu")
' Add a menu item to the new menu
Dim newMenuItem As AcadPopupMenuItem
Dim openMacro As String
' Assign the macro the VBA equivalent of "ESC ESC _open "
openMacro = Chr(vbKeyEscape) + Chr(vbKeyEscape) + "_open "
Set newMenuItem = newMenu.AddMenuItem _
(newMenu.count + 1, Chr(Asc("&")) _
+ "Open", openMacro)
' Display the menu on the menu bar
newMenu.InsertInMenuBar _
(ThisDrawing.Application.menuBar.count + 1)
End Sub

Create Cascading Submenus

To add a cascading submenu, create a submenu using the AddSubmenu
method. This method creates a new PopupMenuItem object and adds it to
the designated menu. This special kind of PopupMenuItem object is
assigned the type of acSubmenu.

Create and Edit Pull-Down and Shortcut

Menus | 203

The AddSubmenu method takes three parameters as input: Index, Label,

and
Tag.
The Index parameter is an integer that specifies the position of the new
menu item within the menu. The index begins with position zero (0) as the
first position on the menu after the title. To add the new menu item to the
end of a menu, set the Index parameter equal to the Count property of the
menu. (The Count property of the menu represents the total number of
menu items on that menu.)
The Label parameter is a string that defines the content and formatting of
menu items. The text that the user sees displayed for the menu item is
called the Caption, and it is derived from the label by interpreting all the
DIESEL string expressions and special codes contained in the label. For
example, the label &Edit produces the caption Edit.
The Tag parameter, or name tag, is a string consisting of alphanumeric and
underscore (_) characters. This string uniquely identifies the menu item
within a given menu.
The AddSubmenu method does not return the PopupMenuItem object that
it creates. Instead, it returns the new menu that the submenu points to. The
new menu, which is returned as a PopupMenu object, can then be
populated as a normal menu would be. For information on populating a
menu, see Add New Menu Items to a Menu on page 200.
Create and populate a submenu
This example creates a new menu called TestMenu and adds it to a submenu called OpenFile. The submenu is then populated with a menu
item called Open, which opens a drawing when executed. Finally, the
menu is displayed on the menu bar.

204 | Chapter 6 Customize Toolbars and

Menus

Sub Ch6_AddASubMenu()
Dim currMenuGroup As AcadMenuGroup
Set currMenuGroup = ThisDrawing.Application.MenuGroups.Item(0)
' Create the new menu
Dim newMenu As AcadPopupMenu
Set newMenu = currMenuGroup.Menus.Add("TestMenu")
' Add the submenu
Dim FileSubMenu As AcadPopupMenu
Set FileSubMenu = newMenu.AddSubMenu("", "OpenFile")
' Add a menu item to the sub menu
Dim newMenuItem As AcadPopupMenuItem
Dim openMacro As String
' Assign the macro the VB equivalent of "ESC ESC _open "
openMacro = Chr(vbKeyEscape) + Chr(vbKeyEscape) + "_open "
Set newMenuItem = FileSubMenu.AddMenuItem _
(newMenu.count + 1, "Open", openMacro)
' Display the menu on the menu bar
newMenu.InsertInMenuBar _
(ThisDrawing.Application.menuBar.count + 1)
End Sub

Delete Menu Items from a Menu

To remove menu items from a menu, use the Delete method found on the
menu item.

Warning! If you delete a menu item, do not call another method or

property that would directly or indirectly cause the same menu file to be
loaded again within the same macro. For example, after deleting a menu item,
do not use the MenuGroup.Load method or the
Preferences.Profiles.ActiveProfile property, or issue a "Menuload" command
using the Document.SendCommand method. These items directly or indirectly
cause the loading of menu files. You should only use these methods or
properties in a separate macro.

Create and Edit Pull-Down and Shortcut

Menus | 205

Delete a menu item from a menu

This example adds a menu item to the end of the last menu displayed on the
menu bar. It then deletes the menu item.
Sub Ch6_DeleteMenuItem()
Dim LastMenu As AcadPopupMenu
Set LastMenu = ThisDrawing.Application.menuBar. _
Item(ThisDrawing.Application.menuBar.count - 1)
' Add a menu item
Dim newMenuItem As AcadPopupMenuItem
Dim openMacro As String
' Assign the macro the VB equivalent of "ESC ESC _open "
openMacro = Chr(vbKeyEscape) + Chr(vbKeyEscape) + "_open "
Set newMenuItem = LastMenu.AddMenuItem _
(LastMenu.count + 1, "Open", openMacro)
' Remove the menu item from the menu
newMenuItem.Delete
End Sub

Explore the Properties of Menu Items

All menu items share the following properties:
TagString

A tag, or name tag, is a string consisting of

alphanumeric and underscore (_) characters. This string
uniquely identifies the menu item within a given
menu. Tags identify the accelerator keys (keyboard key
sequences) that correspond to the menu item.
You can read or write the value of a tag by using the
TagString property.

Label

A label is a string that defines the content and

formatting of menu items.
Menu item labels can contain DIESEL string
expressions that conditionally alter the labels each
time they are displayed.
You can read or write the value of a label by using the
Label property.

206 | Chapter 6 Customize Toolbars and

Menus

Caption

A caption is the text that the user sees displayed on the

menu. This property is read-only and is derived from
the Label property by removing any DIESEL string
expressions.
You can read the value of a caption by using the
Caption property.

Macro

A macro is a series of commands that executes specific

actions when a menu item is selected. Menu macros can
simply be recordings of keystrokes that accomplish a
task, or they can be a complex combination of
commands, AutoLISP, DIESEL, or ActiveX
programming code.
You can read or write the value of a menu macro by
using the Macro property.

HelpString

A help string is the text string that appears in the

AutoCAD status line when a user highlights a menu
item for selection.
You can read or write the value of a help string by
using the HelpString property.

Enable

Using the Enable property you can enable or disable a

menu item. You can also read the Enable property to
determine if a menu item is currently enabled or
disabled. Using this property to enable or disable a
menu item overrides any setting for enabling in the
DIESEL expression of the menu item.
See Enable and disable menu items on page 208 for
an example of disabling menu items.

Check

Using the Check property you can check or uncheck a

menu item. You can also read the Check property to
determine if a menu item is currently checked or
unchecked. Using this property to check or uncheck a
menu item overrides any setting for checking in the
DIESEL expression of the menu item.

Index

The index of a menu item specifies the position of that

menu item on the menu on which it belongs. The
index position of a menu always begins with position
0. For example, if the item is the first item on a menu,
it returns an index position of 0. If it is the second
item on a menu, it returns an index position of 1 and
so on.

Create and Edit Pull-Down and Shortcut

Menus | 207

Type

You can determine the type of a menu item by using the

Type property. A menu item can be one of the
following types: a regular menu, a separator, or the
heading for a submenu. If the item is a regular menu
item, this property returns acMenuItem. If the item is a
separator, this property returns acMenuSeparator. If the
item is a heading for a submenu, this property returns
acSubMenu.

SubMenu

You can find the submenu by using the SubMenu

property. If the menu item is of the type acSubMenu, this
property returns the menu that is attached as the
submenu, or embedded menu. The embedded menu is
returned as a PopupMenu object.
If the menu item is not of the type acSubMenu, this
property returns an error.

Parent

You can find the menu to which a menu item belongs

by using the Parent property. This property returns the
menu on which the menu item resides. The parent
menu is returned as a PopupMenu object.

Enable and disable menu items

This example creates a new menu called TestMenu and inserts two menu
items. The second menu item is then disabled using the Enable property
and the menu is displayed on the menu bar.

208 | Chapter 6 Customize Toolbars and

Menus

Sub Ch6_DisableMenuItem()
Dim currMenuGroup As AcadMenuGroup
Set currMenuGroup = ThisDrawing.Application.MenuGroups.Item(0)
' Create the new menu
Dim newMenu As AcadPopupMenu
Set newMenu = currMenuGroup.Menus.Add("TestMenu")
' Add two menu items and a menu separator to the new menu
Dim MenuEnable As AcadPopupMenuItem
Dim MenuDisable As AcadPopupMenuItem
Dim MenuSeparator As AcadPopupMenuItem
Dim openMacro As String
' Assign the macro the VB equivalent of "ESC ESC _open "
openMacro = Chr(vbKeyEscape) + Chr(vbKeyEscape) + "_open "
Set MenuEnable = newMenu.AddMenuItem _
(newMenu.count + 1, "OpenEnabled", openMacro)
Set MenuSeparator = newMenu.AddSeparator("")
Set MenuDisable = newMenu.AddMenuItem _
(newMenu.count + 1, "OpenDisabled", openMacro)
' Disable the second menu item
MenuDisable.Enable = False
' Display the menu on the menu bar
newMenu.InsertInMenuBar _
(ThisDrawing.Application.menuBar.count + 1)
End Sub

Create and Edit Toolbars

Using AutoCAD ActiveX/VBA you can create and edit toolbars within an
existing menu group.

Create
Toolbars

New

To create a new toolbar, use the Add method to add a new Toolbar object to
the Toolbars collection.
The Add method requires as input the name of the toolbar to add. The name
is a string of alphanumeric characters with no punctuation other than a
dash () or an underscore (_). The name is the easiest way of identifying the
tool- bar within the collection.
You can change the name of a toolbar once it has been created. To
change the name of an existing toolbar, use the Name property for that
toolbar.

Create and Edit Toolbars

209

Create a new toolbar

This example creates a new toolbar called TestToolbar in the first menu
group in the MenuGroups collection.
Sub Ch6_CreateToolbar()
Dim currMenuGroup As AcadMenuGroup
Set currMenuGroup = ThisDrawing.Application.MenuGroups.Item(0)
' Create the new toolbar
Dim newToolbar As AcadToolbar
Set newToolbar = currMenuGroup.Toolbars.Add("TestToolbar")
End Sub

Add New Toolbar Buttons to a

Toolbar
To add a new toolbar button to a toolbar use the AddToolbarButton method.
This method creates a new ToolbarItem object and adds it to the designated
toolbar. You should only add buttons to a toolbar while the toolbar is
visible.
The AddToolbarButton method takes five parameters as input: Index,
Name,
HelpString, Macro, and FlyoutButton.
Index

The Index parameter is an integer that specifies the

position of the new Toolbar item within the toolbar.
The index begins with position zero (0) as the first
position on the toolbar after the title. To add the new
toolbar button to the end of a toolbar, set the Index
parameter equal to the Count property of the toolbar.
(The Count property of the toolbar represents the total
number of toolbar buttons on that toolbar.)
Once a toolbar button has been created, you cannot
change the index of the button through the Index
property. To change the index of an existing toolbar
button, you must delete and re-add the toolbar button
to a different position, or add or delete surrounding
toolbar buttons until a proper placement is achieved.

Name

A name is a string that identifies the toolbar button.

The string must comprise alphanumeric characters
with no punctuation other than a dash () or an
underscore (_). This string is displayed as the tooltip
when the cursor is placed over the toolbar button.
Once a toolbar button has been created, you can
change the name using the Name property.

210 | Chapter 6 Customize Toolbars and

Menus

Help String

A help string is the text string that appears in the

AutoCAD status line when a user highlights a menu
item for selection.
Once a toolbar button has been created, you can
change the help string for the button using the
HelpString property.

Macro

A macro is a series of commands that executes specific

actions when a toolbar button is selected. Toolbar
macros can be simply recordings of keystrokes that
accomplish a task, or they can be a complex
combination of commands, AutoLISP, DIESEL, or
ActiveX programming code.
Once a Toolbar button has been created, you can
change the macro for the button using the Macro
property.

FlyoutButton

The FlyoutButton parameter is an optional flag

stating whether or not the new button is to be a flyout
button. If the new button is to be a flyout button, this
parameter must be set to TRUE. If the new button is not
to be a flyout button, this parameter can be set to
FALSE or it can be ignored.

Add buttons to a new toolbar

This example creates a new toolbar and adds a button to the toolbar. The
button is assigned a macro that will execute the OPEN command when the
button is selected.
Sub Ch6_AddButton()
Dim currMenuGroup As AcadMenuGroup
Set currMenuGroup = ThisDrawing.Application.MenuGroups.Item(0)
' Create the new toolbar
Dim newToolbar As AcadToolbar
Set newToolbar = currMenuGroup.Toolbars.Add("TestToolbar")
' Add a button to the new toolbar
Dim newButton As AcadToolbarItem
Dim openMacro As String
' Assign the macro the VB equivalent of "ESC ESC _open "
openMacro = Chr(vbKeyEscape) + Chr(vbKeyEscape) + "_open "
Set newButton = newToolbar.AddToolbarButton _
("", "NewButton", "Open a file.", openMacro)
End Sub

Create and Edit Toolbars

211

Add Separators to a Toolbar

To add a separator to a toolbar use the AddSeparator method. This method
creates a new ToolbarItem object and adds it to the designated toolbar. This
kind of ToolbarItem object is assigned the type of acSeparator. The type of
a Toolbar button can be found through the Type property.
The AddSeparator method takes one parameter as input: Index. The Index
parameter is an integer that specifies the position of the separator within the
toolbar. The index begins with position zero (0) as the first position on the
toolbar after the title.

Define the Toolbar Button Image

To define the images to be used on a toolbar button, use the SetBitmaps and
GetBitmaps methods.
The SetBitmaps method takes two parameters: SmallIconName and
LargeIconName.
SmallIconName

The small icon name identifies the ID string of the

small-image resource (16 15 bitmap). The string must
comprise alphanumeric characters with no
punctuation other than a dash () or an underscore (_),
and should include the .bmp extension. The resource
can be either a system bitmap or a user-defined bitmap.
User-defined bitmaps must be of the appropriate size
and must reside in the Support path.

LargeIconName

The large icon name identifies the ID string of the largeimage resource (24 22 bitmap). The string must
comprise alphanumeric characters with no
punctuation other than a dash () or an underscore (_),
and should include the .bmp extension. The resource
can be either a system bitmap or a user-defined bitmap.
User-defined bitmaps must be of the appropriate size
and must reside in the Support path.

212 | Chapter 6 Customize Toolbars and

Menus

Query an existing toolbar to find the name of the icons for the buttons
Sub Ch6_GetButtonImages()
Dim Button As AcadToolbarItem
Dim Toolbar0 As AcadToolbar
Dim MenuGroup0 As AcadMenuGroup
Dim SmallButtonName As String
Dim LargeButtonName As String
Dim msg As String
Dim ButtonType As String
' Get the first toolbar in the first menu group
Set MenuGroup0 = ThisDrawing.Application. _
MenuGroups.Item(0)
Set Toolbar0 = MenuGroup0.Toolbars.Item(0)
' Clear the string variables
SmallButtonName = ""
LargeButtonName = ""
' Create a header for the message box and
' display the toolbar to be queried
msg = "Toolbar: " + Toolbar0.Name + vbCrLf
Toolbar0.Visible = True
' Iterate through the toolbar and collect data
' for each button in the toolbar. If the toolbar is
' a normal button or a flyout, collect the small
' and large button names for the button.
For Each Button In Toolbar0
ButtonType = Choose(Button.Type + 1, "Button", _
"Separator", "Control", "Flyout")
msg = msg & ButtonType & ":
"
If Button.Type = acToolbarButton Or _
Button.Type = acToolbarFlyout Then
Button.GetBitmaps SmallButtonName, _
LargeButtonName
msg = msg + SmallButtonName + ", " _
+ LargeButtonName
End If
msg = msg + vbCrLf
Next Button
' Display the results
MsgBox msg
End Sub

Create Flyout Toolbars

To add a flyout toolbar button to a toolbar, use the AddToolbarButton
method. This method creates a new ToolbarItem object and adds it to the
designated toolbar.

Create and Edit Toolbars

213

The AddToolbarButton method takes five parameters as input: Index,

Name, HelpString, Macro, and FlyoutButton. By setting the parameter
Flyout to TRUE, the new button will be created as a flyout button. The return
value from this method will be the new flyout toolbar. The flyout toolbar
can then be populated as a normal toolbar would be.
For more information about populating a toolbar, see Add New Toolbar
But- tons to a Toolbar on page 210.
Create a flyout toolbar button
This example creates two toolbars. The first toolbar contains a flyout
button. The second toolbar is attached to the flyout button on the first
toolbar.
Sub Ch6_AddFlyoutButton()
Dim currMenuGroup As AcadMenuGroup
Set currMenuGroup = ThisDrawing.Application. _
MenuGroups.Item(0)
' Create the first toolbar
Dim FirstToolbar As AcadToolbar
Set FirstToolbar = currMenuGroup.Toolbars. _
Add("FirstToolbar")
' Add a flyout button to the first menu on the menu bar
Dim FlyoutButton As AcadToolbarItem
Set FlyoutButton = FirstToolbar.AddToolbarButton _
("", "Flyout", "Demonstrates a flyout button", _
"OPEN", True)
' Create the second toolbar. This will be attached to
' the first toolbar via the flyout button.
Dim SecondToolbar As AcadToolbar
Set SecondToolbar = currMenuGroup.Toolbars. _
Add("SecondToolbar")
' Add a button to the next toolbar
Dim newButton As AcadToolbarItem
Dim openMacro As String
' Assign the macro the VB equivalent of "ESC ESC _open "
openMacro = Chr(vbKeyEscape) + Chr(vbKeyEscape) + "_open "
Set newButton = SecondToolbar.AddToolbarButton _
("", "NewButton", "Open a file.", openMacro)
' Attach the second toolbar to the flyout
' button on the first toolbar
FlyoutButton.AttachToolbarToFlyout currMenuGroup.Name, _
SecondToolbar.Name
' Display the first toolbar, hide the second toolbar
FirstToolbar.Visible = True
SecondToolbar.Visible = False
End Sub

214 | Chapter 6 Customize Toolbars and

Menus

Float and Dock Toolbars

Toolbars can be docked or floated programmatically.
To float a toolbar, use the Float method for the toolbar. The Float method
takes three parameters as input: Top, Left, and NumberFloatRows. The Top
and Left parameters specify the pixel location for the top and left edge of
the toolbar. The NumberFloatRows specifies the number of rows with which
to create a horizontal toolbar. This number must be equal to or greater than
one. The buttons of the toolbar will be distributed equally across the
number of rows specified. For vertically aligned toolbars, this value
specifies the number of columns.
To dock a toolbar, use the Dock method for the toolbar. The Dock method
takes three parameters as input: Side, Row, and Column. The Side parameter
specifies the side of the toolbar that you will be positioning in the docking
maneuver. You can specify the top, bottom, left, or right side of the toolbar.
The Row and Column parameters specify a number on the existing rows and
columns of docked toolbars at which to dock the toolbar.
You can query a toolbar to see if it is docked by using the DockStatus property. The DockStatus property will return TRUE if the toolbar is docked and
FALSE if the toolbar is floating.
Dock a toolbar
This example creates a new toolbar with three buttons on it. The toolbar is
then displayed and docked on the left side of the screen.

Create and Edit Toolbars

215

Sub Ch6_DockToolbar()
Dim currMenuGroup As AcadMenuGroup
Set currMenuGroup = ThisDrawing.Application. _
MenuGroups.Item(0)
' Create the new toolbar
Dim newToolbar As AcadToolbar
Set newToolbar = currMenuGroup.Toolbars. _
Add("TestToolbar")
' Add three buttons to the new toolbar.
' All three buttons will have the same macro attached.
Dim newButton1 As AcadToolbarItem
Dim newButton2 As AcadToolbarItem
Dim newButton3 As AcadToolbarItem
Dim openMacro As String
' Assign the macro the VB equivalent of "ESC ESC _open "
openMacro = Chr(vbKeyEscape) + Chr(vbKeyEscape) + "_open "
Set newButton1 = newToolbar.AddToolbarButton _
("", "NewButton1", "Open a file.", openMacro)
Set newButton2 = newToolbar.AddToolbarButton _
("", "NewButton2", "Open a file.", openMacro)
Set newButton3 = newToolbar.AddToolbarButton _
("", "NewButton3", "Open a file.", openMacro)
' Display the toolbar
newToolbar.Visible = True
' Dock the toolbar to the left of the screen.
newToolbar.Dock acToolbarDockLeft
End Sub

Delete Toolbar Buttons from a

Toolbar
To remove toolbar buttons from a toolbar, use the Delete method found on
the toolbar button. You should only delete buttons from a toolbar while the
toolbar is visible.

Explore
the
Toolbar Items

Properties

All toolbar items share the following properties:

216 | Chapter 6 Customize Toolbars and

Menus

of

Tagstring

A tag, or name tag, is a string consisting of

alphanumeric and underscore (_) characters. This string
uniquely identifies the toolbar item within a given
toolbar. A new tag is assigned automatically when a
toolbar item is created.
You can read or write the value of a tag by using the
Tagstring property.

Name

A name is a string identifying the toolbar item. It is also

the string used for the tooltip text, which is the text
string that pops up in AutoCAD when a user holds the
mouse or another pointing device over the toolbar
item.
You can read or write the value of a name by using the
Name property.

Macro

A macro is a series of commands that executes specific

actions when a toolbar item is selected. Macros can
simply be recordings of keystrokes that accomplish a
task, or they can be a complex combination of
commands, AutoLISP, DIESEL, or ActiveX
programming code.
You can read or write the value of a macro by using the
Macro property.

HelpString

A help string is the text string that appears in the

AutoCAD status line for a toolbar button.
You can read or write the value of a help string by
using the HelpString property.

Index

The index of a toolbar item specifies the position of that

toolbar item on the toolbar to which it belongs. The
index position of a toolbar always begins with position
0. For example, if the item is the first item on a
toolbar, it will have an index position of 0. If it is the
second item on a toolbar, it will have an index
position of 1, and so on.
You can read the index position of a toolbar item by
using the Index property.

Create and Edit Toolbars

217

Type

A toolbar item can be one of the following types: a

regular toolbar button, a separator, a flyout toolbar
button, or a special control element. If the item is a
regular toolbar button, this property returns acButton.
If the item is a separator, this property returns
acToolButtonSeparator. If the item is a flyout button,
this property returns acFlyout. If the item is a special
control element, this property returns acControl.
You can determine the type of a toolbar item by using
the Type property.

Flyout

If the toolbar item is of the type acFlyout, this property

returns the toolbar that is attached as the flyout
toolbar. The flyout toolbar is returned as a Toolbar
object.
If the menu item is not of the type acFlyout, this
property returns NULL.
You can find the flyout toolbar of a toolbar item by
using the Flyout property.

Parent

This property returns the toolbar on which the toolbar

item resides. The Parent toolbar is returned as a
Toolbar object.
You can find the toolbar to which a toolbar item
belongs by using the Parent property.

Toolbar
Properties

There are other properties that apply to all toolbar

items on the toolbar. Such properties include: whether
the toolbar is docked or floating, visible or hidden,
and whether the toolbar uses large buttons or small
buttons.

Create Macros
A macro is a series of commands that executes specific actions when a
toolbar item is selected. Macros can simply be recordings of keystrokes that
accom- plish a task, or they can be a complex combination of commands,
AutoLISP, DIESEL, or ActiveX programming code.
If you intend to include command parameters in a menu macro, you must
know the sequence in which that command expects its parameters. Every
character in a menu macro is significant, even the blank spaces. As
AutoCAD is revised and enhanced, the sequence of prompts for various
commands (and sometimes even the command names) might change.
Therefore, your

218 | Chapter 6 Customize Toolbars and

Menus

custom menus might require minor changes when you upgrade to a new
release of AutoCAD.
When command input comes from a menu item, the settings of the
PICKADD and PICKAUTO system variables are assumed to be 1 and 0,
respectively. This preserves compatibility with previous releases of
AutoCAD and makes customization easier because you are not required to
check the settings of these variables.

Macro Characters Mapped to ASCII

Equivalents
The following table provides a synopsis of special characters used in menu
macros and their equivalent ASCII numbers as they are used in VB and
VBA. Use the ASCII equivalent for these special characters when creating the
string for the Macro property.
Special characters used in menu and toolbar macros
Character

ASCII equivalent

Description

chr(59)

Issues ENTER

^M

chr(13)

Issues ENTER

^|

chr(94) + chr(124)

Issues TAB

SPACEBAR

chr(32)

Enters a space; blank space between

command sequences in a menu item is
equivalent to pressing the SPACEBAR

chr(92)

Pauses for user input

chr(95)

Translates AutoCAD commands and key

words that follow

chr(43)

Continues menu macro to the next line

(if last character)

=*

chr(61) + chr(42)

Displays the current top-level image,

pull-down, or shortcut menu

*^C^C

chr(42) + chr(3) + chr(3)

Prefix for a repeating item

chr(36)

Loads a menu section or introduces a

conditional DIESEL macro expression

^B

chr(2)

Toggles Snap on or off (CTRL+B)

Create Macros
219

Special characters used in menu and toolbar macros

(continued)
Character

ASCII equivalent

Description

^C

chr(3)

Cancels command (CTRL+C)

ESC

chr(3)

Cancels command (ESC)

^D

chr(4)

Toggles Coords on or off (CTRL+D)

^E

chr(5)

Sets the next isometric plane (CTRL+E)

^G

chr(7)

Toggles Grid on or off (CTRL+G)

^H

chr(8)

Issues backspace

^O

chr(15)

Toggles Ortho on or off (CTRL+O)

^P

chr(16)

Toggles MENUECHO on or off

^Q

chr(17)

Echoes all prompts, status listings, and

input to the printer (CTRL+Q)

^T

chr(20)

Toggles Tablet on or off (CTRL+T)

^V

chr(22)

Changes current viewport (CTRL+V)

^Z

chr(26)

Null character that suppresses the

automatic addition of SPACEBAR at the
end of a menu item

Macro Termination
When a macro is executed, AutoCAD places a space at the end of the macro
before processing the
command sequence. AutoCAD processes the
following menu macro as though you had entered line SPACEBAR.
line

Sometimes this is undesirable; for example, the TEXT or DIM command

must be terminated by ENTER, not by a space. Also, it sometimes takes
more than one space (or ENTER) to complete a command, but some text
editors dont let you create a line with trailing blanks. Two special
conventions get around these problems.

When a semicolon (;) appears in a macro, AutoCAD substitutes an ENTER.

If a line ends with a control character, a backslash (\), a plus sign (+), or
a semicolon (;), AutoCAD does not add a blank after it.

220 | Chapter 6 Customize Toolbars and

Menus

Look at the following macro:

erase \;

If this item simply ended with the backslash (which indicates user input), it
would fail to complete the ERASE operation, because AutoCAD doesnt add a
blank after the backslash. Therefore, this macro uses a semicolon (;) to force
an ENTER after the user input. Here are more examples:
ucs
ucs ;
text \.4 0 DRAFT Inc;;;Main St.;;;City, State;

Selecting the first macro enters ucs and SPACEBAR on the command line,
and the following prompt appears:
Enter an option [New/Move/orthoGraphic/Prev/Restore/Save/Del/Apply/?/
World] <World>:
Selecting the second macro enters ucs, SPACEBAR, and semicolon (;) at the
command line, which accepts the default value, World. No difference
between the first and second item would be evident on the screen;
naturally, you wouldnt put both on the same menu.
Selecting the third macro displays a prompt for a starting point and then
draws the address on three lines. In the triple-semicolon (;;;), the first
semicolon ends the text string, the second causes repetition of the TEXT command, and the third calls for the default placement below the previous line.

Note All special characters must be input using their ASCII equivalents. For
a list of ASCII equivalents, see Macro Characters Mapped to ASCII
Equivalents.

Pause for User Input

Sometimes it is useful to accept input from the keyboard or the pointing
device in the midst of a macro by placing a backslash (\) at the point
where you want input.
circle \1
layer off \;

Create Macros
221

The first macro pauses to ask the user for the center point and then reads a
radius of 1 from the macro. Note that there is no space after the backslash
character (\). The next macro pauses to ask the user to enter one layer
name, then turns that layer off and exits the LAYER command. The LAYER
command normally prompts for another operation and exits only if you
press SPACEBAR (blank) or ENTER (;).
Normally, the macro resumes after one item is entered. Therefore, it isnt possible to construct a macro that accepts a variable number of inputs (as in
object selection) and then continues. However, an exception is made for the
SELECT command; a backslash suspends the macro until object selection has
completed. For example, consider the following macro:
select \change previous ;properties color red ;

This macro uses the SELECT command to create a selection set of one or more
objects. It then issues the CHANGE command, references this selection set
using the Previous option, and changes the color of all selected objects to
red.
Because the backslash character (\) causes a macro to pause for user input,
you cannot use a backslash for any other purpose in a macro. When
specify- ing file directory paths, use a forward slash (/) as the path delimiter:
for exam- ple, /direct/file.
The following circumstances delay resumption of a macro:

If input of a point is expected, Object Snap modes may precede entry of

the actual point.
If X/Y/Z point filters are used, the macro remains suspended until the
entire point has been accumulated.
For the SELECT command only, the macro doesnt resume until
object selection has been completed.
If the user responds with a transparent command, the suspended macro
remains suspended until the transparent command is completed and the
originally requested input is received.
If the user responds by choosing another macro (to supply options or to
execute a transparent command), the original macro is suspended, and
the newly selected item is processed to completion before the suspended
macro is resumed.

Cancel a Command
To make sure you have no previous incomplete commands, use ^C^C in a
macro. This is the same as pressing ESC twice from the keyboard. Although
a single ^C cancels most commands, ^C^C is required to return to the

222 | Chapter 6 Customize Toolbars and

Menus

Command prompt from a DIM command. Therefore, ^C^C ensures that

AutoCAD returns to the Command prompt in most cases.

Macro Repetition
Once you have selected a command, you are likely to use it several times
before moving on to another command. That is how most people use tools;
you pick up a tool, do several things with it, then pick up another tool,
and so on. To avoid picking up the tool before each use, AutoCAD provides
a command repetition capability, triggered by a null response. However,
you cannot use this feature to specify command options.
This feature makes it possible for you to repeat frequently used commands
until you choose another command. If a macro begins with *^C^C immediately following the item label, the macro is saved in memory. Subsequent
Command prompts are answered by that macro until it is terminated by ESC
or by the selection of another macro.
Do not use ^C (Cancel) within a macro that begins with the string *^C^C;
this cancels the macro repetition.
The following is an example of the repetitive, or modal, approach to
command handling.
*^C^CMOVE Single
*^C^CCOPY Single
*^C^CERASE Single
*^C^CSTRETCH Single Crossing
*^C^CROTATE Single
*^C^CSCALE Single

Macro repetition does not work for items in image tile menus.

Use of Single Object Selection Mode

Single object selection puts object selection in single selection mode,
disables the normal dialog conducted by object selection, and causes the
selection to return the first object(s) selected by a subsequent option. This
can be quite handy in a macro. For example, consider the following macro:
*^C^CERASE single

Create Macros
223

This macro terminates the current command and activates the ERASE command with the single selection option. After you select this item, you either
point to the single object to be erased or point to a blank area and specify a
window. The object(s) selected in this way are erased, and the macro is
repeated (due to the leading asterisk) so that you can erase something else.
Single selection mode leads to more dynamic interaction with AutoCAD.

Create Status-Line Help for Menu

Items and
Toolbar Items
Status-line help messages are an important aspect of native help support.
These are the simple, descriptive messages that appear in the status line
when a menu or toolbar item is highlighted. The status-line help for all
menu and toolbar items is contained in the HelpString property for that
item.
The HelpString property is empty when the menu or toolbar item is first
created.
Add status-line help to a menu item
This example creates a new menu called TestMenu and then creates a
menu item called Open. The menu item is then assigned status-line
help via the HelpString property.

224 | Chapter 6 Customize Toolbars and

Menus

Sub Ch6_AddHelp()
Dim currMenuGroup As AcadMenuGroup
Set currMenuGroup = ThisDrawing.Application.MenuGroups.Item(0)
' Create the new menu
Dim newMenu As AcadPopupMenu
Set newMenu = currMenuGroup.Menus.Add _
("Te" + Chr(Asc("&")) + "stMenu")
' Add a menu item to the new menu
Dim newMenuItem As AcadPopupMenuItem
Dim openMacro As String
' Assign the macro the VBA equivalent of "ESC ESC _open "
openMacro = Chr(vbKeyEscape) + Chr(vbKeyEscape) + "_open "
' Create the menu item
Set newMenuItem = newMenu.AddMenuItem _
(newMenu.count + 1, Chr(Asc("&")) _
+ "Open", openMacro)
' Add the status line help to the menu item
newMenuItem.HelpString = "Opens an AutoCAD drawing file."
' Display the menu on the menu bar
newMenu.InsertInMenuBar _
(ThisDrawing.Application.menuBar.count + 1)
End Sub

Add Entries to the Right-Click Menu

The right-click menu, or shortcut menu, is a special menu included in the
AutoCAD base menu group. This menu appears when the user holds SHIFT
and clicks the right mouse button.
AutoCAD finds the shortcut menu by looking in the base menu group for a
menu with the ShortcutMenu property equal to TRUE. You can add new
menu items to the shortcut menu by following the steps listed in Add New
Menu Items to a Menu on page 200.

Add Entries to the Right-Click Menu

| 225

New menu groups may or may not have a shortcut menu available. To
create a shortcut menu for a menu group, follow the guidelines listed in
Create New Menus on page 200, and use POP0 as the label for the new
menu.
Add a menu item to the end of the right-click menu
This example adds the menu item OpenDWG to the end of the right-click
menu.
Sub Ch6_AddMenuItemToshortcutMenu()
Dim currMenuGroup As AcadMenuGroup
Set currMenuGroup = ThisDrawing.Application.MenuGroups.Item(0)
' Find the shortcut menu and assign it to the
' shortcutMenu variable
Dim scMenu As AcadPopupMenu
Dim entry As AcadPopupMenu
For Each entry In currMenuGroup.Menus
If entry.shortcutMenu = True Then
Set scMenu = entry
End If
Next entry
' Add a menu item to the shortcut menu
Dim newMenuItem As AcadPopupMenuItem
Dim openMacro As String
' Assign the macro the VBA equivalent of "ESC ESC _open "
openMacro = Chr(vbKeyEscape) + Chr(vbKeyEscape) + "_open "
Set newMenuItem = scMenu.AddMenuItem _
("", Chr(Asc("&")) _
+ "OpenDWG", openMacro)
End Sub

226 | Chapter 6 Customize Toolbars and

Menus

Use Events

Events are notifications, or messages, that are sent out

In this chapter

by AutoCAD to inform you about the current state of

Understand the Events in

the session, or alert you that something has happened.

Guidelines for Event

For example, when a drawing is opened the BeginOpen

event is triggered. This event contains the name of the
AutoCAD drawing that was opened. There is another
event triggered when a drawing is closed. Given this

AutoCAD
Handlers
Handle Application Level

Events

Handle Document Level

Events

Handle Object Level

Events

information you could write a subroutine, or event handler, that uses these events to track the amount of time
a user spends working on a particular drawing.

227

Understand the Events in

AutoCAD
There are three types of events in AutoCAD:

Application level events respond to changes in the AutoCAD

application and its environment. These events respond to the opening,
saving, closing and printing of drawings, creation of new drawings,
issuing of AutoCAD commands, loading or unloading of ARX and LISP
applications, changes to system variables, and changes to the
Application window.
Document level events respond to the changes of a specific document or
its contents. These events respond to the addition, deletion, or modification of objects, activation of a shortcut menu, changes in the pickfirst
selection set, changes to the Drawing window, and regeneration of the
drawing. There are also document level events for the opening, closing,
and printing of a drawing, and the loading or unloading of ARX and LISP
applications from the drawing.
Object level events respond to the changes of a specific object.
Currently there is only one object level event. It is triggered whenever an
object is modified.

Subroutines that respond to events are called event handlers and are executed
automatically each and every time their designated event is triggered.
Infor- mation contained in events, such as the drawing name in the
BeginOpen event, are passed to event handlers through parameters.

Guidelines for Event Handlers

It is important to remember that events simply provide information on the
state or activities taking place within AutoCAD. Although event handlers can
be written to respond to those events, AutoCAD is often in the middle of processing commands when the event handler is triggered. Event handlers,
therefore, have some restrictions on what they can do if they are to provide
safe operations in conjunction with AutoCAD and its database.

Do not rely on the sequence of events.

When writing event handlers, do not rely on the sequence of events to
happen in the exact order you think they occur. For example, if you issue
an OPEN command, the events BeginCommand, BeginOpen, EndOpen,
and EndCommand will all be triggered. However, they may not occur in
that order. The only event sequence you can safely rely on is that a Begin
event will occur before the corresponding End event. In the previous

228 | Chapter 7 Use

Events

example, the events may get triggered in the following order:

BeginCommand, BeginOpen, EndCommand, and EndOpen, or even
BeginCommand, EndCommand, BeginOpen, and EndOpen.

Do not rely on the sequence of operations.

If you delete object1 and then object2, do not rely on the fact that you
will receive the ObjectErased event for object1 and then for object2. You
may receive the ObjectErased event for object2 first.

Do not attempt any interactive functions from an event handler.

Attempting to execute interactive functions from within an event
handler can cause serious problems, as AutoCAD may still be processing
a com- mand at the time the event is triggered. Therefore, you should
always avoid the use of input-acquisition methods such as GetPoint,
GetEntity, GetKeyword, and so on, as well as selection set operations
and the Send- Command method from within event handlers.

Do not launch a dialog box from within an event handler.

Dialog boxes are considered interactive functions and can interfere with
the current operation of AutoCAD. Message boxes and alert boxes are not
considered interactive and can be issued safely, however issuing a
message box within an event handler for the BeginModal, EndModal,
Activate, Deactivate, and BeginRightClick events results in unexpected
sequencing.

You can write data to any object in the database, except the object
that issued the event.
Obviously, any object causing an event to be triggered could still be open
for use with AutoCAD and the operation currently in progress. Therefore,
avoid writing any information to an object from an event handler for the
same object. However, you can safely read information from the object
triggering an event. For example, suppose you have a floor that is filled
with tiles and you create an event handler attached to the border of the
floor. If you change the size of the floor, the event handler will automatically add or subtract tiles to fill the new area. The event handler will be
able to read the new area of the border, but it cannot attempt any changes
on the border itself.

Do not perform any action from an event handler that will trigger
the same event.
If you perform the same action in an event handler that triggers that
same event, you will create an infinite loop. For example, you should
never attempt to open a drawing from within the BeginOpen event, or
AutoCAD will simply continue to open more drawings until the maximum number of open drawings is reached.

Remember that no events will be fired while AutoCAD is displaying

a modal dialog.

Guidelines for Event Handlers

| 229

Handle Application Level Events

Application level events are not persistent in AutoCAD VBA. That is, they
are not automatically enabled when a VBA project is loaded. Application
level events must therefore be enabled for VBA and all other ActiveX
Automation controllers.
Once the application level events are enabled, you have a wide range of
events available to you. These events include:
AppActivate

Triggered just before the main Application window is

activated.

AppDeactivate

Triggered just before the main Application window is

deactivated.

ARXLoaded

Triggered when an ObjectARX application has been

loaded.

ARXUnloaded

Triggered when an ObjectARX application has been

unloaded.

BeginCommand

Triggered immediately after a command is issued, but

before it completes.

BeginFileDrop

Triggered when a file is dropped on the main

Application window.

BeginLISP

Triggered immediately after AutoCAD receives a

request to evaluate a LISP expression.

BeginModal

Triggered just before a modal dialog box is displayed.

BeginOpen

Triggered immediately after AutoCAD receives a

request to open an existing drawing.

BeginPlot

Triggered immediately after AutoCAD receives a

request to print a drawing.

BeginQuit

Triggered just before an AutoCAD session ends.

BeginSave

Triggered immediately after AutoCAD receives a

request to save the drawing.

EndCommand

Triggered immediately after a command completes.

EndLISP

Triggered upon completion of evaluating a LISP

expression.

230 | Chapter 7 Use

Events

EndModal

Triggered just after a modal dialog box is dismissed.

EndOpen

Triggered immediately after AutoCAD finishes opening

an existing drawing.

EndPlot

Triggered after a document has been sent to the printer.

EndSave

Triggered when AutoCAD has finished saving the

drawing.

LISPCancelled

Triggered when the evaluation of a LISP expression is

canceled.

NewDrawing

Triggered just before a new drawing is created.

SysVarChanged

Triggered when the value of a system variable is

changed.

WindowChanged

Triggered when there is a change to the Application

window.

WindowMovedOrResized
Triggered just after the Application window has been
moved or resized.

Enable Application Level Events

Before you can use application level events you must create a new class
mod- ule and declare an object of type AcadApplication with events. For
example, assume that a new class module is created and called
EventClassModule. The new class module contains the declaration of the
application with the VBA keyword WithEvents.
To create a new class and declare an Application object with events
1 In the VBA IDE, insert a class module. From the Insert menu, choose Class
Module.
2 Select the new class module in the Project window.
3 Change the name of the class in the Properties window to EventClassModule.
4 Open the Code window for the class using F7 , or by selecting the menu
option View Code.
5 In the Code window for the class, add the following line:
Public WithEvents App As AcadApplication

Handle Application Level Events

| 231

After the new object has been declared with events, it appears in the Object
drop-down list box in the class module, and you can write event procedures
for the new object in the class module. (When you select the new object in
the Object box, the valid events for that object are listed in the Procedure
drop-down list box.)
Before the procedures will run, however, you must connect the declared
object in the class module with the Application object. You can do this
with the following code from any module.
To connect the declared object to the Application object
1 In the Code window for your main module, add the following line to the
declarations section:
Dim X As New EventClassModule

2 In the same window, add the following subroutine:

Sub InitializeEvents()
Set X.App = ThisDrawing.Application
End Sub

3 In the code for your main module, add a call to the InitializeEvents
subroutine:
Call InitializeEvents

Once the InitializeEvents procedure has been run, the App object in the
class module points to the Application object specified, and any event
procedures in the class module will run when the events occur.
Prompt to continue when a drawing is dropped into AutoCAD
This example intercepts the load process when a file has been dragged and
dropped into AutoCAD. A message box containing the name of the file that
was dropped and Yes/No/Continue buttons that allow the user to decide if
the file should continue to be loaded display. If the user chooses to cancel out
of the operation, that decision is returned through the Cancel parameter of
the BeginFileDrop event and the file is not loaded.

232 | Chapter 7 Use

Events

Public WithEvents ACADApp As AcadApplication

Sub Example_AcadApplication_Events()
' This example intializes the public variable (ACADApp)
' which will be used to intercept AcadApplication Events
'
' Run this procedure FIRST!
' We could get the application from the ThisDocument
' object, but that would require having a drawing open,
' so we grab it from the system.
Set ACADApp = GetObject(, "AutoCAD.Application.16")
End Sub
Private Sub ACADApp_BeginFileDrop _
(ByVal FileName As String, Cancel As Boolean)
' This example intercepts an Application BeginFileDrop event.
'
' This event is triggered when a drawing file is dragged
' into AutoCAD.
'
' To trigger this example event:
'
1) Make sure to run the example that initializes
'
the public variable (named ACADApp) linked to this event.
'
'
2) Drag an AutoCAD drawing file into the AutoCAD
'
application from either the Windows Desktop
'
or Windows Explorer
' Use the "Cancel" variable to stop the loading of the
' dragged file, and the "FileName" variable to notify
' the user which file is about to be dragged in.
If MsgBox("AutoCAD is about to load " & FileName & vbCrLf _
& "Do you want to continue loading this file?", _
vbYesNoCancel + vbQuestion) <> vbYes Then
Cancel = True
End If
End Sub

Handle Document Level

Events
Document level events are persistent in AutoCAD VBA. That is, they are
auto- matically enabled when a VBA project is loaded. However, they are
not enabled for any other controller, such as VB. Document level events
must therefore be enabled for all other ActiveX Automation controllers.

Handle Document Level Events

| 233

Once the document level events are enabled, you have a wide range of
events available to you. These events include
Activate

Triggered when a Document window is activated.

BeginClose

Triggered just before a document is closed.

BeginCommand

Triggered immediately after a command is issued, but

before it completes.

BeginDoubleClick
Triggered after the user double-clicks on an object in
the drawing.
BeginLISP

Triggered immediately after AutoCAD receives a

request to evaluate a LISP expression.

BeginPlot

Triggered immediately after AutoCAD receives a

request to print a drawing.

BeginRightClick
Triggered after the user right-clicks on the Drawing
window.
BeginSave

Triggered immediately after AutoCAD receives a

request to save the drawing.

BeginShortcutMenuCommand
Triggered after the user right-clicks on the Drawing
window, and before the shortcut menu appears in
Command mode.
BeginShortcutMenuDefault
Triggered after the user right-clicks on the Drawing
window, and before the shortcut menu appears in
Default mode.
BeginShortcutMenuEdit
Triggered after the user right-clicks on the Drawing
window, and before the shortcut menu appears in Edit
mode.
BeginShortcutMenuGrip
Triggered after the user right-clicks on the Drawing
window, and before the shortcut menu appears in Grip
mode.

234 | Chapter 7 Use

Events

BeginShortcutMenuOsnap
Triggered after the user right-clicks on the Drawing
window, and before the shortcut menu appears in
Osnap mode.
Deactivate

Triggered when the Drawing window is deactivated.

EndCommand

Triggered immediately after a command completes.

EndLISP

Triggered upon completion of evaluating a LISP

expression.

EndPlot

Triggered after a document has been sent to the printer.

EndSave

Triggered when AutoCAD has finished saving the

drawing.

EndShortcutMenu
Triggered after the shortcut menu appears.
LayoutSwitched

Triggered after the user switches to a different layout.

LISPCancelled

Triggered when the evaluation of a LISP expression is

canceled.

ObjectAdded

Triggered when an object has been added to the

drawing.

ObjectErased

Triggered when an object has been erased from the

drawing.

ObjectModified

Triggered when an object in the drawing has been

modified.

SelectionChanged
Triggered when the current pickfirst selection set
changes.
WindowChanged
Triggered when there is a change to the
Document window.
WindowMovedOrResized
Triggered just after the Drawing window has been
moved or resized.

Enable Document Level Events in

Environments
Other Than VBA
Before you can use document level events in VB or another environment
besides VBA, you must create a new class module and declare an object of
type AcadDocument with events. For example, assume a new class module
is created and called EventClassModule. The new class module contains the
declaration of the application with the VBA keyword WithEvents.
To create a new class and declare a Document object with events
1 In the VBA IDE, insert a class module. From the Insert menu, choose Class
Module.
2 Select the new class module in the Project window.
3 Change the name of the class in the Properties window to EventClassModule.
4 Open the Code window for the class using F7 , or by selecting the menu
option View Code.
5 In the Code window for the class, add the following line:
Public WithEvents Doc As AcadDocument

After the new object has been declared with events, it appears in the Object
drop-down list box in the class module, and you can write event procedures
for the new object in the class module. (When you select the new object in
the Object box, the valid events for that object are listed in the Procedure
drop-down list box.)
Before the procedures will run, however, you must connect the declared
object in the class module with the Document object. You can do this with
the following code from any module.
To connect the declared object to the Document object
1 In the Code window for your main module, add the following line to the
declarations section:
Dim X As New EventClassModule

2 In the same window, add the following subroutine:

Sub InitializeEvents()
Set X.Doc = ThisDrawing
End Sub

3 In the code for your main module, add a call to the InitializeApp
subroutine:
Call InitializeEvents

Once the InitializeEvents procedure has been run, the Doc object in the
class module points to the Document object created, and any event
procedures in the class module will run when the events occur.

Code Document Level Events in

Environments
Other Than VBA
Once the document level events have been enabled, you will find the Doc
class variable available from the Object drop-down list of the Class Module
Code window. Select the Doc class and the list of available events will
appear in the Procedure drop-down list. Simply select the event you want to
write a handler for and the handler skeleton is created automatically.

Code Document Level Events in VBA

As mentioned in Handling Document Events, document level events are
automatically enabled when a VBA project is loaded. To write event
handlers for document level events in VBA, you simply select
AcadDocument from the Object drop-down list in the Code window. The
available events for the document will appear in the Procedure drop-down
list. Simply select the event you want to write a handler for and the handler
skeleton is created automatically.
Note that event handlers created in this fashion apply to the current active
drawing. To create event handlers for a specific drawing, first follow the steps
listed in Enable Document Level Events in Environments Other Than
VBA on page 236. This will allow you to enable a specific document for
events.
Update the shortcut menu at the BeginShortcutMenuDefault and
EndShortcutMenu events
This example uses the event handler for the BeginShortcutMenuDefault
event to add the OpenDWG menu item to the beginning of the shortcut
menu. Then the event handler for the EndShortcutMenu event removes the
additional menu item so that it is not saved permanently in the users
menu configuration.

Private Sub AcadDocument_BeginShortcutMenuDefault _

(ShortcutMenu As AutoCAD.IAcadPopupMenu)
On Error Resume Next
' Add a menu item to the cursor menu
Dim newMenuItem As AcadPopupMenuItem
Dim openMacro As String
openMacro = Chr(vbKeyEscape) + Chr(vbKeyEscape) + "_open "
Set newMenuItem = ShortcutMenu.AddMenuItem _
(0, Chr(Asc("&")) _
+ "OpenDWG", openMacro)
End Sub
Private Sub AcadDocument_EndShortcutMenu _
(ShortcutMenu As AutoCAD.IAcadPopupMenu)
On Error Resume Next
ShortcutMenu.Item("OpenDWG").Delete
End Sub

Handle Object Level Events

The object level events is not persistent in AutoCAD VBA. That is, it is not
automatically enabled when a VBA project is loaded. An object level
event must be enabled for VBA and all other ActiveX Automation
controllers.
Once the object level events is enabled, the Modified event is available
to you. This event is triggered when an object in the drawing has been
modified.

Enable the Object Level

Event
Before you can use object level events you must create a new class module
and declare an object of type AcadObject with events. For example,
assume that a new class module is created and called EventClassModule.
The new class module contains the declaration of the application with the
VBA key- word WithEvents.
To create a new class and declare a Circle object with
events
1 In the VBA IDE, insert a class module. From the Insert menu, choose
Class
Module.
2 Select the new class module in the Project window.
3 Change the name of the class in the Properties window to EventClassModule.

4 Open the Code window for the class using F7 , or by selecting the menu
option View Code.
5 In the Code window for the class, add the following line:
Public WithEvents Object As AcadCircle

After the new object has been declared with events, it appears in the Object
drop-down list box in the class module, and you can write event procedures
for the new object in the class module. (When you select the new object in
the Object box, the valid events for that object are listed in the Procedure
drop-down list box.)
Before the procedures will run, however, you must connect the declared
object in the class module with the Circle object. You can do this with the
following code from any module.
To connect the declared object to the Automation object
1 In the Code window for your main module, add the following line to the
declarations section:
Dim X As New EventClassModule

2 In the same window, create a circle called MyCircle and initialize it as

containing events:
Sub InitializeEvents()
Dim MyCircle As AcadCircle
Dim centerPoint(0 To 2) As Double
Dim radius As Double
centerPoint(0) = 0#: centerPoint(1) = 0#: centerPoint(2) = 0#
radius = 5#
Set MyCircle = ThisDrawing.ModelSpace.AddCircle(centerPoint,
radius)
Set X.Object = MyCircle
End Sub

3 In the code for your main module, add a call to the InitializeApp
subroutine:
Call InitializeEvents

Once the InitializeEvents procedure has been run, the Circle object in the
class module points to the Circle object created, and any event procedures in
the class module will run when the events occur.

Note When coding in VBA, you must provide an event handler for all objects
enabled for the Modified event. If you do not provide a handler, VBA may terminate unexpectedly.

Handle Object Level Events

| 239

Display the area of a closed polyline whenever the polyline is updated

This example creates a lightweight polyline with events. The event handler
for the polyline then displays the new area whenever the polyline is
changed. To trigger the event, simply change the size of the polyline in
AutoCAD. Remember you must run the CreatePLineWithEvents subroutine
before the event handler is activated.
Public WithEvents PLine As AcadLWPolyline
Sub CreatePLineWithEvents()
' This example creates a light weight polyline
Dim points(0 To 9) As Double
points(0) = 1: points(1) = 1
points(2) = 1: points(3) = 2
points(4) = 2: points(5) = 2
points(6) = 3: points(7) = 3
points(8) = 3: points(9) = 2
Set PLine = ThisDrawing.ModelSpace. _
AddLightWeightPolyline(points)
PLine.Closed = True
ThisDrawing.Application.ZoomAll
End Sub
Private Sub PLine_Modified _
(ByVal pObject As AutoCAD.IAcadObject)
' This event is triggered when the polyline is resized.
' If the polyline is deleted the modified event is still
' triggered, so we use the error handler to avoid
' reading data from a deleted object.
On Error GoTo ERRORHANDLER
MsgBox "The area of " & pObject.ObjectName & " is: " _
& pObject.Area
Exit Sub
ERRORHANDLER:
MsgBox Err.Description
End Sub

240 | Chapter 7 Use

Events

Work in Three
Dimensional Space

Most drawings consist of two-dimensional (2D) views of

In this chapter

objects that are three-dimensional (3D). Though this

Specify 3D Coordinates

method of drafting is widely used in the architectural

and engineering communities, it is limited: the drawings are 2D representations of 3D objects and must be
visually interpreted. Moreover, because the views are
created independently, there are more possibilities for

Define a User

Coordinate
Syste
m
Convert Coordinates
Create 3D Objects
Edit in 3D
Edit 3D Solids

error and ambiguity. As a result, you may want to create

true 3D models instead of 2D representations. You can
use the AutoCAD drawing tools to create detailed, realistic 3D objects and manipulate them in various ways.

241

Specify 3D Coordinates
Entering 3D WCS coordinates is similar to entering 2D WCS coordinates. In
addition to specifying X and Y values, you specify a Z value. As with the 2D
coordinates, a variant is used to pass the coordinates to ActiveX methods
and properties, and to query the coordinates.
For more information about specifying 3D coordinates, see Enter 3D Coordinates in chapter 15, Use Precision Tools, in the Users Guide.
Define and query the coordinates for 2D and 3D polylines
This example creates two polylines, each with three coordinates. The first
polyline is a 2D polyline, the second polyline is 3D. Notice the length of the
array containing the vertices is expanded to include the Z coordinates in the
creation of the 3D polyline. The example concludes by querying the coordinates of the polylines and displaying the coordinates in a message box.

242 | Chapter 8 Work in Three Dimensional

Space

Sub Ch8_Polyline_2D_3D()
Dim pline2DObj As AcadLWPolyline
Dim pline3DObj As AcadPolyline
Dim points2D(0 To 5) As Double
Dim points3D(0 To 8) As Double
' Define three 2D polyline points
points2D(0) = 1: points2D(1) = 1
points2D(2) = 1: points2D(3) = 2
points2D(4) = 2: points2D(5) = 2
' Define three 3D polyline points
points3D(0) = 1: points3D(1) = 1: points3D(2) = 0
points3D(3) = 2: points3D(4) = 1: points3D(5) = 0
points3D(6) = 2: points3D(7) = 2: points3D(8) = 0
' Create the 2D light weight Polyline
Set pline2DObj = ThisDrawing.ModelSpace. _
AddLightWeightPolyline(points2D)
pline2DObj.Color = acRed
pline2DObj.Update
' Create the 3D polyline
Set pline3DObj = ThisDrawing.ModelSpace. _
AddPolyline(points3D)
pline3DObj.Color = acBlue
pline3DObj.Update
' Query the coordinates of the polylines
Dim get2Dpts As Variant
Dim get3Dpts As Variant
get2Dpts = pline2DObj.Coordinates
get3Dpts = pline3DObj.Coordinates
' Display the coordinates
MsgBox ("2D polyline (red): " & vbCrLf & _
get2Dpts(0) & ", " & get2Dpts(1) & vbCrLf & _
get2Dpts(2) & ", " & get2Dpts(3) & vbCrLf & _
get2Dpts(4) & ", " & get2Dpts(5))
MsgBox ("3D polyline (blue):
get3Dpts(0) & ", " &
get3Dpts(2) & vbCrLf
get3Dpts(3) & ", " &
get3Dpts(5) & vbCrLf
get3Dpts(6) & ", " &
get3Dpts(8))
End Sub

" & vbCrLf & _

get3Dpts(1) & ", " & _
& _
get3Dpts(4) & ", " & _
& _
get3Dpts(7) & ", " & _

Specify 3D Coordinates
243

Define a User Coordinate System

You define a user coordinate system (UCS) object to change the location of
the (0, 0, 0) origin point and the orientation of the XY plane and Z axis.
You can locate and orient a UCS anywhere in 3D space, and you can define,
save, and recall as many user coordinate systems as you require. Coordinate
input and display are relative to the current UCS.
To indicate the origin and orientation of the UCS, you can display the UCS
icon at the UCS origin point using the UCSIconAtOrigin property. If the
UCS icon is turned on (see the UCSIconOn property) and is not displayed at
the origin, it is displayed at the WCS coordinate defined by the UCSORG
system variable.
You can create a new user coordinate system using the Add method. This
method requires four values as input: the coordinate of the origin, a coordinate on the X and Y axes, and the name of the UCS.
All coordinates in the AutoCAD ActiveX Automation are entered in the
world coordinate system (WCS). Use the GetUCSMatrix method to return the
transformation matrix of a given UCS. Use this transformation matrix to
find the equivalent WCS coordinates.
To make a UCS active, use the ActiveUCS property on the Document object.
If changes are made to the active UCS, the new UCS object must be reset as
the active UCS for the changes to appear. To reset the active UCS, simply call
the ActiveUCS property again with the updated UCS object.
For more information about defining a UCS, see Control the User Coordinate System in 3D in chapter 15, Use Precision Tools in the Users
Guide.
Create a new UCS, make it active, and translate the coordinates of a point
into the UCS coordinates
The following subroutine creates a new UCS and sets it as the active UCS for
the drawing. It then asks the user to pick a point in the drawing, and
returns both WCS and UCS coordinates for the point.

244 | Chapter 8 Work in Three Dimensional

Space

Sub Ch8_NewUCS()
' Define the variables we will need
Dim ucsObj As AcadUCS
Dim origin(0 To 2) As Double
Dim xAxisPnt(0 To 2) As Double
Dim yAxisPnt(0 To 2) As Double
' Define the UCS points
origin(0) = 4: origin(1) = 5: origin(2) = 3
xAxisPnt(0) = 5: xAxisPnt(1) = 5: xAxisPnt(2) = 3
yAxisPnt(0) = 4: yAxisPnt(1) = 6: yAxisPnt(2) = 3
' Add the UCS to the
' UserCoordinatesSystems collection
Set ucsObj = ThisDrawing.UserCoordinateSystems. _
Add(origin, xAxisPnt, yAxisPnt, "New_UCS")
' Display the UCS icon
ThisDrawing.ActiveViewport.UCSIconAtOrigin = True
ThisDrawing.ActiveViewport.UCSIconOn = True
' Make the new UCS the active UCS
ThisDrawing.ActiveUCS = ucsObj
MsgBox "The current UCS is : " & ThisDrawing.ActiveUCS.Name _
& vbCrLf & " Pick a point in the drawing."
' Find the WCS and UCS coordinate of a point
Dim WCSPnt As Variant
Dim UCSPnt As Variant
WCSPnt = ThisDrawing.Utility.GetPoint(, "Enter a point: ")
UCSPnt = ThisDrawing.Utility.TranslateCoordinates _
(WCSPnt, acWorld, acUCS, False)
MsgBox "The WCS coordinates are: " & WCSPnt(0) & ", " _
& WCSPnt(1) & ", " & WCSPnt(2) & vbCrLf & _
"The UCS coordinates are: " & UCSPnt(0) & ", " _
& UCSPnt(1) & ", " & UCSPnt(2)
End Sub

Convert Coordinates
The TranslateCoordinates method translates a point or a displacement from
one coordinate system to another. A point argument, called OriginalPoint,
can be interpreted as either a 3D point or a 3D displacement vector. This
argument is distinguished by the Boolean argument, Disp. If the Disp argument is set to TRUE the OriginalPoint argument is treated as a
displacement vector; otherwise, it is treated as a point. Two more
arguments determine which coordinate system the OriginalPoint is from,
and to which coordi- nate system the OriginalPoint is to be converted.
The following AutoCAD coordinate systems can be specified in the From
and To arguments:

Convert Coordinates
245

WCS

World Coordinate Systemthe reference coordinate

system. All other coordinate systems are defined
relative to the WCS, which never changes. Values
measured relative to the WCS are stable across changes
to other coordinate systems. All points passed in and
out of ActiveX methods and properties are expressed in
the WCS unless otherwise specified.

UCS

User Coordinate Systemthe working coordinate

system. The user specifies a UCS to make drawing tasks
easier. All points passed to AutoCAD commands,
including those returned from AutoLISP routines and
external functions, are points in the current UCS
(unless the user precedes them with an * at the
Command prompt). If you want your application to
send coordinates in the WCS, OCS, or DCS to AutoCAD
commands, you must first convert them to the UCS by
calling the TranslateCoordinates method.

OCS

Object Coordinate Systempoint values specified by

certain methods and properties for the Polyline and
LightweightPolyline objects are expressed in this
coordinate system, relative to the object. These points
are usually converted into the WCS, current UCS, or
current DCS, according to the intended use of the
object. Conversely, points in WCS, UCS, or DCS must
be translated into an OCS before they are written to the
database by means of the same properties. See the
AutoCAD ActiveX and VBA Reference for the methods
and properties that use this coordinate system.
When converting coordinates to or from the OCS you
must enter the normal for the OCS in the final
argument of the TranslateCoordinates function.

246 | Chapter 8 Work in Three Dimensional

Space

DCS

Display Coordinate Systemthe coordinate system

where objects are transformed before they are
displayed. The origin of the DCS is the point stored in
the AutoCAD system variable TARGET, and its Z axis is
the viewing direction. In other words, a viewport is
always a plan view of its DCS. These coordinates can be
used to determine where something will be displayed to
the AutoCAD user.

PSDCS

Paper Space DCSthis 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 offset if the Disp argument is FALSE.
The Z coordinate is scaled but never translated.
Therefore, it can be used to find the scale factor
between the two coordinate systems. The PSDCS can be
transformed only into the current model space
viewport. If the from argument equals PSDCS, then the
to argument must equal DCS, and vice versa.

Translate OCS coordinates to WCS coordinates

This example creates a polyline in model space. The first vertex for the
polyline is then displayed in both the OCS and WCS coordinates. The conversion from OCS to WCS requires the normal for the OCS be placed in the
last argument of the TranslateCoordinates method.

Convert Coordinates
247

Sub Ch8_TranslateCoordinates()
' Create a polyline in model space.
Dim plineObj As AcadPolyline
Dim points(0 To 14) As Double
' Define the 2D polyline points
points(0) = 1: points(1) = 1: points(2) = 0
points(3) = 1: points(4) = 2: points(5) = 0
points(6) = 2: points(7) = 2: points(8) = 0
points(9) = 3: points(10) = 2: points(11) = 0
points(12) = 4: points(13) = 4: points(14) = 0
' Create a light weight Polyline object in model space
Set plineObj = ThisDrawing.ModelSpace.AddPolyline(points)
' Find the X and Y coordinates of the
' first vertex of the polyline
Dim firstVertex As Variant
firstVertex = plineObj.Coordinate(0)
' Find the Z coordinate for the polyline
' using the elevation property
firstVertex(2) = plineObj.Elevation
' Change the normal for the pline so that the
' difference between the coordinate systems
' is obvious.
Dim plineNormal(0 To 2) As Double
plineNormal(0) = 0#
plineNormal(1) = 1#
plineNormal(2) = 2#
plineObj.Normal = plineNormal
' Translate the OCS coordinate into WCS
Dim coordinateWCS As Variant
coordinateWCS = ThisDrawing.Utility.TranslateCoordinates _
(firstVertex, acOCS, acWorld, False, plineNormal)
' Display the coordinates of the point
MsgBox "The first vertex has the following coordinates:" _
& vbCrLf & "OCS: " & firstVertex(0) & ", " & _
firstVertex(1) & ", " & firstVertex(2) & vbCrLf & _
"WCS: " & coordinateWCS(0) & ", " & _
coordinateWCS(1) & ", " & coordinateWCS(2)
End Sub

Create 3D
Objects
AutoCAD supports three types of 3D modeling: wireframe, surface, and
solid. Each type has its own creation and editing techniques.

248 | Chapter 8 Work in Three Dimensional

Space

For more information about creating 3D objects, see Create 3D Objects in

chapter 16, Draw Geometric Objects, in the Users Guide.

Create Wireframes
With AutoCAD you can create wireframe models by positioning any 2D planar object anywhere in 3D space. You can position 2D objects in 3D space
using several methods:

Create the object by entering 3D points. You enter a coordinate

that defines the X, Y, and Z location of the point.
Set the default construction plane (XY plane) on which you will draw the
object by defining a UCS.
Move the object to its proper orientation in 3D space after you create it.

Also, you can create some wireframe objects, such as polylines, that can exist
in all three dimensions. Use the Add3DPoly method to create 3D polylines.
For more information on creating wireframes, see Create Wireframe Models in the Users Guide.

Create Meshes
A rectangular mesh (PolygonMesh object) represents an objects surface using
planar facets. The mesh density, or number of facets, is defined in terms of a
matrix of M and N vertices, similar to a grid consisting of columns and rows.
M and N specify the column and row position, respectively, of any given vertex. You can create meshes in both 2D and 3D, but they are used primarily
for 3D.
Use the Add3DMesh method for creating rectangular meshes. This method
takes three values as input: the number of vertices in the M direction, the
numer of vertices in the N direction, and a variant array containing coordinates for all the vertices in the mesh.
Once the PolygonMesh is created, use the MClose and NClose properties to
close the mesh.
For more information on creating meshes, see Create Surfaces in the Users
Guide.
Create a polygon mesh
This example creates a 4 4 polygon mesh. The direction of the active viewport is then adjusted so that the three-dimensional nature of the mesh is
more easily viewed.

Create 3D Objects
249

Sub Ch8_Create3DMesh()
Dim meshObj As AcadPolygonMesh
Dim mSize, nSize, Count As Integer
Dim points(0 To 47) As Double
' create the matrix of points
points(0) = 0: points(1) = 0: points(2) = 0
points(3) = 2: points(4) = 0: points(5) = 1
points(6) = 4: points(7) = 0: points(8) = 0
points(9) = 6: points(10) = 0: points(11) = 1
points(12) = 0: points(13) = 2: points(14) = 0
points(15) = 2: points(16) = 2: points(17) = 1
points(18) = 4: points(19) = 2: points(20) = 0
points(21) = 6: points(22) = 2: points(23) = 1
points(24) = 0: points(25) = 4: points(26) = 0
points(27) = 2: points(28) = 4: points(29) = 1
points(30) = 4: points(31) = 4: points(32) = 0
points(33) = 6: points(34) = 4: points(35) = 0
points(36) = 0: points(37) = 6: points(38) = 0
points(39) = 2: points(40) = 6: points(41) = 1
points(42) = 4: points(43) = 6: points(44) = 0
points(45) = 6: points(46) = 6: points(47) = 0
mSize = 4: nSize = 4
' creates a 3Dmesh in model space
Set meshObj = ThisDrawing.ModelSpace. _
Add3DMesh(mSize, nSize, points)
' Change the viewing direction of the viewport
' to better see the cylinder
Dim NewDirection(0 To 2) As Double
NewDirection(0) = -1
NewDirection(1) = -1
NewDirection(2) = 1
ThisDrawing.ActiveViewport.direction = NewDirection
ThisDrawing.ActiveViewport = ThisDrawing.ActiveViewport
ZoomAll
End Sub

Create a Polyface
Mesh
Use the AddPolyfaceMesh method to create a polyface mesh, with each face
capable of having numerous vertices.
Creating a polyface mesh is similar to creating a rectangular mesh. To create
a polyface mesh, specify coordinates for all its vertices then define each face
by entering vertex numbers for all the vertices of that face. As you create the
polyface mesh, you can set specific edges to be invisible, assign them to layers, or give them colors.

250 | Chapter 8 Work in Three Dimensional

Space

To make an edge invisible, enter the vertex number for the edge as a
negative value. For more information on creating polyface meshes, see the
AddPoly- faceMesh method of the ActiveX and VBA Reference.
For more information on creating polyface meshes, see Create a Polyface
Mesh in the Users Guide.
Create a polyface mesh
This example creates a Polyface Mesh object in model space. The viewing
direction of the active viewport is updated to display the three-dimensional
nature of the mesh more easily.
Sub Ch8_CreatePolyfaceMesh()
'Define the mesh vertices
Dim vertex(0 To 17) As Double
vertex(0) = 4: vertex(1) = 7: vertex(2) = 0
vertex(3) = 5: vertex(4) = 7: vertex(5) = 0
vertex(6) = 6: vertex(7) = 7: vertex(8) = 0
vertex(9) = 4: vertex(10) = 6: vertex(11) = 0
vertex(12) = 5: vertex(13) = 6: vertex(14) = 0
vertex(15) = 6: vertex(16) = 6: vertex(17) = 1
' Define the face list
Dim FaceList(0 To 7) As Integer
FaceList(0) = 1
FaceList(1) = 2
FaceList(2) = 5
FaceList(3) = 4
FaceList(4) = 2
FaceList(5) = 3
FaceList(6) = 6
FaceList(7) = 5
' Create the polyface mesh
Dim polyfaceMeshObj As AcadPolyfaceMesh
Set polyfaceMeshObj = ThisDrawing.ModelSpace.AddPolyfaceMesh _
(vertex, FaceList)
' Change the viewing direction of the viewport to
' better see the polyface mesh
Dim NewDirection(0 To 2) As Double
NewDirection(0) = -1
NewDirection(1) = -1
NewDirection(2) = 1
ThisDrawing.ActiveViewport.direction = NewDirection
ThisDrawing.ActiveViewport = ThisDrawing.ActiveViewport
ZoomAll
End Sub

Create 3D Objects
251

Create Solids
A solid object (3DSolid object) represents the entire volume of an object.
Solids are the most informationally complete and least ambiguous of the 3D
modeling types. Complex solid shapes are also easier to construct and edit
than wireframes and meshes.
You create solids from one of the basic solid shapes of box, cone, cylinder,
sphere, torus, and wedge or by extruding a 2D object along a path or revolving a 2D object about an axis. Use one of the following methods to create
solids:
AddBox, AddCone, AddCylinder, AddEllipticalCone, AddEllipticalCylinder,
AddExtrudedSolid, AddExtrudedSolidAlongPath, AddRevolvedSolid,
AddSolid, AddSphere, AddTorus, or AddWedge.
Like meshes, solids are displayed as wireframes until you hide, shade, or render them. Additionally, you can analyze solids for their mass properties (volume, moments of inertia, center of gravity, and so forth). Use the following
properties to analyze solids: MomentOfInertia, PrincipalDirections, PrincipalMoments, ProductOfInertia, RadiiOfGyration, and Volume.
The ContourlinesPerSurface property controls the number of tessellation
lines used to visualize curved portions of the wireframe. The RenderSmoothness property adjusts the smoothness of shaded and hidden-line objects.
For more information on creating solids, see Create 3D Solids in the Users
Guide.
Create a wedge solid
The following example creates a wedge-shaped solid in model space. The
viewing direction of the active viewport is updated to display the threedimensional nature of the wedge more easily.

252 | Chapter 8 Work in Three Dimensional

Space

Sub Ch8_CreateWedge()
Dim wedgeObj As Acad3DSolid
Dim center(0 To 2) As Double
Dim length As Double
Dim width As Double
Dim height As Double
' Define the wedge
center(0) = 5#: center(1) = 5#: center(2) = 0
length = 10#: width = 15#: height = 20#
' Create the wedge in model space
Set wedgeObj = ThisDrawing.ModelSpace. _
AddWedge(center, length, width, height)
' Change the viewing direction of the viewport
Dim NewDirection(0 To 2) As Double
NewDirection(0) = -1
NewDirection(1) = -1
NewDirection(2) = 1
ThisDrawing.ActiveViewport.direction = NewDirection
ThisDrawing.ActiveViewport = ThisDrawing.ActiveViewport
ZoomAll
End Sub

Edit in 3D
This section describes how to edit 3D objects by, for example, rotating, arraying, and mirroring.

Rotate
3D

in

With the Rotate method, you can rotate objects in 2D about a specified
point. The direction of rotation is determined by the WCS. The Rotate3D
method rotates objects in 3D about a specified axis. The Rotate3D method
takes three values as input: the WCS coordinates of the two points defining
the rotation axis and the rotation angle in radians.

Edit in 3D
253

axis point 2

axis point 1

object to rotate

axis of rotation

result

To rotate 3D objects, use either the Rotate or Rotate3D method.

For more information on rotating in 3D, see Rotate Objects in the Users
Guide.
Create a 3D box and rotate it about an axis
This example creates a 3D box. It then defines the axis for rotation and
finally rotates the box 30 degrees about the axis.
Sub Ch8_Rotate_3DBox()
Dim boxObj As Acad3DSolid
Dim length As Double
Dim width As Double
Dim height As Double
Dim center(0 To 2) As Double
' Define the box
center(0) = 5: center(1) = 5: center(2) = 0
length = 5
width = 7
height = 10
' Create the box object in model space
Set boxObj = ThisDrawing.ModelSpace. _
AddBox(center, length, width, height)
' Define the rotation axis with two points
Dim rotatePt1(0 To 2) As Double
Dim rotatePt2(0 To 2) As Double
Dim rotateAngle As Double
rotatePt1(0) = -3: rotatePt1(1) = 4: rotatePt1(2) = 0
rotatePt2(0) = -3: rotatePt2(1) = -4: rotatePt2(2) = 0
rotateAngle = 30
rotateAngle = rotateAngle * 3.141592 / 180#
' Rotate the box
boxObj.Rotate3D rotatePt1, rotatePt2, rotateAngle
ZoomAll
End Sub

254 | Chapter 8 Work in Three Dimensional

Space

Array in 3D
With the ArrayRectangular method, you can create a rectangular array in
3D. In addition to specifying the number of columns (X direction) and
rows
(Y direction), you also specify the number of levels (Z direction).
For more information on using arrays of objects in 3D, see Create an Array
of Objects in the Users Guide.
Create a 3D rectangular array
This example creates a circle and then uses that circle to create a rectangular
array of 4 rows, 4 columns, and 3 levels of circles.
Sub Ch8_CreateRectangularArray()
' Create the circle
Dim circleObj As AcadCircle
Dim center(0 To 2) As Double
Dim radius As Double
center(0) = 2: center(1) = 2: center(2) = 0
radius = 0.5
Set circleObj = ThisDrawing.ModelSpace. _
AddCircle(center, radius)
' Define the rectangular array
Dim numberOfRows As Long
Dim numberOfColumns As Long
Dim numberOfLevels As Long
Dim distanceBwtnRows As Double
Dim distanceBwtnColumns As Double
Dim distanceBwtnLevels As Double
numberOfRows = 4
numberOfColumns = 4
numberOfLevels = 3
distanceBwtnRows = 1
distanceBwtnColumns = 1
distanceBwtnLevels = 4
' Create the array of objects
Dim retObj As Variant
retObj = circleObj.ArrayRectangular _
(numberOfRows, numberOfColumns, _
numberOfLevels, distanceBwtnRows, _
distanceBwtnColumns, distanceBwtnLevels)
ZoomAll
End Sub

Mirror in 3D
With the Mirror3D method, you can mirror objects along a specified mirroring plane specified by three points.

Edit in 3D
255

1
2
object to mirror

defining a mirror plane

result

For more information on mirroring objects in 3D, see Mirror Objects in the
Users Guide.
Mirror in 3D
This example creates a box in model space. It then mirrors the box about a
plane and colors the mirrored box red.
Sub Ch8_MirrorABox3D()
' Create the box object
Dim boxObj As Acad3DSolid
Dim length As Double
Dim width As Double
Dim height As Double
Dim center(0 To 2) As Double
center(0) = 5#: center(1) = 5#: center(2) = 0
length = 5#: width = 7: height = 10#
' Create the box (3DSolid) object in model space
Set boxObj = ThisDrawing.ModelSpace. _
AddBox(center, length, width, height)
' Define the mirroring plane with three points
Dim mirrorPt1(0 To 2) As Double
Dim mirrorPt2(0 To 2) As Double
Dim mirrorPt3(0 To 2) As Double
mirrorPt1(0) = 1.25: mirrorPt1(1) = 0: mirrorPt1(2) = 0
mirrorPt2(0) = 1.25: mirrorPt2(1) = 2: mirrorPt2(2) = 0
mirrorPt3(0) = 1.25: mirrorPt3(1) = 2: mirrorPt3(2) = 2
' Mirror the box
Dim mirrorBoxObj As Acad3DSolid
Set mirrorBoxObj = boxObj.Mirror3D _
(mirrorPt1, mirrorPt2, mirrorPt3)
mirrorBoxObj.Color = acRed
ZoomAll
End Sub

256 | Chapter 8 Work in Three Dimensional

Space

Edit 3D Solids
Once you have created a solid, you can create more complex shapes by
combining solids. You can join solids, subtract solids from each other, or
find the common volume (overlapping portion) of solids. Use the Boolean
or CheckInterference methods to perform these combinations.

solids before Boolean intersection

resulting solid from Boolean intersection

Solids are further modified by obtaining the 2D cross section of a solid or

slic- ing a solid into two pieces. Use the SectionSolid method to find cross
sections of solids, and the SliceSolid method for slicing a solid into two
pieces.
Find the interference between two solids
This example creates a box and a cylinder in model space. It then finds the
interference between the two solids and creates a new solid from that interference. For ease of viewing, the box is colored white, the cylinder is
colored cyan, and the interference solid is colored red.

Edit 3D Solids

Sub Ch8_FindInterferenceBetweenSolids()
' Define the box
Dim boxObj As Acad3DSolid
Dim length As Double
Dim width As Double
Dim height As Double
Dim center(0 To 2) As Double
center(0) = 5: center(1) = 5: center(2) = 0
length = 5
width = 7
height = 10
' Create the box object in model space
' and color it white
Set boxObj = ThisDrawing.ModelSpace. _
AddBox(center, length, width, height)
boxObj.Color = acWhite
' Define the cylinder
Dim cylinderObj As Acad3DSolid
Dim cylinderRadius As Double
Dim cylinderHeight As Double
center(0) = 0: center(1) = 0: center(2) = 0
cylinderRadius = 5
cylinderHeight = 20
' Create the Cylinder and
' color it cyan
Set cylinderObj = ThisDrawing.ModelSpace.AddCylinder _
(center, cylinderRadius, cylinderHeight)
cylinderObj.Color = acCyan
' Find the interference between the two solids
' and create a new solid from it. Color the
' new solid red.
Dim solidObj As Acad3DSolid
Set solidObj = boxObj.CheckInterference(cylinderObj, True)
solidObj.Color = acRed
ZoomAll
End Sub

2 | Chapter 8
Space

Work in Three Dimensional

Slice a solid into two solids

This example creates a box in model space. It then slices the box based on a
plane defined by three points. The slice is returned as a 3DSolid.
Sub Ch8_SliceABox()
' Create the box object
Dim boxObj As Acad3DSolid
Dim length As Double
Dim width As Double
Dim height As Double
Dim center(0 To 2) As Double
center(0) = 5#: center(1) = 5#: center(2) = 0
length = 5#: width = 7: height = 10#
' Create the box (3DSolid) object in model space
Set boxObj = ThisDrawing.ModelSpace. _
AddBox(center, length, width, height)
boxObj.Color = acWhite
' Define the section
Dim slicePt1(0 To 2)
Dim slicePt2(0 To 2)
Dim slicePt3(0 To 2)

plane with three points

As Double
As Double
As Double

slicePt1(0) = 1.5: slicePt1(1) = 7.5: slicePt1(2) = 0

slicePt2(0) = 1.5: slicePt2(1) = 7.5: slicePt2(2) = 10
slicePt3(0) = 8.5: slicePt3(1) = 2.5: slicePt3(2) = 10
' slice the box and color the new solid red
Dim sliceObj As Acad3DSolid
Set sliceObj = boxObj.SliceSolid _
(slicePt1, slicePt2, slicePt3, True)
sliceObj.Color = acRed
ZoomAll
End Sub

Edit 3D Solids

260

Define Layouts and Plot

After youve created your drawing with AutoCAD,

In this chapter

you usually plot it on paper. A plotted drawing can

Model Space and Paper

contain a single view of your drawing or a more

Layouts

complex arrangement of views. In paper space, you can

Viewports

create windows called floating viewports, which

Space

Plot Your Drawing

display vari- ous views of the drawing. Depending on

your needs, you can plot one or more viewports, or set
options that determine what is plotted and how the
image fits on the
paper.

261

Model Space and Paper Space

Model space is the drawing environment in which you create the geometry
for your model. Normally, as you begin to draw in model space, you designate your drawing limits to determine the extents of the drawing environment, and you draw in real world units.
Paper space represents the paper representation of your model as it will be
plotted. In paper space you can lay out different views of your drawing, scale
views independently from one another, and arrange the different views of
your drawing as you want them to be plotted. There can be many different
paper space representations of your drawing.
For more information about model space and paper space, see Work in
Paper Space and Model Space in the Users Guide.

Layouts
All the geometry of your drawing is contained in layouts. Model space geometry is contained on a single layout named Model. You cannot rename the
model space layout, nor can you create another model space layout. There
can be only one model space layout per drawing.
Paper space geometry is also contained on layouts. You can have many different paper space layouts in your drawing, each representing a different configuration to print. You can change the name of the paper space layouts.
In ActiveX Automation the ModelSpace object contains all the geometry in
the model space layout. Because there can be more than one paper space layout in a drawing, the PaperSpace object points to the last active paper space
layout.
For more information about working with paper space layouts, see Create
Layouts in the Users Guide.

Layouts and Blocks

The content of any layout is distributed among two different ActiveX
objects: the Layout object and the Block object. The Layout object contains
the plot settings and the visual properties of the layout as it appears in the
AutoCAD user interface. The Block object contains the geometry for the
layout.

6 | Chapter 9
Plot

Define Layouts and

Each Layout object is associated with one, and only one, Block object. To
access the Block object associated with a given layout, use the Block
property. Conversely, each Block object is associated with one, and only one,
Layout object. To access the Layout object associated with a given Block,
use the Layout property for that block.

Plot Configurations
A PlotConfiguration object is similar to a Layout object, as both contain
identical plot information. The difference is that a Layout object is
associated with a Block object containing the geometry to plot. A
PlotConfiguration object is not associated with a particular Block object. It
is simply a named collection of plot settings available for use with any
geometry.

Layout Settings
Layout settings control the final plotted output. These settings affect the
paper size, plot scale, plot area, plot origin, and the plot device name.
Under- standing how to use layout settings ensures the layout plots as
expected. All the settings for a layout can be changed from the Layout
object properties and methods.

Paper Size and Units

The choice of paper size depends on the plotter configured for your system.
Each different plotter will have a standard list of available paper sizes. You
can change the paper size for a layout by using the CanonicalMediaName
property.
You can also specify the units for your layout using the PaperUnits
property. This property takes one of three values: acInches,
acMillimeters, or acPixels. If your plotter is configured for raster output,
you must specify the output size in pixels.

Adjust the Plot Origin

The plot origin is the lower-left corner of the specified plotted area and is
controlled with the PlotOrigin property. Typically, the plot origin is set to
(0, 0). However, you can center the plot on the sheet of paper by setting the
CenterPlot property to TRUE. Centering the plot alters the plot origin.

Set the Plot Area

When you prepare to plot a layout, you can specify the plot area to
determine what will be included in the plot. To specify the plot area, use
the PlotType property. This property requires one of the following values as
input:

Layouts

acDisplay

Prints everything that is in the current model space

display. This option is unavailable when plotting from
a paper space layout.

acExtents

Prints everything that falls within the boundaries of the

currently selected space.

acLimits

Prints everything that is in the limits of the current

space.

acView

Prints the view named by the ViewToPlot property.

acWindow

Prints everything in the window specified by the

SetWindowToPlot method.

acLayout

Prints everything that falls within the margins of the

specified paper size. This option is not available when
printing from model space.

When you create a new paper space layout, the default option is acLayout.

Set the Plot Scale

Generally, you draw objects at their actual size. When you plot the
drawing, you can either specify a precise scale or fit the image to the paper.
To specify a scale, enter either a standard or custom plot scale.
To enter a standard scale, first set the UseStandardScale property to TRUE.
You can then enter the desired scale using the StandardScale property.
To enter a custom scale, first set the UseStandardScale property to FALSE.
You can then enter the custom scale using the SetCustomScale method.
When you are reviewing an early draft view, a precise scale is not always
important. You can use the acScaleToFit value of the StandardScale
prop- erty to plot the layout at the largest possible size that fits the paper.

Set the Lineweight Scale

Lineweights can be scaled proportionately in a layout with the plot scale.
Typically, lineweights specify the linewidth of plotted objects and are
plotted with the linewidth size regardless of the plot scale. Most often, you
use the default plot scale of 1:1 when plotting a layout. However, if you
want to plot an E-size layout that is scaled to fit on an A-size sheet of paper,
for example, you can specify lineweights to be scaled in proportion to the
new plot scale.
To scale lineweights, set the ScaleLineweights property to TRUE. If you do
not want lineweights to be scaled, set this property to FALSE.

8 | Chapter 9
Plot

Define Layouts and

Set the Plot Device

The plot device name is specified in the ConfigName property. You can set
this name to any valid device name for your system. If you do not set this
property, plots will be sent to the default device for your system.

Viewports
When working in model space you draw geometry in tile viewports (referred
to as Viewport objects in ActiveX Automation). You can display one or
several different viewports at a time. If several tiled viewports are displayed,
editing in one viewport affects all other viewports. However, you can set
magnification, viewpoint, grid, and snap settings individually for each
viewport.
In paper space, you work in floating paper space viewports (referred to as
PViewport objects in ActiveX Automation) to contain different views of your
model. Floating viewports are treated as objects you can move, resize, and
shape to create a suitable layout. You also can draw objects, such as title
blocks or annotations, directly in the paper space view without affecting the
model itself.

tiled viewports

floating viewports

For more information about viewports, see Set Model Tab Viewports, Display Multiple Views, and Create Layout Viewports in the Users Guide.

Floating Viewports
You cannot edit the model in paper space. To access the model in a
PViewport object, toggle from paper space to model space using the
ActiveSpace prop- erty. As a result, you can work with the model while
keeping the overall layout visible. In PViewport objects, the editing and
view-changing capabili- ties are almost the same as in Viewport objects.
However, you have more control over the individual views. For example,
you can freeze or turn off

Viewports

layers in some viewports without affecting others. You can turn an entire
viewport display on or off. You can also align views between viewports and
scale the views relative to the overall layout.
The following illustration shows how different views of a model are displayed in paper space. Each paper space image represents a PViewport object
with a different view. In one view, the dimensioning layer is frozen. Notice
that the title block, border, and annotation, which are drawn in paper space,
do not appear in the Model Space view. Also, the layer containing the viewport borders has been turned off.

the model

the model displayed in floating viewports

When you work in a Viewport object, the ActiveSpace property must always
be set to acModelSpace. When you are working in a PViewport object, you
can set the ActiveSpace property to either acModelSpace or acPaperSpace,
thus allowing you to switch between paper space and model space as
needed.
PViewport object, Viewport object, and ActiveSpace property
settings
Type of viewport

Status

Usage

PViewport

ActiveSpace =
acPaperspace

Arrange the layout by creating floating

viewports and adding title block, borders, and
annotation. Editing does not affect the model.

PViewport

ActiveSpace =
acModelspace

Work within floating viewports to edit the model

or change views. You can turn off or freeze
layers in individual viewports.

Viewport

ActiveSpace =
acModelspace

Split the screen into tiled viewports to edit

different views of the model.

10 | Chapter 9 Define Layouts and

Plot

In AutoCAD ActiveX Automation, the ActiveSpace property is used to control the TILEMODE system variable. Setting
ThisDrawing.ActiveSpace = acModelSpace is equivalent to setting
TILEMODE = on, and setting ThisDrawing.ActiveSpace = acPaperSpace
is equivalent to setting TILEMODE = off.
Similarly, the MSpace property is the equivalent of both the MSPACE and
PSPACE commands in AutoCAD. Setting ThisDrawing.MSpace = TRUE is the
same as using the MSPACE command: it switches to model space. Setting
ThisDrawing.MSpace = FALSE is the same as using the PSPACE command: it
switches to paper space.
In addition, you are required to use the Display method before setting the
MSpace property to TRUE. The Display method initializes certain graphic settings that must be set before switching to model space. In AutoCAD this is
done behind the scenes. However, in the ActiveX Automation interface,
the programmer must take care of this initialization.

Note Remember, you must turn on the display using the Display method for
at least one PViewport object before you can set the MSpace property to TRUE.
Failure to turn on the display will result in an error being returned when you try
to set the MSpace property.

Switch to a Paper Space Layout

From model space, you can switch to the last active paper space layout.
To switch to the last active paper space layout
1 Set the ActiveSpace property to acPaperSpace:
ThisDrawing.ActiveSpace = acPaperSpace

2 Toggle the MSpace property to FALSE:

ThisDrawing.MSpace = FALSE

When you are in paper space, AutoCAD displays the paper space UCS icon
in the lower-left corner of the graphics area. The crosshairs indicate that the
paper space layout area (not the views in the viewports) can be edited.

Switch to the Model Space Layout

From paper space, you can switch to model space floating viewports or
model space tiled viewports.
To switch to floating viewports
1 Use the Display method to initialize graphic settings:
ThisDrawing.ActivePViewport.Display TRUE

2 Toggle the MSpace property to TRUE:

ThisDrawing.MSpace = TRUE

This will place you in model space, floating viewports.

Note You must create floating viewports before you attempt to switch
to model space.
To switch to tiled viewports
To switch to tiled viewports, perform this additional step:

Set the ActiveSpace property to acModelSpace:

ThisDrawing.ActiveSpace = acModelSpace

Create Paper Space Viewports

Paper space viewports are created with the AddPViewport method. This
method requires a center point and the width and height of the new viewport. Before creating the viewport, use the ActiveSpace property to set paper
space as the current space (normally done by setting TILEMODE to 0).
After creating the PViewport object, you can set properties of the view itself,
such as viewing direction (Direction property), lens length for perspective
views (LensLength property), and grid display (GridOn property). You can
also control properties of the viewport itself, such as layer (Layer property),
linetype (Linetype property), and linetype scaling (LinetypeScale property).

Create and enable a floating viewport

This example switches AutoCAD to paper space, creates a floating viewport,
sets the view, and enables the viewport.
Sub Ch9_SwitchToPaperSpace()
' Set the active space to paper space
ThisDrawing.ActiveSpace = acPaperSpace
' Create the paperspace viewport
Dim newVport As AcadPViewport
Dim center(0 To 2) As Double
center(0) = 3.25
center(1) = 3
center(2) = 0
Set newVport = ThisDrawing.PaperSpace. _
AddPViewport(center, 6, 5)
' Change the view direction for the viewport
Dim viewDir(0 To 2) As Double
viewDir(0) = 1
viewDir(1) = 1
viewDir(2) = 1
newVport.direction = viewDir
' Enable the viewport
newVport.Display True
' Switch to model space
ThisDrawing.MSpace = True
' Set newVport current
' (not always necessary but a good idea)
ThisDrawing.ActivePViewport = newVport
' Zoom Extents in model space
ZoomExtents
' Turn model space editing off
ThisDrawing.MSpace = False
' ZoomExtents in paperspace
ZoomExtents
End Sub

The order of steps in the preceding code is important. In general, things

must be done in the same order they would be done at the AutoCAD
command line. The only unexpected actions involve defining the view and
enabling the viewport.

Note To set or modify aspects of the view (view direction, lens length, and
so forth), the Viewport objects Display method must be set to off (FALSE), and
before you can set a viewport current the Display method must be set to on
(TRUE).
Create four floating viewports
This example takes the example from Create and enable a floating viewport on page 269 and continues it by creating four floating viewports and
setting the view of each to top, front, right, and isometric views,
respectively. Each view is scaled to half the scale of paper space. To ensure
there is some- thing to see in these viewports, you may want to create a 3D
solid sphere before trying this example.

Sub Ch9_FourPViewports()
Dim topVport, frontVport As AcadPViewport
Dim rightVport, isoVport As AcadPViewport
Dim pt(0 To 2) As Double
Dim viewDir(0 To 2) As Double
ThisDrawing.ActiveSpace = acPaperSpace
ThisDrawing.MSpace = True
' Take the existing PViewport and make it the topVport
pt(0) = 2.5: pt(1) = 5.5: pt(2) = 0
Set topVport = ThisDrawing.ActivePViewport
'No need to set Direction for top view
topVport.center = pt
topVport.width = 2.5
topVport.height = 2.5
topVport.Display True
ThisDrawing.MSpace = True
ThisDrawing.ActivePViewport = topVport
ZoomExtents
ZoomScaled 0.5, acZoomScaledRelativePSpace
'Create and setup frontVport
pt(0) = 2.5: pt(1) = 2.5: pt(2) = 0
Set frontVport = ThisDrawing.PaperSpace. _
AddPViewport(pt, 2.5, 2.5)
viewDir(0) = 0: viewDir(1) = 1: viewDir(2) = 0
frontVport.direction = viewDir
frontVport.Display acOn
ThisDrawing.MSpace = True
ThisDrawing.ActivePViewport = frontVport
ZoomExtents
ZoomScaled 0.5, acZoomScaledRelativePSpace
'Create and setup rightVport
pt(0) = 5.5: pt(1) = 5.5: pt(2) = 0
Set rightVport = ThisDrawing.PaperSpace. _
AddPViewport(pt, 2.5, 2.5)
viewDir(0) = 1: viewDir(1) = 0: viewDir(2) = 0
rightVport.direction = viewDir
rightVport.Display acOn
ThisDrawing.MSpace = True
ThisDrawing.ActivePViewport = rightVport
ZoomExtents
ZoomScaled 0.5, acZoomScaledRelativePSpace
'Create and set up isoVport
pt(0) = 5.5: pt(1) = 2.5: pt(2) = 0
Set isoVport = ThisDrawing.PaperSpace. _
AddPViewport(pt, 2.5, 2.5)
viewDir(0) = 1: viewDir(1) = 1: viewDir(2) = 1
isoVport.direction = viewDir
isoVport.Display acOn
ThisDrawing.MSpace = True
ThisDrawing.ActivePViewport = isoVport
ZoomExtents
ZoomScaled 0.5, acZoomScaledRelativePSpace
'Finish: Perform a regen in all viewports
ThisDrawing.Regen True
End Sub

Change Viewport Views and Content

To change the view within a Viewport object, you must be in model space
and the viewport must be active.
To edit a drawing in a floating viewport
1 In model space, make the viewport active by setting the ActiveViewport
property:
Thisdrawing.ActiveViewport = MyViewportObject

2 Edit the drawing.

You can also create objects such as annotations, dimensions, and title
blocks in paper space. You must, however, set the ActiveSpace property to
FALSE, and turn paper space on using the MSpace property. Objects created
in paper space are visible only in paper space.

Scale Views Relative to Paper Space

Before you plot, you can establish accurate zoom scale factors for each
section of your drawing. Scaling views relative to paper space establishes a
consistent scale for each displayed view. For example, the following
illustra- tion shows a paper space view with several viewportseach set to
different scales and views. To scale the plotted drawing accurately, you must
scale each view relative to paper space, not relative to the previous view or
to the full- scale model.

When you work in paper space, the scale factor represents a ratio between
the size of the plotted drawing and the actual size of the model displayed in
the viewports. To derive this scale, divide paper space units by model space
units. For a quarter-scale drawing, for example, you specify a scale factor of
one paper space unit to four model space units (1:4).

Use the ZoomScaled method to scale viewports relative to paper space units.
This method takes three values as input: the viewport to scale, the scale factor, and how you want that scale factor applied. The third value is optional
and determines how the scale is applied:

Relative to the drawing limits

Relative to the current view
Relative to paper space units

To specify the scale relative to paper space units, enter the

acZoomScaled- RelativePSpace constant for this value.
As shown in the illustrations, if you enter a scale of 2 relative to the paper
space units, the scale in the viewport increases to twice the size of the paper
space units. A scale of .5 relative to the paper space units sets the scale to half
the size of the paper space units. The model is plotted at half its actual size.

current view

zoom to 0.5xp

zoom to 2xp

Scale Pattern Linetypes in Paper Space

In paper space, you can scale any type of linetype in two ways. The scale can
be based on the drawing units of the space in which the object was created
(model or paper). The linetype scale also can be a uniform scale based on
paper space units. You can use the PSLTSCALE system variable to maintain the
same linetype scaling for objects displayed at different zoom scales in different viewports. It also affects the line display in 3D views.
In the following illustration, the pattern linetype of the lines in model space
is scaled uniformly in paper space by the PSLTSCALE system variable.
Notice that the linetype in the two viewports has the same scale, even
though the objects have different zoom scales.

psltscale=1, dashes scaled to paper space

psltscale=0, dashes scaled to space where

they were created

Use the SetVariable method to set the value of the PSLTSCALE system variable.

Hide Lines in Plotted Viewports

If your drawing contains 3D faces, meshes, extruded objects, surfaces, or
solids, you can remove hidden lines from specific viewports when you plot
the viewport.
To hide lines in plots of paper space viewports (PViewport objects) use the
RemoveHiddenLines property for the given viewport. This property takes a
Boolean value. Enter TRUE to remove the hidden lines from the plot, enter
FALSE to have the hidden lines drawn in the plot.
To hide lines in plots of model space viewports (Viewport objects) use the
PlotHidden property found on the Layout object. This property takes a Boolean value. Enter TRUE to remove the hidden lines from the plot, enter FALSE
to have the hidden lines drawn in the plot.

Plot Your Drawing

You can plot your drawing as it is viewed in model space, or you can plot one
of your prepared paper space layouts. Plotting from model space is often
pref- erable when you want to view or verify your drawing prior to creating a
paper space layout. Once your model is ready, you can prepare and plot a
paper space layout.
Plotting involves working with two ActiveX Automation objects: the
Layout object and the Plot object. The Layout object contains the plot
settings for a given layout. The Plot object contains the methods and
properties that ini- tiate and monitor a plotting sequence.

Perform Basic Plotting

From the Plot object you can use the following methods and properties:
PlotToFile

Plots to a file

PlotToDevice

Plots to a plotter or printer

DisplayPlotPreview
Displays a preview of the specified plot
SetLayoutsToPlot
Establish the list of layouts that will be plotted in the
next call to PlotToFile or PlotToDevice
StartBatchMode
QuietErrorMode

Initiates a batch plot

NumberOfCopies
Toggles the quiet error mode for plot error reporting
BatchPlotProgress
Specifies the number of copies to be plotted

Gets the current status of the batch plot, or terminates

the batch plot.
The SetLayoutsToPlot method must be called before each PlotToDevice or
PlotToFile method. If SetLayoutsToPlot is not called, or is called with a
NULL input, the active layout will be plotted.

Plot Your Drawing

19

The NumberOfCopies property specifies the number of copies to plot. If this

property is not reset before each PlotToDevice call, the last value specified in
the NumberOfCopies property will be used.
Batch mode plotting is provided to support the BatchPlot utility application.
Before initiating a batch plot, set the QuietErrorMode to TRUE to have an
uninterrupted plot session. Use the StartBatchMode method to initiate a
batch plot. Use the BatchPlotProgress property to check on the progress of
the batch plot, or to terminate the batch mode.

Plot from Model Space

Typically, when you plot a large drawing such as a floorplan, you can
specify a scale to convert the real drawing units into plotted inches or
millimeters. However, when you plot from model space, the defaults that
are used if there are no settings specified include plot to system printer, plot
the current dis- play, scaled to fit, 0 rotation, and 0,0 offset. To modify the
plot settings, change the properties on the Layout object associated with
model space.
Plot the extents of an active model space layout
This example first checks to make sure the active space is model space. The
example then establishes several plot settings. Finally, the plot is sent using
the PlotToDevice method.
Sub Ch9_PrintModelSpace()
' Verify that the active space is model space
If ThisDrawing.ActiveSpace = acPaperSpace Then
ThisDrawing.MSpace = True
ThisDrawing.ActiveSpace = acModelSpace
End If
' Set the extents and scale of the plot area
ThisDrawing.ModelSpace.Layout.PlotType = acExtents
ThisDrawing.ModelSpace.Layout. _
StandardScale = acScaleToFit
' Set the number of copies to one
ThisDrawing.Plot.NumberOfCopies = 1
' Initiate the plot
ThisDrawing.Plot.PlotToDevice
End Sub

The device name can be specified using the ConfigName property. This
device can be overridden in the PlotToDevice method by specifying a PC3 file.

Plot from Paper Space

You can plot one or many paper space layouts at a time. You can plot the
active layout, as demonstrated in Plot from Model Space on page 276, or
you can specify by name the layouts to be plotted.
Plot two paper space layouts
This example sends the two paper space layouts Layout1 and Layout2 to
the default plot device. Note that these two layouts must exist in the drawing
for this code to run. This example first creates a string array containing the
names of the layouts to be plotted. It then uses this array as input to the SetLayoutsToPlot method. The example then sets the number of copies to be
plotted, and finally sends the plot to the default device.
Sub Ch9_PrintPaperSpace()
' Establish the paper space layouts to be plotted
Dim strLayouts(0 To 1) As String
Dim varLayouts As Variant
strLayouts(0) = "Layout1"
strLayouts(1) = "Layout2"
varLayouts = strLayouts
ThisDrawing.Plot.SetLayoutsToPlot varLayouts
' Set the number of copies to one
ThisDrawing.Plot.NumberOfCopies = 1
' Initiate the plot
ThisDrawing.Plot.PlotToDevice
End Sub

278

Advanced Drawing and

Organizational
Techniques
As you gain experience, you can take advantage of the

In this chapter

many advanced features of AutoCAD to further

Work with Raster Images

enhance your applications.

You can include in your drawing raster images such as
aerial, satellite, and digital photographs, as well as

Use Blocks and

Attributes
Use External References
Assign and Retrieve

Extended
Data

computer-rendered images. For information about raster images in addition to the information in this
section, see the Users Guide.
In addition to enhancing your drawings visual image,
AutoCAD provides several features to help you organize
data, allowing you to further expand the intelligence of
the objects in your drawing.

279

Work with Raster Images

With AutoCAD you can add raster images to your vector-based AutoCAD
drawings, and then view and plot the resulting file.

Attach and Scale a Raster Image

Images can be placed in a drawing file, but they are not actually part of the
file. The image is linked to the drawing file through a path name or a data
management document ID. Linked image paths can be changed or removed
at any time. To attach an image, you create a Raster object in your drawing
using the AddRaster method. This method takes four values as input: the
name of the image file to attach, the insertion point in the drawing to place
the image, the scale factor of the image, and the rotation angle of the
image. Remember, the Raster object represents an independent link to the
image, not the image itself.
Once youve attached an image, you can reattach it many times, creating a
new Raster object for each attachment. Each attachment has its own clip
boundary and its own settings for brightness, contrast, fade, and transparency. A single image can be cut into multiple pieces and rearranged
indepen- dently in your drawing.
You can set the raster image scale factor when you create the Raster object
so that the images geometry scale matches the scale of the geometry created
in the AutoCAD drawing. When you select an image to attach, the image is
inserted at a scale factor of 1 image unit of measurement to 1 AutoCAD unit
of measurement. To set the image scale factor, you need to know the scale
of the geometry on the image, and you need to know what unit of
measure- ment (inches, feet, and so forth) you want to use to define 1
AutoCAD unit. The image file must contain resolution information defining
the DPI, or dots per inch, and number of pixels in the image.
If an image has resolution information, AutoCAD combines it with the scale
factor and the AutoCAD unit of measurement you supply to scale the image
in your drawing. For example, if your raster image is a scanned blueprint on
which the scale is 1 inch equals 50 feet, or 1:600, and your AutoCAD
drawing is set up so that 1 unit represents 1 inch, then to set the scale
factor of the image, you enter 600 for the ScaleFactor parameter of the
AddRaster method. AutoCAD then inserts the image at a scale that brings
the geometry in the image into alignment with the vector geometry in the
drawing.

24 | Chapter 10 Advanced Drawing and Organizational

Techniques

Note If no resolution information is defined with the attached image file,

AutoCAD calculates the images original width as one unit. After insertion, the
image width in AutoCAD units is equal to the scale factor.
Attach a raster image
This example adds a raster image in model space. This example uses the
watch.jpg found in the sample directory. If you do not have this image, or it
is located in a different directory, insert a valid path and file name for the
imageName variable.
Sub Ch10_AttachingARaster()
Dim insertionPoint(0 To 2) As Double
Dim scalefactor As Double
Dim rotationAngle As Double
Dim imageName As String
Dim rasterObj As AcadRasterImage
imageName = "C:/Program Files/AutoCAD 2004/sample/watch.jpg"
insertionPoint(0) = 5
insertionPoint(1) = 5
insertionPoint(2) = 0
scalefactor = 2
rotationAngle = 0
On Error GoTo ERRORHANDLER
' Attach the raster image in model space
Set rasterObj = ThisDrawing.ModelSpace.AddRaster _
(imageName, insertionPoint, _
scalefactor, rotationAngle)
ZoomAll
Exit Sub
ERRORHANDLER:
MsgBox Err.Description
End Sub

Manage Raster Images

You can manage raster image name, file name, and file path using the
prop- erties of the Raster object.

Change Image File Paths

The path and file name of an image is queried or changed using the
ImageFile property. The path set by this property is the actual path where
AutoCAD looks for the image.

Work with Raster Images

25

If AutoCAD cannot locate the drawing (for example, if you have moved the
file to a different directory than the one saved with the ImageFile property),
it removes relative or absolute path information from the name (for
example,
\images\tree.tga or c:\my project\images\tree.tga becomes tree.tga) and
searches the paths you have defined using the SetProjectFilePath method on
the Preferences object. If the drawing is not located in the paths, it
attempts the first search path again.
You can remove the path from the file name or specify a relative path by
resetting the ImageFile property.
Changing the path in the ImageFile property does not affect the project files
search-path settings.

Name Images
Image names are not necessarily the same as image file names. When you
attach an image to a drawing, AutoCAD uses the file name without the file
extension as the image name. You can change the image name without
affecting the name of the file.
The image file is represented by the ImageFile property on the Raster object.
Changing the ImageFile property will change the image in the drawing. The
image name is represented by the Name property, and changing the Name
property will change the name of the image only, not the file associated
with it.

Modify Images and Image Boundaries

All images have an image boundary. When you attach an image to a
drawing, the image boundary inherits the current property settings,
including color, layer, linetype, and linetype scale. If the image is a bitonal
image, the image color and boundary color are the same.
As with other AutoCAD objects, you can modify images and their boundary
properties. For example, you can:

Display or hide the image boundary

Modify the image layer, boundary color, and linetype
Change the image location
Scale, rotate, and change the width and height of the image
Toggle the image visibility
Change the image transparency
Change the image brightness, contrast, and fade
Change the quality and speed of image display

26 | Chapter 10 Advanced Drawing and Organizational

Techniques

Show and Hide Image Boundaries

Hiding an image boundary ensures that the image cannot accidentally be
moved or modified and prevents the boundary from being plotted or
displayed. When image boundaries are hidden, clipped images are still displayed to their specified boundary limits; only the boundary is affected.
Showing and hiding image boundaries affects all images attached to your
drawing.
To show or hide the image boundaries, use the ClippingEnabled property.

Note This property affects only the image boundary. To see a change in the
image when toggling this property, look closely at the small boundary surrounding the image.

Change Image Layer, Boundary Color, and

Boundary Linetype
You can change the color and linetype of image boundaries and the layer
of an image using the following properties:
Layer

Specifies the layer for the image

Color

Specifies the color of the image boundary

Linetype

Specifies the linetype of the image

Change Image Scale, Rotation, Location, Width,

and Height
You can change the scale, rotation, location, width, and height of an
image using the following methods and properties:
ScaleEntity

Scales the image

Rotate

Rotates the image

Origin

Specifies the image location

Width

Specifies the width of the image in pixels Height

Specifies the height of the image in pixels

ImageWidth

Specifies the width of the image in database units

ImageHeight

Specifies the height of the image in database units

ShowRotation

Determines if the raster is displayed as rotated

Work with Raster Images

27

Change Image Visibility

Image visibility affects the redraw speed by hiding images in the current
drawing session. Hidden images are not displayed or plotted; only the drawing boundary is displayed. To hide images, set the ImageVisibility property
to FALSE. To redisplay the images, set the ImageVisibility property to TRUE.

Modify Bitonal Image Color and Transparency

Bitonal raster images are images consisting only of a foreground color and a
background color. When you attach a bitonal image, the foreground pixels
in the image inherit the current layer settings for color. In addition to the
modifications you can make to any attached image, you can modify bitonal
images by changing the foreground color and by turning the transparency
of the background on and off.

Note Bitonal images and bitonal image boundaries are always the same color.
To change the foreground color of a bitonal image, use the Color property.
To turn the transparency on and off, use the Transparency property.

Adjust Image Brightness, Contrast, and Fade

You can adjust image brightness, contrast, and fade in AutoCAD to the display of the image and to plotted output without affecting the original raster
image file.
Use the following properties to adjust brightness, contrast, and fade:
Brightness

Specifies the brightness level of an image

Contrast

Specifies the contrast level of an image

Fade

Specifies the fade level of an image

28 | Chapter 10 Advanced Drawing and Organizational

Techniques

Clip Images
You can define a region of an image for display and plotting by clipping the
image. The clipping boundary must be a 2D polygon or rectangle with
vertices constrained to lay within the boundaries of the image. Multiple
instances of the same image can have different boundaries.
To clip an image
1 Turn on the image boundaries using the ClippingEnabled property.
2 Specify the clipping boundary and perform the clip using the ClipBoundary method. This method takes one value as input: a variant array of 2D
WCS coordinates specifying the clipping boundary of a raster image.

Change the Clipping Boundary

To change an existing clipping boundary, simply repeat the previous steps.
The old boundary will be deleted and the new boundary will replace the old
one.

Show and Hide the Clipping Boundary

You can display a clipped image using the clipping boundary, or you can
hide the clipping boundary and display the original image boundaries. To
hide a clipping boundary and display the original image, set the
ClippingEnabled property to FALSE. To display the clipped image, set the
ClippingEnabled property to TRUE.
Clip a raster image boundary
This example adds a raster image in model space. It then clips the image
based on a clip boundary. This example uses downtown.jpg found in the sample directory. If you do not have this image, or it is located in a different
directory, insert a valid path and file name for the imageName variable.

Work with Raster Images

29

Sub Ch10_ClippingRasterBoundary()
Dim insertionPoint(0 To 2) As Double
Dim scalefactor As Double
Dim rotationAngle As Double
Dim imageName As String
Dim rasterObj As AcadRasterImage
imageName = "C:\AutoCAD\sample\downtown.jpg"
insertionPoint(0) = 5
insertionPoint(1) = 5
insertionPoint(2) = 0
scalefactor = 2
rotationAngle = 0
On Error GoTo ERRORHANDLER
' Creates a raster image in model space
Set rasterObj = ThisDrawing.ModelSpace.AddRaster _
(imageName, insertionPoint, _
scalefactor, rotationAngle)
ZoomAll
' Establish the clip boundary with
Dim clipPoints(0 To 9) As Double
clipPoints(0) = 6: clipPoints(1) =
clipPoints(2) = 7: clipPoints(3) =
clipPoints(4) = 6: clipPoints(5) =
clipPoints(6) = 5: clipPoints(7) =
clipPoints(8) = 6: clipPoints(9) =

an array of points
6.75
6
5
6
6.75

' Clip the image

rasterObj.ClipBoundary clipPoints
' Enable the display of the clip
rasterObj.ClippingEnabled = True
ThisDrawing.Regen acActiveViewport
Exit Sub
ERRORHANDLER:
MsgBox Err.Description
End Sub

Use Blocks and Attributes

AutoCAD provides several features to help you manage objects in your drawings. With blocks you can organize and manipulate many objects as one
component. Attributes associate items of information with the blocks in your
drawingsfor example, part numbers and prices.
Using AutoCAD external references, or xrefs, you can attach or overlay entire
drawings to your current drawing. When you open your current drawing,
any changes made in the referenced drawing appear in the current drawing.

30 | Chapter 10 Advanced Drawing and Organizational

Techniques

Work with Blocks

A block is a collection of objects you can associate together to form a single
object, or a block reference. You can insert, scale, and rotate a block
reference in a drawing. You can explode a block reference into its
component objects, modify them, and redefine the block. AutoCAD
updates all future instances of that block reference based on the definition
of the block.
Blocks can be defined from objects originally drawn on different layers with
different colors and linetypes. You can preserve the layer, color, and linetype
information of objects in a block. Then, each time you insert the block, you
have each object within the block drawn on its original layer with its
original color and linetype.
For more information about working with blocks, see Create and Insert
Symbols (Blocks) in chapter 16, Draw Geometric Objects, in the
Users Guide.

Define Blocks
To create a new block, use the Add method. This method requires two
values as input: the location in the drawing where the block is added and
the name of the block to create.
Once created, you can add any geometrical object, or another block, to the
newly created block. You can then insert an instance of the block into the
drawing. An inserted block is an object called a block reference.
You can also create a block by using the WBlock method to group objects in
a separate drawing file. The drawing file can then be used as a block definition for other drawings. AutoCAD considers any drawing you insert into
another drawing to be a block.
For more information on defining blocks, see Create Blocks in chapter 16,
Draw Geometric Objects, in the Users Guide.

Insert Blocks
You can insert blocks or entire drawings into the current drawing with the
InsertBlock method. The InsertBlock method takes six values as input: the
insertion point, the name of the block or drawing to insert, the X-scale
factor, the Y-scale factor, the Z-scale factor, and the rotation angle.
When you insert an entire drawing into another drawing, AutoCAD treats
the inserted drawing like any other block reference. Subsequent insertions
reference the block definition (which contains the geometric description of
the block) with different position, scale, and rotation settings. If you
change the original drawing after inserting it, the changes have no effect on
the

Use Blocks and Attributes

31

inserted block. If you want the inserted block to reflect the changes you
made to the original drawing, you can redefine the block by reinserting the
original drawing. This can be done with the InsertBlock method.
If you insert a drawing as a block, the file name is automatically used as the
name of the block. You can change the name of the block by using the
Name property once the block has been created.
By default, AutoCAD uses the coordinate (0, 0, 0) as the base point for
inserted drawings. You can change the base point of a drawing by opening
the original drawing and using the SetVariable method to specify a different
insertion base point for the INSBASE system variable. AutoCAD uses the new
base point the next time you insert the drawing.
If the drawing you insert contains PaperSpace objects, those objects are not
included in the current drawings block definition. To use the PaperSpace
objects in another drawing, open the original drawing and use the Add
method to define the PaperSpace objects as a block. You can insert the drawing into another drawing in either paper space or model space.
A block reference cannot be iterated to find the original objects that
compose it. However, you can iterate the original block definition, or you
can explode the block reference into its original components.
You can also insert an array of blocks using the AddMInsertBlock method.
This method does not insert a single block into your drawing, as the InsertBlock does, but instead inserts an array of the specified block. This method
returns an MInsertBlock object.
For more information on inserting blocks, see Insert Blocks in chapter 16,
Draw Geometric Objects, in the Users Guide.
Define a block and insert the block into a drawing
This example defines a block and adds a circle to the block definition. It then
inserts the block into the drawing as a block reference.

32 | Chapter 10 Advanced Drawing and Organizational

Techniques

Sub Ch10_InsertingABlock()
' Define the block
Dim blockObj As AcadBlock
Dim insertionPnt(0 To 2) As Double
insertionPnt(0) = 0
insertionPnt(1) = 0
insertionPnt(2) = 0
Set blockObj = ThisDrawing.Blocks.Add _
(insertionPnt, "CircleBlock")
' Add a circle to the block
Dim circleObj As AcadCircle
Dim center(0 To 2) As Double
Dim radius As Double
center(0) = 0
center(1) = 0
center(2) = 0
radius = 1
Set circleObj = blockObj.AddCircle(center, radius)
' Insert the block
Dim blockRefObj As AcadBlockReference
insertionPnt(0) = 2
insertionPnt(1) = 2
insertionPnt(2) = 0
Set blockRefObj = ThisDrawing.ModelSpace.InsertBlock _
(insertionPnt, "CircleBlock", 1#, 1#, 1#, 0)
ZoomAll
MsgBox "The circle belongs to " & blockRefObj.ObjectName
End Sub

Note

After insertion, the external files WCS is aligned parallel to the XY

plane of the current UCS in the current drawing. Thus, a block from an
external file is inserted at any orientation in space by setting the UCS before
inserting it.

Explode a Block Reference

Use the Explode method to break a block reference. By exploding a block reference, you can modify the block or add to or delete the objects that define
it.
Display the results of an exploded block reference
This example creates a block and adds a circle to the definition of the block.
The block is then inserted into the drawing as a block reference. The block
reference is then exploded, and the objects resulting from the explode process are displayed along with their object types.

Use Blocks and Attributes

33

Sub Ch10_ExplodingABlock()
' Define the block
Dim blockObj As AcadBlock
Dim insertionPnt(0 To 2) As Double
insertionPnt(0) = 0
insertionPnt(1) = 0
insertionPnt(2) = 0
Set blockObj = ThisDrawing.Blocks.Add _
(insertionPnt, "CircleBlock")
' Add a circle to the block
Dim circleObj As AcadCircle
Dim center(0 To 2) As Double
Dim radius As Double
center(0) = 0
center(1) = 0
center(2) = 0
radius = 1
Set circleObj = blockObj.AddCircle(center, radius)
' Insert the block
Dim blockRefObj As AcadBlockReference
insertionPnt(0) = 2
insertionPnt(1) = 2
insertionPnt(2) = 0
Set blockRefObj = ThisDrawing.ModelSpace.InsertBlock _
(insertionPnt, "CircleBlock", 1#, 1#, 1#, 0)
ZoomAll
MsgBox "The circle belongs to " & blockRefObj.ObjectName
' Explode the block reference Dim
explodedObjects As Variant
explodedObjects = blockRefObj.Explode
' Loop through the exploded objects
Dim I As Integer
For I = 0 To UBound(explodedObjects)
explodedObjects(I).Color = acRed
explodedObjects(I).Update
MsgBox "Exploded Object " & I & ": " _
& explodedObjects(I).ObjectName
explodedObjects(I).Color = acByLayer
explodedObjects(I).Update
Next
End Sub

Redefine a Block
Use any of the Block object methods and properties to redefine a block.
When you redefine a block, all the references to that block in the drawing are
immediately updated to reflect the new definition.

34 | Chapter 10 Advanced Drawing and Organizational

Techniques

Redefinition affects previous and future insertions of a block. Constant

attributes are lost and replaced by any new constant attributes.
Variable attributes remain unchanged, even if the new block has no
attributes.
Redefine the objects in a block definition
This example creates a block and adds a circle to the definition of the block.
The block is then inserted into the drawing as a block reference. The circle in
the block definition is updated, and the block reference updates
automatically.
Sub Ch10_RedefiningABlock()
' Define the block
Dim blockObj As AcadBlock
Dim insertionPnt(0 To 2) As Double
insertionPnt(0) = 0
insertionPnt(1) = 0
insertionPnt(2) = 0
Set blockObj = ThisDrawing.Blocks.Add _
(insertionPnt, "CircleBlock")
' Add a circle to the block
Dim circleObj As AcadCircle
Dim center(0 To 2) As Double
Dim radius As Double
center(0) = 0
center(1) = 0
center(2) = 0
radius = 1
Set circleObj = blockObj.AddCircle(center, radius)
' Insert the block
Dim blockRefObj As AcadBlockReference
insertionPnt(0) = 2
insertionPnt(1) = 2
insertionPnt(2) = 0
Set blockRefObj = ThisDrawing.ModelSpace.InsertBlock _
(insertionPnt, "CircleBlock", 1#, 1#, 1#, 0)
ZoomAll
' Redefine the circle in the block,
' and update the block reference
circleObj.radius = 3
blockRefObj.Update
End Sub

Use Blocks and Attributes

35

Work with Attributes

An attribute reference provides an interactive label or tag for you to attach
text to a block. Examples of data are part numbers, prices, comments, and
owners names.
You can extract attribute reference information from a drawing and use that
information in a spreadsheet or database to produce items such as a parts list
or bill of materials (BOM). You can associate more than one attribute reference with a block, provided that each attribute reference has a different tag.
You can also define constant attributes. Because they have the same value in
every occurrence of the block, AutoCAD does not prompt for a value when
you insert the block.
Attributes can be invisible, which means the attribute reference is not displayed or plotted. However, information on the attribute reference is stored
in the drawing file.
For more information about working with attributes, see Overview of Block
Attributes in chapter 16, Draw Geometric Objects, in the Users Guide.

Create Attribute Definitions and Attribute

References
To create an attribute reference, first you must create an attribute definition
on a block by using the AddAttribute method. This method requires six values as input: the height of the attribute text, the attribute mode, a prompt
string, the insertion point, the tag string, and the default attribute value.
The mode value is optional. There are five constants you can enter to
specify the Attribute mode:
acAttributeModeNormal

Specifies that the current mode of each attribute is

maintained.
acAttributeModeInvisible

Specifies that attribute values wont appear when you

insert the block. The ATTDISP command overrides the
Invisible mode.
acAttributeModeConstant

Gives attributes a fixed value for block insertions.

36 | Chapter 10 Advanced Drawing and Organizational

Techniques

acAttributeModeVerify

Prompts you to verify that the

correct when you insert the block.

attribute value is

acAttributeModePreset

Sets the attribute to its default value when you insert a

block containing a present attribute. The value cannot
be edited in this mode.
You can enter none, any combination, or all of the options. To specify a
com- bination of options, add the constants together. For example, you can
enter acAttributeModeInvisible + acAttributeModeConstant.
The prompt string appears when a block containing the attribute is
inserted. The default for this
string is the
Tag string. Input
acAttributeModeConstant for the mode to disable the prompt.
The tag string identifies each occurrence of the attribute. You can use any
characters except spaces or exclamation points. AutoCAD changes
lowercase letters to uppercase.
Once the attribute definition is defined in a block, whenever you insert the
block using the InsertBlock method you can specify a different value for the
attribute reference.
An attribute definition is associated to the block upon which it is created.
Attribute definitions created on model space or paper space are not considered attached to any given block.
Define an attribute definition
This example creates a block and then adds an attribute to the block. The
block is then inserted into the drawing.

Use Blocks and Attributes

37

Sub Ch10_CreatingAnAttribute()
' Define the block
Dim blockObj As AcadBlock
Dim insertionPnt(0 To 2) As Double
insertionPnt(0) = 0
insertionPnt(1) = 0
insertionPnt(2) = 0
Set blockObj = ThisDrawing.Blocks.Add _
(insertionPnt, "BlockWithAttribute")
' Add an attribute to the block
Dim attributeObj As AcadAttribute
Dim height As Double
Dim mode As Long
Dim prompt As String
Dim insertionPoint(0 To 2) As Double
Dim tag As String
Dim value As String
height = 1
mode = acAttributeModeVerify
prompt = "New Prompt"
insertionPoint(0) = 5
insertionPoint(1) = 5
insertionPoint(2) = 0
tag = "New Tag"
value = "New Value"
Set attributeObj = blockObj.AddAttribute(height, mode, _
prompt, insertionPoint, tag, value)
' Insert the block, creating a block reference
' and an attribute reference
Dim blockRefObj As AcadBlockReference
insertionPnt(0) = 2
insertionPnt(1) = 2
insertionPnt(2) = 0
Set blockRefObj = ThisDrawing.ModelSpace.InsertBlock _
(insertionPnt, "BlockWithAttribute", 1#, 1#, 1#, 0)
End Sub

Edit Attribute Definitions

You can use the Attribute object properties and methods to edit the
attribute. Some of the properties on an attribute include the following:
Alignment

Specifies the horizontal and vertical alignment of the

attribute

Backward

Specifies the direction of attribute text

38 | Chapter 10 Advanced Drawing and Organizational

Techniques

FieldLength

Specifies the field length of the attribute

Height

Specifies the height of the attribute

InsertionPoint

Specifies the insertion point of the attribute

Mode

Specifies the mode of the attribute

PromptString

Specifies the prompt string of the attribute

Rotation

Specifies the rotation of the attribute

ScaleFactor

Specifies the scale factor of the attribute

TagString

Specifies the tag string of the attribute

Some of the methods you can use to edit the attribute include the following:
ArrayPolar

Creates a polar array

ArrayRectangular

Creates a rectangular array

Copy

Copies the attribute

Erase

Erases the attribute

Mirror

Mirrors the attribute

Move

Moves the attribute

Rotate

Rotates the attribute

ScaleEntity

Scales the attribute

Redefine an attribute definition

This example creates a block and then adds an attribute to the block. The
block is then inserted into the drawing. The attribute text is then updated to
display backward.

Use Blocks and Attributes

39

Sub Ch10_RedefiningAnAttribute()
' Define the block
Dim blockObj As AcadBlock
Dim insertionPnt(0 To 2) As Double
insertionPnt(0) = 0
insertionPnt(1) = 0
insertionPnt(2) = 0
Set blockObj = ThisDrawing.Blocks.Add _
(insertionPnt, "BlockWithAttribute")
' Add an attribute to the block
Dim attributeObj As AcadAttribute
Dim height As Double
Dim mode As Long
Dim prompt As String
Dim insertionPoint(0 To 2) As Double
Dim tag As String
Dim value As String
height = 1
mode = acAttributeModeVerify
prompt = "New Prompt"
insertionPoint(0) = 5
insertionPoint(1) = 5
insertionPoint(2) = 0
tag = "New Tag"
value = "New Value"
Set attributeObj = blockObj.AddAttribute(height, mode, _
prompt, insertionPoint, tag, value)
' Insert the block, creating a block reference
' and an attribute reference
Dim blockRefObj As AcadBlockReference
insertionPnt(0) = 2
insertionPnt(1) = 2
insertionPnt(2) = 0
Set blockRefObj = ThisDrawing.ModelSpace.InsertBlock _
(insertionPnt, "BlockWithAttribute", 1#, 1#, 1#, 0)
' Redefine the attribute text to display backwards.
attributeObj.Backward = True
attributeObj.Update
End Sub

40 | Chapter 10 Advanced Drawing and Organizational

Techniques

Extract Attribute Information

You can extract attribute information from a drawing using the
GetAttributes and GetConstantAttributes methods. The GetAttributes
method returns an array of the attribute references attached to a block,
along with their current values. The GetConstantAttributes method returns
an array of constant attributes attached to the block or external reference.
The attributes returned by this method are the constant attribute
definitions, not attribute references.
You do not need template files to extract attribute information, and no
attribute information files are created. Simply iterate the array of attribute
references, using the TagString and TextString properties of the attribute
reference to examine the attribute information.
The TagString property represents the individual tag for the attribute reference. The TextString property contains the value for the attribute
reference.
For more information on extracting attribute information, see Extract Data
from Block Attributes in chapter 16, Draw Geometric Objects, in the
Users Guide.
Get attribute reference information
This example creates a block and then adds an attribute to the block. The
block is then inserted into the drawing. The attribute data is then returned
and displayed using a message box. The attribute data is then updated for the
block reference, and once again the attribute data is returned and
displayed.

Use Blocks and Attributes

41

Sub Ch10_GettingAttributes()
' Create the block
Dim blockObj As AcadBlock
Dim insertionPnt(0 To 2) As Double
insertionPnt(0) = 0
insertionPnt(1) = 0
insertionPnt(2) = 0
Set blockObj = ThisDrawing.Blocks.Add _
(insertionPnt, "TESTBLOCK")
' Define the attribute definition
Dim attributeObj As AcadAttribute
Dim height As Double
Dim mode As Long
Dim prompt As String
Dim insertionPoint(0 To 2) As Double
Dim tag As String
Dim value As String
height = 1#
mode = acAttributeModeVerify
prompt = "Attribute Prompt"
insertionPoint(0) = 5
insertionPoint(1) = 5
insertionPoint(2) = 0
tag = "Attribute Tag"
value = "Attribute Value"
' Create the attribute definition object on the block
Set attributeObj = blockObj.AddAttribute _
(height, mode, prompt, _
insertionPoint, tag, value)
' Insert the block
Dim blockRefObj As AcadBlockReference
insertionPnt(0) = 2
insertionPnt(1) = 2
insertionPnt(2) = 0
Set blockRefObj = ThisDrawing.ModelSpace.InsertBlock _
(insertionPnt, "TESTBLOCK", 1, 1, 1, 0)
ZoomAll
' Get the attributes for the block reference
Dim varAttributes As Variant
varAttributes = blockRefObj.GetAttributes
' Move the attribute tags and values into a
' string to be displayed in a Msgbox
Dim strAttributes As String
strAttributes = ""
Dim I As Integer
For I = LBound(varAttributes) To UBound(varAttributes)
strAttributes = strAttributes + " Tag: " + _
varAttributes(I).TagString + vbCrLf + _
"
Value: " + varAttributes(I).textString
Next

42 | Chapter 10 Advanced Drawing and Organizational

Techniques

MsgBox "The attributes for blockReference " + _

blockRefObj.Name & " are: " & vbCrLf _
& strAttributes
' Change the value of the attribute
' Note: There is no SetAttributes. Once you have the
' variant array, you have the objects.
' Changing them changes the objects in the drawing.
varAttributes(0).textString = "NEW VALUE!"
' Get the attributes again
Dim newvarAttributes As Variant
newvarAttributes = blockRefObj.GetAttributes
' Again, display the tags and values
strAttributes = ""
For I = LBound(varAttributes) To UBound(varAttributes)
strAttributes = strAttributes + " Tag: " + _
newvarAttributes(I).TagString + vbCrLf + _
"
Value: " + newvarAttributes(I).textString
Next
MsgBox "The attributes for blockReference " & _
blockRefObj.Name & " are: " & vbCrLf _
& strAttributes
End Sub

Use External References

An external reference (xref) links another drawing to the current drawing.
When you insert a drawing as a block, the block and all of the associated
geometry is stored in the current drawing database. It is not updated if the
original drawing changes. When you insert a drawing as an xref, however,
the xref is updated when the original drawing changes. A drawing that
contains xrefs, therefore, always reflects the most current editing of each
externally referenced file.
Like a block reference, an xref is displayed in the current drawing as a single
object. However, an xref does not significantly increase the file size of the
current drawing and cannot be exploded. As with blocks, you can nest xrefs
that are attached to your drawing.
For more information about xrefs, see Attach, Update, and Bind External
References in the Users Guide.

Use External References

43

Update Xrefs
When you open or plot your drawing, AutoCAD reloads each xref to reflect
the latest state of the referenced drawing. After you make changes to an
externally referenced drawing and save the file, other users can access your
changes immediately by reloading the xref.

Attach Xrefs
Attaching an xref links one drawing (the reference file, or xref) to the current
drawing. When a drawing references an xref, AutoCAD attaches only the xref
definition to the drawing, unlike regular blocks, where the block definition
and the contents of the block are stored with the current drawing. AutoCAD
reads the reference drawing to determine what to display in the current drawing. If the reference file is missing or corrupt, its data is not displayed in the
current drawing. Each time you open a drawing, AutoCAD loads all
graphical and non-graphical (such as layers, linetypes, and text styles)
objects from ref- erenced files. If VISRETAIN is on, AutoCAD stores any
updated xref-dependent layer information in the current drawing.
You can attach as many copies of an xref as you want, and each can have
a different position, scale, and rotation. You can also control the
dependent layers and linetype properties that are defined in the xref.
To attach an xref, use the AttachExternalReference method. This method
requires you to input the path and file name of the drawing to be
referenced, the name the xref is to use in the current drawing, the insertion
point, the scale, and rotation information for the xref. The
AttachExternalReference method returns the newly created
ExternalReference object.
For more information on attaching xrefs, see Attach External References in
the Users Guide.
Attach an external reference to a drawing
This example displays all the blocks in the current drawing before and after
adding an external reference. This example uses the City map.dwg found in
the sample directory. If you do not have this image, or it is located in a different directory, insert a valid path and file name for the PathName variable
below.

44 | Chapter 10 Advanced Drawing and Organizational

Techniques

Sub Ch10_AttachingExternalReference()
On Error GoTo ERRORHANDLER
Dim InsertPoint(0 To 2) As Double
Dim insertedBlock As AcadExternalReference
Dim tempBlock As AcadBlock
Dim msg As String, PathName As String
' Define external reference to be inserted
InsertPoint(0) = 1
InsertPoint(1) = 1
InsertPoint(2) = 0
PathName = "C:/Program Files/AutoCAD 2004/sample/City map.dwg"
' Display current Block information for this drawing
GoSub ListBlocks
' Add the external reference to the drawing
Set insertedBlock = ThisDrawing.ModelSpace. _
AttachExternalReference(PathName, "XREF_IMAGE", _
InsertPoint, 1, 1, 1, 0, False)
ZoomAll
' Display new Block information for this drawing
GoSub ListBlocks
Exit Sub
ListBlocks:
msg = vbCrLf
' Reset message
For Each tempBlock In ThisDrawing.Blocks
msg = msg & tempBlock.Name & vbCrLf
Next
MsgBox "The current blocks in this drawing are: " & msg
Return
ERRORHANDLER:
MsgBox Err.Description
End Sub

Overlay
Xrefs
Overlaying is similar to attaching, except when a drawing is attached or overlaid. Any other overlays nested in it are ignored and, therefore, not displayed.
In other words, nested overlays are not read in.
To
overlay
an
xref,
set
the
bOverlay
AttachExternalReference method to TRUE.

parameter

of

the

Detach
Xrefs
You can detach an xref definition to remove the xrefs completely from your
drawing. You can also erase the individual xref instances. Detaching the xref
definition removes all dependent symbols associated with that xref. If all the
instances of an xref are erased from the drawing, AutoCAD removes the xref
definition the next time the drawing is opened.

Use External References

45

To detach an xref, use the Detach method. You cannot detach a nested
xref.
Detach an xref definition
This example attaches an external reference and then detaches the external
reference. This example uses the City map.dwg found in the sample
directory. If you do not have this image, or it is located in a different
directory, insert a valid path and file name for the PathName variable below.
Sub Ch10_DetachingExternalReference()
On Error GoTo ERRORHANDLER
' Define external reference to be inserted
Dim xrefHome As AcadBlock
Dim xrefInserted As AcadExternalReference
Dim insertionPnt(0 To 2) As Double
Dim PathName As String
insertionPnt(0) = 1
insertionPnt(1) = 1
insertionPnt(2) = 0
PathName = "c:/AutoCAD/sample/City map.dwg"
' Add the external reference
Set xrefInserted = ThisDrawing.ModelSpace. _
AttachExternalReference(PathName, "XREF_IMAGE", _
insertionPnt, 1, 1, 1, 0, False)
ZoomAll
MsgBox "The external reference is attached."
' Detach the external reference definition
Dim name As String
name = xrefInserted.name
ThisDrawing.Blocks.Item(name).Detach
MsgBox "The external reference is detached."
Exit Sub
ERRORHANDLER:
MsgBox Err.Description
End Sub

Reload
Xrefs
If someone modifies an externally referenced drawing while you are working
on the host drawing to which that xref is attached, you can update that xref
drawing using the Reload method. When you reload, the selected xref drawing is updated in your host drawing. Also, if you have unloaded an xref, you
can choose to reload that externally referenced drawing at any time.

46 | Chapter 10 Advanced Drawing and Organizational

Techniques

Reload an xref definition

This example attaches an external reference and then reloads the external
reference. This example uses the City map.dwg found in the sample
directory. If you do not have this image, or it is located in a different
directory, insert a valid path and file name for the PathName variable below.
Sub Ch10_ReloadingExternalReference()
On Error GoTo ERRORHANDLER
' Define external reference to be inserted
Dim xrefHome As AcadBlock
Dim xrefInserted As AcadExternalReference
Dim insertionPnt(0 To 2) As Double
Dim PathName As String
insertionPnt(0) = 1
insertionPnt(1) = 1
insertionPnt(2) = 0
PathName = "c:/AutoCAD/sample/City map.dwg"
' Add the external reference to the block
Set xrefInserted = ThisDrawing.ModelSpace. _
AttachExternalReference(PathName, "XREF_IMAGE", _
insertionPnt, 1, 1, 1, 0, False)
ZoomAll
MsgBox "The external reference is attached."
' Reload the external reference definition
ThisDrawing.Blocks.Item(xrefInserted.name).Reload
MsgBox "The external reference is reloaded."
Exit Sub
ERRORHANDLER:
MsgBox Err.Description
End Sub

Unload Xrefs
To unload an xref use the Unload method. When you unload a referenced
file that is not being used in the current drawing, the AutoCAD performance
is enhanced by not having to read and display unnecessary drawing geometry or symbol table information. The xref geometry and that of any nested
xref is not displayed in the current drawing until the xref is reloaded.
Unload an xref definition
This example attaches an external reference and then unloads the external
reference. This example uses the City map.dwg found in the sample
directory. If you do not have this image, or it is located in a different
directory, insert a valid path and file name for the PathName variable below.

Use External References

47

Sub Ch10_UnloadingExternalReference()
On Error GoTo ERRORHANDLER
' Define external reference to be inserted
Dim xrefHome As AcadBlock
Dim xrefInserted As AcadExternalReference
Dim insertionPnt(0 To 2) As Double
Dim PathName As String
insertionPnt(0) = 1
insertionPnt(1) = 1
insertionPnt(2) = 0
PathName = "c:/AutoCAD/sample/City map.dwg"
' Add the external reference
Set xrefInserted = ThisDrawing.ModelSpace. _
AttachExternalReference(PathName, "XREF_IMAGE", _
insertionPnt, 1, 1, 1, 0, False)
ZoomAll
MsgBox "The external reference is attached."
' Unload the external reference definition
ThisDrawing.Blocks.Item(xrefInserted.name).Unload
MsgBox "The external reference is unloaded."
Exit Sub
ERRORHANDLER:
MsgBox Err.Description
End Sub

Bind Xrefs
Binding an xref to a drawing using the Bind method makes the xref a
perma- nent part of the drawing and no longer an externally referenced file.
The externally referenced information becomes a block. When the
externally referenced drawing is updated, the bound xref is not updated.
This process binds the entire drawings database, including all of its
dependent symbols. Dependent symbols are named objects such as blocks,
dimension styles, lay- ers, linetypes, and text styles. Binding the xref allows
named objects from the xref to be used in the current drawing.
The Bind method requires only one parameter: bPrefixName. If
bPrefixName is set to TRUE, the symbol names of the xref drawing are
prefixed in the current drawing with <blockname>$x$, where x is an integer
that is automat- ically incremented to avoid overriding existing block
definitions. If the bPrefixName parameter is set to FALSE, the symbol names
of the xref drawing are merged into the current drawing without the prefix.
If duplicate names exist, AutoCAD uses the symbols already defined in the
local drawing. If you are unsure whether your drawing contains duplicate
symbol names, it is rec- ommended that you set bPrefixName to TRUE.

48 | Chapter 10 Advanced Drawing and Organizational

Techniques

For more information on binding xrefs, see Archive Drawings That Contain
External References (Bind) in the Users Guide.
Bind an xref definition
This example attaches an external reference and then binds the external
reference to the drawing. This example uses the City map.dwg found in the
sample directory. If you do not have this image, or it is located in a different
directory, insert a valid path and file name for the PathName variable below.
Sub Ch10_BindingExternalReference()
On Error GoTo ERRORHANDLER
' Define external reference to be inserted
Dim xrefHome As AcadBlock
Dim xrefInserted As AcadExternalReference
Dim insertionPnt(0 To 2) As Double
Dim PathName As String
insertionPnt(0) = 1
insertionPnt(1) = 1
insertionPnt(2) = 0
PathName = "c:/AutoCAD/sample/City map.dwg"
' Add the external reference
Set xrefInserted = ThisDrawing.ModelSpace. _
AttachExternalReference(PathName, "XREF_IMAGE", _
insertionPnt, 1, 1, 1, 0, False)
ZoomAll
MsgBox "The external reference is attached."
' Bind the external reference definition
ThisDrawing.Blocks.Item(xrefInserted.name).Bind False
MsgBox "The external reference is bound."
Exit Sub
ERRORHANDLER:
MsgBox Err.Description
End Sub

Clip Blocks and Xrefs

There is no method provided in ActiveX Automation for clipping the
bound- aries of blocks and xrefs. Use the XCLIP command in AutoCAD, or
send the XCLIP command to AutoCAD using the SendCommand method.

Use External References

49

Demand Loading and Xref Performance

Through a combination of demand loading and saving drawings with
indexes, you can increase the performance of drawings with external references. Demand loading works in conjunction with the XLOADCTL and
INDEXCTL system variables. When you turn on demand loading, if indexes
have been saved in the referenced drawings, AutoCAD loads into memory
only the data from the reference drawing that is necessary to regenerate the
current drawing. In other words, referenced material is read in on
demand.
To realize the maximum benefits of demand loading, you need to save the
referenced drawings with layer and spatial indexes. The performance
benefits of demand loading are most noticeable when you

Clip the xref to display a small fraction of it, and a spatial index is saved
in the externally referenced drawing.
Freeze several layers of the xref, and the externally referenced drawing
is saved with a layer index.

To turn on demand loading, use the XRefDemandLoad property. If you

turn on demand loading with the acDemandLoadEnabledWithCopy option,
AutoCAD makes a temporary copy of the externally referenced file and
demand loads the temporary file. You can then demand load the xref while
allowing the original reference drawing to be available for modification.
When you disable demand loading, AutoCAD reads in the entire reference
drawing regardless of layer visibility or clip instances.
To turn on layer and spatial indexes, set the INDEXCTL system variable
using the SetVariable method. The following settings apply to the
INDEXCTL sys- tem variable:

0
1
2
3

= no indexes created
= layer index created
= spatial index created
= both spatial and layer indexes created

By default, INDEXCTL is set to 0 when you create a new AutoCAD drawing.

For more information on demand loading and xrefs, see Increase Performance with Large Xrefs in the Users Guide.

50 | Chapter 10 Advanced Drawing and Organizational

Techniques

Assign and Retrieve

Extended Data
You can use extended data (xdata) as a means for linking information with
objects in a drawing.
Assign xdata to all objects in a selection set
This example prompts the user to select objects from the drawing. The
selected objects are placed into a selection set, and the specified xdata is
attached to all objects in that selection set.
Sub Ch10_AttachXDataToSelectionSetObjects()
' Create the selection set
Dim sset As Object
Set sset = ThisDrawing.SelectionSets.Add("SS1")
' Prompt the user to select objects
sset.SelectOnScreen
' Define the xdata
Dim appName As String, xdataStr As String
appName = "MY_APP"
xdataStr = "This is some xdata"
Dim xdataType(0 To 1) As Integer
Dim xdata(0 To 1) As Variant
' Define the values for each array
'1001 indicates the appName
xdataType(0) = 1001
xdata(0) = appName
'1000 indicates a string value
xdataType(1) = 1000
xdata(1) = xdataStr
' Loop through all entities in the selection
' set and assign the xdata to each entity
Dim ent As Object
For Each ent In sset
ent.SetXData xdataType, xdata
Next ent
End Sub

View the xdata of all objects in a selection set

This example displays the xdata attached with the previous example. If you
attach xdata other than strings (type 1000), you will need to revise this
code.

Assign and Retrieve Extended

Data | 51

Sub Ch10_ViewXData()
' Find the selection created in previous example
Dim sset As Object
Set sset = ThisDrawing.SelectionSets.Item("SS1")
' Define the xdata variables to hold xdata information
Dim xdataType As Variant
Dim xdata As Variant
Dim xd As Variant
'Define index counter
Dim xdi As Integer
xdi = 0
' Loop through the objects in the selection set
' and retrieve the xdata for the object
Dim msgstr As String
Dim appName As String
Dim ent As AcadEntity
appName = "MY_APP"
For Each ent In sset
msgstr = ""
xdi = 0
' Retrieve the appName xdata type and value
ent.GetXData appName, xdataType, xdata
' If the xdataType variable is not initialized, there
' was no appName xdata to retrieve for that entity
If VarType(xdataType) <> vbEmpty Then
For Each xd In xdata
msgstr = msgstr & vbCrLf & xdataType(xdi) _
& ": " & xd
xdi = xdi + 1
Next xd
End If
' If the msgstr variable is NULL, there was no xdata
If msgstr = "" Then msgstr = vbCrLf & "NONE"
MsgBox appName & " xdata on " & ent.ObjectName & _
":" & vbCrLf & msgstr
Next ent
End Sub

52 | Chapter 10 Advanced Drawing and Organizational

Techniques

Develop Applications
with VBA

Many programming tasks involve more than simply

In this chapter

working with the AutoCAD ActiveX object model.

More VBA Terminology

This chapter provides a brief overview of creating

dialog boxes, handling errors, controlling window
focus, and distributing your application to others.
Remember, the Microsoft documentation for VBA
contains more information on these topics.

Forms in VBA
Handle Errors
Encrypt VBA Code

Modules
Run a VBA Macro from a

Toolbar or Menu
Automatically Load a

VBA Project
Automatically Run a

VBA Macro
Automatically Open the

VBA IDE Whenever a

Project Is Loaded
Work in a Zero

Document
State

Distribute Your

Application

309

More VBA Terminology

This chapter expands your exposure to VBA. The following terms will
help you understand and work within the VBA environment.
Project

A set of forms and modules grouped together in a single

file.

Module

A group of (usually related) subroutines and functions.

Macro

A public subroutine or function. Macros are exposed to

the user as an executable component of your project.

Dialog box

A means by which information is displayed or

gathered during application execution.

Form

Container for dialog box controls.

Forms in VBA
Forms are the basic building blocks through which you create your own
custom dialog boxes for your application. Through custom forms you can
provide information to users, get information from users, or have your users
control activity in the application.
Forms are like an artists canvasthey start out blank. To fill your canvas, you
need a palette. In this case, your palette is the control toolbox. You, as the
artist, place selected controls from the toolbox onto the form. You can add
as many controls as you like. At any time you can adjust size and properties
of both the controls and even the form itself. Finally, you add the
functionality (code) to the controls that brings your form to life.

54 | Chapter 11 Develop Applications with

VBA

Although Visual Basic supports different types of forms, VBA supports only
the UserForm. This means some forms have been created and exported in
Visual Basic that cannot be imported into VBA.
UserFormsor forms, as they are called in this guidecan be modal or
mod- eless. The ShowModal property of a form determines whether it is
modal or modeless. Modal forms displayed in your running application
must be closed before users can perform any other action in the application.
For more infor- mation about working with modal forms, see Modal
Forms on page 315.
To create a new form in your project
1 Open the Project window of the VBA IDE and select the project you want
to add the form to.
2 From the Insert menu, choose UserForm.
A blank form is created and added to your project.
To create a modeless form in your project
1 Open the Project window of the VBA IDE and select the project you want
to add the form to.
2 From the Insert menu, choose UserForm, and change the
ShowModal property to False.
3 Add the AcFocusCtrl (AcFocusCtrl.dll) to the Toolbox, and drag the
control onto the form.
The AcFocusCtrl keeps the focus on the form during user interaction.

Design
Mode

and

Run

While you are building your form you are working in design mode, where
you can

Add controls to the

form

Change the

properties of the

form

Change the properties of controls on the

form
Add code
module

to the

form

While in design mode there is no interaction among the user, the user interface of AutoCAD, and your form.
Once you run your application, or your user runs your application, the form
is then in run mode. While in run mode you cannot make adjustments to the

Forms in VBA
55

form directly. However, the form is now displayed in the AutoCAD user
inter- face and the user can interact with the form as part of the normal
operation of your application.

56 | Chapter 11 Develop Applications with

VBA

Add Controls to a
Form
Adding controls to a form is easy. Simply select a control from the control
toolbox and drag it over to the form. When you release your mouse, a copy
of the control will be placed on the form. Once the control is on the form,
you can change the position and size of the control. You can copy over as
many controls as you like.
In addition to the drag method previously mentioned, there are other ways
of placing controls on a form.

Change the Size and Placement of a

Control
To move a control, simply select it and drag it to its new position on the
form.
To resize a control, first select the control by clicking on it once. When you
select a control its border becomes visible. To resize the control, simply
select one of the sizing grips now visible on the border and drag the grip to
a new position. When you release the grip, the control will resize to that
location. (You can resize the form in the same manner.)
To move or resize several controls at once, select each control while
holding down the SHIFT key. This will highlight all the controls. You can
now move or resize the controls as a group.
To size a control as you place it
1 Select the desired control in the control toolbox.
2 On the form, press, drag, and release the mouse button. The selected control will be placed on the form. The size of the control depends on how
far you drag the mouse.
To place several instances of the same control
1 In the control toolbox, double-click on the control you want to
place.
2 On the form, click at the location you want a copy of the control placed.
Move to another location on the form and click again. Another copy of
the control will appear. You can add as many copies of the control as you
need.
3 When you are finished with the control, return to the control toolbox
and click the control one more time to deselect it.

Forms in VBA
57

Use Formatting Controls

VBA provides several formatting controls to help you lay out your form.
These controls can be found on the Format menu of the VBA IDE. These controls allow you to align controls to each other, make two or more controls the
same size, change the spacing between controls, and center controls on the
form.
Remember when using the formatting controls that several controls can be
selected at once by using SHIFT .

Change the Properties of a Control

Properties control various characteristics of a control such as its size, shape,
color, label, and default values. You can set the properties of a control in
design mode by using the Properties window.
To change the property of a control
1 On the form, select the desired control.
2 Open the Properties window using F4 if it is not already open.
3 In the Properties window, find the property you want to change and select
the current value for that property.
4 Change the value to the new desired value for the property.
You can also change the property of a control at runtime by writing code to
access that property. See the
Microsoft documentation for more
information on changing the property of a control at runtime.

Add Code to a Control

Now that you have your form looking the way you want, its time to add
some code behind your controls. To open the Code window for a control
simply double-click on the control in the Form window. The Code window
will open, with a subroutine created for that control and its default event.
You can add code to the default event, or choose a different event from the
event drop-down list at the top-right corner of the Code window.

Display and Hide Forms

Now you have a beautifully designed form with fully functional code behind
all the controls. The last step is getting the form displayed to the user at runtime. Displaying the form is accomplished through the VBA Show method.
The Show method can be called from any code module in your application.

58 | Chapter 11 Develop Applications with

VBA

The form you created is modal by default, so the user will not be able to
inter- act with AutoCAD directly while the form is displayed. For example,
the user cannot select a point or object in the drawing with the form
displayed. To allow the user access to the AutoCAD drawing, use the VBA
Hide method. The Hide method hides the form and allows the user limited
access to AutoCAD. When using the Hide method it is important to
remember the form is not unloaded from memory. It will retain all current
values while hidden.
The Hide method is called in the same manner as the Show method.
Display a form
This example will display the form named UserForm1:
Public Sub MyApplication()
UserForm1.Show
End Sub

The subroutine (and consequently the display of your form) is now callable
as a macro from the VBARUN command or from an AutoCAD menu.
Hide a form
This example hides the form named UserForm1:
Public Sub MyAppHide()
UserForm1.Hide
End Sub

Load and Unload Forms

There may be times when you want to load a form into memory during
run- time, but not show the form. You may choose to do this to better
control when the load time occurs in your application, or when you need
program- matic access to the form but do not want to display the form to
the user.
To load a form, but not display it, use the VBA Load method. The Show
method can then be used to make the form visible at the appropriate time in
your applications execution. Remember, the user cant interact with your
form until it is visible.
If the Show method is called and the form has not been loaded, it will be
loaded automatically.
There may also be times when you will want to unload a form specifically.
Unloading a form removes that form from memory and all the memory
associated with the form is reclaimed. Until the form is loaded again by
using either the Load or Show method, a user cant interact with the form,
and the

Forms in VBA
59

form cant be manipulated programmatically. You may choose to unload a

form when you know the form will not be used again in the application
and you want to reclaim the memory.
The Hide method does not perform an unload. If your application ends and
a form has not been unloaded, it will be unloaded automatically. The
follow- ing table compares the VBA Show, Hide, Load, and Unload
methods:
VBA Show, Hide, Load, and Unload methods
Method

Use

Show

Displays a form. If the form has not been loaded, it is loaded

automatically.

Hide

Hides a form. The form is not unloaded from memory.

Load

Loads a form into memory but does not display it.

Unload

Unloads a form from memory. This can be done explicitly from the
Unload method, or automatically at the termination of the
application.

Modal Forms
When you define a dialog box as modal in AutoCAD VBA, the user must
respond to the dialog box before any other part of the application is
allowed to continue. No subsequent code is executed until the modal
dialog box is closed through either the Hide or Unload method. This
requires that you, as the developer of the application, think carefully about
how and when you implement dialog boxes.
For example, you may have a dialog box that requires the user to select an
object in the AutoCAD drawing. For the user to be able to pick the object
from the AutoCAD Application window you must hide the form by calling
the Hide method. Once the object has been selected you use the Show
method to redisplay the form, with all of its data still current, and
continue with the application.

Note Although other forms in the application are disabled when a modal
dialog box is displayed, other applications are not.

60 | Chapter 11 Develop Applications with

VBA

Handle Errors
Most development environments provide default error handling. For VB and
VBA, the default reaction to an error is to display an error message and
terminate the application. While this behavior is adequate during the development phase of your application, it is not productive for your end-user.
There may be errors that you want to ignore, or that you want to provide
special responses to. There may be errors that you will want to suppress the
error message display for, or simply control the message that gets displayed
to the user. In addition, automatically terminating the application is hardly
ever acceptable to the end-user.
In general, error handling is necessary whenever user-input is required and
whenever working with file I/O. Remember, even if you are sure a needed
file is there and available for processing, there may be conditions you
havent thought of that could cause errors.

Note Most of the code examples provided in the AutoCAD documentation

do not use error trapping. This keeps the examples simple and to the point.
How- ever, as with all programming languages, proper error trapping and
handling is essential for a robust application.

Define Application Error

Types
There are three different types of errors you can encounter in your applications: compile-time errors, runtime errors, and logic errors.
Compile-time errors occur during the construction of your
application.
These errors consist mostly of syntax mistakes, variable scoping
problems, or data typing problems. In VBA, these types of errors are
caught by the development environment. When you enter an incorrect
line of code, the line is highlighted and an error message appears telling
you the problem. Compile-time errors must be corrected before the
application can run.
Runtime errors are a little more difficult to find and correct. They occur
during the execution of your code, and often involve receiving information from the user. For example, if your application requires the user to
enter the name of a drawing and the user enters a name for a drawing
that didnt exist, a runtime error occurs. To handle runtime errors
effectively, you must predict what kinds of problems could happen, trap
them, and then write code to handle these situations.

Forms in VBA
61

Logic errors are the most difficult to find and correct. Symptoms of logic
errors include situations in which there are no compile-time errors and
no runtime errors, but the outcome of your program is still incorrect.
This is what programmers refer to as a bugand a bug can be very easy
or very difficult to track down.

Information on finding and correcting all three types of errors can be

found in documentation for your development environment. AutoCADspecific errors fall into the runtime error category, so these types of errors
will be covered more fully in this documentation.

Trap Runtime Errors

In VB and VBA, runtime errors are trapped using the On Error statement.
This statement literally sets a trap for the system. When an error occurs, this
statement automatically detours processing to your specially written error
handler. The default error handling for the system is bypassed.
The On Error statement has three forms:

On Error Resume Next

On Error GoTo Label
On Error GoTo 0

The On Error Resume Next statement is used when you want to ignore
errors. This statement traps the error and instead of displaying an error
message and terminating the program, it simply moves on to the next line
of code and continues processing. For example, if you wanted to create a
sub- routine to iterate through model space and change the color of each
entity, you know that AutoCAD will throw an error if you try to color an
entity on a locked layer. Instead of terminating the program, simply skip
the entity on the locked layer and continue processing the remaining
entities. The On Error Resume Next statement lets you do just that.
The On Error GoTo Label statement is used when you want to write an
explicit error handler. This statement traps the error and instead of displaying an error message and terminating the program, it jumps to a specific
location in your code. Your code can then respond to the error in whatever
manner is appropriate for your application. For example, you can expand the
example above to display a message containing the handle for each entity
on the locked layer.

Handle Errors
61

Handle errors with the On Error Resume Next statement

The following subroutine iterates model space and changes the color of
each entity to red. Try running this subroutine on a drawing with several
entities, some of which are on a locked layer. Next, comment out the On
Error Resume Next statement and run the subroutine again. You will
notice the subroutine terminates at the first entity on the locked layer.
Sub Ch11_ColorEntities()
Dim entry As Object
On Error Resume Next
For Each entry In ThisDrawing.ModelSpace
entry.Color = acRed
Next entry
End Sub

Handle errors with the On Error GoTo statement

The following subroutine iterates model space and changes the color of
each entity to red. For each entity on the locked layer, the error handler
displays a custom error message and the handle of the entity. Try running
this sub- routine on a drawing with several entities, some of which are on a
locked layer. Next, comment out the On Error GoTo MyErrorHandling
statement and run the subroutine again. You will notice the subroutine
terminates at the first entity on the locked layer.
Sub Ch11_ColorEntities2()
Dim entry As Object
On Error GoTo MyErrorHandler
For Each entry In ThisDrawing.ModelSpace
entry.Color = acRed
Next entry
' Important! Exit the subroutine before the error handler
Exit Sub
MyErrorHandler:
Msgbox entry.EntityName + " is on a locked layer." + _
" The handle is: " + entry.Handle
Resume Next
End Sub

The On Error GoTo 0 statement cancels the current error handler. The On
Error Resume Next and On Error GoTo Label statements remain in effect
until the subroutine ends, another error handler is declared, or the error
han- dler is canceled with the On Error GoTo 0 statement.

62 | Chapter 11 Develop Applications with

VBA

Respond to Trapped Errors

Now that you have trapped an error, what do you do with it? The answer
depends on the nature of your application and the nature of the error.
VB and VBA provide information on the type of error that has been trapped by
using the Err object. This object has several properties: Number, Description,
Source, HelpFile, HelpContext, and LastDLLError. The properties of the Err
object get filled in with the information for the most current error. The
most important properties are the Number and Description properties. The
Num- ber property contains the unique error code associated with the
error, and the Description property contains the error message that would
normally be displayed.
In your error handler you can compare the Number property of the error to
an expected value. This will help you determine the nature of the error that
has occurred. Once you know what kind of error you are dealing with, you
can take the appropriate action.

Respond to AutoCAD User Input Errors

The user-input methods provide a certain amount of inherent error trapping
in that they require the user to enter a certain type of data. If the user tries to
enter some other data, AutoCAD rejects the input and reprompts the user.
Using the InitializeUserInput method with the user input functions provides
additional control of the user input but can also introduce additional conditions that must be verified through error trapping. For an example of error
trapping that is required with certain types of user-input, see Prompt for
User Input on page 73.

Encrypt VBA Code Modules

Although VBA does not support creation of executables, it does offer password protection for the visibility of the project forms, classes, and modules
on a project basis. You can find this Project Protection facility in the VBA
IDE
menu. Choose Tools Project Properties Protection.

Encrypt VBA Code Modules

63

Run a VBA Macro from a Toolbar or

Menu
You can run a VBA macro from an AutoCAD toolbar or menu by simply
changing the Macro property for that toolbar or menu. The Macro
property must be set equal to
-VBARUN filename.dvb!modulename.macroname

where filename is the name of the project file, modulename is the name of the
module containing the macro to be run, and macroname is the name of the
macro. The file name is only required when the file is not loaded in the current session of AutoCAD. If the file name is provided, the file will be loaded.
For more information on editing menus and toolbars, see Customize Toolbars and Menus.

Automatically Load a VBA Project

There are two different ways to load a VBA project automatically:

When VBA is loaded it will look in the AutoCAD directory for a

project named acad.dvb. This file will automatically load as the default
project
Any project other than the default, acad.dvb, can be used by explicitly
loading that project at startup using the VBALOAD command. The following code sample uses the AutoLISP startup file to load VBA and a VBA
project named myproj.dvb when AutoCAD is started. Start notepad.exe and
create (or append to) acad.lsp the following lines:
(defun S::STARTUP()
(command "_VBALOAD" "myproj.dvb")
)

Automatically Run a VBA Macro

You can automatically run any macro in the acad.dvb file by calling it with
the command line version of VBARUN from an AutoCAD startup facility like
acad.lsp. For example, to automatically run the macro named drawline, first
save the drawline macro in the acad.dvb file. Next, invoke notepad.exe and
create (or append to) acad.lsp the following lines:
(defun S::STARTUP()
(command "_-vbarun" "drawline")
)

64 | Chapter 11 Develop Applications with

VBA

You can cause a macro to run automatically when VBA loads by naming the
macro AcadStartup. Any macro in your acad.dvb file called AcadStartup
will automatically get executed when VBA loads.

Automatically Open the VBA IDE

Whenever a Project Is Loaded
There is an option on the Open VBA Project dialog box that allows you to
open the IDE automatically. Simply check the box Open Visual Basic
Editor found in the lower-left side of the dialog box and the VBA IDE will
open auto- matically whenever a VBA project is loaded. This option will
remain set until you turn it off again.

Note To access the Open VBA Project dialog box, enter VBALOAD at the
com- mand line. The dialog box will open and allow you to choose a project to
load. If you do not see the Open VBA Project dialog box, it is most likely
because the system variable FILEDIA is turned off. This system variable turns on
and off the display of dialog boxes. To turn FILEDIA back on, set it to 1.

Work in a Zero Document State

A zero document state is when there are no open drawings in AutoCAD.
There are several important considerations to keep in mind when you are
working with VBA in a zero document state:

The ThisDrawing object is undefined in a zero document state.

Any attempt to use ThisDrawing will result in an error.
Objects that are document dependent are also not defined in a zero
docu- ment state. Document dependent objects are those objects that fall
below the Document object in the AutoCAD object model. Working
with non- document dependent objects, such as the Application or
MenuBar objects, is allowed.
AutoCAD does not have a command line in a zero document state. Any
attempt to access the AutoCAD command line while AutoCAD is in a zero
document state will result in an error.

Automatically Open the VBA IDE Whenever a Project Is

Loaded | 65

Distribute Your Application

VBA applications can be distributed two different ways:

Embedded in an AutoCAD drawing

Stored in a VBA project file

You must choose a distribution option that is appropriate for your application. Applications that are applicable to the current drawing, and do not
access other drawings, are often embedded in the drawing. By embedding
the application in the drawing, you can always be sure the application is
loaded, and therefore available to the user whenever the drawing is open.
Applications that are used by many people, are updated frequently, need to
open and close other drawings, or are not used frequently you may want to
store in a VBA project file. In this way, there is one central location for the
application, and everyone can be sure to use the latest version.
For more information on embedded projects and VBA project files, see
Understand Embedded and Global VBA Projects on page 12.

Distribute Visual Basic Applications

Visual Basic applications, or any other out-of-process application, cannot be
stored within an AutoCAD drawing. These applications are compiled into
standalone executables (EXEs).

66 | Chapter 11 Develop Applications with

VBA

Interact with Other

Applications and
Windows APIs
ActiveX technology allows you to exchange informa-

In this chapter

tion easily with other AutoCAD applications and

Interact with Visual

other ActiveX-enabled applications such as Microsoft

Interact with Other

Excel or Microsoft Word. This chapter examines some

Windows
Applications

of the

Access Windows APIs

basic procedures for interacting with other applications.

from
VBA

LISP Applications

323

Interact with Visual LISP Applications

Visual LISP applications have access to the entire range of ActiveX objects.
They can call ActiveX methods, and set and retrieve ActiveX properties. In
addition, Visual LISP applications can also run VBA macros through the
VBARUN command.
ActiveX and VBA applications can execute Visual LISP applications through
the SendCommand method. This method allows ActiveX and VBA
applica- tions to send a command to the AutoCAD command line.
For more information about accessing ActiveX objects through Visual
LISP, see the AutoLISP Developers Guide.

Interact with Other Windows

Applications
AutoCAD ActiveX technology allows you to exchange information easily
with other ActiveX-enabled applications such as Microsoft Excel or Microsoft
Word. This capability allows you to collect, store, and present AutoCAD
information in formats other than the AutoCAD drawing. You can also read
information from these applications back into AutoCAD to direct the
creation or manipulation of AutoCAD objects. An example of using this
tech- nology is to create a bill of materials as a Microsoft Excel spreadsheet
from the objects in an AutoCAD drawing.
You have already learned how to write code using the AutoCAD ActiveX
Object Model. Exchanging information with other ActiveX-enabled applications involves simply referencing the other applications ActiveX Object
Model and writing the code necessary to utilize their objects.

Note This chapter provides only a brief introduction to the capabilities of

cross- application programming. This material is not AutoCAD specific, and as
such it is discussed in both Microsoft documentation and independent
programming guides.
To exchange information across ActiveX Object Models
1 Reference the other applications ActiveX Object Model.
This will make your code aware of the names and relationships of the
objects in the other Object Model.

68 | Chapter 12 Interact with Other Applications and

Windows APIs

2 Create an instance of the other application.

This will create (instantiate) valid objects for the basic objects in the other
Object Model.
3 Write your code utilizing both the AutoCAD Object Model and the
other applications Object Model.
This is where the exchange of data takes place.

Reference the ActiveX Object Library of

Other
Applications
To write code that accesses another application, you must instruct VBA to
make the objects in the other application available to you. You do this by setting a reference in the other applications object library. This is a file on your
computer where all the objects, methods, properties, constants, and events
for that application are defined.
You make a reference to an object library through the VBA IDE. In the VBA
IDE, under the Tools menu, there is a menu option called References. This
menu option will bring up a dialog box that lists all of the object libraries
VBA finds on your system. To make a reference to a library, simply select the
library from the list. Libraries with check boxes that are selected are already
referenced in the current project. For example, to add the Microsoft Excel
object library, select the Microsoft Excel object library entry in the list.
Once you have created a reference to another applications object library,
you can use the VBA Object Browser to view a list of the applications
objects.

Note You must set the reference for each VBA project that will use this
Object Model. Setting the reference for one project wont automatically set it
for another project. This is for performance reasons.
To make a reference to another applications object library
1 In the VBA IDE, open the Tools menu and select the References menu
option.
2 Find and select the entry in the list of Available References for the application you want to access.
3 Select OK to close the dialog box with your changes.

Interact with Other Windows Applications

| 69

Create an Instance of the Other

Application
Once you have referenced an applications object library you must create an
instance of the application. This is just a fancy way of saying you need to
start the other application programmatically so your code will have valid
objects to work with.
To do this, first declare a variable that will represent the other application.
You do this the same way as built-in objects, by using a Dim statement.
You should qualify the type of application in your Dim statement. For
example, this
Dim statement declares an object variable of type
Excel.Application:
Dim ExcelAppObj as Excel.Application

After you declare the variable, use the Set statement with the New keyword
to set the variable equal to a running instance of the application. For example, the following Set statement sets the variable declared above equal to
the Excel application. The New keyword starts a new session of Excel.
Set ExcelAppObj = New Excel.Application

Note Some applications allow only one running instance of the application
at a time. Using the New keyword on such an application will establish a
reference to the existing instance and will not launch a new session of the
application.

Program with
Applications

Objects

from

Other

Now that you have referenced the object library and created a new instance
of the application, you can create and manipulate objects in that
application. All the objects, methods, and properties defined by the Object
Model are available to you. For example, using the variable declarations from
the previ- ous section, the following line of code makes the Excel session
visible to the user:
ExcelAppObj.Visible = TRUE

You should familiarize yourself with the Object Model of the application
you are writing code for. You can use the VBA Object Browser or the
applications help file to learn about any Object Model you are referencing.

70 | Chapter 12 Interact with Other Applications and

Windows APIs

Quit the Other Application

When you start an application programmatically it takes up memory in the
computer. You should quit the application when you have finished using it
so system resources can be freed up.
Although each Object Model is different, most have a Quit method from the
Application object that can be used to close the application cleanly. For
example, using the variable declarations from the previous section, the
following line of code will quit Excel:
ExcelAppObj.Application.Quit

Note Destroying or going beyond the scope of the object variable does not
necessarily cause the application to terminate. You should always quit the application using the appropriate method to assure proper memory cleanup.
List AutoCAD attributes on an Excel spreadsheet
This subroutine finds all the block references in the current drawing. It then
finds the attributes attached to those block references and lists them in an
Excel spreadsheet. To run this example, do the following:
1 Open a drawing containing block references with attributes. (The
sample drawing sample/activeX/attrib.dwg contains such block references.)
2 Open the VBA IDE using the AutoCAD VBAIDE command.
3 Using the Tools References menu option in the VBA IDE, select
Microsoft Excel 8.0 Object Model.
4 Copy this subroutine into a VBA Code window and run it.

Interact with Other Windows Applications

| 71

Sub Ch12_Extract()
Dim Excel As Excel.Application
Dim ExcelSheet As Object
Dim ExcelWorkbook As Object
Dim
Dim
Dim
Dim
Dim

RowNum As Integer
Header As Boolean
elem As AcadEntity
Array1 As Variant
Count As Integer

' Launch Excel.

Set Excel = New Excel.Application
' Create a new workbook and find the active sheet.
Set ExcelWorkbook = Excel.Workbooks.Add
Set ExcelSheet = Excel.ActiveSheet
ExcelWorkbook.SaveAs "Attribute.xls"
RowNum = 1
Header = False
' Iterate through model space finding
' all block references.
For Each elem In ThisDrawing.ModelSpace
With elem
' When a block reference has been found,
' check it for attributes
If StrComp(.EntityName, "AcDbBlockReference", 1) _
= 0 Then
If .HasAttributes Then
' Get the attributes
Array1 = .GetAttributes
' Copy the Tagstrings for the
' Attributes into Excel
For Count = LBound(Array1) To UBound(Array1)
If Header = False Then
If StrComp(Array1(Count).EntityName, _
"AcDbAttribute", 1) = 0 Then
ExcelSheet.Cells(RowNum, _
Count + 1).value = _
Array1(Count).TagString
End If
End If
Next Count
RowNum = RowNum + 1
For Count = LBound(Array1) To UBound(Array1)
ExcelSheet.Cells(RowNum, Count + 1).value _
= Array1(Count).textString
Next Count
Header = True
End If
End If
End With
Next elem
Excel.Application.Quit
End Sub

72 | Chapter 12 Interact with Other Applications and

Windows APIs

Access Windows APIs from VBA

The Windows API procedures are available to most Windows
applications. These procedures allow you to expand the capabilities of your
application.
Through the Windows APIs you can obtain information about the current
system, such as which other programs are installed or running on the
system, where information is located on a system, and what the current
control settings are for the system. You can also access joystick, multimedia,
and sound controls. These tasks represent but a few of the many capabilities
pro- vided by the Windows APIs.
To use a Windows API, you must first declare the API in your application.
This is done through the Visual Basic Declare statement. The Declare statement requires several pieces of information:

The name of the dynamic link library (DLL) containing the procedure
you want to use
The name of the procedure as it appears in the DLL
The name of the procedure as you want to use it in your application
The parameters the procedure expects to receive
The return value data type (if the procedure you are calling is a function)

You can place the Declare statement in any of your VBA modules. If you
place it in a standard module, the procedure will be available to any module
in your application, unless you limit its scope by using the keyword Private.
If you place the Declare statement in a class or form module, the
procedure will only be available in that module. Once a procedure has been
declared, you can call that procedure as you would any other procedure in
your application.
Getting a Declare statement just right is a difficult skill to learn. Getting a
Declare statement wrong is easy, but it often comes with dire
consequences. Be sure to save any information in active applications before
you try out a new Declare statement.
To help you with your Declare statements, Microsoft provides a file listing
of many of the declarations most commonly used. The file is called
Win32api.txt and comes with Visual Basic and Office. You can search this
file for the procedure you need and copy the Declare statement provided
into your code.

Access Windows APIs from VBA

73

The Microsoft VBA documentation contains more information on the

Declare statement and an example of its use. The Microsoft Windows API
Reference is available as part of the Microsoft Developer Network CD subscription and provides a reference to all the available procedures in the
Windows APIs. Dan Applemans book Visual Basic Programmers Guide to the
Win32 API is also an excellent resource directed at the Visual Basic
programmer.

74 | Chapter 12 Interact with Other Applications and

Windows APIs

Design the Garden

PathAn
ActiveX/VBA
Tutorial
This tutorial demonstrates how to use ActiveX and

In this chapter

Visual Basic for Applications (VBA) and how to add a

Check Your

Environment

macro to AutoCAD . The tutorial is oriented towards

Define the Goal

landscape architecture, but the concepts in the tutorial

Write the First Function

are relevant to any application area.

This tutorial is designed for the proficient AutoCAD
user who is a novice VBA programmer.

Get Input
Draw the Path Outline
Draw the Tiles
Tie It All Together
Step Through the Code
Execute the Macro
Add a Dialog Box

Interface

331

Check Your Environment

For the tutorial, you need the AutoCAD VBA integrated development environment (VBA IDE). The VBA IDE is installed automatically with both the
standard and full options of the AutoCAD installation program. If you
selected the custom option when you installed AutoCAD, the VBA IDE
might not be installed; you might need to install it by running the
AutoCAD instal- lation program again.
To test if the VBA IDE is installed
1 Start AutoCAD.
2 On the command line, enter vbaide, and press ENTER.
If the VBA IDE opens, the VBA IDE is installed. If you receive the message
AutoCAD VBA is not currently installed, the VBA IDE is not installed.

Define the Goal

Your goal in this tutorial is to develop a new macro for AutoCAD that draws
a garden path and fills it with circular concrete tiles. Your new macro will
have the following prompt sequence:
Command: gardenpath
Start point of path: The user will specify the start point
Endpoint of path: The user will specify the endpoint
Half width of path: The user will specify a number
Radius of tiles: The user will specify a number
Spacing between tiles: The user will specify a number
Your macro will first prompt the user to enter the start point and endpoint
to specify the centerline of a path. Next, it will prompt the user to enter the
half width of the path and the radius of the circular tiles. Finally, the user
will enter the spacing between the tiles. You are using the half width of the
path rather than the full width because it is easier to visualize the half width
from the centerline of the path.

76 | Chapter 13 Design the Garden PathAn ActiveX/VBA

Tutorial

Write the First

Function
You develop the Gardenpath macro using a series of functions and subroutines. Many subroutines require the manipulation of angles. Because ActiveX
specifies angles in radians, but most users think of angles in terms of
degrees, begin by creating a function that converts degrees to radians.
To convert degrees to radians
1 On the command line, enter vbaide, and press ENTER.
2 In the VBA IDE, on the View menu, click Code to open the Code window.
3 Enter the following code in the Code window:
Const pi = 3.14159
' Convert angle in degrees to radians
Function dtr(a As Double) As Double
dtr = (a / 180) * pi
End Function

Notice that as soon as you press ENTER after entering the line Function
dtr(a As Double) As Double, End Function is added automatically.
This ensures that all subroutines and functions have an associated End
state- ment.
Now look at the code. First, the constant pi is defined as the value
3.14159. This allows you to use the word pi instead of typing 3.14159
each time you need to use the value.
Next, you are defining a function called dtr (short for degrees to
radians). The function dtr takes one argument, a, which is the angle in
degrees. The result is obtained by dividing the angle in degrees by 180,
and then mul- tiplying this value by pi. The line that begins with a single
quote is a com- ment; VBA ignores all text on a line after a single quote.
This function can now be used in other subroutines throughout your
project.
4 Save your work. Click File Save Global1. Name the project gardenpath.dvb.
Next, add a function to calculate the distance between points.

Write the First Function

77

To calculate the distance between two points

1 Enter the following code after the dtr function:
' Calculate distance between two points
Function distance(sp As Variant, ep As Variant) _
As Double
Dim x As Double
Dim y As Double
Dim z As Double
x = sp(0) - ep(0)
y = sp(1) - ep(1)
z = sp(2) - ep(2)
distance = Sqr((Sqr((x ^ 2) + (y ^ 2)) ^ 2) + (z ^ 2))
End Function

2 Save your work.

Get Input
The Gardenpath macro asks the user where to draw the path, how wide to
make the path, how large the concrete tiles are, and how closely to space
those tiles. You define a subroutine that asks the user for all of these
items and then computes various numbers to use in the rest of the macro.
In this subroutine, you use the user input methods found in the Utility
object.

Declare Variables
The next subroutine uses several variables. All variables must be declared
before the subroutine can access them.
In the VBA IDE, enter the following code in the Code window,
immediately after the line Const pi = 3.14159:
Private
Private
Private
Private
Private
Private
Private
Private
Private
Private

sp(0 To 2) As Double
ep(0 To 2) As Double
hwidth As Double
trad As Double
tspac As Double
pangle As Double
plength As Double
totalwidth As Double
angp90 As Double
angm90 As Double

78 | Chapter 13 Design the Garden PathAn ActiveX/VBA

Tutorial

Now look at the two drop-down lists at the top of the Code window. These
lists are called the Object Box and the Procedure/Event Box and currently
dis- play the terms (General) and (Declarations), respectively. These lists
display the current section of the code you are working in, and enable you
to move quickly to a different section by simply selecting one from the list.
The (Dec- larations) section is the appropriate place to declare variables that
you will use in more than one subroutine.

Enter the gpuser Subroutine

The gpuser subroutine prompts the user for information necessary for drawing a garden path. Enter the following code after the distance function:
' Acquire information for garden path
Private Sub gpuser()
Dim varRet As Variant
varRet = ThisDrawing.Utility.GetPoint( _
, "Start point of path: ")
sp(0) = varRet(0)
sp(1) = varRet(1)
sp(2) = varRet(2)
varRet = ThisDrawing.Utility.GetPoint( _
, "Endpoint of path: ")
ep(0) = varRet(0)
ep(1) = varRet(1)
ep(2) = varRet(2)
hwidth = ThisDrawing.Utility. _
GetDistance(sp, "Half width of path: ")
trad = ThisDrawing.Utility. _
GetDistance(sp, "Radius of tiles: ")
tspac = ThisDrawing.Utility. _
GetDistance(sp, "Spacing between tiles: ")
pangle = ThisDrawing.Utility.AngleFromXAxis( _
sp, ep)
totalwidth = 2 * hwidth
plength = distance(sp, ep)
angp90 = pangle + dtr(90)
angm90 = pangle - dtr(90)
End Sub

In the gpuser subroutine, the line Dim varRet As Variant declares the
vari- able varRet. Because this variable is used only in this subroutine, it can
be declared here locally, instead of in the (Declarations) section.

Get Input
79

The next line, varRet = ThisDrawing.Utility.GetPoint( , "Start point

of path: "), calls the GetPoint method. The underscore in the line is
intended to make a long line easier to read, and tells VBA to read the next
line as if it were on the same line. You can remove the underscore by
placing the code all on one line.
To access the GetPoint method, you must first go through the
ThisDrawing object that represents the current drawing. After entering
ThisDrawing you enter a period (.), which means that you are going to
access something within that object. After you type the period, you enter
Utility and another period. Once again, you are going to access
something within the Utility object. Finally, enter GetPoint, which is the
name of the method you are calling.
The GetPoint method takes two parameters. The first parameter is optional
and wont be used. Leave the parameter blank and simply type a comma to
mark its spot. The second parameter is the prompt, which is also optional.
For this parameter, you entered a string prompting the user to enter the
start point. The point the user enters is put into the varRet variable. The
next three lines of the subroutine copy the point returned by the user into
the sp array.
The endpoint is returned in the same manner.
The GetDistance method is used to obtain the half width of the path
(hwidth), the tile radius (trad), and the spacing between the tiles (tspac). The
GetDistance method takes two parameters. The first parameter is a base
point. For this value, you supply the start point. The second parameter is the
prompt, for which you provide a string prompting the user for the appropriate input. The interesting thing about the GetDistance method is that it can
return either a value entered on the command line or the distance between
a point selected in AutoCAD and the start point.

80 | Chapter 13 Design the Garden PathAn ActiveX/VBA

Tutorial

The subroutine goes on to calculate several variables used later in the

macro. The pangle variable is set to the angle from the start point to the
endpoint and is found by using the AngleFromXAxis method. The width of
the path is found by multiplying the half width by two. The plength
variable is set to the length of the path and is found using the distance
function you entered earlier. Finally, calculate and save the angle of the
path plus and minus 90 degrees in angp90 and angm90, respectively.
The following illustration shows how the variables obtained by gpuser
spec- ify the dimensions of the path.

Save your work.

Get Input
81

Draw the Path Outline

Now that you have acquired the location and width of the path, you can
draw its outline. Add the following code below the gpuser subroutine:
' Draw outline of path
Private Sub drawout()
Dim points(0 To 9) As Double
Dim pline As AcadLWPolyline
Dim varRet As Variant
varRet = ThisDrawing.Utility.PolarPoint(
sp, angm90, hwidth)
points(0) = varRet(0)
points(1) = varRet(1)
points(8) = varRet(0)
points(9) = varRet(1)
varRet = ThisDrawing.Utility.PolarPoint(
varRet, pangle, plength)
points(2) = varRet(0)
points(3) = varRet(1)
varRet = ThisDrawing.Utility.PolarPoint(
varRet, angp90, totalwidth)
points(4) = varRet(0)
points(5) = varRet(1)
varRet = ThisDrawing.Utility.PolarPoint(
varRet, pangle + dtr(180), plength)
points(6) = varRet(0)
points(7) = varRet(1)
Set pline = ThisDrawing.ModelSpace. _
AddLightWeightPolyline(points)
End Sub

This subroutine draws the outline of the path using the

AddLightweightPolyline method. This method takes one parameter: an array
of points that make up the polyline. You must find all the points that
make up the polyline object and place them into an array in the order they
are to be drawn. For this polyline, the points needed are the corners of the
path.

82 | Chapter 13 Design the Garden PathAn ActiveX/VBA

Tutorial

To find the corners of the path, use the PolarPoint method. This method
finds a point that is a given angle and distance from a base point. Begin
with the start point (sp) and find the first corner of the path, working in a
coun- terclockwise direction. This corner will be at a distance of half the
width of the path (hwidth) and at 90 degrees from the path angle. Because
you want to draw a closed rectangle for the path, this point becomes the
first and last point in the array. Hence, the X and Y coordinates returned
from the PolarPoint method are moved into the first and last positions in
the points array.
The remaining corners of the path are found in the same manner using the
length and width of the path (plength and width), and the angle of the
path. Every time the PolarPoint method is called, the coordinates returned
(varRet) are copied into the points array.
Once all the corners have been identified in the points array, the AddLightweightPolyline method is called. Notice that this method is called from the
ModelSpace object. If you were to run this macro, you would also notice
that the polyline is not yet visible in AutoCAD. The polyline will not
become visible until you update the display, which you will do later.

Draw the Tiles

Now that you have developed the user input subroutine, along with the subroutine to draw the outline, you are ready to fill the path with circular tiles.
This task requires some geometry.
In the VBA IDE, enter the following code in the Code window, after the
drawout subroutine:

Draw the Tiles

83

' Place one row of tiles the given distance along path
' and possibly offset it
Private Sub drow(pd As Double, offset As Double)
Dim pfirst(0 To 2) As Double
Dim pctile(0 To 2) As Double
Dim pltile(0 To 2) As Double
Dim cir As AcadCircle
Dim varRet As Variant
varRet = ThisDrawing.Utility.PolarPoint( _
sp, pangle, pd)
pfirst(0) = varRet(0)
pfirst(1) = varRet(1)
pfirst(2) = varRet(2)
varRet = ThisDrawing.Utility.PolarPoint( _
pfirst, angp90, offset)
pctile(0) = varRet(0)
pctile(1) = varRet(1)
pctile(2) = varRet(2)
pltile(0) = pctile(0)
pltile(1) = pctile(1)
pltile(2) = pctile(2)
Do While distance(pfirst, pltile) < (hwidth - trad)
Set cir = ThisDrawing.ModelSpace.AddCircle( _
pltile, trad)
varRet = ThisDrawing.Utility.PolarPoint( _
pltile, angp90, (tspac + trad + trad))
pltile(0) = varRet(0)
pltile(1) = varRet(1)
pltile(2) = varRet(2)
Loop
varRet = ThisDrawing.Utility.PolarPoint( _
pctile, angm90, tspac + trad + trad)
pltile(0) = varRet(0)
pltile(1) = varRet(1)
pltile(2) = varRet(2)
Do While distance(pfirst, pltile) < (hwidth - trad)
Set cir = ThisDrawing.ModelSpace.AddCircle( _
pltile, trad)
varRet = ThisDrawing.Utility.PolarPoint( _
pltile, angm90, (tspac + trad + trad))
pltile(0) = varRet(0)
pltile(1) = varRet(1)
pltile(2) = varRet(2)
Loop
End Sub

84 | Chapter 13 Design the Garden PathAn ActiveX/VBA

Tutorial

' Draw the rows of tiles

Private Sub drawtiles()
Dim pdist As Double
Dim offset As Double
pdist = trad + tspac
offset = 0
Do While pdist <= (plength - trad)
drow pdist, offset
pdist = pdist + ((tspac + trad + trad) * Sin(dtr(60)))
If offset = 0 Then
offset = (tspac + trad + trad) * Cos(dtr(60))
Else
offset = 0
End If
Loop
End Sub

To understand how these subroutines work, refer to the following illustration. The subroutine drow draws a row of tiles at a given distance along the
path specified by its first argument, and offsets the row perpendicular to the
path by a distance specified by its second argument. You want to offset the
tiles on alternate rows to cover more space and make a more pleasing
arrangement.

TSPAC + 2 * TRAD
30 degrees
60 degrees

The drow subroutine finds the location for the first row by using the
PolarPoint method to move along the path by the distance specified by the
first argument. The subroutine then uses the PolarPoint method again to
move perpendicularly to the path for the offset. The subroutine uses the
While statement to continue to draw circles until the edge of the path is
encountered. The PolarPoint method in the first While statement moves on
to the next tile location by spacing a distance of two tile radii (trad) and one
intertile space (tspac). A second while loop then draws the tiles in the row
in the other direction until the other edge is encountered.

Draw the Tiles

85

The drawtiles subroutine calls drow repeatedly to draw all the tile rows.
The subroutine While loop steps along the path, calling drow for each row.
Tiles in adjacent rows form equilateral triangles, as shown in the previous
illustra- tion. The edges of these triangles are equal to twice the tile radius
plus the spacing between the tiles. Therefore, by trigonometry, the distance
along the path between rows is the sine of 60 degrees multiplied by this
quantity, and the offset for odd rows is the cosine of 60 degrees multiplied
by this quantity.
The If statement is used in drawtiles to offset every other row. If the
offset is equal to 0, set it to the spacing between the centers of tiles
multiplied by the cosine of 60 degrees, as explained earlier. If the offset is
not equal to 0, set it to 0. This alternates the offset on the rows as you
want.
Save your work.

Tie It All
Together
You are ready to combine the subroutines into the Gardenpath macro. In the
VBA IDE, enter the following code in the Code window, after the drawtiles
subroutine:
' Execute command, calling constituent functions
Sub gardenpath()
Dim sblip As Variant
Dim scmde As Variant
gpuser
sblip = ThisDrawing.GetVariable("blipmode")
scmde = ThisDrawing.GetVariable("cmdecho")
ThisDrawing.SetVariable "blipmode", 0
ThisDrawing.SetVariable "cmdecho", 0
drawout
drawtiles
ThisDrawing.SetVariable "blipmode", sblip
ThisDrawing.SetVariable "cmdecho", scmde
End Sub

The path subroutine calls gpuser to gather the necessary input. The
GetVariable method is then used to obtain the current values of the
BLIPMODE and CMDECHO system variables, and saves these values as sblip
and scmde. The subroutine then uses the SetVariable method to set both of
these system variables to 0, thereby disabling blips and command echoing.
Next, the path is drawn using the drawout and drawtiles subroutines.
Finally, the SetVariable method is used to reset the system variables to their
original values.

86 | Chapter 13 Design the Garden PathAn ActiveX/VBA

Tutorial

You may notice that this is the only subroutine you have entered that did
not begin with a Private keyword, which ensures the subroutine can only
be called from within the current module. Because the gardenpath
subroutine must be available to the user, you should omit the Private
keyword.
Save your work.

Step Through the Code

Now run the macro, stepping through the code as it executes.
From the AutoCAD Tools menu, click Macro Macros. From the Macros
dialog box select ThisDrawing.gardenpath and click Step Into.
The VBA IDE is brought to the front of the screen, with the first line of the
gardenpath macro highlighted. The highlighted line is the line of code
that is about to be executed. To execute the line, press F8 . The next line of
code to be executed is the gpuser subroutine. To step into the gpuser
subroutine, press F8 again.
Now you are at the beginning of the gpuser routine. Press F8 one more
time to highlight the first GetPoint method. Before you execute this line,
open the Locals window by clicking View Locals Window. This window is
displayed
at the bottom of the VBA IDE. All the local variables and their values are displayed in the Locals window while the macro is executing.
Now press F8 to execute the GetPoint method. Notice that the highlight disappears and no new code is presented. This is because the GetPoint method
is waiting for the user to enter a point in AutoCAD. Switch back to the
AutoCAD window. You see the prompt you specified in the GetPoint call on
the command line. Enter a point.
Control now returns to the macro. The line following the call to the
GetPoint method is highlighted. Continue stepping through the code by
pressing F8 . Remember to switch back to the AutoCAD window when you
are entering information.

Step Through the Code

87

Execute the Macro

You dont need to step through the code whenever you run the macro. You
can run the macro from the Tools menu by clicking Macro Macros, selecting a macro, and then clicking Run. This allows you to see the flow of execution the way a user would see it. Run the macro from AutoCAD, entering
the following values:
Start point of the path: 2, 2
Endpoint of the path: 9, 8
Half width of the path: 2
Radius of tiles: .2
Spacing between tiles: .1
This example should draw a garden path as shown in the following figure:

You can experiment with the Gardenpath macro by specifying the various
inputs.

Add a Dialog Box

Interface
The Gardenpath macro has been written to accept command line input. To
add dialog boxes, you use forms in the VBA IDE.
First, copy the finished version of gardenpath.dvb to another file, gpdialog.dvb.
Then drag gpdialog.dvb into AutoCAD.

88 | Chapter 13 Design the Garden PathAn ActiveX/VBA

Tutorial

Create the Dialog

Box
The dialog box you create contains two option buttons (if you select one, the
other is cleared) for choosing the tile shape: circle or polygon. The dialog box
also contains three text boxes for entering the following numeric values: the
radius of the tiles, the spacing between the tiles, and the number of sides on
the tile (which is available only if the Polygon option button is selected).
To create a dialog box from the VBA
IDE
1 On the Insert menu, click User Form to open a new form. Two
windows, a toolbox, and a blank user form are displayed.
2

One by one, select and drag the following controls from the toolbox
and place them on the user form. You should place two option buttons (
),
three labels (
), three text boxes (
), and two command buttons ( ),
as illustrated on the following form:

3 Close the toolbox.

To set
the properties for
controls

the radio button

1 On the user form, select the OptionButton1 control. On the View menu,
click Properties Window, and change the following properties for
OptionButton1:
(Name) = gp_poly
Caption = Polygon
ControlTipText = Polygon Tile Shape
Accelerator = P

Add a Dialog Box Interface

| 89

2 On the user form, select the OptionButton2 control. In the Properties window, change the following properties for OptionButton2:
(Name) = gp_circ
Caption = Circle
ControlTipText = Circle Tile Shape
Accelerator = I
To set the properties for the label controls
1 On the user form, select the Label1 control. In the Properties window,
change the following properties for Label1:
(Name) = label_trad
Caption = Radius of tiles
TabStop = True
2 On the user form, select the Label2 control. In the Properties window,
change the following properties for Label2:
(Name) = label_tspac
Caption = Space between tiles
TabStop = True
3 On the user form, select the Label3 control. In the Properties window,
change the following properties for Label3:
(Name) = label_tsides
Caption = Number of sides
TabStop = True
To set the properties for the text box controls
1 On the user form, select the TextBox1 control. In the Properties
window, change the following property for TextBox1:
(Name) = gp_trad
2 On the user form, select the TextBox2 control. In the Properties
window, change the following property for TextBox2:
(Name) = gp_tspac
3 On the user form, select the TextBox3 control. In the Properties
window, change the following property for TextBox3:
(Name) = gp_tsides

90 | Chapter 13 Design the Garden PathAn ActiveX/VBA

Tutorial

To set the properties for the command button controls and the
form window
1 On the user form, select the CommandButton1 control. In the Properties
window, change the following properties for CommandButton1:
(Name) = accept
Caption = OK
ControlTipText = Accept the options
Accelerator = O
Default = True
2 On the user form, select the CommandButton2 control. In the Properties
window change the following properties for CommandButton2:
(Name) = cancel
Caption = Cancel
ControlTipText = Cancel the operation
Accelerator = C
3 Select the user form itself by clicking on the background of the form, away
from any control. In the Properties window, change the following properties for the form:
(Name) = gpDialog
Caption = Garden Path
Your form should now look like this:

4 Save your work.

Add a Dialog Box Interface

| 91

Use the Project Window to Navigate

Your
Project
In the VBA IDE, the Project window contains the name and location of the
project, a folder named AutoCAD Objects, and a folder named Forms. (You
might need to click Toggle Folders to see the folders.) When you open the
AutoCAD Objects folder (it may already be open), you see a drawing icon and
the name ThisDrawing. When you open the Forms folder (it may already be
open), you see a form icon and the name gpDialog, the form you created.
You can use the Project window to navigate through code and help you
iden- tify where you are working. For example, to view the code associated
with the form you created, highlight gpDialog in the Project window and
click View Code.
The Code window for the form is displayed.
Now highlight ThisDrawing in the Project window. You can view the code
by clicking View Code. All the code you have already entered is in this
window.

Update the Existing Code

Now that you have created a dialog box, you can modify and add code.
To modify the existing code
1 Open the code for ThisDrawing, if it is not already open.
2 Update the following lines in the Declarations section:
Public
Public
Public
Public

trad As Double
tspac As Double
tsides As Integer
tshape As String

'
'
'
'

Updated
Updated
Add
Add

Because the code in the form accesses trad and tspac, you update their
definitions to make them public. Private variables are available only in the
module in which they are defined, so the variables need to be changed to
public. Additionally, you have added tsides for the number of polygon
tile sides and tshape for the users choice of tile shape, which is either
cir- cle or polygon.
3 Go to the gpuser subroutine. Remove the two lines that obtain the
radius of the tiles and the spacing between the tiles, because this
information comes from the form. Specifically, remove the following:
trad = ThisDrawing.Utility. _
GetDistance(sp, "Radius of tiles: ")
tspac = ThisDrawing.Utility. _
GetDistance(sp, "Spacing between tiles: ")

92 | Chapter 13 Design the Garden PathAn ActiveX/VBA

Tutorial

4 Add the lines that load and display the form. Add the following lines in
place of the lines removed in step 3:
Load gpDialog
gpDialog.Show

5 Add a subroutine to the end of the code file that draws either the
circular tiles or the polygon tiles:
'Draw the tile with the designated shape
Sub DrawShape(pltile)
Dim angleSegment As Double
Dim currentAngle As Double
Dim angleInRadians As Double
Dim currentSide As Integer
Dim varRet As Variant
Dim aCircle As AcadCircle
Dim aPolygon As AcadLWPolyline
ReDim points(1 To tsides * 2) As Double
'Branch based on the type of shape to draw
Select Case tshape
Case "Circle"
Set aCircle = ThisDrawing.ModelSpace. _
AddCircle(pltile, trad)
Case "Polygon"
angleSegment = 360 / tsides
currentAngle = 0
For currentSide = 0 To (tsides - 1)
angleInRadians = dtr(currentAngle)
varRet = ThisDrawing.Utility.PolarPoint(pltile, _
angleInRadians, trad)
points((currentSide * 2) + 1) = varRet(0)
points((currentSide * 2) + 2) = varRet(1)
currentAngle = currentAngle + angleSegment
Next currentSide
Set aPolygon = ThisDrawing.ModelSpace. _
AddLightWeightPolyline(points)
aPolygon.Closed = True
End Select
End Sub

This subroutine uses a Select Case statement to branch control of the

program based on the type of shape to draw. The tshape variable is used
to determine the type of shape.
6 Next, go to the drow subroutine. Find the two occurrences of the
following line:
Set cir = ThisDrawing.ModelSpace.AddCircle(pltile, trad)

Change these lines to draw the appropriate shape tile, as follows:

DrawShape (pltile)

' Updated

Add a Dialog Box Interface

| 93

Add Code to the Dialog Box

Now you remove the code for the circular tile creation and call the DrawShape
subroutine to draw the appropriate shape instead.
To add event handlers for the dialog box
1 Open the Code window for gpDialog.
2 Enter the following code at the top of the window:
Private Sub gp_poly_Click()
gp_tsides.Enabled = True
ThisDrawing.tshape = "Polygon"
End Sub
Private Sub gp_circ_Click()
gp_tsides.Enabled = False
ThisDrawing.tshape = "Circle"
End Sub

Notice that the subroutines gp_poly_Click() and gp_circ_Click()

are named after the two option controls you added earlier, with the
addition of _Click. These subroutines are automatically executed when
the user clicks the respective control. Also notice that the Object Box lists
the con- trols on the form, sorted alphabetically by Name property.

3 Place your cursor on the Private Sub gp_poly_Click() line and open the
Procedure/Event Box.
You see a list of all the events that you can respond to for the gp_poly
option control. The two subroutines you entered handle the Click
event. You can also add code to respond to the DblClick event that
would auto- matically execute when the user double-clicked the control.
You can add code for any of the events listed. These types of subroutines
are called event handlers.

94 | Chapter 13 Design the Garden PathAn ActiveX/VBA

Tutorial

Look at the code you entered for these two event handlers. The first event
handler responds to the Click event for the gp_poly option control. The
first line of code enables the text box for the number of sides. This text box
is available only for polygons, so it is not enabled unless you select the
Polygon control. The next line of code sets the tshape variable to
Polygon.
The second event handler responds to the Click event for the gp_circ
option control. This handler disables the text box for the number of sides
and sets the tshape variable to Circle.
4 Add the following event handler for the OK button:
Private Sub accept_Click()
If ThisDrawing.tshape = "Polygon" Then
ThisDrawing.tsides = CInt(gp_tsides.text)
If (ThisDrawing.tsides < 3#) Or _
(ThisDrawing.tsides > 1024#) Then
MsgBox "Enter a value between 3 and " & _
"1024 for the number of sides."
Exit Sub
End If
End If
ThisDrawing.trad = CDbl(gp_trad.text)
ThisDrawing.tspac = CDbl(gp_tspac.text)
If ThisDrawing.trad < 0# Then
MsgBox "Enter a positive value for the radius."
Exit Sub
End If
If (ThisDrawing.tspac < 0#) Then
MsgBox "Enter a positive value for the spacing."
Exit Sub
End If
GPDialog.Hide
End Sub

This code tests whether the final choice of shape was polygon. If so, the
code retrieves the number of sides from the gp_tsides control. The value
the user enters is stored in the Text property. Because it is stored as a text
string, you convert the string to the integer equivalent using the Visual
Basic CInt function. Once obtained, the event handler tests the range of
the value to make sure it is between 3 and 1024. If it is not, a message is
displayed and the event handler is exited without further processing. The
result is that a message is displayed and the user is given an opportunity
to change the value. After the OK button is clicked again, this event handler triggers and tests the value again.

Add a Dialog Box Interface

| 95

The macro obtains radius and spacing values, but these values are
doubles, not integers, and are obtained using the CDbl function. These
values are also tested to make sure they are positive.
After the values are obtained and verified, the gpDialog.Hide statement
hides the form, passing control back to the subroutine that first called the
form.
5 Add the following event handler for the Cancel button:
Private Sub cancel_Click()
Unload Me
End
End Sub

This simple event handler unloads the form and ends the entire macro.
The only thing you havent done is add the initial values for the form.
There is an event called Initialize that applies to the form. It is executed
when the form is first loaded.
6 Add the following event handler for the form initialization:
Private Sub UserForm_Initialize()
gp_circ.Value = True
gp_trad.Text = ".2"
gp_tspac.Text = ".1"
gp_tsides.Text = "5"
gp_tsides.Enabled = False
ThisDrawing.tsides = 5
End Sub

This code sets the initial values for the form and for the tsides
variable. The tsides variable must be set to a positive number greater
than 3, even if the user selects a circle. To understand this, look in the
DrawShape sub- routine that you entered earlier. There is a variable there
called points that is defined using the number of sides for the polygon.
That variable gets memory allocated to it whether or not a polygon
shape has been requested. Because of this, tsides must have a valid
range defined for it. The user is free to change this value during macro
execution.
You can now save and run the macro from AutoCAD.

96 | Chapter 13 Design the Garden PathAn ActiveX/VBA

Tutorial

Visual LISP and ActiveX/

VBA Comparison

Most of the capabilities found in the Visual LISP

In this appendix

inter- face can also be found in the ActiveX and VBA

AutoLISP and

interface. This appendix serves as a reference to help

ActiveX/VBA
Comparison

developers familiar with Visual LISP find the equivalent

ActiveX
and VBA functionality.

353

AutoLISP and ActiveX/VBA

Comparison
The following table compares AutoLISP functions with the similar ActiveX
or Visual Basic functions and operators. The ActiveX Automation
equivalents are indicated by AutoCAD.Application. and the Visual Basic
equivalents are listed as a function or operator.
Paper space, model space, and TILEMODE settings
AutoLISP function

ActiveX or Visual Basic equivalent

+ (addition)

+ (addition operator)

(subtraction)

(subtraction operator)

* (multiplication)

* (multiplication operator)

/ (division)

/ (division operator)

= (equal to)

= (equal to comparison operator)

/= (not equal to)

<> (not equal to comparison operator)

< (less than)

< (less than comparison operator)

<= (less than or equal to)

<= (less than or equal to comparison operator)

/= (not equal to)

<> (not equal to comparison operator)

> (greater than)

> (greater than comparison operator)

>= (greater than or

equal to)

>= (greater than or equal to comparison operator)

~ (bitwise not)

Not operator

1+ (increment)

Use + (addition operator)

1 (decrement)

Use (subtraction operator)

abs

Abs function

acad_colordlg

Not provided

acad_strlsort

Search for SORT in the online Help index

98 | Appendix A Visual LISP and ActiveX/VBA

Comparison

acad_helpdlg

Search for HELP in the online Help index

AutoLISP and ActiveX/VBA Comparison

| 99

Paper space, model space, and TILEMODE settings (continued)

AutoLISP function

ActiveX or Visual Basic equivalent

action_tile

Use the Visual Basic Dialog Editor

add_list

Use the Visual Basic Dialog Editor

ads

AutoCAD.Application.ListADS method

alert

MsgBox function

and

And operator

angle

AutoCAD.Application.ActiveDocument.Utility.
AngleFromXAxis method

angtof

AutoCAD.Application.ActiveDocument.Utility.AngleToReal
method

angtos

AutoCAD.Application.ActiveDocument.Utility.
AngleToString method

append

Use Visual Basic array manipulation functions

apply

Not provided

arx

AutoCAD.Application.ListARX method

arxload

AutoCAD.Application.LoadARX method

arxunload

AutoCAD.Application.UnloadARX method

ascii

Asc function

assoc

Not provided

atan

Atn function

atof

CDbl Function

atoi

CInt Function

atom

Search for IS in the online Help index

atoms-family

Not provided

autoarxload

Not provided

autoload

Not provided

Paper space, model space, and TILEMODE settings

(continued)
AutoLISP function

ActiveX or Visual Basic equivalent

Boole

Use Visual Basic logical operators

boundp

Search for IS in the online Help index

car/cdr

Use Visual Basic array manipulation functions

chr

Chr function

client_data_tile

Use the Visual Basic Dialog Editor

close

AutoCAD.Application.Documents.Close method

command

AutoCAD.ActiveDocument.SendCommand method

cond

Select Case statement

cons

Use array manipulation functions or

AutoCAD.Application.collection.Add<entityname> method

cos

Cos function

cvunit

Use the conversion functions

defun

The Visual Basic keywords Function and End Function

dictadd

AutoCAD.Application.ActiveDocument.Dictionaries.Add
method

dictnext

AutoCAD.Application.ActiveDocument.Dictionaries.Item
method

dictremove

AutoCAD.Application.ActiveDocument.Dictionaries.
Dictionary.Delete method

dictrename

AutoCAD.Application.ActiveDocument.Dictionaries.
Dictionary.Rename method

dictsearch

AutoCAD.Application.ActiveDocument.Dictionaries.
Dictionary.GetName and GetObject methods

dimx_tile and dimy_tile

Use the Visual Basic Dialog Editor

distance

AutoCAD.Application.Utility.GetDistance for interactive

method.

distof

Not provided

100 | Appendix A Visual LISP and ActiveX/VBA

Comparison

Paper space, model space, and TILEMODE settings (continued)

AutoLISP function

ActiveX or Visual Basic equivalent

done_dialog

Use the Visual Basic Dialog Editor

end_image

Use the Visual Basic Dialog Editor

end_list

Use the Visual Basic Dialog Editor

entdel

AutoCAD.Application.ActiveDocument.collection_object.
Delete method

entget

AutoCAD.Application.ActiveDocument.collection_object.
property properties

entlast

AutoCAD.Application.ActiveDocument.Modelspace.
Item(count-1)

entmake

AutoCAD.Application.ActiveDocument.Modelspace.
Add<entityname> method

entmakex

AutoCAD.Application.ActiveDocument.Modelspace.
Add<entityname> method

entmod

Use any of the read-write properties for the object

entnext

AutoCAD.Application.ActiveDocument.collection.Item
method

entsel

AutoCAD.Application.ActiveDocument.SelectionSets
object/methods/properties

entupd

AutoCAD.Application.ActiveDocument.Modelspace.object.
Update method

eq

Not provided

equal

Eqv operator

*error*

Error object/method/properties

eval

Not provided

exit

AutoCAD.Application.Quit method

exp

Exp function

expand

Not provided

AutoLISP and ActiveX/VBA Comparison

| 101

Paper space, model space, and TILEMODE settings

(continued)
AutoLISP function

ActiveX or Visual Basic equivalent

expt

^ (exponentiation operator)

fill_image

Use the Visual Basic Dialog Editor

findfile

Dir function

fix

Fix, Int, Cint functions

float

CDbl Function

foreach

For Each...Next statement

gc

AutoCAD.Application.ActiveDocument.PurgeAll

gcd

Not provided

get_attr

Use the Visual Basic Dialog Editor

get_tile

Use the Visual Basic Dialog Editor

getangle

AutoCAD.Application.ActiveDocument.Utility.GetAngle
method

getcfg

AutoCAD.Application.Preferences.property property

getcname

Not provided

getcorner

AutoCAD.Application.ActiveDocument.Utility.GetCorner
method

getdist

AutoCAD.Application.ActiveDocument.Utility.GetDistance
method

getenv

AutoCAD.Application.Preferences.property property

getfiled

Use Visual Basic file dialog

getint

AutoCAD.Application.ActiveDocument.Utility.GetInteger
method

getkword

AutoCAD.Application.ActiveDocument.Utility.GetKeyword
method

getorient

AutoCAD.Application.ActiveDocument.Utility.
GetOrientation method

102 | Appendix A Visual LISP and ActiveX/VBA

Comparison

Paper space, model space, and TILEMODE settings (continued)

AutoLISP function

ActiveX or Visual Basic equivalent

getpoint

AutoCAD.Application.ActiveDocument.Utility.GetPoint
method

getreal

AutoCAD.Application.ActiveDocument.Utility.GetReal
method

getstring

AutoCAD.Application.ActiveDocument.Utility.GetString
method

getvar

AutoCAD.Application.GetVariable method

graphscr

AppActivate AutoCAD.Application.Caption

grclear

Obsolete function

grdraw

Not provided

grread

Not provided

grtext

AutoCAD.Application.ActiveDocument.Utility.Prompt

grvecs

Not provided

handent

AutoCAD.Application.ActiveDocument.ModelSpace.object.
Handle property

help

Search for HELP in the online Help index

if

IfThenElse statement

initget

AutoCAD.Application.ActiveDocument.Utility.
InitializeUserInput

inters

AutoCAD.Application.ActiveDocument.Modelspace.object.
IntersectWith

itoa

Str function

lambda

Not provided

last

arrayname(UBound(arrayname))

length

UBound function

list

ReDim statement

AutoLISP and ActiveX/VBA Comparison

| 103

Paper space, model space, and TILEMODE settings

(continued)
AutoLISP function

ActiveX or Visual Basic equivalent

listp

IsArray function

load_dialog

Use the Visual Basic Dialog Editor

load

AutoLISP is not supported through Automation

log

Log function

logand

And function

logior

Or function

lsh

Imp function

mapcar

Not provided

max

Max function

mem

Not provided

member

Use collection

menucmd

AutoCAD.Application.MenuBar object

menugroup

AutoCAD.Application.MenuGroup object

min

Min function

minusp

Use < 0 syntax

mode_tile

Use the Visual Basic Dialog Editor

namedobjdict

AutoCAD.Application.ActiveDocument.Dictionaries
collection

nentsel

AutoCAD.Application.ActiveDocument.SelectionSets.
SelectionSet.SelectAtPoint method

nentselp

AutoCAD.Application.ActiveDocument.SelectionSets.
SelectionSet.SelectAtPoint method

new_dialog

Use the Visual Basic Dialog Editor

not

Use the logical operators

nth

Use object(n) syntax

104 | Appendix A Visual LISP and ActiveX/VBA

Comparison

Paper space, model space, and TILEMODE settings (continued)

AutoLISP function

ActiveX or Visual Basic equivalent

null

IsNull function

numberp

TypeName function

open

Open function

or

Use the logical operators

osnap

Not provided (You can use the SetVariable method to

control the OSMODE system variable.)

polar

AutoCAD.Application.ActiveDocument.Utility.PolarPoint
method

prin1

AutoCAD.Application.ActiveDocument.Utility.Prompt

princ

AutoCAD.Application.ActiveDocument.Utility.Prompt

print

AutoCAD.Application.ActiveDocument.Utility.Prompt

progn

Not provided

prompt

AutoCAD.Application.ActiveDocument.Utility.Prompt

quit

AutoCAD.Application.Quit method

quote

Not provided

read

Not provided

read-char

Input function

read-line

Line Input function

redraw

AutoCAD.Application.ActiveDocument.Modelspace.object.
Update method

regapp

AutoCAD.Application.ActiveDocument.
RegisteredApplications.Add method

rem

Mod function

repeat

ForEach, While,

reverse

Not provided

AutoLISP and ActiveX/VBA Comparison

| 105

Paper space, model space, and TILEMODE settings (continued)

AutoLISP function

ActiveX or Visual Basic equivalent

rtos

AutoCAD.Application.ActiveDocument.Utility.RealToString
method

set

Set function

set_tile

Use the Visual Basic Dialog Editor

setcfg

AutoCAD.Application.Preferences.property property

setfunhelp

Not provided

setq

Set function

setvar

AutoCAD.Application.SetVariable method

sin

Sin function

setview

AutoCAD.Application.ActiveDocument.Viewports.Viewport.
SetView method

slide_image

Use the Visual Basic Dialog Editor

snvalid

Not provided

sqrt

Sqr function

ssadd

AutoCAD.Application.ActiveDocument.SelectionSets.Add
method

ssdel

AutoCAD.Application.ActiveDocument.SelectionSets.
SelectionSet.Delete method

ssget

AutoCAD.Application.ActiveDocument.SelectionSets.
SelectionSet.SelectOnScreen method

ssgetfirst

Not provided

sslength

AutoCAD.Application.ActiveDocument.SelectionSets.
SelectionSet.Count method

ssmemb

Compare ID of object with the SelectionSet members

ssname

AutoCAD.Application.ActiveDocument.SelectionSets.
SelectionSet.Name property

ssnamex

Not provided

106 | Appendix A Visual LISP and ActiveX/VBA

Comparison

Paper space, model space, and TILEMODE settings (continued)

AutoLISP function

ActiveX or Visual Basic equivalent

sssetfirst

AutoCAD.Application.ActiveDocument.PickfirstSelectionSet

startapp

Shell function

start_dialog

Use the Visual Basic Dialog Editor

start_image

Use the Visual Basic Dialog Editor

start_list

Use the Visual Basic Dialog Editor

strcase

StrConv function

strcat

& operator

strlen

Len function

subst

Not provided

substr

Mid function

tablet

Not provided

tblnext

AutoCAD.Application.ActiveDocument.collection_object.
Item method

tblobjname

AutoCAD.Application.ActiveDocument.collection_object.
Name method

tblsearch

AutoCAD.Application.ActiveDocument.collection_object.
Name method

term_dialog

Use the Visual Basic Dialog Editor

terpri

Not provided

textbox

AutoCAD.Application.ActiveDocument.space.object.
GetBoundingBox method

textpage

Not provided

textscr

Not provided

trace

Not provided

trans

AutoCAD.Application.ActiveDocument.Utility.
TranslateCoordinates method

AutoLISP and ActiveX/VBA Comparison

| 107

Paper space, model space, and TILEMODE settings (continued)

AutoLISP function

ActiveX or Visual Basic equivalent

type

TypeName function

unload_dialog

Use the Visual Basic Dialog Editor

untrace

Not provided

vector_image

Use the Visual Basic Dialog Editor

ver

AutoCAD.Application.Version property

vports

AutoCAD.Application.ActiveDocument.Viewports collection

wcmatch

Like operator

while

WhileWend

write-char

Print function

write-line

Print function

xdroom

Not provided

xdsize

Not provided

zerop

Use = 0 syntax

108 | Appendix A Visual LISP and ActiveX/VBA

Comparison

Index

2D objects editing,
104 positioning,
249
3D modeling
3DSolid object, 252
Add 3DPoly method , 249 mirroring
(illustration), 255 rectangular arrays
(illustration), 255 rotating
(illustration), 253
solids
analyzing properties (list), 252
combining, 257
methods for creating (list), 252
wireframes, creating, 249
3D polylines, creating, 249
3DMesh object
example code, 249
3DSolid object
defined, 252
example code, 252, 254, 256

A
acad.dvb project file, 13
acad.tlb type library, migrating automation
projects to AutoCAD 2004, 9
ACAD_LAYERSTATE dictionary, 145
ACADProject file, 15
acAttributeModeConstant constant, 292
acAttributeModeInvisible constant, 292
acAttributeModeNormal constant, 292
acAttributeModePreset constant, 293
acAttributeModeVerify constant, 293
acax16enu.tlb type library, migrating automation
projects to AutoCAD 2004, 9

acByBlock constant, 137

acByLayer constant, 137
AcCmColor object
assigning colors to objects, 138
changing objects' colors, 142
example code, 143
properties and methods, 7
acDisplay, 264
acExtents, 264
ACI numbers
assigning colors to objects, 138
changing objects' colors, 142
layers, 136
acIntersection constant, 89
acLayout, 264
acLimits, 264
acSubtraction constant, 89
Activate event, 234
Active UCS property, 65
ActiveDimStyle property, 180
ActiveLayer property, example code, 134
ActiveLinetype property, 139
ActivePViewport property, example code, 269
ActiveSpace property
example code, 267
view changing, 265, 266
ActiveTextStyle property, 65
ActiveUCS property, User Coordinate System,
244
ActiveViewport property
current viewport, 62
example code, 65, 249
resetting objects, 65

365

ActiveX Automation interface

automation projects. See automation
projects
changed items in AutoCAD 2004, 7
migrating automation projects to AutoCAD
2004, 8, 9
new objects in AutoCAD 2004, 7
ActiveX interface
advantages with AutoCAD, 2
and AutoCAD objects, 4
and VBA applications, 4
types of objects, 2
acUnion constant, 89
acView, 264
acWindow, 264
Add method
blocks, example code, 288
collections, 35, 41
dimension styles, 180
Documents collection, 52
example code, 52
Layers collection, 133
layers, example code, 105, 134
leader lines, 189
menu groups, example code, 197
menus, example code, 200
selection sets, example code, 94
text styles, 151
toolbars, example code, 210
UCS, example code, 244
User Coordinate System, 244
Add3DMesh method
creating rectangular meshes, 249
example code, 249
Add3DPoly method, 3D modeling, 249
AddArc method, 84
AddAttribute method
defining blocks, 292
AddBox method
creating solids, 252
example code, 254, 256, 257
AddCircle method creating
circles, 84 example
code, 87, 88
AddCone method, 252
AddCylinder method
creating solids, 252
example code, 257
AddDimAligned method
example code, 180, 186
linear dimensions, 173
AddDimAngular method
angular dimensions, 176
example code, 177
AddDimDiametric method, 175

110 |
Index

AddDimOrdinate method
example code, 178
ordinate dimensions, 178
AddDimRadial method, 175
example code, 175
radial dimensions, 174
AddDimRotated method, 173, 174
AddEllipse method, 84
AddEllipticalCone method , 252
AddEllipticalCylinder method, 252
AddExtrudedSolid method, 252
AddExtrudedSolidAlongPath method, 252
AddFitPoint method, splines, 127
AddHatch method
creating objects, 90
example code, 92, 129, 131
AddItem method, 94
AddLeader method
creating leader lines, 188
example code, 188, 189
AddLightweightPolyline method
example code, 83, 109
Garden Path tutorial, 338
AddLine method
example code, 120, 123
object hierarchy, 38
AddMenuItem method
creating menu items, 202
example code, 197
AddMInsertBlock method, 7, 288
AddMText method
example code, 162, 163, 189
multiline text, 161
AddPoint method, example code, 85
AddPolyfaceMesh method
creating meshes, 250
example code, 251
AddPViewport method
example code, 269
paper space, 268
AddRaster method
attaching images, 280
example code, 281, 285
AddRegion method, 87
calculating total number of regions, 87
example code, 87, 88
AddRevolvedSolid method, 252
AddSeparator method, using Type property, 202
AddSolid method
creating solids, 252
example code, 86
solid-filled area, 86
AddSphere method, 252
AddSpline method, example code, 84, 128
AddSubMenu method, example code, 204
AddText method
example code, 154

AddTolerance method
example code, 191
geometric tolerance, 191
AddToolbarButton method, 210
creating flyout toolbars, 213
example code, 211, 214
AddTorus method, 252
AddVertex property, polylines, 125
AddWedge method
creating solids, 252
example code, 252
AddXLine method, in 3D, 68
AddXLine object, example code, 68
Alignment property, 158, 294
example code, 159
in text, 159
AltFontFile property, 166
AngleFromXAxis method, 70, 337
AngleToReal method, 70
AngleToString method, 71
angular dimensions
creating, 176
illustration, 170
annotations, and leader lines, 187
AppActivate event, 230
AppDeactivate event, 230
AppendInnerLoop method
boundaries, 91
example code, 129
hatches, 129
AppendOuterLoop method
boundaries, 91
example code, 92, 129, 131
hatches, 129
application level events
declaring objects with events, 232
enabling, 230
events (list), 230
Application object
collections, accessing, 41
declaring objects with events, 232
events (list), 230
example code, 232, 327
root object, accessing, 34
Application window
changing visibility, 34
finding state, 55
finding status, example code, 55
modifying, 34
sizing, 55
Visible property, 56
applications
declaring Windows APIs, 329
distribution options, 322
exchanging data with AutoCAD , 324
instances, creating, 326
object model referencing, 324

applications (continued)
quit methods, 327
referencing application objects, 326
variables, declaring, 326
applicaton-level events
enabling, 231
Arc object creating, 84
Area property, 89
calculating for closed objects, 71
example code, 72, 88
splines, 127
array data, converting to variants, 45
arraying, patterns, 105
ArrayPolar method
attributes, 295
creating arrays, 112
dimension editing, 179
Text object, 161
ArrayRectangular method, 113, 255
attributes, 295
dimension editing, 179
Text object, 161
arrays
polar arrays , 112
rectangular, 113
rectangular arrays , 112
ARXLoaded event, 230
ARXUnloaded event, 230
associative dimensions, defined, 173
AssociativeHatch property, 128
AttachExternalReference method
example code, 300, 302, 303
AttachExternalReference method, changes in
AutoCAD 2004, 7
AttachmentPoint property, 162
AttachToolbarToFlyout method, example code,
214
Attribute object editing,
294 example code,
297
attributes
associating, 292
in blocks (illustration), 292
constants (list), 292
creating references, 292
and definitions, 297 editing
methods (list), 295 editing
properties (list), 294
extracting, 292
and references, 297
for text, 292
visibility, 292
Auto Data Tips, Code window, 26
auto embedding, setting for VBA projects, 18
Auto Indent, Code window, 26
Auto List Member, Code window, 26
Auto Quick Info, Code window, 26

Index
111

Auto Syntax Check, Code window, 26

AutoCAD
exchanging data, 324
reinstalling, 4
AutoCAD Color Index numbers. See ACI
numbers automation projects
migrating to AutoCAD 2004, 8, 9
See also ActiveX Automation interface

B
backslash (\)
in macros, 222
Backward property
attributes, 294
base point, rotating objects, 116
BasePoint property, 68
BatchPlotProgress property, 275
BeginClose event, 234
BeginCommand event, 228, 230, 234
BeginDoubleClick event, 234
BeginFileDrop event
defined, 230
example code, 232
BeginLISP event, 230, 234
BeginModal event, 230
BeginOpen event, 228, 230
BeginPlot event, 230, 234
BeginQuit event, 230
BeginRightClick event, 234
BeginSave event, 230, 234
BeginShortcutMenuCommand event, 234
BeginShortcutMenuDefault event
defined, 234
example code, 237
BeginShortcutMenuEdit event, 234
BeginShortcutMenuGrip event, 234
BeginShortcutMenuOsnap event, 235
Big Font files, 153
BigFontFile property
example code, 154
TextStyle object, 151
Bind method
example code, 305
external references, 304
bitonal images. See raster images
BLIPMODE system variable, 342
Block object
example code, 288, 289
in layouts , 262
Block property, in layouts, 263
block references arrays
and, 288 base
points, 288
exploding, 287, 289
fastener (illustration), 288
iterating, 288

112 |
Index

block references (continued)

listing attributes, 327
naming, 288
redefining, 288
See alsoblocks
BlockReference object
example code, 289, 297, 327
leader lines, 189
See also block references
blocks
attributes, 292
binding, 304
creating new blocks, 287
creating objects, 82
defined, 287
exploding, 123
inserting, 287
and layers, 137, 142
nesting (illustration), 287
organizing objects, 286
redefining, 290
referencing in ActiveX code, 82
BMP files
exporting to, 78
importing, 78
Boolean intersection (illustration), 257
Boolean method, 257
calculating area, 71
composite regions, 88
creating regions, 88
example code, 88
boundaries, Hatch object, 90
Boundary Hatch dialog box pattern option, 131
boxes
adding, example code, 254, 257
mirroring, example code, 256
slicing, example code, 259
Break mode, defined in VBA, 18
break on errors, for VBA projects, 18
Brightness property, 284

C
calculations
AddRegion method, 87
performing in drawings, 65
CanonicalMediaName property, 263
cascading menus. See submenus
CELTSCALE system variable, 140
Center property
example code, 270
WCS coordinate, 43
character formatting, example code, 163
CheckInterference method, 257
example code, 257
child object
relation to root object, 43

Circle object, 43
creating, 84
example code, 87, 88, 106
circular references, 25
Clear method
in selection sets, 103
ClipBoundary method, 285
example code, 285
ClippingEnabled property, 283, 285
example code, 285
Close method
Documents collection, 52
Closed property
polylines, 125
splines, 126
CMDECHO system variable, 342
Code window
Garden Path tutorial in, 333
margin indicator bar, 22
Object Box, 335
Procedure/Event Box, 335
resizing, 22
settings, 26
split bar, 22
collections
adding members, 35
Application object, accessing, 41
available in AutoCAD (list), 39
Count Property, 36
defined, 39
Document object, accessing, 40
Documents, 34
Item method, 36
MenuBar, 194
MenuGroup, 194
as object groups, 35
Color property
example code, 94
layers, 137
obsolescence in AutoCAD 2004, 7
raster images, 283
See also TrueColor property
colors
assigning to objects, 138, 141
changing objects' colors, 142
changing, example code, 143
overriding layers' color settings, 143
command line
controlling user input, 75
in zero document state, 321
prompting user, 73
compile time
errors in VBA, 316
object referencing, 43
ConfigName property, 265, 276

construction lines
modifying, 67
rays, 67
xlines, 67
ContourlinesPerSurface property, 252
Contrast property, 284
control codes, text formatting (table), 165
ControlPoints property, splines, 126
controls for forms adding
code, 313 adding to
forms, 312 control
toolbox, 312
formatting in VBA for, 313
modifying, 312
conversion functions, operation methods, 37
converting coordinates, 245
coordinates
converting between systems , 245
Coordinates property
polylines, 125
Copy method, 106, 161, 179, 295
copying
arraying, 105
from one drawing to another, 106, 107
mirroring, 105
multiple objects, 106
objects to other drawings, 106, 107
offsetting, 105
single object, 106
CopyObjects method, 106
example code, 106, 107
Count property, 36
for menus, 200
CreateObject function
migrating automation projects to AutoCAD
2004, 8, 9
CreatePoint object
example code, 85
CreateRegion, example code, 87
CreateSolid object
example code, 86
CreateSpline object
example code, 84
CreateTypedArray method, 45, 71
creating lines
Add Polyline, 83
AddLightweightPolyline method, 83
AddLine method , 83
AddMLine method, 83
creating objects blocks
in, 82 graphical,
36 model space in,
82 nongraphical,
36 paper space in,
82
crosshairs
resizing, 54

Index
113

cursor
restricting with Ortho mode, 66
restricting with Snap mode, 66
cursor menus
adding new items, 225
creating, 199, 200
deleting, 200
on graphics screen, 199
Shortcut menu property, 225
truncating, 199
CursorSize property
crosshairs, resizing, 54
curved objects
arcs, 83
circles, 83
ellipses, 83
spline curves, 83
CustomDictionary property, 167
cylinder, example code for adding, 257

D
DatabasePreferences object
storing options, 54
DCS
converting coordinates, 247
definition, 247
DDIM Annotation dialog box, 180
DDIM Format dialog box, 180
DDIM Geometry dialog box, 180
Deactivate event, 235
Declare statement, 329
Default to Full Module View
Project window, 27 default
VBA project name, 15
Degree property
splines, 127
degrees
converting from radians, 333
Delete method, 61
collections, 117
deleting views, example code, 61
example code, 206
in selection sets, 104
layers, 137
linetypes, 140
DeleteFitPoint method
splines, 127
deleting
collection member, 42
demand loading
and indexes, 306
performance benefits, 306
Description property
example code, 140
linetypes, 140
design mode, VBA environment and, 311

114 |
Index

Detach method
example code, 302
external references, 302
dialog boxes
in modal forms, 315
macro, 16
options for VBA IDE, 26
Save Project, 25
VBA Manager, 13
dialog controls. See controls
DIESEL string expressions, 201
DimAligned object
example code, 180, 186
DimAngular object
example code, 177
DIMASSOC system variable, 173
DIMCLRD system variable, 192
DIMCLRT system variable, 190, 192
dimension lines
illustration, 171
dimension styles
active, 173
Add method, 180
creating dimensions, 180
modifying, 180
parent, 180
dimension styles (illustration), 180
dimension system variables
list, 171, 174
dimensions
and geometry, 187
angular, 170
angular (illustration), 176
annotations, 172
associative, 173
hook lines (illustration), 175, 188
in model space, 187
in paper space, 187
leader lines (illustration), 172, 187
LeaderLength setting, 176
linear, 170
methods, editing, 179
modifying, 173
ordinate (illustration), 177
properties, editing, 179
radial, 170
creating, 174
rotating, 174
text styles, 172
illustration, 172
types of illustration, 170
DIMFIT system variable, 174
DIMGAP system variable , 192
DIMJUST system variable, 171, 174
DIMLFAC system variable, 187
DimOrdinate object
example code, 178

DimRadial object
example code, 175
DIMTAD system variable, 171, 174
DIMTIH system variable, 171, 174
DIMTOFL system variable, 171, 174
DIMTOH system variable, 171, 174
DIMTXSTY system variable, 190
DIMTXT system variable, 190, 192
DIMTXTSTY system variable, 192
DIMUPT system variable, 171, 174
Direction property, 268
example code, 249, 269
DirectionVector property, 68
example code, 68
displacement vector, 115
Display Coordinate System
definition, 247
Display method
in viewports, 267
Display preference, Options dialog box, 53
Display property
example code, 268, 269
DisplayPlotPreview method, 275
DisplayScreenMenu property, 54
DisplayScrollBar property, 54
DistanceToReal method, 71
distributing applications
VB, 322
VBA, 322
Dock method
docking toolbars, 215
example code, 215
document level events
and Document object, 236
coding, 237
declaring objects with events, 236
document- level events
enabling, 233
Document object
ActiveViewport property, 62
as AutoCAD drawing, 34
declaring objects with events, 236
enabling events, 233
events (list), 233
example code, 237, 267, 269
model space, accessing, 34
modifying drawings, 52
paper space, accessing, 34
ZoomAll method, 60
ZoomExtents method, 60
Document window
creating views, 60
Delete method, 61
displaying views, 56
maximizing, 56
minimizing, 56
modifying position, 56

Document window (continued)

Regen method, 64
sizing, 56
Split method, 62
status of active document, 56
Update method, 64
viewports, 61
WindowState property, 56
Zoom option, 57
zoom scale, specifying, 58
ZoomAll method, 59
ZoomCenter method, 59
ZoomExtents method, 59
ZoomPickWindow, 57
ZoomWindow, 57
document-level events
events (list), 233
right-clicking, 233
Documents collection
links to drawing, 34
Drafting preference, Options dialog box, 53
Drag and Drop Text Editing
Project window, 27 drawing
display, defined, 32
drawing extents and
rays, 69
zooming to, 59
drawings
assigning colors to objects, 138
changing objects' colors, 142
performing calculations, 65
text styles, 151
drawing-stored options, setting, 54
dtr function
in Garden Path tutorial, 333
DVB files, migrating automation projects to
AutoCAD 2004, 8
DWF files
exporting to, 78
DXF codes, and filter types (table), 95
DXF files
exporting to, 78
importing, 78

E
editing
2D objects, 104
macros, 17
nongraphical objects, 104
ElevateOrder method
splines, 127
Ellipse object
creating, 84
embedded projects
auto embed feature, 18
ThisDrawing object, 38

Index
115

enabling, application-level events, 231

EndAngle property, 123
EndCommand event, 228, 230, 235
EndLISP event, 230, 235
EndModal event, 231
EndOpen event, 228, 231
EndPlot event, 231, 235
EndPoint property, 123
example code, 123
EndSave event, 231, 235
EndShortcutMenu event, 235
example code, 237
EndTangent property
splines, 126
EPS (Encapsulated PostScript) files
exporting to, 78
ERASE command
macros, 224
Erase method, 110, 161, 179, 295
in selection sets, 103
leader lines, 189
Err object, 319
errors
at runtime, 316
Break mode, 18
at compile time, 316
Err object, 319
error messages, 316
error trapping, 316
ignoring errors, 317
user input control, 319
Evaluate method, 92
example code, 92, 129
in hatches, 128
leader lines, 190
event handlers
and infinite loops, 229
and interactive functions, 229
and parameters, 228
and subroutines, 228
Begin events, 228
creating objects, 229
deleting objects, 229
enabling doc-level eventsdocument-level
events, 233
End events, 228
writing guidelines, 228
events
document level, coding, 237
enabling application-level events, 231
enabling object-level events, 238
handling, 233
in AutoCAD, 228
InitializeEvents procedure, 237
Excel, extracting attributes, example code, 327
Explode method, 289
example code, 289

116 |
Index

exploding
blocks, 123
objects, 123
polylines, 123
Export method, 78
for saved layer settings, 149
extended data
uses of, 36
with graphical objects, 36
external references
attaching, 300
binding, 304
defined, 299
demand loading, 306
detaching, 301
and indexes, 306
overlaying, 301
reloading, 302
unloading, 303
updating, 300
ExternalReference object
example code, 300, 302, 303, 305

F
Fade property, 284
FieldLength property, 295
FileDependencies object, 7
FileDependency object, 7
Files preference, Options dialog box, 53
FILLMODE system variable, 86
filter lists, 95101
example code, 96101
filter types, and DXF codes (table), 95
filtering
example code, 96
selection sets, 95101
FitPoints property
splines, 126
FitTolerance property
splines, 126
Float method
floating toolbars, 215
flyout button, 211
Flyout property
ToolbarItem object, 218
flyout toolbars
AddToolbarButton method, 213
example code, 214
FontFile property, 151, 153
example code, 154
FontFileMap property, 166
fonts
alternative, specifying, 166
and text styles, 166
assigning in drawings, 152
Big Font files, 153

fonts (continued)
exporting in drawings, 153
font mapping tables, 166
SHX fonts, 153
substituting, 166
substitution rules, 166
TEXTFILL system variable, 153
TrueType, 153
Unicode, 153
form controls. See controls
Format menu
VBA IDE, 313
formatting characters
example code, 163
forms
adding controls, 312
control toolbox, 312
displaying, 314
formatting controls in VBA, 313
hiding, 314
hiding in Garden Path tutorial, 352
importing into VBA, 21
loading at runtime, 314
as macros, 314
modal dialog boxes, 315
modal versus modeless, 311
modal, defined, 314
mode, setting, 311
modifying controls, 312
unloading, 314
VBA environment, 311
VBA project component, 20
visibility at runtime, 313
Freeze property, 136

G
Garden Path tutorial
adding dialog boxes, 344
AddLightweightPolyline method, 338
Code window (illustration), 350
creating dialog boxes (illustration), 345
creating new macro, 332
determining corners, 339
determining values, 351
dtr function, 333
entering code, 333
event handling, 351
GetDistance method, 336
GetPoint method, 336
gpuser subroutine, 335
hiding forms, 352
installing VBA environment, 332
locating rows, 341
macro control, 343

Garden Path tutorial (continued)

option controls, 350
pangle variable, 337
Garden Path tutorial (continued)
PolarPoint method, 339
prompt sequence, 332
running macros, 344
saving files, 333
setting parameters, 336
stepping through code, 343
text edit box, 351
ThisDrawing object, 336
using prompts, 332
Utility object, 334
geometric tolerances
creating, 191
modifying, 191
GetAttributes method, 297
example code, 297, 327
GetBitmaps method, 212
example code, 212
GetDistance method, 71
example code, 71
Garden Path tutorial, 336
GetFitPoint method
splines, 127
GetFont method
example code, 152
GetInterfaceObject method
migrating automation projects to AutoCAD
2004, 9
GetKeyword method, 74
example code, 74
GetObject function
migrating automation projects to AutoCAD
2004, 8, 9
GetPoint method, 74, 343
defined, 74
example code, 74, 244
Garden Path tutorial, 336
GetString method, 74
example code, 73
GetUCSMatrix method, 244
GetVariable method, 65
GetXData method
example code, 307
global projects
defined, 12
ThisDrawing object, 38
graphical objects
defined, 32
editing commands, 36
properties, 36
visible objects, 36
GridOn property, 268

Index
117

H
Hatch object
AppendInnerLoop method, 91
AppendOuterLoop method, 91
AssociativeHatch property, 128
associativity, 90, 128
boundaries, 91
Boundary Hatch dialog box, 131
creating, 90
editing, 128, 131
example code, 92, 129, 131
handling islands, 91
patterns, 90, 131
specifying loops, 90
hatches, editing, 128
HatchStyle property
definitions (table), 91
handling islands, 91
Height property, 151, 154, 283, 295
example code, 154, 270
Help, status line
for menus and toolbars, 224
HelpString property
ToolbarItem object, 211, 217
hierarchy
accessing objects in VBA, 38
referencing objects, 38
hook lines
illustration, 188

I
image boundaries, defined, 282
ImageFile property, 281
ImageHeight property, 283
ImageVisibility property, 284
ImageWidth property, 283
Import method
file conversions , 78
for saved layer settings, 149
importing forms,
21 modules,
21
Index property
ToolbarItem object, 217
INDEXCTL system variable, 306
indexes
and demand loading, 306
and external references, 306
InitializeUserInput
example code, 75
InitializeUserInput method, 73, 319
(list), 75
defining keywords, 75
InsertBlock method, 287
example code, 288, 289

118 |
Index

InsertBlock method, changes in AutoCAD 2004,

8
InsertInMenuBar method, 195
example code, 198, 202204, 208, 224
from PopupMenu object, 197
InsertionPoint property, 158, 295
InsertLoopAt method, 129
InsertMenuInMenuBar method, 195
example code, 197
from PopupMenus collection, 197
intersecting regions
Region object, 89
IsPeriodic property
splines, 127
IsPlanar property
splines, 127
IsRational property
splines, 127
Item method, 36
iterating collections, 41
iterating collections
example code, 133

K
keywords
command line, 75
user input keywords, 75
Knots property
splines, 126

L
Label property
accelerator key, 203
Labels for menus
captions, 201
special codes, 201
LAYER command
macros, 222
Layer object
example code, 105, 134, 135
layer properties, saving. See layer settings, saving
Layer property, 142, 268
raster images, 283
layer settings
deleting saved settings
example code, 148
exporting saved settings, 149
example code, 150
importing saved settings, 149
example code, 150
listing saved settings, 145
managing, 146
renaming saved settings
example code, 148
restoring saved settings, 148

layer settings (continued)

example code, 149
saving, 144, 147
example code, 148
illustrated, 145
storing, 144, ??147
LayerOn property, 135
example code, 135
layers, 133
ACI number, 136
ActiveLayer property, 134
assigning colors to, 138
assigning linetypes, 137
assigning to objects, 141
and blocks, 137
changing layers, 142
color and, 132
Color property, 137
color, assigning, 136
color, settings, 143
freezing, 135
linetypes and, 132
locking, 136
plotting, 135
turning off (illustration), 135
Layers collection, 133
example code, 133
saved layer settings and, 145
LayerStateManager object, 145, 146
accessing, 146
associating database with, 147
Layout object, 262
example code, 276
layouts
Block object, 262
Block property, 262
CanonicalMediaName property, 263
Layout object, 262
lineweight scale, 264
in model space, 262
paper size, 263
in paper space, 262
PaperUnits property, 263
plot elements, 263
PlotConfiguration object, 263 plotting
input values (list), 263 switching
model space and paper space,
267
LayoutSwitched event, 235
leader lines
annotations, 189
associativity and editing, 190
associativity with annotations, 189
color, 187
creating, 187
determining type, 188

leader lines (continued)

illustration, 187
modifying, 187
scale, 187
scaling, 191
updating geometry, 190
Leader object
example code, 188, 189
LensLength property, 268
LicenseServer property, removed in AutoCAD
2004, 8
LightweightPolyline object, 125
creating, 83
example code, 83, 109, 111
LIN library files
and linetypes, 139
Line object
creating, 83
example code, 120, 123
linear dimensions
aligning, 174
creating, 173
illustration, 170
modifying properties (illustration), 173
rotating, 174
lines
creating, 83
lengthening, 123
Ray object, 67
Xline object, 67
Linetype object
example code, 139, 140
Linetype property, 137, 268
defining for layers, 143
example code, 143
raster images, 283
linetypes
active, 139
assigning to layers, 137
assigning to objects, 141
changing descriptions, 140
complex, 139
continuous (illustration), 143
deleting, 140
examples of (illustration), 139
LIN library files, 139
Load method, 139
new object properties, 139
renaming, 140
scales (illustration), 140
x-ref dependent, 139
Linetypes collection, 133
LinetypeScale property, 140, 268
lineweights
scaling in layouts , 264
LISPCancelled event, 231, 235

Load method
example code, 139, 195
linetypes, 139, 143
MenuGroups collection, 195
loading
ObjectARX applications, 34
VBA projects on startup, 320
loading projects
in AutoCAD, 13
in VBA, 25
Lock property, 136
loops
defining regions, 87
LowerLeftCorner property
illustration, 62
LTSCALE system variable, 140

M
macro libraries, 25
Macro property, 202, 320
ToolbarItem object, 211, 217
macros
and projects, 12 backslash
character, 222 canceling
commands, 222
command handling, 223
creating in tutorial, 332
delays (list), 222
editing, 17
enabling virus protection, 19
ERASE command, 224
guidelines for writing, 218
in menus, 218
in toolbars, 218
in VBA, 18
LAYER command, 222
naming, 16
object selection, single, 223
running, 17
running on startup, 320
SELECT command, 222
setting Break mode, 18
special characters (table), 219
stepping into, 18
terminating, 220
use of repetition, 223
user input, 221
Macros dialog box, 16
VBARUN command, 30
MainDictionary property, 167
matrix
See transformation matrices
maximizing, Document window, 56
MAXSORT system variable, 65
MClose property, 249

menu macros
special characters (table), 219
menu objects
ActiveX (illustration), 194
See also PopupMenu objects
MenuBar collection, 194
inserting menus, 197
object model (illustration), 195
rearranging menus, 198
removing menus, 198
MenuBar object
example code, 198
MenuBar property
example code, 198
MenuGroup object
example code, 195, 196, 197
MenuGroups collection, 194
Load method, 195
modifying (list), 195
new groups, creating, 196
object model (illustration), 194
popup menus and, 194
and toolbars, 194
See also menu objects
menus
assigning menu items, 208
checking, 207
creating submenus, 203
deleting, 205
disabling, 207
enabling, 207
menu macros, special characters, 208
positioning, 207
returning submenus, 208
type of menu item, 208
meshes
density, defined, 249
polyface mesh, creating, 250
rectangular, defined, 249
and solids, 249
and wireframes, 249
methods. See specific method names
migrating automation projects to AutoCAD
2004, 8, 9
minimizing, Document window, 56
MInsertBlock object, 288
Mirror method, 110, 161, 179
example code, 111
illustration, 110
Mirror3D method, 255
example code, 256
mirroring
example code, 111
in 3D, 255
objects, 105
Text objects, 110
with two coordinates, 110

MIRRTEXT system variable, 110, 161

MLine object
creating, 83
Mode property, 295
model space
accessing objects, 35
and paper space, switching, 267
creating objects, 82
defined, 262
dimensioning in, 187
example code, 82
hidden lines, 274
layouts, 262
plot settings, modifying, 276
plotting, 275
referencing in ActiveX code, 82
returning objects, 39
viewports, 265
ModelSpace property, 82
Modified event, 238
module
VBA object component, 20
modules
importing into VBA, 21
MomentOfInertia property, 252
Move method, 161, 179, 191
vectors, 115
Move object
example code, 116
illustration, 115
MSpace property, 267
example code, 267, 269
mtext
control codes (table), 165
creating, 161
in drawings, 150
modifying, 161
Unicode fonts (table), 165
uses for, 161
MText object, 161
creating text, example code, 163
example code, 162, 189
formatting options, 162
justification (illustration), 162
leader lines, 189
modifying, 162
orientation options, 162
overriding default, 162
text boundary, 162
multiline text. See mtext

N
Name property
example code, 105
layers, 133
linetypes, 140

Name property (continued)

PopupMenus collection, 200
raster images, 282
setting active viewport, 62
ToolbarItem object, 210, 217
toolbars, 209
named colors
assigning colors to objects, 138
changing objects' colors, 142
color names (table), 138
named objects
character length, 104
purging, 104
renaming, 104
specifying, 104
naming macros, 16
naming projects, in VBA IDE, 24
NClose property, 249
NewDrawing event, 231
nongraphical objects, editing, 104
NumberOfControlPoints property
splines, 127
NumberOfCopies property, 275
example code, 276, 277
NumberOfFitPoints property
splines, 127
NURBS, AddSpline method, 84

O
Object Coordinate System
definition, 246
object level events
and event handlers, 239
and VBA keywords, 238
class modules, 238
enabling, 238
object libraries
AutoCAD as Automation controller, 3
referencing in VBA IDE, 325
object methods, defined, 42
object model
MenuBar collection (illustration), 195
MenuGroups collection (illustration), 194
ObjectAdded event, 235
ObjectARX applications
specific actions, 34
ObjectARXPath property, obsolescence in
AutoCAD 2004, 8
ObjectErased event, 235
ObjectModified event, 235
object-oriented, VBA interface, 3
objects
active, resetting, 65
assigning colors, 138
changing colors, 142
changing layers, 142

objects (continued)
closed
calculating area (illustration), 71
defining from user input points, 71
creating, 82
enabling events, 238
existing, modifying, 104
exploding, 123
extending, 122
for menus, 194
graphical, 36
in ActiveX, 32
in ActiveX (list), 2
moving along a vector, 115
named, specifying, 104
nongraphical, 36
object component, 20
offsetting, 109
open, calculating area (illustration), 71
properties, defined, 42
removing from selection sets, 103
rotating in 3D, 253
scale factor, 118
scaling, 118
ThisDrawing, 17
transforming, 119
trimming, 122
See also specific object names
ObliqueAngle property, 151, 155, 158
obliquing angles, in text
illustration, 155
OCS
converting coordinates, 246
creating polylines, 83
definition, 246
Offset method, 109
creating objects, 43
example code, 109
offsetting, objects, 105
On Error
forms of (list), 317
VBA statement, example code, 318
Open method
Documents collection, 52
example code, 52
Open method, changes in AutoCAD 2004, 8
Open VBA Project dialog box, 321
opening VBA IDE
from command line, 19
from menu bar, 19
OpenSave preference, Options dialog box, 53
operating system
rebooting, 4
options
setting for VBA projects, 18

Options dialog box

in VBA IDE, 26
preferences objects (list), 53
ordinate dimensions
and error preventing, 177
creating, 177
leader lines, 177
organizational structures, defined, 32
organizing projects, with VBA Manager, 13
Origin property, 283
Ortho mode
cursor movement, 66
defining axes (illustration), 67
example code, 67
OrthoOn property, 67
Output preference, Options dialog box, 53
overlaying, external references, 301

P
paper space
accessing objects, 35
and model space, switching, 268
creating objects, 82, 272
defined, 262
dimensioning in, 187
editing models, 265
example code, 82
hidden lines, 274
layouts, 262
plotting, 275
referencing in ActiveX code, 82
returning objects, 39
scaling linetypes, 274
scaling views, 272
viewports, floating, 265
zooming (illustration), 274
Paper Space Display Coordinate System
definition, 247
PaperSpace property, 82
PaperUnits property, 263
parent objects
relation to root object, 43
Parent property
ToolbarItem object, 218
PatternAngle property, 131
PatternDouble property, 131
PatternName property, 131
patterns
asssigning hatch patterns, 90
PatternScale property, 131
PatternSpace property, 131
example code, 131
PatternType constants
defined, 91

pausing macros
delays (list), 222
PDMODE system variable
illustration, 84
PDSIZE system variable
illustration, 84
PICKADD system variable, 219
PICKAUTO system variable, 219
Plot object, 275
example code, 276, 277
Plot dialog box, 37
PlotConfiguration object, 263
PlotHidden property, 274
plotting
in model space, 275, 276 in
paper space, 275, 277 layout
input values (list), 263
methods (list), 275
properties (list), 275
PlotToDevice method, 275
example code, 276, 277
PlotToFile method, 275
PlotType property
example code, 276
Point object
controlling appearance of, 84
creating, 84
example code, 85
polar arrays
center point, specifying, 112
creating, 112
example code, 112
reference points, 112
PolarPoint method, 71, 339
PolyfaceMesh object
example code, 251
PolygonMesh object, 249
Polyline object, 125
creating, 83
defining from user input points, 72
polylines
creating in OCS, 83
editing, 125
exploding, 123
fit and spline fit, 125
modifying, 125
PopupMenu object
creating submenus, 203
deleting menu items, 205
example code, 197, 198, 200
InsertInMenuBar method, 197
menu items, ordering (illustration), 201
PopupMenuItem object
accelerator keys, assigning, 203
AddSeparator method, 202
Caption property, 207

PopupMenuItem object (continued)

Check property, 207
creating, 200
deleting menu items, 205
editing labels, 201
Enable property, 207
example code, 197
HelpString property, 207
Index property, 207
index, defined, 201
Label property, 206
label, defined, 201
Macro property, 207
macro, defined, 202
new menu items, adding, 200
Parent property, 207
position menu, changing, 201
status-line Help message, 224
Submenu property, 207
Tag property, 206
tag, defined, 201
Type property, 207
writing macros, 218
PopupMenus collection
cursor menus, 200
InsertMenuInMenuBar method, 197
Name property, 200
new menus, creating, 200
RemoveMenuFromMenuBar method, 198
PostScript files, importing, 78
preferences in AutoCAD
accessing, 54
CursorSize property, 54
drawing-stored options, 54
properties, 54
registry-stored options, 54
Preferences object, Options dialog box, 36
Preferences objects, accessing, 54
PrincipalDirections property, 252
PrincipalMoments property, 252
Procedure Separator Display
Project window, 27
ProductOfInertia property, 252
Profiles preference, Options dialog box, 53
ProgIDs
migrating automation projects to AutoCAD
2004, 8, 9
project components
forms, 20
importing, 21
modules, 20
new, 20
references, 20
Project window
defined in VBA IDE, 19
settings, 26

projects
.dvb file, 24
automation. See automation projects
circular references, 25
components in VBA, 20
embedded, 12, 14, 29
extracting, 15
global, 12, 29
importing, 21
loading in AutoCAD, 13
migrating to AutoCAD 2004, 8, 9
naming in VBA IDE, 24
referencing, 25
setting options for VBA, 18
unloading, 14
VBA default name, 15
VBA terms defined, 29
prompts for user input
Garden Path tutorial, 332
PromptString property, 295
Properties window
VBA IDE, 24
properties. See specific property names
PSDCS
converting coordinates, 247
definition, 247
PSLTSCALE system variable, 274
pull-down menus
creating, 199
from menu bar, 199
truncating, 199
PurgeAll method
example code, 104
purging, named objects, 104
PViewport object, 265
example code, 268, 269, 270

Q
QuietErrorMode property, 275
Quit method
example code, 327

R
radial dimensions
creating, 174
illustration, 170
TextPosition property, 174
radians
converting degrees, 333
RadiiOfGyration property, 252
raster images
and vector files, 280
attachments, 280
bitonal images, 284
clipping (illustration), 285

raster images (continued) clipping

boundaries, 285 display
properties (list), 284 display,
adjusting, 284
DPI, defined, 280 file
naming, 282 geometry
scale, 280 hiding
boundaries, 283
image boundaries, defined, 282
image names vs. file names, 282
linking paths, 280
modifying (list), 282, 283
Name property, 282
path, modifying, 282
properties for modifying (list), 283
redraw speed, 284
resolution, 280
scale factor, 280
showing boundaries, 283
vectors, 284
visibility, 284
Raster object, 280
example code, 281, 285
Ray object, 67, 69
BasePoint property, 69
DirectionVector property, 69
example code, 69
rectangular arrays, 113
creating in 3D, 255
example code, 114
in 3D (illustration), 255
snap rotation angle, 114
reference points, in polar arrays, 112
referenced projects, loading in AutoCAD, 25
referencing objects
calling hierarchy, 38
type library, 43
Regen method
example code, 270
for text styles, 152
Region object
Boolean method, 88
calculating total number, 87
creating composite, 88
defining loops, 87
example code, 87, 88
intersecting regions, 89
subtracting, 88
uniting regions, 89
registry-stored settings, 53
accessing, 34
Reload method
example code, 303
external references, 302
RemoveFromMenuBar method
example code, 198
RemoveHiddenLines property, 274

RemoveItems method
in selection sets, 103
RemoveMenuFromMenuBar method
from PopupMenus collection, 198
RenderSmoothness property, 252
Require Variable Declaration
Code window, 26
Reverse method
splines, 127
RGB values
assigning colors to objects, 138
changing objects' colors, 142
right-click menu. See cursor menu
root object
accessing, 39
hierarchy, 39
relation to parent object, 43
See also Application object
Rotate method, 116, 161, 179
example code, 117
Rotate3D method, 253
example code, 254
rotating objects, 116
illustration, 116
rotation angles, 155
Rotation property, 158, 162, 179, 295
run mode, in VBA environment, 311
running macros, 17
runtime
error trapping, 317
errors in VBA, 316
object referencing, 43

S
sample code, finding for ActiveX and VBA, 6
SAT files
exporting to, 78
importing, 78
SAVE command
from VBA IDE, 25
Save method
for layer settings, 147
verifying changes, 53
Save Project dialog box
accessing, 25
VBAUNLOAD command, 30
SaveAs method, 52
example code, 196
SaveAs method, changes in AutoCAD 2004, 8
saved layer settings. See layer settings
saving projects, in VBA IDE, 25
scale factor
illustration, 118
object dimensions, 118
ScaleEntity method, 118, 179, 191, 283, 295
example code, 119

ScaleFactor property, 158, 295

scaling
in layouts, 264
in paper space, 272
leader lines, 191
linetypes, 274
objects, 118
viewports (illustration) , 272
SecurityParams object, 7
SELECT command
macros , 222
Select method, 94
SelectAtPoint method, 94
SelectByPolygon method, 94
Selection preference, Options dialog box, 53
selection sets
filter lists, 95101
removing objects, 103
SelectionChanged event, 235
SelectionSet object, 93
example code, 94, 96, 307
SelectionSets collection, 93
SelectOnScreen method, 94
example code, 94, 307
separators
adding to menus, 202
adding to toolbars, 212
SetBitmaps method, 212
LargeIconName parameter, 212
SmallIconName parameter, 212
SetBulge method
polylines, 125
SetControlPoint method
example code, 128
splines, 127
SetCustomScale method, 264
SetDatabase method, 147
SetFitPoint method
splines, 127
SetFont method
example code, 152
SetLayoutsToPlot method, 275
example code, 277
SetPattern method, 131
SetProjectFilePath method, 282
SetVariable method, 65, 85
example code, 159
for dimensioning, 171
linetypes, 140
SetWeight method
splines, 127
SetWidth method
polylines, 125
SetXData method
example code, 307
sharing code by referencing projects in VBA, 25
ShortcutMenu property, 225

ShowRotation method, 283

SHX fonts, 153
Single object selection in macros, 223
sizing
Application window, 55
Document window, 56
SliceSolid method
example code, 259
snap angle
illustration, 66
Snap mode
cursor movement, 66
snap rotation angle
rectangular arrays, 114
SnapBasePoint property, 66
example code, 66
SnapRotationAngle property, 66, 114
example code, 66
Solid object
analyzing properties, 252
Boolean intersection (illustration), 257
CheckInterference method, 257
combining solids, 257
creating, 86 creating
solids, 252 example
code, 86 properties
(list), 252
solid-filled areas
illustration, 86
See also Solid object
spell checking, 166
Spline object
creating, 84
example code, 84, 128
splines
editing, 126
querying, 127
SPLINETYPE system variable, 125
split bar, in Code window, 22
Split method, 62
viewports, example code, 62
splitting viewports
example code, 63
spreadsheets, extracting attributes to, example
code, 327
standard color names. See named colors
StandardScale property, 264
example code, 276
StartAngle property, 123
StartBatchMode method, 275
StartPoint property, 123
StartTangent property
splines, 126
startup
loading VBA projects, 320
running a macro, 320
status-line Help, for menus and toolbars, 224

stepping into macros, 18

style settings, 32
StyleName property, 158, 163, 179
submenus
adding, 203
populating, 204
positioning, 203
subtracting regions
Boolean method, 88
Region object, 89
System preference, Options dialog box, 53
SysVarChanged event, 231

T
Tag property, 201
ToolbarItem object, 217
TagString property, 295
attribute references, 297
example code, 297
terminating macros
code examples, 220
terminology in VBA environment (list), 310
Text object
aligning in drawings (illustration), 159
angles, setting, 155
displaying backward, 156
displaying upside down, 156
example code, 154, 156, 159
formatting, 158
height settings, 154
line text, 150
line text, creating, 157
methods (list), 161
mirroring text, 110
modifying, 161
mtext, 150
ObliqueAngle property, 155
properties (list), 158
spell check, 166
text generation flag, 156
used in drawings, 150
text styles
changing properties, 152
creating, 151
current, 151
default, 151
for dimensions, 172
properties (table), 151
TextAlignmentPoint property, 158
example code, 159
TEXTFILL system variable, 153
TextGenerationFlag property, 151, 152, 156,
158
example code, 155, 156
TextOverride property
example code, 180

TextPosition property, 179

TextRotation property, 179
TextString property, 158
attribute referrences, 297
example code, 297
TextStyle object, 151
example code, 154
properties (list), 151
TextStyles collection, 151
TextSuffix property
example code, 186
This, 289
ThisDrawing object, 29
accessing Document object, 38
Garden Path tutorial, 336
in embedded objects, 17, 38
in global objects, 17
in global projects, 38
working in zero document state, 321
TILEMODE system variable, 267
Tolerance object
example code, 191
leader lines, 189
tolerances
geometric, 191
system variables (list), 192
toolbar macros
special characters (table), 219
Toolbar object
AddSeparator method, 212
AddToolbarButton method, 210
Dock method, 215
Docked property, 215
example code, 210, 211, 214, 215
Float method, 215
flyout toolbars, creating, 213
naming, 209
using Type property, 212
ToolbarItem object, 210
creating flyout button, 211
deleting, 216
example code, 211, 212, 214
Flyout property, 218
GetBitmaps, 212
HelpString property, 211, 217
Index property, 217
Macro property, 211, 217
Name property, 210, 217
Parent property, 218
positioning toolbar buttons, 210
SetBitmaps method, 212
status-line Help message, 224
Tag property, 217
Type property, 218
writing macros, 218
toolbars
modifying, 195

Toolbars collection
Add method, 209
Name property, 209
transformation matrices
assigning matrix to variable, 120
rotation (table), 121
scaling (table), 121
transforming objects
translation (table), 121
transformation matrix
user coordinate system, 244
world coordinate system , 244
TransformBy method, 119
example code, 120
TranslateCoordinates method, 71
converting coordinates, 245
example code, 244, 247
true colors
assigning to objects, 138 changing
objects' colors, 142 changing,
example code, 143 overriding layers'
color settings, 143
TrueColor property
changing objects' colors, 142
example code, 143
new properties in AutoCAD 2004, 7
See also Color property
TrueType fonts, 153
height settings, 154
tutorial
See Garden Path tutorial
type libraries
adding reference, 43
defined, 43
type libraries, migrating automation projects to
AutoCAD 2004, 9
Type property
example code, 212
ToolbarItem object, 218
TypeName function, 46

U
UCS
converting coordinates, 246
definition, 246
UCSIconAtOrigin property, 244
UCSIconOn property, 244
UCSORG system variable , 244
Unicode fonts, 153
table, 165
uniting regions
Region object, 89
Unload method
example code, 303
external references, 303

unloading
ObjectARX applications, 34
Update method, 123
example code, 64
for text styles, 152
redrawing objects, 104
Text object, 159
UpperRightCorner property
illustration, 62
User Coordinate System
axis location, 244
definition, 246
origin point location, 244
viewports, 244
user input
Garden Path tutorial, 332, 334
user input functions
prompting, 37
user input methods
GetInteger method, 73
GetKeyword , 74
GetPoint, 74
GetPoint method, 73
GetString, 74
GetString method, 73
user input pausing macros, 221
User preference, Options dialog box, 53
UserForm
window
editing forms , 22
UseStandardScale property, 264
Utility object
calculating area, 71
calculation methods (list), 70
example code, 244
functions, 37
TranslateCoordinates method, example
code, 247
user input methods, 73

V
variants
CreateTypedArray method, 45
defined, 44
input arrays , 44
output arrays, 44
polyline editing, 124
Typename function, 46
VarType function, 46
VarType function, 46
VB
ActiveX Automation interface
changed items, 7
new objects, 7
automation projects. See automation
projects

VBA
ActiveX Automation interface
changed items, 7
new objects, 7
automation projects. See automation
projects
VBA environment
accessing applications, 325
application distribution, 322
control toolbox (illustration), 310
design mode, 311
dialog boxes, creating, 310
End statement, 333
forms, 310, 311
installing for tutorial, 332
password protection, 319
referencing object libraries, 325
run mode, 311
running macros, 320
terminology (list), 310
Windows API procedures, accessing, 329
working in a zero document state, 321
VBA Hide method, 314
VBA IDE
"Hello World" exercise, 28
defined, 29
macro execution, 18
opening, 19
opening on project load, 321
Properties window, 24
referencing object libraries, 325
SAVE command, 25
viewing project data, 19
VBA interface
advantages
with ActiveX, 4
with AutoCAD, 3
elements of, 4
environment, 3
implementing in AutoCAD, 3
VB, similarities with, 3
with ActiveX interface, 3
VBA Load method, 314
VBA Manager
creating projects, 15
defined, 30
dialog box, 13
embedding projects, 14
extracting projects, 15
loading projects, 13
saving projects, 15
unloading projects, 14
VBA methods, (table), 315
VBA Object Browser, 325
VBA programming using ActiveX, 4
VBA projects
acad.dvb file, 320

VBA projects (continued)

defined, 12
loading on startup, 320
running macros on startup, 320
VBA Show method, 313
VBA statements
On Error, example code, 318
VBAIDE command, 30
VBALOAD command, 13, 30
VBAMAN command, 30
VBARUN command, 16, 30
VBASTMT command, 30
VBAUNLOAD command, 14, 30
VBP files, migrating automation projects to
AutoCAD 2004, 9
vector files, and raster images, 280
vectors
moving objects, 115
version, accessing, 34
version-dependent ProgIDs
migrating automation projects to AutoCAD
2004, 8, 9
version-independent ProgIDs
migrating automation projects to AutoCAD
2004, 8, 9
Viewport object, 265
example code, 249
LowerLeftCorner property, 62
UpperRightCorner property, 62
viewports
changing views (illustration), 272
detail view, 61
displaying, 265
floating (illustration), 265
full view, 61
hidden lines, 274
horizontal display (illustration), 62
in model space, 265
in paper space, 265
models (illustration), 266
modifying, 270
properties (list), 268
scale factor, 272
setting active, 62
settings (table), 266
splitting, example code, 63
tiled (illustration), 265
vertical display (illustration), 62
views
creating, 60
Views collection, 60

virus protection
enabling for macros, 19
setting for VBA projects, 19
using project code, 14
Visible property, 56 example
code, 214 setting,
example code, 56
Visual Basic, 47
Visual Basic automation projects
migrating to AutoCAD 2004, 8, 9
Visual Basic for Applications. See entries beginning
with VBA
Visual Basic. See VB
Visual LISP
accessing objects, 324
calling methods, 324
retrieving methods, 324
Volume property, 252

W
WBlock method, 287
leader lines, 189
WCS
converting coordinates, 246
definition, 246
wedges
adding, example code, 252
Width property, 151, 283
example code, 270
WindowChanged event, 231, 235
WindowMovedOrResized event, 231, 235
Windows APIs
accessing from VBA, 329
WindowState property, 56
WithEvents
declaring objects with events, 232, 236
enabling objects with events, 239
GetObject, VBA function
example code, 232
VBA Keyword, example code, 232, 236
WMF files
exporting to, 78
World Coordinate System
definition, 246
entering coordinates, 242

X
xdata. See extended data
Xline object, 67
XLOADCTL system variable, 306
XMLDatabase object, removed in AutoCAD
2004, 8
XRefDemandLoad property, 306
xrefs. See external references

Z
zero document state, 321
Zoom Center method
illustration, 59
zoom scale, specifying, 58
Zoom window
example code, 57
ZoomAll method, 59
example code, 60, 83, 85, 86
illustration, 60
ZoomCenter method, 59
example code, 59

ZoomExtents method
example code, 60, 270
illustration, 60
in active viewport, 59
zooming
defined, 57
in paper space (illustration), 274
scale factors, 272
zoom scales, 274
ZoomPickWindow method, 57
example code, 57
ZoomScaled method , 58, 273
example code, 58, 270
ZoomWindow method, 57