widget Module

Classes:

UrwidImage	Image widget (box/flow) for the urwid TUI framework.
UrwidImageCanvas	Image canvas for the urwid TUI framework.
UrwidImageScreen	A screen that supports drawing images.

class term_image.widget.UrwidImage(image, format_spec='', *, upscale=False)

Bases: urwid.widget.Widget

Image widget (box/flow) for the urwid TUI framework.

Parameters:

• image (BaseImage) – The image to be rendered by the widget.

• format_spec (str) – Render format specifier. Padding width and height are ignored.

• upscale (bool) – If True, the image will be upscaled to fit maximally within the available size, if neccessary, while still preserving the aspect ratio. Otherwise, the image is never upscaled.

Raises:

• TypeError – An argument is of an inappropriate type.

• ValueError – An argument is of an appropriate type but has an unexpected/invalid value.

• term_image.exceptions.StyleError – Invalid style-specific format specifier.

• term_image.exceptions.UrwidImageError – Too many image widgets rendering images with the kitty render style.

Any ample space in the widget’s render size is filled with spaces.

For animated images, the current frame (at render-time) is rendered.

Tip

If image is of a graphics-based render style and the widget is being used as or within a flow widget, with overlays or in any other case where the canvas will require vertical trimming, make sure to use a render method that splits images across lines such as the LINES render method for kitty and iterm2 render styles.

Note

• The z-index style-specific format spec field for KittyImage is ignored as this is used internally.

• A maximum of 2**32 - 2 instances initialized with KittyImage instances may exist at the same time.

Important

This is defined if and only if the urwid package is available.

Instance Properties:

image

The image rendered by the widget.

Instance Methods:

clear

Clears all images drawn by the widget, if the image rendered by the widget is of the kitty render style.

Static Methods:

clear_all

Clears all on-screen images of graphics-based styles that support/require such an operation.

Class Methods:

set_error_placeholder

Sets the widget to be rendered in place of an image when rendering fails.

property image

The image rendered by the widget.

Type:

BaseImage

clear(*, now=False)

Clears all images drawn by the widget, if the image rendered by the widget is of the kitty render style.

Parameters:

now (bool) – If True the images are cleared immediately. Otherwise they’re cleared just before the next screen redraw.

static clear_all(*, now=False)

Clears all on-screen images of graphics-based styles that support/require such an operation.

Parameters:

now (bool) – If True the images are cleared immediately. Otherwise they’re cleared just before the next screen redraw.

classmethod set_error_placeholder(widget)

Sets the widget to be rendered in place of an image when rendering fails.

Parameters:

widget (urwid.widget.Widget | None) – The placholder widget or None to remove the placeholder.

Raises:

TypeError – widget is not an urwid widget.

If set, any exception raised during rendering is suppressed and the placeholder is rendered in place of the image.

class term_image.widget.UrwidImageCanvas(render, size, image_size)

Bases: urwid.canvas.Canvas

Image canvas for the urwid TUI framework.

Parameters:

• render (str) – The rendered image.

• size (Tuple[int, int]) – The canvas size. Also, the size of the rendered (and formatted) image.

• image_size (Tuple[int, int]) – The size with which the image was rendered (excluding padding).

Note

The canvas outputs blanks (spaces) for graphics-based images when horizontal trimming is required (e.g when a widget is laid over an image). This is temporary as horizontal trimming will be implemented in the future.

This canvas is intended to be rendered by UrwidImage (or a sublass of it) only. Otherwise, the output isn’t guaranteed to be as expected.

Warning

The constructor of this class performs NO argument validation at all for the sake of performance. If instantiating this class directly, make sure to pass appropriate arguments or create subclass, override the constructor and perform the validation.

Important

This is defined if and only if the urwid package is available.

class term_image.widget.UrwidImageScreen(*args, **kwargs)

Bases: urwid.raw_display.Screen

A screen that supports drawing images.

It monitors images of some graphics-based render styles and clears them off the screen when necessary (e.g at startup, when scrolling, upon terminal resize and at exit).

See the baseclass for further description.

Important

This is defined if and only if the urwid package is available.

Instance Methods:

draw_screen	See the description of the baseclass' method.
flush	See the baseclass' method for the description.
get_available_raw_input	See the baseclass' method for the description.
write	See the baseclass' method for the description.

draw_screen(maxres, canvas)

See the description of the baseclass’ method.

Synchronizes output on terminal emulators that support the feature to reduce/eliminate image flickering and screen tearing.

Important

Synchronized with term_image.utils.lock_tty().

flush()

See the baseclass’ method for the description.

Important

Synchronized with term_image.utils.lock_tty().

get_available_raw_input()

See the baseclass’ method for the description.

Important

Synchronized with term_image.utils.lock_tty().

write(data)

See the baseclass’ method for the description.

Important

Synchronized with term_image.utils.lock_tty().