Create a custom tool

Click here to get the sample associated with this walkthrough.

About creating a custom tool

Create a class library

1. Start Visual Studio.
   

Add references

Delete the class1 file

Create a DrawGraphicLine tool

1. On the Solution Explorer, right-click the project, click Add, and click Add New Item.
2. On the Add New Item dialog box, under the Categories area, click the Visual Basic Items node and click ArcGIS. Click Base Tool under the Templates area. Name the class DrawGraphicLine.cs (C#) or DrawGraphicLine.vb (VB .NET), and click Add. See the following screen shot:
   
   
   
   When the ArcGIS New Item Wizard Options dialog box appears, click Desktop ArcMap Tool, and click OK.
3. By default, a bitmap is added to the project and will be the icon you click in ArcMap to use for your custom tool. Customize the bitmap with the image editor by double-clicking DrawGraphicLine.bmp on the Solution Explorer and use the Visual Studio tools to design your .bmp file. Alternatively, you can browse for an existing image such as a .png file. See the following screen shot:
   
   
   
   Understand and edit DrawGraphicLine class template

• Imports (VB .NET) or using (C#) statements have been added to the DrawGraphicLine class. Since these are shortcuts, you do not have to fully qualify your code in the code editor. To have the Imports or using statements, it is required that .NET assemblies be added to the project. This was done automatically as part of the ArcGIS Add Item templates for the Tool class. No modification of this code section is required for the walkthrough.
• The DrawGraphicLine class inherits from the BaseTool abstract class. The BaseTool class uses the implementation of ITool and ICommand, which makes coding easier. Abstract classes are classes that cannot be instantiated and are frequently partially implemented or not implemented. Abstract classes are closely related to interfaces; however, they differ significantly from interfaces in that a class can implement any number of interfaces, but it can inherit from only one abstract class. No modification of this code section is required for the walkthrough.
• Component Object Model (COM) registration functions and COM globally unique identifiers (GUIDs) sections are automatically added and are embedded within collapsible #Region (VB .NET) or #region (C#) statements. Since ArcObjects are a COM-based application, it is necessary to have the .NET created .dlls be supported by COM. These code sections allow ArcObjects to use .NET code. For more information, see Using ArcObjects (COM-based) in .NET and Binary compatibility. Edit these sections if you want different GUIDs or want to add the tool to additional component categories.
• A private member variable (m_application) is provided and will be set in the OnCreate event (or method) as the hook object from the calling application passed into the DrawGraphicLine class. Since ArcMap consumes the custom .dll, the hook object (ArcMap.exe) is passed into the OnCreate event of the DrawGraphicLine class. This event sets the m_application variable which is of type ESRI.ArcGIS.Framework.IApplication and begins the entry point for your tool to perform its functionality.
• Other events (or methods) are automatically stubbed out for the DrawGraphicLine tool (OnClick, OnMouseDown, OnMouseMove, and OnMouseUp). More information can be found for these methods in the ArcObjects library reference in the ESRI.ArcGIS.ADF.BaseTool class methods documentation. Of particular interest is the OnMouseDown method in which custom code will be written. For more information, see Coding the OnMouseDown method section in this walkthrough. The OnMouseDown method fires when the user previously clicked the DrawGraphicLine tool to activate it, then clicks the data view of ArcMap.
• The final piece of template code is the constructor. The constructor code is important because it notifies ArcMap about the DrawGraphicLine tool class and how it can be used on the graphical user interface (GUI). Modify the constructor to use the functionality by ArcMap. Modify the code to resemble the following code example:
  

public DrawGraphicLine()
{
    //
    // TODO: Define values for the public properties.
    //
    base.m_category="Walkthroughs"; //Localizable text. 
    base.m_caption="Draw Graphic Line"; //Localizable text. 
    base.m_message=""; //Localizable text.
    base.m_toolTip="Draws a graphic line in the map window of ArcMap."; 
        //Localizable text.
    base.m_name="CustomTool_DrawGraphicLine"; 
        //Unique ID, nonlocalizable (for example, "MyCategory_ArcMapTool").
    try
    {
        //
        // TODO: If necessary, change the resource name.
        //
        string bitmapResourceName=GetType().Name + ".bmp";
        base.m_bitmap=new Bitmap(GetType(), bitmapResourceName);
        base.m_cursor=new System.Windows.Forms.Cursor(GetType(), GetType().Name + 
            ".cur");
    }
    catch (Exception ex)
    {
        System.Diagnostics.Trace.WriteLine(ex.Message, "Invalid Bitmap");
    }
}

Public Sub New()
    MyBase.New()
    ' TODO: Define values for the public properties.
    MyBase.m_category="Walkthroughs" 'Localizable text.
    MyBase.m_caption="Draw Graphic Line" 'Localizable text.
    MyBase.m_message="" 'Localizable text.
    MyBase.m_toolTip="Draws a graphic line in the map window of ArcMap." 'Localizable text.
    MyBase.m_name="CustomTool_DrawGraphicLine" 'Unique ID, nonlocalizable (for example, "MyCategory_ArcMapTool").
    
    Try
    'TODO: If necessary, change the resource name.
    Dim bitmapResourceName As String=Me.GetType().Name + ".bmp"
    MyBase.m_bitmap=New Bitmap(Me.GetType(), bitmapResourceName)
    MyBase.m_cursor=New System.Windows.Forms.Cursor(Me.GetType(), Me.GetType().Name + ".cur")
    Catch ex As Exception
    System.Diagnostics.Trace.WriteLine(ex.Message, "Invalid Bitmap")
    End Try
    
End Sub

Add ArcGIS snippets functionality to DrawGraphicLine tool template

1. To access ArcGIS snippets, right-click the Visual Studio code editor window at the necessary insertion point (before the end of the class file), and Insert Snippet: Double-click `ArcObjects` from the popup window. Double-click 'Mapping'. Double click 'Map Documents' and Double-click 'Get ActiveView from ArcMap', the code snippet gets added.
   You will add three ArcGIS snippets to the DrawGraphicLine class (add these snippets to the DrawGraphicLine.vb [VB .NET] or DrawGraphicLine.cs [C#] file at the bottom of the class file).
   

#region "Get ActiveView from ArcMap"
///<summary>Get ActiveView from ArcMap.</summary>
///<param name="application">An IApplication interface that is the ArcMap application.</param>
///<returns>An IActiveView interface.</returns>
///<remarks></remarks>
public IActiveView GetActiveViewFromArcMap(IApplication application)
{
    if (application == null)
    {
        return null;
    }
    IMxDocument mxDocument=application.Document as IMxDocument; // Dynamic cast.
    IActiveView activeView=mxDocument.ActiveView;
    return activeView;
}

#endregion

#Region "Get ActiveView from ArcMap"
'''<summary>Get ActiveView from ArcMap</summary>
'''<param name="application">An IApplication interface that is the ArcMap application.</param>
'''<returns>An IActiveView interface.</returns>
'''<remarks></remarks>

Public Function GetActiveViewFromArcMap(ByVal application As IApplication) As IActiveView
    
    If application Is Nothing Then
        Return Nothing
    End If
    
    Dim mxDocument As IMxDocument=TryCast(application.Document, IMxDocument) ' Dynamic cast.
    Dim activeView As IActiveView=mxDocument.ActiveView
    
    Return activeView
    
End Function

#End Region

#region "Get Polyline From Mouse Clicks"
///<summary>
///Create a polyline geometry object using the RubberBand.TrackNew method when a user clicks on the map control. 
///</summary>
///<param name="activeView">
An ESRI.ArcGIS.Carto.IActiveView interface that users interact with to draw a
    polyline. <  / param > 
///<returns>An ESRI.ArcGIS.Geometry.IPolyline interface that is the polyline the user draws.</returns>
///<remarks>Double-click to end tracking the polyline.</remarks>
public IPolyline GetPolylineFromMouseClicks(IActiveView activeView)
{
    IScreenDisplay screenDisplay=activeView.ScreenDisplay;

    IRubberBand rubberBand=new RubberLineClass();
    IGeometry geometry=rubberBand.TrackNew(screenDisplay, null);

    IPolyline polyline=(IPolyline)geometry;

    return polyline;
}

#endregion

#Region "Get Polyline From Mouse Clicks"
'''<summary>
'''Create a polyline geometry object using the RubberBand.TrackNew method when a user clicks on the map control.
'''</summary>
'''<param name="activeView">An ESRI.ArcGIS.Carto.IActiveView interface that users interacts with to draw a polyline.</param>
'''<returns>An ESRI.ArcGIS.Geometry.IPolyline interface that is the polyline the user draws.</returns>
'''<remarks>Double-click to end tracking the polyline.</remarks>

Public Function GetPolylineFromMouseClicks(ByVal activeView As IActiveView) As IPolyline
    
    Dim screenDisplay As IScreenDisplay=activeView.ScreenDisplay
    
    Dim rubberBand As IRubberBand=New RubberLineClass
    Dim geometry As IGeometry=rubberBand.TrackNew(screenDisplay, Nothing)
    
    Dim polyline As IPolyline=CType(geometry, IPolyline)
    
    Return polyline
    
End Function

#End Region

#region "Add Graphic to Map"
///<summary>Draw a specified graphic on the map using the supplied colors.</summary>
///<param name="map">An IMap interface.</param>
///<param name="geometry">An IGeometry interface. It can be of the geometry type: esriGeometryPoint, esriGeometryPolyline, or esriGeometryPolygon.</param>
///<param name="rgbColor">An IRgbColor interface. The color to draw the geometry.</param>
///<param name="outlineRgbColor">An IRgbColor interface. Geometries with an outline will be this color.</param>
///<remarks>Calling this function will not automatically make the graphics appear in the map area. Refresh the map area after calling this function with methods, such as, IActiveView.Refresh or IActiveView.PartialRefresh.</remarks>
public void AddGraphicToMap(IMap map, IGeometry geometry, IRgbColor rgbColor,
    IRgbColor outlineRgbColor)
{
    IGraphicsContainer graphicsContainer=(IGraphicsContainer)map; // Explicit cast.
    IElement element=null;

    if ((geometry.GeometryType) == esriGeometryType.esriGeometryPoint)
    {
        // Marker symbols.
        ISimpleMarkerSymbol simpleMarkerSymbol=new SimpleMarkerSymbolClass();
        simpleMarkerSymbol.Color=rgbColor;
        simpleMarkerSymbol.Outline=true;
        simpleMarkerSymbol.OutlineColor=outlineRgbColor;
        simpleMarkerSymbol.Size=15;
        simpleMarkerSymbol.Style=esriSimpleMarkerStyle.esriSMSCircle;
        IMarkerElement markerElement=new MarkerElementClass();
        markerElement.Symbol=simpleMarkerSymbol;
        element=(IElement)markerElement; // Explicit cast.
    }
    else if ((geometry.GeometryType) == esriGeometryType.esriGeometryPolyline)
    {
        //  Line elements.
        ISimpleLineSymbol simpleLineSymbol=new SimpleLineSymbolClass();
        simpleLineSymbol.Color=rgbColor;
        simpleLineSymbol.Style=esriSimpleLineStyle.esriSLSSolid;
        simpleLineSymbol.Width=5;
        ILineElement lineElement=new LineElementClass();
        lineElement.Symbol=simpleLineSymbol;
        element=(IElement)lineElement; // Explicit cast.
    }
    else if ((geometry.GeometryType) == esriGeometryType.esriGeometryPolygon)
    {
        // Polygon elements.
        ISimpleFillSymbol simpleFillSymbol=new SimpleFillSymbolClass();
        simpleFillSymbol.Color=rgbColor;
        simpleFillSymbol.Style=esriSimpleFillStyle.esriSFSForwardDiagonal;
        IFillShapeElement fillShapeElement=new PolygonElementClass();
        fillShapeElement.Symbol=simpleFillSymbol;
        element=(IElement)fillShapeElement; // Explicit cast.
    }

    if (!(element == null))
    {
        element.Geometry=geometry;
        graphicsContainer.AddElement(element, 0);
    }

}

#endregion

#Region "Add Graphic to Map"
'''<summary>Draw a specified graphic on the map using the supplied colors.</summary>
'''<param name="map">An IMap interface.</param>
'''<param name="geometry">An IGeometry interface. It can be of the geometry type: esriGeometryPoint, esriGeometryPolyline, or esriGeometryPolygon.</param>
'''<param name="rgbColor">An IRgbColor interface. The color to draw the geometry.</param>
'''<param name="outlineRgbColor">An IRgbColor interface. Geometries with an outline will be this color.</param>
'''<remarks></remarks>

Public Sub AddGraphicToMap(ByVal map As IMap, ByVal geometry As IGeometry, ByVal rgbColor As IRgbColor, ByVal outlineRgbColor As IRgbColor)
    
    Dim graphicsContainer As IGraphicsContainer=CType(map, IGraphicsContainer) ' Explicit cast.
    Dim element As IElement=Nothing
    
    If (geometry.GeometryType)=esriGeometryType.esriGeometryPoint Then
        
        ' Marker symbols.
        Dim simpleMarkerSymbol As ISimpleMarkerSymbol=New SimpleMarkerSymbolClass()
        simpleMarkerSymbol.Color=rgbColor
        simpleMarkerSymbol.Outline=True
        simpleMarkerSymbol.OutlineColor=outlineRgbColor
        simpleMarkerSymbol.Size=15
        simpleMarkerSymbol.Style=esriSimpleMarkerStyle.esriSMSCircle
        Dim markerElement As IMarkerElement=New MarkerElementClass()
        markerElement.Symbol=simpleMarkerSymbol
        element=CType(markerElement, IElement) ' Explicit cast.
        
    ElseIf (geometry.GeometryType)=esriGeometryType.esriGeometryPolyline Then
        
        '  Line elements.
        Dim simpleLineSymbol As ISimpleLineSymbol=New SimpleLineSymbolClass()
        simpleLineSymbol.Color=rgbColor
        simpleLineSymbol.Style=esriSimpleLineStyle.esriSLSSolid
        simpleLineSymbol.Width=5
        Dim lineElement As ILineElement=New LineElementClass()
        lineElement.Symbol=simpleLineSymbol
        element=CType(lineElement, IElement) ' Explicit cast.
        
    ElseIf (geometry.GeometryType)=esriGeometryType.esriGeometryPolygon Then
        
        ' Polygon elements.
        Dim simpleFillSymbol As ISimpleFillSymbol=New SimpleFillSymbolClass()
        simpleFillSymbol.Color=rgbColor
        simpleFillSymbol.Style=esriSimpleFillStyle.esriSFSForwardDiagonal
        Dim fillShapeElement As IFillShapeElement=New PolygonElementClass()
        fillShapeElement.Symbol=simpleFillSymbol
        element=CType(fillShapeElement, IElement) ' Explicit cast.
        
    End If
    
    If Not (element Is Nothing) Then
        
        element.Geometry=geometry
        graphicsContainer.AddElement(element, 0)
        
    End If
    
End Sub

#End Region

Code the OnMouseDown method

public override void OnMouseDown(int Button, int Shift, int X, int Y)
{
    //TODO: Add DrawGraphicLine_VB.OnMouseDown implementation.

    //Get the active view from the application object (that is, hook).
    IActiveView activeView=GetActiveViewFromArcMap(m_application);

    //Get the polyline object from the user's mouse clicks.
    IPolyline polyline=GetPolylineFromMouseClicks(activeView);

    //Make a color to draw the polyline. 
    IRgbColor rgbColor=ESRI.ArcGIS.ADF.Converter.ToRGBColor(Color.FromArgb(255, 0,
        0));

    //Add the user's drawn graphics as persistent on the map.
    AddGraphicToMap(activeView.FocusMap, polyline, rgbColor, rgbColor);

    //Only redraw the portion of the active view that contains graphics. 
    activeView.PartialRefresh(esriViewDrawPhase.esriViewGraphics, null, null);
}

Public Overrides Sub OnMouseDown(ByVal Button As Integer, ByVal Shift As Integer, ByVal X As Integer, ByVal Y As Integer)
'TODO: Add DrawGraphicLine.OnMouseDown implementation.

'Get the active view from the application object (that is, hook).
Dim activeView As IActiveView=GetActiveViewFromArcMap(m_application)

'Get the polyline object from the user's mouse clicks.
Dim polyline As IPolyline=GetPolylineFromMouseClicks(activeView)

'Make a color to draw the polyline.
Dim rgbColor As IRgbColor=ESRI.ArcGIS.ADF.Converter.ToRGBColor(Color.FromArgb(255, 0, 0))

'Add the user's drawn graphics as persistent on the map.
AddGraphicToMap(activeView.FocusMap, polyline, rgbColor, rgbColor)

'Only redraw the portion of the active view that contains graphics.
activeView.PartialRefresh(esriViewDrawPhase.esriViewGraphics, Nothing, Nothing)

End Sub

Compile the project

1. Save the project.
2. Click the Build menu and click Build Solution. 
3. View the Output window at the bottom of the Visual Studio .NET IDE. If the project builds correctly, a report shows that the build succeeded.
   

Use the tool in ArcMap

1. Start ArcMap and open a map document with data layers.
2. Click the Tools menu and click Customize. The Customize dialog box appears.
3. Click the Commands tab and click Walkthroughs under the Categories area. See the following screen shot:
   

 

4. In the Commands area under the Commands tab, click Draw Graphic Line and drag it on the ArcMap GUI in the toolbar section. Close the Customize dialog box. See the following screen shot:
   
   Click the added tool on the toolbar.
5. Click the map window, move the mouse, click again several times to draw a polyline, and double-click to finish the drawing. See the following screen shot:
   
   When you finish drawing graphics on the map, click the Select Elements tool to select the graphic and press Delete to remove the graphic. See the following screen shot:
   
   
   
   
   Debug the tool

1. Return to the solution in the Visual Studio IDE.
2. Verify that ArcMap.exe is set as the external program to use for debugging. This is another feature set for you by the ArcGIS project template when you create your project.
   1. Right-click the CustomTool project in the Solution Explorer window and click Properties.
   2. Click the Debug tab on the property page.
   3. Under the Start Action area, select Start external program to use ArcMap.exe in the Bin folder of your ArcGIS install directory. See the following screen shot:
      

3. In the code window for the DrawGraphicLine, find the OnMouseDown method and set a breakpoint. See the following screen shot:
   

4. Click the Debug menu and click Start Debugging (or press F5). Visual Studio runs ArcMap. When the user clicks the map area  in ArcMap, the debugger returns to Visual Studio and allows you to step through the code one line at a time with the buttons on the debugging toolbar.

Deploy the tool

See Also: