Repository navigation
Description
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.attachonKeyargument. -
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 -
_HighlightModeManager - 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
HardwareKeyboardto make migration easierbool isKeyPressed(LogicalKeyboardKey key)bool get isControlPressedbool get isShiftPressedbool get isAltPressedbool 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
RawKeyEventevents.
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
RawKeyEventtoKeyEventtransition 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.
Activity
gspencergoog commentedon Oct 13, 2023
For the migration away from
RawKeyEvent, we need to makeShortcutActivator.acceptshandleKeyEventevents. The options appear to be:add a new
acceptsKeyEventmethod that takes aKeyEvent, and make people override it (it will break all subclasses when it is added), orcreate a sealed base class that only
RawKeyEventandKeyEventderive from (GenericKeyEventperhaps) and make theShortcutActivator.acceptsmethod take acovariant GenericKeyEvent, and then provide two implementations conditional on which type was given. Later, bothRawKeyEventandGenericKeyEventwould be removed.The up side of the first method is that I don't need to relate the two key event classes, but the down side is a huge breaking change up front when the new method is added.
The up side of the second way is that we don't need to rename the method, and we don't break people's subclasses, but the down side is that we'll break all the subclasses anyhow when we remove
GenericKeyEvent, or at runtime when we switch to sending onlyKeyEvents.We could just leave
GenericKeyEventin place after removing the deprecatedRawKeyEvent, but it would have no members, and only one subclass (KeyEvent), so it's really pretty useless. We could start its deprecation period when we removeRawKeyEvent, I guess, and then remove it two years from now...The other part of the problem is when to switch over from sending
RawKeyEventinstances toShortcutActivator.acceptsto sendingKeyEventinstances. If I go with the sealed base class path, then it will just break a lot of code at runtime, and static failures are preferable to runtime failures, of course.Here's what I might try:
Introduce the sealed base class (
GenericKeyEvent) and updateShortcutActivator.accepts:GenericKeyEvent(which will mean moving implementation of RawKeyEvent in the framework into the same file asKeyEvent, but it'll be deprecated and removed eventually).ShortcutActivator.acceptsmethod to accept acovariant GenericKeyEvent.ShortcutActivator.acceptsforRawKeyEvent.ShortcutActivator.acceptsthat handlesKeyEventobjects.Deprecate
RawKeyEvent:RawKeyEventclass as deprecated.RawKeyEventtoKeyEvent.Transition to
KeyEvent:ShortcutActivator.acceptsto use KeyEvent instead ofRawKeyEvent.RawKeyEventinShortcutActivator.acceptsfor a deprecation period.Remove
RawKeyEvent:RawKeyEventclass.RawKeyEvent-specific implementation fromShortcutActivator.accepts.Change some usage of RawKeyEvent to KeyEvent in preparation for depre…
gspencergoog commentedon Oct 16, 2023
After talking with Michael, it seems like method 1, above might be the best way to go. Yes, it causes a breaking change for people who subclass
ShortcutActivatordirectly, but most people don't do that.I'm going to give that a try.
rydmike commentedon Oct 17, 2023
Looks like this change will require a lot of rework in several repos. Been using things like
RawKeyboardListenerand e.g.RawKeyEventDataMacOs,RawKeyEventDataIos, since that was pretty much the only way to get what was needed done, when it was written many years ago.I've seen there are some newer ways, but no real idea what they are. Yes these old APIs are fairly low level, but once setup they worked very well, so there was no need to fix them or look into the newer APIs, since they were not broken.
I hope good and very in-depth guides on how to replace all the deprecated APIs above will be provided. At least I have no clue where to even begin to look for replacements.
33 remaining items
konrad321 commentedon May 23, 2024
I just noticed that HardwareKeyboard.instance.isShiftPressed doesn't work on Android, whereas the RawKeyEvent event.isShiftPressed did work. This applies both to hardware and virtual keyboards. Is this the intended behaviour to drop support for isShiftPressed on Android or should a file a bug for this? I used it to distinguish Enter and Shift+Enter for some cases.
gspencergoog commentedon May 23, 2024
@konrad321 No, that's not intended behavior, although it is intended that it doesn't work with virtual keyboards (because they don't generally generate events on Android). I don't think that ever worked for virtual keyboards. Could you please file a separate issue for that with details?
konrad321 commentedon May 24, 2024
@gspencergoog I tested the behaviour again with the Android Emulator and you're right, it didn't worked there even with the old event system. Neither with a hardware keyboard, nor with the virtual keyboard. It seems I have a very special Android device here, that triggers the shift key as an event. Since this behaviour seems to be device specific and uncommon, I won't file a bug report.
flutter-triage-bot commentedon Jun 7, 2024
The
triaged-desktoplabel is irrelevant if there is noteam-desktoplabel orfyi-desktoplabel.rydmike commentedon Jan 28, 2025
@gspencergoog I noticed the planned removal scheduled of the deprecated
RawKeyboardListenerand related APIs was already in Q4 2024. We discovered a severe blocking issue for migrating to the new APIs last weekend and I submitted this report today #162305.For game dev the issue is like @spydon also commented quite severe. We actually had to revert our already migrated usage to the old API, to make our game platform usable on web builds.
We kindly ask if you can hold off the removal of the deprecated
RawKeyboardListenerand its related APIs, until this issue is resolved and its fix has landed in the Flutter stable channel. Either via next stable release or as a CP:d hot-fix.konrad321 commentedon Jan 29, 2025
There is also a macOS issue with the new
HardwareKeyboardwhich I reported in #148936 many months ago. I'm also stuck with the oldRawKeyboardListeneruntil it is resolved.Convert some usage of `RawKeyEvent`, et al to `KeyEvent` (#139329)
Deprecate `RawKeyEvent`, `RawKeyboard`, et al. (#136677)
Add `KeyEventDeviceType` to `KeyData` (flutter-team-archive/engine#47315