Tool Class—ArcGIS Pro

Tool Class

In This Topic

Represents a tool control. This is an abstract class.

Syntax

C#
Visual Basic (Declaration)

public abstract class Tool : Button, System.ComponentModel.INotifyPropertyChanged

Public MustInherit Class Tool 
   Inherits Button
   Implements System.ComponentModel.INotifyPropertyChanged

Remarks

All ribbon control elements share several attributes. The loadOnClick attribute determines when the control should be created by the framework. By default, controls appear enabled, but are not actually instantiated until they are clicked. This simple just-in-time (JIT) strategy improves resource utilization and startup time by deferring the instantiation of controls until they are initiated by the end user. Note that non-visible controls are never loaded until they become visible (or are executed programmatically), regardless of the value assigned to loadOnClick.

Tooltips are defined using the tooltip sub-element and may span as many lines as necessary. The image attribute is used to supply an image that will appear next to the tip text. Command tooltips also support a disabledText element, this string is additional displayed when the command is disabled.

Most controls support multiple sizes in the ribbon. For example, a button can render small (small icon only), medium (small icon with text), and large (large icon over text). Use the smallImage and largeImage attributes to specify unique images for the different sizes. Images don’t have to be graphics, you can also use XAML. You can also use overlayLargeImage and overlaySmallImage to draw a graphic or XAML overtop of the corresponding images. If the image should flip when running right-to-left, e.g. arrow buttons, set the flipImageRTL attribute to true.

The disableIfBusy element is used to signal that the control should be disabled whenever the primary worker thread is busy. This prevents work from queuing up. This element is true by default. Controls that always need to be enabled such as the close application button should set this to false.

All control declarations support a condition attribute allowing the assignment of a condition. If the specified condition isn’t met, the control will be automatically disabled by the framework. In addition, controls remain unloaded until their is met. If no condition is specified, the control is assumed to be always relevant.

Controls can also be registered into component categories using the categoryRefID attribute. In this scenario, you can additionally use the content sub-element to define any custom data. For example, the Editing module may define a component category for 'sketch tools' and your custom sketch tool would need to be registered in this category for it to appear in their custom tool palette.

Generally speaking, an active tool is established whenever a Pane is selected. Several rules are involved in determining which tool should be activated; many of these rules involve the incoming and outgoing panes.

If the two panes have the same Pane.ContentID, carry over the currently active tool
Restore the incoming pane's cached tool only if it is sticky.
Restore incoming pane's cached (non-sticky) tool if the previous pane's tool is sticky
Restore the last active tool for the incoming pane if available; otherwise, use its default tool

Declaring Tools in DAML:

            <tool id="acme_selectByRectangleTool" className="Acme.Mapping.SelectTool" 
              largeImage="pack://application:,,,/Acme;component/Images/SelectionSelectTool32.png" 
              smallImage="pack://application:,,,/Acme;component/Images/SelectionSelectTool16.png" 
              caption="Select By Rectangle" 
              condition="esri_mapping_mapPane">
              <tooltip heading="Select By Rectangle">Select features by clicking them or dragging a box around them.
                <disabledText></disabledText>
              </tooltip>
            </tool>

DAML attributes
id	Required identifier.
caption	The default DockPane heading.
extendedCaption	A more descriptive title.
smallImage	Image (16x16) used when button is small and middle size.
largeImage	Image (32x32) used when button is large size.
overlaySmallImage	Optional image overlay.
overlayLargeImage	Optional image overlay.
flipImageRTL	Option to flip the image when running right-to-left. Default is false.
keytip	The key that selects the button in keytip mode (Alt navigation).
loadOnClick	Delay creating the actual control until it has been clicked. Default is true.
categoryRefID	Adds control to a specific component category.
condition	Automatically disable the button if the condition is not satisfied.
disableIfBusy	Automatically disable the button if the application is busy. Default true.
helpContextID	The help topic to show.
className	Required class identifier. Optionally include namespace if not in default namespace.
assembly	Assembly name if not in the default assembly.
publicKeyToken	The necessary public key token if the assembly is strongly named.
version	The version of the dll if the assembly is strongly named.

DAML Child Elements
tooltip	Description of the control.
content	Optional custom XML data when registered in a component category.

Inheritance Hierarchy

System.Object
   ArcGIS.Desktop.Framework.Contracts.PropertyChangedBase
      ArcGIS.Desktop.Framework.Contracts.PlugIn
         ArcGIS.Desktop.Framework.Contracts.Button
            ArcGIS.Desktop.Framework.Contracts.Tool
               ArcGIS.Desktop.Layouts.LayoutTool
               ArcGIS.Desktop.Mapping.MapTool

Requirements

Target Platforms: Windows 11, Windows 10

ArcGIS Pro version: 3 or higher.

Reference

Tool Members
ArcGIS.Desktop.Framework.Contracts Namespace

Send feedback