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 toga.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¶

Any class that represents an image.

toga.images.ImageConverter ¶

Bases: Protocol

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

image_class `instance-attribute` ¶

image_class

The base image class this plugin can interpret.

convert_from_format `staticmethod` ¶

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.

PARAMETER	DESCRIPTION
`image_in_format`	An instance of `image_class` (or a subclass). TYPE: `ExternalImageT`

RETURNS	DESCRIPTION
`BytesLikeT`	The image data, in a known image format.

convert_to_format `staticmethod` ¶

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.

PARAMETER	DESCRIPTION
`data`	Image data in a known image format. TYPE: `BytesLikeT`
`image_class`	The class of image to return. TYPE: `type[ExternalImageT]`

RETURNS	DESCRIPTION
`ExternalImageT`	The image, as an instance of the image class specified.