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: Sequence[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) → Iterable[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) → Iterable[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) → Iterable[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, wcls, size, focus) → 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)

Remove all canvases cached for widget.

classmethod store(wcls, 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)