iced-cube

Application

Command palette

The app-wide launcher, opened with Ctrl+K, with recent commands and nested pages.

use iced_cube::command_palette::{self, Event, Output, State, command_palette, page};
use iced_cube::navigation::command::{group, item};
API reference
Pages and recent commands: Ctrl+K or Ctrl+Shift+P opens it anywhere. Recent commands come first, and Change theme opens a page of its own; Backspace on an empty query goes back.Pages and recent commands: Ctrl+K or Ctrl+Shift+P opens it anywhere. Recent commands come first, and Change theme opens a page of its own; Backspace on an empty query goes back.
Static preview
Pages and recent commands. Ctrl+K or Ctrl+Shift+P opens it anywhere. Recent commands come first, and Change theme opens a page of its own; Backspace on an empty query goes back.

Usage

The command palette puts a command list inside a dialog and adds what an app-wide launcher needs. The app owns a command_palette::State, routes presses from keys::subscription() through state.key_event so Ctrl+K or Ctrl+Shift+P opens it from anywhere, and runs whatever update returns as Output::Activated. The palette closes itself when a command runs, on Escape with an empty query, or on a click outside.

Commands you run are remembered, newest first, and listed under Recent at the top while the query is empty. Typing hides that group so nothing shows twice. Choosing an item whose id names a page, such as “Change theme…”, opens that page’s list with its own title and placeholder instead of running anything. Backspace on an empty query, Escape or the Back button returns to the page before, and the search field keeps its focus throughout.

Results can also come from background work through the command list’s channel. Subscribe to command_palette::subscription(), keep the sender from Output::Ready, and when update returns Output::Search(query), search state.page_id() for it and send command::results(query, group, items). Results for an older query are dropped. Set .loading(true) while a search runs.

While the search field has focus, the list keeps its own keys, then the palette’s Back and toggle chords, then the dialog’s, so arrows, Enter and Escape work as they do in the list on its own.

Examples

Async results

Typing asks the app to search, and a background task streams file matches through the command list's channel.

API

ItemDescription
State::new(groups)A closed palette listing command groups on its first page.
.with_page(page(id, title, groups))A nested list. Choosing the item with the page's id opens it instead of running it. Add .placeholder(text) to the page.
.with_recent(ids) / .with_recent_limit(n)Starts with recent commands, and keeps up to n of them (five by default, zero for none).
.with_visible_rows(n)How many rows show at once, eight by default.
state.update(Event)Handles Open, Close, Toggle, Back and the command list's own events. Returns Output::Activated when a command runs, Search(query) when the query changes, and Ready(sender) once the channel is open.
state.is_open() / state.page() / state.page_id() / state.depth()Whether the palette is open, and the nested page on show.
state.recent() / state.query() / state.command()The recent commands, newest first, the query and the command list inside.
state.set_groups(groups)Replaces the first page's groups, for labels that follow your app's state.
state.key_event(&keymap, &key)Resolves a key press from keys::subscription, so the toggle chords open the palette anywhere.
command_palette::subscription()The command list's results channel, wrapped in Event::Command.
command_palette(&state, base)Wraps your app in the palette's dialog. The list renders disabled until .on_event is set.
.on_event(f) / .title(text) / .placeholder(text) / .empty(text)Maps palette events to your message, and sets the first page's title, the search placeholder and the empty-state text.
.loading(bool) / .max_height(f32) / .size(dialog::Size)Shows that a search is running, caps the list's height (400 by default), and sets the dialog's width.
.keymap(keymap) / .command_keymap(keymap) / .dialog_keymap(keymap)Replace the toggle and Back chords, the list's keys and the dialog's keys.
command_palette::default_keymap()The default shortcuts as a Keymap<Action>.

Keyboard

Default shortcuts. Every one can be changed or removed with a keymap; see Keyboard shortcuts.

KeysAction
Ctrl+K or Ctrl+Shift+PToggle Opens the palette from anywhere, or closes it.
BackspaceBack Returns to the page before, while the query is empty.
Esc