Interface

GioIcon

Description [src]

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

Prerequisite

In order to implement Icon, your type must inherit fromGObject.

Implementations

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.

g_icon_hash

Gets a hash for an icon.

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.

Gio.Icon.hash

Gets a hash for an icon.

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