Building custom UI elements using add-ins

Click here to get the sample associated with this walkthrough.

About building custom UI elements

• Buttons
• Tools
• Construction Tools
• Tool palettes
• Combo boxes
• Menus
• Toolbars
• Multi-items
• Dockable windows

Creating a custom button and tool

Creating a Visual Studio project

1. Start Visual Studio. 
2. Click File, select New, and click Project. The New Project dialog box appears. 
3. Under Project types, expand the Visual Basic or Visual C# project node, expand the ArcGIS node, and click Desktop Add-Ins.

4. Select the ArcMap Add-in template in the Templates pane. Add-in customizations are specific to ArcGIS for Desktop applications and can also be created for ArcCatalog, ArcScene, and ArcGlobe. 
5. Name the project CustomUIElements and browse to the location where you want to save the project. See the following screen shot:
   
    
6. Click OK to close the dialog box and open the ArcGIS Add-Ins Wizard.  

Using the ArcGIS Add-Ins Wizard

1. On the Welcome page, fill in the basic information about the add-in: name, company/publisher, description, and the image. The metadata information you provide about an add-in on the Welcome page displays on the Add-In Manager dialog box. Add the information as shown in the following screen shot:
   
   

2. Click Next. The Available Add-in Components page appears. The Add-in Types section on the left lists the type of customizations that you can add to your add-in. 
3. Under Add-in Types, select the Button check box. The declarative properties of the button, such as caption, image, and ToolTip become active.
4. Add the button information as shown in the following screen shot:
   
   
   
   You can find help tips about each entry in the dialog box by hovering the mouse pointer over the appropriate help icon. The ZoomToLayerButton class will be the managed class that implements the run time behavior of the button. The managed class will be created by the wizard.
5. Select the Tool check box to add a custom tool to the add-in.
6. Type AddGraphicsTool as the class name, which must implement the run time behavior of the tool, and add the other declarative properties of the tool as shown in the following screen shot:
   
   
7. Click Finish. An add-in project is created. The following screen shot shows the files created by the wizard as seen in the Solution Explorer:
   
   

Understanding the XML

1. Each metadata element defined in the add-in has a significant purpose. The Add-in Manager relies on the name, description, version, image, author, and company elements to provide a description of the installed add-ins. The AddInID element uniquely identifies the add-in. To guarantee uniqueness, this is typically a globally unique identifier (GUID). The Add-in installation utility relies on the AddInID and Version elements.
2. The Targets element specifies the most compatible version and product of ArcGIS for the add-in. The Add-in installation utility will install the add-in only to the product and version specified in the Targets element. At present, the only legal values for the name and version attributes are Desktop and 10.0, respectively.
   
   

3. The AddIn element is the parent element that includes all the add-in customization elements. The language attribute on the AddIn element specifies the programming environment of the add-in. The supported values are component language runtime (CLR), which indicates a .NET managed add-in, and Java, which indicates a Java add-in. The library attribute indicates to the add-in framework the related assembly to load. Though add-in files can contain multiple assemblies, most rely on a single assembly. The namespace attribute is the default namespace for all classes in the assembly.
4. The ArcMap element denotes that the specified add-in customizations are for the ArcMap application. You can also create add-in custom components for ArcCatalog, ArcScene, and ArcGlobe.
5. All your custom button, tool, tool palette, multi-item, and combo box add-in components must be defined in the Commands element. You can define any number of buttons, tools, combo boxes, and tool palettes in the Commands XML element.
6. The Tool element denotes the custom AddGraphics tool that you created through the wizard. The class attribute specifies the corresponding managed class that defines the run time behavior of the tool. The id attribute uniquely identifies the custom tool across all customizations. The tool is identified by the unique id when included in other customizations such as  a toolbar or menu. You can find more information about the attributes of the Tool element by hovering your mouse over the attribute or refer to the add-in XML reference document.
7. The Button element denotes the custom ZoomToLayer button that you created through the wizard. The ZoomToLayerButton class attribute specifies the corresponding managed class in which the run time behavior of the button must be described. The id attribute is the unique ID of the button and serves the same purpose as that of the Tool element. See the following screen shot:
   
   

