:right-sidebar: True Icon =================================================================== .. currentmodule:: gi.repository.Gio .. class:: Icon(*args, **kwargs) :no-contents-entry: Implementations: :class:`~gi.repository.Gio.BytesIcon`, :class:`~gi.repository.Gio.Emblem`, :class:`~gi.repository.Gio.EmblemedIcon`, :class:`~gi.repository.Gio.FileIcon`, :class:`~gi.repository.Gio.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 :obj:`~gi.repository.Gio.ThemedIcon`), or the path to an icon (see :obj:`~gi.repository.Gio.LoadableIcon`). To obtain a hash of a ``GIcon``, see :obj:`~gi.repository.Gio.Icon.hash`. To check if two ``GIcon``'s are equal, see :obj:`~gi.repository.Gio.Icon.equal`. For serializing a ``GIcon``, use :obj:`~gi.repository.Gio.Icon.serialize` and :obj:`~gi.repository.Gio.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: :obj:`~gi.repository.Gio.LoadableIcon`, :obj:`~gi.repository.Gio.ThemedIcon` and :obj:`~gi.repository.Gio.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 :obj:`~gi.repository.Gio.LoadableIcon`. If your application or library provides one or more ``GIcon`` implementations you need to ensure that your new implementation also implements :obj:`~gi.repository.Gio.LoadableIcon`. Additionally, you must provide an implementation of :obj:`~gi.repository.Gio.Icon.serialize` that gives a result that is understood by :obj:`~gi.repository.Gio.Icon.deserialize`, yielding one of the built-in icon types. Methods ------- .. rst-class:: interim-class .. class:: Icon :no-index: .. method:: deserialize(value: ~gi.repository.GLib.Variant) -> ~gi.repository.Gio.Icon | None Deserializes a :obj:`~gi.repository.Gio.Icon` previously serialized using :func:`~gi.repository.Gio.Icon.serialize`. .. versionadded:: 2.38 :param value: a :obj:`~gi.repository.GLib.Variant` created with :func:`~gi.repository.Gio.Icon.serialize` .. method:: equal(icon2: ~gi.repository.Gio.Icon | None = None) -> bool Checks if two icons are equal. :param icon2: pointer to the second :obj:`~gi.repository.Gio.Icon`. .. method:: hash() -> int Gets a hash for an icon. .. method:: new_for_string(str: str) -> ~gi.repository.Gio.Icon Generate a :obj:`~gi.repository.Gio.Icon` instance from ``str``. This function can fail if ``str`` is not valid - see :func:`~gi.repository.Gio.Icon.to_string` for discussion. If your application or library provides one or more :obj:`~gi.repository.Gio.Icon` implementations you need to ensure that each :obj:`~gi.repository.GObject.Type` is registered with the type system prior to calling :func:`~gi.repository.Gio.Icon.new_for_string`. .. versionadded:: 2.20 :param str: A string obtained via :func:`~gi.repository.Gio.Icon.to_string`. .. method:: serialize() -> ~gi.repository.GLib.Variant | None Serializes a :obj:`~gi.repository.Gio.Icon` into a :obj:`~gi.repository.GLib.Variant`. An equivalent :obj:`~gi.repository.Gio.Icon` can be retrieved back by calling :func:`~gi.repository.Gio.Icon.deserialize` on the returned value. As serialization will avoid using raw icon data when possible, it only makes sense to transfer the :obj:`~gi.repository.GLib.Variant` between processes on the same machine, (as opposed to over the network), and within the same file system namespace. .. versionadded:: 2.38 .. method:: 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 :func:`~gi.repository.Gio.Icon.new_for_string` to get ``icon`` back from the returned string. The encoding of the returned string is proprietary to :obj:`~gi.repository.Gio.Icon` except in the following two cases - If ``icon`` is a :obj:`~gi.repository.Gio.FileIcon`, the returned string is a native path (such as `/path/to/my icon.png`) without escaping if the :obj:`~gi.repository.Gio.File` for ``icon`` is a native file. If the file is not native, the returned string is the result of :func:`~gi.repository.Gio.File.get_uri` (such as `sftp://path/to/my``%20icon``.png`). - If ``icon`` is a :obj:`~gi.repository.Gio.ThemedIcon` with exactly one name and no fallbacks, the encoding is simply the name (such as ``network-server``). .. versionadded:: 2.20 Virtual Methods --------------- .. rst-class:: interim-class .. class:: Icon :no-index: .. method:: do_equal(icon2: ~gi.repository.Gio.Icon | None = None) -> bool Checks if two icons are equal. :param icon2: pointer to the second :obj:`~gi.repository.Gio.Icon`. .. method:: do_hash() -> int Gets a hash for an icon. .. method:: do_serialize() -> ~gi.repository.GLib.Variant | None Serializes a :obj:`~gi.repository.Gio.Icon` into a :obj:`~gi.repository.GLib.Variant`. An equivalent :obj:`~gi.repository.Gio.Icon` can be retrieved back by calling :func:`~gi.repository.Gio.Icon.deserialize` on the returned value. As serialization will avoid using raw icon data when possible, it only makes sense to transfer the :obj:`~gi.repository.GLib.Variant` between processes on the same machine, (as opposed to over the network), and within the same file system namespace. .. versionadded:: 2.38 .. method:: do_to_tokens() -> tuple[bool, list[str], int] Serializes the ``icon`` into string tokens. This is can be invoked when :func:`~gi.repository.Gio.Icon.new_for_string` is called. .. versionadded:: 2.20