TermUI.SpatialIndex (TermUI v0.2.0)

View Source

Spatial index for fast component lookup by screen position.

The spatial index enables efficient routing of mouse events to the correct component based on cursor coordinates. It maintains a mapping of screen regions to component references.

Usage

# Register a component's bounds
SpatialIndex.update(:my_button, pid, %{x: 10, y: 5, width: 20, height: 3})

# Find component at position
{:ok, {:my_button, pid}} = SpatialIndex.find_at(15, 6)

# Remove when unmounted
SpatialIndex.remove(:my_button)

Z-Order

When components overlap, the one with the highest z-index receives mouse events. Default z-index is 0. Modals typically use higher values.

Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

clear()

Clears all entries from the index.

count()

Returns the number of indexed components.

find_all_at(x, y)

Finds all components at the given coordinates.

find_at(x, y)

Finds the component at the given coordinates.

get_bounds(id)

Gets the bounds for a component.

remove(id)

Removes a component from the index.

start_link(opts \\ [])

Starts the spatial index.

update(id, pid, bounds, opts \\ [])

Updates a component's bounds in the index.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

clear()

@spec clear() :: :ok

Clears all entries from the index.

count()

@spec count() :: non_neg_integer()

Returns the number of indexed components.

find_all_at(x, y)

@spec find_all_at(integer(), integer()) :: [{term(), pid(), integer()}]

Finds all components at the given coordinates.

Returns all overlapping components sorted by z-index (highest first).

find_at(x, y)

@spec find_at(integer(), integer()) :: {:ok, {term(), pid()}} | {:error, :not_found}

Finds the component at the given coordinates.

Returns the topmost component (highest z-index) at the position.

Returns

  • {:ok, {id, pid}} - Component found
  • {:error, :not_found} - No component at position

get_bounds(id)

@spec get_bounds(term()) :: {:ok, map()} | {:error, :not_found}

Gets the bounds for a component.

remove(id)

@spec remove(term()) :: :ok

Removes a component from the index.

start_link(opts \\ [])

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

Starts the spatial index.

update(id, pid, bounds, opts \\ [])

@spec update(term(), pid(), map(), keyword()) :: :ok

Updates a component's bounds in the index.

Parameters

  • id - Component identifier
  • pid - Component process
  • bounds - Map with x, y, width, height
  • opts - Options including :z_index

Examples

SpatialIndex.update(:button, pid, %{x: 0, y: 0, width: 10, height: 1})
SpatialIndex.update(:modal, pid, bounds, z_index: 100)