TermUI.Widgets.Canvas (TermUI v0.2.0)

View Source

Canvas widget for custom drawing with direct buffer access.

Canvas provides a drawing surface with primitives for lines, rectangles, text, and Braille graphics. Useful for custom visualizations, charts, diagrams, and other graphics that don't fit standard widget patterns.

Usage

Canvas.new(
  width: 40,
  height: 20,
  on_draw: fn canvas ->
    canvas
    |> Canvas.draw_rect(0, 0, 10, 5, "─", "│", "┌", "┐", "└", "┘")
    |> Canvas.draw_text(2, 2, "Hello")
  end
)

Features

  • Direct character buffer access
  • Drawing primitives: line, rect, text
  • Braille graphics for sub-character resolution
  • Clear and fill operations
  • Custom render callback

Braille Graphics

Each character cell contains a 2x4 Braille dot matrix, providing higher resolution for plotting and charts.

Summary

Functions

braille_resolution(state)

Gets the Braille resolution (dots) for the canvas.

clear(state)

Clears the canvas with the default character.

clear_braille(state)

Clears all Braille dots.

clear_dot(state, x, y)

Clears a Braille dot at sub-character position.

dots_to_braille(dots)

Converts dots to a Braille character.

draw(width, height, draw_fn)

Creates a canvas and draws on it with a function.

draw_braille_line(state, x1, y1, x2, y2)

Draws a Braille line between two points.

draw_hline(state, x, y, length, char \\ "─")

Draws a horizontal line.

draw_line(state, x1, y1, x2, y2, char \\ "•")

Draws a line between two points using Bresenham's algorithm.

draw_rect(state, x, y, width, height, border \\ %{})

Draws a rectangle outline.

draw_text(state, x, y, text)

Draws text at a position.

draw_vline(state, x, y, length, char \\ "│")

Draws a vertical line.

empty_braille()

Returns empty Braille character.

fill(state, char)

Fills the canvas with a character.

fill_rect(state, x, y, width, height, char)

Fills a rectangle with a character.

full_braille()

Returns full Braille character (all dots set).

get_char(state, x, y)

Gets a character at a position.

new(opts)

Creates new Canvas widget props.

resize(state, width, height)

Updates the canvas dimensions.

set_char(state, x, y, char)

Sets a character at a position.

set_dot(state, x, y)

Sets a Braille dot at sub-character position.

to_strings(state)

Renders the canvas state to a list of strings.

Functions

braille_resolution(state)

@spec braille_resolution(map()) :: {integer(), integer()}

Gets the Braille resolution (dots) for the canvas.

clear(state)

@spec clear(map()) :: map()

Clears the canvas with the default character.

clear_braille(state)

@spec clear_braille(map()) :: map()

Clears all Braille dots.

clear_dot(state, x, y)

@spec clear_dot(map(), integer(), integer()) :: map()

Clears a Braille dot at sub-character position.

dots_to_braille(dots)

@spec dots_to_braille([{integer(), integer()}]) :: String.t()

Converts dots to a Braille character.

Takes a list of {x, y} coordinates within a 2x4 cell.

draw(width, height, draw_fn)

@spec draw(integer(), integer(), (map() -> map())) :: map()

Creates a canvas and draws on it with a function.

draw_braille_line(state, x1, y1, x2, y2)

@spec draw_braille_line(map(), integer(), integer(), integer(), integer()) :: map()

Draws a Braille line between two points.

Coordinates are in sub-character (dot) space:

  • X resolution: width * 2
  • Y resolution: height * 4

draw_hline(state, x, y, length, char \\ "─")

@spec draw_hline(map(), integer(), integer(), integer(), String.t()) :: map()

Draws a horizontal line.

draw_line(state, x1, y1, x2, y2, char \\ "•")

@spec draw_line(map(), integer(), integer(), integer(), integer(), String.t()) ::
  map()

Draws a line between two points using Bresenham's algorithm.

draw_rect(state, x, y, width, height, border \\ %{})

@spec draw_rect(map(), integer(), integer(), integer(), integer(), map()) :: map()

Draws a rectangle outline.

Border Options

The border map can contain:

  • :h - Horizontal character (default: "─")
  • :v - Vertical character (default: "│")
  • :tl - Top-left corner (default: "┌")
  • :tr - Top-right corner (default: "┐")
  • :bl - Bottom-left corner (default: "└")
  • :br - Bottom-right corner (default: "┘")

draw_text(state, x, y, text)

@spec draw_text(map(), integer(), integer(), String.t()) :: map()

Draws text at a position.

draw_vline(state, x, y, length, char \\ "│")

@spec draw_vline(map(), integer(), integer(), integer(), String.t()) :: map()

Draws a vertical line.

empty_braille()

@spec empty_braille() :: String.t()

Returns empty Braille character.

fill(state, char)

@spec fill(map(), String.t()) :: map()

Fills the canvas with a character.

fill_rect(state, x, y, width, height, char)

@spec fill_rect(map(), integer(), integer(), integer(), integer(), String.t()) ::
  map()

Fills a rectangle with a character.

full_braille()

@spec full_braille() :: String.t()

Returns full Braille character (all dots set).

get_char(state, x, y)

@spec get_char(map(), integer(), integer()) :: String.t() | nil

Gets a character at a position.

new(opts)

@spec new(keyword()) :: map()

Creates new Canvas widget props.

Options

  • :width - Canvas width in characters (default: 40)
  • :height - Canvas height in characters (default: 20)
  • :default_char - Character to fill canvas (default: " ")
  • :on_draw - Callback function to draw on canvas

resize(state, width, height)

@spec resize(map(), integer(), integer()) :: map()

Updates the canvas dimensions.

set_char(state, x, y, char)

@spec set_char(map(), integer(), integer(), String.t()) :: map()

Sets a character at a position.

set_dot(state, x, y)

@spec set_dot(map(), integer(), integer()) :: map()

Sets a Braille dot at sub-character position.

Each character cell is 2 dots wide and 4 dots high.

to_strings(state)

@spec to_strings(map()) :: [String.t()]

Renders the canvas state to a list of strings.