Description

Several years ago, we embarked on a project to improve the keyboard key handling for Flutter. The new system has been in production use for a while now (at least a couple of years).

However, the legacy interfaces are still present, and on the framework side, this makes for a confusing story for our users, and complicates the code. On the engine side, we are still producing and handling both kinds of keyboard events, which complicates the code and is less efficient.

This document describes the steps that need to be taken in order to complete the deprecation and removal of the old “Raw” APIs and code.

The migration guide for this work has been published.

Affected APIs

The APIs that need to be deprecated and eventually removed are:

• RawKeyboard
• RawKeyEvent
• RawKeyDownEvent
• RawKeyUpEvent
• RawKeyEventData
• RawKeyEventDataAndroid
• RawKeyEventDataLinux
• RawKeyEventDataIos
• RawKeyEventDataMacOs
• RawKeyEventDataWindows
• RawKeyEventDataFuchsia
• RawKeyEventDataWeb
• RawKeyEventHandler
• FocusOnKeyCallback
• RawKeyboardListener
• KeyEventManager.handleRawKeyMessage
• KeyboardSide
• ModifierKey
• KeyDataTransitMode
• KeySimulatorTransitModeVariant
• Focus.onKey
• FocusScope.onKey
• FocusNode.onKey
• FocusNode.attach onKey argument.
• FocusScopeNode.onKey
• debugKeyEventSimulatorTransitModeOverride

Things that still need to be migrated to use only KeyEvent instead of RawKeyEvent (in some cases these currently work with both, and will eventually only need to work with KeyEvent):

• ShortcutActivator.accepts
• ShortcutActivator.isActivatedBy
• ShortcutManager.handleKeypress
• simulateKeyDownEvent
• simulateKeyUpEvent
• KeyEventSimulator
• Many tests

Functionality that existed in RawKeyEvent that no longer exists after switch to KeyEvent:

• Convenience functions for determining if a key is pressed need to be implemented on HardwareKeyboard to make migration easier
  • bool isKeyPressed(LogicalKeyboardKey key)
  • bool get isControlPressed
  • bool get isShiftPressed
  • bool get isAltPressed
  • bool get isMetaPressed

Things that need to be removed eventually:

• All related private APIs
• Key code generation that refers to RawKeyEvent
• Engine side code that generates RawKeyEvent events.

Documentation that needs updating:

• Documentation references to all deprecated APIs in API docs.
• Documentation references to all deprecated APIs in website docs.
• Migration guide for the deprecated APIs. (Add migration guide for RawKeyEvent to KeyEvent transition website#9889)

Deprecation Timeline

Q4 2023: Deprecate all the API listed above as deprecated.
Q4 2024: Remove RawKeyboard and RawKeyEvent, et al. from the Flutter Framework.
Q4 2024: Remove related code from the Flutter Engine.