Skip to content

feat: add KeyboardKey enum for keyboard event keys - #7123

Open
ndonkoHenri wants to merge 3 commits into
flet-1.2from
feat/keyboard-key-enum
Open

ndonkoHenri wants to merge 3 commits into
flet-1.2from
feat/keyboard-key-enum

Conversation

@ndonkoHenri

@ndonkoHenri ndonkoHenri commented Nov 22, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Keyboard handlers compare e.key with hand-typed labels:

if e.key == "Arrow Right": ...
if e.key in (" ", "Enter"): ...

The labels aren't discoverable, and a typo such as "ArrowRight" or "Space" silently never matches.

Change

ft.KeyboardKey names every key the client can report:

if e.key == ft.KeyboardKey.ARROW_RIGHT: ...
if e.key in (ft.KeyboardKey.SPACE, ft.KeyboardKey.ENTER): ...
  • One member per Flutter LogicalKeyboardKey (444), valued with the key's keyLabel, the string the client already sends. No Dart or protocol change.
  • Backward compatible: KeyboardKey(str, Enum) members are strings, so e.key == "Arrow Right" keeps working, and __str__ returns the label, so f"Key: {e.key}" still shows Arrow Right.
  • Event fields: key on KeyboardEvent, KeyDownEvent, KeyUpEvent and KeyRepeatEvent is Union[KeyboardKey, str]: a member for known keys, a plain string for keys without one (e.g. "Ü" on a German layout).
  • from_dict: a Union that includes an enum decodes to the member when one has the value, else keeps the value. Optional unions of several types keep all of them (previously only the first), and X | Y unions are handled like Union[X, Y] (on 3.10–3.13 they have a different origin and were skipped).
  • Generated, like icons: .github/scripts/generate_keyboard_keys.py renders keyboard_key.py from Flutter's keyboard_key.g.dart at the .fvmrc version through a Jinja template. CI runs it with --verify in the icons step.
  • Docs: KeyboardKey type page, a key-comparison example on the keyboard shortcuts cookbook page, and examples switched to the enum.

Testing

  • Unit suite passes; generate_keyboard_keys.py --verify reports up to date; ruff clean.
  • from_dict union handling checked on Python 3.10, 3.12 and 3.14 with Union[M, str], M | str, M | str | None, Optional[M] and dataclass/list unions.
  • Not run in a live app; events go through the same from_dict decoding that was checked.

Summary by Sourcery

Add a string-compatible KeyboardKey enum and integrate it across keyboard events, deserialization, examples, documentation, and generated-file validation.

New Features:

  • Add the public KeyboardKey enum covering Flutter keyboard event labels, with string-compatible members for backward-compatible key comparisons.
  • Decode known keyboard event keys as enum members while preserving unknown layout-specific keys as strings.

Bug Fixes:

  • Improve union deserialization for optional and pipe-style type annotations, including preservation of multiple optional union types.

Enhancements:

  • Update keyboard event types and examples to use discoverable KeyboardKey values while retaining existing string behavior.
  • Generate keyboard key definitions from the pinned Flutter SDK and verify generated output in CI.

CI:

  • Verify generated keyboard key definitions are up to date in the CI generation checks.

Documentation:

  • Document KeyboardKey and add keyboard shortcut examples using enum members.

Keyboard handlers compared `e.key` with hand-typed labels such as
"Arrow Right" or " ", where a typo fails silently. `ft.KeyboardKey` names
every key Flutter reports, so handlers can write
`e.key == ft.KeyboardKey.ARROW_RIGHT`.

What changes:
- `KeyboardKey(str, Enum)` has one member per Flutter `LogicalKeyboardKey`
  (444), valued with the key's `keyLabel`, the string the client sends.
  Members are strings, so comparisons with plain labels keep working, and
  `__str__` returns the label, so f-strings show "Arrow Right".
- `key` on `KeyboardEvent`, `KeyDownEvent`, `KeyUpEvent` and
  `KeyRepeatEvent` is `Union[KeyboardKey, str]`: a member for known keys,
  a plain string for keys without one (e.g. letters of non-English layouts).
- `from_dict` decodes a `Union` that includes an enum into the member when
  one has the value, else keeps the value; `Optional` unions of several
  types now keep all of them instead of only the first.
- `.github/scripts/generate_keyboard_keys.py` renders `keyboard_key.py`
  from Flutter's `keyboard_key.g.dart` at the `.fvmrc` version through a
  Jinja template; CI runs it with `--verify` in the icons step.
- Docs: `KeyboardKey` type page and sidebar entry, cookbook example on the
  keyboard shortcuts page; examples use the enum; 1.2.0 changelog entry.

Tested: unit suite passes; generator --verify reports up to date; ruff clean.
`convert_value` recognized only `typing.Union`, so a field annotated with
PEP 604 syntax, such as `KeyboardKey | str` or `Padding | None`, was not
treated as a union on Python 3.10-3.13, where `X | Y` has the origin
`types.UnionType`: `None` handling and enum conversion were skipped and the
raw value was returned.

Both origins are now treated as a union: `X | None` keeps `None` and
converts the rest like `Optional[X]`, and `SomeEnum | T` gives the enum
member when one has the value, else the value, like `Union[SomeEnum, T]`.

Tested: `Union[M, str]`, `M | str`, `M | str | None`, `Optional[M]` and
dataclass/list unions convert the same on Python 3.10, 3.12 and 3.14;
unit suite passes; ruff clean.
Adds the PR link to the 1.2.0 KeyboardKey entry.
@ndonkoHenri ndonkoHenri added this to the 1.2.0 milestone Nov 22, 2026

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've reviewed your changes and they look great!


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 22, 2026 •

Copy link
Copy Markdown

Deploying flet-website-v2 with  Cloudflare Pages  Cloudflare Pages

Latest commit: cf68bd2
Status: ✅  Deploy successful!
Preview URL: https://df250376.flet-website-v2.pages.dev
Branch Preview URL: https://feat-keyboard-key-enum.flet-website-v2.pages.dev

View logs

This branch has not been deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant