How to create an add-in tool

Summary This document will guide you through the workflow for creating a tool using the Eclipse integrated development environment (IDE). After the workflow is presented the documentation takes a closer look at the abstract Tool class and defines additional methods available to you when creating your tools.

In this topic

About the tool

A tool is very similar to a button. However, a tool requires user interaction with the desktop application’s display first, and then based on that interaction executes some business logic. The zoom in tool in ArcMap is a good example that requires that an end user click or drag a rectangle over a map before the display is redrawn to show the map contents in greater detail for the specified area.
The following will guide you through the process of creating a tool using the Eclipse IDE. Before beginning this workflow, you must make sure that you have created a new ArcMap add-in project using Eclipse (see How to create an add-in project in Eclipse for details). Since there is no difference between creating a tool for any one of the ArcGIS Desktop applications, this workflow shows you how to create a tool for ArcMap.
 
The workflow for creating a tool in Eclipse consists of the following three steps:
  1. Creating a new tool
  2. Setting properties
  3. Creating a Java class and defining your business logic
 
Step 1 will examine the process of create a new tool in Eclipse.  Step 2 will examine all of the properties that can be set for the tool with detailed descriptions for each property.  The final step examines the creation of a Java class that is used to define all the business logic for the tool.

Creating a new tool

The following will show you how to create a new tool for an existing Eclipse add-in project. Please ensure that you have the add-in view enabled for the add-in editor on the config.xml file and that you have filled out the required overview properties.
  1. Under all add-ins, click the add button.


    You are presented with a dialog box asking you which type of customization you wish to create. Notice that all 8 different types of add-ins are presented to you at this point.
  1. Choose tool and click OK.
A new section of the editor now appears with various properties for you to set for your new tool. By default, the id*, class*, caption*, and category*are filled in for you with default values to help expedite the development process. Also, observe the warning symbol under tool details and next to the class* property. This indicates to you that the Java class for your new tool has not been created yet. At a latter step in this workflow you will learn how to create your new Java class and where you will write your business logic. For now, the following figure shows you the new tool details section that is added to the editor with default values.

Setting properties

A tool has a number of properties for you to set. The following is a list of all of the properties with an explanation for each:
  • id* - The id represents the unique name that is used to identify your tool. It is possible for you to create more than one tool for a given project and this id property is used to distinguish between the different tools. Notice that the image shows a default value for this property. Ideally, you should replace this id with a more meaningful name. It is also highly recommended that the Java package naming convention is used when constructing your id property value. For example, com.esri.arcgis.arcmap.addin.arcmaptool could be used to represent the tool being created for this document (Required).
  • class* - The class property is used to identify the Java class for your tool. The Java class is where you will write your business logic. This class is important because it is called whenever the tool is invoked in a desktop application. To create a new class you can click on the class property itself – notice that the class property is blue and underlined to indicate this to you. It is also highly recommended that the Java package naming convention is used when constructing your class. For example, com.esri.arcgis.addin.ArcMapTool could be used to represent the tool class being created (Required).
  • caption* - The caption property is used to give a name to the tool and is used in two different locations after a project is deployed (Required).

    The first location is in the Add-In Manager where the caption is used as meta-data to help a user identify types of customizations available.  The following example uses a value of "ArcMap Tool" for the caption property and is exposed in the Add-In Manager as follows (notice the type of add-in is identified in brackets):

    The second place that the caption is used is when an end user is adding the tool to the user interface (UI) of a desktop application. The workflow for doing so is discussed in How to deploy your add-in. For reference, the customize dialog’s commands tab is used and will use the caption defined under the commands text area as follows:
  • category* - The category property is used to give a name that can identify your add-ins as a group. A given category can have more than one by supplying the same name for the category property in each add-in defined. For example, you could have a category that can contain all your add-ins for ArcMap, like a button, tool, toolbar, and so on. To achieve this you need to give the same category value for each type of add-in defined in your project (Required).

    Identical to the caption property, the category property is visible in two locations, first is the Add-In Manager (notice that the category explicitly identifies this property):

    The second place that the category is used is when an end user is locating the add-in project in the Customize Dialog in a desktop application. The Customize Dialog’s Commands tab lists a number of Categories (for example: Animation, ArcScan, and so on), and the category property value you set is used in this list to identify your add-in type(s):
  • cursor - A 16x16 pixel image that can be used to represent your cursor. The cursor image is used when a user clicks on the tool in a desktop application. The cursor image must have a .cur extension. The Browse button allows you to add a reference to the cursor image (Optional).
  • image - A 16x16 pixel image that can be used to represent your tool. This image is used in the customize dialog’s commands tab to symbolize your tool and also is used by default when your tool is added to the UI of a desktop application. The image itself can be placed in your project and the browse button allows you to add a reference to this image (Optional).
  • tooltip - A tooltip is a brief description of your tool that can be used to intuitively help your end user use your tool or remind them of the tool’s purpose. The tooltip appears when the mouse pointer pauses over the tool in a desktop application. A message dialog then displays with the message supplied for this property (Optional).
  • message - A message is a more detailed description of your tool that describes in greater detail what your tool will do. Identical to the tooltip, the message appears when the mouse pointer pauses over the tool in a desktop application in conjunction with the tooltip. This message appears with the value supplied with this property in the status bar of a desktop application, which is located in the lower left corner (Optional).
