Skip to main content

on_window_acquire_focus_clear

Function on_window_acquire_focus_clear 

Source
pub fn on_window_acquire_focus_clear(
    acquire_focus: On<'_, '_, AcquireFocus>,
    windows: Query<'_, '_, (), With<Window>>,
    focus: ResMut<'_, InputFocus>,
)
Expand description

Observer which clears input focus when an AcquireFocus request bubbles all the way up to a Window without finding a focusable target.

This is the generalized half of focus acquisition: it has no knowledge of any specific focus-navigation scheme. It is what makes “click outside to unfocus” work even when no navigation framework (e.g. tab_navigation) is installed — an AcquireFocus triggered on a non-focusable entity bubbles via WindowTraversal until it reaches the window, where this observer clears focus. Actually focusing a target is the responsibility of a navigation module: for tab navigation, that is acquire_focus_tab_index, which stops the request (and focuses the target) before it can reach the window.

Clearing focus relies on the request actually reaching the window via WindowTraversal. That traversal walks up ChildOf relationships, and — as a fallback — routes to AcquireFocus::window once it runs off the end of the ancestor chain. Because of this window fallback, the request target does not need to be a descendant of the window entity: any non-window entity eventually reaches the window, where focus is cleared.

The focus.get() guard avoids spurious mutations so change detection only fires on real changes. Verify against the acquire_focus_* tests before altering any of this.