Working with Visual Basic for Applications

This topic discusses how to program in the VBA environment to control either ArcMap, ArcCatalog, or ArcScene by accessing the objects they expose. Your code manipulates the objects by getting and setting properties on their interfaces, such as setting the MaximumScale and MinimumScale of a map's FeatureLayer; invoking methods on the interfaces, such as adding a vertex to a polyline; or setting a field's value. The code runs when an event occurs, for example, when a user opens a document, clicks a button, or alters data by modifying an edit sketch.
The VBA development environment
Getting started with VBA
    To start the Visual Basic Editor
    To add a macro to a module
    Adding modules and class modules
    To add a procedure to an existing module
    Adding user forms
    To add and start coding in a user form
Some VBA project-management techniques
    Reusing modules, class modules, and user forms
    Removing project items
    Protecting your code
    Saving a VBA project
Running VBA code
    To run your code in the Visual Basic Editor or from the Macros dialog box
    To run only one procedure in the Visual Basic Editor
    After you've finished writing your code
Using the Global Application objects

The VBA development environment

First you'll see the aspects of the VBA development environment in which you'll do your work that are specific to the ESRI applications. Consult the Visual Basic Reference, the online help file that displays when you click Microsoft Visual Basic Help in the Help menu of the VBA Editor for generic help on the user interface, conceptual topics, how-to topics, language reference topics, customizing the Visual Basic Editor, and user forms and controls.
In the VBA development environment you can add modules, class modules, and user forms to the default project contained in every ArcGIS application document. A project can consist of as many modules, class modules, and user forms as your work requires. A project is a collection of items to which you add code. A module is a set of declarations followed by procedures—a list of instructions that your code performs. A class module is a special type of module that contains the definition of a class, including its property and method definitions. A user form is a container for user interface controls, such as command buttons and text boxes.
ArcMap has a default project associated with its document that's listed in the Project Explorer as Project followed by its filename. In addition, you'll see another project listed in the Project Explorer called Normal (Normal.mxt).
Normal is, in fact, a template for all documents. It's always loaded into the document. It contains all the user-interface elements that users see, as well as the class module named ArcID, which contains all the UIDs for the application's commands.
Since any modifications made to Normal will be reflected every time you create or open a document, you should be careful when making changes to Normal.
In ArcMap, users can start by opening a template other than the default template. These templates are available to them in the New dialog box. From a developer's perspective this is a base template, a document that loads an additional project into the document; it is listed in the Project Explorer as the TemplateProject followed by its filename. This project can store code in modules, class modules, forms, and any other customizations, such as maps with data, page layout frames, and so on. Any modifications or changes made to this base template are reflected only in documents that are derived from it.
In ArcCatalog, Normal (Normal.gxt) is the only project that appears in the Project Explorer. There is no default Project in ArcCatalog, and you can't load any templates. You can, of course, add code to Normal.gxt inside modules, class modules, or forms, but again, be careful when making changes.
Once you've invoked the Visual Basic Editor, you can insert a module, class module, or user form. Then you insert a procedure or enter code for an existing event procedure in the item's Code window, where you can write, display, and edit code. You can open as many Code windows as you have modules, class modules, and user forms, so you can easily view the code and copy and paste between Code windows. In addition to creating your own modules, you can import other modules, class modules, or user forms from disk.
If your work requires it, you can add an external object library or type library reference to your project. This makes another application's objects available in your code. Once a reference is set, the referenced objects are displayed in the development environment's Object Browser.

Getting started with VBA

To begin programming with VBA in ArcMap or ArcCatalog, you start the Visual Basic Editor.

To start the Visual Basic Editor

  1. Start ArcMap or ArcCatalog.
  2. Click the Tools menu, point to Macros, then click Visual Basic Editor. You can also use the shortcut keys Alt+F11 to display the Visual Basic Editor. To navigate among the projects in the Visual Basic Editor, use the Project Explorer. It displays a list of the document's modules, class modules, and user forms.

To add a macro to a module