Adding ZoomToLayer functionality to the custom button

1. Open the ZoomToLayerButton C# or VB.NET class file. The custom button must inherit from the ESRI.ArcGIS.Desktop.AddIns.Button abstract class and must override the following two methods:
• OnClick—This method is invoked and executed when the custom button is clicked in ArcMap.
• OnUpdate—This method is invoked and executed at frequent intervals (in milliseconds) to update the enabled and checked status of the button. See Add-in coding patterns for more information about this method. 
2. To implement ZoomToLayer functionality in your button, use the ArcGIS Snippet Finder tool. The ArcGIS Snippet Finder tool provides code snippets for common workflows. You can insert the code in your managed class as needed. To implement the ZoomToLayerFunctionality, perform the following steps: 
1. Right-click the Visual Studio code editor window at the desired insertion point. 
2. Select ArcGIS Snippet Finder from the context menu. The ArcGIS Snippet Finder dialog box appears. 
3. Type zoom in the Keyword(s) text field to narrow your search of ArcGIS snippets, and click Search. 
4. Select the Zoom to Active Layer in TOC snippet, and click Insert Code to embed the snippet into your Visual Studio code editor. See the following screen shot:
   
   
3. Invoke the ZoomToLayer method upon OnClick() method implementation. The ZoomToLayer() method requires IMxDocument as method parameters. The ArcGIS Add-Ins Wizard creates static classes depending on the customizations in your add-in in the config.designer.cs file. Since you're building an ArcMap component, the add-in template generated an ArcMap class with several static members—such as Application and Document—for you to use. Use the object browser to get a complete list of all the class members. See the following screen shot:
   
   
   The following code example utilizes the static instances:

protected override void OnClick()
{
    ZoomToActiveLayerInTOC(ArcMap.Application.Document as IMxDocument);
}

Protected Overrides Sub OnClick()
ZoomToActiveLayerInTOC(TryCast(ArcMap.Application.Document, IMxDocument))
End Sub

Adding AddGraphics functionality to the custom tool

1. Open the AddGraphicsTool.cs class file. The custom tool class must inherit from the ESRI.ArcGIS.Desktop.AddIns.Tool abstract base class and must override the OnUpdate() method. The wizard generates the plumbing code for you. The Tool base class provides several methods to capture the UI events—such as OnMouseDown() and OnMouseUp. You can override any of these methods depending on the behavior of your custom tool. The OnMouseDown() method must be overridden for the AddGraphics tool.
2. Before you override the OnMouseDown() method, you must implement the AddGraphics functionality as an independent method using the ArcGIS Snippet Finder as shown in the following steps:
1. Right-click the Visual Studio code editor window at the desired insertion point.
2. Select ArcGIS Snippet Finder from the context menu. The ArcGIS Snippet Finder dialog box appears.
3. Type add graphic in the Keyword(s) text field and click Search.
4. Select the Add Graphic to Map snippet and click Insert Code. See the following screen shot:
   
   

protected override void OnMouseDown(ESRI.ArcGIS.Desktop.AddIns.Tool.MouseEventArgs
    arg)
{
    //Get the active view from the ArcMap static class.
    IActiveView activeView = ArcMap.Document.ActiveView;
    //If it's a polyline object, get from the user's mouse clicks.
    IPolyline polyline = GetPolylineFromMouseClicks(activeView);
    //Make a color to draw the polyline. 

    IRgbColor rgbColor = new RgbColorClass();
    rgbColor.Red = 255;
    //Add the user's drawn graphics as persistent on the map.
    AddGraphicToMap(activeView.FocusMap, polyline, rgbColor, rgbColor);
    //Best practice: Redraw only the portion of the active view that contains graphics. 
    activeView.PartialRefresh(esriViewDrawPhase.esriViewGraphics, null, null);
}

