TTkCanvas🌢️

class TTkCanvas(width: int = 0, height: int = 0)[source]🌢️

Bases: object

TTkCanvas:

A low-level drawing surface that stores characters and colors before they are composed into widgets or flushed to the terminal.

Parameters:
  • width (int) – the width of the Canvas

  • height (int) – the height of the Canvas

Methods🌢️

clean() → None[source]🌢️

Clears the canvas content using either blanks or transparent cells.

cleanBuffers() → None[source]🌢️

Resets the secondary buffers used by buffered terminal painting.

copy() → TTkCanvas[source]🌢️

Creates a detached copy of the canvas content.

Returns:

a new canvas with duplicated size and buffers

Return type:

TTkCanvas

copyBuffers() → Tuple[List[List[str]], List[List[TTkColor]]][source]🌢️

Duplicates the current character and color buffers.

Returns:

copies of the data and color buffers

Return type:

tuple[list[list[str]], list[list[TTkColor]]]

drawBox(pos: ~typing.Tuple[int, int], size: ~typing.Tuple[int, int], color: ~TermTk.TTkCore.color.TTkColor = <TermTk.TTkCore.color.TTkColor object>, grid: int = 0) → None[source]🌢️

Draws a rectangular box using the configured grid theme.

Parameters:
  • pos (tuple[int, int]) – the top-left position of the box

  • size (tuple[int, int]) – the width and height of the box

  • color (TTkColor) – the color applied to the box border

  • grid (int) – the themed grid variant to use

drawBoxTitle(pos: ~typing.Tuple[int, int], size: ~typing.Tuple[int, int], text: ~TermTk.TTkCore.string.TTkString, align: ~TermTk.TTkCore.constant.TTkConstant.Alignment = Alignment.CENTER_ALIGN, color: ~TermTk.TTkCore.color.TTkColor = <TermTk.TTkCore.color.TTkColor object>, colorText: ~TermTk.TTkCore.color.TTkColor = <TermTk.TTkCore.color.TTkColor object>) → None[source]🌢️

Draws a titled label embedded into the top border of a box.

Parameters:
  • pos (tuple[int, int]) – the top-left position of the surrounding box

  • size (tuple[int, int]) – the size of the surrounding box

  • text (TTkString) – the title text to render

  • align (TTkK.Alignment) – the title alignment along the top border

  • color (TTkColor) – the border color around the title

  • colorText (TTkColor) – the color of the title text

drawButtonBox(pos: ~typing.Tuple[int, int], size: ~typing.Tuple[int, int], color: ~TermTk.TTkCore.color.TTkColor = <TermTk.TTkCore.color.TTkColor object>, grid: int = 0) → None[source]🌢️

Draws a button-style border using the button box theme.

Parameters:
  • pos (tuple[int, int]) – the top-left position of the box

  • size (tuple[int, int]) – the width and height of the box

  • color (TTkColor) – the color applied to the border

  • grid (int) – the themed button box variant to use

drawChar(pos: ~typing.Tuple[int, int], char: str, color: ~TermTk.TTkCore.color.TTkColor = <TermTk.TTkCore.color.TTkColor object>) → None[source]🌢️

Draws a single character at the given position.

Parameters:
  • pos (tuple[int, int]) – the target position

  • char (str) – the character to draw

  • color (TTkColor) – the color applied to the character

drawGrid(pos: ~typing.Tuple[int, int], size: ~typing.Tuple[int, int], hlines: ~typing.List[int] = [], vlines: ~typing.List[int] = [], color: ~TermTk.TTkCore.color.TTkColor = <TermTk.TTkCore.color.TTkColor object>, grid: int = 0) → None[source]🌢️

Draws a bordered grid with optional internal horizontal and vertical lines.

Parameters:
  • pos (tuple[int, int]) – the top-left position of the grid

  • size (tuple[int, int]) – the width and height of the grid

  • hlines (list[int]) – row offsets for inner horizontal separators

  • vlines (list[int]) – column offsets for inner vertical separators

  • color (TTkColor) – the color applied to the grid glyphs

  • grid (int) – the themed grid variant to use

