macOS: add dynamic ApplicationHandlerExtMacOS::accepts_first_mouse

Add an `accepts_first_mouse` callback to `ApplicationHandlerExtMacOS`
that receives the window ID and click position, enabling per-click
decisions about whether to accept first mouse on inactive windows.

This is needed for applications that want to follow the macOS convention
of accepting first mouse for low-risk actions (selection, scrolling) but
rejecting it for buttons and destructive actions.

The implementation dispatches synchronously via a new
`EventHandler::handle_with_result` method. When the handler is
unavailable (not set or re-entrant), the static `accepts_first_mouse`
value from `WindowAttributes` is used as a fallback.

Author: tilladam

winit-appkit/src/app_state.rs

@@ -290,6 +290,21 @@ impl AppState {
         }
     }
 
+    /// Try to call the handler synchronously and return a result.
+    ///
+    /// Returns `None` if the handler is not set or is currently in use (re-entrant call).
+    #[track_caller]
+    pub fn try_with_handler_result<R>(
+        self: &Rc<Self>,
+        callback: impl FnOnce(&mut dyn ApplicationHandler, &ActiveEventLoop) -> R,
+    ) -> Option<R> {
+        let this = self;
+        self.event_handler.handle_with_result(|app| {
+            let event_loop = ActiveEventLoop { app_state: Rc::clone(this), mtm: this.mtm };
+            callback(app, &event_loop)
+        })
+    }
+
     #[track_caller]
     fn with_handler(
         self: &Rc<Self>,

winit-appkit/src/view.rs

@@ -4,7 +4,7 @@ use std::collections::{HashMap, VecDeque};
 use std::ptr;
 use std::rc::Rc;
 
-use dpi::{LogicalPosition, LogicalSize};
+use dpi::{LogicalPosition, LogicalSize, PhysicalPosition};
 use objc2::rc::Retained;
 use objc2::runtime::{AnyObject, Sel};
 use objc2::{DefinedClass, MainThreadMarker, define_class, msg_send};
@@ -781,9 +781,30 @@ define_class!(
         }
 
         #[unsafe(method(acceptsFirstMouse:))]
-        fn accepts_first_mouse(&self, _event: &NSEvent) -> bool {
+        fn accepts_first_mouse(&self, event: Option<&NSEvent>) -> bool {
             trace_scope!("acceptsFirstMouse:");
-            self.ivars().accepts_first_mouse
+            // The event parameter can be nil according to Apple's API contract.
+            // When nil, fall back to the static default.
+            event
+                .and_then(|event| {
+                    let window_id = window_id(&self.window());
+                    let point_in_window = event.locationInWindow();
+                    let point_in_view = self.convertPoint_fromView(point_in_window, None);
+                    let scale_factor = self.scale_factor();
+                    let position = PhysicalPosition::new(
+                        point_in_view.x * scale_factor,
+                        point_in_view.y * scale_factor,
+                    );
+                    self.ivars()
+                        .app_state
+                        .try_with_handler_result(move |app, event_loop| {
+                            app.macos_handler().map(|h| {
+                                h.accepts_first_mouse(event_loop, window_id, position)
+                            })
+                        })
+                        .flatten()
+                })
+                .unwrap_or(self.ivars().accepts_first_mouse)
         }
     }
 );

winit-common/src/event_handler.rs

@@ -112,24 +112,39 @@ impl EventHandler {
         matches!(self.inner.try_borrow().as_deref(), Ok(Some(_)))
     }
 
