#[non_exhaustive]pub struct KeyEvent {
pub key: Key,
pub modifiers: Modifiers,
pub text: Option<String>,
pub phase: KeyPhase,
}Expand description
One key event for the focused piece (Decorate::on_key, Decorate::on_key_up).
Build one with KeyEvent::new, KeyEvent::named, KeyEvent::typed_text or
KeyEvent::typed_by, then KeyEvent::with_phase for a repeat or a release.
Fields (Non-exhaustive)§
This struct is marked as non-exhaustive
Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.key: KeyThe key. On the short route (a focusable piece or a canvas) the four arrows and the ten
digits (from the main row or the numeric keypad) arrive everywhere, plus
Key::Delete and Key::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 Primary nor 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 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.
The one exception is a single-line text field with a key handler (keys::handled for
its node): it hands Key::ArrowUp, Key::ArrowDown and Key::Escape, pressed
with no modifier, to that handler instead of acting on them itself, so an address bar
can walk a suggestion list (docs/textfield.md “Keys”).
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 a named variant
(KeyEvent::NAMED lists their web names); a key that types is Key::Character
with 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 key
stays that character ('c' with 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 Key::Unidentified: 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: ModifiersThe modifiers held with the key.
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
and on a release.
phase: KeyPhaseWhether the key went down, repeated while held, or came up. Decorate::on_key
receives Down and Repeat; Decorate::on_key_up receives Up.
Implementations§
Source§impl KeyEvent
impl KeyEvent
Sourcepub const DIGITS: [&'static str; 10]
pub const DIGITS: [&'static str; 10]
The ten digit key names, indexed by value: a backend’s key-code table.
Sourcepub const NAMED: [&'static str; 26]
pub const NAMED: [&'static str; 26]
The web KeyboardEvent.key name of every key that types nothing, as a backend’s wire
and a dayscript key: step spell them. A name outside this list is the text it types.
Sourcepub fn new(key: Key, modifiers: Modifiers) -> KeyEvent
pub fn new(key: Key, modifiers: Modifiers) -> KeyEvent
A press of key with modifiers held that typed nothing.
Sourcepub fn with_phase(self, phase: KeyPhase) -> KeyEvent
pub fn with_phase(self, phase: KeyPhase) -> KeyEvent
This event in another phase: KeyEvent::new(Key::ArrowLeft, Modifiers::NONE)
.with_phase(KeyPhase::Up) is the release. A release carries no text.
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<Key>, modifiers: impl Into<Modifiers>) -> KeyEvent
pub fn named(key: impl Into<Key>, modifiers: impl Into<Modifiers>) -> KeyEvent
A key that types nothing (a named key, or a chord’s character under Control or Alt),
on either route. A backend passes the key’s web name and its wire modifier mask; both
convert (Key::from_name, Modifiers::from_bits).
Sourcepub fn typed_text(
text: impl Into<String>,
modifiers: impl Into<Modifiers>,
) -> KeyEvent
pub fn typed_text( text: impl Into<String>, modifiers: impl Into<Modifiers>, ) -> KeyEvent
Text a press committed on the full route. The key is the text’s character when the
text is one character (the press typed it), and Key::Unidentified for a longer
commit, which no single key is behind.
Sourcepub fn typed_by(
key: impl Into<Key>,
text: impl Into<String>,
modifiers: impl Into<Modifiers>,
) -> KeyEvent
pub fn typed_by( key: impl Into<Key>, text: impl Into<String>, modifiers: impl Into<Modifiers>, ) -> KeyEvent
Text a press committed on the full route, with the key that produced it 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.
Sourcepub fn primary(&self) -> bool
pub fn primary(&self) -> bool
Whether the platform’s command key is held (Modifiers::PRIMARY).
Sourcepub fn control(&self) -> bool
pub fn control(&self) -> bool
Whether the Control key itself is held (Modifiers::CONTROL).
Sourcepub fn is_press(&self) -> bool
pub fn is_press(&self) -> bool
Whether the key went down or repeated: what Decorate::on_key delivers.
Sourcepub fn is_release(&self) -> bool
pub fn is_release(&self) -> bool
Whether the key came up.