drawHChart(pos: ~typing.Tuple[int, int], values: ~typing.Tuple[~typing.List[int], ~typing.List[int]], zoom: float = 1.0, color: ~TermTk.TTkCore.color.TTkColor = <TermTk.TTkCore.color.TTkColor object>) → None[source]🌢️

Draws a compact two-series vertical chart using braille cells.

Parameters:
  • pos (tuple[int, int]) – the baseline position of the chart

  • values (tuple[list[int], list[int]]) – the two value series to combine into each braille cell

  • zoom (float) – a scale factor applied before rasterizing the chart

  • color (TTkColor) – the color applied to the chart glyphs

drawHLine(pos: ~typing.Tuple[int, int], size: int, color: ~TermTk.TTkCore.color.TTkColor = <TermTk.TTkCore.color.TTkColor object>) → None[source]🌢️

Draws a themed horizontal line segment.

Parameters:
  • pos (tuple[int, int]) – the left position of the line

  • size (int) – the width of the line

  • color (TTkColor) – the color used for the line glyphs

drawMenuBarBg(pos: ~typing.Tuple[int, int], size: int, color: ~TermTk.TTkCore.color.TTkColor = <TermTk.TTkCore.color.TTkColor object>) → None[source]🌢️

Draws the themed background strip for a menu bar.

Parameters:
  • pos (tuple[int, int]) – the starting position of the menu bar background

  • size (int) – the total width of the menu bar background

  • color (TTkColor) – the color applied to the background glyphs

drawScroll(pos: ~typing.Tuple[int, int], size: int, slider: ~typing.Tuple[int, int], orientation: ~TermTk.TTkCore.constant.TTkConstant.Direction, color: ~TermTk.TTkCore.color.TTkColor = <TermTk.TTkCore.color.TTkColor object>) → None[source]🌢️

Draws a horizontal or vertical scrollbar.

Parameters:
  • pos (tuple[int, int]) – the top-left position of the scrollbar

  • size (int) – the total length of the scrollbar including arrow cells

  • slider (tuple[int, int]) – the slider start and end positions relative to pos

  • orientation (TTkK.Direction) – the scrollbar orientation

  • color (TTkColor) – the color applied to the scrollbar glyphs

drawTTkString(pos: ~typing.Tuple[int, int], text: ~TermTk.TTkCore.string.TTkString, width: int | None = None, color: ~TermTk.TTkCore.color.TTkColor = <TermTk.TTkCore.color.TTkColor object>, alignment: ~TermTk.TTkCore.constant.TTkConstant.Alignment = Alignment.NONE, forceColor: bool = False) → None[source]🌢️

Draws a TTkString with alignment and optional color override.

This method keeps a dedicated fast path because text drawing is used in most widgets and needs to minimize conversion overhead.

Parameters:
  • pos (tuple[int, int]) – the top-left position where the string is drawn

  • text (TTkString) – the formatted text object to render

  • width (int | None) – the output width, defaults to the string terminal width

  • color (TTkColor) – an additional color merged with the string colors

  • alignment (TTkK.Alignment) – the alignment used inside width

  • forceColor (bool) – True to ignore embedded string colors and use only color

drawTableLine(pos: Tuple[int, int], items: List[str], sizes: List[int], colors: List[TTkColor], alignments: List[Alignment]) → None[source]🌢️

Draws a single row of table cells with per-column formatting.

Parameters:
  • pos (tuple[int, int]) – the starting position of the first cell

  • items (list[str]) – the strings to render in each column

  • sizes (list[int]) – the width of each column

  • colors (list[TTkColor]) – the color used for each column

  • alignments (list[TTkK.Alignment]) – the alignment used for each column

drawText(text: str = '', pos: ~typing.Tuple[int, int] = (0, 0), width: int | None = None, color: ~TermTk.TTkCore.color.TTkColor = <TermTk.TTkCore.color.TTkColor object>, alignment: ~TermTk.TTkCore.constant.TTkConstant.Alignment = Alignment.NONE, forceColor: bool = False) → None[source]🌢️

Draws plain text with optional alignment and color.

This method keeps a dedicated fast path because text drawing is used in most widgets and needs to minimize conversion overhead.

