Revise MouseButton type: enum -> struct

dhardy · dhardy · commit 0f3f8c2782c4 · 2025-09-08T15:39:13.000+01:00
diff --git a/winit-appkit/src/view.rs b/winit-appkit/src/view.rs
@@ -1096,14 +1096,11 @@ fn mouse_button(event: &NSEvent) -> MouseButton {
     // For the other events, it's always set to 0.
     // MacOS only defines the left, right and middle buttons, 3..=31 are left as generic buttons,
     // but 3 and 4 are very commonly used as Back and Forward by hardware vendors and applications.
-    match unsafe { event.buttonNumber() } {
-        0 => MouseButton::Left,
-        1 => MouseButton::Right,
-        2 => MouseButton::Middle,
-        3 => MouseButton::Back,
-        4 => MouseButton::Forward,
-        n => MouseButton::Other(n as u16),
-    }
+    let b: isize = unsafe { event.buttonNumber() };
+    b.try_into()
+        .ok()
+        .and_then(MouseButton::try_from_u8)
+        .expect("expected MacOS button number in the range 0..=31")
 }
 
 // NOTE: to get option as alt working we need to rewrite events
diff --git a/winit-core/src/event.rs b/winit-core/src/event.rs
@@ -521,14 +521,14 @@ pub enum ButtonSource {
 }
 
 impl ButtonSource {
-    /// Convert any [`ButtonSource`] to an equivalent [`MouseButton`]. If a pointer type has no
+    /// Try to convert a [`ButtonSource`] to an equivalent [`MouseButton`]. If a pointer type has no
     /// special handling in an application, this method can be used to handle it like any generic
     /// mouse input.
-    pub fn mouse_button(self) -> MouseButton {
+    pub fn mouse_button(self) -> Option<MouseButton> {
         match self {
-            ButtonSource::Mouse(mouse) => mouse,
-            ButtonSource::Touch { .. } => MouseButton::Left,
-            ButtonSource::Unknown(code) => MouseButton::Other(code),
+            ButtonSource::Mouse(mouse) => Some(mouse),
+            ButtonSource::Touch { .. } => Some(MouseButton::Left),
+            ButtonSource::Unknown(_) => None,
         }
     }
 }
@@ -1037,21 +1037,113 @@ impl ElementState {
     }
 }
 
-/// Describes a button of a mouse controller.
+/// Identifies a button of a mouse controller.
 ///
 /// ## Platform-specific
 ///
-/// **macOS:** `Back` and `Forward` might not work with all hardware.
-/// **Orbital:** `Back` and `Forward` are unsupported due to orbital not supporting them.
+/// The first three buttons should be supported on all platforms.
+/// [`Self::Back`] and [`Self::Forward`] are supported on most platforms
+/// (when using a compatible mouse).
+///
+/// - **Android, iOS:** Currently not supported.
+/// - **Orbital:** Only left/right/middle buttons are supported at this time.
+/// - **Web, Windows:** Supports left/right/middle/back/forward buttons.
+/// - **Wayland:** Supports buttons 0..=15.
+/// - **macOS, X11:** Supports all button variants.
+/// - **X11:** Supports buttons 0..=250.
 #[derive(Debug, Hash, PartialEq, Eq, PartialOrd, Ord, Clone, Copy)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[repr(u8)]
 pub enum MouseButton {
-    Left,
-    Right,
-    Middle,
-    Back,
-    Forward,
-    Other(u16),
+    /// The primary (usually left) button
+    Left = 0,
+    /// The secondary (usually right) button
+    Right = 1,
+    /// The tertiary (usually middle) button
+    Middle = 2,
+    /// The first side button, frequently assigned a back function
+    Back = 3,
+    /// The second side button, frequently assigned a forward function
+    Forward = 4,
+    /// The sixth button
+    Button5 = 5,
+    /// The seventh button
+    Button6 = 6,
+    /// The eighth button
+    Button7 = 7,
+    /// The ninth button
+    Button8 = 8,
+    /// The tenth button
+    Button9 = 9,
+    /// The eleventh button
+    Button10 = 10,
+    /// The twelfth button
+    Button11 = 11,
+    /// The thirteenth button
+    Button12 = 12,
+    /// The fourteenth button
+    Button13 = 13,
+    /// The fifteenth button
+    Button14 = 14,
+    /// The sixteenth button
+    Button15 = 15,
+    Button16 = 16,
+    Button17 = 17,
+    Button18 = 18,
+    Button19 = 19,
+    Button20 = 20,
+    Button21 = 21,
+    Button22 = 22,
+    Button23 = 23,
+    Button24 = 24,
+    Button25 = 25,
+    Button26 = 26,
+    Button27 = 27,
+    Button28 = 28,
+    Button29 = 29,
+    Button30 = 30,
+    Button31 = 31,
+}
+
+impl MouseButton {
+    /// Construct from a `u8` if within the range `0..=31`
+    pub fn try_from_u8(b: u8) -> Option<MouseButton> {
+        Some(match b {
+            0 => MouseButton::Left,
+            1 => MouseButton::Right,
+            2 => MouseButton::Middle,
+            3 => MouseButton::Back,
+            4 => MouseButton::Forward,
+            5 => MouseButton::Button5,
+            6 => MouseButton::Button6,
+            7 => MouseButton::Button7,
+            8 => MouseButton::Button8,
+            9 => MouseButton::Button9,
+            10 => MouseButton::Button10,
+            11 => MouseButton::Button11,
+            12 => MouseButton::Button12,
+            13 => MouseButton::Button13,
+            14 => MouseButton::Button14,
+            15 => MouseButton::Button15,
+            16 => MouseButton::Button16,
+            17 => MouseButton::Button17,
+            18 => MouseButton::Button18,
+            19 => MouseButton::Button19,
+            20 => MouseButton::Button20,
+            21 => MouseButton::Button21,
+            22 => MouseButton::Button22,
+            23 => MouseButton::Button23,
+            24 => MouseButton::Button24,
+            25 => MouseButton::Button25,
+            26 => MouseButton::Button26,
+            27 => MouseButton::Button27,
+            28 => MouseButton::Button28,
+            29 => MouseButton::Button29,
+            30 => MouseButton::Button30,
+            31 => MouseButton::Button31,
+            _ => return None,
+        })
+    }
 }
 
 /// Describes a difference in the mouse scroll wheel state.
