Icon

class Icon(*args, **kwargs)

Implementations: BytesIcon, Emblem, EmblemedIcon, FileIcon, ThemedIcon

GIcon is a very minimal interface for icons. It provides functions for checking the equality of two icons, hashing of icons and serializing an icon to and from strings.

GIcon does not provide the actual pixmap for the icon as this is out of GIO’s scope, however implementations of GIcon may contain the name of an icon (see ThemedIcon), or the path to an icon (see LoadableIcon).

To obtain a hash of a GIcon, see hash.

To check if two GIcons are equal, see equal.

For serializing a GIcon, use serialize and deserialize.

If you want to consume GIcon (for example, in a toolkit) you must be prepared to handle at least the three following cases: LoadableIcon, ThemedIcon and EmblemedIcon. It may also make sense to have fast-paths for other cases (like handling `GdkPixbuf <https://docs.gtk.org/gdk-pixbuf/class.Pixbuf.html>`__ directly, for example) but all compliant GIcon implementations outside of GIO must implement LoadableIcon.

If your application or library provides one or more GIcon implementations you need to ensure that your new implementation also implements LoadableIcon. Additionally, you must provide an implementation of serialize that gives a result that is understood by deserialize, yielding one of the built-in icon types.

Methods

class Icon

classmethod deserialize() → Icon | None

Deserializes a Icon previously serialized using serialize().

Added in version 2.38.

equal(icon2: Icon | None = None) → bool

Checks if two icons are equal.

Parameters:

icon2 – pointer to the second Icon.

hash() → int

Gets a hash for an icon.

classmethod new_for_string() → Icon

Generate a Icon instance from str. This function can fail if str is not valid - see to_string() for discussion.

If your application or library provides one or more Icon implementations you need to ensure that each Type is registered with the type system prior to calling new_for_string().

Added in version 2.20.

serialize() → Variant | None

Serializes a Icon into a Variant. An equivalent Icon can be retrieved back by calling deserialize() on the returned value. As serialization will avoid using raw icon data when possible, it only makes sense to transfer the Variant between processes on the same machine, (as opposed to over the network), and within the same file system namespace.

Added in version 2.38.

to_string() → str | None

Generates a textual representation of icon that can be used for serialization such as when passing icon to a different process or saving it to persistent storage. Use new_for_string() to get icon back from the returned string.

The encoding of the returned string is proprietary to Icon except in the following two cases

• If icon is a FileIcon, the returned string is a native path (such as /path/to/my icon.png) without escaping if the File for icon is a native file. If the file is not native, the returned string is the result of get_uri() (such as sftp://path/to/my%20icon.png).

• If icon is a ThemedIcon with exactly one name and no fallbacks, the encoding is simply the name (such as network-server).

Added in version 2.20.

Virtual Methods

class Icon

do_equal(icon2: Icon | None = None) → bool

Checks if two icons are equal.

Parameters:

icon2 – pointer to the second Icon.

do_hash() → int

Gets a hash for an icon.

do_serialize() → Variant | None

Serializes a Icon into a Variant. An equivalent Icon can be retrieved back by calling deserialize() on the returned value. As serialization will avoid using raw icon data when possible, it only makes sense to transfer the Variant between processes on the same machine, (as opposed to over the network), and within the same file system namespace.

Added in version 2.38.

do_to_tokens() → tuple[bool, list[str], int]

The type of the None singleton.

Added in version 2.20.