Overhaul device events API and add gamepad support on Windows

CHANGELOG.md

@@ -43,6 +43,19 @@
 - Refactored Windows state/flag-setting code.
 - On Windows, hiding the cursor no longer hides the cursor for all Winit windows - just the one `hide_cursor` was called on.
 - On Windows, cursor grabs used to get perpetually canceled when the grabbing window lost focus. Now, cursor grabs automatically get re-initialized when the window regains focus and the mouse moves over the client area.
+- Improve event API documentation.
+- Overhaul device event API:
+  - **Breaking**: `Event::DeviceEvent` split into `MouseEvent`, `KeyboardEvent`, and `GamepadEvent`.
+  - **Breaking**: Remove `DeviceEvent::Text` variant.
+  - **Breaking**: `DeviceId` split into `MouseId`, `KeyboardId`, and `GamepadHandle`.
+  - **Breaking**: Removed device IDs from `WindowEvent` variants.
+  - Add `enumerate` function on device ID types to list all attached devices of that type.
+  - Add `is_connected` function on device ID types check if the specified device is still available.
+  - **Breaking**: On Windows, rename `DeviceIdExtWindows` to `DeviceExtWindows`.
+    - Add `handle` function to retrieve the underlying `HANDLE`.
+- On Windows, fix duplicate device events getting sent if Winit managed multiple windows.
+- On Windows, raw mouse events now report Mouse4 and Mouse5 presses and releases.
+- Added gamepad support on Windows via raw input and XInput.
 
 # Version 0.18.1 (2018-12-30)
 

Cargo.toml

@@ -37,6 +37,7 @@ core-graphics = "0.17.3"
 [target.'cfg(target_os = "windows")'.dependencies]
 backtrace = "0.3"
 bitflags = "1"
+rusty-xinput = "1.0"
 
 [target.'cfg(target_os = "windows")'.dependencies.winapi]
 version = "0.3.6"