@@ -1184,7 +1276,7 @@ mod tests {
                 primary: true,
                 state: event::ElementState::Pressed,
                 position: (0, 0).into(),
-                button: event::MouseButton::Other(0).into(),
+                button: event::ButtonSource::Unknown(0),
             });
             with_window_event(PointerButton {
                 device_id: None,
diff --git a/winit-wayland/src/seat/pointer/mod.rs b/winit-wayland/src/seat/pointer/mod.rs
@@ -404,22 +404,14 @@ impl Default for WinitPointerDataInner {
 /// Convert the Wayland button into winit.
 fn wayland_button_to_winit(button: u32) -> ButtonSource {
     // These values are coming from <linux/input-event-codes.h>.
-    const BTN_LEFT: u32 = 0x110;
-    const BTN_RIGHT: u32 = 0x111;
-    const BTN_MIDDLE: u32 = 0x112;
-    const BTN_SIDE: u32 = 0x113;
-    const BTN_EXTRA: u32 = 0x114;
-
-    match button {
-        BTN_LEFT => MouseButton::Left.into(),
-        BTN_RIGHT => MouseButton::Right.into(),
-        BTN_MIDDLE => MouseButton::Middle.into(),
-        // Note that apps routinely handle BTN_SIDE/BTN_EXTRA as back/forward
-        BTN_SIDE => MouseButton::Back.into(),
-        BTN_EXTRA => MouseButton::Forward.into(),
-        // Skip named buttons (0..=4); map others to 5..
-        b @ 0x110..=0x11f => MouseButton::Other((b - 0x110) as u16).into(),
-        other => ButtonSource::Unknown(other as u16),
+    const BTN_MOUSE: u32 = 0x110;
+    const BTN_JOYSTICK: u32 = 0x120;
+
+    if (BTN_MOUSE..BTN_JOYSTICK).contains(&button) {
+        // Mapping orders match
+        MouseButton::try_from_u8((button - BTN_MOUSE) as u8).unwrap().into()
+    } else {
+        ButtonSource::Unknown(button as u16)
     }
 }
 
diff --git a/winit-win32/src/event_loop.rs b/winit-win32/src/event_loop.rs
@@ -1775,7 +1775,7 @@ unsafe fn public_window_callback_inner(
 
         WM_XBUTTONDOWN => {
             use winit_core::event::ElementState::Pressed;
-            use winit_core::event::MouseButton::{Back, Forward, Other};
+            use winit_core::event::MouseButton;
             use winit_core::event::WindowEvent::PointerButton;
             let xbutton = util::get_xbutton_wparam(wparam as u32);
 
@@ -1787,25 +1787,25 @@ unsafe fn public_window_callback_inner(
             let y = util::get_y_lparam(lparam as u32) as i32;
             let position = PhysicalPosition::new(x as f64, y as f64);
 
+            // 1 is defined as back, 2 as forward; other codes are unexpected.
+            let b = xbutton as u8 + MouseButton::Back as u8 - 1;
+
             userdata.send_window_event(window, PointerButton {
                 device_id: None,
                 primary: true,
                 state: Pressed,
                 position,
-                button: match xbutton {
-                    1 => Back,
-                    2 => Forward,
-                    _ => Other(xbutton),
-                }
-                .into(),
+                // 1 is defined as back, 2 as forward; other codes are unexpected.
+                button: MouseButton::try_from_u8(b).unwrap().into(),
             });
             result = ProcResult::Value(0);
         },
 
         WM_XBUTTONUP => {
             use winit_core::event::ElementState::Released;
-            use winit_core::event::MouseButton::{Back, Forward, Other};
+            use winit_core::event::MouseButton;
             use winit_core::event::WindowEvent::PointerButton;
+
             let xbutton = util::get_xbutton_wparam(wparam as u32);
 
             unsafe { release_mouse(userdata.window_state_lock()) };
@@ -1816,17 +1816,16 @@ unsafe fn public_window_callback_inner(
             let y = util::get_y_lparam(lparam as u32) as i32;
             let position = PhysicalPosition::new(x as f64, y as f64);
 
+            // 1 is defined as back, 2 as forward; other codes are unexpected.
+            let b = xbutton as u8 + MouseButton::Back as u8 - 1;
+
             userdata.send_window_event(window, PointerButton {
                 device_id: None,
                 primary: true,
                 state: Released,
                 position,
-                button: match xbutton {
-                    1 => Back,
-                    2 => Forward,
-                    _ => Other(xbutton),
-                }
-                .into(),
+                // 1 is defined as back, 2 as forward; other codes are unexpected.
+                button: MouseButton::try_from_u8(b).unwrap().into(),
             });
             result = ProcResult::Value(0);
         },
diff --git a/winit-x11/src/event_processor.rs b/winit-x11/src/event_processor.rs
@@ -996,7 +996,6 @@ impl EventProcessor {
                 position,
                 button: MouseButton::Middle.into(),
             },
-
             xlib::Button3 => WindowEvent::PointerButton {
                 device_id,
                 primary: true,
@@ -1020,28 +1019,23 @@ impl EventProcessor {
                 },
                 phase: TouchPhase::Moved,
             },
-            8 => WindowEvent::PointerButton {
-                device_id,
-                primary: true,
-                state,
-                position,
-                button: MouseButton::Back.into(),
-            },
 
-            9 => WindowEvent::PointerButton {
+            x @ 8..37 => WindowEvent::PointerButton {
                 device_id,
                 primary: true,
                 state,
                 position,
-                button: MouseButton::Forward.into(),
+                // Button 8 maps to MouseButton::BACK = 3; 36 maps to MouseButton::Button::Button31.
+                // 255 is the largest code yielded on X11 (tested).
+                button: MouseButton::try_from_u8((x - 5) as u8).unwrap().into(),
             },
-            x @ 10..=0xffff => WindowEvent::PointerButton {
+            x @ 37..=0xff => WindowEvent::PointerButton {
                 device_id,
                 primary: true,
                 state,
                 position,
-                // Skip named buttons (0..=4), map 10 to 5, 11 to 6, ...
-                button: MouseButton::Other((x - 5) as u16).into(),
+                // 255 is the largest code yielded on X11 (tested).
+                button: ButtonSource::Unknown(x as u16),
             },
             _ => return,
         };
diff --git a/winit/examples/application.rs b/winit/examples/application.rs
@@ -3,6 +3,7 @@
 //! Note that a real application accepting text input **should** support
 //! the IME interface. See the `ime` example.
 
+use std::borrow::Cow;
 use std::collections::HashMap;
 use std::error::Error;
 use std::fmt::Debug;
@@ -485,8 +486,9 @@ impl ApplicationHandler for Application {
                 let mods = window.modifiers;
                 if let Some(action) = state
                     .is_pressed()
-                    .then(|| Self::process_mouse_binding(button.mouse_button(), &mods))
+                    .then(|| button.mouse_button())
                     .flatten()
+                    .and_then(|button| Self::process_mouse_binding(button, &mods))
                 {
                     self.handle_action_with_window(event_loop, window_id, action);
                 }
@@ -1145,15 +1147,16 @@ fn modifiers_to_string(mods: ModifiersState) -> String {
     mods_line
 }
 
-fn mouse_button_to_string(button: MouseButton) -> &'static str {
+fn mouse_button_to_string(button: MouseButton) -> Cow<'static, str> {
     match button {
         MouseButton::Left => "LMB",
         MouseButton::Right => "RMB",
         MouseButton::Middle => "MMB",
         MouseButton::Back => "Back",
         MouseButton::Forward => "Forward",
-        MouseButton::Other(_) => "",
+        other => return format!("button {}", other as u8 + 1).into(),
     }
+    .into()
 }
 
 #[cfg(web_platform)]