Protected Overrides Sub OnMouseDown(ByVal arg As ESRI.ArcGIS.Desktop.AddIns.Tool.MouseEventArgs)
MyBase.OnMouseDown(arg)
'Get the active view from the ArcMap static class.
Dim activeView As IActiveView = My.ArcMap.Document.ActiveView
'If it's a polyline object, get from the user's mouse clicks.
Dim polyline As IPolyline = GetPolylineFromMouseClicks(activeView)
'Make a color to draw the polyline.
Dim rgbColor As IRgbColor = New RgbColorClass()
rgbColor.Red = 255
'Add the user's drawn graphics as persistent on the map.
AddGraphicToMap(activeView.FocusMap, polyline, rgbColor, rgbColor)
'Best practice: Redraw only the portion of the active view that contains graphics.
activeView.PartialRefresh(esriViewDrawPhase.esriViewGraphics, Nothing, Nothing)
End Sub

Installing the custom button and tool

1. Save the project. 
2. Click the Build menu and select Build Solution.
3. View the output window in your Visual Studio .NET IDE. If the project builds correctly, the necessary files for customization are bundled as an add-in file (.ESRIAddIn) and installed using the ESRIRegasm utility. These steps are conducted automatically by a post-build MSBuild task included by the wizard in your project.

Testing the custom button and tool

1. Start ArcMap and open a map document.
2. Click Customize and click Add-In Manager. The Add-In Manager dialog box appears. The Add-In Manager dialog box lists the installed add-ins that are targeting the current application. Add-in information—such as name, image, and description—is included in the Add-In Manager dialog box. See the following screen shot:
   
   

Creating a custom combo box

1. Open the CustomUIElement project that you previously created.
2. In the Project Explorer, right-click your project, select Add, and click New Item. The Add New Item dialog box appears as shown in the following screen shot:
   
   

Adding functionality to the custom combo box

public ArcGISAddin1()
{
    string[] serviceLinks = 
    {
        "Add a World Map Service", "World_Topo_Map", "World_Terrain_Base"
    };
    foreach (string currLink in serviceLinks)
    {
        Add(currLink);
    }

}

protected override void OnSelChange(int cookie)
{
    string selectedURL = null;
    // The value property provides the selected item.
    switch (Value)
    {
        case "World_Topo_Map":
            {
                selectedURL = 
                    "http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer?f=lyr&v=9.2";
                break;

            }
        case "World_Terrain_Base":
            {
                selectedURL = 
                    "http://services.arcgisonline.com/ArcGIS/rest/services/World_Terrain_Base/MapServer?f=lyr&v=9.2";
                break;
            }
    }
    if (selectedURL != null)
    {
        System.Diagnostics.Process.Start(selectedURL);
    }
    base.OnSelChange(cookie);
}

Public Sub New()
    Dim serviceLinks As String() = {"Add a World Map Service", "World_Topo_Map", "World_Terrain_Base"}
    For Each currLink As String In serviceLinks
        Add(currLink)
    Next
End Sub

Protected Overloads Overrides Sub OnSelChange(ByVal cookie As Integer)
Dim selectedURL As String = Nothing
' The value property provides the selected item.
Select Case Value
    Case "World_Topo_Map"
        If True Then
            selectedURL = "http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer?f=lyr&v=9.2"
            Exit Select
        End If
    Case "World_Terrain_Base"
        If True Then
            selectedURL = "http://services.arcgisonline.com/ArcGIS/rest/services/World_Terrain_Base/MapServer?f=lyr&v=9.2"
            Exit Select
        End If
End Select
If selectedURL IsNot Nothing Then
    System.Diagnostics.Process.Start(selectedURL)
End If
MyBase.OnSelChange(cookie)
End Sub

Installing the custom combo box

