Raxol.Effects.CursorTrail (Raxol v2.0.1)

View Source

Visual cursor trail effects for terminal interfaces.

Creates a fading trail behind cursor movements for enhanced visual feedback. Useful for:

  • Drawing attention to cursor position
  • Visualizing movement patterns
  • Improving accessibility
  • Creating engaging UIs

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})

# Apply trail to buffer
buffer = CursorTrail.apply(trail, buffer)

Configuration

config = %{
  max_length: 20,           # Maximum trail positions to track
  decay_rate: 0.15,         # How quickly trail fades (0.0-1.0)
  colors: [:cyan, :blue, :magenta],
  chars: ["*", "+", "."],   # Characters for different trail positions
  min_opacity: 0.1          # Minimum opacity before hiding
}

trail = CursorTrail.new(config)

Summary

Types

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

Functions

apply(map, buffer)

Apply trail effect to buffer.

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

Apply glow effect to current cursor position.

clear(trail)

Clear all trail points.

comet(config \\ %{})

Create comet trail effect (long fading tail).

interpolate(trail, from, to)

Interpolate positions for smooth trail.

length(map)

Get current trail length.

minimal(config \\ %{})

Create minimal trail effect.

multi_cursor(positions, config \\ %{})

Create animated trail with multiple cursors.

new(config \\ %{})

Create a new cursor trail effect.

rainbow(config \\ %{})

Create rainbow trail effect.

set_enabled(trail, enabled)

Enable or disable trail effect.

stats(map)

Get trail statistics.

update(trail, position)

Update trail with new cursor position.

update_config(trail, new_config)

Update trail configuration.

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(:enabled) => boolean()
}

position()

@type position() :: {non_neg_integer(), non_neg_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 trail effect to buffer.

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

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

Apply glow effect to current cursor position.

clear(trail)

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

Clear all trail points.

comet(config \\ %{})

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

Create comet trail effect (long fading tail).

interpolate(trail, from, to)

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

Interpolate positions for smooth trail.

Adds intermediate points between cursor positions for smoother trails.

length(map)

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

Get current trail length.

minimal(config \\ %{})

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

Create minimal trail effect.

multi_cursor(positions, config \\ %{})

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

Create animated trail with multiple cursors.

new(config \\ %{})

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

Create a new cursor trail effect.

rainbow(config \\ %{})

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

Create rainbow trail effect.

set_enabled(trail, enabled)

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

Enable or disable trail effect.

stats(map)

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

Get trail statistics.

update(trail, position)

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

Update trail with new cursor position.

update_config(trail, new_config)

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

Update trail configuration.