Raxol.Terminal.Cell (Raxol v0.4.0)
View SourceTerminal character cell module.
This module handles the representation and manipulation of individual character cells in the terminal screen buffer, including:
- Character content
- Text attributes (color, style)
- Cell state
Summary
Types
Text style for a terminal cell. See Raxol.Terminal.ANSI.TextFormatting.text_style/0
for details.
Functions
Creates a deep copy of a cell.
Checks if the cell is in double-height mode.
Checks if the cell is in double-width mode.
Compares two cells for equality.
Creates a Cell struct from a map representation, typically from rendering. Expects a map like %{char: integer_codepoint, style: map, is_wide_placeholder: boolean | nil}. Returns nil if the map is invalid.
Returns the character of the cell.
Gets the text style of the cell.
Checks if the cell has a specific attribute.
Checks if the cell has a specific decoration.
Checks if a cell is empty.
Merges a given style map into the cell's style.
Creates a new cell with optional character and style.
Creates a new cell representing the second half of a wide character. Inherits the style from the primary cell.
Sets the character content of a cell.
Sets the text style of the cell.
Creates a copy of a cell with new attributes applied.
Creates a copy of a cell with a new character.
Types
@type style() :: Raxol.Terminal.ANSI.TextFormatting.text_style()
Text style for a terminal cell. See Raxol.Terminal.ANSI.TextFormatting.text_style/0
for details.
@type t() :: %Raxol.Terminal.Cell{ char: String.t() | nil, dirty: boolean(), is_wide_placeholder: boolean(), style: Raxol.Terminal.ANSI.TextFormatting.text_style() }
Functions
Creates a deep copy of a cell.
Examples
iex> cell = Cell.new("A", %{foreground: :red})
iex> copy = Cell.copy(cell)
iex> Cell.get_char(copy)
"A"
iex> Cell.get_style(copy)
%{foreground: :red}
Checks if the cell is in double-height mode.
Examples
iex> cell = Cell.new("A", %{foreground: :red})
iex> Cell.double_height?(cell)
false
Checks if the cell is in double-width mode.
Examples
iex> cell = Cell.new("A", %{foreground: :red})
iex> Cell.double_width?(cell)
false
Compares two cells for equality.
Cells are considered equal if they have the same character and the same style map.
Handles comparison with nil
.
Examples
iex> style1 = TextFormatting.new() |> TextFormatting.apply_attribute(:bold)
iex> style2 = TextFormatting.new() |> TextFormatting.apply_attribute(:bold)
iex> style3 = TextFormatting.new() |> TextFormatting.apply_attribute(:underline)
iex> cell1 = Cell.new("A", style1)
iex> cell2 = Cell.new("A", style2) # Same char and style attributes
iex> cell3 = Cell.new("B", style1) # Different char
iex> cell4 = Cell.new("A", style3) # Different style
iex> Cell.equals?(cell1, cell2)
true
iex> Cell.equals?(cell1, cell3)
false
iex> Cell.equals?(cell1, cell4)
false
iex> Cell.equals?(cell1, nil)
false
iex> Cell.equals?(nil, cell1)
false
iex> Cell.equals?(nil, nil)
true
Creates a Cell struct from a map representation, typically from rendering. Expects a map like %{char: integer_codepoint, style: map, is_wide_placeholder: boolean | nil}. Returns nil if the map is invalid.
Returns the character of the cell.
Gets the text style of the cell.
Examples
iex> cell = Cell.new("A", %{foreground: :red})
iex> Cell.get_style(cell)
%{foreground: :red}
Checks if the cell has a specific attribute.
Examples
iex> cell = Cell.new("A", %{foreground: :red})
iex> Cell.has_attribute?(cell, :foreground)
true
Checks if the cell has a specific decoration.
Examples
iex> cell = Cell.new("A", %{foreground: :red})
iex> Cell.has_decoration?(cell, :bold)
false
Checks if a cell is empty.
A cell is considered empty if it contains a space character and has the default text formatting style.
Examples
iex> cell = Cell.new()
iex> Cell.is_empty?(cell)
true
iex> cell = Cell.new("A")
iex> Cell.is_empty?(cell)
false
iex> bold_style = TextFormatting.new() |> TextFormatting.apply_attribute(:bold)
iex> cell = Cell.new(" ", bold_style) # Space char but non-default style
iex> Cell.is_empty?(cell)
false
Merges a given style map into the cell's style.
Only non-default attributes from the style
map will overwrite existing attributes
in the cell's style. This prevents merging default values (like bold: false
)
and unintentionally removing existing attributes.
Examples
iex> initial_style = TextFormatting.new() |> TextFormatting.apply_attribute(:bold) # %{bold: true, ...}
iex> merge_style = TextFormatting.new() |> TextFormatting.apply_attribute(:underline) # %{underline: true, bold: false, ...}
iex> cell = Cell.new("A", initial_style)
iex> merged_cell = Cell.merge_style(cell, merge_style)
iex> Cell.get_style(merged_cell)
%{bold: true, underline: true} # Note: :bold remains, :underline added
Creates a new cell with optional character and style.
Examples
iex> cell = Cell.new()
iex> Cell.is_empty?(cell)
true
iex> cell = Cell.new("A")
iex> Cell.get_char(cell)
"A"
iex> cell = Cell.new("A", %{foreground: :red})
iex> Cell.get_char(cell)
"A"
iex> Cell.get_style(cell)
%{foreground: :red}
Creates a new cell representing the second half of a wide character. Inherits the style from the primary cell.
Sets the character content of a cell.
Examples
iex> cell = Cell.new()
iex> cell = Cell.set_char(cell, "A")
iex> Cell.get_char(cell)
"A"
Sets the text style of the cell.
Examples
iex> cell = Cell.new("A")
iex> cell = Cell.set_style(cell, %{foreground: :red})
iex> Cell.get_style(cell)
%{foreground: :red}
Creates a copy of a cell with new attributes applied.
Accepts a map of attributes or a list of attribute atoms. If a list is provided, the attributes are applied sequentially, starting from the cell's existing style.
Examples
iex> cell = Cell.new("A", %{bold: true})
iex> new_cell = Cell.with_attributes(cell, %{underline: true}) # Using a map
iex> Cell.get_style(new_cell)
%{bold: true, underline: true} # Merged
iex> cell = Cell.new("B", %{bold: true})
iex> new_cell = Cell.with_attributes(cell, [:underline, :reverse]) # Using a list
iex> Cell.get_style(new_cell)
%{bold: true, underline: true, reverse: true} # Original bold + list applied
Creates a copy of a cell with a new character.
Examples
iex> cell = Cell.new("A", %{foreground: :red})
iex> new_cell = Cell.with_char(cell, "B")
iex> Cell.get_char(new_cell)
"B"
iex> Cell.get_style(new_cell)
%{foreground: :red}