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; 512, 256, 128, 72, 64, 32, and 16px 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 perform this lookup for each variant size, falling back to a name without a size specifier if a size-specific variant has not been provided. For example, when resolving the 32px variant, Toga will look for (in order):
myicon-linux-32.png
myicon-32.png
myicon-linux-32.ico
myicon-32.ico
myicon-linux-32.icns
myicon-32.icns
myicon.png
myicon.ico
Any icon that is found will be resized to the required size. Toga will generate any GTK icon variants that are not available from the highest resolution provided (e.g., if no 128px variant can be found, one will be created by scaling the highest resolution variant that is available).
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 return DEFAULT_ICON
. The only exception to this is
if an icon file is found, but it cannot be loaded (e.g., due to a file format or
permission error). In this case, an error will be raised.
Reference¶
-
type IconContentT¶
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. If the icon cannot be found, the default icon will be
DEFAULT_ICON
. If an icon file is found, but it cannot be loaded (due to a file format or permission error), an exception will be raised.system (bool) – For internal use only
- APP_ICON¶
The application icon.
The application icon will be loaded from
resources/<app name>
(where<app name>
is the value oftoga.App.app_name
).If this resource cannot be found, and the app has been packaged as a binary, the icon from the application binary will be used as a fallback.
Otherwise,
DEFAULT_ICON
will be used.
- DEFAULT_ICON¶
The default icon used as a fallback - Toga’s “Tiberius the yak” icon.
- OPTION_CONTAINER_DEFAULT_TAB_ICON¶
The default icon used to decorate option container tabs.