Overhaul the Keyboard API

Overhaul the keyboard API in winit to mimic the W3C specification
to achieve better crossplatform parity. The `KeyboardInput` event
is now uses `KeyEvent` which consists of:

  - `physical_key` - a cross platform way to refer to scancodes;
  - `logical_key`  - keysym value, which shows your key respecting the
                     layout;
  - `text`         - the text produced by this keypress;
  - `location`     - the location of the key on the keyboard;
  - `repeat`       - whether the key was produced by the repeat.

And also a `platform_specific` field which encapsulates extra
information on desktop platforms, like key without modifiers
and text with all modifiers.

The `Modifiers` were also slightly reworked as in, the information
whether the left or right modifier is pressed is now also exposed
on platforms where it could be queried reliably. The support was
also added for the web and orbital platforms finishing the API
change.

This change made the `OptionAsAlt` API on macOS redundant thus it
was removed all together.

Co-Authored-By: Artúr Kovács <kovacs.artur.barnabas@gmail.com>
Co-Authored-By: Kirill Chibisov <contact@kchibisov.com>
Co-Authored-By: daxpedda <daxpedda@gmail.com>
Fixes: #2631.
Fixes: #2055.
Fixes: #2032.
Fixes: #1904.
Fixes: #1810.
Fixes: #1700.
Fixes: #1443.
Fixes: #1343.
Fixes: #1208.
Fixes: #1151.
Fixes: #812.
Fixes: #600.
Fixes: #361.
Fixes: #343.

.github/workflows/ci.yml

@@ -75,7 +75,6 @@ jobs:
     env:
       RUST_BACKTRACE: 1
       CARGO_INCREMENTAL: 0
-      PKG_CONFIG_ALLOW_CROSS: 1
       RUSTFLAGS: "-C debuginfo=0 --deny warnings"
       OPTIONS: ${{ matrix.platform.options }}
       FEATURES: ${{ format(',{0}', matrix.platform.features ) }}
@@ -98,12 +97,9 @@ jobs:
         targets: ${{ matrix.platform.target }}
         components: clippy
 
-    - name: Install Linux dependencies
-      if: (matrix.platform.os == 'ubuntu-latest')
-      run: sudo apt-get update && sudo apt-get install pkg-config libxkbcommon-dev
     - name: Install GCC Multilib
       if: (matrix.platform.os == 'ubuntu-latest') && contains(matrix.platform.target, 'i686')
-      run: sudo dpkg --add-architecture i386 && sudo apt-get update && sudo apt-get install g++-multilib gcc-multilib libxkbcommon-dev:i386
+      run: sudo apt-get update && sudo apt-get install gcc-multilib
     - name: Install cargo-apk
       if: contains(matrix.platform.target, 'android')
       run: cargo install cargo-apk

CHANGELOG.md

