HardwareKeyboard class

Manages key events from hardware keyboards.

HardwareKeyboard manages all key events of the Flutter 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 addHandler. To only be notified when a specific part of the app is focused, use a Focus widget's onFocusChanged attribute instead of addHandler. Handlers should be removed with removeHandler 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 physicalKeysPressed, logicalKeysPressed, or lockModesEnabled. These states will have been updated with the event when used during a key event handler.

The singleton HardwareKeyboard instance is held by the ServicesBinding as ServicesBinding.keyboard, and can be conveniently accessed using the HardwareKeyboard.instance static accessor.

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")
  • KeyRepeatEvent(physicalKey: keyA, logicalKey: keyA, character: "A")
  • KeyUpEvent(physicalKey: keyA, logicalKey: keyA)
  • KeyUpEvent(physicalKey: shiftLeft, logicalKey: shiftLeft)
• Tap key Q, French layout:
  • KeyDownEvent(physicalKey: keyA, logicalKey: keyQ, character: "q")
  • KeyUpEvent(physicalKey: keyA, logicalKey: keyQ)
• Tap CapsLock:
  • KeyDownEvent(physicalKey: capsLock, logicalKey: capsLock)
  • KeyUpEvent(physicalKey: capsLock, logicalKey: capsLock)

When the Flutter 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. For example, if CapsLock is enabled when the application starts, then immediately before the first key event, a synthesized KeyDownEvent and KeyUpEvent of CapsLock will be dispatched.

The resulting event stream does not map one-to-one to the native key event stream. Some native events might be skipped, while some events might be synthesized and do not correspond to native events. Synthesized events will be indicated by KeyEvent.synthesized.

Example:

• Flutter starts with CapsLock on, the first press of keyA:
  • KeyDownEvent(physicalKey: capsLock, logicalKey: capsLock, synthesized: true)
  • KeyUpEvent(physicalKey: capsLock, logicalKey: capsLock, synthesized: true)
  • KeyDownEvent(physicalKey: keyA, logicalKey: keyA, character: "a")
• While holding ShiftLeft, lose window focus, release shiftLeft, then focus back and press keyA:
  • KeyUpEvent(physicalKey: shiftLeft, logicalKey: shiftLeft, synthesized: true)
  • KeyDownEvent(physicalKey: keyA, logicalKey: keyA, character: "a")

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.

See also:

• KeyDownEvent, KeyRepeatEvent, and KeyUpEvent, the classes used to describe specific key events.
• instance, the singleton instance of this class.