Raxol.Core.FocusManager (Raxol v0.4.0)
View SourceFocus management system for Raxol terminal UI applications.
This module provides utilities for managing focus between interactive components:
- Tab-based keyboard navigation
- Focus history tracking
- Focus ring rendering
- Screen reader announcements
Usage
# Register focusable components in your view
FocusManager.register_focusable("search_input", 1)
FocusManager.register_focusable("submit_button", 2)
# Initialize the focus manager with the first focusable element
FocusManager.set_initial_focus("search_input")
Summary
Functions
Disable a focusable component, preventing it from receiving focus.
Enable a previously disabled focusable component.
Move focus to the next focusable element.
Move focus to the previous focusable element.
Alias for get_focused_element/0.
Get the ID of the currently focused element.
Get the next focusable element after the given one. (Placeholder implementation - mirrors focus_next logic)
Get the previous focusable element before the given one.
Mirrors the logic of get_next_focusable/1
but searches backwards.
Check if a component has focus.
Register a handler function to be called when focus changes.
Register a focusable component with the focus manager.
Return to the previously focused element.
Set focus to a specific component.
Set the initial focus to a specific component.
Unregister a focus change handler function. (Placeholder implementation)
Unregister a focusable component.
Functions
Disable a focusable component, preventing it from receiving focus.
Examples
iex> FocusManager.disable_component("submit_button")
:ok
Enable a previously disabled focusable component.
Examples
iex> FocusManager.enable_component("submit_button")
:ok
Move focus to the next focusable element.
Options
:group
- Only navigate within this group (default:nil
- use current group):wrap
- Wrap around to first element when at the end (default:true
)
Examples
iex> FocusManager.focus_next()
:ok
iex> FocusManager.focus_next(group: :form_actions)
:ok
Move focus to the previous focusable element.
Options
:group
- Only navigate within this group (default:nil
- use current group):wrap
- Wrap around to last element when at the beginning (default:true
)
Examples
iex> FocusManager.focus_previous()
:ok
@spec get_current_focus() :: String.t() | nil
Alias for get_focused_element/0.
Get the ID of the currently focused element.
Examples
iex> FocusManager.set_initial_focus("my_button")
iex> FocusManager.get_focused_element()
"my_button"
Get the next focusable element after the given one. (Placeholder implementation - mirrors focus_next logic)
Get the previous focusable element before the given one.
Mirrors the logic of get_next_focusable/1
but searches backwards.
Check if a component has focus.
Examples
iex> FocusManager.has_focus?("search_input")
true
Register a handler function to be called when focus changes.
The handler function should accept two arguments: old_focus
and new_focus
.
(Placeholder implementation)
Register a focusable component with the focus manager.
Parameters
component_id
- Unique identifier for the componenttab_index
- Tab order index (lower numbers are focused first)opts
- Additional options
Options
:group
- Focus group name for grouped navigation (default::default
):disabled
- Whether the component is initially disabled (default:false
):announce
- Announcement text for screen readers when focused (default:nil
)
Examples
iex> FocusManager.register_focusable("search_input", 1)
:ok
iex> FocusManager.register_focusable("submit_button", 2, group: :form_actions)
:ok
Return to the previously focused element.
Examples
iex> FocusManager.return_to_previous()
:ok
Set focus to a specific component.
Examples
iex> FocusManager.set_focus("submit_button")
:ok
Set the initial focus to a specific component.
Examples
iex> FocusManager.set_initial_focus("search_input")
:ok
Unregister a focus change handler function. (Placeholder implementation)
Unregister a focusable component.
Examples
iex> FocusManager.unregister_focusable("search_input")
:ok