This document is archived and information here might be outdated.  Recommended version.


How to create a command with a custom interface ToolControl (ArcObjects .NET 10.8 SDK)
ArcObjects Help for .NET developers > ArcObjects Help for .NET developers > Developing with ArcGIS > Learning ArcObjects > Extending ArcObjects > Application framework customizations > Creating commands and tools > How to create a command with a custom interface ToolControl

How to create a command with a custom interface ToolControl


Summary
To create a custom ToolControl object, implement ICommand and IToolControl. Be aware that only one instance of a particular ToolControl is allowed to exist in the application at any time.

In this topic

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:
  1. Add a user control to the project and name it appropriately.
  2. Add a reference to the ESRI.ArcGIS.SystemUI assembly to the project.
  3. Implement ICommand and IToolControl interfaces and stub out the members.
  4. 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.
  5. 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.
  6. 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.
  7. 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:
Use the ArcGIS Component Category Registrar dialog box to insert registration code.
  1. 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:

Samples:

To 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 Desktop Basic ArcGIS Desktop Basic
ArcGIS Desktop Standard ArcGIS Desktop Standard
ArcGIS Desktop Advanced ArcGIS Desktop Advanced