: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`` <https://docs.gtk.org/gdk-pixbuf/class.Pixbuf.html>`__ 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:


   .. classmethod:: deserialize() -> ~gi.repository.Gio.Icon | None

      Deserializes a :obj:`~gi.repository.Gio.Icon` previously serialized using :func:`~gi.repository.Gio.Icon.serialize`.


      .. versionadded:: 2.38








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









   .. classmethod:: new_for_string() -> ~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








   .. 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() -> ~typing.Tuple[bool, list[str], int]

      The type of the None singleton.



      .. versionadded:: 2.20