Parameters:
  • text (str) – the string to render

  • pos (tuple[int, int]) – the top-left position where the text is drawn

  • width (int | None) – the output width, defaults to the text length

  • color (TTkColor) – the color applied to the text

  • alignment (TTkK.Alignment) – the alignment used inside width

  • forceColor (bool) – kept for API parity with drawTTkString()

drawVLine(pos: ~typing.Tuple[int, int], size: int, color: ~TermTk.TTkCore.color.TTkColor = <TermTk.TTkCore.color.TTkColor object>) → None[source]🌢️

Draws a themed vertical line segment.

Parameters:
  • pos (tuple[int, int]) – the top position of the line

  • size (int) – the height of the line

  • color (TTkColor) – the color used for the line glyphs

enableDoubleBuffer() → None[source]🌢️

Initializes the secondary buffer used for buffered terminal updates.

fill(pos: ~typing.Tuple[int, int] = (0, 0), size: ~typing.Tuple[int, int] | None = None, char: str = ' ', color: ~TermTk.TTkCore.color.TTkColor = <TermTk.TTkCore.color.TTkColor object>) → None[source]🌢️

Fills a rectangular region with a character and color.

Parameters:
  • pos (tuple[int, int]) – the top-left position of the fill area

  • size (tuple[int, int] | None) – the width and height of the fill area, defaults to the full canvas

  • char (str) – the character written into each cell

  • color (TTkColor) – the color applied to the filled cells

hide() → None[source]🌢️

Marks the canvas as hidden so draw operations become no-ops.

paintCanvas(canvas: TTkCanvas, geom: Tuple[int, int, int, int], _slice: Tuple[int, int, int, int], bound: Tuple[int, int, int, int]) → None[source]🌢️

Paints another canvas onto this one inside the given geometry and bounds.

Parameters:
  • canvas (TTkCanvas) – the source canvas to compose onto this canvas

  • geom (tuple[int, int, int, int]) – destination geometry as (x, y, width, height)

  • _slice (tuple[int, int, int, int]) – reserved slice information for compatibility with callers

  • bound (tuple[int, int, int, int]) – clipping bounds as (x, y, width, height)

pushToTerminal(x: int, y: int, w: int, h: int) → None[source]🌢️

Pushes the full canvas to the terminal without diffing.

Parameters:
  • x (int) – unused compatibility parameter for the destination x coordinate

  • y (int) – unused compatibility parameter for the destination y coordinate

  • w (int) – unused compatibility parameter for the destination width

  • h (int) – unused compatibility parameter for the destination height

pushToTerminalBuffered(x: int, y: int, w: int, h: int) → None[source]🌢️

Pushes only changed cells to the terminal using the secondary buffer.

Parameters:
  • x (int) – unused compatibility parameter for the destination x coordinate

  • y (int) – unused compatibility parameter for the destination y coordinate

  • w (int) – unused compatibility parameter for the destination width

  • h (int) – unused compatibility parameter for the destination height

pushToTerminalBufferedNew(x: int, y: int, w: int, h: int) → None[source]🌢️

Pushes buffered terminal updates with run-length compression.

Parameters:
  • x (int) – unused compatibility parameter for the destination x coordinate

  • y (int) – unused compatibility parameter for the destination y coordinate

  • w (int) – unused compatibility parameter for the destination width

  • h (int) – unused compatibility parameter for the destination height

resize(w: int, h: int) → None[source]🌢️

resize the canvas keeping or cutting the current one

Parameters:
  • w – the width of the new canvas

  • h – the height of the new canvas

setTransparent(tr: bool = True) → None[source]🌢️

Enables or disables transparent composition for this canvas.

Parameters:

tr (bool) – True to preserve destination cells where nothing is drawn

show() → None[source]🌢️

Marks the canvas as visible again.

size() → Tuple[int, int][source]🌢️

Returns the current canvas size.

Returns:

the width and height of the canvas

Return type:

tuple[int, int]

toAnsi() → str[source]🌢️

Serializes the full canvas content into ANSI text.

Returns:

the canvas rendered as newline-separated ANSI escape sequences

Return type:

str

transparent() → bool[source]🌢️

Returns whether the canvas treats empty cells as transparent.

Returns:

True when empty cells preserve the destination canvas

Return type:

bool

updateSize() → None[source]🌢️

Rebuilds the internal buffers when the requested canvas size changes.