The final section of the tool details portion of the add-in editor, help content, is for the help content you can supply a user with. These properties allow you to supply information that will be used when a user invokes context-sensitive help. These are generally short pop-up topics that remain on-screen until a user clicks somewhere else.
The following properties comprise this context-sensitive help and are explained further here:
  • Heading - A header to indicate what the text is about (Optional).
  • Content - The content property is where you place the content for the tool (Optional).

Creating a Java class and defining your business logic

At this stage, you have finished entering values for all of the properties needed to define your tool. The final step in this workflow is to create a Java class that will contain your business logic. To create the new Java class, do the following:
  1. Click the class* property found under button details.
A new Java class dialog box will appear with a few pre-populated form boxes. The one of interest is the superclass property. This property is grayed out automatically because a tool class that you create must inherit the abstract class Tool from the com.esri.arcgis.addins.desktop package. This abstract class is what is used to hide the implementation details for making your tool work with the desktop applications.
  1. Enter a package for your new class, then enter a name for the Java class file and click finish.
A class, in this instance called "ArcMapTool", similar to the one generated next:
[Java] 
public class ArcMapTool extends Tool{
    @Override public void activate()throws IOException, AutomationException{}
    @Override public void mousePressed(MouseEvent arg0){}
}
The generated class file has two significant pieces. The first is the use of the extends keyword to inherit from the abstract class Tool (a required piece that contains the necessary plumbing code to get your tool to work with desktop applications). The second is the auto-generated activate() method that is stubbed out in the source code. The activate() method is important because this is where you will write logic to define the action performed by your tool when is activated in a desktop application (called once the user clicks on the tool). Typically, you will not just work with the activate() method alone, but in conjunction with another method, like mousePressed(), to build your tools. The mousePressed() method is an action that you can write business logic for and will be called when the mouse is pressed by a user in the desktop application display area. This differs from a button, because a tool requires end user action before the business logic is executed - a subtle, but important difference. Depending on what you are attempting to achieve with your tool, your business logic will be placed in the method accordingly.
The next example prints a message dialog with the "Hello, World!" message when the tool is activated and a user clicks in the data or layout views in ArcMap. For instructions on how to deploy the tool, see How to deploy your add-in for further details.
[Java] 
public class ArcMapTool extends Tool{
    @Override public void activate()throws IOException, AutomationException{}
    @Override public void mousePressed(MouseEvent arg0){
        JOptionPane.showMessageDialog(null, "Hello, World!");
    }
}

About the abstract class Tool

The abstract class Tool provides you with a set of additional methods that can be overridden, but are not required like the activate() method; however, are necessary to make your tool useful. Twelve such methods exist and are described here in detail.

deactivate() method

The deactivate() method is called by the ArcGIS Desktop framework when the tool is active and the user selects another tool instead of using the active selected tool to deactivate it. If appropriate, this method can be overridden with a Boolean test to determine if this tool should be deactivated.

init() method

When working with one of the ArcGIS Desktop applications it is quite possible that you might need to access various items within the applications. For example, in ArcMap you might wish to access the map (that is, data frame) or layers contained within a map. Your Java application cannot just instantiate an instance of the ArcMap application; instead you are passed a reference to an object that will give you the application that the tool is contained within. The init() method serves this purpose as well as defining any logic that is necessary to initialize your tool (for example: instantiate objects that are needed in your mousePressed() method as one example). How then are you able to get an object that points to the desktop application your tool is hosted in? First, you need to write some code to hold onto the IApplication object that is passed into the init() method when it is invoked. This can be achieved with the following initialization code:
[Java] 
private IApplication app;
@Override public void init(IApplication app){
    this.app = app;
}
Once you have a reference to the application object, you can use it to get a reference to the desktop application the tool is being used in with the following code:
  1. Obtain an object reference to ArcMap:
