Struct HardwareKeyboard 

pub struct HardwareKeyboard { /* private fields */ }

Manages key events from hardware keyboards.

HardwareKeyboard manages all key events of the application from hardware keyboards (in contrast to on-screen keyboards). It receives key data from the native platform, dispatches key events to registered handlers, and records the keyboard state.

To stay notified whenever keys are pressed, held, or released, add a handler with add_handler. Handlers should be removed with remove_handler when notification is no longer necessary, or when the handler is being disposed.

To query whether a key is being held, or a lock mode is enabled, use physical_keys_pressed, logical_keys_pressed, or lock_modes_enabled. These states will have been updated with the event when used during a key event handler.

Event model

Flutter uses a universal event model (KeyEvent) and key options (LogicalKeyboardKey and PhysicalKeyboardKey) regardless of the native platform, while preserving platform-specific features as much as possible.

HardwareKeyboard guarantees that the key model is “regularized”: The key event stream consists of “key tap sequences”, where a key tap sequence is defined as one KeyDownEvent, zero or more KeyRepeatEvents, and one KeyUpEvent in order, all with the same physical key and logical key.

Example:

• Tap and hold key A, US layout:
  • KeyDownEvent(physicalKey: keyA, logicalKey: keyA, character: "a")
  • KeyRepeatEvent(physicalKey: keyA, logicalKey: keyA, character: "a")
  • KeyUpEvent(physicalKey: keyA, logicalKey: keyA)
• Press ShiftLeft, tap key A, then release ShiftLeft, US layout:
  • KeyDownEvent(physicalKey: shiftLeft, logicalKey: shiftLeft)
  • KeyDownEvent(physicalKey: keyA, logicalKey: keyA, character: "A")
  • KeyUpEvent(physicalKey: keyA, logicalKey: keyA)
  • KeyUpEvent(physicalKey: shiftLeft, logicalKey: shiftLeft)

When the application starts, all keys are released, and all lock modes are disabled. Upon key events, HardwareKeyboard will update its states, then dispatch callbacks: KeyDownEvents and KeyUpEvents set or reset the pressing state, while KeyDownEvents also toggle lock modes.

Flutter will try to synchronize with the ground truth of keyboard states using synthesized events (KeyEvent::synthesized), subject to the availability of the platform. The desynchronization can be caused by non-empty initial state or a change in the focused window or application.

Flutter does not distinguish between multiple keyboards. Flutter will process all events as if they come from a single keyboard, and try to resolve any conflicts and provide a regularized key event stream, which can deviate from the ground truth.

Dart’s HardwareKeyboard.instance is instance, the App’s singleton.

Implementations

impl HardwareKeyboard

pub fn instance(app: &mut App) -> Handle<HardwareKeyboard>

The current HardwareKeyboard, if one has been created.

Dart’s HardwareKeyboard.instance.

pub fn physical_keys_pressed( self: Handle<Self>, app: &App, ) -> HashSet<PhysicalKeyboardKey>

The set of PhysicalKeyboardKeys that are pressed.

If called from a key event handler, the result will already include the effect of the event.

See also:

• logical_keys_pressed, which tells if a logical key is being pressed.

pub fn logical_keys_pressed( self: Handle<Self>, app: &App, ) -> HashSet<LogicalKeyboardKey>

The set of LogicalKeyboardKeys that are pressed.

If called from a key event handler, the result will already include the effect of the event.

See also:

• physical_keys_pressed, which tells if a physical key is being pressed.

pub fn look_up_layout( self: Handle<Self>, app: &App, physical_key: PhysicalKeyboardKey, ) -> Option<LogicalKeyboardKey>

Returns the logical key that corresponds to the given pressed physical key.

Returns None if the physical key is not currently pressed.

pub fn lock_modes_enabled( self: Handle<Self>, app: &App, ) -> HashSet<KeyboardLockMode>

The set of KeyboardLockMode that are enabled.

Lock keys, such as CapsLock, are logical keys that toggle their respective boolean states on key down events. Such flags are usually used as modifier to other keys or events.

If called from a key event handler, the result will already include the effect of the event.

pub fn is_logical_key_pressed( self: Handle<Self>, app: &App, key: LogicalKeyboardKey, ) -> bool

Returns true if the given LogicalKeyboardKey is pressed, according to the HardwareKeyboard.

pub fn is_physical_key_pressed( self: Handle<Self>, app: &App, key: PhysicalKeyboardKey, ) -> bool

Returns true if the given PhysicalKeyboardKey is pressed, according to the HardwareKeyboard.

pub fn is_control_pressed(self: Handle<Self>, app: &App) -> bool

Returns true if a logical CTRL modifier key is pressed, regardless of which side of the keyboard it is on.

Use is_logical_key_pressed if you need to know which control key was pressed.

pub fn is_shift_pressed(self: Handle<Self>, app: &App) -> bool

Returns true if a logical SHIFT modifier key is pressed, regardless of which side of the keyboard it is on.

Use is_logical_key_pressed if you need to know which shift key was pressed.

pub fn is_alt_pressed(self: Handle<Self>, app: &App) -> bool

Returns true if a logical ALT modifier key is pressed, regardless of which side of the keyboard it is on.

The AltGr key that appears on some keyboards is considered to be the same as LogicalKeyboardKey::ALT_RIGHT on some platforms (notably Android). On platforms that can distinguish between altRight and altGr, a press of AltGr will not return true here, and will need to be tested for separately.

Use is_logical_key_pressed if you need to know which alt key was pressed.

pub fn is_meta_pressed(self: Handle<Self>, app: &App) -> bool

Returns true if a logical META modifier key is pressed, regardless of which side of the keyboard it is on.

Use is_logical_key_pressed if you need to know which meta key was pressed.

pub fn add_handler(self: Handle<Self>, app: &mut App, handler: KeyEventCallback)

Register a listener that is called every time a hardware key event occurs.

All registered handlers will be invoked in order regardless of their return value. The return value indicates whether Flutter “handles” the event. If any handler returns true, the event will not be propagated to other native components in the add-to-app scenario.

If an object added a handler, it must remove the handler before it is disposed.

If used during event dispatching, the addition will not take effect until after the dispatching.

See also:

• remove_handler, which removes the handler.

pub fn remove_handler( self: Handle<Self>, app: &mut App, handler: &KeyEventCallback, )

Stop calling the given listener every time a hardware key event occurs.

The handler argument must be a clone of the one used in add_handler. If multiple exist, the first one will be removed. If none is found, then this method is a no-op.

If used during event dispatching, the removal will not take effect until after the event has been dispatched.

pub fn sync_keyboard_state( self: Handle<Self>, app: &mut App, keyboard_state: &HashMap<u64, u64>, )

Update the pressed keys to the state the host reports.

Both the framework and the host maintain a state of the current pressed keys. There are edge cases, related to startup and restart, where the framework needs to resynchronize its keyboard state. keyboard_state maps a USB HID usage to the logical key id pressed on it.

pub fn handle_key_event( self: Handle<Self>, app: &mut App, event: &KeyEvent, ) -> bool

Process a new KeyEvent by recording the state changes and dispatching to handlers.

Returns true if any handler handled the event.

pub fn clear_state(self: Handle<Self>, app: &mut App)

Clear all keyboard states and additional handlers.

This is used by the testing framework to make sure that tests are hermetic.

Trait Implementations

impl Default for HardwareKeyboard

fn default() -> Self

Returns the “default value” for a type.