TermUI.Renderer.Cell (TermUI v0.2.0)

Represents a single cell in the terminal screen buffer.

A cell contains a character (grapheme cluster), foreground and background colors, and style attributes. Cells are immutable - updates create new cells, enabling efficient diffing by reference comparison.

Color Types

Colors can be specified as:

:default - Terminal default color
Atom - Named color (:red, :green, :blue, etc.)
Integer 0-255 - 256-color palette index
{r, g, b} tuple - True color RGB values (0-255 each)

Attributes

Supported style attributes:

:bold - Bold/bright text
:dim - Dimmed text
:italic - Italic text
:underline - Underlined text
:blink - Blinking text
:reverse - Reversed colors
:hidden - Hidden text
:strikethrough - Strikethrough text

Summary

Types

attribute()

color()

t()

Functions

add_attr(cell, attr)

Adds an attribute to the cell.

empty()

Returns an empty cell with default styling.

empty?(cell)

Checks if a cell is empty (space with default styling).

equal?(a, b)

Compares two cells for equality.

has_attr?(cell, attr)

Checks if the cell has a specific attribute.

named_colors()

Returns list of valid color names.

new(char, opts \\ [])

Creates a new cell with the given character and optional styling.

put_bg(cell, color)

Returns a cell with updated background color.

put_char(cell, char)

Returns a cell with updated character.

put_fg(cell, color)

Returns a cell with updated foreground color.

remove_attr(cell, attr)

Removes an attribute from the cell.

valid_attributes()

Returns list of valid attributes.

wide?(cell)

Returns true if this cell is a wide (double-width) character.

wide_placeholder(primary)

Creates a placeholder cell for the second column of a wide character.

wide_placeholder?(cell)

Returns true if this cell is a wide character placeholder.

width(cell)

Returns the display width of a cell (1 or 2).

Types

attribute()

@type attribute() ::
  :bold
  | :dim
  | :italic
  | :underline
  | :blink
  | :reverse
  | :hidden
  | :strikethrough

color()

@type color() :: :default | atom() | 0..255 | {0..255, 0..255, 0..255}

t()

@type t() :: %TermUI.Renderer.Cell{
  attrs: MapSet.t(attribute()),
  bg: color(),
  char: String.t(),
  fg: color(),
  wide_placeholder: boolean(),
  width: 1 | 2
}

Functions

add_attr(cell, attr)

@spec add_attr(t(), attribute()) :: t()

Adds an attribute to the cell.

empty()

@spec empty() :: t()

Returns an empty cell with default styling.

An empty cell contains a space character with default colors and no attributes.

Examples

iex> Cell.empty()
%Cell{char: " ", fg: :default, bg: :default, attrs: MapSet.new()}

empty?(cell)

@spec empty?(t()) :: boolean()

Checks if a cell is empty (space with default styling).

Examples

iex> Cell.empty?(Cell.empty())
true

iex> Cell.empty?(Cell.new("A"))
false

equal?(a, b)

@spec equal?(t(), t()) :: boolean()

Compares two cells for equality.

Returns true if both cells have the same character, colors, and attributes. Used by the diff algorithm to identify changed cells.

Examples

iex> Cell.equal?(Cell.empty(), Cell.empty())
true

iex> Cell.equal?(Cell.new("A"), Cell.new("B"))
false

has_attr?(cell, attr)

@spec has_attr?(t(), attribute()) :: boolean()

Checks if the cell has a specific attribute.

named_colors()

@spec named_colors() :: [atom()]

Returns list of valid color names.

new(char, opts \\ [])

@spec new(
  String.t(),
  keyword()
) :: t()

Creates a new cell with the given character and optional styling.

Examples

iex> Cell.new("A")
%Cell{char: "A", fg: :default, bg: :default, attrs: MapSet.new()}

iex> Cell.new("X", fg: :red, attrs: [:bold])
%Cell{char: "X", fg: :red, bg: :default, attrs: MapSet.new([:bold])}

put_bg(cell, color)

@spec put_bg(t(), color()) :: t()

Returns a cell with updated background color.

put_char(cell, char)

@spec put_char(t(), String.t()) :: t()

Returns a cell with updated character.

Examples

iex> cell = Cell.new("A", fg: :red)
iex> Cell.put_char(cell, "B")
%Cell{char: "B", fg: :red, bg: :default, attrs: MapSet.new()}

put_fg(cell, color)

@spec put_fg(t(), color()) :: t()

Returns a cell with updated foreground color.

remove_attr(cell, attr)

@spec remove_attr(t(), attribute()) :: t()

Removes an attribute from the cell.

valid_attributes()

@spec valid_attributes() :: [attribute()]

Returns list of valid attributes.

wide?(cell)

@spec wide?(t()) :: boolean()

Returns true if this cell is a wide (double-width) character.

wide_placeholder(primary)

@spec wide_placeholder(t()) :: t()

Creates a placeholder cell for the second column of a wide character.

This cell inherits the styling from the primary cell but renders as empty.

wide_placeholder?(cell)

@spec wide_placeholder?(t()) :: boolean()

Returns true if this cell is a wide character placeholder.

width(cell)

@spec width(t()) :: non_neg_integer()

Returns the display width of a cell (1 or 2).