Introduce FingerId (rust-windowing#3783)

src/changelog/unreleased.md

@@ -56,6 +56,9 @@ changelog entry.
   well.
 - On Android, add `{Active,}EventLoopExtAndroid::android_app()` to access the app used to create the loop.
 - Add `ActiveEventLoop::system_theme()`, returning the current system theme.
+- Add `Touch::finger_id` with a new type `FingerId`.
+- On Web and Windows, add `FingerIdExt*::is_primary()`, exposing a way to determine
+  the primary finger in a multi-touch interaction.
 
 ### Changed
 
@@ -110,6 +113,7 @@ changelog entry.
   v0.5 support. v0.6 remains in place and is enabled by default.
 - Remove `DeviceEvent::Added` and `DeviceEvent::Removed`.
 - Remove `DeviceEvent::Motion` and `WindowEvent::AxisMotion`.
+- Remove `Touch::id` in favor of `Touch::finger_id`.
 
 ### Fixed
 

src/event.rs

@@ -447,6 +447,26 @@ impl DeviceId {
     }
 }
 
+/// Identifier of a finger in a touch event.
+///
+/// Whenever a touch event is received it contains a `FingerId` which uniquely identifies the finger
+/// used for the current interaction.
+#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct FingerId(pub(crate) platform_impl::FingerId);
+
+impl FingerId {
+    /// Returns a dummy id, useful for unit testing.
+    ///
+    /// # Notes
+    ///
+    /// The only guarantee made about the return value of this function is that
+    /// it will always be equal to itself and to future values returned by this function.
+    /// No other guarantees are made. This may be equal to a real `FingerId`.
+    pub const fn dummy() -> Self {
+        FingerId(platform_impl::FingerId::dummy())
+    }
+}
+
 /// Represents raw hardware events that are not associated with any particular window.
 ///
 /// Useful for interactions that diverge significantly from a conventional 2D GUI, such as 3D camera
@@ -846,7 +866,7 @@ pub struct Touch {
     ///   [android documentation](https://developer.android.com/reference/android/view/MotionEvent#AXIS_PRESSURE).
     pub force: Option<Force>,
     /// Unique identifier of a finger.
-    pub id: u64,
+    pub finger_id: FingerId,
 }
 
 /// Describes the force of a touch event
@@ -1012,6 +1032,7 @@ mod tests {
             #[allow(unused_mut)]
             let mut x = $closure;
             let did = event::DeviceId::dummy();
+            let fid = event::FingerId::dummy();
 
             #[allow(deprecated)]
             {
@@ -1075,7 +1096,7 @@ mod tests {
                     device_id: did,
                     phase: event::TouchPhase::Started,
                     location: (0.0, 0.0).into(),
-                    id: 0,
+                    finger_id: fid,
                     force: Some(event::Force::Normalized(0.0)),
                 }));
                 with_window_event(ThemeChanged(crate::window::Theme::Light));
@@ -1133,6 +1154,7 @@ mod tests {
         let _ = event::StartCause::Init.clone();
 
         let did = crate::event::DeviceId::dummy().clone();
+        let fid = crate::event::FingerId::dummy().clone();
         HashSet::new().insert(did);
         let mut set = [did, did, did];
         set.sort_unstable();
@@ -1148,7 +1170,7 @@ mod tests {
             device_id: did,
             phase: event::TouchPhase::Started,
             location: (0.0, 0.0).into(),
-            id: 0,
+            finger_id: fid,
             force: Some(event::Force::Normalized(0.0)),
         }
         .clone();

src/platform/web.rs

@@ -56,6 +56,7 @@ use web_sys::HtmlCanvasElement;
 use crate::application::ApplicationHandler;
 use crate::cursor::CustomCursorSource;
 use crate::error::NotSupportedError;
+use crate::event::FingerId;
 use crate::event_loop::{ActiveEventLoop, EventLoop};
 use crate::monitor::MonitorHandle;
 use crate::platform_impl::PlatformCustomCursorSource;
@@ -763,3 +764,16 @@ impl Display for OrientationLockError {
 }
 
 impl Error for OrientationLockError {}
+
+/// Additional methods on [`FingerId`] that are specific to Web.
+pub trait FingerIdExtWeb {
+    /// Indicates if the finger represents the first contact in a multi-touch interaction.
+    #[allow(clippy::wrong_self_convention)]
+    fn is_primary(self) -> bool;
+}
+
+impl FingerIdExtWeb for FingerId {
+    fn is_primary(self) -> bool {
+        self.0.is_primary()
+    }
+}

src/platform/windows.rs

@@ -7,7 +7,7 @@ use std::ffi::c_void;
 use std::path::Path;
 
 use crate::dpi::PhysicalSize;
-use crate::event::DeviceId;
+use crate::event::{DeviceId, FingerId};
 use crate::event_loop::EventLoopBuilder;
 use crate::monitor::MonitorHandle;
 use crate::window::{BadIcon, Icon, Window, WindowAttributes};
@@ -668,6 +668,20 @@ impl DeviceIdExtWindows for DeviceId {
     }
 }
 
