wijjit.core.focus.FocusManager

class wijjit.core.focus.FocusManager

Manages focus across UI elements.

This class tracks which element has focus and provides methods for navigating focus between focusable elements.

Variables:

• elements (list) – List of focusable elements (sorted by tab_index)

• current_index (int or None) – Index of currently focused element

• all_focusable (list) – All focusable elements including those with tab_index=-1

__init__()

Return type:

None

Methods

__init__()
clear()	Clear all elements and focus.
focus_element(element)	Focus a specific element.
focus_first()	Focus the first focusable element.
focus_last()	Focus the last focusable element.
focus_next()	Move focus to the next element.
focus_previous()	Move focus to the previous element.
get_focused_element()	Get the currently focused element.
restore_state(state)	Restore focus state from saved state.
save_state()	Save current focus state.
set_elements(elements)	Set the list of focusable elements.
set_focus_filter(allowed_elements)	Filter focusable elements to a specific subset.

set_elements(elements)

Set the list of focusable elements.

Preserves focus on the same element (by ID or index) if possible. Elements are sorted by tab_index: explicit indices first (sorted numerically), then elements without tab_index (document order). Elements with tab_index=-1 are excluded from Tab navigation but can still receive focus via click or programmatic focus.

Parameters:

elements (list) – List of focusable elements

Return type:

None

get_focused_element()

Get the currently focused element.

Returns:

Currently focused element, or None if no element has focus

Return type:

Element or None

focus_first()

Focus the first focusable element.

Return type:

None

focus_last()

Focus the last focusable element.

Return type:

None

focus_next()

Move focus to the next element.

Focus wraps cyclically: advancing past the last element returns to the first.

Returns:

True if focus moved; False only when there are no focusable elements.

Return type:

bool

focus_previous()

Move focus to the previous element.

Focus wraps cyclically: moving back past the first element returns to the last.

Returns:

True if focus moved; False only when there are no focusable elements.

Return type:

bool

focus_element(element)

Focus a specific element.

Parameters:

element (Element) – Element to focus

Returns:

True if element was focused, False if not found

Return type:

bool

clear()

Clear all elements and focus.

Return type:

None

set_focus_filter(allowed_elements)

Filter focusable elements to a specific subset.

This is used for focus trapping in overlays. When an overlay traps focus, only elements within that overlay are focusable.

Parameters:

allowed_elements (list of Element or None) – Elements that should be focusable, or None to clear filter. If provided, only these elements will be in the focus cycle.

Return type:

None

Notes

This temporarily restricts focus navigation to the specified elements. The original element list is preserved and can be restored by passing None or by calling set_elements() again.

save_state()

Save current focus state.

Returns:

Tuple of (elements list, current_index) that can be restored later

Return type:

tuple

Notes

Used by overlay manager to save focus state before showing an overlay with focus trapping enabled.

restore_state(state)

Restore focus state from saved state.

Parameters:

state (tuple) – State tuple returned by save_state()

Return type:

None

Notes

Restores the complete focus state including the element list and focused element. Used when closing an overlay that trapped focus.