VBA projects can contain modules. A module is a self-contained piece of programming code. A VBA project can have one or more modules.

To add a module, choose Insert

Figure 37.1. The VBA IDE.

To see the list of AutoCAD objects, click the <All Libraries> drop-down list and choose AutoCAD. You can see the result in Figure 37.1.

Although you might first think that an object in VBA is the same as an object in an AutoCAD drawing, there is more to the story. In VBA, everything is an object. For example, AutoCAD as an application is an object. Your current drawing is also an object. Model space and paper space are also objects. Therefore, to specify an object in your drawing, you need to specify the application, the drawing, and finally the object in the drawing. To do this, VBA works with a hierarchy of objects. For example, the hierarchy makes it possible to distinguish between an object in your drawing and an object in an Excel spreadsheet.

Objects are specified from the most general to the most specific, with a period between each part of the definition. You then add the desired method or properties after another period. For example, you can use the following VBA code to add a circle:

Application.ActiveDocument.ModelSpace.AddCircle(center, radius)

A shortcut for Application.ActiveDocument is ThisDrawing, so you can also use:

ThisDrawing.ModelSpace.AddCircle(center, radius)

In order to work with any object, you need to know where it fits in the hierarchy. The quickest way to see the hierarchical structure from the VBA IDE is to choose any method or property in the Object Browser and to choose the Help (question mark) button on the Object Browser's toolbar. On the Contents tab, choose Object Model to see the listing in Figure 37.2.

Note

Within AutoCAD, choose InfoCenter toolbar

Figure 37.2. The object model shows you the hierarchy of all the VBA objects so that you can work with them.

STEPS: Becoming Acquainted with the VBA Environment

VBA offers several help features. You've already seen the Object Browser, which provides you with a list of objects as well as their properties and methods. To access help on an object, choose it in Object Browser and click Help. You can do the same for a method or property, as shown in Figure 37.3.

Figure 37.3. The help page for the Center property.

After you open a help page, click Example to see an example. These examples are a great way to learn VBA. You can copy a snippet of VBA code and paste it into your own routine, and then edit it as you want.

For more general help, AutoCAD offers two systems:

To access these reference guides, switch to AutoCAD and click the Help button or press F1. Then click the Contents tab and choose ActiveX Automation and VBA.

The Microsoft Visual Basic for Applications Help provides information on the general VBA environment. Click Help on the VBA IDE Menu Bar toolbar. Here you see help for other VBA-enabled applications that you may have. You can use this when you're ready to write VBA code that integrates more than one application.

After you start programming, you can get help on any class, method, or property by clicking it and pressing F1. For example, you can type AddLine and press F1 to access help on how to create a line.

To start programming, you need an idea of how a VBA procedure is put together. Here is a complete VBA subroutine that draws a 3D solid box.

'Insert a 3D Solid Box
Sub Box()
'declare input variables to AddBox()
     Dim dOrigin(0 To 2) As Double 'origin is array of doubles '(x,y,z)
     Dim dLength As Double         'length
     Dim dWidth As Double          'width
     Dim dHeight As Double         'height
     Dim myBox As Acad3DSolid      'holds return from AddBox()

     dOrigin(0) = 0#               'set origin to (0,0,0)
     dOrigin(1) = 0#
     dOrigin(2) = 0#

dLength = 5#                  'make a cube 5 by 5 by 5
     dWidth = 5#
     dHeight = 5#

     'create the box in modelspace of the current drawing
     Set myBox = ThisDrawing.ModelSpace.AddBox(dOrigin, dLength, _
                 dWidth, dHeight)
     'change the viewpoint to better see the box
     ThisDrawing.SendCommand ("VPOINT 1,1,1 ")
End Sub

Here's what the code means:

To find the syntax for a statement that you want to use, look in VBA Help, as explained in the "Accessing help" section earlier in this chapter. In the preceding VBA routine, you might want to click AddBox and press F1 to find the syntax and elements that are required for creating a box. Then click Example to see an actual example of code for that statement.

