Struct KeyBinding 

pub struct KeyBinding { /* private fields */ }

A keybinding: a keystroke sequence, the action it runs, and the key context it applies in.

You usually create one with KeyBinding::new and register it with App::bind_keys. Its accessors let you inspect a binding, for example to show its shortcut in a menu:

use gpui::{Action, KeyBinding, actions};

actions!(binding_docs, [Save]);

let binding = KeyBinding::new("cmd-k cmd-s", Save, Some("Editor"));
assert_eq!(binding.keystrokes().len(), 2);
assert_eq!(binding.action().name(), "binding_docs::Save");
assert!(binding.predicate().is_some());

See keyboard input for how bindings are matched against the focus path.

Implementations

impl KeyBinding

pub fn new<A: Action>( keystrokes: &str, action: A, context: Option<&str>, ) -> Self

Creates a binding that runs action when keystrokes is typed in context.

keystrokes is a whitespace-separated sequence of keystrokes, such as "cmd-s" or "ctrl-k ctrl-s". context is a key context predicate, such as "Editor" or "Editor && mode == insert". Pass None to make the binding apply everywhere, which counts as the deepest context for precedence.

Bindings made here use the keys as written. They never go through the platform’s keyboard mapping, so use this for bindings in code.

Panics

Panics if any keystroke or the context fails to parse. Use KeyBinding::load to get an error instead.

Examples

use gpui::{KeyBinding, actions};

actions!(binding_new_docs, [Save]);

let binding = KeyBinding::new("secondary-s", Save, Some("Editor"));
assert_eq!(binding.keystrokes().len(), 1);

pub fn load( keystrokes: &str, action: Box<dyn Action>, context_predicate: Option<Rc<KeyBindingContextPredicate>>, use_key_equivalents: bool, action_input: Option<SharedString>, keyboard_mapper: &dyn PlatformKeyboardMapper, ) -> Result<Self, InvalidKeystrokeError>

Creates a binding from the parts that a keymap file provides.

keystrokes is split on spaces and each part is parsed with Keystroke::parse. Each keystroke is then passed to keyboard_mapper, and use_key_equivalents asks it for the layout-dependent mapping. On macOS, that replaces a key with the character the current layout types for it. For bindings from a keymap file, action_input is the JSON the action was built from. Pass None when there is none.

Errors

Returns InvalidKeystrokeError if any keystroke fails to parse. The context is already parsed, so this function doesn’t check it.

pub fn with_meta(self, meta: KeyBindingMetaIndex) -> Self

Sets the source metadata for this binding and returns it.

See KeyBindingMetaIndex for how the keymap uses this. A binding without metadata counts as the strongest source.

pub fn set_meta(&mut self, meta: KeyBindingMetaIndex)

Sets the source metadata for this binding. See KeyBinding::with_meta.

pub fn match_keystrokes(&self, typed: &[impl AsKeystroke]) -> Option<bool>

Returns how the typed keystrokes relate to this binding’s keystroke sequence.

Returns None if they don’t match. Returns Some(true) if they match the start of the sequence and more keystrokes are needed, and Some(false) if they match all of it. The keymap uses this to decide whether to wait for the next key.

Examples

use gpui::{Keystroke, KeyBinding, actions};

actions!(match_docs, [Save]);

let binding = KeyBinding::new("ctrl-k ctrl-s", Save, None);
let ctrl_k = [Keystroke::parse("ctrl-k").unwrap()];
let ctrl_k_ctrl_s = [
    Keystroke::parse("ctrl-k").unwrap(),
    Keystroke::parse("ctrl-s").unwrap(),
];

assert_eq!(binding.match_keystrokes(&ctrl_k), Some(true));
assert_eq!(binding.match_keystrokes(&ctrl_k_ctrl_s), Some(false));
assert_eq!(binding.match_keystrokes(&[Keystroke::parse("ctrl-x").unwrap()]), None);

pub fn keystrokes(&self) -> &[KeybindingKeystroke]

Returns the keystrokes that trigger this binding, in order. A binding has one keystroke for a single key, and more for a sequence such as ctrl-k ctrl-s.

pub fn action(&self) -> &dyn Action

Returns the action this binding runs.

pub fn predicate(&self) -> Option<Rc<KeyBindingContextPredicate>>

Returns the key context predicate this binding applies in, or None if it applies in every context.

pub fn meta(&self) -> Option<KeyBindingMetaIndex>

Returns the source metadata set with KeyBinding::with_meta, if any.

pub fn action_input(&self) -> Option<SharedString>

Returns the JSON input the action was built from, if the binding came from a keymap file.

Trait Implementations

impl Clone for KeyBinding

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for KeyBinding

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.