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)

You can also tell Toga how to convert from (and to) other classes that represent images via image format plugin.

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

• If you subclass toga.Image, you can supply that subclass as the requested format to any as_format() method in Toga, provided that your subclass has a constructor signature compatible with the base toga.Image class.

Reference

toga.Image

Image(src=NOT_PROVIDED, *, path=NOT_PROVIDED, data=NOT_PROVIDED)

Create a new image.

PARAMETER	DESCRIPTION
src	The source from which to load the image. Can be any valid ImageContentT type. TYPE: ImageContentT DEFAULT: NOT_PROVIDED
path	DEPRECATED - Use src. TYPE: object DEFAULT: NOT_PROVIDED
data	DEPRECATED - Use src. TYPE: object DEFAULT: NOT_PROVIDED

RAISES	DESCRIPTION
FileNotFoundError	If a path is provided, but that path does not exist.
ValueError	If the source cannot be loaded as an image.

data property

data

The raw data for the image, in PNG format.

height property

height

The height of the image, in pixels.

path property

path

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

size property

size

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

width property

width

The width of the image, in pixels.

as_format

as_format(format)

Return the image, converted to the image format specified.

PARAMETER	DESCRIPTION
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 plugin. TYPE: type[ImageT]

RETURNS	DESCRIPTION
ImageT	The image in the requested format

RAISES	DESCRIPTION
TypeError	If the format supplied is not recognized.

save

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

PARAMETER	DESCRIPTION
path	Path to save the image to. TYPE: str | Path

toga.images.ImageContentT module-attribute

ImageContentT

When specifying content for an toga.Image, you can provide:

• a string specifying an absolute or relative path to a file in a known image format;
• an absolute or relative pathlib.Path object describing a file in a known image format;
• a "blob of bytes" data type (bytes, bytearray, or memoryview) containing raw image data in a known image format;
• an instance of toga.Image;
• if Pillow is installed, an instance of PIL.Image.Image;
• an image of a class registered via an image format plugin (or a subclass of such a class); or
• an instance of the native platform image representation.

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

toga.images.ImageT module-attribute

ImageT

Toga is able to receive and return content in a wide range of image formats. ImageT describes any "image-like" object. This could be an instance of toga.Image, an image type from a third party library (such as PIL.Image.Image from Pillow), or the platform's native type for representing images.

toga.images.ExternalImageT module-attribute

ExternalImageT

A type describing an image-like object provided by a third-party library, such as PIL.Image.Image from Pillow.