Image#

Graphical content of arbitrary size.

Availability (Key)#

macOS

GTK

Windows

iOS

Android

Web

Terminal

Usage#

Images and Icons are not the same!

Toga draws a distinction between an Image and an Icon. An Image can have an arbitrary size or aspect ratio, and is not platform dependent - the same image will be used on every platform. An Image is not an interactive element, because there is no visual cue to the user that the image can be interacted with.

An Icon, on the other hand, is small, square, and might vary between platforms. It is a visual element that is often used as part of an interactive element such as a button, a toolbar item, or a tab selector - but the Icon itself isn’t an interactive element.

If you are looking for a widget that the user can click on, you’re looking for a widget configured to use an Icon (probably Button), not an on_press handler on an Image or ImageView.

An image can be constructed from a wide range of sources:

from pathlib import Path
import toga

# Load an image in the same folder as the file that declares the App class
my_image = toga.Image("brutus.png")

# Load an image at an absolute path
my_image = toga.Image(Path.home() / "path/to/brutus.png")

# Create an image from raw data
with (Path.home() / "path/to/brutus.png").open("rb") as f:
    my_image = toga.Image(data=f.read())

# Create an image from a PIL image (if PIL is installed)
import PIL.Image
my_pil_image = PIL.Image.new("L", (30, 30))
my_toga_image = toga.Image(my_pil_image)

Notes#

  • PNG and JPEG formats are guaranteed to be supported. Other formats are available on some platforms:

    • GTK: BMP

    • macOS: GIF, BMP, TIFF

    • Windows: GIF, BMP, TIFF

  • The native platform representations for images are:

    • Android: android.graphics.Bitmap

    • GTK: GdkPixbuf.Pixbuf

    • iOS: UIImage

    • macOS: NSImage

    • Windows: System.Drawing.Image

Reference#

type ImageContent#

When specifying content for an Image, you can provide:

If a relative path is provided, it will be anchored relative to the module that defines your Toga application class.

class toga.Image(src=NOT_PROVIDED, *, path=NOT_PROVIDED, data=NOT_PROVIDED)#

Create a new image.

Parameters:
  • src (ImageContent) – The source from which to load the image. Can be any valid image content type.

  • pathDEPRECATED - Use src.

  • dataDEPRECATED - Use src.

Raises:
  • FileNotFoundError – If a path is provided, but that path does not exist.

  • ValueError – If the source cannot be loaded as an image.

as_format(format)#

Return the image, converted to the image format specified.

Parameters:

format (type[ImageT]) – The image class to return. Currently supports only Image, and PIL.Image.Image if Pillow is installed.

Returns:

The image in the requested format

Raises:

TypeError – If the format supplied is not recognized.

Return type:

ImageT

property data: bytes#

The raw data for the image, in PNG format.

property height: int#

The height of the image, in pixels.

property path: Path | None#

The path from which the image was opened, if any (or None).

save(path)#

Save image to given path.

The file format of the saved image will be determined by the extension of the filename provided (e.g path/to/mypicture.png will save a PNG file).

Parameters:

path (str | Path) – Path to save the image to.

Return type:

None

property size: int, int#

The size of the image, as a (width, height) tuple.

property width: int#

The width of the image, in pixels.