Creating a Python add-in tool—Help

Creating an add-in tool

Creating an add-in tool

A tool is very similar to a button. However, a tool requires user interaction with the desktop application's display first and, based on that interaction, executes some business logic. The Zoom In tool Zoom In in ArcMap is a good example—it requires that you click or drag a rectangle over a map before the display is redrawn, showing the map contents in greater detail for the specified area.

This topic guides you through the process of creating a tool on a new toolbar using the Python Add-In Wizard. Before beginning this workflow, make sure that you have created an ArcMap add-in project and specified the project settings. For more information, see Creating an add-in project. While this workflow shows you how to create a tool for ArcMap, you can use this process to add a tool to any ArcGIS Desktopapplication. This topic examines the process of creating a simple Create Fishnet tool. The Python class created by the add-in wizard is then examined in greater detail to explore the properties and methods that provide functionality to your tool.

Creating an add-in tool consists of the following steps:

Create a toolbar.
Click the Add-In Contents tab and begin declaring your add-in customizations. A tool can reside on a toolbar but not on a menu. See Creating an add-in toolbar for steps on creating your own toolbar.

Create the tool.

Right-click the new toolbar and choose New Tool.

A tool has a number of properties for you to set. The following is a list of all the properties with an explanation for each. These properties are stored in the config.xml file for the project.

Property	Description
Caption (required)	Defines the tool's caption. The following illustration shows the caption used as in the ArcGIS Add-In Manager to help identify the different types of customizations available (the type of add-in is identified in parentheses): The next illustration shows the caption used as the text to identify the tool on the toolbar:
Class (required)	The Python class representing your tool. The Python class is where you write your business logic for the tool. This class is important because it is executed whenever the tool is clicked in a desktop application. Use the Python naming convention when constructing your class. Python classes use CapWords notation. In this example, create a class named CreateFishnet is created.
ID (required)	The unique name used to identify your tool. It is possible for you to create more than one tool for a given project, and this ID is used to distinguish between the different tools. Ideally, you should replace the default ID with a more meaningful value. The ID should not contain any spaces. You can use underscores to connect words. You should not use Python keywords. Consult the Python documentation for reserved words.
Tooltip (optional)	A brief description that appears when the mouse pointer pauses over the tool in a desktop application.
Message (optional)	A more detailed description of the tool that describes what the tool does. Identical to the ToolTip, the message appears when the mouse pointer pauses over the tool in conjunction with the ToolTip.
Image (optional)	This should be a 16 by 16 pixel image used to symbolize your tool. The image format can only be one of the following formats: .png, .gif, or .bmp). The image will be copied to the Images folder created in your add-in project.

The final section of the tool is the help heading and content. These properties allow you to supply information that appears when a user invokes context-sensitive help. These are pop-up topics that remain on-screen until the user clicks somewhere else.

The following properties comprise this context-sensitive help section:

Property	Description
Heading (optional)	Indicates what the help content is about
Content (optional)	The help content for the tool

Once you have finished entering the properties, click Save at the bottom of the wizard. All the necessary files and folders are created within your working folder.

Edit the Python script and update the Python class to include the functionality for creating a fishnet of polygons.

An area of interest is defined by dragging the mouse to create a rectangle. The size of the fishnet is set to 10 rows by 10 columns. To add the functionality to the custom tool, perform the following steps:

Edit the Python script in the Install folder located in the working folder you created through the wizard.
A class will exist with the same name as entered through the wizard. Do not rename this class as the class name is referenced in config.xml. For the explanation of each function and property of the class, see the Tool class topic.

Update the functions as shown below.

This code provides the functionality to create a fishnet of polygons with 10 rows and 10 columns.

def __init__(self):
    self.enabled = True
    self.cursor = 3
    self.shape = 'Rectangle'
    
def onRectangle(self, rectangle_geometry):
    """Occurs when the rectangle is drawn and the mouse button is released.
    The rectangle is a extent object."""

    extent = rectangle_geometry
    # Create a fishnet with 10 rows and 10 columns.
    if arcpy.Exists(r'in_memory\fishnet'):
        arcpy.Delete_management(r'in_memory\fishnet')
    fishnet = arcpy.CreateFishnet_management(r'in_memory\fishnet',
                            '%f %f' %(extent.XMin, extent.YMin),
                            '%f %f' %(extent.XMin, extent.YMax),
                            0, 0, 10, 10,
                            '%f %f' %(extent.XMax, extent.YMax),'NO_LABELS',
                            '%f %f %f %f' %(extent.XMin, extent.YMin, extent.XMax, extent.YMax), 'POLYGON')
    arcpy.RefreshActiveView()
    return fishnet

Save the script.

Testing the tool
Once the tool is created and the script code is added, it is important to make the add-in file and test the add-in before sharing it. For these steps, see Testing an add-in.
Deploy and share the add-in.
For steps on deploying and sharing the add-in, see Sharing add-ins.

Creating an add-in tool

Related topics