pub struct KeyEvent {
pub key: String,
pub modifiers: u8,
pub text: Option<String>,
}Fields§
§key: StringThe key’s name, in the web KeyboardEvent.key vocabulary every platform can map onto:
the four arrows (“ArrowLeft”, “ArrowRight”, “ArrowUp”, “ArrowDown”) and the ten digits
(“0” through “9”, from the main row or the numeric keypad) everywhere, plus
“Delete” and “Backspace” on backends with no menu bar (Cap::AppMenu unsupported),
where no accelerator can own those keys. A focused piece claims every key the route
carries, so offering them on a menu-bar platform would let a canvas swallow the Delete
its own Edit menu was about to act on (docs/menus.md). The two delete keys keep the
names the platform gives the physical keys (a Mac’s ⌫ is “Backspace” and its ⌦ is
“Delete”), so a handler that means “remove this” takes both. A digit arrives only while
neither KeyEvent::PRIMARY nor KeyEvent::ALT (nor a Mac’s Control) is held: ⌘1
and Ctrl+1 are accelerators, and a canvas claiming them would starve the menu. Most
backends name the digit the keypress types, so a layout whose number row needs Shift for
digits reports “1” with KeyEvent::SHIFT set; XAML and ArkUI read the physical key.
Backends emit Event::Key only while no text widget has focus; a field’s own editing
keys never surface here.
A piece that declared Decorate::keyboard() takes the full route instead: every key
the platform delivers while it is focused. A key that types nothing is named by its
web name (KeyEvent::NAMED: “Enter”, “Tab”, “Escape”, “Backspace”, “Delete”, “Home”,
“End”, “PageUp”, “PageDown”, “Insert”, the arrows and “F1” through “F12”); a key that
types is named by its unmodified character (“a”, “A” under Shift, “8”, “ü” on a layout
that has one), and what it typed rides in KeyEvent::text. Under Control or Alt the
name stays that character (“c” with KeyEvent::CONTROL set, never the control code
it would type). Text an input method commits (a dead-key accent, a Japanese phrase,
the soft keyboard’s word) arrives with the text alone and an empty name: no single
key is behind it. Only the platform’s command chords stay out: ⌘ on Apple platforms
and the browser’s own shortcuts belong to the menu and the browser, so a terminal’s
⌘C still copies. KeyEvent::typed is the question a text consumer asks.
modifiers: u8§text: Option<String>The text this press committed, on the full route: what the key typed (“a”, “A”, “é”
after a dead key, the whole string an input method committed at once), or None for
a key that typed nothing (a named key, a Control or Alt chord, a composition still in
progress). Separate from KeyEvent::key so that a committed “Enter” is text and the
Enter key is a key, whatever the input method sends. Always None on the short route.
Implementations§
Source§impl KeyEvent
impl KeyEvent
pub const SHIFT: u8 = 1
Sourcepub const PRIMARY: u8 = 2
pub const PRIMARY: u8 = 2
The platform’s command key: ⌘ on Apple platforms, Ctrl elsewhere (the
Shortcut::primary convention).
pub const ALT: u8 = 4
Sourcepub const CONTROL: u8 = 8
pub const CONTROL: u8 = 8
The Control key itself, wherever it sits: on Apple platforms it is a different key from
KeyEvent::PRIMARY (⌘), elsewhere the same one, so a Ctrl+C on Linux sets both.
Carried on the full route only (Decorate::keyboard).
Sourcepub const NAMED: [&'static str; 26]
pub const NAMED: [&'static str; 26]
Every name the full route gives a key that types nothing (the web KeyboardEvent.key
vocabulary). A key outside this list is named by the text it types.
Sourcepub fn typed(&self) -> Option<&str>
pub fn typed(&self) -> Option<&str>
The text this press typed (KeyEvent::text), or None for a key that typed nothing.
Sourcepub fn named(key: impl Into<String>, modifiers: u8) -> KeyEvent
pub fn named(key: impl Into<String>, modifiers: u8) -> KeyEvent
A key that types nothing (one of KeyEvent::NAMED, or a chord’s character under
Control or Alt), on either route.
Sourcepub fn typed_text(text: impl Into<String>, modifiers: u8) -> KeyEvent
pub fn typed_text(text: impl Into<String>, modifiers: u8) -> KeyEvent
Text a press committed on the full route. The key is named by the text when the text is one character (the press typed it), and left empty for a longer commit, which no single key is behind.
Sourcepub fn typed_by(
key: impl Into<String>,
text: impl Into<String>,
modifiers: u8,
) -> KeyEvent
pub fn typed_by( key: impl Into<String>, text: impl Into<String>, modifiers: u8, ) -> KeyEvent
Text a press committed on the full route, named by the key that produced it
(key, in the vocabulary above) when the backend knows it.
Sourcepub fn function_name(n: u8) -> Option<&'static str>
pub fn function_name(n: u8) -> Option<&'static str>
The web name for the function key F<n>, 1..=12.
Sourcepub fn digit_name(c: char) -> Option<&'static str>
pub fn digit_name(c: char) -> Option<&'static str>
The key name for a typed character when it is one of the ten digits: what a backend
reports for a keypress that types 0–9.