# Canvas Classes and Functions

## Canvas Classes

class urwid.Canvas

  base class for canvases

  Base Canvas class

  property decoded_text: Sequence[str]

    Decoded text content of the canvas as a sequence of strings, one for each row.

  finalize(widget: Widget, size: tuple[()] | tuple[int] | tuple[int, int], focus: bool) → None

    Mark this canvas as finalized (should not be any future changes to its content). This is required before caching the canvas. This happens automatically after a widget’s ‘render call returns the canvas thanks to some metaclass magic.

    widget – widget that rendered this canvas size – size parameter passed to widget’s render method focus – focus parameter passed to widget’s render method

  set_pop_up(w: Widget, left: int, top: int, overlay_width: int, overlay_height: int) → None

    This method adds pop-up information to the canvas. This information is intercepted by a PopUpTarget widget higher in the chain to display a pop-up at the given (left, top) position relative to the current canvas.

    Parameters:

      - w (widget) – widget to use for the pop-up

      - left (int) – x position for left edge of pop-up >= 0

      - top (int) – y position for top edge of pop-up >= 0

      - overlay_width (int) – width of overlay in screen columns > 0

      - overlay_height (int) – height of overlay in screen rows > 0

  property text: list[bytes]

    Return the text content of the canvas as a list of strings, one for each row.

  translate_coords(dx: int, dy: int) → dict[str, tuple[int, int, tuple[Widget, int, int]]]

    Return coords shifted by (dx, dy).

class urwid.TextCanvas(text: list[bytes] | None = None, attr: list[list[tuple[Hashable | None, int]]] | None = None, cs: list[list[tuple[Literal['0', 'U'] | None, int]]] | None = None, cursor: tuple[int, int] | None = None, maxcol: int | None = None, check_width: bool = True)

  class for storing rendered text and attributes

  text – list of strings, one for each line attr – list of run length encoded attributes for text cs – list of run length encoded character set for text cursor – (x,y) of cursor or None maxcol – screen columns taken by this canvas check_width – check and fix width of all lines in text

  cols() → int

    Return the screen column width of this canvas.

  content(trim_left: int = 0, trim_top: int = 0, cols: int | None = 0, rows: int | None = 0, attr=None) → Iterator[tuple[object, Literal['0', 'U'] | None, bytes]]

    Return the canvas content as a list of rows where each row is a list of (attr, cs, text) tuples.

    trim_left, trim_top, cols, rows may be set by CompositeCanvas when rendering a partially obscured canvas.

  content_delta(other: Canvas)

    Return the differences between other and this canvas.

    If other is the same object as self this will return no differences, otherwise this is the same as calling content().

  rows() → int

    Return the number of rows in this canvas.

  translated_coords(dx: int, dy: int) → tuple[int, int] | None

    Return cursor coords shifted by (dx, dy), or None if there is no cursor.

class urwid.BlankCanvas

  a canvas with nothing on it, only works as part of a composite canvas since it doesn’t know its own size

  Base Canvas class

  content(trim_left: int = 0, trim_top: int = 0, cols: int | None = 0, rows: int | None = 0, attr=None) → Iterator[list[tuple[object, Literal['0', 'U'] | None, bytes]]]

    return (cols, rows) of spaces with default attributes.

class urwid.SolidCanvas(fill_char: str | bytes, cols: int, rows: int)

  A canvas filled completely with a single character.

  Base Canvas class

  content_delta(other)

    Return the differences between other and this canvas.

class urwid.CompositeCanvas(canv: Canvas = None)

  class for storing a combination of canvases

  canv – a Canvas object to wrap this CompositeCanvas around.

  if canv is a CompositeCanvas, make a copy of its contents

  content(trim_left: int = 0, trim_top: int = 0, cols: int | None = None, rows: int | None = None, attr=None) → Iterator[list[tuple[object, Literal['0', 'U'] | None, bytes]]]

    Return the canvas content as a list of rows where each row is a list of (attr, cs, text) tuples.

  content_delta(other: Canvas)

    Return the differences between other and this canvas.

  fill_attr(a: Hashable) → None

    Apply attribute a to all areas of this canvas with default attribute currently set to None, leaving other attributes intact.

  fill_attr_apply(mapping: dict[Hashable | None, Hashable]) → None

    Apply an attribute-mapping dictionary to the canvas.

    mapping – dictionary of original-attribute:new-attribute items

  overlay(other: CompositeCanvas, left: int, top: int) → None

    Overlay other onto this canvas.

  pad_trim_left_right(left: int, right: int) → None

    Pad or trim this canvas on the left and right

    values > 0 indicate screen columns to pad values < 0 indicate screen columns to trim

  pad_trim_top_bottom(top: int, bottom: int) → None

    Pad or trim this canvas on the top and bottom.

  set_depends(widget_list: Sequence[Widget]) → None

    Explicitly specify the list of widgets that this canvas depends on. If any of these widgets change this canvas will have to be updated.

  trim(top: int, count: int | None = None) → None

    Trim lines from the top and/or bottom of canvas.

    top – number of lines to remove from top count – number of lines to keep, or None for all the rest

  trim_end(end: int) → None

    Trim lines from the bottom of the canvas.

    end – number of lines to remove from the end

## CompositeCanvas Builders

urwid.CanvasCombine(canvas_info: Iterable[tuple[Canvas, Any, bool]]) → CompositeCanvas

  Stack canvases in l vertically and return resulting canvas.

  Parameters:

    canvas_info –

    list of (canvas, position, focus) tuples:

    position

      a value that widget.set_focus will accept or None if not allowed

    focus

      True if this canvas is the one that would be in focus if the whole widget is in focus

urwid.CanvasJoin(canvas_info: Iterable[tuple[Canvas, Any, bool, int]]) → CompositeCanvas

  Join canvases in l horizontally. Return result.

  Parameters:

    canvas_info –

    list of (canvas, position, focus, cols) tuples:

    position

      value that widget.set_focus will accept or None if not allowed

    focus

      True if this canvas is the one that would be in focus if the whole widget is in focus

    cols

      is the number of screen columns that this widget will require, if larger than the actual canvas.cols() value then this widget will be padded on the right.

urwid.CanvasOverlay(top_c: Canvas, bottom_c: Canvas, left: int, top: int) → CompositeCanvas

  Overlay canvas top_c onto bottom_c at position (left, top).

## CanvasCache

class urwid.CanvasCache

  Cache for rendered canvases. Automatically populated and accessed by Widget render() MetaClass magic, cleared by Widget._invalidate().

  Stores weakrefs to the canvas objects, so an external class must maintain a reference for this cache to be effective. At present the Screen classes store the last topmost canvas after redrawing the screen, keeping the canvases from being garbage collected.

  _widgets[widget] = {(wcls, size, focus): weakref.ref(canvas), …} _refs[weakref.ref(canvas)] = (widget, wcls, size, focus) _deps[widget} = [dependent_widget, …]

  classmethod clear() → None

    Empty the cache.

  classmethod fetch(widget: Widget, wcls: type[Widget], size, focus: bool) → Canvas | None

    Return the cached canvas or None.

    widget – widget object requested wcls – widget class that contains render() function size, focus – render() parameters

  classmethod invalidate(widget: Widget) → None

    Remove all canvases cached for widget.

  classmethod store(wcls: type[Widget], canvas: Canvas) → None

    Store a weakref to canvas in the cache.

    wcls – widget class that contains render() function canvas – rendered canvas with widget_info (widget, size, focus)