Image Format Plugins

Usage

Toga can be extended, via plugins, to understand externally defined image types, gaining the ability to convert them to and from its own Image class. Toga’s Pillow support is, in fact, implemented as a plugin that’s included as part of the core Toga package.

An image format plugin consists of two things:

  • a converter class conforming to the ImageConverter protocol, with methods defining how to convert to and from your image class

  • an entry point in the toga.image_formats group telling Toga the path to your converter class.

Let’s say you want to tell Toga how to handle an image class called MyImage, and you’re publishing your plugin as a package named togax-myimage (see package prefixes) that contains a plugins.py module that defines your MyImageConverter plugin class. Your pyproject.toml might include something like the following:

[project.entry-points."toga.image_formats"]
myimage = "togax_myimage.plugins.MyImageConverter"

The variable name being assigned to (myimage in this case) can be whatever you like (although it should probably have some relationship to the image format name) What matters is the string assigned to it, which represents where Toga can find (and import) your ImageConverter class.

Package prefixes

An image plugin can be registered from any Python module. If you maintain a package defining an image format, you could include a Toga converter plugin along with it. If you’re publishing a plugin as a standalone package, you should title it with a togax- prefix, to indicate that it’s an unofficial extension for Toga. Do not use the toga- prefix, as the BeeWare Project wishes to reserve that package prefix for “official” packages.

Reference

type ExternalImageT

Any class that represents an image.

protocol toga.images.ImageConverter

A class to convert between an externally defined image type and toga.Image.

Classes that implement this protocol must have the following methods / attributes:

static convert_from_format(image_in_format)

Convert from image_class to data in a known image format.

Will accept an instance of image_class, or subclass of that class.

Parameters:

image_in_format (ExternalImageT) – An instance of image_class (or a subclass).

Returns:

The image data, in a known image format.

Return type:

BytesLike

static convert_to_format(data, image_class)

Convert from data to image_class or specified subclass.

Accepts a bytes-like object representing the image in a known image format, and returns an instance of the image class specified. This image class is guaranteed to be either the image_class registered by the plugin, or a subclass of that class.

Parameters:

  • data (BytesLike) – Image data in a known image format.

  • image_class (type[ExternalImageT]) – The class of image to return.

Returns:

The image, as an instance of the image class specified.

Return type:

ExternalImageT

image_class: type[ExternalImageT]

The base image class this plugin can interpret.