Skip to content

Gio.Icon

interface

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 Icon.hash.

To check if two GIcons are equal, see Icon.equal.

For serializing a GIcon, use Icon.serialize and Icon.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 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 Icon.serialize that gives a result that is understood by Icon.deserialize, yielding one of the built-in icon types.

Methods

equal

def equal(self, icon2: Icon | None = ...) -> bool

Checks if two icons are equal.

Parameters:

  • icon2 — pointer to the second Icon.

hash

def hash(self) -> int

Gets a hash for an icon.

serialize

def serialize(self) -> GLib.Variant | None

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

to_string

def to_string(self) -> 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 Icon.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 File.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).

Static functions

deserialize

@staticmethod
def deserialize(value: GLib.Variant) -> Icon | None

Deserializes a Icon previously serialized using Icon.serialize.

Parameters:

new_for_string

@staticmethod
def new_for_string(str: str) -> Icon

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

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

Parameters:

Virtual methods

do_equal

def do_equal(self, icon2: Icon | None = ...) -> bool

Checks if two icons are equal.

Parameters:

  • icon2 — pointer to the second Icon.

do_hash

def do_hash(self) -> int

Gets a hash for an icon.

do_serialize

def do_serialize(self) -> GLib.Variant | None

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

do_to_tokens

def do_to_tokens(self) -> tuple[bool, list[str], int]

Serializes the icon into string tokens. This is can be invoked when Icon.new_for_string is called.