refactor: keyboards events

.changes/keyboard-event.md

@@ -0,0 +1,15 @@
+---
+"tao": minor
+---
+
+**Breaking change**: New keyboard API, including `Accelerator` and `GlobalShortcut`.
+
+`WindowEvent::ModifiersChanged` is emitted when a new keyboard modifier is pressed. This is your responsibility to keep a local state. When the modifier is released, `ModifiersState::empty()` is emitted.
+
+`WindowEvent::KeyboardInput` as been refactored and is exposing the event `KeyEvent`.
+
+All menus (`ContextMenu` and `MenuBar`), now includes `Accelerator` support on Windows, macOS and Linux.
+
+New modules available: `keyboard`, `accelerator` and `platform::global_shortcut`. 
+
+_Please refer to the docs and examples for more details._

Cargo.toml

@@ -61,17 +61,21 @@ core-graphics = "0.22"
 dispatch = "0.2"
 scopeguard = "1.1"
 
-  [target."cfg(target_os = \"macos\")".dependencies.core-video-sys]
-  version = "0.1"
-  default_features = false
-  features = [ "display_link" ]
+[target."cfg(target_os = \"macos\")".dependencies.core-video-sys]
+version = "0.1"
+default_features = false
+features = [ "display_link" ]
+
+[target."cfg(target_os = \"macos\")".build-dependencies]
+cc = "1"
 
 [target."cfg(target_os = \"windows\")".dependencies]
 parking_lot = "0.11"
+unicode-segmentation = "1.7.1"
 
