How to add a context menu using the Visual Studio Integration tools

Summary
This topic outlines the steps to create a context menu to display on a form that hosts an ArcGIS Engine control. A context menu (also known as a shortcut menu) usually appears when a user right-clicks an item in an application, for example, a map selection, a layer in the table of contents (TOC), or a toolbar. It contains commands that are specifically associated with the objects over which the mouse pointer is positioned. A custom context menu can be created with the help of the ArcGIS Context Menu template installed with ArcGIS Visual Studio integrated development environment (IDE) Integration Framework from the .NET software development kit (SDK).

Adding a context menu using an ArcGIS item template

Do the following steps to add a context menu using an ArcGIS item template:
  1. Add a context menu item to your project—You can define a custom context menu for an ArcGIS Engine application by selecting the Context Menu template on the Add New Item dialog box. For more information about accessing the Add New Item dialog box in Visual Studio, see Using item templates to extend ArcObjects. 

     The item template is located under the ArcGIS node on the Categories pane. Click Add to add a class to your project that has the context menu template code. The class name (EngineContextMenu1.cs) is the same as the file name defined on the Add New Item dialog box.

    The following screen shot shows the Add New Item dialog box with the current project in C#:
This class uses the ToolBarMenuClass to implement an ArcGIS Engine context menu.
  1. Add commands to the context menu—A custom context menu is defined by a list of ArcGIS Engine commands and custom commands, or ArcGIS Engine commands or custom commands. Each command is identified by its unique identifier object (UID), which is a combination of a ProgID or class identifier (CLSID) and the subtype code. Define these command items inside the SetHook() method in the newly created context menu class. Use the overloaded AddItem() helper methods to add commands to your context menu definition. To add a separator between commands, call BeginGroup(). 

    In the following code example, modify the commented code after TODO: Define context menu items here:
[C#] 
public class EngineContextMenu1
{
    ... public void SetHook(object hook)
    {
        m_toolbarMenu = new ToolbarMenuClass();
        m_toolbarMenu.SetHook(hook);
        //
        // TODO: Define context menu items here.
        //
        AddItem(new Guid("B100C679-76C5-410D-BC8D-AE9E7882A80F"),  - 1); 
            //Add data command.
        BeginGroup();
        AddItem("esriControls.ControlsMapZoomOutFixedCommand",  - 1);
        AddItem("esriControls.ControlsMapZoomInFixedCommand",  - 1);
    }
    ...
}
[VB.NET] 
Public Class EngineContextMenu1
    …

    Public Sub SetHook(ByVal hook As Object)
        m_toolbarMenu = New ToolbarMenuClass()
        m_toolbarMenu.SetHook(hook)
        '
        ' TODO: Define context menu items here.
        '
        AddItem(New Guid("B100C679-76C5-410D-BC8D-AE9E7882A80F"), -1) 'Add data command.
        BeginGroup()
        AddItem("esriControls.ControlsMapZoomOutFixedCommand", -1)
        AddItem("esriControls.ControlsMapZoomInFixedCommand", -1)
    End Sub

    …
End Class
The custom context menu class is now ready to use in your ArcGIS Engine application.

Displaying the custom context menu

Do the following steps to display the custom context menu:
  1. Create and design a form—Create and design a form that houses the ArcGIS Engine control (the hook object) to be associated with the custom context menu. A context menu is typically associated with one of the following ArcGIS Engine controls:
    • MapControl
    • PageLayoutControl
    • TOCControl
    • ToolbarControl
    • GlobeControl
    • SceneControl
    • SymbologyControl
The following screen shot shows the available ArcGIS Engine controls in Visual Studio's toolbox. Drag and drop these controls onto your form from the ArcGIS Windows Forms list in the toolbox.
  1. Declare and instantiate the custom context menu—This is typically done in the form class where the associated control is placed. See the following code example:
[C#] 
public partial class Form1: Form
{
    //Declare the menu class as a member variable.
    private EngineContextMenu1 m_contextMenu = new EngineContextMenu1();
    ...
}
[VB.NET] 
Public Class Form1
    'Declare the menu class as a member variable.
    Private m_contextMenu As New EngineContextMenu1()
    …
End Class
  1. Hook the menu with an ArcGIS Engine control—Set the hook object for the custom context menu via the hook parameter in the SetHook() method. This is typically done once, before the context menu appears; for example, Form_OnLoad.
    1. Pass the object property of the ArcGIS Engine control you placed on the form. See the following code example:
[C#] 
private void Form1_Load(object sender, EventArgs e)
{
    //Pass MapControl as the hook. 
    m_contextMenu.SetHook(axMapControl1.Object);
}
[VB.NET] 
Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
    'Pass MapControl as the hook.
    m_contextMenu.SetHook(axMapControl1.Object)
End Sub
    1. If your application contains a ToolbarControl, and its buddy control is the same control your context menu works with, you can pass the ToolbarControl or its buddy as the hook object. The IToolbarMenu.CommandPool property should share the IToolbarControl.CommandPool property to ensure that only one instance of a particular command is created within the application. See the following code example:
[C#] 
private void Form1_Load(object sender, EventArgs e)
{
    //Pass the ToolbarControl's buddy as the hook. 
    IToolbarControl toolbarControl = (IToolbarControl)axToolbarControl1.Object;
    m_contextMenu.SetHook(toolbarControl.Buddy);

    //Get the IToolbarMenu2 interface from the custom context menu.
    IToolbarMenu2 toolbarMenu = m_contextMenu.ContextMenu;
    toolbarMenu.CommandPool = toolbarControl.CommandPool;
}
[VB.NET] 
Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
    'Pass the ToolbarControl's buddy as the hook.
    Dim toolbarControl As IToolbarControl = DirectCast(axToolbarControl1.Object, IToolbarControl)
    m_contextMenu.SetHook(toolbarControl.Buddy)
    
    'Get the IToolbarMenu2 interface from the custom context menu.
    Dim toolbarMenu As IToolbarMenu2 = m_contextMenu.ContextMenu
    toolbarMenu.CommandPool = toolbarControl.CommandPool
End Sub
  1. Display the custom context menu—To have the context menu appear when the user right-clicks an item, call the PopupMenu() method with the pop-up location and the handle of the parent control. This is typically done in the OnMouseDown event for the control on the form where you want the context menu to appear. See the following code example:
[C#] 
private void axMapControl1_OnMouseDown(object sender,
    IMapControlEvents2_OnMouseDownEvent e)
{
    //Show the context menu when the user right-clicks.
    if (e.button == 2)
        m_contextMenu.PopupMenu(e.x, e.y, axMapControl1.hWnd);
}
[VB.NET] 
Private Sub AxMapControl1_OnMouseDown(ByVal sender As System.Object, ByVal e As ESRI.ArcGIS.Controls.IMapControlEvents2_OnMouseDownEvent) Handles axMapControl1.OnMouseDown
    'Show the context menu when the user right-clicks.
    If e.button = 2 Then
        m_contextMenu.PopupMenu(e.x, e.y, axMapControl1.hWnd)
    End If
End Sub
If you need to change the context menu dynamically at run time, use the read-only ContextMenu property of the custom context menu class, and call the appropriate members on the IToolbarMenu2 interface returned.


See Also:

Using item templates to extend ArcObjects
Code snippet: Create PopUp ToolbarMenu



Additional Requirements
  • ArcGIS Visual Studio Integration Framework, Visual Basic Express, or Visual C# Express editions.

Development licensing Deployment licensing
Engine Developer Kit Engine