Struct Keymap 

pub struct Keymap { /* private fields */ }

The set of key bindings for the application, and the rules for choosing among them.

Usually you don’t build a Keymap yourself. App holds one, and App::bind_keys adds to it. It is also the place where the precedence rules are implemented, so this is the reference for how a keystroke resolves.

Examples

use gpui::{Action, KeyBinding, KeyContext, Keymap, Keystroke, actions};

actions!(keymap_docs, [Save, Format]);

let keymap = Keymap::new(vec![
    KeyBinding::new("cmd-s", Format, Some("Workspace")),
    KeyBinding::new("cmd-s", Save, Some("Editor")),
]);

// In an editor inside a workspace, the deeper `Editor` binding wins.
let typed = [Keystroke::parse("cmd-s").unwrap()];
let context = [
    KeyContext::parse("Workspace").unwrap(),
    KeyContext::parse("Editor").unwrap(),
];
let (bindings, pending) = keymap.bindings_for_input(&typed, &context);
assert_eq!(bindings[0].action().name(), "keymap_docs::Save");
assert!(!pending);

See keyboard input for the full precedence rules as they apply during dispatch.

Implementations

impl Keymap

pub fn new(bindings: Vec<KeyBinding>) -> Self

Creates a keymap that contains bindings, in the order given.

pub fn version(&self) -> KeymapVersion

Returns the current version. See KeymapVersion.

pub fn add_bindings<T: IntoIterator<Item = KeyBinding>>(&mut self, bindings: T)

Adds bindings after the existing ones and changes the version.

A binding added later wins over an earlier one at the same depth. Add the user’s bindings after the defaults so that they take precedence.

pub fn clear(&mut self)

Removes every binding and changes the version.

pub fn bindings( &self, ) -> impl DoubleEndedIterator<Item = &KeyBinding> + ExactSizeIterator

Iterates over all bindings, in the order they were added.

The iterator includes NoAction and Unbind entries.

pub fn bindings_for_action<'a>( &'a self, action: &'a dyn Action, ) -> impl 'a + DoubleEndedIterator<Item = &'a KeyBinding>

Iterates over the bindings that run action, in the order they were added.

Bindings disabled by a later NoAction or Unbind are left out. This ignores key contexts, so a binding is included even when it can’t fire in the current focus. To find the bindings that apply now, use Window::bindings_for_action. For a shortcut label, use the last binding, which was added most recently.

pub fn all_bindings_for_input(&self, input: &[Keystroke]) -> Vec<KeyBinding>

Returns every binding that matches all of input, ignoring key contexts.

The bindings are in precedence order: the most recently added comes first. Bindings that need more keystrokes than input are left out. NoAction and Unbind entries that match are included, but their effect on other bindings is not applied.

pub fn bindings_for_input( &self, input: &[impl AsKeystroke], context_stack: &[KeyContext], ) -> (SmallVec<[KeyBinding; 1]>, bool)

Returns the bindings that match input in context_stack, and whether a longer input could still match a binding.

The first value holds the matching bindings, highest precedence first. The second value is true when some binding needs more keystrokes than input, so the caller should wait for the next keystroke.

Precedence works as follows:

• Depth. A binding’s depth is the deepest point in context_stack where its predicate matches. A binding in a deeper context wins over one in a shallower context. A binding without a context is as deep as the stack, so it is at least as deep as any context-specific binding. At equal depth, the order rule below decides.
• Order. At the same depth, the binding added later wins.
• NoAction. A winning NoAction removes the lower-precedence bindings for the same keystrokes, unless they come from a stronger source. See KeyBindingMetaIndex.
• Unbind. A winning Unbind removes the lower-precedence binding for the same keystrokes that runs the action it names, whatever that binding’s context.

Several bindings can be returned, because a match that isn’t suppressed stays in the list.

Examples

use gpui::{Action, KeyBinding, KeyContext, Keymap, Keystroke, actions};

actions!(input_docs, [Save, Format]);

let keymap = Keymap::new(vec![
    KeyBinding::new("cmd-s", Format, Some("Workspace")),
    KeyBinding::new("cmd-s", Save, Some("Editor")),
]);

// The `Editor` binding is at depth 2 and the `Workspace` binding at depth 1.
let (bindings, _) = keymap.bindings_for_input(
    &[Keystroke::parse("cmd-s").unwrap()],
    &[
        KeyContext::parse("Workspace").unwrap(),
        KeyContext::parse("Editor").unwrap(),
    ],
);
assert_eq!(bindings[0].action().name(), "input_docs::Save");

pub fn possible_next_bindings_for_input( &self, input: &[Keystroke], context_stack: &[KeyContext], ) -> Vec<KeyBinding>

Returns the bindings that input could still complete with more keystrokes, highest precedence first, for the given context_stack.

Use it to list the shortcuts available after a prefix, such as after ctrl-k. Bindings that match input exactly, and NoAction and Unbind entries, are not included.

Trait Implementations

impl Default for Keymap

fn default() -> Self

Returns the “default value” for a type.