ProGuide Command Search

Language:      C#
Subject:       Framework
Contributor:   ArcGIS Pro SDK Team <arcgisprosdk@esri.com>
Organization:  Esri, http://www.esri.com
Date:          12/21/2022
ArcGIS Pro:    3.1
Visual Studio: 2022

This guide will discuss configuring your add-in to use Command Search, a new capability added to Pro at 2.8. Command search can be found on the Pro ribbon.

In this Topic

• Using Command Search in your Add-in

Command Search

In ArcGIS Pro 2.8, the CommandSearch control was added to the top of the Pro ribbon. This feature lets users quickly find and execute commands by typing keywords into the search edit box. When focus is initially shifted to within the CommandSearch control by clicking or tabbing into it, the user will see recently used commands and a composite list of suggested commands in a drop down. Any commands that are executed from the CommandSearch control will be added to a "Recently Used list" of commands. This list is persisted within the user.config file located under the user’s roaming profile.

Suggested Commands

The "Suggested" commands listed will vary depending on the currently active tab. The purpose being to propose a list of commonly used commands relevant to the currently activated ribbon tab. Add-in modules can provide a list of suggested command ids to always include in the suggested commands list (when the relevant tab is activated) by overriding the public override string[] GetSuggestedCMDIDs(string activeTabID) method on the Module class. GetSuggestedCMDIDs() returns the list of "suggested" commands to be automatically included in the "Suggested" section of the Command Search drop down when their respective tab is activated. For add-ins that do not implement this override, the global default list (statically defined by the Pro application) will be presented to the user instead whenever one of the add-in's tabs is activated. Refer to Step 3.

As text is entered into the CommandSearch control, it is dynamically processed to produce a composite list of commands and help topics. Note that commands appearing within the result list are disabled or enabled based on the current application state. Refer to Step 4.

In cases where the match count is larger than would reasonably fit within the dropdown list (currently limited to 15 commands), results are dropped, and the user must modify the query to be more specific. To exclude commands from appearing in Command Search results, add-ins should use the daml attribute: hidden="true" on their command's DAML declaration (eg button, tool, etc). Refer to Step 5.

Step 1:

Create an add-in project called "CommandSearch". Add a generic c# class file to your add-in project. Call it "Example_Buttons.cs". Replace the contents of Example_Buttons.cs with the following c# code:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using ArcGIS.Desktop.Framework.Contracts;
using ArcGIS.Desktop.Framework.Dialogs;

namespace CommandSearch
{

 internal class ButtonBase : Button  {

    protected override void OnClick() {
       var time = System.DateTime.Now.ToString("F");
       MessageBox.Show(this.Caption + $" {time}", this.Caption);
    }
 }

 internal class FindButton1 : ButtonBase { }
 internal class FindButton2 : ButtonBase { }
 internal class FindButton3 : ButtonBase { }
 internal class FindButton4 : ButtonBase { }
 internal class HideButton1 : ButtonBase { }
}

It declares five Pro buttons and a common base class "ButtonBase". Ensure that the namespace in this example, CommandSearch, matches the default namespace of your add-in. Change the namespace if needed to match your add-in's default.

Step 2

Modify your Config.daml to add the necessary button declarations, groups, and tabs within your <modules><insertModule ...> tag. In the daml, we are defining two tabs and two groups, one group per tab. One of the groups, "Group 1", will be on "Tab 1", the other group, "Group 2", will be on "Tab 2". Two buttons are being added to Group 1, three buttons to Group 2.

<insertModule id=.....>
  

  <tabs>
    <tab id="CommandSearch_Example_Tab1" caption="Tab 1">
      <group refID="CommandSearch_Example_Group1" />
    </tab>
    <tab id="CommandSearch_Example_Tab2" caption="Tab 2">
      <group refID="CommandSearch_Example_Group2" />
    </tab>
  </tabs>
  <groups>
    <group id="CommandSearch_Example_Group1" caption="Group 1" appearsOnAddInTab="false">
      <button refID="CommandSearch_Example_Button1" size="large" />
      <button refID="CommandSearch_Example_Button2" size="large" />
      <button refID="CommandSearch_Example_Button5" size="large" />
    </group>
    <group id="CommandSearch_Example_Group2" caption="Group 2" appearsOnAddInTab="false">
      <button refID="CommandSearch_Example_Button3" size="large" />
      <button refID="CommandSearch_Example_Button4" size="large" />
    </group>
  </groups>
  <controls>
    <button id="CommandSearch_Example_Button1" caption="Find Button1" className="FindButton1" loadOnClick="true"
      largeImage="pack://application:,,,/ArcGIS.Desktop.Resources;component/Images/GenericButtonBlue32.png">
      <tooltip heading="Tooltip Heading">The quick brown fox jumped<disabledText/></tooltip>
    </button>
    <button id="CommandSearch_Example_Button2" caption="Find Button2" className="FindButton2" loadOnClick="true"
      largeImage="pack://application:,,,/ArcGIS.Desktop.Resources;component/Images/GenericButtonGreen32.png">
      <tooltip heading="Tooltip Heading">over the lazy dog<disabledText/></tooltip>
    </button>
    <button id="CommandSearch_Example_Button3" caption="Find Button3" className="FindButton3" loadOnClick="true"
      largeImage="pack://application:,,,/ArcGIS.Desktop.Resources;component/Images/GenericButtonRed32.png">
      <tooltip heading="Tooltip Heading">The quick brown fox jumped<disabledText/></tooltip>
    </button>
    <button id="CommandSearch_Example_Button4" caption="Find Button4" className="FindButton4" loadOnClick="true"
      largeImage="pack://application:,,,/ArcGIS.Desktop.Resources;component/Images/GenericButtonPurple32.png">
      <tooltip heading="Tooltip Heading">over the lazy dog<disabledText/></tooltip>
    </button>
    <button id="CommandSearch_Example_Button5" caption="Hidden Button5" className="HideButton1" loadOnClick="true"
      largeImage="pack://application:,,,/ArcGIS.Desktop.Resources;component/Images/GenericButtonGrey32.png">
      <tooltip heading="Tooltip Heading">Set hidden = true to hide from search<disabledText/></tooltip>
    </button>	
  </controls>


 </insertModule>

