How to create an add-in tool palette

Summary This document will guide you through the workflow for creating a tool palette using the Eclipse integrated development environment (IDE). A tool palette is a container for tools that you have created or other ESRI provided tools.

In this topic

About the tool palette

A tool palette is a container for tools. These tools can be your own tools or the ESRI provided system tools. In addition, tool palettes can only be exposed by adding them to an existing toolbar (see How to create an add-in toolbar for more information on creating your own toolbar).
The following will guide you through the process of creating a tool palette 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 palette for any one of the ArcGIS Desktop applications, this workflow shows you how to create a tool palette that can be consumed in ArcMap. This document will show how the tool palette can be used to contain your tools and/or ESRI provided tools. It will also demonstrate how to expose your tool palette so it can be consumed in ArcMap.
The workflow for creating a tool palette in Eclipse consists of the following four steps:
  1. Creating a new tool palette
  2. Setting properties
  3. Add functionality
  4. Adding the tool palette to a toolbar
 
Step 1 will examine the process of creating a new tool palette in Eclipse. Step 2 will examine all of the properties that can be set for the tool palette with detailed descriptions. Step 3 will examine how existing functionality is added to the tool palette, either your own add-ins or ESRI provided functionality. The final step examines the process of adding a tool palette to a toolbar so it can be exposed in an ArcGIS Desktop application after the project is deployed.

Creating a new tool palette

The following will show you how to create a new tool palette 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 add-in you wish to create.  Notice that all 8 different types of add-ins are presented to you at this point.
  1. Choose tool palette and click OK.
A new section of the editor now appears with various properties for you to set for your new tool palette. By default, the id*, caption*, and category* properties are filled in for you with default values to help expedite the development process. The following figure shows you the new tool palette details section that is added to the editor with default values.

Setting properties

A tool palette has only three properties for you to set. The following is an explanation for each:
  • id* - The id* represents the unique name that is used to identify your tool palette. It is possible for you to create more than one tool palette for a given project and this id* property is used to distinguish between the different tool palettes.  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.arcmaptoolpalette could be used to represent the tool palette being created for this document (Required).
  • caption* - The caption property is used to give a name to the tool palette and is used in a single location after a project is deployed (Required).

    The caption is used as meta-data in the Add-In Manager to help a user identify the types of customizations available. The following example uses a value of "ArcMap Tool Palette" for the caption property and is exposed in the Add-In Manager as follows:
  • Is Menu Style - The tool palette, by default, exposes a selector dialog. For example, if you had 4 tools in a tool palette, it would be exposed in a 2x2 square when the user selects the tool palette. This menu style allows you to expose your tools and organize them the same way a menu is organized - top to bottom approach. If this option is checked on, the same 4 tools will appear as 4 items long and not like a 2x2 square.

Adding functionality

At this stage, you have finished entering values for all of the properties needed to define your tool palette. This step looks at how you can add functionality to your tool palette container. A tool palette can contain your own tools or the ones provided to you by ESRI. The following image illustrates all of these different possibilities:
The dialog box on the left shows all of the possible types of add-in that can be put into a tool palette container. All the tools that you define are considered commands and are designated with that keyword. This dialog also gives you the ESRI provided tools designated using system as the keyword. The dialog box on the right is used to show what the tool palette contains. To add your functionality to the tool palette, do the following:
  1. Select the functionality you want to move.
  1. Click the arrow to move the piece of functionality to the right dialog box.
The other arrow is available to allow you to remove functionality from a tool palette if the functionality is undesired.
For example, this example moves the "ArcMap Tool" to the right dialog along with the ESRI provided pan, zoom in, and zoom out tools. The result of these actions would result in the following:
Similar to adding your customizations to a tool palette, you can also add any of the ESRI system provided tools by following the same methodology presented. This approach avoids having duplication if the functionality already exists in the desktop product you are customizing.

Adding the tool palette to a toolbar

The final piece that you must take care of before deploying your add-in Project is to add your tool palette to a toolbar. To achieve this, do the following:
  1. See How to create an add-in toolbar for details on creating a toolbar.
  1. Select your add-in toolbar under the all add-ins section of the editor.
  1. Using the technique explored previously, add your tool palette to your new toolbar.
See How to deploy your add-in for information about consuming tool palettes that are connected with your toolbars. Once you have followed the workflow, the following is an example of how the tool palette will look connected to the ArcMap Toolbar.
In this example, the add-in tool palette contains the pan, zoom in and zoom out ESRI provided tools along with a custom tool called, "ArcMap Tool". the exposed tool palette is connected to a custom toolbar. In the customize mode, this tool palette can be dragged to other toolbars; however, initially it can only be exposed through an add-in toolbar. Remember that a tool palette is a container for only tools, while a toolbar can contain commands and more.

Understanding the config.xml

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

Creating different types of customizations

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





Development licensing Deployment licensing
ArcView ArcView
ArcEditor ArcEditor
ArcInfo ArcInfo