How to create a map tool
A custom map tool is a class in an add-in that implements the ESRI.ArcGIS.OperationsCenter.IMapTool interface, and also inherits from UserControl. It must have an Export attribute with the value ESRI.ArcGIS.OperationsDashboard.MapTool. It should also have ExportMetadata attributes to set DisplayName, Description and ImagePath attributes. Other optional related interfaces can add additional functionality.
The simplest way to create a new custom map tool is to use the Map Tool item template available in Visual Studio for Operations Dashboard for ArcGIS.
Creating a new map tool
- Open an existing add-in project or create a new one by following the steps in the Getting started topic.
- Click
Project -> Add New Item.
The New Item dialog box appears with the list of installed templates.
- Navigate to Visual C# or Visual Basic > WPF > ArcGIS.
- Select the Operations Dashboard for ArcGIS Map Tool template, enter a Name, and click OK.
The following items are added to the project:
- A new MapTool.xaml file providing the user interface of the map tool.
- A corresponding MapTool.xaml.cs/.vb code behind file. This item defines the custom map tool and provides a default implementation of IMapTool.
- An Images folder containing an image file. This item defines the icon for the custom map tool.
Essential elements of a map tool
The following essential elements of a map tool are automatically generated by the item template, with default values and implementation. Edits to these elements may be required when the default implementation is adapted.
- IMapTool interface: The IMapTool interface must be implemented on a map tool class. This provides the minimum contract for a map tool to be hosted inside a toolbar within a map widget in the application, defining essential activation and configuration members for custom map tools. See the API Reference help for information on implementing each member of this interface.
- Export attribute: An Export attribute with the value ESRI.ArcGIS.OperationsDashboard.MapTool is required on the map tool class. This attribute is defined in the System.ComponentModel.Composition namespace, part of the .NET Framework that provides the Managed Extensibility Framework (MEF). The application uses MEF to find and load custom add-ins and the types they contain.
- Serializing attributes: A DataContract attribute is required on the map tool class, and DataMember attributes are required on any members which must be serialized to the operation view when the operation view containing the map tool is saved. These attributes are defined in the System.Runtime. Serialization namespace, part of the .NET Framework providing serialization and deserialization support. See the Serializing add-in properties topic for more information.
- Metadata attributes: Three ExportMetadata attributes are required on the map tool class to define information shown about the tool before the assembly is loaded, in the Manage Add-Ins and Configure Map Tools dialog boxes. The names of these attributes should be DisplayName, Description, and ImagePath, all with appropriate values. The item template, and sample map tools, that are part of the SDK demonstrate appropriate values. This attribute is again defined in the System.ComponentModel.Composition namespace
Optional elements of a map tool
The additional areas of functionality can be implemented on a map tool, if the workflow being developed requires them.
Configuration
Some out-of-the-box map tools are configurable–they allow the operation view author to alter how the map tool operations. For example, the place finder tool allows the author to choose the type of coordinate notation used. However, configuration is optional.
To make a map tool configurable, return true from the IMapTool.CanConfigure method–the application will then show a configuration button next to the map tool in the list, allowing the author to change settings. If the CanConfigure method returns false, no configuration button is shown. See the API Reference help for other information on implementing the CanConfigure and Configure members of IMapTool.
Text boxes, drop down lists and galleries
Not all map tools add only a button to a toolbar. For example, for example the Find Places tool requires the end user to type into a box. If the additional controls will fit into the space of the toolbar, they can simply be added to the Xaml of the map tool in the same way as a Button is added by the Map Tool new item template.
Some map tools require only a simple button shown on the toolbar, for example the Link Map Extents tool. Other map tools show, when clicked, drop-down lists or galleries of further options which is dismissed once the end user makes a selection, for example the Basemaps or Bookmarks tools. Some tools may also show drop-down checkable lists, where a user can make multiple selections, before dismissing the tool by clicking elsewhere in the application, for example the Layer Filter and Map Contents tools.
To map a map tool that shows additional user interface when clicked, add the elements to the Xaml of the map tool, changing the visibility to true when the end user clicks the map tool button.
Styles are available to show a consistent user interface to the out-of-the-box tools. See the Using application resources in add-ins and Application resource reference topics for more information.
Tools that can be canceled
Some out-of-the-box map tools provide operations that require the user to interact with the map, and that can be canceled. For example, the Select tool allows the user to define a rectangle on the map, selecting the features within that area. When the end user clicks the map tool, the existing toolbar is temporarily replaced with a custom toolbar . This custom toolbar both prevents use of any other tools, and provides a clear way to cancel the selection operation by showing a Cancel button. It also provides a caption on the toolbar indicating to the user how to use the tool.
There is no notion of a currently selected tool in the toolbar in the application, therefore it is recommended that custom tools with similar workflows use the same approach and set a temporary custom toolbar providing a cancelation button. For more information, see the section below. For an example of a map tool that provides a cancelation toolbar, see the Zoom to extent map tool sample.
Setting a custom toolbar
Some out-of-the-box map tools may show information to the user during the use of the tool, For example, the Measure tool allows the user to define points, lines, and areas on the map, and shows the user the measurement, allowing the user to change the units used to display the value. A custom toolbar replaces the existing toolbar when the Measure tool is clicked, allowing the display of the multiple tools required to provide this functionality.
A custom toolbar can be set by creating implementing the IMapToolbar interface on a class that inherits from UserControl. An instance of this class is then passed in to the MapWidget.SetToolbar method. The visual element of the custom toolbar class is used to temporarily replace the existing toolbar. The previous toolbar is reinstated by passing null (Nothing in Visual Basic) to the SetToolbar method. The simplest way to create a new custom toolbar is to use the Map Toolbar item template available in Visual Studio for Operations Dashboard for ArcGIS.
For an example of a map tool that provides a toolbar, see the Zoom to extent map tool sample. For more information about implementing the IMapToolbar interface, see the API Reference help.