ESRI Command Creation Wizard
The Command Creation Wizard facilitates the creation of a command or tool for use within ArcMap, ArcCatalog, the ArcGIS Controls, or a combination of these. For instance, a tool written for ArcMap may also be suitable for the MapControl or PageLayoutControl. It is possible to quickly develop commands and tools without this wizard using the interface implementer and the Compile and Register Add-ins, but this wizard has many features that make the addition of commands straightforward.
To access the add-in, click ESRI Command Wizard from the Add-Ins menu in Visual Basic. An introduction screen will display.
Introduction screen
This screen has information about the wizard. When you complete the wizard, it compiles and registers the project automatically. The project will only be saved to file if you select this option at the start of the wizard.
The first step of the wizard displays only if the project was not saved prior to executing the wizard. It is advisable to save the project at the start of the wizard, as this will also ensure that the project is saved on completion.
Step 1
When you save a project using the wizard, if no filenames have been assigned to modules you are prompted to enter the filenames. In addition, you can elect to check for default names. If you enabled these options, the wizard checks the names of modules and if a default name is detected, you are prompted to enter a new name. Default names are not a good idea since there is less chance that the programmable ID will be unique.
The wizard always performs the next step, project compilation, either after you save the project, or when the wizard starts. If the project fails to compile, the wizard displays step 2. You have no other choice but to fix the compilation error and rerun the wizard.
Step 2
The next step involves selecting the target application in which the command will operate. Not all commands are suitable for all application environments. For example, a Select tool used to select features on a map could be used within the ArcMap application, the MapControl and the ToolbarControl, since the topmost object that must be accessed is the Map, and all these these environments expose a map object; however, a Select tool may not be suitable for ArcCatalog since it does not expose a Map object.
The graphic below illustrates the choices made. You must select at least one application in order to continue on to the next step.
Step 3
Step 4 of the wizard allows you to determine various properties of the code that the wizard generates.
Step 4
You can add the generated source code to an existing class within your project. This option is only enabled if there is a suitable class module within your active project. The wizard disregards any class that already implements the ICommand interface. If the wizard does create a new class, it assigns the class the name of the Commands caption, minus any spaces, prepended by “cls”.
The Error Handlers option controls whether the wizard adds error-handling code to the functions. All functions should have an error handler, but if you do not wish to use the generic ESRI error handler you can disable the creation of the error handlers and add your own.
Verbose comments can be helpful when starting out with Command development. With this option enabled, several hundred lines of comment code are added.
A number of objects within the ArcObjects object model support outbound event interfaces. To work with these interfaces, a certain amount of plumbing code is required to ensure that the event source and sink are connected. The wizard supports all three common event sources: the MxDocument, PageLayout, and Map objects. None of these options are available if ArcCatalog is set as a target application. When the ArcGIS Controls option is selected, the choice is limited to the Map and Page Layoutevent sources. ArcMap supports all three event sources.
The stub functions the wizard creates will by default contain no lines of code other than error-handling code. The exceptions to this are the functions where code was added because it was required to perform an action, such as setting member variables when the command is created. If the function does not contain automatically generated code you can add a message box to the function. This allows you to see when the application framework calls the function. This can be very helpful when you start to work with events. If the wizard creates a tool, a message box is not added to the OnClick event.
The wizard displays Step 5 only if you chose to add the code to a class already in the project. If there is only one class, the wizard displays the class in the list with its check box selected; otherwise, you must select a class before continuing.
Step 5
The wizard displays step 6 only if you chose to listen to Document events in step 4. The NewDocument and OpenDocument events are mandatory as these are required to maintain the source sink connection as new documents are created or loaded.
Step 6
If you do not select an event to implement, it is straightforward to add the event later. You must select the variable DocumentEvents in the Object combo box of the Visual Basic editor, and the required event is selected in Visual Basic’s Procedure combo box.
The wizard displays step 7 only if you chose to listen to Map events in step 4. The wizard assigns the event handler to the variable MapActiveViewEvents.
Step 7
The wizard displays step 8 only if you chose to listen to PageLayout events in step 4. The wizard assigns the event handler to the variable PageActiveViewEvents.
Step 8
Step 9 allows you to select whether to create a command or a tool. A command has the majority of the functionality coded within the OnClick event, whereas a tool is used to handle user interaction with the ActiveView (Map or PageLayout). Typically this involves handling mouse events, such as mouse down, mouse move, and mouse up.
Step 9
Both commands and tools must implement the ICommand interface. Step 10 allows you to specify the properties of the ICommand interface. The name of the command is automatically generated from the category and caption entries. This can be changed if required. If the command has a bitmap, it can be added by selecting a bitmap file. If the bitmap uses a masking color, this can also be selected by clicking in the Mask color box on the form.
Step 10
The bitmap is added to an image list named using the class name prepended with “iml”, and the image is keyed with the string “Bitmap”. The image list is added to a form module with the name of frmResources. If the module is not present in the project the wizard adds a form module. The wizard remembers the path of the bitmap file, and will open the bitmap file browser at that path on subsequent calls.
The option to Enable conditionally allows you to select when the command will be enabled with the application, based on some preset conditions. Step 11 covers these options. The Checked when active option is only available for commands, since tools are automatically checked by the application when they are the active tool. When a button on a toolbar is checked the button appears depressed; when the button is on a menu, a small checkmark is placed to the left of the caption.
The wizard displays step 11 only if you selected the option to Enable conditionally in step 10. These conditions are Data View, Layout View, Data Present, and Edit Status. Data View and Layout View are mutually exclusive. The conditions that you can choose to base the enabling on can be AND’d or OR’d together. If some other combination is required, you must edit the generated source code.
Step 11
The wizard displays step 12 if you are creating a tool. It is a common function of a tool to generate a geometry object through input from the user; the object is then used in a subsequent action. To support this, you can elect to support Display Feedback, which can be in one of the four geometry types. Pressing the mouse button down and moving the cursor creates the Envelope and Circle geometries. When you release the mouse, the wizard creates the geometry. You can create polygon and polyline geometries by pressing the mouse button, each successive button press creates a vertex on the geometry. Double-clicking creates the geometry.
Step 12
A tool normally is in one of two states: passive or active. When the user interacts with the tool, normally by pressing a key or mouse button, the tool is in its active state. When the user is not directly interacting with the tool and the tool is simply the current tool in use, the tool is in its passive state. You can associate cursors with these two states. The cursors are added to an image list named using the class name prepended with “iml”, and the images are keyed with the strings “Active” and “Passive”. The wizard adds the image list to a form module with the name of frmResources. If the module is not present in the project, a form module is added. The wizard remembers the path of the cursor file, and will open the cursor file browser at that path on subsequent calls.
The last panel of the wizard has two options that control the compiling and registration stage, and an option to save all the settings selected during the wizard execution as the defaults. These settings include all check boxes and options, but do not include the command string properties or the bitmap and icons.
Step 13
After the wizard generates all the source code, it compiles the project into a DLL. The wizard then registers the DLL on the system and places the newly created class in the appropriate component category. Only the newly created command is placed in a component category. If there are other classes, the Compile and Register Wizard can be used to register these and create the Registry script for use later with an install program. If required after the successful compile, you can direct the wizard to set the project’s version compatibility mode to the newly compiled DLL by checking the Set Binary Compatibility option. You can view the progress of these various stages by checking the Display Progress Dialogs check box.