Raxol.Effects.CursorTrail (Raxol v2.6.0)

View Source

Visual cursor trail for terminal interfaces.

Tracks recent cursor positions and renders a fading trail behind the current cursor. Useful for drawing attention to cursor movement, visualising input, or just adding aesthetic weight to a TUI cockpit.

Example

trail = CursorTrail.new(max_length: 10)
trail = CursorTrail.update(trail, {5, 10})
trail = CursorTrail.update(trail, {6, 10})
trail = CursorTrail.update(trail, {7, 10})

buffer = CursorTrail.apply(trail, buffer)

Configuration

config = %{
  max_length: 20,           # Maximum trail positions to track
  decay_rate: 0.15,         # Exponential opacity decay per tick
  colors: [:cyan, :blue, :magenta],
  chars: ["*", "+", "."],   # Characters cycled along the trail
  min_opacity: 0.1,         # Drop points below this opacity
  overwrite_text: false,    # Paint over non-space cells if true
  enabled: true
}

trail = CursorTrail.new(config)

Presets

Summary

Types

config()
position()
t()
trail_point()

Functions

apply(map, buffer)

Apply the trail's current points to a buffer.

apply_glow(buffer, arg, color \\ :cyan)

Apply a fixed glow halo around a single position. Independent of trail state -- useful for highlighting an active cursor without history.

clear(trail)

Drop all points (preserves config).

comet(config \\ %{})

Long white-to-blue fading tail with tapered chars.

electric(config \\ %{})

Bright yellow/cyan crackle, matches BorderBeam :electric.

interpolate(trail, from, to)

Append the points along the line from -> to to the trail. Uses Bresenham's algorithm to fill in intermediate cells so a single jump produces a smooth trail.

length(map)

Number of currently visible points.

matrix(config \\ %{})

Green-on-green digital rain, matches BorderBeam :matrix.

minimal(config \\ %{})

Subtle five-cell white trail with quick decay.

multi_cursor(positions, config \\ %{})

Build a trail seeded with multiple positions.

neon(config \\ %{})

Magenta/cyan vapor, matches BorderBeam :neon.

new(config \\ %{})

Create a new cursor trail.

rainbow(config \\ %{})

Six-color rainbow cycle, length 24.

set_enabled(trail, enabled)

Enable or disable the effect.

stats(map)

Trail statistics: point_count, max_length, enabled, tick, average_opacity.

update(trail, position)

Append a position to the trail (or age existing points if unchanged).

update_config(trail, new_config)

Merge new config keys into the existing config.

Types

config()

@type config() :: %{
  optional(:max_length) => pos_integer(),
  optional(:decay_rate) => float(),
  optional(:colors) => [atom()],
  optional(:chars) => [String.t()],
  optional(:min_opacity) => float(),
  optional(:overwrite_text) => boolean(),
  optional(:enabled) => boolean()
}

position()

@type position() :: {integer(), integer()}

t()

@type t() :: %Raxol.Effects.CursorTrail{
  config: config(),
  points: [trail_point()],
  tick: non_neg_integer()
}

trail_point()

@type trail_point() :: %{
  position: position(),
  age: non_neg_integer(),
  opacity: float()
}

Functions

apply(map, buffer)

@spec apply(t(), Raxol.Core.Buffer.t()) :: Raxol.Core.Buffer.t()

Apply the trail's current points to a buffer.

apply_glow(buffer, arg, color \\ :cyan)

@spec apply_glow(Raxol.Core.Buffer.t(), position(), atom()) :: Raxol.Core.Buffer.t()

Apply a fixed glow halo around a single position. Independent of trail state -- useful for highlighting an active cursor without history.

clear(trail)

@spec clear(t()) :: t()

Drop all points (preserves config).

comet(config \\ %{})

@spec comet(config()) :: t()

Long white-to-blue fading tail with tapered chars.

electric(config \\ %{})

@spec electric(config()) :: t()

Bright yellow/cyan crackle, matches BorderBeam :electric.

interpolate(trail, from, to)

@spec interpolate(t(), position(), position()) :: t()

Append the points along the line from -> to to the trail. Uses Bresenham's algorithm to fill in intermediate cells so a single jump produces a smooth trail.

length(map)

@spec length(t()) :: non_neg_integer()

Number of currently visible points.

matrix(config \\ %{})

@spec matrix(config()) :: t()

Green-on-green digital rain, matches BorderBeam :matrix.

minimal(config \\ %{})

@spec minimal(config()) :: t()

Subtle five-cell white trail with quick decay.

multi_cursor(positions, config \\ %{})

@spec multi_cursor([position()], config()) :: t()

Build a trail seeded with multiple positions.

neon(config \\ %{})

@spec neon(config()) :: t()

Magenta/cyan vapor, matches BorderBeam :neon.

new(config \\ %{})

@spec new(config()) :: t()

Create a new cursor trail.

rainbow(config \\ %{})

@spec rainbow(config()) :: t()

Six-color rainbow cycle, length 24.

set_enabled(trail, enabled)

@spec set_enabled(t(), boolean()) :: t()

Enable or disable the effect.

stats(map)

@spec stats(t()) :: map()

Trail statistics: point_count, max_length, enabled, tick, average_opacity.

update(trail, position)

@spec update(t(), position()) :: t()

Append a position to the trail (or age existing points if unchanged).

update_config(trail, new_config)

@spec update_config(t(), config()) :: t()

Merge new config keys into the existing config.