Skip to content

RawKeyEvent and RawKeyboard, et al should be deprecated and removed #136419

Open

Description

@gspencergoog

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
  • _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 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:

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

  1. self-assigned this
    on Oct 11, 2023
  2. added
    c: tech-debtTechnical debt, code quality, testing, etc.
    a: text inputEntering text in a text field or keyboard related problems
    P2Important issues not at the top of the work list
    fyi-frameworkFor the attention of Framework team
    on Oct 11, 2023
  3. gspencergoog commented on Oct 13, 2023

    @gspencergoog
    ContributorAuthor

    For the migration away from RawKeyEvent, we need to make ShortcutActivator.accepts handle KeyEvent events. The options appear to be:

    1. add a new acceptsKeyEvent method that takes a KeyEvent, and make people override it (it will break all subclasses when it is added), or

    2. create a sealed base class that only RawKeyEvent and KeyEvent derive from (GenericKeyEvent perhaps) and make the ShortcutActivator.accepts method take a covariant GenericKeyEvent, and then provide two implementations conditional on which type was given. Later, both RawKeyEvent and GenericKeyEvent would 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 only KeyEvents.

    We could just leave GenericKeyEvent in place after removing the deprecated RawKeyEvent, 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 remove RawKeyEvent, I guess, and then remove it two years from now...

    The other part of the problem is when to switch over from sending RawKeyEvent instances to ShortcutActivator.accepts to sending KeyEvent instances. 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:

    1. Introduce the sealed base class (GenericKeyEvent) and update ShortcutActivator.accepts:

      • Introduce the sealed base class GenericKeyEvent (which will mean moving implementation of RawKeyEvent in the framework into the same file as KeyEvent, but it'll be deprecated and removed eventually).
      • Update the ShortcutActivator.accepts method to accept a covariant GenericKeyEvent.
      • Maintain the existing implementation of ShortcutActivator.accepts for RawKeyEvent.
      • Add a new implementation for ShortcutActivator.accepts that handles KeyEvent objects.
    2. Deprecate RawKeyEvent:

      • Mark the RawKeyEvent class as deprecated.
      • Provide a migration guide for developers to switch from RawKeyEvent to KeyEvent.
    3. Transition to KeyEvent:

      • Update the code that sends key events to ShortcutActivator.accepts to use KeyEvent instead of RawKeyEvent.
      • Maintain the existing implementation for RawKeyEvent in ShortcutActivator.accepts for a deprecation period.
    4. Remove RawKeyEvent:

      • After the deprecation period, remove the RawKeyEvent class.
      • Remove the RawKeyEvent-specific implementation from ShortcutActivator.accepts.
  4. gspencergoog commented on Oct 16, 2023

    @gspencergoog
    ContributorAuthor

    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 ShortcutActivator directly, but most people don't do that.

    I'm going to give that a try.

  5. rydmike commented on Oct 17, 2023

    @rydmike
    Contributor

    Looks like this change will require a lot of rework in several repos. Been using things like RawKeyboardListener and 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.

  6. 33 remaining items

  7. konrad321 commented on May 23, 2024

    @konrad321

    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.

  8. gspencergoog commented on May 23, 2024

    @gspencergoog
    ContributorAuthor

    @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?

  9. konrad321 commented on May 24, 2024

    @konrad321

    @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.

  10. flutter-triage-bot commented on Jun 7, 2024

    @flutter-triage-bot

    The triaged-desktop label is irrelevant if there is no team-desktop label or fyi-desktop label.

  11. rydmike commented on Jan 28, 2025

    @rydmike
    Contributor

    @gspencergoog I noticed the planned removal scheduled of the deprecated RawKeyboardListener and 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 RawKeyboardListener and 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.

  12. konrad321 commented on Jan 29, 2025

    @konrad321

    There is also a macOS issue with the new HardwareKeyboard which I reported in #148936 many months ago. I'm also stuck with the old RawKeyboardListener until it is resolved.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

P2Important issues not at the top of the work lista: desktopRunning on desktopa: text inputEntering text in a text field or keyboard related problemsc: tech-debtTechnical debt, code quality, testing, etc.team-text-inputOwned by Text Input team

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions