Canvas Classes and Functions

Canvas Classes

class urwid.Canvas(value1=None, value2=None, value3=None)

base class for canvases

value1, value2, value3 – if not None, raise a helpful error:
the old Canvas class is now called TextCanvas.
finalize(widget, size, focus)

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, left, top, overlay_width, overlay_height)

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
text

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

translate_coords(dx, dy)

Return coords shifted by (dx, dy).

class urwid.TextCanvas(text=None, attr=None, cs=None, cursor=None, maxcol=None, check_width=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()

Return the screen column width of this canvas.

content(trim_left=0, trim_top=0, cols=None, rows=None, attr_map=None)

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)

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

Return the number of rows in this canvas.

translated_coords(dx, dy)

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

content(trim_left, trim_top, cols, rows, attr)

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

class urwid.SolidCanvas(fill_char, cols, rows)

A canvas filled completely with a single character.

content_delta(other)

Return the differences between other and this canvas.

class urwid.CompositeCanvas(canv=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()

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

content_delta(other)

Return the differences between other and this canvas.

fill_attr(a)

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

fill_attr_apply(mapping)

Apply an attribute-mapping dictionary to the canvas.

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

overlay(other, left, top)

Overlay other onto this canvas.

pad_trim_left_right(left, right)

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, bottom)

Pad or trim this canvas on the top and bottom.

set_depends(widget_list)

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, count=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)

Trim lines from the bottom of the canvas.

end – number of lines to remove from the end

CompositeCanvas Builders

urwid.CanvasCombine(l)

Stack canvases in l vertically and return resulting canvas.

Parameters:l –

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

Join canvases in l horizontally. Return result.

Parameters:l –

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, bottom_c, left, top)

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

Empty the cache.

classmethod fetch(widget, wcls, size, focus)

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)

Store a weakref to canvas in the cache.

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