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.

src/platform/macos.rs

@@ -56,17 +56,6 @@ pub trait WindowExtMacOS {
 
     /// Put the window in a state which indicates a file save is required.
     fn set_document_edited(&self, edited: bool);
-
-    /// Set option as alt behavior as described in [`OptionAsAlt`].
-    ///
-    /// This will ignore diacritical marks and accent characters from
-    /// being processed as received characters. Instead, the input
-    /// device's raw character will be placed in event queues with the
-    /// Alt modifier set.
-    fn set_option_as_alt(&self, option_as_alt: OptionAsAlt);
-
-    /// Getter for the [`WindowExtMacOS::set_option_as_alt`].
-    fn option_as_alt(&self) -> OptionAsAlt;
 }
 
 impl WindowExtMacOS for Window {
@@ -109,16 +98,6 @@ impl WindowExtMacOS for Window {
     fn set_document_edited(&self, edited: bool) {
         self.window.set_document_edited(edited)
     }
-
-    #[inline]
-    fn set_option_as_alt(&self, option_as_alt: OptionAsAlt) {
-        self.window.set_option_as_alt(option_as_alt)
-    }
-
-    #[inline]
-    fn option_as_alt(&self) -> OptionAsAlt {
-        self.window.option_as_alt()
-    }
 }
 
 /// Corresponds to `NSApplicationActivationPolicy`.
@@ -161,11 +140,6 @@ pub trait WindowBuilderExtMacOS {
     fn with_has_shadow(self, has_shadow: bool) -> WindowBuilder;
     /// Window accepts click-through mouse events.
     fn with_accepts_first_mouse(self, accepts_first_mouse: bool) -> WindowBuilder;
-
-    /// Set whether the `OptionAsAlt` key is interpreted as the `Alt` modifier.
-    ///
-    /// See [`WindowExtMacOS::set_option_as_alt`] for details on what this means if set.
-    fn with_option_as_alt(self, option_as_alt: OptionAsAlt) -> WindowBuilder;
 }
 
 impl WindowBuilderExtMacOS for WindowBuilder {
@@ -225,12 +199,6 @@ impl WindowBuilderExtMacOS for WindowBuilder {
         self.platform_specific.accepts_first_mouse = accepts_first_mouse;
         self
     }
-
-    #[inline]
-    fn with_option_as_alt(mut self, option_as_alt: OptionAsAlt) -> WindowBuilder {
-        self.platform_specific.option_as_alt = option_as_alt;
-        self
-    }
 }
 
 pub trait EventLoopBuilderExtMacOS {
@@ -341,23 +309,3 @@ impl<T> EventLoopWindowTargetExtMacOS for EventLoopWindowTarget<T> {
         self.p.hide_other_applications()
     }
 }
-
-/// Option as alt behavior.
-///
-/// The default is `None`.
-#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
-#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
-pub enum OptionAsAlt {
-    /// The left `Option` key is treated as `Alt`.
-    OnlyLeft,
-
-    /// The right `Option` key is treated as `Alt`.
-    OnlyRight,
-
-    /// Both `Option` keys are treated as `Alt`.
-    Both,
-
-    /// No special handling is applied for `Option` key.
-    #[default]
-    None,
-}

src/platform/mod.rs

@@ -32,6 +32,7 @@ pub mod windows;
 #[cfg(x11_platform)]
 pub mod x11;
 
+pub mod modifier_supplement;
 #[cfg(any(
     windows_platform,
     macos_platform,
@@ -41,3 +42,4 @@ pub mod x11;
     orbital_platform
 ))]
 pub mod run_return;
+pub mod scancode;

src/platform/modifier_supplement.rs

@@ -0,0 +1,24 @@
+#![cfg(any(windows_platform, macos_platform, x11_platform, wayland_platform))]
+
+use crate::keyboard::Key;
+
+/// Additional methods for the `KeyEvent` which cannot be implemented on all
+/// platforms.
+pub trait KeyEventExtModifierSupplement {
+    /// Identical to `KeyEvent::text` but this is affected by <kbd>Ctrl</kbd>.
+    ///
+    /// For example, pressing <kbd>Ctrl</kbd>+<kbd>a</kbd> produces `Some("\x01")`.
+    fn text_with_all_modifiers(&self) -> Option<&str>;
+
+    /// This value ignores all modifiers including,
+    /// but not limited to <kbd>Shift</kbd>, <kbd>Caps Lock</kbd>,
+    /// and <kbd>Ctrl</kbd>. In most cases this means that the
+    /// unicode character in the resulting string is lowercase.
+    ///
+    /// This is useful for key-bindings / shortcut key combinations.
+    ///
+    /// In case `logical_key` reports `Dead`, this will still report the
+    /// key as `Character` according to the current keyboard layout. This value
+    /// cannot be `Dead`.
+    fn key_without_modifiers(&self) -> Key;
+}

src/platform/scancode.rs

@@ -0,0 +1,28 @@
+#![cfg(any(windows_platform, macos_platform, x11_platform, wayland_platform))]
+
+// TODO: Maybe merge this with `modifier_supplement` if the two are indeed supported on the same
+// set of platforms
+
+use crate::keyboard::KeyCode;
+
+/// Additional methods for the [`KeyCode`] type that allow the user to access the platform-specific
+/// scancode.
+///
+/// [`KeyCode`]: crate::keyboard::KeyCode
+pub trait KeyCodeExtScancode {
+    /// The raw value of the platform-specific physical key identifier.
+    ///
+    /// Returns `Some(key_id)` if the conversion was succesful; returns `None` otherwise.
+    ///
+    /// ## Platform-specific
+    /// - **Windows:** A 16bit extended scancode
+    /// - **Wayland/X11**: A 32-bit X11-style keycode.
+    // TODO: Describe what this value contains for each platform
+    fn to_scancode(self) -> Option<u32>;
+
+    /// Constructs a `KeyCode` from a platform-specific physical key identifier.
+    ///
+    /// Note that this conversion may be lossy, i.e. converting the returned `KeyCode` back
+    /// using `to_scancode` might not yield the original value.
+    fn from_scancode(scancode: u32) -> KeyCode;
+}

src/platform/windows.rs

@@ -2,9 +2,11 @@ use std::{ffi::c_void, path::Path};
 
 use crate::{
     dpi::PhysicalSize,
-    event::DeviceId,
+    event::{DeviceId, KeyEvent},
     event_loop::EventLoopBuilder,
+    keyboard::Key,
     monitor::MonitorHandle,
+    platform::modifier_supplement::KeyEventExtModifierSupplement,
     platform_impl::WinIcon,
     window::{BadIcon, Icon, Window, WindowBuilder},
 };
@@ -344,3 +346,18 @@ impl IconExtWindows for Icon {
         Ok(Icon { inner: win_icon })
     }
 }
+
+impl KeyEventExtModifierSupplement for KeyEvent {
+    #[inline]
+    fn text_with_all_modifiers(&self) -> Option<&str> {
+        self.platform_specific
+            .text_with_all_modifers
+            .as_ref()
+            .map(|s| s.as_str())
+    }
+
+    #[inline]
+    fn key_without_modifiers(&self) -> Key {
+        self.platform_specific.key_without_modifiers.clone()
+    }
+}