At this juncture, compile and run your add-in. Check that the two tabs, "Tab 1" and "Tab 2", get added to the Pro ribbon and that all of the buttons on the two tabs work. If any buttons stay disabled it probably means that you have an error in your Config.daml. Check the className attribute property of the buttons. Ensure it matches the class name you used in your button .cs source file.

Step 3

We are going to add an override for GetSuggestedCMDIDs() in the Module class to provide default command options in CommandSearch for when our tabs are activated.

Add the following implementation into your Module1.cs file. If your DAML ids for either of the tabs or buttons are different than what is shown here then change them accordingly:

internal class Module1 : Module {

  private static Module1 _this = null;
  ...

 /// <summary>
 /// Used by Command Search
 /// </summary>
 public override string[] GetSuggestedCMDIDs(string activeTabID)
 {
    //Return the static list of daml ids you want to be the (suggested) 
    //defaults relevant to the given tab. It can be none, some, or all of the
    //commands associated with the activeTabID.
    //In this example, there are two tabs. This example arbitrarily
    //identifies just one command on each tab to be a default to show in the
    //command search list (when _that_ particular tab is active)
    switch(activeTabID)
    {
       case "CommandSearch_Example_Tab1":
          return new string[] { "CommandSearch_Example_Button2" };
       case "CommandSearch_Example_Tab2":
          return new string[] { "CommandSearch_Example_Button4" };
     }
     return new string[] { "" };
 }

Compile and run the add-in.

Activate "Tab 1". Click on Command Search. "Find Button 2" should show in the Suggested group of the drop down. Activate "Tab 2". Click on Command Search. Now "Find Button 4" should show. These are the buttons corresponding to the daml ids being returned from GetSuggestedCMDIDs(). Activate any other tab. Your commands will no longer be included in the Command Search drop down by default.

Step 4

Let's try out the text search capabilities of Command Search.

With any tab activated, type in the phrase the quick brown fox. "Find Button 1" and "Find Button 3" should show in the list. Try "lazy dog". "Find Button 2" and "Find Button 4" should show in the list. The search is returning these results using the tooltip strings defined in your Config.daml.

Experiment with "Find" or "Find Button" to retrieve your commands based on their caption and so-on. Other Pro command content may also show in the list depending on the particular phrase you enter.

Clicking on any of the commands in the list will execute them (assuming they are enabled). Executing the commands directly from the Suggested group will add them to the "Recently Used" group on the Command Search drop down.

Step 5

Now we will try out the "hidden" feature of Command Search to exclude one of our commands. Currently, if you type "Hidden" or "Hidden Button" into Command Search the "Hidden Button5" will show in the list (along with any other commands matching the word or phrase you entered).

Stop the debugger or close Pro. Go into your Config.daml and find the declaration for <button id="CommandSearch_Example_Button5" caption="Hidden Button5" .... Add the daml attribute hidden="true" to its declaration. The declaration should now look as follows:

  <button id="CommandSearch_Example_Button5" caption="Hidden Button5" className="HideButton1" loadOnClick="true"
    largeImage="pack://application:,,,/ArcGIS.Desktop.Resources;component/Images/GenericButtonGrey32.png"
    hidden="true">
     <tooltip heading="Tooltip Heading">Set hidden = true to hide from search<disabledText /></tooltip>
  </button>

Rebuild your add-in to force the add-in to recompile. Start Pro. Go back to Command Search. Repeat the previous search using "Hidden" or "Hidden Button". Your "Hidden Button5" should no longer show in the list. It has been excluded via the hidden="true" attribute.