@@ -8,6 +8,34 @@ And please only add new entries to the top of this list, right below the `# Unre
 
 # Unreleased
 
+- **Breaking:** Remove all deprecated `modifiers` fields.
+- **Breaking:** Overhaul keyboard input handling.
+  - Replace `KeyboardInput` with `KeyEvent` and `RawKeyEvent`.
+    - Change `WindowEvent::KeyboardInput` to contain a `KeyEvent`.
+    - Change `Event::Key` to contain a `RawKeyEvent`.
+  - Remove `Event::ReceivedCharacter`. In its place, you should use
+    `KeyEvent.text` in combination with `WindowEvent::Ime`.
+  - Replace `VirtualKeyCode` with the `Key` enum.
+  - Replace `ScanCode` with the `KeyCode` enum.
+  - Rename `ModifiersState::LOGO` to `SUPER` and `ModifiersState::CTRL` to `CONTROL`.
+  - Add `KeyCode` to refer to keys (roughly) by their physical location.
+  - Add `NativeKeyCode` to represent raw `KeyCode`s which Winit doesn't
+    understand.
+  - Add `Key` to represent the keys after they've been interpreted by the
+    active (software) keyboard layout.
+  - Add `NativeKey` to represent raw `Key`s which Winit doesn't understand.
+  - Add `KeyLocation` to tell apart `Key`s which usually "mean" the same thing,
+    but can appear simultanesouly in different spots on the same keyboard
+    layout.
+  - Add `Window::reset_dead_keys` to enable application-controlled cancellation
+    of dead key sequences.
+  - Add `KeyEventExtModifierSupplement` to expose additional (and less
+    portable) interpretations of a given key-press.
+  - Add `KeyCodeExtScancode`, which lets you convert between raw keycodes and
+    `KeyCode`.
+  - Remove `WindowExtMacOS::option_as_alt` and `WindowExtMacOS::set_option_as_alt`.
+  - `ModifiersChanged` now uses dedicated `Modifiers` struct.
+- On Orbital, fix `ModifiersChanged` not being sent.
 - **Breaking:** `CursorIcon` is now used from the `cursor-icon` crate.
 - **Breaking:** `CursorIcon::Hand` is now named `CursorIcon::Pointer`.
 - **Breaking:** `CursorIcon::Arrow` was removed.

Cargo.toml

@@ -36,15 +36,15 @@ rustdoc-args = ["--cfg", "docsrs"]
 
 [features]
 default = ["x11", "wayland", "wayland-dlopen", "wayland-csd-adwaita"]
-x11 = ["x11-dl", "mio", "percent-encoding"]
-wayland = ["wayland-client", "wayland-backend", "wayland-protocols", "sctk", "fnv"]
+x11 = ["x11-dl", "mio", "percent-encoding", "xkbcommon-dl/x11"]
+wayland = ["wayland-client", "wayland-backend", "wayland-protocols", "sctk", "fnv", "memmap2"]
 wayland-dlopen = ["wayland-backend/dlopen"]
 wayland-csd-adwaita = ["sctk-adwaita", "sctk-adwaita/ab_glyph"]
 wayland-csd-adwaita-crossfont = ["sctk-adwaita", "sctk-adwaita/crossfont"]
 wayland-csd-adwaita-notitle = ["sctk-adwaita"]
 android-native-activity = ["android-activity/native-activity"]
 android-game-activity = ["android-activity/game-activity"]
-serde = ["dep:serde", "cursor-icon/serde"]
+serde = ["dep:serde", "cursor-icon/serde", "smol_str/serde"]
 
 [build-dependencies]
 cfg_aliases = "0.1.1"
@@ -58,6 +58,7 @@ mint = { version = "0.5.6", optional = true }
 once_cell = "1.12"
 raw_window_handle = { package = "raw-window-handle", version = "0.5" }
 serde = { version = "1", optional = true, features = ["serde_derive"] }
+smol_str = "0.2.0"
 
 [dev-dependencies]
 image = { version = "0.24.0", default-features = false, features = ["png"] }
@@ -67,6 +68,7 @@ simple_logger = { version = "2.1.0", default_features = false }
 # Coordinate the next winit release with android-ndk-rs: https://github.com/rust-windowing/winit/issues/1995
 android-activity = "0.4.0"
 ndk = "0.7.0"
+ndk-sys = "0.4.0"
 
 [target.'cfg(any(target_os = "ios", target_os = "macos"))'.dependencies]
 core-foundation = "0.9.3"
@@ -76,6 +78,9 @@ objc2 = ">=0.3.0-beta.3, <0.3.0-beta.4" # Allow `0.3.0-beta.3.patch-leaks`
 core-graphics = "0.22.3"
 dispatch = "0.2.0"
 
+[target.'cfg(target_os = "windows")'.dependencies]
+unicode-segmentation = "1.7.1"
+
 [target.'cfg(target_os = "windows")'.dependencies.windows-sys]
 version = "0.45"
 features = [
@@ -110,13 +115,15 @@ libc = "0.2.64"
 mio = { version = "0.8", features = ["os-ext"], optional = true }
 percent-encoding = { version = "2.0", optional = true }
 fnv = { version = "1.0.3", optional = true }
-sctk = { package = "smithay-client-toolkit", version = "0.17.0", optional = true }
+sctk = { package = "smithay-client-toolkit", version = "0.17.0", default-features = false, features = ["calloop"], optional = true }
 sctk-adwaita = { version = "0.6.0", default_features = false, optional = true }
 wayland-client = { version = "0.30.0", optional = true }
 wayland-backend = { version = "0.1.0", default_features = false, features = ["client_system"], optional = true }
 wayland-protocols = { version = "0.30.0", features = [ "staging"], optional = true }
 calloop = "0.10.5"
 x11-dl = { version = "2.18.5", optional = true }
+xkbcommon-dl = { git = "https://github.com/maroider/xkbcommon-dl", rev = "900832888ad6f11011d1369befb344a9aa8a9610" }
+memmap2 = { version = "0.5.0", optional = true }
 
 [target.'cfg(target_os = "redox")'.dependencies]
 orbclient = { version = "0.3.42", default-features = false }

FEATURES.md

@@ -222,9 +222,9 @@ Changes in the API that have been agreed upon but aren't implemented across all
 
 |Feature                             |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS    |WASM      |Redox OS|
 |------------------------------      | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | ------ |
-|New API for HiDPI ([#315] [#319])   |✔️    |✔️    |✔️       |✔️          |✔️     |✔️    |❓        |❓      |
-|Event Loop 2.0 ([#459])             |✔️    |✔️    |✔️       |✔️          |✔️     |✔️    |❓        |❓      |
-|Keyboard Input ([#812])             |❌    |❌    |❌       |❌          |❌     |❌    |❓        |❓      |
+|New API for HiDPI ([#315] [#319])   |✔️      |✔️     |✔️        |✔️            |✔️      |✔️      |❓        |❓      |
+|Event Loop 2.0 ([#459])             |✔️      |✔️     |✔️        |✔️            |✔️      |✔️      |❓        |✔️       |
+|Keyboard Input 2.0 ([#753])         |✔️      |✔️     |✔️        |✔️            |✔️      |❌     |✔️         |✔️       |
 
 ### Completed API Reworks
 |Feature                             |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS    |WASM      |Redox OS|
@@ -243,5 +243,5 @@ Changes in the API that have been agreed upon but aren't implemented across all
 [#720]: https://github.com/rust-windowing/winit/issues/720
 [#721]: https://github.com/rust-windowing/winit/issues/721
 [#750]: https://github.com/rust-windowing/winit/issues/750
+[#753]: https://github.com/rust-windowing/winit/issues/753
 [#804]: https://github.com/rust-windowing/winit/issues/804
-[#812]: https://github.com/rust-windowing/winit/issues/812

docs/res/ATTRIBUTION.md

@@ -0,0 +1,11 @@
+# Image Attribution
+
+These images are used in the documentation of `winit`.
+
+## keyboard_*.svg
+
+These files are a modified version of "[ANSI US QWERTY (Windows)](https://commons.wikimedia.org/wiki/File:ANSI_US_QWERTY_(Windows).svg)"
+by [Tomiĉo] (https://commons.wikimedia.org/wiki/User:Tomi%C4%89o). It is
+originally released under the [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/deed.en)
+License. Minor modifications have been made by [John Nunley](https://github.com/notgull),
+which have been released under the same license as a derivative work.

examples/child_window.rs

@@ -5,7 +5,7 @@ fn main() {
     use raw_window_handle::HasRawWindowHandle;
     use winit::{
         dpi::{LogicalPosition, LogicalSize, Position},
-        event::{ElementState, Event, KeyboardInput, WindowEvent},
+        event::{ElementState, Event, KeyEvent, WindowEvent},
         event_loop::{ControlFlow, EventLoop, EventLoopWindowTarget},
         window::{Window, WindowBuilder, WindowId},
     };
@@ -59,8 +59,8 @@ fn main() {
                     println!("cursor entered in the window {window_id:?}");
                 }
                 WindowEvent::KeyboardInput {
-                    input:
-                        KeyboardInput {
+                    event:
+                        KeyEvent {
                             state: ElementState::Pressed,
                             ..
                         },

examples/control_flow.rs

@@ -4,8 +4,9 @@ use std::{thread, time};
 
 use simple_logger::SimpleLogger;
 use winit::{
-    event::{Event, KeyboardInput, WindowEvent},
+    event::{ElementState, Event, KeyEvent, WindowEvent},
     event_loop::EventLoop,
+    keyboard::Key,
     window::WindowBuilder,
 };
 
@@ -40,7 +41,7 @@ fn main() {
     let mut close_requested = false;
 
     event_loop.run(move |event, _, control_flow| {
-        use winit::event::{ElementState, StartCause, VirtualKeyCode};
+        use winit::event::StartCause;
         println!("{event:?}");
         match event {
             Event::NewEvents(start_cause) => {
@@ -54,31 +55,33 @@ fn main() {
                     close_requested = true;
                 }
                 WindowEvent::KeyboardInput {
-                    input:
-                        KeyboardInput {
-                            virtual_keycode: Some(virtual_code),
+                    event:
+                        KeyEvent {
+                            logical_key: key,
                             state: ElementState::Pressed,
                             ..
                         },
                     ..
-                } => match virtual_code {
-                    VirtualKeyCode::Key1 => {
+                } => match key.as_ref() {
+                    // WARNING: Consider using `key_without_modifers()` if available on your platform.
+                    // See the `key_binding` example
+                    Key::Character("1") => {
                         mode = Mode::Wait;
                         println!("\nmode: {mode:?}\n");
                     }
-                    VirtualKeyCode::Key2 => {
+                    Key::Character("2") => {
                         mode = Mode::WaitUntil;
                         println!("\nmode: {mode:?}\n");
                     }
-                    VirtualKeyCode::Key3 => {
+                    Key::Character("3") => {
                         mode = Mode::Poll;
                         println!("\nmode: {mode:?}\n");
                     }
-                    VirtualKeyCode::R => {
+                    Key::Character("r") => {
                         request_redraw = !request_redraw;
                         println!("\nrequest_redraw: {request_redraw}\n");
                     }
-                    VirtualKeyCode::Escape => {
+                    Key::Escape => {
                         close_requested = true;
                     }
                     _ => (),

examples/cursor.rs

@@ -2,7 +2,7 @@
 
 use simple_logger::SimpleLogger;
 use winit::{
-    event::{ElementState, Event, KeyboardInput, WindowEvent},
+    event::{ElementState, Event, KeyEvent, WindowEvent},
     event_loop::EventLoop,
     window::{CursorIcon, WindowBuilder},
 };
@@ -23,8 +23,8 @@ fn main() {
             Event::WindowEvent {
                 event:
                     WindowEvent::KeyboardInput {
-                        input:
-                            KeyboardInput {
+                        event:
+                            KeyEvent {
                                 state: ElementState::Pressed,
                                 ..
                             },

examples/cursor_grab.rs

@@ -2,8 +2,9 @@
 
 use simple_logger::SimpleLogger;
 use winit::{
-    event::{DeviceEvent, ElementState, Event, KeyboardInput, ModifiersState, WindowEvent},
+    event::{DeviceEvent, ElementState, Event, KeyEvent, WindowEvent},
     event_loop::EventLoop,
+    keyboard::{Key, ModifiersState},
     window::{CursorGrabMode, WindowBuilder},
 };
 
@@ -25,35 +26,37 @@ fn main() {
             Event::WindowEvent { event, .. } => match event {
                 WindowEvent::CloseRequested => control_flow.set_exit(),
                 WindowEvent::KeyboardInput {
-                    input:
-                        KeyboardInput {
+                    event:
+                        KeyEvent {
+                            logical_key: key,
                             state: ElementState::Released,
-                            virtual_keycode: Some(key),
                             ..
                         },
                     ..
                 } => {
-                    use winit::event::VirtualKeyCode::*;
                     let result = match key {
-                        Escape => {
+                        Key::Escape => {
                             control_flow.set_exit();
                             Ok(())
                         }
-                        G => window.set_cursor_grab(CursorGrabMode::Confined),
-                        L => window.set_cursor_grab(CursorGrabMode::Locked),
-                        A => window.set_cursor_grab(CursorGrabMode::None),
-                        H => {
-                            window.set_cursor_visible(modifiers.shift());
-                            Ok(())
-                        }
+                        Key::Character(ch) => match ch.to_lowercase().as_str() {
+                            "g" => window.set_cursor_grab(CursorGrabMode::Confined),
+                            "l" => window.set_cursor_grab(CursorGrabMode::Locked),
+                            "a" => window.set_cursor_grab(CursorGrabMode::None),
+                            "h" => {
+                                window.set_cursor_visible(modifiers.shift_key());
+                                Ok(())
+                            }
+                            _ => Ok(()),
+                        },
                         _ => Ok(()),
                     };
 
                     if let Err(err) = result {
                         println!("error: {err}");
                     }
                 }
-                WindowEvent::ModifiersChanged(m) => modifiers = m,
+                WindowEvent::ModifiersChanged(new) => modifiers = new.state(),
                 _ => (),
             },
             Event::DeviceEvent { event, .. } => match event {

examples/drag_window.rs

@@ -2,10 +2,9 @@
 
 use simple_logger::SimpleLogger;
 use winit::{
-    event::{
-        ElementState, Event, KeyboardInput, MouseButton, StartCause, VirtualKeyCode, WindowEvent,
-    },
+    event::{ElementState, Event, KeyEvent, MouseButton, StartCause, WindowEvent},
     event_loop::EventLoop,
+    keyboard::Key,
     window::{Window, WindowBuilder, WindowId},
 };
 
@@ -45,14 +44,14 @@ fn main() {
                 name_windows(entered_id, switched, &window_1, &window_2)
             }
             WindowEvent::KeyboardInput {
-                input:
-                    KeyboardInput {
+                event:
+                    KeyEvent {
                         state: ElementState::Released,
-                        virtual_keycode: Some(VirtualKeyCode::X),
+                        logical_key: Key::Character(c),
                         ..
                     },
                 ..
-            } => {
+            } if c == "x" => {
                 switched = !switched;
                 name_windows(entered_id, switched, &window_1, &window_2);
                 println!("Switched!")