#[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.
Trait Implementations§
impl StructuralPartialEq for KeyEvent
Auto Trait Implementations§
impl Forget for KeyEvent
impl Freeze for KeyEvent
impl Move for KeyEvent
impl RefUnwindSafe for KeyEvent
impl Send for KeyEvent
impl Sync for KeyEvent
impl Unpin for KeyEvent
impl UnsafeUnpin for KeyEvent
impl UnwindSafe for KeyEvent
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> ErasedDestructor for Twhere
T: 'static,
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more