-    pub fn handle(&self, callback: impl FnOnce(&mut (dyn ApplicationHandler + '_))) {
+    /// Try to call the handler and return a value.
+    ///
+    /// Returns `None` if the handler is not set or is currently in use (re-entrant call).
+    ///
+    /// It is important that we keep the `RefMut` borrowed during the callback, so that `in_use`
+    /// can properly detect that the handler is still in use. If the handler unwinds, the `RefMut`
+    /// will ensure that the handler is no longer borrowed.
+    pub fn handle_with_result<R>(
+        &self,
+        callback: impl FnOnce(&mut (dyn ApplicationHandler + '_)) -> R,
+    ) -> Option<R> {
         match self.inner.try_borrow_mut().as_deref_mut() {
-            Ok(Some(user_app)) => {
-                // It is important that we keep the reference borrowed here,
-                // so that `in_use` can properly detect that the handler is
-                // still in use.
-                //
-                // If the handler unwinds, the `RefMut` will ensure that the
-                // handler is no longer borrowed.
-                callback(&mut **user_app);
-            },
+            Ok(Some(user_app)) => Some(callback(&mut **user_app)),
             Ok(None) => {
-                // `NSApplication`, our app state and this handler are all
-                // global state and so it's not impossible that we could get
-                // an event after the application has exited the `EventLoop`.
+                // `NSApplication`, our app state and this handler are all global state and so
+                // it's not impossible that we could get an event after the application has
+                // exited the `EventLoop`.
                 tracing::error!("tried to run event handler, but no handler was set");
+                None
             },
             Err(_) => {
+                // Handler is currently in use, return None instead of panicking.
+                None
+            },
+        }
+    }
+
+    pub fn handle(&self, callback: impl FnOnce(&mut (dyn ApplicationHandler + '_))) {
+        match self.handle_with_result(callback) {
+            Some(()) => {},
+            // Handler not set — already logged by handle_with_result.
+            None if !self.in_use() => {},
+            None => {
                 // Prevent re-entrancy.
                 panic!("tried to handle event while another event is currently being handled");
             },
@@ -153,3 +168,80 @@ impl EventHandler {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use winit_core::application::ApplicationHandler;
+    use winit_core::event::WindowEvent;
+    use winit_core::event_loop::ActiveEventLoop;
+    use winit_core::window::WindowId;
+
+    use super::EventHandler;
+
+    struct DummyApp;
+
+    impl ApplicationHandler for DummyApp {
+        fn can_create_surfaces(&mut self, _event_loop: &dyn ActiveEventLoop) {}
+
+        fn window_event(
+            &mut self,
+            _event_loop: &dyn ActiveEventLoop,
+            _window_id: WindowId,
+            _event: WindowEvent,
+        ) {
+        }
+    }
+
+    #[test]
+    fn handle_with_result_returns_value() {
+        let handler = EventHandler::new();
+        handler.set(Box::new(DummyApp), || {
+            let result = handler.handle_with_result(|_app| 42);
+            assert_eq!(result, Some(42));
+        });
+    }
+
+    #[test]
+    fn handle_with_result_returns_none_when_not_set() {
+        let handler = EventHandler::new();
+        let result = handler.handle_with_result(|_app| 42);
+        assert_eq!(result, None);
+    }
+
+    #[test]
+    fn handle_with_result_returns_none_when_in_use() {
+        let handler = EventHandler::new();
+        handler.set(Box::new(DummyApp), || {
+            // Borrow the handler via `handle`, then try `handle_with_result`
+            // from within — simulating re-entrancy.
+            handler.handle(|_app| {
+                let result = handler.handle_with_result(|_app| 42);
+                assert_eq!(result, None);
+            });
+        });
+    }
+
+    #[test]
+    fn handle_with_result_returns_none_when_reentrant_through_self() {
+        let handler = EventHandler::new();
+        handler.set(Box::new(DummyApp), || {
+            let result = handler.handle_with_result(|_app| {
+                // Re-entrant call through handle_with_result itself.
+                handler.handle_with_result(|_app| 42)
+            });
+            assert_eq!(result, Some(None));
+        });
+    }
+
+    #[test]
+    #[should_panic(expected = "tried to handle event while another event is currently being handled")]
+    fn handle_panics_on_reentrant_call() {
+        let handler = EventHandler::new();
+        handler.set(Box::new(DummyApp), || {
+            handler.handle(|_app| {
+                // Re-entrant handle must still panic after the refactoring.
+                handler.handle(|_app| {});
+            });
+        });
+    }
+}

winit-core/src/application/macos.rs

@@ -1,3 +1,5 @@
+use dpi::PhysicalPosition;
+
 use crate::application::ApplicationHandler;
 use crate::event_loop::ActiveEventLoop;
 use crate::window::WindowId;
@@ -49,4 +51,30 @@ pub trait ApplicationHandlerExtMacOS: ApplicationHandler {
         let _ = window_id;
         let _ = action;
     }
+
+    /// Called when the user clicks on an inactive window to determine whether the click should
+    /// also be processed as a normal mouse event.
+    ///
+    /// This corresponds to the [`acceptsFirstMouse:`] method on `NSView`, which receives the
+    /// triggering mouse event. Winit extracts the click position from that event and passes it
+    /// here so that the application can make per-click decisions, e.g. accept first mouse for
+    /// low-risk actions (selection, scrolling) but reject it for buttons or destructive actions.
+    ///
+    /// The default implementation returns `true`.
+    ///
+    /// If this method cannot be called synchronously (e.g. the handler is already in use), the
+    /// static `accepts_first_mouse` value from
+    /// [`WindowAttributes`][crate::window::WindowAttributes] is used as a fallback.
+    ///
+    /// [`acceptsFirstMouse:`]: https://developer.apple.com/documentation/appkit/nsview/acceptsfirstmouse(_:)
+    #[doc(alias = "acceptsFirstMouse:")]
+    fn accepts_first_mouse(
+        &mut self,
+        event_loop: &dyn ActiveEventLoop,
+        window_id: WindowId,
+        position: PhysicalPosition<f64>,
+    ) -> bool {
+        let _ = (event_loop, window_id, position);
+        true
+    }
 }

winit/src/changelog/unreleased.md

@@ -44,6 +44,7 @@ changelog entry.
 
 - Add `keyboard` support for OpenHarmony.
 - On iOS, add Apple Pencil support with force, altitude, and azimuth data.
+- On macOS, add `ApplicationHandlerExtMacOS::accepts_first_mouse` for dynamic per-click decisions.
 
 ### Changed