ImageView

A widget that displays an image.

../../../_images/imageview.png

Usage

An ImageView provides a mechanism to display an Image as part of an interface.

import toga

my_image = toga.Image(self.paths.app / "brutus.png")
view = toga.ImageView(my_image)

Notes

  • An ImageView is not an interactive element - there is no on_press handler for ImageView. If you want a graphical element that can be clicked or pressed, try using a toga.Button that uses an toga.Icon.

  • The default size of the view is the size of the image, or 0x0 if image is None.

  • If an explicit width or height is specified, the size of the image will be fixed in that axis, and the size in the other axis will be determined by the image’s aspect ratio.

  • If an explicit width and height is specified, the image will be scaled to fill the described size without preserving the aspect ratio.

  • If an ImageView is given a style of flex=1, and doesn’t have an explicit size set along its container’s main axis, it will be allowed to expand and contract along that axis, with the size determined by the flex allocation.

    • If the cross axis size is unspecified, it will be determined by applying the image’s aspect ratio to the size allocated on the main axis.

    • If the cross axis has an explicit size, the image will be scaled to fill the available space so that the entire image can be seen, while preserving its aspect ratio. Any extra space will be distributed equally between both sides.

Reference

class toga.ImageView(image=None, id=None, style=None)

Bases: Widget

Create a new image view.

Parameters:

  • image (ImageContent | None) – The image to display. Can be any valid image content type; or None to display no image.

  • id – The ID for the widget.

  • style – A style object. If no style is provided, a default style will be applied to the widget.

as_image(format=toga.Image)

Return the image in the specified format.

Parameters:

format (type[ImageT]) – Format to provide. Defaults to Image; also supports PIL.Image.Image if Pillow is installed, as well as any image types defined by installed image format plugins.

Returns:

The image in the specified format.

Return type:

ImageT

property enabled: bool

Is the widget currently enabled? i.e., can the user interact with the widget?

ImageView widgets cannot be disabled; this property will always return True; any attempt to modify it will be ignored.

focus()

No-op; ImageView cannot accept input focus

property image: Image | None

The image to display.

When setting an image, you can provide any valid image content type; or None to clear the image view.