Raxol.Core.KeyboardNavigator (Raxol v0.3.0)
View SourceKeyboard navigation handler for Raxol terminal UI applications.
This module integrates with the FocusManager to provide keyboard navigation between interactive components using standard key bindings:
- Tab: Move to next focusable element
- Shift+Tab: Move to previous focusable element
- Arrow keys: Navigate between elements in a component group
- Escape: Return to previous focus or dismiss dialogs
- Enter/Space: Activate currently focused element
Usage
# Initialize keyboard navigation in your application
KeyboardNavigator.init()
# Customize keybindings
KeyboardNavigator.configure(next_key: :right, previous_key: :left)
Summary
Functions
Configure keyboard navigation behavior.
Define explicit navigation paths between components.
Handle keyboard events for navigation.
Initialize the keyboard navigator.
Register component positions for spatial navigation.
Register a custom shortcut handler.
Functions
Configure keyboard navigation behavior.
Options
:next_key
- Key to move to next element (default::tab
):previous_key
- Key to move to previous element (default::tab
with shift):activate_keys
- Keys to activate elements (default:[:enter, :space]
):dismiss_key
- Key to dismiss or go back (default::escape
):arrow_navigation
- Enable arrow key navigation (default:true
):vim_keys
- Enable vim-style navigation with h,j,k,l (default:false
):group_navigation
- Enable group-based navigation (default:true
):spatial_navigation
- Enable spatial navigation for grid layouts (default:false
):tab_navigation
- Enable tab-based navigation (default:true
)
Examples
iex> KeyboardNavigator.configure(vim_keys: true)
:ok
Handle keyboard events for navigation.
This function is called by the EventManager when keyboard events occur.
Parameters
event
- The keyboard event to handle
Returns
:handled
- If the event was handled by the navigator:unhandled
- If the event was not handled
Initialize the keyboard navigator.
This registers event handlers for keyboard navigation.
Examples
iex> KeyboardNavigator.init()
:ok
Register component positions for spatial navigation.
This allows arrow keys to navigate components based on their physical layout.
Parameters
component_id
- Unique identifier for the componentx
- X coordinatey
- Y coordinatewidth
- Width of the componentheight
- Height of the component
Examples
iex> KeyboardNavigator.register_component_position("search_input", 10, 5, 30, 3)
:ok
Register a custom shortcut handler.
Parameters
key
- The key to handlemodifiers
- List of modifier keys (e.g., [:ctrl, :shift])handler
- Function to call when shortcut is pressed
Examples
iex> KeyboardNavigator.register_shortcut(:f1, [], &show_help/0)
:ok