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 classan 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