@@ -45,6 +46,7 @@ features = [
     "commctrl",
     "dwmapi",
     "errhandlingapi",
+    "hidpi",
     "hidusage",
     "libloaderapi",
     "objbase",
@@ -60,6 +62,7 @@ features = [
     "wingdi",
     "winnt",
     "winuser",
+    "xinput",
 ]
 
 [target.'cfg(any(target_os = "linux", target_os = "dragonfly", target_os = "freebsd", target_os = "openbsd", target_os = "netbsd"))'.dependencies]

examples/cursor.rs

@@ -14,7 +14,7 @@ fn main() {
 
     event_loop.run(move |event, _, control_flow| {
         match event {
-            Event::WindowEvent { event: WindowEvent::KeyboardInput { input: KeyboardInput { state: ElementState::Pressed, .. }, .. }, .. } => {
+            Event::WindowEvent { event: WindowEvent::KeyboardInput(KeyboardInput { state: ElementState::Pressed, .. }), .. } => {
                 println!("Setting cursor to \"{:?}\"", CURSORS[cursor_idx]);
                 window.set_cursor(CURSORS[cursor_idx]);
                 if cursor_idx < CURSORS.len() - 1 {

examples/cursor_grab.rs

@@ -17,15 +17,12 @@ fn main() {
         if let Event::WindowEvent { event, .. } = event {
             match event {
                 WindowEvent::CloseRequested => *control_flow = ControlFlow::Exit,
-                WindowEvent::KeyboardInput {
-                    input: KeyboardInput {
-                        state: ElementState::Released,
-                        virtual_keycode: Some(key),
-                        modifiers,
-                        ..
-                    },
+                WindowEvent::KeyboardInput(KeyboardInput {
+                    state: ElementState::Released,
+                    virtual_keycode: Some(key),
+                    modifiers,
                     ..
-                } => {
+                }) => {
                     use winit::event::VirtualKeyCode::*;
                     match key {
                         Escape => *control_flow = ControlFlow::Exit,

examples/fullscreen.rs

@@ -56,15 +56,11 @@ fn main() {
         match event {
             Event::WindowEvent { event, .. } => match event {
                 WindowEvent::CloseRequested => *control_flow = ControlFlow::Exit,
-                WindowEvent::KeyboardInput {
-                    input:
-                        KeyboardInput {
-                            virtual_keycode: Some(virtual_code),
-                            state,
-                            ..
-                        },
+                WindowEvent::KeyboardInput(KeyboardInput {
+                    virtual_keycode: Some(virtual_code),
+                    state,
                     ..
-                } => match (virtual_code, state) {
+                }) => match (virtual_code, state) {
                     (VirtualKeyCode::Escape, _) => *control_flow = ControlFlow::Exit,
                     (VirtualKeyCode::F, ElementState::Pressed) => {
                         #[cfg(target_os = "macos")]

examples/gamepad.rs

@@ -0,0 +1,36 @@
+extern crate winit;
+use winit::window::WindowBuilder;
+use winit::event::{Event, WindowEvent};
+use winit::event::device::GamepadEvent;
+use winit::event_loop::{EventLoop, ControlFlow};
+
+fn main() {
+    let event_loop = EventLoop::new();
+
+    let _window = WindowBuilder::new()
+        .with_title("The world's worst video game")
+        .build(&event_loop)
+        .unwrap();
+
+    println!("enumerating gamepads:");
+    for gamepad in winit::event::device::GamepadHandle::enumerate(&event_loop) {
+        println!("    gamepad {:?}", gamepad);
+    }
+
+    let deadzone = 0.12;
+
+    event_loop.run(move |event, _, control_flow| {
+        match event {
+            Event::GamepadEvent(gamepad_handle, event) => match event {
+                GamepadEvent::Axis{stick: true, ..} => (),
+                GamepadEvent::Stick{x_value, y_value, ..} if (x_value.powi(2) + y_value.powi(2)).sqrt() < deadzone => (),
+                _ => println!("[{:?}] {:#?}", gamepad_handle, event)
+            },
+            Event::WindowEvent {
+                event: WindowEvent::CloseRequested,
+                ..
+            } => *control_flow = ControlFlow::Exit,
+            _ => ()
+        }
+    });
+}

examples/gamepad_rumble.rs

@@ -0,0 +1,58 @@
+extern crate winit;
+use winit::event_loop::EventLoop;
+use std::time::Instant;
+
+#[derive(Debug, Clone)]
+enum Rumble {
+    None,
+    Left,
+    Right,
+}
+
+fn main() {
+    let event_loop = EventLoop::new();
+
+    // You should generally use `GamepadEvent::Added/Removed` to detect gamepads, as doing that will
+    // allow you to more easily support gamepad hotswapping. However, we're using `enumerate` here
+    // because it makes this example more concise.
+    let gamepads = winit::event::device::GamepadHandle::enumerate(&event_loop).collect::<Vec<_>>();
+
+    let rumble_patterns = &[
+        (0.5, Rumble::None),
+        (2.0, Rumble::Left),
+        (0.5, Rumble::None),
+        (2.0, Rumble::Right),
+    ];
+    let mut rumble_iter = rumble_patterns.iter().cloned().cycle();
+
+    let mut active_pattern = rumble_iter.next().unwrap();
+    let mut timeout = active_pattern.0;
+    let mut timeout_start = Instant::now();
+
+    event_loop.run(move |_, _, _| {
+        if timeout <= active_pattern.0 {
+            let t = (timeout / active_pattern.0) * std::f64::consts::PI;
+            let intensity = t.sin();
+
+            for g in &gamepads {
+                let result = match active_pattern.1 {
+                    Rumble::Left => g.rumble(intensity, 0.0),
+                    Rumble::Right => g.rumble(0.0, intensity),
+                    Rumble::None => Ok(()),
+                };
+
+                if let Err(e) = result {
+                    println!("Rumble failed: {:?}", e);
+                }
+            }
+
+            timeout = (Instant::now() - timeout_start).as_millis() as f64 / 1000.0;
+        } else {
+            active_pattern = rumble_iter.next().unwrap();
+            println!("Rumbling {:?} for {:?} seconds", active_pattern.1, active_pattern.0);
+
+            timeout = 0.0;
+            timeout_start = Instant::now();
+        }
+    });
+}

examples/handling_close.rs

@@ -38,15 +38,11 @@ fn main() {
                     // closing the window. How to close the window is detailed in the handler for
                     // the Y key.
                 }
-                WindowEvent::KeyboardInput {
-                    input:
-                        KeyboardInput {
-                            virtual_keycode: Some(virtual_code),
-                            state: Released,
-                            ..
-                        },
+                WindowEvent::KeyboardInput(KeyboardInput {
+                    virtual_keycode: Some(virtual_code),
+                    state: Released,
                     ..
-                } => match virtual_code {
+                }) => match virtual_code {
                     Y => {
                         if close_requested {
                             // This is where you'll want to do any cleanup you need.

examples/multiwindow.rs

@@ -29,7 +29,7 @@ fn main() {
                             *control_flow = ControlFlow::Exit;
                         }
                     },
-                    WindowEvent::KeyboardInput { input: KeyboardInput { state: ElementState::Pressed, .. }, .. } => {
+                    WindowEvent::KeyboardInput(KeyboardInput { state: ElementState::Pressed, .. }) => {
                         let window = Window::new(&event_loop).unwrap();
                         windows.insert(window.id(), window);
                     },

examples/resizable.rs

@@ -20,15 +20,11 @@ fn main() {
         match event {
             Event::WindowEvent { event, .. } => match event {
                 WindowEvent::CloseRequested => *control_flow = ControlFlow::Exit,
-                WindowEvent::KeyboardInput {
-                    input:
-                        KeyboardInput {
-                            virtual_keycode: Some(VirtualKeyCode::Space),
-                            state: ElementState::Released,
-                            ..
-                        },
+                WindowEvent::KeyboardInput(KeyboardInput {
+                    virtual_keycode: Some(VirtualKeyCode::Space),
+                    state: ElementState::Released,
                     ..
-                } => {
+                }) => {
                     resizable = !resizable;
                     println!("Resizable: {}", resizable);
                     window.set_resizable(resizable);