Icon#

A small, square image, used to provide easily identifiable visual context to a widget.

Availability (Key)#

macOS

GTK

Windows

iOS

Android

Web

Terminal

Usage#

Icons and Images are not the same!

Toga draws a distinction between an Icon and an Image. An Icon is small, square, and might vary between platforms. It is a visual element that is often used as part of an interactive element such as a button, toolbar item, or tab selector - but the Icon itself isn’t an interactive element.

An Image, on the other hand, can have an arbitrary size or aspect ratio, and is not platform dependent - the same image will be used on every platform. An Image is not an interactive element, because there is no visual cue to the user that the image can be interacted with.

If you are looking for a widget that the user can click on, you’re looking for a widget configured to use an Icon (probably Button), not an on_press handler on an Image or ImageView.

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; or

  • an 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.