GIcon: GIO Reference Manual

## GIcon GIcon — Interface for icons |

## Functions

guint | g_icon_hash ()
gboolean | g_icon_equal ()
gchar * | g_icon_to_string ()
GIcon * | g_icon_new_for_string ()
GVariant * | g_icon_serialize ()
GIcon * | g_icon_deserialize ()

## Types and Values

| GIcon
struct | GIconIface

## Object Hierarchy

        GInterface
        ╰── GIcon

## Prerequisites

GIcon requires GObject.

## Known Derived Interfaces

GIcon is required by GLoadableIcon.

## Known Implementations

GIcon is implemented by GBytesIcon, GEmblem, GEmblemedIcon, GFileIcon and GThemedIcon.

## Includes

    #include <gio/gio.h>

## Description

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

## Functions

### g_icon_hash ()

    guint
    g_icon_hash (gconstpointer icon);

Gets a hash for an icon.

Virtual: hash

#### Parameters

icon | gconstpointer to an icon object. | [not nullable]

#### Returns

a guint containing a hash for the `icon` , suitable for use in a GHashTable or similar data structure.

### g_icon_equal ()

    gboolean
    g_icon_equal (GIcon *icon1,
                  GIcon *icon2);

Checks if two icons are equal.

#### Parameters

icon1 | pointer to the first GIcon. | [nullable]
icon2 | pointer to the second GIcon. | [nullable]

#### Returns

`TRUE` if `icon1` is equal to `icon2` . `FALSE` otherwise.

### g_icon_to_string ()

    gchar *
    g_icon_to_string (GIcon *icon);

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.

The encoding of the returned string is proprietary to GIcon except in the following two cases

- If `icon` is a GFileIcon, the returned string is a native path (such as `/path/to/my icon.png`) without escaping if the GFile for `icon` is a native file. If the file is not native, the returned string is the result of `g_file_get_uri()` (such as `sftp://path/to/my%20icon.png`).

- If `icon` is a GThemedIcon with exactly one name and no fallbacks, the encoding is simply the name (such as `network-server`).

Virtual: to_tokens

#### Parameters

icon | a GIcon. |

#### Returns

An allocated NUL-terminated UTF8 string or `NULL` if `icon` can't be serialized. Use `g_free()` to free.

[nullable]

Since: 2.20

### g_icon_new_for_string ()

    GIcon *
    g_icon_new_for_string (const gchar *str,
                           GError **error);

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

If your application or library provides one or more GIcon implementations you need to ensure that each GType is registered with the type system prior to calling `g_icon_new_for_string()`.

#### Parameters

str | A string obtained via `g_icon_to_string()`. |
error | Return location for error. |

#### Returns

An object implementing the GIcon interface or `NULL` if `error` is set.

[transfer full]

Since: 2.20

### g_icon_serialize ()

    GVariant *
    g_icon_serialize (GIcon *icon);

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.

#### Parameters

icon | a GIcon |

#### Returns

a GVariant, or `NULL` when serialization fails. The GVariant will not be floating.

[nullable][transfer full]

Since: 2.38

### g_icon_deserialize ()

    GIcon *
    g_icon_deserialize (GVariant *value);

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

#### Parameters

value | a GVariant created with `g_icon_serialize()`. | [transfer none]

#### Returns

a GIcon, or `NULL` when deserialization fails.

[nullable][transfer full]

Since: 2.38

## Types and Values

### GIcon

    typedef struct _GIcon GIcon;

An abstract type that specifies an icon.

### struct GIconIface

    struct GIconIface {
      GTypeInterface g_iface;

      /* Virtual Table */

      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.

#### Members

`hash` () | A hash for a given GIcon. |
`equal` () | Checks if two GIcons are equal. |
`to_tokens` () | 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` () | 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` () | Serializes a GIcon into a GVariant. Since: 2.38 |