Files
craft-libs/crates/keymap/src/chord.rs
T
aiongg 46bd564b75 top-w2: net change of 6 commits
- top-w2: written by an agent
- top-w2: finished by an agent
- top-w2: review fixes (review-1)
- top-w2: the menu-letter step of the shortcut trial types its letter as text, which mnemonics read (top run round)
- top-w2: typed letters in a menu go to the container of the focused row's level, with a trial for a title-click menu (top run round)
- top-w2: a menu row's pick walks out from the menu it runs in, with a trial for Cut from the Help search field's edit menu (top run round)
2026-11-15 04:46:09 +00:00

827 lines
29 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! Keys, modifiers, chords and their text forms.
//!
//! Canonical text is `Cmd+Ctrl+Alt+Shift+Key`, written by [`Chord`]'s `Display` and read back by
//! [`Chord::parse`]. A double press is the chord twice, separated by a space: `A A`.
use std::fmt;
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use crate::layout::Layout;
use crate::parity::ReturnGlyph;
pub mod foreign;
/// The longest chord or trigger text [`Chord::parse`] and [`Trigger::parse`] accept, in bytes.
pub const MAX_CHORD_TEXT: usize = 72;
/// The platform a keymap is used on. It decides display text and whether `ctrl` folds into `cmd`.
pub use craft_host::target::Os as Platform;
macro_rules! keys {
($($variant:ident => $name:literal),* $(,)?) => {
/// A key on the keyboard, independent of any UI toolkit.
///
/// Digits are the main row; numeric keypad keys map to the same keys.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[non_exhaustive]
pub enum Key {
$(#[allow(missing_docs)] $variant),*
}
impl Key {
/// The W3C `KeyboardEvent.code` of the physical key that types this key on a US keyboard: `KeyA`, `Digit5`,
/// `F10`, `ArrowUp`, `Equal`. A shifted key (`+`, `:`, `?`, `{`) names the key it is typed on.
pub const fn code_name(self) -> &'static str {
match self {
Key::A => "KeyA",
Key::B => "KeyB",
Key::C => "KeyC",
Key::D => "KeyD",
Key::E => "KeyE",
Key::F => "KeyF",
Key::G => "KeyG",
Key::H => "KeyH",
Key::I => "KeyI",
Key::J => "KeyJ",
Key::K => "KeyK",
Key::L => "KeyL",
Key::M => "KeyM",
Key::N => "KeyN",
Key::O => "KeyO",
Key::P => "KeyP",
Key::Q => "KeyQ",
Key::R => "KeyR",
Key::S => "KeyS",
Key::T => "KeyT",
Key::U => "KeyU",
Key::V => "KeyV",
Key::W => "KeyW",
Key::X => "KeyX",
Key::Y => "KeyY",
Key::Z => "KeyZ",
Key::Num0 => "Digit0",
Key::Num1 => "Digit1",
Key::Num2 => "Digit2",
Key::Num3 => "Digit3",
Key::Num4 => "Digit4",
Key::Num5 => "Digit5",
Key::Num6 => "Digit6",
Key::Num7 => "Digit7",
Key::Num8 => "Digit8",
Key::Num9 => "Digit9",
Key::F1 => "F1",
Key::F2 => "F2",
Key::F3 => "F3",
Key::F4 => "F4",
Key::F5 => "F5",
Key::F6 => "F6",
Key::F7 => "F7",
Key::F8 => "F8",
Key::F9 => "F9",
Key::F10 => "F10",
Key::F11 => "F11",
Key::F12 => "F12",
Key::F13 => "F13",
Key::F14 => "F14",
Key::F15 => "F15",
Key::F16 => "F16",
Key::F17 => "F17",
Key::F18 => "F18",
Key::F19 => "F19",
Key::F20 => "F20",
Key::F21 => "F21",
Key::F22 => "F22",
Key::F23 => "F23",
Key::F24 => "F24",
Key::F25 => "F25",
Key::F26 => "F26",
Key::F27 => "F27",
Key::F28 => "F28",
Key::F29 => "F29",
Key::F30 => "F30",
Key::F31 => "F31",
Key::F32 => "F32",
Key::F33 => "F33",
Key::F34 => "F34",
Key::F35 => "F35",
Key::Escape => "Escape",
Key::Tab => "Tab",
Key::Menu => "ContextMenu",
Key::Backspace => "Backspace",
Key::Enter => "Enter",
Key::Space => "Space",
Key::Insert => "Insert",
Key::Delete => "Delete",
Key::Home => "Home",
Key::End => "End",
Key::PageUp => "PageUp",
Key::PageDown => "PageDown",
Key::Up => "ArrowUp",
Key::Down => "ArrowDown",
Key::Left => "ArrowLeft",
Key::Right => "ArrowRight",
Key::Minus => "Minus",
Key::Equals | Key::Plus => "Equal",
Key::OpenBracket | Key::OpenCurlyBracket => "BracketLeft",
Key::CloseBracket | Key::CloseCurlyBracket => "BracketRight",
Key::Backslash | Key::Pipe => "Backslash",
Key::Semicolon | Key::Colon => "Semicolon",
Key::Quote => "Quote",
Key::Backtick => "Backquote",
Key::Comma => "Comma",
Key::Period => "Period",
Key::Slash | Key::Questionmark => "Slash",
Key::IntlBackslash => "IntlBackslash",
Key::Exclamationmark => "Digit1",
}
}
/// Every key, in declaration order.
pub const ALL: &'static [Key] = &[$(Key::$variant),*];
/// The canonical name: `K`, `5`, `F5`, `PageUp`, `;`.
pub const fn name(self) -> &'static str {
match self {
$(Key::$variant => $name),*
}
}
// The Rust variant name, which is also egui's `Key` variant name except for arrows.
const fn variant_name(self) -> &'static str {
match self {
$(Key::$variant => stringify!($variant)),*
}
}
}
};
}
keys! {
A => "A", B => "B", C => "C", D => "D", E => "E", F => "F", G => "G", H => "H", I => "I",
J => "J", K => "K", L => "L", M => "M", N => "N", O => "O", P => "P", Q => "Q", R => "R",
S => "S", T => "T", U => "U", V => "V", W => "W", X => "X", Y => "Y", Z => "Z",
Num0 => "0", Num1 => "1", Num2 => "2", Num3 => "3", Num4 => "4",
Num5 => "5", Num6 => "6", Num7 => "7", Num8 => "8", Num9 => "9",
F1 => "F1", F2 => "F2", F3 => "F3", F4 => "F4", F5 => "F5", F6 => "F6", F7 => "F7",
F8 => "F8", F9 => "F9", F10 => "F10", F11 => "F11", F12 => "F12", F13 => "F13",
F14 => "F14", F15 => "F15", F16 => "F16", F17 => "F17", F18 => "F18", F19 => "F19",
F20 => "F20", F21 => "F21", F22 => "F22", F23 => "F23", F24 => "F24", F25 => "F25",
F26 => "F26", F27 => "F27", F28 => "F28", F29 => "F29", F30 => "F30", F31 => "F31",
F32 => "F32", F33 => "F33", F34 => "F34", F35 => "F35",
Escape => "Escape", Tab => "Tab", Menu => "Menu", Backspace => "Backspace", Enter => "Enter",
Space => "Space", Insert => "Insert", Delete => "Delete", Home => "Home", End => "End",
PageUp => "PageUp", PageDown => "PageDown",
Up => "Up", Down => "Down", Left => "Left", Right => "Right",
Minus => "-", Equals => "=", Plus => "+", OpenBracket => "[", CloseBracket => "]",
Backslash => "\\", Semicolon => ";", Quote => "'", Backtick => "`",
Comma => ",", Period => ".", Slash => "/", IntlBackslash => "IntlBackslash",
Colon => ":", Pipe => "|", Questionmark => "?", Exclamationmark => "!",
OpenCurlyBracket => "{", CloseCurlyBracket => "}",
}
/// Key aliases beyond the canonical and egui variant names. Matched without regard to ASCII case.
const KEY_ALIASES: &[(&str, Key)] = &[
("esc", Key::Escape),
("⎋", Key::Escape),
("return", Key::Enter),
("⏎", Key::Enter),
("↩", Key::Enter),
("del", Key::Delete),
("⌦", Key::Delete),
("⌫", Key::Backspace),
("⇥", Key::Tab),
("pgup", Key::PageUp),
("pgdn", Key::PageDown),
("page up", Key::PageUp),
("page down", Key::PageDown),
("arrowup", Key::Up),
("arrowdown", Key::Down),
("arrowleft", Key::Left),
("arrowright", Key::Right),
("↑", Key::Up),
("↓", Key::Down),
("←", Key::Left),
("→", Key::Right),
("spacebar", Key::Space),
("ins", Key::Insert),
("equal", Key::Equals),
("grave", Key::Backtick),
("backquote", Key::Backtick),
("apostrophe", Key::Quote),
// The minus sign menus and docs print (U+2212), not the hyphen-minus the key types.
("−", Key::Minus),
];
impl Key {
/// Reads a key name: canonical (`K`, `PageUp`, `;`), egui variant names (`ArrowUp`, `Num5`,
/// `Semicolon`) and the aliases `esc`, `return`, `del`, `pgup`, `pgdn`, `spacebar`, `ins`,
/// the Mac key glyphs and the minus sign `−`. Case does not matter.
pub fn parse(name: &str) -> Option<Key> {
Key::ALL
.iter()
.copied()
.find(|k| k.name().eq_ignore_ascii_case(name) || k.variant_name().eq_ignore_ascii_case(name))
.or_else(|| KEY_ALIASES.iter().find(|(alias, _)| alias.eq_ignore_ascii_case(name)).map(|&(_, k)| k))
}
/// `A` to `Z`.
pub const fn is_letter(self) -> bool {
matches!(
self,
Key::A
| Key::B
| Key::C
| Key::D
| Key::E
| Key::F
| Key::G
| Key::H
| Key::I
| Key::J
| Key::K
| Key::L
| Key::M
| Key::N
| Key::O
| Key::P
| Key::Q
| Key::R
| Key::S
| Key::T
| Key::U
| Key::V
| Key::W
| Key::X
| Key::Y
| Key::Z
)
}
/// `0` to `9`.
pub const fn is_digit(self) -> bool {
matches!(self, Key::Num0 | Key::Num1 | Key::Num2 | Key::Num3 | Key::Num4 | Key::Num5 | Key::Num6 | Key::Num7 | Key::Num8 | Key::Num9)
}
/// Punctuation and symbol keys: `-`, `=`, `+`, brackets, `\`, `;`, `'`, `` ` ``, `,`, `.`,
/// `/`, the ISO key next to left Shift (`IntlBackslash`) and the shifted symbols `:`, `|`,
/// `?`, `!`, `{`, `}`.
pub const fn is_symbol(self) -> bool {
matches!(
self,
Key::Minus
| Key::Equals
| Key::Plus
| Key::OpenBracket
| Key::CloseBracket
| Key::Backslash
| Key::Semicolon
| Key::Quote
| Key::Backtick
| Key::Comma
| Key::Period
| Key::Slash
| Key::IntlBackslash
| Key::Colon
| Key::Pipe
| Key::Questionmark
| Key::Exclamationmark
| Key::OpenCurlyBracket
| Key::CloseCurlyBracket
)
}
/// The letter, digit or symbol key for a typed character, ignoring case.
pub fn from_char(c: char) -> Option<Key> {
let mut buf = [0; 4];
let text: &str = c.encode_utf8(&mut buf);
Key::ALL.iter().copied().find(|k| (k.is_letter() || k.is_digit() || k.is_symbol()) && k.name().eq_ignore_ascii_case(text))
}
/// `F1` to `F35`.
pub const fn is_function_key(self) -> bool {
matches!(
self,
Key::F1
| Key::F2
| Key::F3
| Key::F4
| Key::F5
| Key::F6
| Key::F7
| Key::F8
| Key::F9
| Key::F10
| Key::F11
| Key::F12
| Key::F13
| Key::F14
| Key::F15
| Key::F16
| Key::F17
| Key::F18
| Key::F19
| Key::F20
| Key::F21
| Key::F22
| Key::F23
| Key::F24
| Key::F25
| Key::F26
| Key::F27
| Key::F28
| Key::F29
| Key::F30
| Key::F31
| Key::F32
| Key::F33
| Key::F34
| Key::F35
)
}
/// The key as macOS menus show it: arrows and editing keys as glyphs.
pub(crate) fn mac_symbol(self, glyph: ReturnGlyph) -> &'static str {
match self {
Key::Up => "↑",
Key::Down => "↓",
Key::Left => "←",
Key::Right => "→",
Key::Enter => glyph.symbol(),
Key::Backspace => "⌫",
Key::Delete => "⌦",
Key::Escape => "⎋",
Key::Tab => "⇥",
k => k.text_name(),
}
}
/// The key as Windows and Linux show it.
pub(crate) fn text_name(self) -> &'static str {
match self {
Key::PageUp => "Page Up",
Key::PageDown => "Page Down",
k => k.name(),
}
}
}
impl fmt::Display for Key {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.name())
}
}
impl Serialize for Key {
fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
serializer.serialize_str(self.name())
}
}
impl<'de> Deserialize<'de> for Key {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Key, D::Error> {
let text = <std::borrow::Cow<'de, str>>::deserialize(deserializer)?;
if text.len() > MAX_CHORD_TEXT {
return Err(serde::de::Error::custom(ParseError::TooLong));
}
Key::parse(&text).ok_or_else(|| serde::de::Error::custom(ParseError::UnknownKey(text.into_owned())))
}
}
/// Modifier keys held with a chord's key.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
pub struct Mods {
/// The command modifier: ⌘ on macOS, Ctrl on Windows and Linux.
pub cmd: bool,
/// The Control key on macOS. Off macOS it folds into `cmd`.
pub ctrl: bool,
/// Alt, Option on macOS.
pub alt: bool,
/// The Shift key.
pub shift: bool,
}
impl Mods {
/// No modifiers.
pub const NONE: Mods = Mods { cmd: false, ctrl: false, alt: false, shift: false };
/// Only [`cmd`](Mods::cmd).
pub const CMD: Mods = Mods { cmd: true, ctrl: false, alt: false, shift: false };
/// Only [`ctrl`](Mods::ctrl).
pub const CTRL: Mods = Mods { cmd: false, ctrl: true, alt: false, shift: false };
/// Only [`alt`](Mods::alt).
pub const ALT: Mods = Mods { cmd: false, ctrl: false, alt: true, shift: false };
/// Only [`shift`](Mods::shift).
pub const SHIFT: Mods = Mods { cmd: false, ctrl: false, alt: false, shift: true };
/// Whether no modifier is held.
pub const fn is_none(self) -> bool {
!(self.cmd || self.ctrl || self.alt || self.shift)
}
/// The modifiers' text before a key: `⌃⌥⇧⌘` on macOS, `Ctrl+Alt+Shift+` elsewhere.
pub(crate) fn prefix(self, platform: Platform) -> String {
let parts = self.parts(platform);
if platform.is_mac() { parts.concat() } else { parts.iter().map(|name| format!("{name}+")).collect() }
}
/// The held modifiers one by one, in the platform's order: `⌃ ⌥ ⇧ ⌘` on macOS, `Ctrl Alt Shift` elsewhere.
pub fn parts(self, platform: Platform) -> Vec<&'static str> {
let m = self.effective(platform);
let table: [(bool, &'static str); 4] = if platform.is_mac() {
[(m.ctrl, "⌃"), (m.alt, "⌥"), (m.shift, "⇧"), (m.cmd, "⌘")]
} else {
[(m.cmd, "Ctrl"), (m.alt, "Alt"), (m.shift, "Shift"), (false, "")]
};
table.into_iter().filter(|(on, _)| *on).map(|(_, name)| name).collect()
}
/// The held modifiers' names for a screen reader, in the platform's order: `Ctrl Option Shift Cmd` on macOS,
/// `Ctrl Alt Shift` elsewhere.
pub fn spoken(self, platform: Platform) -> Vec<&'static str> {
let m = self.effective(platform);
let table: [(bool, &'static str); 4] = if platform.is_mac() {
[(m.ctrl, "Ctrl"), (m.alt, "Option"), (m.shift, "Shift"), (m.cmd, "Cmd")]
} else {
[(m.cmd, "Ctrl"), (m.alt, "Alt"), (m.shift, "Shift"), (false, "")]
};
table.into_iter().filter(|(on, _)| *on).map(|(_, name)| name).collect()
}
/// The modifiers as `platform` sees them: off macOS `ctrl` becomes `cmd`.
pub const fn effective(self, platform: Platform) -> Mods {
if platform.is_mac() || !self.ctrl { self } else { Mods { cmd: true, ctrl: false, ..self } }
}
}
/// A key with modifiers.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct Chord {
/// The modifiers held with the key.
pub mods: Mods,
/// The key.
pub key: Key,
}
/// Why chord or trigger text was refused.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub enum ParseError {
/// The text is empty.
Empty,
/// Longer than [`MAX_CHORD_TEXT`].
TooLong,
/// Modifiers with no key, or a trailing `+`.
MissingKey,
/// A key name nothing here recognises, as written.
UnknownKey(String),
/// A modifier name nothing here recognises, as written.
UnknownModifier(String),
/// A modifier written twice, as written.
DuplicateModifier(String),
/// Two different chords: key sequences are not supported.
Sequence,
}
impl fmt::Display for ParseError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
ParseError::Empty => f.write_str("empty shortcut"),
ParseError::TooLong => write!(f, "shortcut longer than {MAX_CHORD_TEXT} bytes"),
ParseError::MissingKey => f.write_str("shortcut has no key"),
ParseError::UnknownKey(k) => write!(f, "unknown key `{k}`"),
ParseError::UnknownModifier(m) => write!(f, "unknown modifier `{m}`"),
ParseError::DuplicateModifier(m) => write!(f, "modifier `{m}` given twice"),
ParseError::Sequence => f.write_str("key sequences are not supported"),
}
}
}
impl std::error::Error for ParseError {}
#[derive(Clone, Copy)]
enum Modifier {
Cmd,
Ctrl,
Alt,
Shift,
}
fn modifier_named(name: &str) -> Option<Modifier> {
const NAMES: &[(&str, Modifier)] = &[
("cmd", Modifier::Cmd),
("command", Modifier::Cmd),
("meta", Modifier::Cmd),
("super", Modifier::Cmd),
("mod", Modifier::Cmd),
("⌘", Modifier::Cmd),
("ctrl", Modifier::Ctrl),
("control", Modifier::Ctrl),
("ctl", Modifier::Ctrl),
("⌃", Modifier::Ctrl),
("alt", Modifier::Alt),
("opt", Modifier::Alt),
("option", Modifier::Alt),
("⌥", Modifier::Alt),
("shift", Modifier::Shift),
("⇧", Modifier::Shift),
];
NAMES.iter().find(|(n, _)| n.eq_ignore_ascii_case(name)).map(|&(_, m)| m)
}
/// A modifier glyph at the start of `text`, and the text after it.
fn strip_glyph(text: &str) -> Option<(Modifier, &str)> {
let mut chars = text.chars();
let m = match chars.next()? {
'⌘' => Modifier::Cmd,
'⌃' => Modifier::Ctrl,
'⌥' => Modifier::Alt,
'⇧' => Modifier::Shift,
_ => return None,
};
Some((m, chars.as_str()))
}
fn add_modifier(mods: &mut Mods, m: Modifier, written: &str) -> Result<(), ParseError> {
let slot = match m {
Modifier::Cmd => &mut mods.cmd,
Modifier::Ctrl => &mut mods.ctrl,
Modifier::Alt => &mut mods.alt,
Modifier::Shift => &mut mods.shift,
};
if *slot {
return Err(ParseError::DuplicateModifier(written.to_owned()));
}
*slot = true;
Ok(())
}
impl Chord {
/// A chord of `key` held with `mods`.
pub const fn new(mods: Mods, key: Key) -> Chord {
Chord { mods, key }
}
/// The key with no modifiers.
pub const fn plain(key: Key) -> Chord {
Chord { mods: Mods::NONE, key }
}
/// Reads canonical text (`Cmd+Shift+Z`) and the common aliases: modifier words in any order
/// and case (`cmd command meta super mod`, `ctrl control ctl`, `alt opt option`, `shift`),
/// Mac glyphs, glued (`⇧⌘Z`) or with `+`, and the key names [`Key::parse`] reads. `Cmd++` is
/// Cmd with the Plus key.
pub fn parse(text: &str) -> Result<Chord, ParseError> {
if text.len() > MAX_CHORD_TEXT {
return Err(ParseError::TooLong);
}
let mut rest = text.trim();
if rest.is_empty() {
return Err(ParseError::Empty);
}
let mut mods = Mods::NONE;
// Each pass consumes at least one byte, so the loop ends within MAX_CHORD_TEXT passes.
loop {
if let Some((m, after)) = strip_glyph(rest) {
add_modifier(&mut mods, m, rest.get(..rest.len() - after.len()).unwrap_or_default())?;
// `⌘+K` and `⌘K` are the same; in `⌘+` the `+` is the key.
rest = match after.strip_prefix('+') {
Some(r) if !r.is_empty() => r,
_ => after,
};
if rest.trim().is_empty() {
return Err(ParseError::MissingKey);
}
continue;
}
// A `+` in first position is the Plus key, never a separator.
let first = rest.chars().next().map_or(0, char::len_utf8);
let separator = rest.get(first..).and_then(|r| r.find('+')).map(|i| i + first);
match separator {
Some(i) => {
let token = rest.get(..i).unwrap_or_default().trim();
let after = rest.get(i + 1..).unwrap_or_default();
if after.trim().is_empty() {
return Err(ParseError::MissingKey);
}
let m = modifier_named(token).ok_or_else(|| ParseError::UnknownModifier(token.to_owned()))?;
add_modifier(&mut mods, m, token)?;
rest = after;
}
None => {
let token = rest.trim();
if modifier_named(token).is_some() {
return Err(ParseError::MissingKey);
}
let key = Key::parse(token).ok_or_else(|| ParseError::UnknownKey(token.to_owned()))?;
return Ok(Chord { mods, key });
}
}
}
}
/// Canonical text, the same as `to_string()`: `Cmd+Ctrl+Alt+Shift+Key`.
pub fn portable(&self) -> String {
self.to_string()
}
/// The chord as `platform` sees it: off macOS `ctrl` folds into `cmd`. Lookups and conflict
/// checks compare effective chords.
pub const fn effective(self, platform: Platform) -> Chord {
Chord { mods: self.mods.effective(platform), key: self.key }
}
/// Text for menus and settings: `⌃⌥⇧⌘K` on macOS, `Ctrl+Alt+Shift+K` elsewhere.
pub fn display(&self, platform: Platform) -> String {
self.display_key(platform, None)
}
/// [`display`](Self::display) for the keys of `layout`: a punctuation key shows the character
/// the layout types at its position when that character has no key of its own (`Ctrl+Ü` for
/// Ctrl+[ on German). Letters and digits show as in `display`.
pub fn display_for(&self, platform: Platform, layout: &Layout) -> String {
self.display_key(platform, layout.key_label(self.key).as_deref())
}
fn display_key(&self, platform: Platform, key_text: Option<&str>) -> String {
self.display_key_with(platform, key_text, ReturnGlyph::Enter)
}
pub(crate) fn display_key_with(&self, platform: Platform, key_text: Option<&str>, glyph: ReturnGlyph) -> String {
let mut s = self.mods.prefix(platform);
s.push_str(&self.key_text(platform, key_text, glyph));
s
}
fn key_text(&self, platform: Platform, key_text: Option<&str>, glyph: ReturnGlyph) -> String {
match key_text {
Some(text) => text.to_owned(),
None if platform.is_mac() => self.key.mac_symbol(glyph).to_owned(),
None => self.key.text_name().to_owned(),
}
}
/// The chord as one text per key, modifiers first, each as [`display_for`](Self::display_for) writes it:
/// `["Ctrl", "Shift", "K"]`, or `["⇧", "⌘", "K"]` on macOS. A keycap is drawn around each.
pub fn parts_for(&self, platform: Platform, layout: &Layout) -> Vec<String> {
let mut parts: Vec<String> = self.mods.parts(platform).into_iter().map(str::to_owned).collect();
parts.push(self.key_text(platform, layout.key_label(self.key).as_deref(), ReturnGlyph::Enter));
parts
}
/// The chord as names for a screen reader and AccessKit's `keyboard_shortcut`, in the platform's order
/// whatever its symbols: `Ctrl+Option+Shift+Cmd+K` on macOS, `Ctrl+Alt+Shift+K` elsewhere.
pub fn spoken(&self, platform: Platform) -> String {
let mut names: Vec<&str> = self.mods.spoken(platform);
names.push(self.key.text_name());
names.join("+")
}
/// Whether the key is a function key.
pub const fn is_function_key(&self) -> bool {
self.key.is_function_key()
}
/// No cmd, ctrl or alt. Shift alone still counts as plain: such chords are tool keys that
/// typing in a text field would trigger.
pub const fn is_plain(&self) -> bool {
!(self.mods.cmd || self.mods.ctrl || self.mods.alt)
}
/// Holds the command modifier: cmd, or ctrl (Control on macOS, folded into cmd elsewhere).
pub const fn has_command(&self) -> bool {
self.mods.cmd || self.mods.ctrl
}
}
impl From<Key> for Chord {
fn from(key: Key) -> Chord {
Chord::plain(key)
}
}
impl fmt::Display for Chord {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
for (on, name) in [(self.mods.cmd, "Cmd+"), (self.mods.ctrl, "Ctrl+"), (self.mods.alt, "Alt+"), (self.mods.shift, "Shift+")] {
if on {
f.write_str(name)?;
}
}
f.write_str(self.key.name())
}
}
impl std::str::FromStr for Chord {
type Err = ParseError;
fn from_str(s: &str) -> Result<Chord, ParseError> {
Chord::parse(s)
}
}
impl Serialize for Chord {
fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
serializer.collect_str(self)
}
}
impl<'de> Deserialize<'de> for Chord {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Chord, D::Error> {
let text = <std::borrow::Cow<'de, str>>::deserialize(deserializer)?;
Chord::parse(&text).map_err(serde::de::Error::custom)
}
}
/// What starts a command: a chord, pressed once or twice in a row.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct Trigger {
/// The chord to press.
pub chord: Chord,
/// The chord pressed twice.
pub double: bool,
}
impl Trigger {
/// A trigger that fires on one press of `chord`.
pub const fn single(chord: Chord) -> Trigger {
Trigger { chord, double: false }
}
/// A trigger that fires on two presses of `chord` in a row.
pub const fn double(chord: Chord) -> Trigger {
Trigger { chord, double: true }
}
/// Reads a chord as [`Chord::parse`] does, or the same chord twice separated by whitespace
/// (`A A`) as a double press. Two different chords are [`ParseError::Sequence`].
pub fn parse(text: &str) -> Result<Trigger, ParseError> {
if text.len() > MAX_CHORD_TEXT {
return Err(ParseError::TooLong);
}
let single = match Chord::parse(text) {
Ok(chord) => return Ok(Trigger::single(chord)),
Err(e) => e,
};
let mut parts = text.split_whitespace();
match (parts.next(), parts.next(), parts.next()) {
(Some(first), Some(second), None) => {
let (first, second) = (Chord::parse(first)?, Chord::parse(second)?);
if first == second { Ok(Trigger::double(first)) } else { Err(ParseError::Sequence) }
}
_ => Err(single),
}
}
/// Canonical text, the same as `to_string()`.
pub fn portable(&self) -> String {
self.to_string()
}
/// The trigger with its chord's modifiers as `platform` sees them ([`Mods::effective`]).
pub const fn effective(self, platform: Platform) -> Trigger {
Trigger { chord: self.chord.effective(platform), double: self.double }
}
/// [`Chord::display`], twice with a space between for a double press.
pub fn display(&self, platform: Platform) -> String {
let one = self.chord.display(platform);
if self.double { format!("{one} {one}") } else { one }
}
/// [`Chord::display_for`], twice with a space between for a double press.
pub fn display_for(&self, platform: Platform, layout: &Layout) -> String {
let one = self.chord.display_for(platform, layout);
if self.double { format!("{one} {one}") } else { one }
}
}
impl From<Chord> for Trigger {
fn from(chord: Chord) -> Trigger {
Trigger::single(chord)
}
}
impl fmt::Display for Trigger {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
if self.double { write!(f, "{0} {0}", self.chord) } else { write!(f, "{}", self.chord) }
}
}
impl std::str::FromStr for Trigger {
type Err = ParseError;
fn from_str(s: &str) -> Result<Trigger, ParseError> {
Trigger::parse(s)
}
}
impl Serialize for Trigger {
fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
serializer.collect_str(self)
}
}
impl<'de> Deserialize<'de> for Trigger {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Trigger, D::Error> {
let text = <std::borrow::Cow<'de, str>>::deserialize(deserializer)?;
Trigger::parse(&text).map_err(serde::de::Error::custom)
}
}