Skip to main content

KeyEvent

Struct KeyEvent 

Source
#[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
Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.
§key: Key

The 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: Modifiers

The 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: KeyPhase

Whether 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

Source

pub const DIGITS: [&'static str; 10]

The ten digit key names, indexed by value: a backend’s key-code table.

Source

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.

Source

pub fn new(key: Key, modifiers: Modifiers) -> KeyEvent

A press of key with modifiers held that typed nothing.

Source

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.

Source

pub fn typed(&self) -> Option<&str>

The text this press typed (KeyEvent::text), or None for a key that typed nothing.

Source

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).

Source

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.

Source

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.

Source

pub fn function_name(n: u8) -> Option<&'static str>

The web name for the function key F<n>, 1..=12.

Source

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.

Source

pub fn digit(&self) -> Option<u8>

The value of a digit key, or None for every other key.

Source

pub fn shift(&self) -> bool

Whether Shift is held.

Source

pub fn primary(&self) -> bool

Whether the platform’s command key is held (Modifiers::PRIMARY).

Source

pub fn alt(&self) -> bool

Whether Alt (Option) is held.

Source

pub fn control(&self) -> bool

Whether the Control key itself is held (Modifiers::CONTROL).

Source

pub fn is_press(&self) -> bool

Whether the key went down or repeated: what Decorate::on_key delivers.

Source

pub fn is_repeat(&self) -> bool

Whether this is the platform repeating a held key.

Source

pub fn is_release(&self) -> bool

Whether the key came up.

Trait Implementations§

Source§

impl Clone for KeyEvent

Source§

fn clone(&self) -> KeyEvent

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for KeyEvent

Source§

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

Formats the value using the given formatter. Read more
Source§

impl PartialEq for KeyEvent

Source§

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

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

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

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for KeyEvent

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> AnyEq for T
where T: Any + PartialEq,

Source§

fn equals(&self, other: &(dyn Any + 'static)) -> bool

Source§

fn as_any(&self) -> &(dyn Any + 'static)

Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> ErasedDestructor for T
where T: 'static,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts 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
Source§

impl<T> IntoReactive<T, StaticMark> for T
where T: Clone + 'static,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.