ArcMap and ArcCatalog both provide a shortcut for creating a simple macro in a module.
  1. Click the Tools menu, point to Macros, then click Macros.
  2. Type the name of the macro you want to create in the Macro name text box. If you don't specify a module name, the application creates a module called modulexx and stores the macro in that module. If no module is specified after you specify a module, and a module is already active, the macro is placed in that module. Preceding a macro's name with a name and a dot stores it in a module with the specified name. If the module doesn't exist, the application creates it.
  3. Click the dropdown arrow of the Macros in the combo box and choose the VBA project in which you want to create the macro.
  4. Press the Enter key or click Create.
  5. The stub for a Sub procedure for the macro appears in the Code window.

Adding modules and class modules

All ArcGIS application documents contain the class module ThisDocument, a custom object that represents the specific document associated with a VBA project. The document object is called MxDocument in ArcMap and GxDocument in ArcCatalog. The IDocument interface provides access to the document's title, type, accelerator table, command bars collection, parent application, and Visual Basic project.
Modules and class modules can contain more than one type of procedure: sub, function, or property. You can choose the procedure type and its scope when you insert a procedure. Inserting a procedure is like creating a code template into which you enter code.
Every procedure has either private or public scope. Procedures with private scope are limited to the module that contains them—only a procedure within the same module can call a private procedure. If you declare the procedure public, other programs and modules can call it.
Variables in your procedures may either be local or global. Global variables exist during the entire time the code executes, whereas local variables exist only while the procedure in which they are declared is running. The next time you execute a procedure, all local variables are reinitialized. However, you can preserve the value of all local variables in a procedure for the code's lifetime by declaring them static, thereby fixing their value.

To add a procedure to an existing module

  1. In the Project Explorer, double-click the ArcMap Objects, ArcCatalog Objects, or Modules folder, then choose the name of a module. Ensure that the code view of the module is active by clicking the View Code button.
  2. Click the Insert menu and click Procedure.


  3. Type the name of the procedure in the Name text box.
  4. Click the Type dropdown arrow and click the type of procedure: Sub, Function, or Property.
  5. Click the Scope dropdown arrow and click Public or Private.
  6. To declare all local variables static, check the All Local variables as Statics check box.
  7. Click OK. VBA stubs in a procedure into the item's Code window into which you can enter code. The stub contains the first and last lines of code for the type of procedure you've added.
  8. Enter code into the procedure.
For more information about procedures, see the Microsoft Visual Basic online help reference.

Adding user forms

If you want your code to prompt the user for information, or you want to display the result of some action performed when the user invokes an ArcGIS application command or tool, or in response to some other event, use VBA's user forms. User forms provide a context in which you can provide access to a rich set of integrated controls. Some of these controls are similar to the UIControls that are available as part of the Customize dialog box's Commands tab. In addition to text boxes or command buttons, you have access to a rich set of additional controls. A user form is a container for user-interface controls, such as command buttons and text boxes. A control is a Visual Basic object you place on a user form that has its own properties, methods, and events. You use controls to receive user input, display output, and trigger event procedures. You can set the form to be either modal, in which case the user must respond before using any other part of the application, or modeless, in which case subsequent code is executed as it's encountered.

To add and start coding in a user form

  1. In the Project Explorer, select the Project to which you want to add a user form.
  2. Click the Insert menu and click UserForm.
  3. VBA inserts a user form into your project and opens the Controls Toolbox.


  4. Click the controls in the Controls Toolbox that you want to add to the form.
  5. Add code to the user form or to its controls.
For more information about adding controls, see the Microsoft Visual Basic online help reference.
To display the Code window for a user form or control, double-click the user form or control. Then, choose the event you want your code to trigger from the dropdown list of events and procedures in the Code window and start typing your code. Or, just as in a module or class module, insert a procedure and start typing your code.
To display the form during an ArcMap or ArcCatalog session in response to some action, invoke its Show method, as in this example:
[VBA] 
UserForm1.Show vbModeless 'show modeless

