macOS: add dynamic accepts_first_mouse callback

[tilladam]

Summary

• Add ApplicationHandlerExtMacOS::accepts_first_mouse callback that receives the window ID and click position (PhysicalPosition<f64>), enabling per-click decisions about whether to accept first mouse on inactive windows.
• Add EventHandler::handle_with_result for synchronous, re-entrant-safe handler dispatch that returns Option<R>. Refactor existing handle on top of it to eliminate duplication.
• When the handler is unavailable (not set or re-entrant), the static accepts_first_mouse value from WindowAttributes is used as a fallback.

Motivated by slint-ui/slint#10451 — applications need per-click decisions to follow the macOS convention of accepting first mouse for low-risk actions (selection, scrolling) but rejecting it for buttons and destructive actions.

Implementation notes

• acceptsFirstMouse: must return bool synchronously, so the handler is called via handle_with_result which returns None on re-entrancy instead of panicking.
• The NSEvent parameter is Option<&NSEvent> per Apple's API contract (can be nil); nil falls back to the static default.
• Coordinates use the same conversion as existing mouse event handlers (convertPoint_fromView + scale factor), with isFlipped providing top-left origin.

Test plan

• cargo build -p winit-core / winit-appkit / winit — compiles
• cargo test -p winit-core — passes
• cargo test -p winit-common --features event-handler — 5 new tests pass:
  • handle_with_result returns value (normal path)
  • handle_with_result returns None when handler not set
  • handle_with_result returns None on re-entrancy via handle
  • handle_with_result returns None on re-entrancy via itself
  • handle still panics on re-entrancy (regression test)
• cargo clippy -p winit-appkit — no warnings
• cargo +nightly fmt -- --check — clean

[madsmtm]

Thanks for the PR, and sorry for being slow to get back to it, the continuos rebases helped ;)

[madsmtm]

When is acceptsFirstMouse: called by AppKit? If it's only done when responding to events from the OS, and not in e.g. methods like Window::set_title() or whatever, maybe it'd make sense to warn if we had a fn accepts_first_mouse, but couldn't call it?

[tilladam]

`acceptsFirstMouse:` is only called by AppKit in response to mouse-down events on an inactive window — not from programmatic calls like `set_title()`. Added a warning in 7ea93ef for the case where the handler can't be called synchronously (re-entrancy); it logs before falling back to the static value.

[madsmtm]

Nit: Makes no sense to talk about "after the refactoring" in a code comment

[tilladam]

Fixed in 959c126.

[madsmtm]

Hmm, but that'd mean that by returning Some(self) in macos_handler, you overwrite WindowAttributesMacOS.accepts_first_mouse?

[tilladam]

Good point — I've clarified the docs in 6cf8480 to make the precedence explicit: when macos_handler() returns Some, the dynamic callback takes precedence over the static WindowAttributesMacOS::with_accepts_first_mouse setting. The static value is only used as a fallback during re-entrancy.

I've also added guidance in 2cb9dce on when to use one vs the other: use the static setting when a per-window value is sufficient, use the dynamic callback when you need to decide based on click position.

[ogoffart]

IMHO this is confusing to have both. I'm wondering if it would not be better here to remove WindowAttributesMacOS::with_accepts_first_mouse entirely.

[madsmtm]

Could you add usage to the app example?

Or maybe just document when, as a user, you'd want to implement this vs. WindowAttributesMacOS.accepts_first_mouse.

[tilladam]

Done in 2cb9dce — added accepts_first_mouse to the application example and documented when you'd use the static setting vs the dynamic callback.

[madsmtm]

I think it's the right approach to the problem, but boy do I not like the fallback behavior when we're re-entrant, I wish we could do something different - but I don't see a good solution, AppKit is hella re-entrant and that's hard to avoid. Spitballing, maybe making ApplicationHandlerExtMacOS take &self, and do fn macos_handler(&self) -> Option<Box<dyn macos::ApplicationHandlerExtMacOS>> instead? That would push the re-entrancy to the user.

Anyhow, not something we need to fix in this PR, such changes can be made later when we better understand the requirements.

[madsmtm]

Actually, thinking about it a bit more, maybe the better approach would be to allow querying whether an event was the first mouse event?

E.g. something like:

match event {
    WindowEvent::PointerButton {
        button: ButtonSource::Mouse(MouseButton::Left),
        is_macos_first_after_focus_bikeshed, // bool
        position,
        ..
    } => {
        if is_macos_first_after_focus_bikeshed && self.thing_at_pos_is_button(position) {
            return; // Don't try to click buttons for first
        }
        // Select item / click button / whatever you'd normally do
    }
    _ => ...,
}

