Struct Keystroke 

pub struct Keystroke {
    pub modifiers: Modifiers,
    pub key: String,
    pub key_char: Option<String>,
}

A key press, with the modifier keys that were held when it happened.

The platform creates a keystroke for each key press. To write one by hand, as a binding or a test does, parse it from a string with Keystroke::parse:

let keystroke = Keystroke::parse("ctrl-shift-z").unwrap();
assert!(keystroke.modifiers.control);
assert!(keystroke.modifiers.shift);
assert_eq!(keystroke.key, "z");

See keyboard input for the bigger picture.

Fields

modifiers: Modifiers

The modifier keys held when the key was pressed.

key: String

The key that was pressed, named after the character printed on it, such as s, or a name such as enter or pageup for keys without a character.

For option-s on macOS this is s, not ß. On layouts without ASCII letters, such as Thai, this is the ASCII equivalent of the key, and the typed character is in key_char.

key_char: Option<String>

The text the key would type with the current layout and modifiers, if any.

This is Some("s") for s, Some("ß") for option-s on a US macOS layout, and None for cmd-s, because cmd doesn’t type text.

Implementations

impl Keystroke

pub fn should_match(&self, target: &KeybindingKeystroke) -> bool

Returns whether this keystroke, as typed, matches a keystroke in a keymap.

self is the keystroke the user typed and target is the one from the binding. Matching first compares modifiers and key. It also accepts a target whose key is this keystroke’s key_char, when the target’s modifiers are exactly this keystroke’s ctrl and cmd (on Windows, when the target has no modifiers). That covers layouts where a binding key sits behind option, such as $ on a Czech keyboard typed as alt-ç, and input methods that turn a sequence of keys into one character.

pub fn parse(source: &str) -> Result<Self, InvalidKeystrokeError>

Parses a keystroke from text such as cmd-s, ctrl-shift-tab or cmd--.

The syntax is zero or more modifiers, then a key, separated by -:

• Modifiers are ctrl, alt, shift, fn, secondary, cmd, super and win. They can come in any order and any case. cmd, super and win all set Modifiers::platform. secondary sets cmd on macOS and ctrl on other platforms, which is what Modifiers::secondary reports.
• The key is the last part. Any other part must be a modifier. Key names are case-insensitive and stored in lowercase, so Tab and tab are the same key. Other text is accepted as a key without checking, but the names that platforms produce are space, tab, enter, backspace, escape, delete, insert, home, end, pageup, pagedown, up, down, left, right and function keys such as f1.
• A single uppercase letter sets shift and uses the lowercase letter as the key, so S is shift-s.
• A key of - is written as an extra dash, so cmd-- is cmd and -.
• A modifier with no key becomes the key. The first of shift, ctrl, alt, cmd and fn that is present is used, in that order. Its key is named shift, control, alt, platform or function, and that modifier is cleared. So ctrl alone is the key control with no modifiers set.
• key->key_char sets key_char to the text after ->, for example alt-s->ß. Keystroke::should_match ignores it when matching a binding.

Errors

Returns InvalidKeystrokeError if a part before the key isn’t a modifier, as in ctrl-a-b, or if -> isn’t followed by a key character.

Examples

let save = Keystroke::parse("secondary-s").unwrap();
assert!(save.modifiers.secondary());
assert_eq!(save.key, "s");

let shifted = Keystroke::parse("S").unwrap();
assert!(shifted.modifiers.shift);
assert_eq!(shifted.key, "s");

assert!(Keystroke::parse("ctrl-a-b").is_err());

See keyboard input for how bindings use these.

pub fn unparse(&self) -> String

Returns text that Keystroke::parse reads back as this keystroke.

The platform’s name for cmd is used: cmd on macOS, super on Linux and win on Windows. key_char is not included, so the result doesn’t round-trip when it is set.

pub fn is_ime_in_progress(&self) -> bool

Returns whether an input method is still composing text for this keystroke.

This is true when key_char is None, the key is printable or empty (not a named key such as escape or f1), and none of cmd, ctrl, fn or alt is held. shift alone doesn’t count.

pub fn with_simulated_ime(self) -> Self

Returns this keystroke with key_char set to the text it would type.

Simulated keystrokes use this so that they type text as a real key press does. It only applies when key_char is None and none of cmd, ctrl, fn or alt is held. space, tab and enter type a space, a tab and a newline. Other printable keys type their character, uppercased when shift is held.

Trait Implementations

impl AsKeystroke for Keystroke

fn as_keystroke(&self) -> &Keystroke

Returns the Keystroke this value represents.

impl Clone for Keystroke

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 Keystroke

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

Formats the value using the given formatter.

impl Default for Keystroke

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Keystroke

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Keystroke

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

Formats the value using the given formatter.

impl Eq for Keystroke

impl Hash for Keystroke

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Keystroke

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Keystroke