Skip to main content

KeyEvent

Struct KeyEvent 

Source
pub struct KeyEvent {
    pub key: String,
    pub modifiers: u8,
    pub text: Option<String>,
}

Fields§

§key: String

The 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. The one exception is a single-line text field with a key handler (keys::handled for its node): it hands “ArrowUp”, “ArrowDown” and “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 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

Source

pub const SHIFT: u8 = 1

Source

pub const PRIMARY: u8 = 2

The platform’s command key: ⌘ on Apple platforms, Ctrl elsewhere (the Shortcut::primary convention).

Source

pub const ALT: u8 = 4

Source

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

Source

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

The ten digit key names, indexed by value.

Source

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.

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

Source

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.

Source

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.

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

Source

pub fn primary(&self) -> bool

Source

pub fn alt(&self) -> bool

Source

pub fn control(&self) -> bool

Trait Implementations§

Source§

impl Clone for KeyEvent

Source§

fn clone(&self) -> Self

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

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

impl PartialEq for KeyEvent

Source§

fn eq(&self, other: &Self) -> 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> 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> 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> 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.