Struct winit::event::KeyEvent

source ·
pub struct KeyEvent {
    pub physical_key: PhysicalKey,
    pub logical_key: Key,
    pub text: Option<SmolStr>,
    pub location: KeyLocation,
    pub state: ElementState,
    pub repeat: bool,
    /* private fields */
}
Expand description

Describes a keyboard input targeting a window.

Fields§

§physical_key: PhysicalKey

Represents the position of a key independent of the currently active layout.

It also uniquely identifies the physical key (i.e. it’s mostly synonymous with a scancode). The most prevalent use case for this is games. For example the default keys for the player to move around might be the W, A, S, and D keys on a US layout. The position of these keys is more important than their label, so they should map to Z, Q, S, and D on an “AZERTY” layout. (This value is KeyCode::KeyW for the Z key on an AZERTY layout.)

Caveats

  • Certain niche hardware will shuffle around physical key positions, e.g. a keyboard that implements DVORAK in hardware (or firmware)
  • Your application will likely have to handle keyboards which are missing keys that your own keyboard has.
  • Certain KeyCodes will move between a couple of different positions depending on what layout the keyboard was manufactured to support.

Because of these caveats, it is important that you provide users with a way to configure most (if not all) keybinds in your application.

Fn and FnLock

Fn and FnLock key events are exceedingly unlikely to be emitted by Winit. These keys are usually handled at the hardware or OS level, and aren’t surfaced to applications. If you somehow see this in the wild, we’d like to know :)

§logical_key: Key

This value is affected by all modifiers except Ctrl.

This has two use cases:

  • Allows querying whether the current input is a Dead key.
  • Allows handling key-bindings on platforms which don’t support key_without_modifiers.

If you use this field (or key_without_modifiers for that matter) for keyboard shortcuts, it is important that you provide users with a way to configure your application’s shortcuts so you don’t render your application unusable for users with an incompatible keyboard layout.

Platform-specific

  • Web: Dead keys might be reported as the real key instead of Dead depending on the browser/OS.
§text: Option<SmolStr>

Contains the text produced by this keypress.

In most cases this is identical to the content of the Character variant of logical_key. However, on Windows when a dead key was pressed earlier but cannot be combined with the character from this keypress, the produced text will consist of two characters: the dead-key-character followed by the character resulting from this keypress.

An additional difference from logical_key is that this field stores the text representation of any key that has such a representation. For example when logical_key is Key::Named(NamedKey::Enter), this field is Some("\r").

This is None if the current keypress cannot be interpreted as text.

See also: text_with_all_modifiers()

§location: KeyLocation

Contains the location of this key on the keyboard.

Certain keys on the keyboard may appear in more than once place. For example, the “Shift” key appears on the left side of the QWERTY keyboard as well as the right side. However, both keys have the same symbolic value. Another example of this phenomenon is the “1” key, which appears both above the “Q” key and as the “Keypad 1” key.

This field allows the user to differentiate between keys like this that have the same symbolic value but different locations on the keyboard.

See the KeyLocation type for more details.

§state: ElementState

Whether the key is being pressed or released.

See the ElementState type for more details.

§repeat: bool

Whether or not this key is a key repeat event.

On some systems, holding down a key for some period of time causes that key to be repeated as though it were being pressed and released repeatedly. This field is true if and only if this event is the result of one of those repeats.

Trait Implementations§

source§

impl Clone for KeyEvent

source§

fn clone(&self) -> KeyEvent

Returns a copy of the value. Read more
1.0.0 · 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 Hash for KeyEvent

source§

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher. Read more
1.3.0 · source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
source§

impl KeyEventExtModifierSupplement for KeyEvent

source§

fn text_with_all_modifiers(&self) -> Option<&str>

Identical to KeyEvent::text but this is affected by Ctrl. Read more
source§

fn key_without_modifiers(&self) -> Key

This value ignores all modifiers including, but not limited to Shift, Caps Lock, and Ctrl. In most cases this means that the unicode character in the resulting string is lowercase. Read more
source§

impl PartialEq for KeyEvent

source§

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

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl Eq for KeyEvent

source§

impl StructuralEq for KeyEvent

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> Downcast for T
where T: Any,

source§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
source§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
source§

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

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
source§

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

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
source§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

source§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
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,

§

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

§

type Error = Infallible

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

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

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

§

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

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more