Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# `widget` Module

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

  Bases: `urwid.widget.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.

  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.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.display._posix_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.

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