+/// Additional methods on `FingerId` that are specific to Windows.
+pub trait FingerIdExtWindows {
+    /// Indicates if the finger represents the first contact in a multi-touch interaction.
+    #[allow(clippy::wrong_self_convention)]
+    fn is_primary(self) -> bool;
+}
+
+impl FingerIdExtWindows for FingerId {
+    #[inline]
+    fn is_primary(self) -> bool {
+        self.0.is_primary()
+    }
+}
+
 /// Additional methods on `Icon` that are specific to Windows.
 pub trait IconExtWindows: Sized {
     /// Create an icon from a file path.

src/platform_impl/android/mod.rs

@@ -359,7 +359,7 @@ impl EventLoop {
                             device_id,
                             phase,
                             location,
-                            id: pointer.pointer_id() as u64,
+                            finger_id: event::FingerId(FingerId(pointer.pointer_id())),
                             force: Some(Force::Normalized(pointer.pressure() as f64)),
                         });
 
@@ -705,6 +705,15 @@ impl DeviceId {
     }
 }
 
+#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+pub struct FingerId(i32);
+
+impl FingerId {
+    pub const fn dummy() -> Self {
+        FingerId(0)
+    }
+}
+
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
 pub struct PlatformSpecificWindowAttributes;
 

src/platform_impl/apple/appkit/mod.rs