As I mention earlier, the AutoCAD version of VBA saves VBA projects as separate files with a DVB file extension. However, when you run a routine, AutoCAD lists it in the format ModuleName:Procedure Name. If your project has only one module, you can give the module and the procedure the same name. However, most VBA routines have more than one module, with one module controlling the rest. By running the controlling module, you run the whole project.

To name a module, look in the Properties window. After you've created a module, the VBA IDE lists its name property as Module1 by default. Double-click Module1 and type a new name. Notice that the module name in the Project window also changes accordingly.

You can save your project in the SampleVBA subfolder in the AutoCAD 2010 folder, or use another folder that is in the support-file search paths of AutoCAD.

When you type code from scratch in the Visual Basic editor, you immediately notice that Visual Basic color-codes your text as you go. The most common colors are:

Keywords include variable types and other words that Visual Basic recognizes, such as Dim and Sub.

Tip

You can customize these colors by choosing Tools

When you start to type a keyword that Visual Basic recognizes, you'll often see a box pop up that enables you to choose from a list, or that helps you to complete the word. The editor also adds or removes spaces and capitalizes certain words for you to improve your syntax. If you make a syntax mistake, a small error message often appears as you work. In these ways, the Visual Basic editor helps you to type accurate code.

STEPS: Creating, Saving, and Running a VBA Program

Don't save your drawing.

Here's an explanation of the routine that you just wrote and used. Note that blank lines are ignored.

A variable holds a value for later use in your program. In VBA, you don't need to explicitly declare your variables in advance (as long as you don't include Option Explicit, which I explain later). You use the Set statement to set a variable to an object, as in the example here. This statement creates a variable, cir, and sets its value equal to the circle that the AddCircle method creates.

Set cir = ThisDrawing.ModelSpace.AddCircle(cen, radius)

When you create a variable in this way, VBA assigns the default variant type to it. The variant type of variable can contain numbers, dates, or strings (of text).

However, declaring variables explicitly in advance has two advantages:

You declare variables by using the Dim statement. Here's an example:

Dim radius As Double

You can create three different levels of variables:

Placing the statement Option Explicit in a Declarations section requires all variables to be declared. Using Option Explicit is a way to force yourself to write your code more carefully. Declared variables are easier to debug because they're easier to find.

Table 37.2 describes the kinds of variables that you can declare.

Here's an example that uses the Date variable type and displays it in a message box:

Sub DateDemo()
Dim dt As Date
Dim dbl As Double
    dt = Now        'set the dt to the current date and time
    dbl = dt        'assign this date value to a double
MsgBox "Normal date version: " & dt & "  Double version: " & dbl
End Sub

Running DateDemo (by pressing F5) would show something similar to:

Normal date version: 5/10/2005 8:03:13 PM
Double version: 38482.8355671296

Although a complete discussion of how to write VBA code is beyond the scope of this book, some general principles will be helpful.

A statement in VBA is the most basic unit of code. It contains a complete instruction. There are three kinds of statements:

VBA has many keywords, functions, and other components that you can use to create code. To find the basic components of the VBA language, choose Help

Remember that you can also find a list of objects and their properties and methods in the Object Browser, as I explained earlier in this chapter.

The Toolbox toolbar contains the tools that you need to create a dialog box. These are the familiar controls that you see in the dialog boxes that you use all the time, such as text boxes, list boxes, check boxes, and so on.

Table 37.4 explains the Toolbox toolbar buttons.

After you insert a user form, you should name it. Find the Name property in the Properties window, and change it from UserForm1 (the default name) to any useful name that you want. You might find it useful to use the word frm in the name. For example, for a routine to draw a circle, you could call the user form frmCircle.

Figure 37.6 shows the property box when you insert a user form. You can easily change the dialog box's properties in the property box.

One property that you'll want to change is the Caption property of the dialog box. The dialog box should have a caption that summarizes its purpose. When you type the new caption in the property box, the caption on the dialog box changes at the same time.

Figure 37.6. When you insert a user form (dialog box), the Properties window lists all its properties.

One of the more commonly used controls is the command button. A command button is a button that you click in the dialog box to execute an action. The most familiar command buttons are the OK and Cancel buttons.

