Using the control commands


In this topic


About using the control commands

The control commands are commands, tools, tool controls, toolsets, menus, and palettes that work with the ArcGIS Engine controls to perform specific actions. For example, there is a suite of map navigation, map inquiry, feature selection, graphic element, feature editing, and ink commands that work with the MapControl and PageLayoutControl; a suite of globe commands that work with the GlobeControl; a suite of scene commands that work with the SceneControl; and a suite of network and schematic commands that work with the ArcGIS Network Analyst and ArcGIS Schematics extensions, respectively. You can extend these suites of control commands by creating customized commands that perform a specific piece of work.
For a full list of the control commands, including a description of each, its associated globally unique identifier (GUID), the ArcGIS Engine controls with which the command works, and any extension required, see ArcGIS Engine commands.

Control commands with the ToolbarControl

For applications using the ToolbarControl in conjunction with a buddy control, these commands can be added to the ToolbarControl in one of the following three ways:
  • Through the ToolbarControl property pages at design time.
  • Programmatically using the AddItem, AddMenuItem, and AddToolbarDef methods. The commands can be added to a ToolbarMenu using the AddItem and AddSubMenu methods, and the commands can be added to a ToolbarPalette using the AddItem method.
  • By the end user if the ToolbarControl is in customize mode.

Control commands without the ToolbarControl

While building applications with the ToolbarControl can quickly provide pieces of a framework similar to the ArcGIS Desktop application framework, there are times when the ToolbarControl is not required for an application—the visual appearance of the ToolbarControl might not match that of the application, the overhead of implementing Command objects for the ToolbarControl is not required, or there is an existing application framework in the application.
The control commands can work directly with the MapControl, PageLayoutControl, GlobeControl, and SceneControl by programmatically creating an instance of a command and passing either the MapControl, PageLayoutControl, GlobeControl, or SceneControl to the ICommand.OnCreate method. The developer becomes responsible for calling the ICommand.OnCreate and ICommand.OnClick methods at the appropriate times and reading properties on the ICommand interface to build up the user interface (UI) as follows:
  • A new instance of a command is created programmatically and the individual ArcGIS control is passed to the OnCreate event. For example, if the Zoom FullExtent command is to work with the MapControl, the MapControl must be passed as the hook to the OnCreate method.
  • A developer can use the CommandPool object without the ToolbarControl to manage the commands used by an application. The CommandPool provides support for calling the OnCreate method of each command based on its Hook property.
  • If the command implements only the ICommand interface, you can call the OnClick method at the appropriate time to perform the specific action. If the command is a tool that implements both the ICommand and ITool interfaces, set the tool to be the CurrentTool in the ArcGIS control. The ArcGIS control sends any keyboard and mouse events to the tool.
  • A command's Enabled, Caption, and Bitmap properties can be read and set into the properties of a command button supplied by the development environment to build up the application's UI.
