Creating custom commands with VBA and UI Controls
Release 9.2 Last modified November 9, 2006	Print all topics in : "Writing macros using VBA"

About creating custom commands with VBA and UIControls

There is an easy way to create custom commands with VBA. You can create a new button, tool, combo box, or edit box (collectively named UIControls), then attach code to the control's events, such as what happens when you click a button. After you have created it, you can drag this new control onto a toolbar.

UIControls

If you create a macro and add it to a toolbar, you've essentially customized what happens when you click the button. UIControls, however, provide a way to enrich an application in addition to button clicks and menu selections. The event procedures associated with these controls allow you to respond to user interaction and update controls based on the state of the application. Because UIControls can appear on menus or toolbars, they may allow you to avoid having to display a dialog box or user form in order to get input from the user.

Object library

ArcGIS is component object model (COM)-based, and the system is built and extended using the ArcObject software components. ArcObjects are an integrated collection of cross-platform GIS software components that are client/server ready. The ArcGIS family of applications relies on ArcObjects to provide data management, map presentation functionality, and more. There is an extensive ArcObjects object library available to help you customize applications in ArcGIS Desktop. The ESRI Developer Network (EDN) describes the classes, interfaces, properties, methods, and enumerations that are available in the development that is core to applications, such as ArcMap and ArcCatalog.
As an ArcObjects developer, you should be familiar with the ArcGIS developer guides, which outline the development options open to you. You can find these guides, such as Extending ArcObjects, on http://edn.esri.com.

Types of UIControls you can create

You can create the following types of UIControls in VBA:

• The UIButtonControl works similarly to the core buttons that come with the application. Typically, you use a UIButtonControl to start, end, or interrupt an action or series of actions. You can write code to determine whether or not the button appears enabled or pressed in on the toolbar. You can also set its ToolTip, provide a message that will appear in the status bar, and respond to its Click event.
  
• The UIToolControl works similarly to the core tools that come with the application. Typically, you use a UIToolControl to perform some type of interaction with the display. You can write code to toggle whether the tool appears as enabled, set its message for the status bar, or set its ToolTip. You can respond to mouse and key events. In addition, you can have it respond when the user selects the tool and double-clicks or right-clicks it. You can write code for the UIToolControl when the map refreshes or when the tool is deactivated.
  
• The UIComboBoxControl works similarly to the combo boxes that appear as part of the interface. It combines the features of a text box and a list box. Typically, you use a UIComboBoxControl to provide a set of choices from which a selection can be made. You can also type into the edit box portion of the control. The combo box has methods that allow you to populate its list or remove individual or all items. Several properties associated with the combo box allow you to work with items, return the index of the selected item, return the text at a specific index, return the text in the control's edit box, and determine how many items are in the control. In addition, you can respond to several events, including when the user makes a change in the edit portion of the control or when a change to the selection occurs. As with the UIButtonControl, you can set the control's ToolTip and provide a status bar message.
  
• The UIEditBoxControl works similarly to the edit boxes (or text boxes) that appear as part of the interface. Typically, you use a UIEditBoxControl to display information entered by the user. The control can also display data derived from an external source. You can use its Clear method to remove its contents, and its Text property contains the text that's displayed. You can specify whether the control appears as enabled. In addition, you can respond when the user makes a change or presses a key. As with the UIButtonControl, you can set this control's ToolTip and provide a status bar message.
  

How to create custom commands with VBA

1. Click the View menu, point to Toolbars, then click the toolbar to which you want to add a new command.
   
2. Click the Tools menu and click Customize.
   
3. Click the Commands tab.
   
4. Click the drop-down arrow on the Save in combo box, then click the document or template in which the new command will be saved.
   
5. Click [UIControls] in the Categories list.
   
6. Click New UIControl.
   
7. Click the type of UIControl you want to create.
   
8. Click Create to create the control without attaching code to it.
   
The name of the control appears in the Commands list. You can add code for the control at another time. If you want to start adding code to the control right away, click Create and Edit and skip to step 13.

9. Click the newly created UIControl, click it again to activate in-place editing, then type a new name for the control.
   
10. Click and drag the newly created UIControl and drop it on a toolbar or menu.
    
11. On the toolbar or menu, right-click the command to set its image, caption, and other properties.
    
12. Right-click the new command on the toolbar or menu, then click View Source.
    
The Visual Basic Editor appears, displaying the control's code in the Code window.

13. Click the Procedures/Events drop-down arrow and click one of the control's event procedures.
    
14. Type code for the event procedure.
    
15. Repeat steps 13 and 14 until all the appropriate event procedures have been coded.
    
16. Click Save on the Visual Basic Editor.
    
17. Click the Close button on the Visual Basic Editor.
    
18. If you clicked Create and Edit in step 8, open the Customize dialog box, click the Commands tab, and drag the newly created UIControl from the Commands list to a toolbar or menu.
    
19. Click Close on the Customize dialog box.
    

Tips

The UIControl you are creating is in design mode while the VBE is open. The code that you have written for the properties and events doesn't get executed while the control is in design mode. To fully test your new command, you must close the VBE. If a search string is entered in the 'Show commands containing' text field, you may not see the new UIControl added to the Commands list after clicking the 'New UIControl' button. Cancel the command list filtering by clearing the search string in the text field.

Please visit the Feedback page to comment or give suggestions on ArcGIS Desktop Help.
Copyright © Environmental Systems Research Institute, Inc.