Add a command button

To add a command button, click CommandButton on the Toolbox toolbar. Move your cursor over the dialog box, and drag to create a button. Figure 37.7 shows a dialog box with a new command button. The selection border and handles indicate that the button is a selected object. You can move the button by dragging it. You can resize the button by dragging one of the handles. Add all the command buttons that you need. Don't forget to include at least a Cancel button. Many dialog boxes also have an OK button. If you know in advance all the controls that you'll need, you can add them all at once.

Figure 37.7. A dialog box with one selected command button.

Tip

There's an art to laying out a dialog box so that it's clear and easy to understand. After a while, you'll get the hang of it. Pay more attention to the dialog boxes that you use every day to pick up some design pointers.

Just as the dialog box has properties, each control on the dialog box has properties. When a control such as a command button is selected, you see its properties in the Properties window. You generally would change at least the caption and the name of a command button. It's a good idea to change the names to something meaningful, instead of using the default name. For example, rather than CommandButton1, use a name such as cmdDrawBox or cmdOk.

Write the VBA Code for a command button

After you create a command button, you can attach VBA code to it. To attach VBA code to a control, double-click the control. The text editor opens with the Sub and End Sub lines already entered for you. Type the code that you want to attach to the button.

VBA dialog boxes are modal by default, which means that they must be closed before AutoCAD can do anything further. To close a dialog box after your VBA code has run, use Unload Me at the end of a routine.

To run VBA code that is attached to a dialog box, you need to show the dialog box so that you can use it — click a command button, type in text, and so on. The VBA IDE creates private subroutines for each dialog box control. To show the dialog box, start a new module and create code that looks like the code in this example:

Sub DrawArc()
  frmArc.Show
End Sub

FrmArc is the name of the user form in this example. Don't forget to name the user form in the Properties window. Also, remember to name the module, because the module name is what appears in the Macro dialog box when you want to run the routine.

Add a label

A command button is quite simple. You just click it, and it performs. You can label its function right on the command button. However, most other controls require some more explanation. For example, if you want the user to type in text, you need a text box. However, a text box has no caption. Therefore, you need to add instructions to the user. A dialog box may also need other instructions to clarify the purpose of the controls, which responses are required, and so on.

You add instructions with the Label tool on the Toolbox toolbar. Click Label and drag a rectangle on your dialog box. Then type the label. You can resize or move the label as needed.

Add other dialog box controls

The code for some of the dialog box controls can be quite complex. For example, to create a list box that enables the user to choose from an existing list of options, you'd probably create the list of options in advance. For help on creating dialog boxes, choose Help

STEPS: Creating a Dialog Box with a Command Button

1. Start a new drawing in AutoCAD by using the acad.dwt template.

2. To start a new project, choose Manage tab

   

3. Choose Insert

   

4. With the user form active (click its title bar to make it active), change the Name property of the user form to frmArc in the Properties window.

5. Change the Caption property of the user form to Draw an Arc. Watch the caption of the user form change as you type.

6. Choose CommandButton on the Toolbox toolbar. (It's the last button in the second row. If you don't see the Toolbox toolbar, click in the user form on the right side of your screen.) Move the cursor over the user form and drag to create a wide button across the upper center of the user form.

7. Change the Caption property of the button to Draw the Arc!. Change the Name property to cmdDrawArc.

8. Again, choose CommandButton on the Toolbox toolbar. Create a smaller button below the first one near the right side of the user form.

9. Change the Caption property of the smaller button to Cancel. Change its Name property to cmdCancel. Your dialog box should look like the one in Figure 37.8.

   

   Figure 37.8. A simple dialog box created in VBA.

10. Double-click the larger button. In the text editor, type the following code at the cursor's current location between the Private Sub and End Sub statements:

    'declare variables
    Dim startang As Double
    Dim endang As Double
    Dim ctr(0 To 2) As Double
    Dim rad As Double
    Dim newarc As Object
    'specify arc parameters
    startang = 0
    'angles are in radians.
    endang = 100
    ctr(0) = 5
    ctr(1) = 2
    ctr(2) = 0
    rad = 2
    'draw arc
    Set newarc = ThisDrawing.ModelSpace.AddArc(ctr, rad, startang, endang)
    'close dialog box
    Unload Me

