Gio.Icon
Description: Reference for Gio.Icon

### Interface

# GioIcon

since: 2.0

#### Description

    interface Gio.Icon : GObject.Object

`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 `GThemedIcon`), or the path to an icon (see `GLoadableIcon`).

To obtain a hash of a `GIcon`, see `g_icon_hash()`.

To check if two `GIcon`s are equal, see `g_icon_equal()`.

For serializing a `GIcon`, use `g_icon_serialize()` and `g_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: `GLoadableIcon`, `GThemedIcon` and `GEmblemedIcon`. 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 `GLoadableIcon`.

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

Available since: 2.0

#### Prerequisite

In order to implement Icon, your type must inherit from`GObject`.

#### Implementations

- GBytesIcon
- GEmblem
- GEmblemedIcon
- GFileIcon
- GThemedIcon

#### Functions

###### g_icon_deserialize

Deserializes a `GIcon` previously serialized using g_icon_serialize().

since: 2.38

###### g_icon_new_for_string

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

since: 2.20

#### Instance methods

###### g_icon_equal

Checks if two icons are equal.

since: 2.0

###### g_icon_hash

Gets a hash for an icon.

since: 2.0

###### g_icon_serialize

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

since: 2.38

###### g_icon_to_string

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 `g_icon_new_for_string()` to get `icon` back from the returned string.

since: 2.20

#### Interface structure

    struct GioIconIface {
      GTypeInterface g_iface;
      guint (* hash) (
        GIcon* icon
      );
      gboolean (* equal) (
        GIcon* icon1,
        GIcon* icon2
      );
      gboolean (* to_tokens) (
        GIcon* icon,
        GPtrArray* tokens,
        gint* out_version
      );
      GIcon* (* from_tokens) (
        gchar** tokens,
        gint num_tokens,
        gint version,
        GError** error
      );
      GVariant* (* serialize) (
        GIcon* icon
      );

    }

GIconIface is used to implement GIcon types for various different systems. See `GThemedIcon` and `GLoadableIcon` for examples of how to implement this interface.

###### Interface members

`g_iface` |
    GTypeInterface
| The parent interface.
`hash` |
    guint (* hash) (
        GIcon* icon
      )
| A hash for a given `GIcon`.
`equal` |
    gboolean (* equal) (
        GIcon* icon1,
        GIcon* icon2
      )
| Checks if two `GIcons` are equal.
`to_tokens` |
    gboolean (* to_tokens) (
        GIcon* icon,
        GPtrArray* tokens,
        gint* out_version
      )
| Serializes a `GIcon` into tokens. The tokens must not contain any whitespace. Don’t implement if the `GIcon` can’t be serialized (Since 2.20).
`from_tokens` |
    GIcon* (* from_tokens) (
        gchar** tokens,
        gint num_tokens,
        gint version,
        GError** error
      )
| Constructs a `GIcon` from tokens. Set the `GError` if the tokens are malformed. Don’t implement if the `GIcon` can’t be serialized (Since 2.20).
`serialize` |
    GVariant* (* serialize) (
        GIcon* icon
      )
| Serializes a `GIcon` into a `GVariant`. Since: 2.38

#### Virtual methods

###### Gio.Icon.equal

Checks if two icons are equal.

since: 2.0

###### Gio.Icon.hash

Gets a hash for an icon.

since: 2.0

###### Gio.Icon.serialize

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

since: 2.38

###### Gio.Icon.to_tokens

Serializes the `icon` into string tokens. This is can be invoked when `g_icon_new_for_string()` is called.

since: 2.20