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 GIcon’s 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

deserialize(value: Variant) → Icon | None

Deserializes a Icon previously serialized using serialize().

Added in version 2.38.

Parameters:: value – a Variant created with serialize()

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.

new_for_string(str: str) → 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.

Parameters:: str – A string obtained via to_string().

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]: Serializes the icon into string tokens. This is can be invoked when new_for_string() is called.

Added in version 2.20.