ProGuide Keyboard shortcuts

Language:      C#
Subject:       Framework
Contributor:   ArcGIS Pro SDK Team <[email protected]>
Organization:  Esri, http://www.esri.com
Date:          10/06/2024
ArcGIS Pro:    3.4
Visual Studio: 2022

This guide introduces keyboard shortcuts and demonstrates how to enhance your add-in or configuration with an efficient keyboard interface.

In this Topic

• Shortcuts and Accelerators
• User Customization
• Shortcut Context and Processing
• Choosing the Right Keys
• Defining Shortcuts in DAML
• ProGuide Steps - Create a Shortcut for a Button Control
• ProGuide Steps - Create a Shortcut for a Menu or Dockpane
• ProGuide Steps - Create a Global Accelerator
• Bypassing Pro Shortcut Key Filtering on Dockpanes

Shortcuts and Accelerators

Keyboard shortcuts and accelerators are keys or combinations of keys that provide an alternative way to do something that a user would typically do with a mouse. Shortcuts greatly improve the usability, productivity, and accessibility of your customization.

Accelerators are available in all versions of ArcGIS Pro and are global in context. ArcGIS Pro 3.2 extended the keyboard framework with Shortcuts, which allow context-sensitive key definitions to prevent key conflicts and improve the user experience.

User Customization

Shortcuts and Accelerators are end-user customizable. Users can add or edit them through the Customize the Ribbon page in the Options dialog or the Keyboard Shortcuts dialog that was added at ArcGIS Pro 3.2.

The Keyboard Shortcuts dialog:

Users can expand the groups to view and modify existing Shortcuts or add a new one:

Shortcut Context and Processing

The keyboard framework has four context tiers. Three processing tiers for Shortcuts, and a fourth and final tier for Accelerators. They are processed in the following order:

1. The active tool (e.g. the "Delete Vertex" Editing tool)
2. The active view (e.g. switch tools)
3. The active pane (DockPane)
4. Global (e.g. the "Save Project" command, defined as a Global Accelerator)

In tiers 1 and 2, Shortcuts are contextual to tools, views, or a combination of both. For example, a shortcut may be "live" only when a certain tool and state are both active. Similarly, a shortcut may only work when a particular view is active, or when a view with a specific state is set. Tier 3 processes Shortcuts when the target DockPane is active.

Tier 4 processes Global Accelerators. You should one use the global context for commands that are free of contextual constraints and generally applicable regardless of application state - opening, closing, or saving the current project; opening a new map; signing into/out of a Portal; and closing ArcGIS Pro, are all good examples of Global Accelerators.

Choosing the Right Keys

When choosing key combinations for your Shortcuts, it's important that they don't conflict with the built-in shortcuts included in ArcGIS Pro. Use the Keyboard Shortcuts dialog to inspect the existing shortcuts in each context where you want to add your own. Take extra care when defining a Global Accelerator. You need to choose keys that won't conflict with existing Global Accelerators or with Shortcuts used in common contexts like "Mapping" or "View Navigation".

Due to the well-targeted nature of Shortcuts, key combinations can often be re-used without conflicts. Using the same key combinations for logically similar concepts decreases the amount of memorization required while greatly improving usability.

Combinations of Control, Alt, and Shift along with a key are also acceptable. But Shortcuts do not require a modifier. It is perfectly acceptable to assign a command the letter 'Z', for example. Single key Shortcuts can be very efficient in highly focused contexts.

Defining Shortcuts in DAML

Shortcuts are available in ArcGIS Pro 3.2 and later. They are defined in DAML. Each shortcutTable has an id and a targetID attribute. The targetID is the Pane, Dockpane, or Tool that the shortcut targets. A condition attribute may also be specified to further focus the shortcut through the use of Conditions. Define the category, caption, and description attributes to control how and where your table displays in the Keyboard Shortcuts dialog. For example, the shortcutTable defined below appears as the "Sketch regular polygon" subgroup within the "Editing" Category group. For visual consistency, Captions should use title case.

shortcut elements contain a refId attribute that references the command, menu, pane, or dockpane they should launch. The key attribute maps to a single key on the keyboard. The flags attribute allows you to define one or more modifier keys for the shortcut key combination, such as "Ctrl" or "Alt+Shift". Use a value of "None" if you wish to define a single key shortcut with no modifiers.

Example of a shortcutTable and individual shortcut elements, defined in DAML:

<shortcutTables>
  <insertShortcutTable id="esri_editing_shortcutList_RegularPolygon" 
                       targetID="esri_mapping_mapPane"  
                       category="Editing" 
                       caption="Sketch Regular Polygons" 
                       condition="esri_editing_shortcutCondition_RegularPolygon"
                       description="Available when the Regular Polygon tool is active.">
    <shortcut refID="esri_editing_DirectionContextMenuItem" key="A" flags="None"/>
    <shortcut refID="esri_editing_DistanceContextMenuItem"  key="D" flags="None"/>
    <shortcut refID="esri_editing_AbsoluteXYZContextMenuItem" key="F6" flags="None"/>
  </insertShortcutTable>
</shortcutTables>

Global Accelerators, available in all versions of ArcGIS Pro, are defined and listed in the <accelerators> section of DAML. See ProGuide Steps - Create a Global Accelerator and the Accelerators snippets for Global Accelerator examples.