Whether we can actually implement that is a different story, but I think it'd be more consistent with how Winit otherwise works.

[tilladam]

Thanks for the review! I've addressed the inline comments — see replies above.

Regarding the alternative approach (a is_macos_first_after_focus bool on PointerButton events): I agree it would be more consistent with winit's event-driven model and would avoid the re-entrancy complexity entirely. However, I think the callback approach is the better fit for now:

• Native mapping: The current approach maps directly onto acceptsFirstMouse:, which AppKit calls before deciding whether to deliver the click. With the event-based approach, we'd always return true from acceptsFirstMouse: and reconstruct the "was this first mouse?" state after the fact.
• Reliable detection is tricky: By the time mouseDown: fires, the window is already key. We'd need to track focus-transition state and correlate it with the next mouse-down, with edge cases around rapid clicks, focus changes without clicks, and multiple windows.
• Suppression semantics: With acceptsFirstMouse: returning false, AppKit never delivers the mouseDown at all. The event-based approach can only ignore the click in userland, which is likely equivalent for a custom view but is a semantic difference.

That said, if this is something you'd prefer to explore further or if it's a blocker for the PR, happy to discuss. The event-based approach could also work as a future addition alongside the callback — they aren't mutually exclusive.

[tilladam]

Sorry to nag, but is there anything more I can supply to move this forward? Happy to rework this if you have other ideas for how to fix it or if you prefer the event approach described above.

[ogoffart]

I made a review. But please note that i am not familiar with macOS at all and i don't know really how this is supposed to work.

I have the feeling is_macos_first_after_focus might still be nicer.

Regarding your arguments:

Native mapping

On the other hand winit is an abstraction and doesn't need to map exactly to each platform API (otherwise we'd use the platform API directly)

Reliable detection is tricky
Suppression semantics

That's the question whether it is possible to implement or not.

Regardless, how do you think people will use this? For example, in Slint we'd also probably map this to a is_first_after_forcus or something like that. Or do you have other idea in mind?

[ogoffart]

IMHO this is confusing to have both. I'm wondering if it would not be better here to remove WindowAttributesMacOS::with_accepts_first_mouse entirely.

[ogoffart]

Is it the equivalent of a press, or a release event?

When returning true, do we get normal press end release event as well?

[tilladam]

Reworked this as the event-flag approach you both suggested. Force-pushed a single squashed commit (d073235e) rebased on current master.

What changed:

• New: WindowEvent::PointerButton::is_macos_activation_click: bool. On macOS, it's set on both the press and the matching release of the click that activated an inactive window, so apps can short-circuit the whole gesture with a single check — no state tracking needed for press/release pairs:

  WindowEvent::PointerButton { is_macos_activation_click: true, .. } => return,

  Always false on other platforms. Intervening drag motion (PointerMoved) is not tagged; apps that care about drags during the activation gesture have to track that themselves.

• Removed: ApplicationHandlerExtMacOS::accepts_first_mouse and WindowAttributesMacOS::with_accepts_first_mouse. Per @ogoffart's suggestion, dropping the static one entirely — it's fully redundant once apps can decide per click.

• The acceptsFirstMouse: impl simplifies to "set a Cell<bool> flag, return true". No re-entrancy handling, no handle_with_result primitive, no precedence docs to write.

@ogoffart, to answer your specific questions:

Is it the equivalent of a press, or a release event? When returning true, do we get normal press and release event as well?

Both — the activating left press and its matching release are tagged with is_macos_activation_click: true, intentionally, so a single if is_macos_activation_click { return; } drops the whole gesture. The release event is delivered normally otherwise (so apps that don't care about activation clicks see press + release as usual).

I'm wondering if it would not be better here to remove WindowAttributesMacOS::with_accepts_first_mouse entirely.

Done.

Verified locally: cargo build, cargo test, cargo clippy, cargo +nightly fmt --check clean on macOS host. cargo check -p winit-web --target wasm32-unknown-unknown clean. Cross-platform PointerButton sites (22 across win32/x11/wayland/android/uikit/web/orbital plus core helpers) all pass is_macos_activation_click: false — mechanical, but I couldn't compile the non-macOS/web backends locally; relying on CI for those.

@madsmtm, this also obviates the re-entrancy fallback you flagged — there's nothing to fall back to anymore.