Struct KeyEvent

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 */
}

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.

Example

In games, you often want to ignore repated key events - this can be done by ignoring events where this property is set.

use winit::event::{ElementState, KeyEvent, WindowEvent};
use winit::keyboard::{KeyCode, PhysicalKey};
match window_event {
    WindowEvent::KeyboardInput {
        event:
            KeyEvent {
                physical_key: PhysicalKey::Code(KeyCode::KeyW),
                state: ElementState::Pressed,
                repeat: false,
                ..
            },
        ..
    } => {
        // The physical key `W` was pressed, and it was not a repeat
    },
    _ => {}, // Handle other events
}

Trait Implementations

impl Clone for KeyEvent

fn clone(&self) -> KeyEvent

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for KeyEvent

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

Formats the value using the given formatter.

impl Hash for KeyEvent

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

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl KeyEventExtModifierSupplement for KeyEvent

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

Identical to KeyEvent::text but this is affected by Ctrl.

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.

impl PartialEq for KeyEvent

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for KeyEvent

impl StructuralPartialEq for KeyEvent