How to create an add-in tool

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

In this topic

About the tool

A tool is to a button; however, a tool requires user interaction with the desktop application's display first, then based on that interaction, executes some business logic. ArcMap's Zoom In tool is a good example that requires an end user to 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.
This topic guides you through the process of creating a tool using the Eclipse IDE. Before beginning this workflow, make sure that you have created an ArcMap add-in project using Eclipse. For more information, see How to create an add-in project in Eclipse.
Since there is no difference between creating a tool for any ArcGIS for Desktop application, this workflow shows you how to create a tool for ArcMap. The workflow for creating a tool in Eclipse consists of the following (done in the order as shown):

Creating a tool

The following shows how to create a tool for an existing Eclipse add-in project. Ensure that you have the Add-In view enabled on the Add-In Editor for the config.xml file and that you have completed the required Add-In Overview properties. See the following screen shot:

  1. Under All Add-ins on the Add-In Editor, click the Add button. The Create New Add-In dialog box appears. See the following screen shot:

  1. Select the Tool option on the preceding screen shot (there are eight different options), then click OK.

    A new section of the Add-In Editor appears with various properties for you to set for your new tool. By default, the id*, class*, caption*, and category*are completed with default values to help expedite the development process. Also, observe the warning symbol under the Tool Details and next to the class* property. This indicates that the Java class for the new tool has not been created. In a later step in this workflow, you will learn how to create your Java class and where you write your business logic. For now, the following screen shot shows you the new Tool Details section that is added to the Add-In 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:
The final section of the Tool Details is Help Content. This section is for the help content you can supply a user with about the tool. These properties allow you to supply information that will be used when a user invokes context-sensitive Help. These are pop-up topics that remain on-screen until a user clicks somewhere else.
The following properties comprise this context-sensitive Help section:

Creating a Java class and defining your business logic

At this stage, you have finished adding values for all of the necessary properties to define the tool. The final step is to create a Java class that contains your business logic. Do the following steps to create the Java class:
  1. Click the class* property found under Button Details. A new Java class dialog box  appears with a few pre-populated form boxes. The one of interest is the superclass property. This property is automatically unavailable 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.
  2. Add a package for your new class, add a name for the Java class file, then click Finish.
A class, in this instance, called ArcMapTool, is similar to the one generated next. See the following code example:
[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 write logic to define the action performed by your tool when it is activated in a desktop application (called once the user clicks the tool). 
Typically, you will not just work with the activate() method alone, but in conjunction with another method, such as 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 clicked 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 following code example prints a message dialog box with the "Hello, World!" message when the tool is activated, and a user clicks the data or layout views in ArcMap. For instructions on how to deploy the tool, see the previously referenced topic, How to deploy your add-in.
[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, but are necessary to make your tool useful. The following sections describe these methods.

deactivate() method

The deactivate() method is called by the ArcGIS for 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 for Desktop applications, it is possible that you might need to access various items within the applications. For example, in ArcMap, you might want 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 gives 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).
To get an object that points to the desktop application your tool is hosted in, write 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 example:
[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 in which the tool is being used.
  1. Obtain an object reference to ArcMap. See the following code example:
[Java] 
IMxDocument mxDocument = (IMxDocument)app.getDocument();
  1. Obtain an object reference to ArcCatalog. See the following code example:
[Java] 
IGxDocument gxDocument = (IGxDocument)app.getDocument();
  1. Obtain an object reference to ArcGlobe. See the following code example:
[Java] 
IGMxDocument gMxDocument = (IGMxDocument)app.getDocument();
  1. Get an object reference to ArcScene. See the following code example:
[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 pressed in the desktop application as the following screen shot 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

This 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, 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 keyboard key is pressed, 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 keyboard key is released, 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 on the display of 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 on the display of 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 on the display of 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 x,y location. A context menu is initiated when a right-click is done and a pop-up menu appears. Business logic can be written to respond to a context menu and the x,y coordinates of the clicked location 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 on 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 a mechanism to include any or all of the preceding methods into your source code, and it also helps to avoid typographical errors.
To insert any or all of the methods into your Java class source code, right-click on Eclipse's source code editor and select Source, then Override/Implement methods. The following Override/Implement Methods dialog box appears, which allows you to add any or all of the defined methods:

Understanding the XML

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

Creating different types of customizations

This topic showed how to create a tool; however, there are additional types of add-ins that can be created and defined. See the following topics that discuss each type of add-in.


See Also:

Understanding the config.xml



Development licensingDeployment licensing
ArcGIS for Desktop BasicArcGIS for Desktop Basic
ArcGIS for Desktop StandardArcGIS for Desktop Standard
ArcGIS for Desktop AdvancedArcGIS for Desktop Advanced