11. From the left (Object) drop-down list at the top of the text editor, choose cmdCancel to add the code for the second button. In the space below the start of the subroutine (Private Sub cmdCancel_Click()), type Unload Me.

12. Choose Insert

    

    Sub DrawArc()
    frmArc.Show

    Visual Basic places the End Sub statement for you after the code.

13. In the Properties window, change the module's name to DrawArc.

14. Click Save on the toolbar and save the file in your AutoCAD Bible folder as ab37-03.dvb.

15. Return to your drawing. Choose Manage tab

    

16. Click the large button. AutoCAD draws the arc.

Getting user input for a circle radius

Here's another example of a routine that draws a circle, although here you get user input for the radius by using the VAL function. The VAL function returns a numerical value from a text string. Here you create a text box that enables users to type in a radius. The VAL function converts the string in the text box to a number and uses it as the circle's radius. Follow these steps:

1. Open AutoCAD with a new drawing, using the acad.dwt template. Open the VBA IDE.

2. Choose Insert

   

3. In the Properties window, change the name of the form to frmDrawCircle, and change the caption to Draw a Circle Demo.

4. From the Toolbox toolbar, choose Label and drag a small rectangle on the left side of the form, around the middle.

5. Change the name to lblRadius, and change the caption to Radius.

6. Choose Textbox on the Toolbox toolbar, and drag a box on the form to the right of the label.

7. Change the name to txtRadius.

8. Choose CommandButton on the Toolbox toolbar, and drag a larger box at the top center of the form.

9. Change the name to cmdDrawCircle, and change the caption to Draw Circle.

10. Double-click this command button to bring up the text editor in the cmdDrawCircle_Click () subroutine.

11. Add the following lines:

    Dim dCenter(0 To 2) As Double
    Dim dRadius As Double
    Dim myCircle as AcadCircle
    
    dCenter(0) = 0#
    dCenter(1) = 0#
    dCenter(2) = 0#
    
    dRadius = Val(txtRadius)
    Set myCircle = ThisDrawing.ModelSpace.AddCircle(dCenter, dRadius)
    myCircle.Update

12. Close the text editor. Save the routine if you want. On the VBA IDE menu, choose Run

    

13. Add as many circles as you like. Click the Close box of the dialog box when you're done.

Constants are names that are given to commonly used values. For instance, AutoCAD defines constants for the seven standard colors: acRed, acYellow, acGreen, acCyan, acBlue, acMagenta, and acWhite. In the DrawCircle example, after creating the circle, you could add the following code to change its color to blue:

Dim clrObj As AcadAcCmColor
Set clrObj = myCircle.TrueColor
clrObj.ColorMethod = acColorMethodByACI
clrObj.ColorIndex = acBlue
myCircle.TrueColor = clrObj

Most functions or properties that have a standard set of values will have corresponding constants defined.

Functions are a type of procedure (like subroutines), except that they return a value. Here's an example for those of you who are counting the days until January 1, 2010. (If you're reading this after that date, you can change it to a later date.) Alternatively, it will tell you how many days ago January 1, 2010, occurred (indicated by a negative value).

Function DaysTil2010() As Integer  'notice "As Integer" tells
'the return type of                'the function
    Dim dtToday As Date            'holds today's date
    Dim dt2010 As Date             'holds Jan 1, 2010

    dtToday = Now()                'assign today's date
    dt2010 = CDate("1/1/2010")     'assign Jan 1, 2010
    DaysTil2010 = dt2010 - dtToday 'calculate difference,
'return value assigned             'to function name
End Function                       'same as End Sub

To use this function, you must do something with the return value through an assignment, or use it as a parameter to another procedure. For example:

Public Sub Test2010()
MsgBox "Days until year 2010: " & DaysTil2010()
End Sub

You can then run the Test2010 sub to open a message box that tells you how many days are left until the year 2010.