Rebase Physical Keys Shortcuts by LeonMatthes · Pull Request #12570 · slint-ui/slint

LeonMatthes · 2026-07-21T15:44:53Z

This PR rebases #11474 by @amirHdev on to the current master.

It also closes the backend gap so that now all backends support physical key bindings 🥳

Signed-off-by: Amirhossein Akhlaghpour <m9.akhlaghpoor@gmail.com>

Native menu bars interpret shortcuts as logical keys. Emit a compiler warning for @physical-keys() in MenuItem shortcuts, log a one-time runtime warning in the winit+muda backend, and map supported physical codes to a best-effort logical key. Add parser/resolver syntax tests for invalid @physical-keys(), and update the physical-keys runtime test to reuse testing backend helpers.

Replace WindowEvent::Key { event_type, event } with WindowEvent::Key(WindowKeyEvent) where WindowKeyEvent bundles the existing KeyEvent struct plus the event type. This keeps the public key event payload consistent with the rest of the runtime and avoids duplicating fields. Signed-off-by: Amirhossein Akhlaghpour <m9.akhlaghpoor@gmail.com>

After the rebase, some imports were unresolved and some API shapes had changed, which needed adjustment.

Also improve physical_key_codes documentation

tronical · 2026-07-22T09:24:13Z

+}
+```
+
+Physical key names reuse familiar `Key` names such as `A`, `Digit1`, `BackQuote`, or `LeftArrow`, but they refer to a physical key location instead of logical text. Today these names refer to positions on a U.S. keyboard layout.


Is that really just today and a contract that we might break in the future, or will it remain that way?

Generally, I think the use-case and the explanation what the mapping is should come first in the docs, before explaining the syntax. (see style guide, "Write actionable" and "Offer direct advice")

The keys we're adding now will remain to be based on the position of a U.S. keyboard layout.
However, if we ever add keys that just don't exist on a U.S. layout, those of course won't refer to U.S. layout positions.
Or if we ever add things like "PowerButton"/"VolumeUp/Down" and so on. Those aren't really on the U.S. keyboard.
So this is a bit defensively phrased. Should I still remove it?

(Moved the paragraph above the code example).

As an additional note on docs/discoverability here: The PR currently does not introduce a PhysicalKey namespace and Rust enum, like we have for Key.
I think this would be valuable to have as well, but we can/should do that as a follow-up PR so that this PR doesn't become stale again.
(#12212 also depends on this PR and would then be unblocked).

For some reason the doc-tests picked up this comment as a doc test: //! Slint # Winit # Xkb # Win # Mac Fixed by removing the indentation 🤷

tronical

Looks generally good. I feel we're discussing details ;)

tronical · 2026-07-23T08:56:14Z


+### Physical Key Bindings
+
+If you want to match a physical key position instead of the character produced on the current keyboard layout, use `@physical-keys(..)`.


Suggest to flip it around: "Use @physical-keys(..) to match ..." . Also saves you the "want" :)

Could you include an example (use-case, not code) as well, perhaps? (games?)

Done (Added WASD as example)

tronical · 2026-07-23T09:00:08Z

+If you want to match a physical key position instead of the character produced on the current keyboard layout, use `@physical-keys(..)`.
+
+Physical key names reuse familiar `Key` names such as `A`, `Digit1`, `BackQuote`, or `LeftArrow`, but they refer to a physical key location instead of logical text.
+Today these names refer to positions on a U.S. keyboard layout.


After yesterday's discussion I feel even more that "Today" should be omitted.

Okay, and reworded it to make it shorter.

tronical · 2026-07-23T09:03:29Z

+                /// This uses the same names as `@physical-keys(...)`, for example `A`,
+                /// `Digit1`, or `LeftArrow`. It is empty when the backend doesn't provide
+                /// physical key information.
+                physical_key: SharedString,


A question, just for my understanding: The name suggests that it's a single key, but the field is a string. Would you use a char in a perfect world?

For performance we could just use an int. This is just an identifier for a physical key, we should not even be thinking in terms of "characters" here really.

The reason this is a string is so that you can easily name your own keys. Like if you have your own embedded device which has a physical key to "start the reactor", you could just have a "StartReactor" key.
At the moment, this is not supported yet, but that is a limitation we should lift in the future so backends can implement their own custom physical keys.

This is somewhat nicer to do with a string than some kind of integer, but an integer would definitely be more performant. So maybe we should talk about this again during API review.
Also, it matches what the Keys type already stores, so we don't have to make that a tagged union.

tronical · 2026-07-23T09:05:41Z

 }

 #[inline(never)]
-fn compile_keys_literal(expr: &Expression) -> TokenStream {


This looks like an unnecessary re-indentation? :)

The indentation didn't change, the type of the function argument changed ;)

(The previous function was weirdly unpacking the expression enum for no reason).

tronical · 2026-07-23T09:07:56Z

+                    && let Some(binding) = element.borrow().bindings.get("shortcut")
+                    && matches!(&binding.borrow().expression, Expression::Keys(k) if k.is_physical)
+                {
+                    diag.push_warning(


Wouldn't it be better to make this an error?

Hm, yes, probably better to make it an error, we can always relax it later.

In theory they do actually work in menus due to our fallback logic, but we cannot show them in the MenuItem correctly (they show up as and will match like logical keys and will also match the physical key).

This error also doesn't prevent you from sneaking a physical key onto a MenuItem shortcut through a property binding. So it's not a perfect defense.

tronical · 2026-07-23T09:09:52Z

+        };
+    }
+
+    thread_local! {


Instead of "duplicating" this in each thread, wouldn't it be better to put this behind a LazyLock?

Hm, our compiler currently only runs in one thread, but sure, we can make that a lazylock for when olivier finishes the LLR interpreter :)

tronical · 2026-07-23T09:12:19Z

    /// Always reported as [`Accepted`](crate::api::WindowEventDispatchResult::Accepted).
    PointerExited,
+    /// A key was pressed or released.
+    Key(WindowKeyEvent),


I suggest to split out making the new key event public into a separate PR. Reduces the surface of this and makes it easier to discuss/review just the API. I don't think it's needed strictly for this functionality, right?

Ah, I just ported the backends to use this 🙈
They would all have to use InternalKeyEvent then for physical keys support.

Can we just decide during API review whether we want it public or not and add a PR to make it private again if needed?

tronical · 2026-07-23T09:16:17Z

+    static WARN_ONCE: std::sync::Once = std::sync::Once::new();
+    WARN_ONCE.call_once(|| {
+        i_slint_core::debug_log!(
+            "Warning: Physical keys used in menu shortcuts are interpreted as logical keys based on a US keyboard layout. Use @keys(...) for menu shortcuts."


Isn't this caught at compile time? (especially if it were an error)

You could still set this via a property from Rust, so this is a last layer of defense.

tronical · 2026-07-23T09:23:00Z


 As another example, `@keys(Control + Plus)` is equivalent to `@keys(Control + Shift? + "+")`.

+### Physical Key Bindings


Perhaps here it would also be worthwhile to mention the menu limitation? (or is that overdoing it?)

Added that onto the docs of the MenuItem.shortcut property now. I think it's unnecessary here, but definitely makes sense there.

amirHdev and others added 13 commits July 22, 2026 10:07

input: add @physical-keys for physical shortcuts

8d0f5ab

Signed-off-by: Amirhossein Akhlaghpour <m9.akhlaghpoor@gmail.com>

platform: avoid key event type name collisions

ff56fbc

Signed-off-by: Amirhossein Akhlaghpour <m9.akhlaghpoor@gmail.com>

[autofix.ci] apply automated fixes

3b62989

input: address physical key shortcut review feedback

cbd3def

input: adapt physical keys to current runtime

c19cbf5

ci: allow Backquote key spelling

367a9ba

input: mark parsed shortcut tests as logical keys

2d76209

lsp: complete physical key modifiers

5aab4cc

Fix conflicts after rebasing onto 20f2e2a

29733f5

After the rebase, some imports were unresolved and some API shapes had changed, which needed adjustment.

Add Changelog entry

8bd1424

Also improve physical_key_codes documentation

Qt backend: Add physical keys support on Linux

f4683a4

LeonMatthes force-pushed the physical-keys-shortcuts-v2 branch from 2630a9a to faeae5c Compare July 22, 2026 08:48

tronical reviewed Jul 22, 2026

View reviewed changes

LeonMatthes force-pushed the physical-keys-shortcuts-v2 branch from faeae5c to df16e1a Compare July 22, 2026 10:01

github-actions Bot deployed to pr-preview-12570 July 22, 2026 10:35 View deployment

github-actions Bot deployed to pr-preview-12570 July 22, 2026 13:29 View deployment

LeonMatthes force-pushed the physical-keys-shortcuts-v2 branch from 597b083 to a0dd0e6 Compare July 22, 2026 13:43

LeonMatthes added 7 commits July 22, 2026 16:23

Qt: Add physical key codes for macOS/Windows

77cca09

Align physical key codes table

3f98e62

LinuxKMS: Add physical keys support

6907839

Winit WASM: Add physical key support

73d2a6d

Android: Add physical keys support

d24694d

Fix comment being picked up as doc test.

140985a

For some reason the doc-tests picked up this comment as a doc test: //! Slint # Winit # Xkb # Win # Mac Fixed by removing the indentation 🤷

Move Physical keys docs above code example

6502f4e

LeonMatthes force-pushed the physical-keys-shortcuts-v2 branch from a0dd0e6 to 6502f4e Compare July 22, 2026 14:23

github-actions Bot deployed to pr-preview-12570 July 22, 2026 15:25 View deployment

LeonMatthes mentioned this pull request Jul 23, 2026

Resolve standard shortcuts by physical key (fix Ctrl+V on non-Latin layouts and with CapsLock) #12587

Open

LeonMatthes requested a review from tronical July 23, 2026 08:48

tronical reviewed Jul 23, 2026

View reviewed changes

LeonMatthes marked this pull request as ready for review July 24, 2026 08:39

LeonMatthes requested a review from tronical July 24, 2026 08:39

Incorporate review feedback by @tronical

9e85f40

LeonMatthes force-pushed the physical-keys-shortcuts-v2 branch from de41e6e to 9e85f40 Compare July 24, 2026 08:50

github-actions Bot deployed to pr-preview-12570 July 24, 2026 09:24 View deployment

LeonMatthes enabled auto-merge (squash) July 27, 2026 08:11


		### Physical Key Bindings

		If you want to match a physical key position instead of the character produced on the current keyboard layout, use `@physical-keys(..)`.


		As another example, `@keys(Control + Plus)` is equivalent to `@keys(Control + Shift? + "+")`.

		### Physical Key Bindings

Uh oh!

Conversation

LeonMatthes commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tronical left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LeonMatthes Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LeonMatthes Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

LeonMatthes commented Jul 21, 2026 •

edited

Loading

LeonMatthes Jul 24, 2026 •

edited

Loading

LeonMatthes Jul 24, 2026 •

edited

Loading