[Java] 
IMxDocument mxDocument = (IMxDocument)app.getDocument();
  1. Obtain an object reference to ArcCatalog:
[Java] 
IGxDocument gxDocument = (IGxDocument)app.getDocument();
  1. Obtain an object reference to ArcGlobe:
[Java] 
IGMxDocument gMxDocument = (IGMxDocument)app.getDocument();
  1. Get an object reference to ArcScene:
[Java] 
ISxDocument sxDocument = (ISxDocument)app.getDocument();

isChecked() method

In some special circumstances it might be important for you to determine if your tool has been executed or not. The isChecked() method reports this state of a tool, where by default it is set to false. When this method returns true, the tool appears as though it is depressed in the desktop application as the following example shows.
A system event is periodically called to set the status of tools on toolbars, thus determining if a tool is checked or not. If a condition is used to determine this status, the logic should not be complicated or lengthy for this reason.

isEnabled() method

The following method allows you to add some logic to specify in what state the desktop application should be in for the tool to be enabled and thus allow someone to click it. For example, you might have a tool that requires a data layer to be loaded in ArcMap before execution is possible. The isEnabled() method allows you to write logic to test if a layer is present or not. If a layer has been added to ArcMap, then the tool is enabled, otherwise, it remains disabled until that action is performed. Similar to the isChecked() method, a system event is called to check if a tool is enabled or not.

keyPressed() method

The keyPressed() method is invoked when a key is pressed on the keyboard while the tool is active. Business logic can be written to respond to any key or a specific key on the keyboard.  The KeyEvent that is generated and passed into the keyPressed() method comes from the java.awt.event package.

keyReleased() method

The keyReleased() method is invoked when a key is released on the keyboard while the tool is active. Business logic can be written to respond to any key or a specific key on the keyboard. The KeyEvent that is generated and passed into the keyReleased() method comes from the java.awt.event package.

mouseMoved() method

The mouseMoved() method is invoked when the mouse is moved while the tool is active. Business logic can be written to respond to mouse movement in the display of the desktop applications. The MouseEvent that is generated and passed into the mouseMoved() method comes from the java.awt.event package.

mousePressed() method

The mousePressed() method is invoked when the mouse button is pressed while the tool is active. Business logic can be written to respond to a mouse click in the display of the desktop applications. The MouseEvent that is generated and passed into the mousePressed() method comes from the java.awt.event package.

mouseReleased() method

The mouseReleased() method is invoked when the mouse button is released while the tool is active. Business logic can be written to respond to a mouse click's release in the display of the desktop applications. The MouseEvent that is generated and passed into the mouseReleased() method comes from the java.awt.event package.

onContextMenu() method

The onContextMenu() method is invoked when a context menu event occurs at a given XY location. A context menu is initiated when a right-click is done and a popup menu appears. Business logic can be written to respond to a context menu and the x, y coordinates of the location clicked are passed to this method. It is possible to expose different business logic depending on where the user invoked the context menu.

onDoubleClick() method

The onDoubleClick() method is invoked when a double-click is performed by the user and the tool is active. Business logic can be written to respond to this double-click action.

refresh() method

The refresh() method is invoked when the screen display in the desktop application is refreshed.  Business logic can be written while the refresh() method is being invoked.
Instead of writing code to stub out all of these methods, Eclipse provides you with a mechanism for including any one or all of the preceding methods into your source code and it also helps you avoid typos. To insert any one or all of the methods into your Java class source code, right-click anywhere in the source code editor in Eclipse and select source > override/implement methods. The following dialog will give you the ability to add any one or all of the methods defined.

Understanding the XML

When setting all of the properties, the raw XML for the config.xml file was being generated behind the scenes for you. To understand more about how this config.xml file is defined, see Understanding the config.xml document.

Creating different types of customizations

The following documentation showed you how to create a tool. However, there are 7 additional types of add-ins that can be created and defined. The following links will take you to those documents.


See Also:

Understanding the config.xml



Development licensing Deployment licensing
ArcView ArcView
ArcEditor ArcEditor
ArcInfo ArcInfo