@@ -43,6 +43,15 @@ impl DeviceId {
 // Constant device ID; to be removed when if backend is updated to report real device IDs.
 pub(crate) const DEVICE_ID: RootDeviceId = RootDeviceId(DeviceId);
 
+#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct FingerId;
+
+impl FingerId {
+    pub const fn dummy() -> Self {
+        FingerId
+    }
+}
+
 #[derive(Debug)]
 pub enum OsError {
     CGError(core_graphics::base::CGError),

src/platform_impl/apple/uikit/mod.rs

@@ -38,6 +38,15 @@ impl DeviceId {
 
 pub(crate) const DEVICE_ID: RootDeviceId = RootDeviceId(DeviceId);
 
+#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct FingerId(usize);
+
+impl FingerId {
+    pub const fn dummy() -> Self {
+        FingerId(0)
+    }
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct KeyEventExtra {}
 

src/platform_impl/apple/uikit/view.rs

@@ -14,9 +14,9 @@ use objc2_ui_kit::{
 
 use super::app_state::{self, EventWrapper};
 use super::window::WinitUIWindow;
-use super::DEVICE_ID;
+use super::{FingerId, DEVICE_ID};
 use crate::dpi::PhysicalPosition;
-use crate::event::{Event, Force, Touch, TouchPhase, WindowEvent};
+use crate::event::{Event, FingerId as RootFingerId, Force, Touch, TouchPhase, WindowEvent};
 use crate::window::{WindowAttributes, WindowId as RootWindowId};
 
 pub struct WinitViewState {
@@ -480,7 +480,7 @@ impl WinitView {
             } else {
                 None
             };
-            let touch_id = touch as *const UITouch as u64;
+            let touch_id = touch as *const UITouch as usize;
             let phase = touch.phase();
             let phase = match phase {
                 UITouchPhase::Began => TouchPhase::Started,
@@ -502,7 +502,7 @@ impl WinitView {
                 window_id: RootWindowId(window.id()),
                 event: WindowEvent::Touch(Touch {
                     device_id: DEVICE_ID,
-                    id: touch_id,
+                    finger_id: RootFingerId(FingerId(touch_id)),
                     location: physical_location,
                     force,
                     phase,

src/platform_impl/linux/mod.rs

@@ -177,6 +177,23 @@ impl DeviceId {
     }
 }
 
+#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum FingerId {
+    #[cfg(x11_platform)]
+    X(x11::FingerId),
+    #[cfg(wayland_platform)]
+    Wayland(wayland::FingerId),
+}
+
+impl FingerId {
+    pub const fn dummy() -> Self {
+        #[cfg(wayland_platform)]
+        return FingerId::Wayland(wayland::FingerId::dummy());
+        #[cfg(all(not(wayland_platform), x11_platform))]
+        return FingerId::X(x11::FingerId::dummy());
+    }
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub enum MonitorHandle {
     #[cfg(x11_platform)]

src/platform_impl/linux/wayland/mod.rs

@@ -71,6 +71,15 @@ impl DeviceId {
     }
 }
 
+#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct FingerId(i32);
+
+impl FingerId {
+    pub const fn dummy() -> Self {
+        FingerId(0)
+    }
+}
+
 /// Get the WindowId out of the surface.
 #[inline]
 fn make_wid(surface: &WlSurface) -> WindowId {

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

@@ -10,7 +10,7 @@ use tracing::warn;
 use crate::dpi::LogicalPosition;
 use crate::event::{Touch, TouchPhase, WindowEvent};
 use crate::platform_impl::wayland::state::WinitState;
-use crate::platform_impl::wayland::{self, DeviceId};
+use crate::platform_impl::wayland::{self, DeviceId, FingerId};
 
 impl TouchHandler for WinitState {
     fn down(
@@ -50,7 +50,9 @@ impl TouchHandler for WinitState {
                 phase: TouchPhase::Started,
                 location: location.to_physical(scale_factor),
                 force: None,
-                id: id as u64,
+                finger_id: crate::event::FingerId(crate::platform_impl::FingerId::Wayland(
+                    FingerId(id),
+                )),
             }),
             window_id,
         );
@@ -93,7 +95,9 @@ impl TouchHandler for WinitState {
                 phase: TouchPhase::Ended,
                 location: touch_point.location.to_physical(scale_factor),
                 force: None,
-                id: id as u64,
+                finger_id: crate::event::FingerId(crate::platform_impl::FingerId::Wayland(
+                    FingerId(id),
+                )),
             }),
             window_id,
         );
@@ -138,7 +142,9 @@ impl TouchHandler for WinitState {
                 phase: TouchPhase::Moved,
                 location: touch_point.location.to_physical(scale_factor),
                 force: None,
-                id: id as u64,
+                finger_id: crate::event::FingerId(crate::platform_impl::FingerId::Wayland(
+                    FingerId(id),
+                )),
             }),
             window_id,
         );
@@ -170,7 +176,9 @@ impl TouchHandler for WinitState {
                     phase: TouchPhase::Cancelled,
                     location,
                     force: None,
-                    id: id as u64,
+                    finger_id: crate::event::FingerId(crate::platform_impl::FingerId::Wayland(
+                        FingerId(id),
+                    )),
                 }),
                 window_id,
             );

src/platform_impl/linux/x11/event_processor.rs

@@ -33,8 +33,8 @@ use crate::platform_impl::platform::x11::ActiveEventLoop;
 use crate::platform_impl::x11::atoms::*;
 use crate::platform_impl::x11::util::cookie::GenericEventCookie;
 use crate::platform_impl::x11::{
-    mkdid, mkwid, util, CookieResultExt, Device, DeviceId, DeviceInfo, Dnd, DndState, ImeReceiver,
-    ScrollOrientation, UnownedWindow, WindowId,
+    mkdid, mkfid, mkwid, util, CookieResultExt, Device, DeviceId, DeviceInfo, Dnd, DndState,
+    ImeReceiver, ScrollOrientation, UnownedWindow, WindowId,
 };
 
 /// The maximum amount of X modifiers to replay.
@@ -60,7 +60,7 @@ pub struct EventProcessor {
     //
     // Used to detect key repeats.
     pub held_key_press: Option<u32>,
-    pub first_touch: Option<u64>,
+    pub first_touch: Option<u32>,
     // Currently focused window belonging to this process
     pub active_window: Option<xproto::Window>,
     /// Latest modifiers we've sent for the user to trigger change in event.
@@ -1313,7 +1313,7 @@ impl EventProcessor {
         let window = xev.event as xproto::Window;
         if self.window_exists(window) {
             let window_id = mkwid(window);
-            let id = xev.detail as u64;
+            let id = xev.detail as u32;
             let location = PhysicalPosition::new(xev.event_x, xev.event_y);
 
             // Mouse cursor position changes when touch events are received.
@@ -1336,7 +1336,7 @@ impl EventProcessor {
                     phase,
                     location,
                     force: None, // TODO
-                    id,
+                    finger_id: mkfid(id),
                 }),
             };
             callback(&self.target, event)
@@ -1761,7 +1761,7 @@ impl EventProcessor {
     }
 }
 
-fn is_first_touch(first: &mut Option<u64>, num: &mut u32, id: u64, phase: TouchPhase) -> bool {
+fn is_first_touch(first: &mut Option<u32>, num: &mut u32, id: u32, phase: TouchPhase) -> bool {
     match phase {
         TouchPhase::Started => {
             if *num == 0 {

src/platform_impl/linux/x11/mod.rs

@@ -822,6 +822,16 @@ impl DeviceId {
     }
 }
 
+#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct FingerId(u32);
+
+impl FingerId {
+    #[allow(unused)]
+    pub const fn dummy() -> Self {
+        FingerId(0)
+    }
+}
+
 pub(crate) struct Window(Arc<UnownedWindow>);
 
 impl Deref for Window {
@@ -1027,6 +1037,10 @@ fn mkdid(w: xinput::DeviceId) -> crate::event::DeviceId {
     crate::event::DeviceId(crate::platform_impl::DeviceId::X(DeviceId(w)))
 }
 
+fn mkfid(w: u32) -> crate::event::FingerId {
+    crate::event::FingerId(crate::platform_impl::FingerId::X(FingerId(w)))
+}
+
 #[derive(Debug)]
 pub struct Device {
     _name: String,