ExRatatui.BigText (ExRatatui v0.10.0)

Build oversized 8×8-pixel text widgets for slide titles and banners.

Powered by tui-big-text. Each character is rasterised through a bitmap font; the pixel_size option controls how many cells a single 8×8 pixel maps to.

banner = ExRatatui.BigText.new("HELLO", pixel_size: :quadrant, alignment: :center)

def view(_model, frame) do
  area = %ExRatatui.Layout.Rect{x: 0, y: 0, width: frame.width, height: 10}
  [{banner, area}]
end

Options

:pixel_size - one of :full (default, one character cell per pixel), :half_height, :half_width, :quadrant, :third_height, :sextant, :quarter_height, :octant. Smaller variants pack more characters into the same area at the cost of legibility.
:alignment - :left (default), :center, or :right.
:style - %ExRatatui.Style{} applied to all rendered glyphs. Per-line and per-span styles in the input still win on conflict.
:block - optional %ExRatatui.Widgets.Block{} for a border / title around the big text.

Accepted input shapes

new/2 coerces its first argument through the same path ExRatatui.Paragraph uses, so any text-like shape is accepted:

String.t() — split on "\n" into one line per chunk
%ExRatatui.Text.Line{} or %ExRatatui.Text.Span{}
%ExRatatui.Text{} — the lines + outer style are unpacked
[%Line{} | %Span{} | binary] — list of any single accepted shape

Sizing tip

A :full glyph is 8×8 character cells. A two-character word at :full therefore needs ~16 cells wide and 8 cells tall. If you're targeting an 80×24 terminal, :half_height (4 rows tall) or :quadrant (4 rows tall, 4 cols wide) usually fits a 2–3 word title.

Summary

Types

new_opts()

Functions

new(text, opts \\ [])

Build a %ExRatatui.Widgets.BigText{} from text-like input.

Types

new_opts()

@type new_opts() :: [
  pixel_size: ExRatatui.Widgets.BigText.pixel_size(),
  alignment: ExRatatui.Widgets.BigText.alignment(),
  style: ExRatatui.Style.t(),
  block: ExRatatui.Widgets.Block.t() | nil
]

Functions

new(text, opts \\ [])

@spec new(term(), new_opts()) :: ExRatatui.Widgets.BigText.t()

Build a %ExRatatui.Widgets.BigText{} from text-like input.

text accepts the same shapes any text-bearing widget accepts: a binary, a single %Line{} / %Span{}, a full %Text{}, or a homogeneous list. When a %Text{} is supplied (or coerced into), its outer :style is merged with the widget's own :style and its :alignment is preferred over the widget's default when set.

Returns the widget struct directly; constructing fails fast with ArgumentError on a bad shape or invalid option (matching the rest of the widget surface — no {:ok, _} wrapper, no NIF call).

Examples

iex> ExRatatui.BigText.new("HELLO")
%ExRatatui.Widgets.BigText{
  lines: [
    %ExRatatui.Text.Line{
      spans: [%ExRatatui.Text.Span{content: "HELLO", style: %ExRatatui.Style{}}],
      style: %ExRatatui.Style{},
      alignment: nil
    }
  ],
  pixel_size: :full,
  alignment: :left,
  style: %ExRatatui.Style{},
  block: nil
}

iex> widget = ExRatatui.BigText.new("HI", pixel_size: :quadrant, alignment: :center)
iex> {widget.pixel_size, widget.alignment}
{:quadrant, :center}

iex> ExRatatui.BigText.new("X", pixel_size: :huge)
** (ArgumentError) expected :pixel_size to be one of [:full, :half_height, :half_width, :quadrant, :third_height, :sextant, :quarter_height, :octant], got: :huge