Canvas Classes and Functions

Canvas Classes

class urwid.Canvas

base class for canvases

Base Canvas class

cols() → int

Return the screen column width of this canvas.

Raises:

NotImplementedError – the subclass does not report its own width.

content(trim_left: int = 0, trim_top: int = 0, cols: int = 0, rows: int = 0, attr: Mapping[Hashable, AttrSpec | str | None] | None = None) → Iterator[_ContentLine]

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

Raises:

NotImplementedError – the subclass does not implement the canvas content protocol.

content_delta(other: Canvas) → list[int] | Iterator[_ContentLine]

Delta between two canvases.

Returns:

a list of row deltas if other is None, otherwise an iterator of row deltas.

Raises:

NotImplementedError – the subclass does not implement the canvas content protocol.

Deprecated since version 4.0.3: Not used by the code base; there is no replacement. It will be removed in a future release.

property decoded_text: Sequence[str]

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

finalize(widget: AbstractWidget, 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.

Parameters:

  • widget – widget that rendered this canvas

  • size – size parameter passed to widget’s render method

  • focus – focus parameter passed to widget’s render method

Raises:

CanvasError – this canvas has already been finalized and can no longer be modified.

rows() → int

Return the screen row height of this canvas.

Raises:

NotImplementedError – the subclass does not report its own height.

set_cursor(c: tuple[int, int] | None) → None

Set the cursor position to (x, y), or remove it when c is None.

Raises:

CanvasError – this canvas has already been finalized and can no longer be modified.

set_pop_up(w: AbstractWidget, 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

Raises:

CanvasError – the canvas is already finalised, the position is negative or the overlay size is not positive

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) → _CanvasCoords

Return coords shifted by (dx, dy).

class urwid.TextCanvas(text: list[bytes] | None = None, attr: list[list[tuple[Hashable, 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

Parameters:

  • 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

Raises:

  • CanvasError – a line of text is not a plain string in the screen encoding, is wider than maxcol, or has an attribute or character set run extending beyond its text.

  • TypeError – maxcol is not an integer.

cols() → int

Return the screen column width of this canvas.

content(trim_left: int = 0, trim_top: int = 0, cols: int = 0, rows: int = 0, attr: Mapping[object, AttrSpec | str | None] | None = None) → Iterator[_ContentLine]

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.

Raises:

ValueError – trim_left or trim_top, together with cols or rows, selects a region outside this canvas.

content_delta(other: Canvas) → list[int] | Iterator[_ContentLine]

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().

Deprecated since version 4.0.3: Not used by the code base; there is no replacement. It will be removed in a future release.

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

cols() → NoReturn

Raise NotImplementedError: a BlankCanvas does not know its own size.

Raises:

NotImplementedError – a BlankCanvas does not know its own size.

content(trim_left: int = 0, trim_top: int = 0, cols: int = 0, rows: int = 0, attr: Mapping[Hashable, AttrSpec | str | None] | None = None) → Iterator[_ContentLine]

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

content_delta(other: Canvas) → NoReturn

Raise NotImplementedError: a BlankCanvas does not know its own size.

Deprecated since version 4.0.3: Not used by the code base; there is no replacement. It will be removed in a future release.

Raises:

NotImplementedError – a BlankCanvas does not know its own size.

rows() → NoReturn

Raise NotImplementedError: a BlankCanvas does not know its own size.

Raises:

NotImplementedError – a BlankCanvas does not know its own size.

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

A canvas filled completely with a single character.

Build a canvas of cols by rows screen cells, every one holding fill_char.

Raises:

ValueError – fill_char is not exactly one screen column wide.

cols() → int

Return the screen column width of this canvas.

Raises:

NotImplementedError – the subclass does not report its own width.

content(trim_left: int = 0, trim_top: int = 0, cols: int | None = None, rows: int | None = None, attr: Mapping[Hashable, AttrSpec | str | None] | None = None) → Iterator[_ContentLine]

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

Raises:

NotImplementedError – the subclass does not implement the canvas content protocol.

content_delta(other: Canvas) → list[int] | Iterator[_ContentLine]

Return the differences between other and this canvas.

Deprecated since version 4.0.3: Not used by the code base; there is no replacement. It will be removed in a future release.

rows() → int

Return the screen row height of this canvas.

Raises:

NotImplementedError – the subclass does not report its own height.

class urwid.CompositeCanvas(canv: Canvas | None = None)

class for storing a combination of canvases

Parameters:

canv – a Canvas object to wrap this CompositeCanvas around.

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

cols() → int

Return the screen column width of this canvas.

Raises:

TypeError – the shards add up to a non-integer column count.

content(trim_left: int = 0, trim_top: int = 0, cols: int = 0, rows: int = 0, attr: Mapping[Hashable, AttrSpec | str | None] | None = None) → Iterator[_ContentLine]

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

All parameters are ignored.

content_delta(other: Canvas) → Iterator[_ContentLine]

Return the differences between other and this canvas.

Deprecated since version 4.0.3: Not used by the code base; there is no replacement. It will be removed in a future release.

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, Hashable]) → None

Apply an attribute-mapping dictionary to the canvas.

Parameters:

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

Raises:

CanvasError – this canvas has already been finalized and can no longer be modified.

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

Overlay other onto this canvas.

Raises:

  • CanvasError – this canvas has already been finalized and can no longer be modified.

  • ValueError – other does not fit within this canvas at the given left and top offsets.

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

Raises:

CanvasError – this canvas has already been finalized and can no longer be modified.

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

Pad or trim this canvas on the top and bottom.

Raises:

CanvasError – this canvas has already been finalized and can no longer be modified.

rows() → int

Return the screen row height of this canvas.

Raises:

TypeError – a shard carries a non-integer row count.

set_depends(widget_list: Sequence[AbstractWidget]) → 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.

Raises:

CanvasError – this canvas has already been finalized and can no longer be modified.

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

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

Parameters:

  • top – number of lines to remove from top

  • count – number of lines to keep, or None for all the rest

Raises:

  • ValueError – top is negative, or is at least the number of rows in this canvas.

  • CanvasError – this canvas has already been finalized and can no longer be modified.

trim_end(end: int) → None

Trim lines from the bottom of the canvas.

Parameters:

end – number of lines to remove from the end

Raises:

  • ValueError – end is not positive, or is greater than the number of rows in this canvas.

  • CanvasError – this canvas has already been finalized and can no longer be modified.

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: CompositeCanvas, 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: AbstractWidget, wcls: type[AbstractWidget], size: tuple[int, int] | tuple[int] | tuple[()], focus: bool) → Canvas | None

Return the cached canvas or None.

Parameters:

  • widget – widget object requested

  • wcls – widget class that contains render() function

  • size – size parameter passed to the widget’s render method

  • focus – focus parameter passed to the widget’s render method

classmethod invalidate(widget: AbstractWidget) → None

Remove all canvases cached for widget.

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

Store a weakref to canvas in the cache.

Parameters:

  • wcls – widget class that contains render() function

  • canvas – rendered canvas with widget_info (widget, size, focus)

Raises:

TypeError – canvas has not been finalized, so it carries no widget_info.