Icon#
A small, square image, used to provide easily identifiable visual context to a widget.
Usage#
The filename specified for an icon should be specified without an extension; the platform will determine an appropriate extension, and may also modify the name of the icon to include a platform and/or size qualifier.
The following formats are supported (in order of preference):
Android - PNG
iOS - ICNS, PNG, BMP, ICO
macOS - ICNS, PNG, PDF
GTK - PNG, ICO, ICNS. 32px and 72px variants of each icon can be provided;
Windows - ICO, PNG, BMP
The first matching icon of the most specific platform, with the most specific
size will be used. For example, on Windows, specifying an icon of myicon
will cause Toga to look for (in order):
myicon-windows.ico
myicon.ico
myicon-windows.png
myicon.png
myicon-windows.bmp
myicon.bmp
On GTK, Toga will look for (in order):
myicon-linux-72.png
myicon-72.png
myicon-linux-32.png
myicon-32.png
myicon-linux.png
myicon.png
myicon-linux-72.ico
myicon-72.ico
myicon-linux-32.ico
, and so on.
An icon is guaranteed to have an implementation, regardless of the path specified. If you specify a path and no matching icon can be found, Toga will output a warning to the console, and load a default “Tiberius the yak” icon.
Reference#
-
type IconContent#
When specifying an
Icon
, you can provide:a string specifying an absolute or relative path;
an absolute or relative
pathlib.Path
object; oran instance of
toga.Icon
.
If a relative path is provided, it will be anchored relative to the module that defines your Toga application class.
- class toga.Icon(path, *, system=False)#
Create a new icon.
- Parameters:
path (str | Path) –
Base filename for the icon. The path can be an absolute file system path, or a path relative to the module that defines your Toga application class.
This base filename should not contain an extension. If an extension is specified, it will be ignored.
system (bool) – For internal use only
- DEFAULT_ICON#
The default icon used as a fallback.
- OPTION_CONTAINER_DEFAULT_TAB_ICON#
The default icon used to decorate option container tabs.
- TOGA_ICON#
DEPRECATED - Use
DEFAULT_ICON
, or your own icon.