Some VBA project-management techniques

To work efficiently in the ArcGIS application's VBA development environment, and reduce the amount of work you have to do every time you start a new task, make use of several techniques that will streamline your work:

Reusing modules, class modules, and user forms

To add an existing module or form to the Normal template, the Project, or a TemplateProject, click the name of the destination in the Project Explorer, then choose Import File from the File menu. You can choose any VBA module, user form, or class module to add a copy of the file to your project. To export an item from your project so that it is available for importing into other projects, select the item you want to export in the Project Explorer, choose Export File from the File menu, then navigate to where you want to save the file. Exporting an item does not remove it from your project.

Removing project items

When you remove an item, it is permanently deleted from the project list—you can't undo the Remove action; however, this action doesn't delete a file if it exists on disk. Before removing an item, make sure remaining code in other modules and user forms doesn't refer to code in the removed item. To remove an item, select it in the Project Explorer, then choose Remove <Name> from the File menu. Before you remove the item, you'll be asked whether you want to export it. If you click Yes in the message box, the Export File dialog box opens. If you click No, VBA deletes the item.

Protecting your code

To protect your code from alteration and viewing by users, you can lock a Project, a TemplateProject, or even Normal. When you lock one of these items, you set a password that must be entered before it can be viewed in the Project Explorer. To lock one of these items, right-click Project, TemplateProject, or Normal in the Project Explorer, then click the Properties item in the context menu that appears. In the Properties dialog box, click the Protection tab and click the option to Lock Project for Viewing. Enter a password and confirm it. Finally, save your ArcMap or ArcCatalog file and close it. The next time you or anyone else opens the file, the project is locked. If anyone wants to view or edit the project, they must enter the password.

Saving a VBA project

VBA projects are stored in a file that can be a base template (*.mxt), the Normal template, or a document (*.mxd). When a user creates a new ArcMap document from a base template, the new document references the base template's VBA project and its items. To save your ArcMap document and your VBA project, click Save from the ArcMap File menu or Save <File Name> from the File menu in the Visual Basic Editor. Both commands save your file with the project and any items stored in it. After saving the file, its filename is displayed in the Project Explorer in parentheses after the project name. To save the document as a template, click Save As from the ArcMap File menu and specify ArcMap Templates (*.mxt) as the File type.

Running VBA code

As you build and refine your code, you can run it within VBA to test and debug it. This section discusses running your code in the Visual Basic Editor during design time. For more information about running and debugging a VBA program, such as adding breakpoints, adding watch expressions, and stepping into and out of execution, see Microsoft Visual Basic online help.

To run your code in the Visual Basic Editor or from the Macros dialog box

  1. Click the Tools menu and click Macros.
  2. In the Macro list, click the macro you want and click Run.
If the macro you want is not listed, make sure you've chosen the appropriate item: either Normal, Project, or TemplateProject in the Macros In box. Private procedures do not appear in any menus or dialog boxes.

To run only one procedure in the Visual Basic Editor

  1. In the Project Explorer, open the module that contains the procedure that you want to run.
  2. In the Code window, click an insertion point in the procedure code.
  3. Click the Run menu and click Run Sub/UserForm.
Only the procedure in which your cursor is located runs.

After you've finished writing your code

After you have finished writing code, users can run it from ArcMap or ArcCatalog. To do this, they choose Macros and then Macros from the Tools menu. You can also associate the code with a command or tool, or it can run in response to events or in other ways that you design.

Using the Global Application objects

Application and ThisDocument are examples of global system variables that can be accessed by any module or class in the VBA environment while ArcMap is running. This variable is automatically set to reference the current document when ArcMap opens the document. You can use ThisDocument as a shortcut when programming in VBA to access the current document. Here is an example of how to use both the Application and ThisDocument:
[VBA] 
Dim pMxDoc As IMxDocument
Set pMxDoc = Application.Document
'or
Set pMxDoc = ThisDocument
Both methods illustrated above result in a reference being set to the local document.