See the following code example:
[C#]
ICommand command = new ControlsSelectFeaturesToolClass();
command.OnCreate(axMapControl1.Object);
axMapControl1.CurrentTool = (ITool)command;
[VB.NET]
Dim pCommand As ICommand
pCommand = New ControlsSelectFeaturesToolClass
pCommand.OnCreate(AxMapControl1.Object)
AxMapControl1.CurrentTool = pCommand

Create custom commands

To extend the suite of control commands, you can create custom commands, tools, menus, and palettes to work with the ArcGIS Engine controls. The HookHelper, GlobeHookHelper, and SceneHookHelper objects can be used to simplify this development. The HookHelper object makes it straightforward to create a command that works with the MapControl, PageLayoutControl, ToolbarControl, and the ArcMap application; the GlobeHookHelper to create a command that works with the GlobeControl, ToolbarControl, and the ArcGlobe application; and the SceneHookHelper to create a command that works with the SceneControl, ToolbarControl, and the ArcScene application.
You do not need to add code to an ICommand.OnCreate method to determine the type of hook passed to the command. The following shows how the HookHelper, GlobeHookHelper, and SceneHookHelper objects handle this instead:
See the following code example:
[C#]
public sealed class Command1: BaseCommand
{
    private IHookHelper m_pHookHelper;

    public override void OnCreate(object hook)
    {
        if (m_pHookHelper == null)
            m_pHookHelper = new HookHelperClass();
        m_pHookHelper.Hook = hook;
    }
}
[VB.NET]
Public NotInheritable Class Command1
Inherits BaseCommand

Private m_pHookHelper As IHookHelper

Public Overrides Sub OnCreate(ByVal hook As Object)
If (m_pHookHelper Is Nothing) Then m_pHookHelper = New HookHelperClass
m_pHookHelper.Hook = hook
End Sub

End Class
When a change is made to the HookHelper, GlobeHookHelper, and SceneHookHelper objects, the IHookHelperEvents.OnHookUpdated event is fired. For example, the event is fired in response to the IToolbarControlEvents.OnBuddyChanged event and the IPageLayoutControlEvents.OnPageLayoutReplaced event. Use the event to resync any member variables storing IHookHelper, IGlobeHookHelper, and ISceneHookHelper properties and to resync any event listeners, such as IActiveViewEvents.
HookHelper and GlobeHookHelper both implement the IHookActions interface, which provides methods to flash, pan, or zoom and create graphics, labels, and callouts on the specified IPoint, IEnvelope, IPolyline, and IPolygon interfaces. For example, the DoActionOnMultiple method could be used to zoom to the extent of the selected features in the map.
See the following code example:
[C#]
public override void OnClick()
{
    ESRI.ArcGIS.esriSystem.Array myArray = new ESRI.ArcGIS.esriSystem.Array();
    ISelection selection = m_pHookHelper.FocusMap.FeatureSelection;
    IEnumFeature enumFeature = (IEnumFeature)selection;
    IFeature feature;

    //Add the selected features' geometry to the array.
    enumFeature.Reset();
    feature = enumFeature.Next();
    do
    {
        myArray.Add(feature.Shape);
        feature = enumFeature.Next();
    }
    while (feature != null);

    //If zooming is supported, zoom to the selected features.
    IHookActions hookActions = (IHookActions)m_pHookHelper;
    if (hookActions.get_ActionSupportedOnMultiple(myArray,
        esriHookActions.esriHookActionsZoom) == true)
        hookActions.DoActionOnMultiple(myArray, esriHookActions.esriHookActionsZoom);
}
[VB.NET]
Public Overrides Sub OnClick()
Dim myArray As ESRI.ArcGIS.esriSystem.Array = New ESRI.ArcGIS.esriSystem.Array
Dim selection As ISelection = m_pHookHelper.FocusMap.FeatureSelection
Dim enumFeature As IEnumFeature = selection, feature As IFeature

'Add the selected features' geometry to the array.
enumFeature.Reset()
feature = enumFeature.Next
Do Until feature Is Nothing
    myArray.Add(feature.Shape)
    feature = enumFeature.Next
Loop

'If zooming is supported, zoom to the selected features.
Dim hookActions As IHookActions = m_pHookHelper
If (hookActions.ActionSupportedOnMultiple(myArray, esriHookActions.esriHookActionsZoom) = True) Then
    hookActions.DoActionOnMultiple(myArray, esriHookActions.esriHookActionsZoom)
End If
End Sub

Singleton objects

There are several singleton objects that support only one instance of the object per process used by the control commands (see the following objects, as well as the topic Interacting with singleton objects). You can also use these objects in your custom commands.


See Also:

Controls library overview
Interacting with singleton objects
How to create a command or tool to work with the controls
How to provide context-sensitive help for a custom command
Sample: Committing ink sketches using the controls ink commands
Sample: Controls commands environment
Sample: Configure a command for a specific locale
Sample: Custom map navigation commands
Sample: Custom map selection commands
Sample: Custom scene navigation commands
Sample: Feature editing with the control commands
Sample: Using HookActions in custom commands
Sample: Graphics layers ToolControl
Using the swipe and transparency commands
Using the flicker commands
Using the roam command




Development licensing Deployment licensing
Engine Developer Kit Engine Runtime
ArcView
ArcEditor
ArcInfo