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 necessary, 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

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

GET:

Returns the image instance rendered by the widget.

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 placeholder 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 subclass 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:

clear_images	Clears on-screen images of graphics-based styles that support/require such an operation.
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.

clear_images(*widgets, now=False)

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

Parameters:

• widgets (term_image.widget.urwid.UrwidImage) –

  Image widgets to clear.

  All on-screen images rendered by each of the widgets are cleared, provided the widget was initialized with a term_image.image.KittyImage instance.

  If none is given, all images (of styles that support/require such an operation) on-screen are cleared.

• now (bool) – If True the images are cleared immediately. Otherwise, they’re cleared when next the output buffer is flushed, such as at the next screen redraw.

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

flush()

See the baseclass’ method for the description.

Important

Synchronized with lock_tty().

get_available_raw_input()

See the baseclass’ method for the description.

Important

Synchronized with lock_tty().

write(data)

See the baseclass’ method for the description.

Important

Synchronized with lock_tty().