TermUI.Event.Transformation (TermUI v0.2.0)

View Source

Event transformation utilities.

Transforms events as they route to components, including:

  • Coordinate transformation (screen to component-local)
  • Event metadata enrichment
  • Event filtering

Usage

# Transform mouse coordinates to component-local
local_event = Transformation.to_local(event, component_bounds)

# Add metadata to event
enriched = Transformation.with_metadata(event, %{target: :button})

Summary

Functions

envelope(event, opts \\ [])

Creates a standard event envelope with routing metadata.

filter(events, filters)

Filters a list of events based on criteria.

get_metadata(event, key, default \\ nil)

Gets metadata from an event.

matches?(event, filters)

Checks if an event matches a filter.

to_local(event, arg2)

Transforms screen coordinates to component-local coordinates.

to_screen(event, arg2)

Transforms component-local coordinates back to screen coordinates.

with_metadata(event, metadata)

Adds metadata to an event.

Functions

envelope(event, opts \\ [])

@spec envelope(
  term(),
  keyword()
) :: map()

Creates a standard event envelope with routing metadata.

Parameters

  • event - The raw event
  • opts - Options:
    • :source - Source of the event
    • :target - Target component id
    • :timestamp - Override timestamp

Returns

Event with envelope metadata.

filter(events, filters)

@spec filter(
  list(),
  keyword()
) :: list()

Filters a list of events based on criteria.

Parameters

  • events - List of events
  • filters - Filter criteria (see matches?/2)

Returns

List of events matching all filters.

get_metadata(event, key, default \\ nil)

@spec get_metadata(map(), atom(), term()) :: term()

Gets metadata from an event.

Parameters

  • event - The event
  • key - Metadata key to get
  • default - Default value if key not found

Returns

The metadata value or default.

matches?(event, filters)

@spec matches?(
  term(),
  keyword()
) :: boolean()

Checks if an event matches a filter.

Filter Options

  • :type - Event type (:key, :mouse, :focus, :custom)
  • :key - Specific key (for key events)
  • :action - Specific action (for mouse/focus events)
  • :button - Specific button (for mouse events)
  • :modifiers - Required modifiers (any or all)
  • :modifiers_all - All modifiers must be present
  • :modifiers_any - Any modifier must be present

Example

# Match Ctrl+C
matches?(event, type: :key, key: :c, modifiers_all: [:ctrl])

# Match any click
matches?(event, type: :mouse, action: :click)

to_local(event, arg2)

@spec to_local(TermUI.Event.Mouse.t() | term(), map()) ::
  TermUI.Event.Mouse.t() | term()

Transforms screen coordinates to component-local coordinates.

For mouse events, subtracts the component's position from the event coordinates so the component receives coordinates relative to its own origin (0, 0).

Parameters

  • event - Mouse event with screen coordinates
  • bounds - Component bounds with x, y position

Returns

Event with transformed coordinates, or unchanged event if not a mouse event.

Example

event = %Mouse{x: 15, y: 10, ...}
bounds = %{x: 10, y: 5, width: 20, height: 10}
local = to_local(event, bounds)
# local.x = 5, local.y = 5

to_screen(event, arg2)

@spec to_screen(TermUI.Event.Mouse.t() | term(), map()) ::
  TermUI.Event.Mouse.t() | term()

Transforms component-local coordinates back to screen coordinates.

Inverse of to_local/2.

Parameters

  • event - Mouse event with local coordinates
  • bounds - Component bounds with x, y position

Returns

Event with screen coordinates.

with_metadata(event, metadata)

@spec with_metadata(map(), map()) :: map()

Adds metadata to an event.

Creates or updates a :metadata field on the event struct.

Parameters

  • event - The event to enrich
  • metadata - Map of metadata to add

Returns

Event with metadata merged.

Example

event = with_metadata(key_event, %{target: :input, phase: :bubble})