Creating a command with a custom interface
ToolControls allow you to add (within reason) any type of window to the toolbar instead of simply displaying a button.
ToolControls were deprecated at ArcGIS 10 as ComboBoxes and ToolPalettes—the main controls implemented using ToolControls—became fully supported types.
Implementing a ToolControl
In .NET, you can implement a ToolControl in a single class that contains the child controls and enables the required interfaces.
Do the following steps to add a ToolControl implementation to an existing project:
- Add a user control to the project and name it appropriately.
- Add a reference to the ESRI.ArcGIS.SystemUI assembly to the project.
- Implement ICommand and IToolControl interfaces and stub out the members.
- Drag and drop controls onto the user control design canvas:
- Be careful when sizing your ToolControl window. Ensure that the entire window area fits onto the restricted height of the toolbar (about 20 pixels) when displayed on a horizontally and vertically docked toolbar.
- Implement the members of the ICommand interface the same way as for a simple button with the following exceptions:
- Caption and Bitmap properties are used mainly on the Customize dialog box. The bitmap also appears as the button on a vertically docked toolbar. Always set the Bitmap property; otherwise, your ToolControl displays as a blank space on a vertical toolbar.
- The Checked property and OnClick method will not be called.
- Remember to switch the enable state of the child controls to reflect the value returned in the Enabled property implementation.
- Implement the members of the IToolControl interface:
- The OnDrop method is used to specify the type of command bar this ToolControl can be put on. In most cases, ToolControls can only be used on toolbars.
- Return the window handle of the user control in the hWnd property.
- Hold on to the ICompletionNotify parameter from the OnFocus method as a class variable. Call the SetComplete method in at least one of the control events to indicate it has completed its actions and can lose focus.
- Handle events of the child control and set up the control properties. For example, fill in the drop-down list in the DropDown event. If the content must be kept up-to-date with any application event, such as document and focus map changes, sink the appropriate events and update your control accordingly:
- Call ICompletionNotify.SetComplete when your ToolControl completes its actions.
Use the ArcGIS Component Category Registrar dialog box to insert registration code.
- Register the class into the appropriate command component categories. See the following:
- ArcMap—ESRI Mx Commands
- ArcCatalog—ESRI Gx Commands
- ArcScene—ESRI Sx Commands
- ArcGlobe—ESRI GMx Commands
- ArcGIS Engine—ESRI Controls Commands
See Also:
Sample: Recently used files—Command, MultiItem, and ComboBoxTo use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
Development licensing | Deployment licensing |
---|---|
ArcGIS for Desktop Basic | ArcGIS for Desktop Basic |
ArcGIS for Desktop Standard | ArcGIS for Desktop Standard |
ArcGIS for Desktop Advanced | ArcGIS for Desktop Advanced |