Refine Window::set_cursor_grab API

This commit renames `Window::set_cursor_grab` to
`Window::set_cursor_grab_mode`. The new API now accepts enumeration
to control the way cursor grab is performed. The value could be: `lock`,
`confine`, or `none`.

This commit also implements `Window::set_cursor_position` for Wayland,
since it's tied to locked cursor.

Implements API from #1677.

CHANGELOG.md

@@ -58,6 +58,8 @@ And please only add new entries to the top of this list, right below the `# Unre
 - **Breaking:** On X11, device events are now ignored for unfocused windows by default, use `EventLoopWindowTarget::set_device_event_filter` to set the filter level.
 - Implemented `Default` on `EventLoop<()>`.
 - Implemented `Eq` for `Fullscreen`, `Theme`, and `UserAttentionType`.
+- **Breaking:** `Window::set_cursor_grab` now accepts `CursorGrabMode` to control grabbing behavior.
+- On Wayland, add support for `Window::set_cursor_position`.
 
 # 0.26.1 (2022-01-05)
 

FEATURES.md

@@ -100,7 +100,8 @@ If your PR makes notable changes to Winit's features, please update this section
 ### Input Handling
 - **Mouse events**: Generating mouse events associated with pointer motion, click, and scrolling events.
 - **Mouse set location**: Forcibly changing the location of the pointer.
-- **Cursor grab**: Locking the cursor so it cannot exit the client area of a window.
+- **Cursor locking**: Locking the cursor inside the window so it cannot move.
+- **Cursor confining**: Confining the cursor to the window bounds so it cannot leave them.
 - **Cursor icon**: Changing the cursor icon, or hiding the cursor.
 - **Cursor hittest**: Handle or ignore mouse events for a window.
 - **Touch events**: Single-touch events.
@@ -197,8 +198,9 @@ Legend:
 |Feature                 |Windows   |MacOS   |Linux x11|Linux Wayland|Android|iOS    |WASM      |
 |----------------------- | -----    | ----   | ------- | ----------- | ----- | ----- | -------- |
 |Mouse events            |✔️       |▢[#63]  |✔️       |✔️          |**N/A**|**N/A**|✔️        |
-|Mouse set location      |✔️       |✔️      |✔️       |❓           |**N/A**|**N/A**|**N/A**|
-|Cursor grab             |✔️       |▢[#165] |▢[#242]  |✔️         |**N/A**|**N/A**|✔️        |
+|Mouse set location      |✔️       |✔️      |✔️       |✔️(when locked)  |**N/A**|**N/A**|**N/A**|
+|Cursor locking          |❌      |✔️      |❌    |✔️         |**N/A**|**N/A**|✔️        |
+|Cursor confining        |✔️       |❌     |✔️     |✔️         |**N/A**|**N/A**|❌       |
 |Cursor icon             |✔️       |✔️      |✔️       |✔️           |**N/A**|**N/A**|✔️        |
 |Cursor hittest          |✔️       |✔️      |❌       |✔️           |**N/A**|**N/A**|❌        |
 |Touch events            |✔️       |❌      |✔️       |✔️          |✔️    |✔️     |❌        |

examples/cursor_grab.rs

@@ -4,7 +4,7 @@ use simple_logger::SimpleLogger;
 use winit::{
     event::{DeviceEvent, ElementState, Event, KeyboardInput, ModifiersState, WindowEvent},
     event_loop::EventLoop,
-    window::WindowBuilder,
+    window::{CursorGrabMode, WindowBuilder},
 };
 
 fn main() {
@@ -34,11 +34,23 @@ fn main() {
                     ..
                 } => {
                     use winit::event::VirtualKeyCode::*;
-                    match key {
-                        Escape => control_flow.set_exit(),
-                        G => window.set_cursor_grab(!modifiers.shift()).unwrap(),
-                        H => window.set_cursor_visible(modifiers.shift()),
-                        _ => (),
+                    let result = match 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(())
+                        }
+                        _ => Ok(()),
+                    };
+
+                    if let Err(err) = result {
+                        println!("error: {}", err);
                     }
                 }
                 WindowEvent::ModifiersChanged(m) => modifiers = m,

examples/multithreaded.rs

@@ -9,7 +9,7 @@ fn main() {
         dpi::{PhysicalPosition, PhysicalSize, Position, Size},
         event::{ElementState, Event, KeyboardInput, VirtualKeyCode, WindowEvent},
         event_loop::EventLoop,
-        window::{CursorIcon, Fullscreen, WindowBuilder},
+        window::{CursorGrabMode, CursorIcon, Fullscreen, WindowBuilder},
     };
 
     const WINDOW_COUNT: usize = 3;
@@ -88,7 +88,21 @@ fn main() {
                                 }
                                 (false, _) => None,
                             }),
-                            G => window.set_cursor_grab(state).unwrap(),
+                            L if state => {
+                                if let Err(err) = window.set_cursor_grab(CursorGrabMode::Locked) {
+                                    println!("error: {}", err);
+                                }
+                            }
+                            G if state => {
+                                if let Err(err) = window.set_cursor_grab(CursorGrabMode::Confined) {
+                                    println!("error: {}", err);
+                                }
+                            }
+                            G | L if !state => {
+                                if let Err(err) = window.set_cursor_grab(CursorGrabMode::None) {
+                                    println!("error: {}", err);
+                                }
+                            }
                             H => window.set_cursor_visible(!state),
                             I => {
                                 println!("Info:");

src/platform_impl/android/mod.rs

@@ -20,7 +20,8 @@ use crate::{
     error,
     event::{self, VirtualKeyCode},
     event_loop::{self, ControlFlow},
-    monitor, window,
+    monitor,
+    window::{self, CursorGrabMode},
 };
 
 static CONFIG: Lazy<RwLock<Configuration>> = Lazy::new(|| {
@@ -765,7 +766,7 @@ impl Window {
         ))
     }
 
-    pub fn set_cursor_grab(&self, _: bool) -> Result<(), error::ExternalError> {
+    pub fn set_cursor_grab(&self, _: CursorGrabMode) -> Result<(), error::ExternalError> {
         Err(error::ExternalError::NotSupported(
             error::NotSupportedError::new(),
         ))

src/platform_impl/ios/window.rs

@@ -23,7 +23,8 @@ use crate::{
         monitor, view, EventLoopWindowTarget, MonitorHandle,
     },
     window::{
-        CursorIcon, Fullscreen, UserAttentionType, WindowAttributes, WindowId as RootWindowId,
+        CursorGrabMode, CursorIcon, Fullscreen, UserAttentionType, WindowAttributes,
+        WindowId as RootWindowId,
     },
 };
 
@@ -184,7 +185,7 @@ impl Inner {
         Err(ExternalError::NotSupported(NotSupportedError::new()))
     }
 
-    pub fn set_cursor_grab(&self, _grab: bool) -> Result<(), ExternalError> {
+    pub fn set_cursor_grab(&self, _: CursorGrabMode) -> Result<(), ExternalError> {
         Err(ExternalError::NotSupported(NotSupportedError::new()))
     }
 

src/platform_impl/linux/mod.rs

@@ -9,8 +9,6 @@
 #[cfg(all(not(feature = "x11"), not(feature = "wayland")))]
 compile_error!("Please select a feature to build for unix: `x11`, `wayland`");
 
-#[cfg(feature = "wayland")]
-use crate::window::Theme;
 #[cfg(feature = "wayland")]
 use std::error::Error;
 
@@ -28,6 +26,8 @@ use raw_window_handle::RawWindowHandle;
 pub use self::x11::XNotSupported;
 #[cfg(feature = "x11")]
 use self::x11::{ffi::XVisualInfo, util::WindowType as XWindowType, XConnection, XError};
+#[cfg(feature = "wayland")]
+use crate::window::Theme;
 use crate::{
     dpi::{PhysicalPosition, PhysicalSize, Position, Size},
     error::{ExternalError, NotSupportedError, OsError as RootOsError},
@@ -37,7 +37,7 @@ use crate::{
     },
     icon::Icon,
     monitor::{MonitorHandle as RootMonitorHandle, VideoMode as RootVideoMode},
-    window::{CursorIcon, Fullscreen, UserAttentionType, WindowAttributes},
+    window::{CursorGrabMode, CursorIcon, Fullscreen, UserAttentionType, WindowAttributes},
 };
 
 pub(crate) use crate::icon::RgbaIcon as PlatformIcon;
@@ -388,8 +388,8 @@ impl Window {
     }
 
     #[inline]
-    pub fn set_cursor_grab(&self, grab: bool) -> Result<(), ExternalError> {
-        x11_or_wayland!(match self; Window(window) => window.set_cursor_grab(grab))
+    pub fn set_cursor_grab(&self, mode: CursorGrabMode) -> Result<(), ExternalError> {
+        x11_or_wayland!(match self; Window(window) => window.set_cursor_grab(mode))
     }
 
     #[inline]

src/platform_impl/linux/wayland/env.rs

@@ -24,23 +24,23 @@ use sctk::shm::ShmHandler;
 /// Set of extra features that are supported by the compositor.
 #[derive(Debug, Clone, Copy)]
 pub struct WindowingFeatures {
-    cursor_grab: bool,
+    pointer_constraints: bool,
     xdg_activation: bool,
 }
 
 impl WindowingFeatures {
     /// Create `WindowingFeatures` based on the presented interfaces.
     pub fn new(env: &Environment<WinitEnv>) -> Self {
-        let cursor_grab = env.get_global::<ZwpPointerConstraintsV1>().is_some();
+        let pointer_constraints = env.get_global::<ZwpPointerConstraintsV1>().is_some();
         let xdg_activation = env.get_global::<XdgActivationV1>().is_some();
         Self {
-            cursor_grab,
+            pointer_constraints,
             xdg_activation,
         }
     }
 
-    pub fn cursor_grab(&self) -> bool {
-        self.cursor_grab
+    pub fn pointer_constraints(&self) -> bool {
+        self.pointer_constraints
     }
 
     pub fn xdg_activation(&self) -> bool {

src/platform_impl/linux/wayland/seat/pointer/data.rs

@@ -5,8 +5,9 @@ use std::rc::Rc;
 
 use sctk::reexports::client::protocol::wl_surface::WlSurface;
 use sctk::reexports::client::Attached;
-use sctk::reexports::protocols::unstable::pointer_constraints::v1::client::zwp_pointer_constraints_v1::{ZwpPointerConstraintsV1};
+use sctk::reexports::protocols::unstable::pointer_constraints::v1::client::zwp_pointer_constraints_v1::ZwpPointerConstraintsV1;
 use sctk::reexports::protocols::unstable::pointer_constraints::v1::client::zwp_confined_pointer_v1::ZwpConfinedPointerV1;
+use sctk::reexports::protocols::unstable::pointer_constraints::v1::client::zwp_locked_pointer_v1::ZwpLockedPointerV1;
 
 use crate::event::{ModifiersState, TouchPhase};
 
@@ -25,6 +26,7 @@ pub(super) struct PointerData {
     pub pointer_constraints: Option<Attached<ZwpPointerConstraintsV1>>,
 
     pub confined_pointer: Rc<RefCell<Option<ZwpConfinedPointerV1>>>,
+    pub locked_pointer: Rc<RefCell<Option<ZwpLockedPointerV1>>>,
 
     /// Latest observed serial in pointer events.
     pub latest_serial: Rc<Cell<u32>>,
@@ -39,6 +41,7 @@ pub(super) struct PointerData {
 impl PointerData {
     pub fn new(
         confined_pointer: Rc<RefCell<Option<ZwpConfinedPointerV1>>>,
+        locked_pointer: Rc<RefCell<Option<ZwpLockedPointerV1>>>,
         pointer_constraints: Option<Attached<ZwpPointerConstraintsV1>>,
         modifiers_state: Rc<RefCell<ModifiersState>>,
     ) -> Self {
@@ -47,6 +50,7 @@ impl PointerData {
             latest_serial: Rc::new(Cell::new(0)),
             latest_enter_serial: Rc::new(Cell::new(0)),
             confined_pointer,
+            locked_pointer,
             modifiers_state,
             pointer_constraints,
             axis_data: AxisData::new(),

src/platform_impl/linux/wayland/seat/pointer/handlers.rs

@@ -60,6 +60,7 @@ pub(super) fn handle_pointer(
             let winit_pointer = WinitPointer {
                 pointer,
                 confined_pointer: Rc::downgrade(&pointer_data.confined_pointer),
+                locked_pointer: Rc::downgrade(&pointer_data.locked_pointer),
                 pointer_constraints: pointer_data.pointer_constraints.clone(),
                 latest_serial: pointer_data.latest_serial.clone(),
                 latest_enter_serial: pointer_data.latest_enter_serial.clone(),
@@ -104,6 +105,7 @@ pub(super) fn handle_pointer(
             let winit_pointer = WinitPointer {
                 pointer,
                 confined_pointer: Rc::downgrade(&pointer_data.confined_pointer),
+                locked_pointer: Rc::downgrade(&pointer_data.locked_pointer),
                 pointer_constraints: pointer_data.pointer_constraints.clone(),
                 latest_serial: pointer_data.latest_serial.clone(),
                 latest_enter_serial: pointer_data.latest_enter_serial.clone(),

src/platform_impl/linux/wayland/seat/pointer/mod.rs

@@ -11,6 +11,7 @@ use sctk::reexports::protocols::unstable::relative_pointer::v1::client::zwp_rela
 use sctk::reexports::protocols::unstable::relative_pointer::v1::client::zwp_relative_pointer_v1::ZwpRelativePointerV1;
 use sctk::reexports::protocols::unstable::pointer_constraints::v1::client::zwp_pointer_constraints_v1::{ZwpPointerConstraintsV1, Lifetime};
 use sctk::reexports::protocols::unstable::pointer_constraints::v1::client::zwp_confined_pointer_v1::ZwpConfinedPointerV1;
+use sctk::reexports::protocols::unstable::pointer_constraints::v1::client::zwp_locked_pointer_v1::ZwpLockedPointerV1;
 
 use sctk::seat::pointer::{ThemeManager, ThemedPointer};
 use sctk::window::Window;
@@ -35,9 +36,13 @@ pub struct WinitPointer {
     /// Cursor to handle confine requests.
     confined_pointer: Weak<RefCell<Option<ZwpConfinedPointerV1>>>,
 
+    /// Cursor to handle locked requests.
+    locked_pointer: Weak<RefCell<Option<ZwpLockedPointerV1>>>,
+
     /// Latest observed serial in pointer events.
     /// used by Window::start_interactive_move()
     latest_serial: Rc<Cell<u32>>,
+
     /// Latest observed serial in pointer enter events.
     /// used by Window::set_cursor()
     latest_enter_serial: Rc<Cell<u32>>,
@@ -157,6 +162,52 @@ impl WinitPointer {
         }
     }
 
+    pub fn lock(&self, surface: &WlSurface) {
+        let pointer_constraints = match &self.pointer_constraints {
+            Some(pointer_constraints) => pointer_constraints,
+            None => return,
+        };
+
+        let locked_pointer = match self.locked_pointer.upgrade() {
+            Some(locked_pointer) => locked_pointer,
+            // A pointer is gone.
+            None => return,
+        };
+
+        *locked_pointer.borrow_mut() = Some(init_locked_pointer(
+            pointer_constraints,
+            surface,
+            &*self.pointer,
+        ));
+    }
+
+    pub fn unlock(&self) {
+        let locked_pointer = match self.locked_pointer.upgrade() {
+            Some(locked_pointer) => locked_pointer,
+            // A pointer is gone.
+            None => return,
+        };
+
+        let mut locked_pointer = locked_pointer.borrow_mut();
+
+        if let Some(locked_pointer) = locked_pointer.take() {
+            locked_pointer.destroy();
+        }
+    }
+
+    pub fn set_cursor_position(&self, surface_x: u32, surface_y: u32) {
+        let locked_pointer = match self.locked_pointer.upgrade() {
+            Some(locked_pointer) => locked_pointer,
+            // A pointer is gone.
+            None => return,
+        };
+
+        let locked_pointer = locked_pointer.borrow_mut();
+        if let Some(locked_pointer) = locked_pointer.as_ref() {
+            locked_pointer.set_cursor_position_hint(surface_x.into(), surface_y.into());
+        }
+    }
+
     pub fn drag_window(&self, window: &Window<WinitFrame>) {
         // WlPointer::setart_interactive_move() expects the last serial of *any*
         // pointer event (compare to set_cursor()).
@@ -174,6 +225,9 @@ pub(super) struct Pointers {
 
     /// Confined pointer.
     confined_pointer: Rc<RefCell<Option<ZwpConfinedPointerV1>>>,
+
+    /// Locked pointer.
+    locked_pointer: Rc<RefCell<Option<ZwpLockedPointerV1>>>,
 }
 
 impl Pointers {
@@ -185,11 +239,15 @@ impl Pointers {
         modifiers_state: Rc<RefCell<ModifiersState>>,
     ) -> Self {
         let confined_pointer = Rc::new(RefCell::new(None));
+        let locked_pointer = Rc::new(RefCell::new(None));
+
         let pointer_data = Rc::new(RefCell::new(PointerData::new(
             confined_pointer.clone(),
+            locked_pointer.clone(),
             pointer_constraints.clone(),
             modifiers_state,
         )));
+
         let pointer_seat = seat.detach();
         let pointer = theme_manager.theme_pointer_with_impl(
             seat,
@@ -216,6 +274,7 @@ impl Pointers {
             pointer,
             relative_pointer,
             confined_pointer,
+            locked_pointer,
         }
     }
 }
@@ -232,6 +291,11 @@ impl Drop for Pointers {
             confined_pointer.destroy();
         }
 
+        // Drop lock ponter.
+        if let Some(locked_pointer) = self.locked_pointer.borrow_mut().take() {
+            locked_pointer.destroy();
+        }
+
         // Drop the pointer itself in case it's possible.
         if self.pointer.as_ref().version() >= 3 {
             self.pointer.release();
@@ -264,3 +328,16 @@ pub(super) fn init_confined_pointer(
 
     confined_pointer.detach()
 }
+
+pub(super) fn init_locked_pointer(
+    pointer_constraints: &Attached<ZwpPointerConstraintsV1>,
+    surface: &WlSurface,
+    pointer: &WlPointer,
+) -> ZwpLockedPointerV1 {
+    let locked_pointer =
+        pointer_constraints.lock_pointer(surface, pointer, None, Lifetime::Persistent);
+
+    locked_pointer.quick_assign(move |_, _, _| {});
+
+    locked_pointer.detach()
+}