#CommandPalette

A CommandPalette is a search box over the workspace that finds and runs a command. The user presses Ctrl+K, types a part of the command name, and presses Enter. It gives a keyboard user fast access to every action of your UI.

How to add a command palette:

1. Add one CommandPalette to the workspace, in UXML or in code. It stays hidden. The shortcut works while the palette is in a panel.
2. Add the commands in code. Each command has a text and an action.

<tb:Workspace name="workspace">
    <!-- the windows -->
    <tb:CommandPalette name="palette" />
</tb:Workspace>

var palette = root.Q<CommandPalette>("palette");
palette.AddCommand("Save layout", SaveLayout, "Ctrl+S", "Layout");
palette.AddCommand("Reset layout", ResetLayout, group: "Layout");
var paste = palette.AddCommand("Paste", Paste, "Ctrl+V", "Edit");
paste.Enabled = false; // dim, and Enter passes over it
palette.Executed += command => Debug.Log($"Ran {command.Text}");

• Up and Down move the highlight and pass over a disabled command. Enter, the gamepad submit button or a click runs a command.
• While the typed text is the start of the highlighted command, the rest of the name shows grey after it. Tab completes the name and does not run the command. The focus stays in the search.
• Escape, the shortcut again, or a press outside the dialog closes the palette without a command.
• The palette closes before the action runs. The focus is back in the control that had it, so the action can use that control or open another overlay.
• The shortcut does not open the palette while a MessageBox or another modal overlay is open.
• The best match is first: a command that contains the typed text, then one that has its letters in order. The list is a ChoiceList, so the rows have the tb-choice-list classes.
• The palette opens with an empty search field and all the commands.

Tips:

• Use one palette for each panel. Two palettes with the same shortcut both open. Give an extra palette shortcut="" and open it from code.
• Put the shortcut of a command in detail. The palette shows the text; it does not register the shortcut.
• Add commands for the windows of the workspace, as the WorkspaceDemo example does, so the user opens a window by name:

foreach (var button in workspace.Query<WorkspaceToolbarButton>().ToList())
{
    var id = button.WindowId;
    palette.AddCommand($"Open {button.Title}", () => _ = workspace.OpenWindowAsync(id), group: "Windows");
}

• For text in other languages, give the tb.type-a-command key a text in your ToolboxText source. See the Localization example.
• Keep the command texts short and start them with a verb. The user finds "Open Gauge" faster than "Gauge window".

#Styling