ProGuide Steps

Create a Shortcut for a Button Control

Step 1

Create an add-in project called "ProAppModule1". Add a generic C# class file called "Button1.cs" and replace the contents of Button1.cs with the following C# code:

 internal class Button1 : Button {
    protected override void OnClick() 
    {
      MessageBox.Show("Are you able to show this message via shortcut?");
    }
 }

Step 2

Modify the Config.daml file by adding a <shortcutTables> element below the modules definition. Inside the <shortcutTables> element, add a <insertShortcutTable> element. The id and category defined in the <insertShortcutTable> element will be reflected in the Keyboard Shortcut dialog. The TargetID is the Pane (view), DockPane, or Tool the shortcuts target. In the following example, the mapping pane is listed as the target id. The shortcuts will be available when the map view is activated.

<shortcutTables>
  <insertShortcutTable id="myaddin_example_shortcutTable"
                       category="Add-In Shortcuts"
                       caption="Example Shortcut Table"
                       targetID="esri_mapping_mapPane"
                       description="My add-in shortcuts available when a map view is active.">
    <shortcut refID="ProAppModule1_Button1" key="k" flags="None" />
  </insertShortcutTable>
</shortcutTables>

Step 3 Build your add-in and run ArcGIS Pro. Open a Map and press the "k" key. The shortcut will call the OnClick method in the corresponding button class for the command ProAppModule1_Button1, causing the MessageBox to appear. Because targetID is set to the mapPane context, the shortcut will only be enabled when a map view is active.

Press F12 to open the Keyboard Shortcuts dialog. You should see your new custom "Add-in Shortcuts" category listed below built-in the Global category.

Note: unchecking "Show currently active shortcuts" undoes the dialog's context filter, allowing you to see the full list of shortcuts in the application.

Step 4 (Optional)

Sometimes keyboard shortcuts need to be allowed only if a condition is met. The condition attribute can be a great help in this scenario. For more info regarding conditions, please refer to the ProGuide Code Your Own States and Conditions

Modify the shortcut table by adding a condition attribute. Setting the value to "esri_mapping_onlyFeatureLayersSelectedCondition" will enable the shortcut only when a feature layer is selected in a map view.

<shortcutTables>
  <insertShortcutTable id="myaddin_example_shortcutTable"
                       category="Add-In Shortcuts"
                       caption="Example Shortcut Table"
                       targetID="esri_mapping_mapPane"
                       description="My add-in shortcuts available when a map view is active."
                       condition="esri_mapping_onlyFeatureLayersSelectedCondition">
    <shortcut refID="ProAppModule1_Button1" key="k" flags="None" />
  </insertShortcutTable>
</shortcutTables>

Create a Shortcut for a Menu or Dockpane

Shortcuts can also reference menus, panes, and dockpanes. This supports an efficient user workflow where an easily remembered shortcut opens a frequently used menu, eliminating the difficulty of remembering individual shortcuts for a large number of commands. Shortcuts can also open panes and dockpanes.

Step 1

Modify Config.daml to include the following shortcuts. Because their shortcut table has a esri_mapping_mapPane targetID, the shortcuts will only be in context when a map view is active. esri_mapping_popupToolContextMenu assigns the "k" key to open the pop-up context menu that appears on top of the map. esri_core_projectDockPane assigns the "g" key to open or activate the Catalog dockpane.

<shortcutTables>
  <insertShortcutTable id="myaddin_example_shortcutTable"
                       category="Add-In Shortcuts"
                       caption="Example Shortcut Table"
                       targetID="esri_mapping_mapPane"
                       description="My add-in shortcuts available when a map view is active.">
    <shortcut refID="esri_mapping_popupToolContextMenu" key="k" flags="None" />     Open the Map context menu
    <shortcut refID="esri_core_projectDockPane" key="g" flags="None" />     Open or activate the built-in Catalog dockpane
  </insertShortcutTable>
</shortcutTables>

Create a Global Accelerator

Global Accelerators are shortcuts that do not require contextual activation. ArcGIS Pro comes with a list of global shortcuts. The global shortcuts are listed in "Global" category in the Keyboard Shortcut dialog. F12 is one example of a global accelerator. It launches the Keyboard Shortcut dialog itself via F12 anytime when ArcGIS Pro is in use. Some of the global shortcuts are read-only and not available for modification.

Step 1

Modify Config.daml to include the following DAML elements. Simply add an <accelerators> element and specify the refID matching the command id you intend to use.

<accelerators>
  <insertAccelerator refID="ProAppModule1_Button1" key="r" flags="Ctrl+Shift"/>
</accelerators>

Step 2

Rebuild the add-in, start ArcGIS Pro, and press F12 to check if the Global Accelerator is registered in the Keyboard Shortcut dialog. It should appear in the Global group.

Bypassing Pro Shortcut Key Filtering on Dockpanes

Starting at Pro 3.3, you can turn off/block Pro's global shortcut filtering using the BlockShortcuts attached property within your dockpane .xaml declaration. This may be useful if Pro's global shortcut filtering is intefering with the keypress handling of an embedded control, when it gets focus, on your custom dockpane. Consult the ProGuide Dockpanes Bypassing Pro Shortcut Key Filtering on Dockpanes topic for more information.