Keyboard Input 2.0

.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!")