1. In Visual Studio, save the project.
2. Click the Build menu and click Build Solution.
3. View the output window in your Visual Studio .NET IDE. If the project builds correctly, the output shows that the build has succeeded and the add-in has been deployed to the user location. You can also verify the installation of the add-in using the Add-In Manager dialog box.

Testing the custom combo box

1. Start ArcMap and open a map document.
2. Click the Customize menu and click Customize Mode. The Customize dialog box appears.
3. Click the Commands tab and scroll to the Add-In Controls category. See the following screen shot:
   
   

Creating a custom toolbar

1. In Visual Studio, in the Project Explorer, right-click your project, select New Item, and click Add. The Add New Item dialog box appears.
2. Expand the Visual Basic or Visual C# project node, expand the ArcGIS node, and select Desktop Add-ins.
3. Select Add-in Command Container from the Templates pane and click Add. The ArcGIS Add-Ins Wizard opens.
4. Click Add-in Command Bars, and select Toolbar.
5. Type DharmaToolbar in the Caption field.
6. Click Add Item to add items to the toolbar. A toolbar can contain one or more buttons, tools, combo boxes, menus, and tool palettes. A drop-down box appears listing the custom add-in components in the project.
7. Add custom add-in components from your project to the toolbar, as well as any built-in menu, tool, button, or combo box using its ProgID or class identifier (CLSID) as shown in the following screen shot:
   
   
8. Click Finish. The appropriate XML elements are added to create a custom toolbar as shown in the following screen shot:
   
   

Installing the custom toolbar

1. Save the project.
2. Click the Build menu and click Build Solution.
3. View the output window in your Visual Studio .NET IDE. If the project builds correctly, the output shows that the build has succeeded and the add-in has been deployed to the user location.

Testing the custom toolbar

1. Start ArcMap and open a map document.
2. Click Customize and click Customize Mode. The Customize dialog box appears.
3. Click the Toolbars tab and select Dharma Toolbar as shown in the following screen shot:
   
   
4. Click Close. The custom toolbar is added to ArcMap as shown in the following screen shot:
   
   

Creating a custom menu

1. In Visual Studio, in the Project Explorer, right-click your project, select New Item, and click Add. The Add New Item dialog box appears.
2. Expand the Visual Basic or Visual C# project node, expand the ArcGIS node, and select Desktop Add-ins.
3. Select Add-in Command Container from the Templates pane and click Add. The ArcGIS Add-Ins Wizard opens.
4. Click Add-in Command Bars, and select Menu.
5. Type Zoom Commands in the Caption field.
6. Click Add item to add items to your menu. You can select and add the custom buttons and menus already defined in the add-in from the drop-down list. You can also add other built-in or custom items using their ProgID or CLSID. See the following screen shot:
   
    
7. Click Finish. The appropriate XML elements are added to the config.esriaddinx XML file as shown in the following screen shot. Any custom menu created through the add-ins can also be added as a sub-menu.
   
8. Add the menu to the custom toolbar by specifying the menu's ProgID.

Installing the custom menu

1. Save the project.
2. Click the Build menu and click Build Solution.
3. View the output window in your Visual Studio .NET IDE. If the project builds correctly, the output shows that the build has succeeded and the add-in has been deployed to the user location.

Testing the custom menu

1. Start ArcMap and open a map document. (If ArcMap is already open, close the application and start it again.) The custom menu you created has been added to the custom add-in toolbar. See the following screen shot:
   
    
2. If the custom add-in toolbar does not display, follow these steps:
1. Click Customize and click Customize Mode. The Customize dialog box appears.
2. Select Dharma Toolbar and click Close.

Uninstalling an add-in

1. In ArcMap, click Customize, and click Add-In Manager. The Add-In Manager dialog box appears.
2. Select the CustomUIElement add-in and click Uninstall Add-In. This moves the add-in from your add-ins folder to the system's recycle bin.

See Also: