Revise Key and KeyCode enums

Split `Key` into clear categories, like `Named`, `Dead`, Character`, `Unidentified`
removing the `#[non_exhaustive]` from the `Key` itself.

Similar action was done for the `KeyCode`.

Fixes: #2995
Co-authored-by: Kirill Chibisov <contact@kchibisov.com>

examples/control_flow.rs

@@ -10,7 +10,7 @@ use simple_logger::SimpleLogger;
 use winit::{
     event::{ElementState, Event, KeyEvent, WindowEvent},
     event_loop::{ControlFlow, EventLoop},
-    keyboard::Key,
+    keyboard::{Key, NamedKey},
     window::WindowBuilder,
 };
 
@@ -88,7 +88,7 @@ fn main() -> Result<(), impl std::error::Error> {
                         request_redraw = !request_redraw;
                         println!("\nrequest_redraw: {request_redraw}\n");
                     }
-                    Key::Escape => {
+                    Key::Named(NamedKey::Escape) => {
                         close_requested = true;
                     }
                     _ => (),

examples/cursor_grab.rs

@@ -4,7 +4,7 @@ use simple_logger::SimpleLogger;
 use winit::{
     event::{DeviceEvent, ElementState, Event, KeyEvent, WindowEvent},
     event_loop::EventLoop,
-    keyboard::{Key, ModifiersState},
+    keyboard::{Key, ModifiersState, NamedKey},
     window::{CursorGrabMode, WindowBuilder},
 };
 
@@ -35,7 +35,7 @@ fn main() -> Result<(), impl std::error::Error> {
                 ..
             } => {
                 let result = match key {
-                    Key::Escape => {
+                    Key::Named(NamedKey::Escape) => {
                         elwt.exit();
                         Ok(())
                     }

examples/fullscreen.rs

@@ -4,7 +4,7 @@ use simple_logger::SimpleLogger;
 use winit::dpi::PhysicalSize;
 use winit::event::{ElementState, Event, KeyEvent, WindowEvent};
 use winit::event_loop::EventLoop;
-use winit::keyboard::Key;
+use winit::keyboard::{Key, NamedKey};
 use winit::window::{Fullscreen, WindowBuilder};
 
 #[cfg(target_os = "macos")]
@@ -65,7 +65,7 @@ fn main() -> Result<(), impl std::error::Error> {
                         },
                     ..
                 } => match key {
-                    Key::Escape => elwt.exit(),
+                    Key::Named(NamedKey::Escape) => elwt.exit(),
                     // WARNING: Consider using `key_without_modifers()` if available on your platform.
                     // See the `key_binding` example
                     Key::Character(ch) => match ch.to_lowercase().as_str() {

examples/ime.rs

@@ -6,7 +6,7 @@ use winit::{
     dpi::{PhysicalPosition, PhysicalSize},
     event::{ElementState, Event, Ime, WindowEvent},
     event_loop::EventLoop,
-    keyboard::{Key, KeyCode},
+    keyboard::NamedKey,
     window::{ImePurpose, WindowBuilder},
 };
 
@@ -69,12 +69,12 @@ fn main() -> Result<(), impl std::error::Error> {
                 WindowEvent::KeyboardInput { event, .. } => {
                     println!("key: {event:?}");
 
-                    if event.state == ElementState::Pressed && event.physical_key == KeyCode::F2 {
+                    if event.state == ElementState::Pressed && event.logical_key == NamedKey::F2 {
                         ime_allowed = !ime_allowed;
                         window.set_ime_allowed(ime_allowed);
                         println!("\nIME allowed: {ime_allowed}\n");
                     }
-                    if event.state == ElementState::Pressed && event.logical_key == Key::F3 {
+                    if event.state == ElementState::Pressed && event.logical_key == NamedKey::F3 {
                         ime_purpose = match ime_purpose {
                             ImePurpose::Normal => ImePurpose::Password,
                             ImePurpose::Password => ImePurpose::Terminal,

examples/multithreaded.rs

@@ -9,7 +9,7 @@ fn main() -> Result<(), impl std::error::Error> {
         dpi::{PhysicalPosition, PhysicalSize, Position, Size},
         event::{ElementState, Event, KeyEvent, WindowEvent},
         event_loop::EventLoop,
-        keyboard::{Key, ModifiersState},
+        keyboard::{Key, ModifiersState, NamedKey},
         window::{CursorGrabMode, CursorIcon, Fullscreen, WindowBuilder, WindowLevel},
     };
 
@@ -65,17 +65,17 @@ fn main() -> Result<(), impl std::error::Error> {
                             },
                         ..
                     } => {
-                        use Key::{ArrowLeft, ArrowRight};
+                        use NamedKey::{ArrowLeft, ArrowRight};
                         window.set_title(&format!("{key:?}"));
                         let state = !modifiers.shift_key();
                         match key {
                             // Cycle through video modes
-                            Key::ArrowRight | Key::ArrowLeft => {
-                                video_mode_id = match key {
-                                    ArrowLeft => video_mode_id.saturating_sub(1),
-                                    ArrowRight => (video_modes.len() - 1).min(video_mode_id + 1),
-                                    _ => unreachable!(),
-                                };
+                            Key::Named(ArrowRight) | Key::Named(ArrowLeft) => {
+                                if key == ArrowLeft {
+                                    video_mode_id = video_mode_id.saturating_sub(1);
+                                } else if key == ArrowRight {
+                                    video_mode_id = (video_modes.len() - 1).min(video_mode_id + 1);
+                                }
                                 println!("Picking video mode: {}", video_modes[video_mode_id]);
                             }
                             // WARNING: Consider using `key_without_modifers()` if available on your platform.
@@ -185,7 +185,7 @@ fn main() -> Result<(), impl std::error::Error> {
                     event:
                         KeyEvent {
                             state: ElementState::Released,
-                            logical_key: Key::Escape,
+                            logical_key: Key::Named(NamedKey::Escape),
                             ..
                         },
                     ..

examples/multiwindow.rs

@@ -4,9 +4,9 @@ use std::collections::HashMap;
 
 use simple_logger::SimpleLogger;
 use winit::{
-    event::{ElementState, Event, KeyEvent, WindowEvent},
+    event::{ElementState, Event, WindowEvent},
     event_loop::EventLoop,
-    keyboard::Key,
+    keyboard::{Key, NamedKey},
     window::Window,
 };
 
@@ -40,19 +40,18 @@ fn main() -> Result<(), impl std::error::Error> {
                     }
                 }
                 WindowEvent::KeyboardInput {
-                    event:
-                        KeyEvent {
-                            state: ElementState::Pressed,
-                            logical_key: Key::Character(c),
-                            ..
-                        },
+                    event,
                     is_synthetic: false,
                     ..
-                } if matches!(c.as_ref(), "n" | "N") => {
-                    let window = Window::new(elwt).unwrap();
-                    println!("Opened a new window: {:?}", window.id());
-                    windows.insert(window.id(), window);
-                }
+                } if event.state == ElementState::Pressed => match event.logical_key {
+                    Key::Named(NamedKey::Escape) => elwt.exit(),
+                    Key::Character(c) if c == "n" || c == "N" => {
+                        let window = Window::new(elwt).unwrap();
+                        println!("Opened a new window: {:?}", window.id());
+                        windows.insert(window.id(), window);
+                    }
+                    _ => (),
+                },
                 WindowEvent::RedrawRequested => {
                     if let Some(window) = windows.get(&window_id) {
                         fill::fill_window(window);

examples/resizable.rs

@@ -5,7 +5,7 @@ use winit::{
     dpi::LogicalSize,
     event::{ElementState, Event, KeyEvent, WindowEvent},
     event_loop::EventLoop,
-    keyboard::KeyCode,
+    keyboard::{KeyCode, PhysicalKey},
     window::WindowBuilder,
 };
 
@@ -34,7 +34,7 @@ fn main() -> Result<(), impl std::error::Error> {
                 WindowEvent::KeyboardInput {
                     event:
                         KeyEvent {
-                            physical_key: KeyCode::Space,
+                            physical_key: PhysicalKey::Code(KeyCode::Space),
                             state: ElementState::Released,
                             ..
                         },

examples/startup_notification.rs

@@ -11,7 +11,6 @@ mod example {
 
     use winit::event::{ElementState, Event, KeyEvent, WindowEvent};
     use winit::event_loop::EventLoop;
-    use winit::keyboard::Key;
     use winit::platform::startup_notify::{
         EventLoopExtStartupNotify, WindowBuilderExtStartupNotify, WindowExtStartupNotify,
     };
@@ -46,7 +45,7 @@ mod example {
                             },
                         ..
                     } => {
-                        if logical_key == Key::Character("n".into()) {
+                        if logical_key == "n" {
                             if let Some(window) = windows.get(&window_id) {
                                 // Request a new activation token on this window.
                                 // Once we get it we will use it to create a window.

examples/web.rs

@@ -3,7 +3,7 @@
 use winit::{
     event::{ElementState, Event, KeyEvent, WindowEvent},
     event_loop::EventLoop,
-    keyboard::KeyCode,
+    keyboard::Key,
     window::{Fullscreen, WindowBuilder},
 };
 
@@ -39,13 +39,13 @@ pub fn main() -> Result<(), impl std::error::Error> {
                     WindowEvent::KeyboardInput {
                         event:
                             KeyEvent {
-                                physical_key: KeyCode::KeyF,
+                                logical_key: Key::Character(c),
                                 state: ElementState::Released,
                                 ..
                             },
                         ..
                     },
-            } if window_id == window.id() => {
+            } if window_id == window.id() && c == "f" => {
                 if window.fullscreen().is_some() {
                     window.set_fullscreen(None);
                 } else {

examples/window_debug.rs

@@ -7,7 +7,7 @@ use winit::{
     dpi::{LogicalSize, PhysicalSize},
     event::{DeviceEvent, ElementState, Event, KeyEvent, RawKeyEvent, WindowEvent},
     event_loop::{DeviceEvents, EventLoop},
-    keyboard::{Key, KeyCode},
+    keyboard::{Key, KeyCode, PhysicalKey},
     window::{Fullscreen, WindowBuilder},
 };
 
@@ -51,14 +51,14 @@ fn main() -> Result<(), impl std::error::Error> {
                     }),
                 ..
             } => match physical_key {
-                KeyCode::KeyM => {
+                PhysicalKey::Code(KeyCode::KeyM) => {
                     if minimized {
                         minimized = !minimized;
                         window.set_minimized(minimized);
                         window.focus_window();
                     }
                 }
-                KeyCode::KeyV => {
+                PhysicalKey::Code(KeyCode::KeyV) => {
                     if !visible {
                         visible = !visible;
                         window.set_visible(visible);

examples/window_resize_increments.rs

@@ -2,9 +2,9 @@ use log::debug;
 use simple_logger::SimpleLogger;
 use winit::{
     dpi::LogicalSize,
-    event::{ElementState, Event, KeyEvent, WindowEvent},
+    event::{ElementState, Event, WindowEvent},
     event_loop::EventLoop,
-    keyboard::Key,
+    keyboard::NamedKey,
     window::WindowBuilder,
 };
 
@@ -27,15 +27,10 @@ fn main() -> Result<(), impl std::error::Error> {
     event_loop.run(move |event, elwt| match event {
         Event::WindowEvent { event, window_id } if window_id == window.id() => match event {
             WindowEvent::CloseRequested => elwt.exit(),
-            WindowEvent::KeyboardInput {
-                event:
-                    KeyEvent {
-                        logical_key: Key::Space,
-                        state: ElementState::Released,
-                        ..
-                    },
-                ..
-            } => {
+            WindowEvent::KeyboardInput { event, .. }
+                if event.logical_key == NamedKey::Space
+                    && event.state == ElementState::Released =>
+            {
                 has_increments = !has_increments;
 
                 let new_increments = match window.resize_increments() {

examples/window_tabbing.rs

@@ -9,7 +9,7 @@ use simple_logger::SimpleLogger;
 use winit::{
     event::{ElementState, Event, KeyEvent, WindowEvent},
     event_loop::EventLoop,
-    keyboard::Key,
+    keyboard::{Key, NamedKey},
     platform::macos::{WindowBuilderExtMacOS, WindowExtMacOS},
     window::{Window, WindowBuilder},
 };
@@ -70,10 +70,10 @@ fn main() -> Result<(), impl std::error::Error> {
                     Key::Character("w") => {
                         let _ = windows.remove(&window_id);
                     }
-                    Key::ArrowRight => {
+                    Key::Named(NamedKey::ArrowRight) => {
                         windows.get(&window_id).unwrap().select_next_tab();
                     }
-                    Key::ArrowLeft => {
+                    Key::Named(NamedKey::ArrowLeft) => {
                         windows.get(&window_id).unwrap().select_previous_tab();
                     }
                     Key::Character(ch) => {

src/event.rs

@@ -671,7 +671,7 @@ pub enum DeviceEvent {
 #[derive(Debug, Clone, Eq, PartialEq, Hash)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub struct RawKeyEvent {
-    pub physical_key: keyboard::KeyCode,
+    pub physical_key: keyboard::PhysicalKey,
     pub state: ElementState,
 }
 
@@ -703,7 +703,7 @@ pub struct KeyEvent {
     /// `Fn` and `FnLock` key events are *exceedingly unlikely* to be emitted by Winit. These keys
     /// are usually handled at the hardware or OS level, and aren't surfaced to applications. If
     /// you somehow see this in the wild, we'd like to know :)
-    pub physical_key: keyboard::KeyCode,
+    pub physical_key: keyboard::PhysicalKey,
 
     // Allowing `broken_intra_doc_links` for `logical_key`, because
     // `key_without_modifiers` is not available on all platforms
@@ -743,7 +743,7 @@ pub struct KeyEvent {
     /// An additional difference from `logical_key` is that
     /// this field stores the text representation of any key
     /// that has such a representation. For example when
-    /// `logical_key` is `Key::Enter`, this field is `Some("\r")`.
+    /// `logical_key` is `Key::Named(NamedKey::Enter)`, this field is `Some("\r")`.
     ///
     /// This is `None` if the current keypress cannot
     /// be interpreted as text.