-  [target."cfg(target_os = \"windows\")".dependencies.winapi]
-  version = "0.3"
-  features = [
+[target."cfg(target_os = \"windows\")".dependencies.winapi]
+version = "0.3"
+features = [
   "combaseapi",
   "commctrl",
   "dwmapi",
@@ -91,6 +95,7 @@ parking_lot = "0.11"
   "winerror",
   "wingdi",
   "winnt",
+  "winnls",
   "winuser",
   "impl-default"
 ]
@@ -99,8 +104,11 @@ parking_lot = "0.11"
 cairo-rs = "0.9"
 gio = "0.9"
 glib = "0.10"
+glib-sys = "0.10"
 gtk = { version = "0.9", features = [ "v3_16" ] }
 gdk = "0.13"
+gdk-sys = "0.10"
 gdk-pixbuf = { version = "0.9", features = [ "v2_36_8" ] }
 sourceview = { version = "0.9", optional = true }
 libappindicator = { version = "0.5", optional = true }
+x11-dl = "2.18"

build.rs

@@ -10,4 +10,14 @@ fn main() {
   {
     println!("cargo:rustc-cfg=use_colorsync_cgdisplaycreateuuidfromdisplayid");
   }
+  // link carbon hotkey on macOS
+  #[cfg(target_os = "macos")]
+  {
+    if std::env::var("CARGO_CFG_TARGET_OS").map_or(false, |os| os == "macos") {
+      println!("cargo:rustc-link-lib=framework=Carbon");
+      cc::Build::new()
+        .file("src/platform_impl/macos/carbon_hotkey/carbon_hotkey_binding.c")
+        .compile("carbon_hotkey_binding.a");
+    }
+  }
 }

examples/accelerator.rs

@@ -0,0 +1,55 @@
+// Copyright 2019-2021 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+
+fn main() {
+  use simple_logger::SimpleLogger;
+  use tao::{
+    accelerator::{Accelerator, RawMods},
+    dpi::LogicalSize,
+    event::{ElementState, Event, WindowEvent},
+    event_loop::{ControlFlow, EventLoop},
+    keyboard::{Key, KeyCode, ModifiersState},
+    window::WindowBuilder,
+  };
+
+  SimpleLogger::new().init().unwrap();
+
+  // create a sample hotkey
+  let hotkey = Accelerator::new(RawMods::Shift, KeyCode::Digit1);
+  // create local modifier state
+  let mut modifiers = ModifiersState::default();
+
+  let event_loop = EventLoop::new();
+
+  let _window = WindowBuilder::new()
+    .with_inner_size(LogicalSize::new(400.0, 200.0))
+    .build(&event_loop)
+    .unwrap();
+
+  event_loop.run(move |event, _, control_flow| {
+    *control_flow = ControlFlow::Wait;
+
+    if let Event::WindowEvent { event, .. } = event {
+      match event {
+        WindowEvent::CloseRequested => *control_flow = ControlFlow::Exit,
+        WindowEvent::ModifiersChanged(new_state) => {
+          // update our local modifier state
+          modifiers = new_state;
+        }
+        // catch only pressed event
+        WindowEvent::KeyboardInput { event, .. } if event.state == ElementState::Pressed => {
+          if hotkey.matches(&modifiers, &event.physical_key) {
+            println!(
+              "KeyEvent:  `Shift` + `1` | logical_key: {:?}",
+              &event.logical_key
+            );
+            // we can match manually without `Accelerator`
+          } else if event.key_without_modifiers() == Key::Character("1") && modifiers.is_empty() {
+            println!("KeyEvent: `1`");
+          }
+        }
+        _ => (),
+      }
+    }
+  });
+}

examples/control_flow.rs

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

examples/cursor.rs

@@ -3,7 +3,7 @@
 
 use simple_logger::SimpleLogger;
 use tao::{
-  event::{ElementState, Event, KeyboardInput, WindowEvent},
+  event::{ElementState, Event, KeyEvent, WindowEvent},
   event_loop::{ControlFlow, EventLoop},
   window::{CursorIcon, WindowBuilder},
 };
@@ -24,8 +24,8 @@ fn main() {
       Event::WindowEvent {
         event:
           WindowEvent::KeyboardInput {
-            input:
-              KeyboardInput {
+            event:
+              KeyEvent {
                 state: ElementState::Pressed,
                 ..
               },
@@ -44,9 +44,7 @@ fn main() {
       Event::WindowEvent {
         event: WindowEvent::CloseRequested,
         ..
-      } => {
-        *control_flow = ControlFlow::Exit;
-      }
+      } => *control_flow = ControlFlow::Exit,
       _ => (),
     }
   });

examples/cursor_grab.rs

@@ -3,8 +3,9 @@
 
 use simple_logger::SimpleLogger;
 use tao::{
-  event::{DeviceEvent, ElementState, Event, KeyboardInput, ModifiersState, WindowEvent},
+  event::{DeviceEvent, ElementState, Event, KeyEvent, WindowEvent},
   event_loop::{ControlFlow, EventLoop},
+  keyboard::{Key, ModifiersState},
   window::WindowBuilder,
 };
 
@@ -27,19 +28,23 @@ fn main() {
       Event::WindowEvent { event, .. } => match event {
         WindowEvent::CloseRequested => *control_flow = ControlFlow::Exit,
         WindowEvent::KeyboardInput {
-          input:
-            KeyboardInput {
+          event:
+            KeyEvent {
+              logical_key: key,
               state: ElementState::Released,
-              virtual_keycode: Some(key),
               ..
             },
           ..
         } => {
-          use tao::event::VirtualKeyCode::*;
+          // WARNING: Consider using `key_without_modifers()` if available on your platform.
+          // See the `key_binding` example
           match key {
-            Escape => *control_flow = ControlFlow::Exit,
-            G => window.set_cursor_grab(!modifiers.shift()).unwrap(),
-            H => window.set_cursor_visible(modifiers.shift()),
+            Key::Escape => *control_flow = ControlFlow::Exit,
+            Key::Character(ch) => match ch.to_lowercase().as_str() {
+              "g" => window.set_cursor_grab(!modifiers.shift_key()).unwrap(),
+              "h" => window.set_cursor_visible(modifiers.shift_key()),
+              _ => (),
+            },
             _ => (),
           }
         }

examples/custom_menu.rs

@@ -5,9 +5,11 @@ use simple_logger::SimpleLogger;
 #[cfg(target_os = "macos")]
 use tao::platform::macos::{CustomMenuItemExtMacOS, NativeImage};
 use tao::{
+  accelerator::{Accelerator, SysMods},
   clipboard::Clipboard,
   event::{Event, WindowEvent},
   event_loop::{ControlFlow, EventLoop},
+  keyboard::KeyCode,
   menu::{MenuBar as Menu, MenuItem, MenuItemAttributes, MenuType},
   window::WindowBuilder,
 };
@@ -25,15 +27,15 @@ fn main() {
   // create `first_menu`
   let mut first_menu = Menu::new();
 
-  // create an empty menu to be used as submenu
-  let mut my_sub_menu = Menu::new();
-
   // create second menu
   let mut second_menu = Menu::new();
+  // create an empty menu to be used as submenu
+  let mut my_sub_menu = Menu::new();
 
-  // create custom item `Disable menu` children of `my_sub_menu`
-  let mut test_menu_item =
-    my_sub_menu.add_item(MenuItemAttributes::new("Disable menu").with_accelerators("<Primary>d"));
+  let mut test_menu_item = my_sub_menu.add_item(
+    MenuItemAttributes::new("Disable menu")
+      .with_accelerators(&Accelerator::new(SysMods::Cmd, KeyCode::KeyD)),
+  );
 
   // add native `Copy` to `first_menu` menu
   // in macOS native item are required to get keyboard shortcut
@@ -46,6 +48,7 @@ fn main() {
 
   // add `my_sub_menu` children of `first_menu` with `Sub menu` title
   first_menu.add_submenu("Sub menu", true, my_sub_menu);
+  first_menu.add_native_item(MenuItem::Quit);
 
   // create custom item `Selected and disabled` children of `second_menu`
   second_menu.add_item(

examples/drag_window.rs

@@ -3,10 +3,9 @@
 
 use simple_logger::SimpleLogger;
 use tao::{
-  event::{
-    ElementState, Event, KeyboardInput, MouseButton, StartCause, VirtualKeyCode, WindowEvent,
-  },
+  event::{ElementState, Event, KeyEvent, MouseButton, StartCause, WindowEvent},
   event_loop::{ControlFlow, EventLoop},
+  keyboard::Key,
   window::{Window, WindowBuilder, WindowId},
 };
 
@@ -47,14 +46,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,
             ..
           },
         ..
-      } => {
+      } if logical_key == Key::Character("x") => {
         switched = !switched;
         name_windows(entered_id, switched, &window_1, &window_2);
         println!("Switched!")