TermUI.EventRouter (TermUI v1.0.0)

View Source

Central event routing for TermUI components.

This is a standalone service for the process-oriented component subsystem. TermUI.Runtime does not start or call it; the integrated Elm runtime routes every event to its own :root entry.

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. An unrouted event is passed to the optional fallback handler

The router does not bubble unhandled events through registry parents.

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.