TermUI.EventRouter (TermUI v0.2.0)

View Source

Central event routing for TermUI components.

The EventRouter manages event distribution to components based on:

  • Focus state for keyboard events
  • Spatial index for mouse events
  • Broadcast for system events (resize)

Usage

# Route a keyboard event to focused component
EventRouter.route(%Event.Key{key: :enter})

# Route a mouse event to component at position
EventRouter.route(%Event.Mouse{action: :click, x: 10, y: 5})

# Set focused component
EventRouter.set_focus(:my_input)

# Broadcast to all components
EventRouter.broadcast({:resize, 80, 24})

Event Flow

  1. Event received by router
  2. Router determines target based on event type
  3. Event delivered to target component
  4. If unhandled, event bubbles to parent (if propagation enabled)

Summary

Types

route_result()

Functions

broadcast(event)

Broadcasts an event to all registered components.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

clear_fallback_handler()

Clears the fallback handler.

clear_focus()

Clears the current focus.

get_focus()

Gets the currently focused component.

route(event)

Routes an event to the appropriate component.

route_to(component_id, event)

Routes an event directly to a specific component by id.

set_fallback_handler(handler)

Registers a global event handler for events that no component handles.

set_focus(component_id)

Sets the currently focused component.

start_link(opts \\ [])

Starts the event router.

Types

route_result()

@type route_result() :: :handled | :unhandled | {:error, term()}

Functions

broadcast(event)

@spec broadcast(term()) :: {:ok, non_neg_integer()}

Broadcasts an event to all registered components.

Useful for system-wide events like resize.

Returns

  • {:ok, count} - Number of components that received the event

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

clear_fallback_handler()

@spec clear_fallback_handler() :: :ok

Clears the fallback handler.

clear_focus()

@spec clear_focus() :: :ok

Clears the current focus.

get_focus()

@spec get_focus() :: {:ok, term() | nil}

Gets the currently focused component.

Returns

  • {:ok, component_id} - The focused component
  • {:ok, nil} - No component focused

route(event)

@spec route(
  TermUI.Event.Key.t()
  | TermUI.Event.Mouse.t()
  | TermUI.Event.Focus.t()
  | TermUI.Event.Custom.t()
) :: route_result()

Routes an event to the appropriate component.

Keyboard and focus events go to the focused component. Mouse events go to the component at the mouse position.

Returns

  • :handled - Event was processed by a component
  • :unhandled - No component handled the event
  • {:error, reason} - Routing failed

route_to(component_id, event)

@spec route_to(term(), term()) :: route_result()

Routes an event directly to a specific component by id.

Returns

  • :handled - Component handled the event
  • :unhandled - Component did not handle the event
  • {:error, :not_found} - Component not found

set_fallback_handler(handler)

@spec set_fallback_handler((term() -> :ok)) :: :ok

Registers a global event handler for events that no component handles.

The handler receives unhandled events and can process them as needed.

Parameters

  • handler - Function that receives events: fn event -> :ok end

set_focus(component_id)

@spec set_focus(term() | nil) :: :ok

Sets the currently focused component.

Sends focus lost event to previous focus and focus gained to new focus.

Parameters

  • component_id - The component to focus, or nil to clear focus

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the event router.