Skip to content

ImageView

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

Bases: Widget

Source code in core/src/toga/widgets/imageview.py 
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
class ImageView(Widget):
    def __init__(
        self,
        image: ImageContentT | None = None,
        id: str | None = None,
        style: StyleT | None = None,
        **kwargs,
    ):
        """Create a new image view.

        :param image: The image to display. Can be any valid
            [image content][toga.images.ImageContentT] type; or [`None`][] to
            display no image.
        :param id: The ID for the widget.
        :param style: A style object. If no style is provided, a default style will be
            applied to the widget.
        :param kwargs: Initial style properties.
        """
        # Prime the image attribute
        self._image = None

        super().__init__(id, style, **kwargs)

        self.image = image

    def _create(self) -> Any:
        return self.factory.ImageView(interface=self)

    @property
    def enabled(self) -> Literal[True]:
        """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.
        """
        return True

    @enabled.setter
    def enabled(self, value: object) -> None:
        pass

    def focus(self) -> None:
        """No-op; ImageView cannot accept input focus."""
        pass

    @property
    def image(self) -> toga.Image | None:
        """The image to display.

        When setting an image, you can provide any valid
        [image content][toga.images.ImageContentT] type;
        or [`None`][] to clear the image view.
        """
        return self._image

    @image.setter
    def image(self, image: ImageContentT) -> None:
        if isinstance(image, toga.Image):
            self._image = image
        elif image is None:
            self._image = None
        else:
            self._image = toga.Image(image)

        self._impl.set_image(self._image)
        self.refresh()

    def as_image(self, format: type[ImageT] = toga.Image) -> ImageT:
        """Return the image in the specified format.

        :param format: Format to provide. Defaults to [`Image`][toga.images.Image]; also
            supports [`PIL.Image.Image`][] if Pillow is installed, as well as any image
            types defined by installed [image format plugins][image-format-plugins].
        :returns: The image in the specified format.
        """
        return self.image.as_format(format)

enabled property writable

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.

image property writable

The image to display.

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

__init__(image=None, id=None, style=None, **kwargs)

Create a new image view.

:param image: The image to display. Can be any valid image content type; or [None][] to display no image. :param id: The ID for the widget. :param style: A style object. If no style is provided, a default style will be applied to the widget. :param kwargs: Initial style properties.

Source code in core/src/toga/widgets/imageview.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def __init__(
    self,
    image: ImageContentT | None = None,
    id: str | None = None,
    style: StyleT | None = None,
    **kwargs,
):
    """Create a new image view.

    :param image: The image to display. Can be any valid
        [image content][toga.images.ImageContentT] type; or [`None`][] to
        display no image.
    :param id: The ID for the widget.
    :param style: A style object. If no style is provided, a default style will be
        applied to the widget.
    :param kwargs: Initial style properties.
    """
    # Prime the image attribute
    self._image = None

    super().__init__(id, style, **kwargs)

    self.image = image

as_image(format=toga.Image)

Return the image in the specified format.

:param format: 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.

Source code in core/src/toga/widgets/imageview.py 
137
138
139
140
141
142
143
144
145
def as_image(self, format: type[ImageT] = toga.Image) -> ImageT:
    """Return the image in the specified format.

    :param format: Format to provide. Defaults to [`Image`][toga.images.Image]; also
        supports [`PIL.Image.Image`][] if Pillow is installed, as well as any image
        types defined by installed [image format plugins][image-format-plugins].
    :returns: The image in the specified format.
    """
    return self.image.as_format(format)

focus()

No-op; ImageView cannot accept input focus.

Source code in core/src/toga/widgets/imageview.py 
111
112
113
def focus(self) -> None:
    """No-op; ImageView cannot accept input focus."""
    pass