Module: Gio::Icon

Defined in:
(unknown)

Overview

#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 GThemed::Icon), 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: GLoadable::Icon, #GThemedIcon and #GEmblemedIcon. It may also make sense to have fast-paths for other cases (like handling Gdk::Pixbuf directly, for example) but all compliant #GIcon implementations outside of GIO must implement GLoadable::Icon.

If your application or library provides one or more #GIcon implementations you need to ensure that your new implementation also implements GLoadable::Icon. 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.

Instance Method Summary collapse

Instance Method Details

#equal(icon1, icon2) ⇒ TrueClass

Returns true if icon1 is equal to icon2. false otherwise.

Parameters:

  • icon1 (Gio::Icon)

    pointer to the first #GIcon.

  • icon2 (Gio::Icon)

    pointer to the second #GIcon.

Returns:

  • (TrueClass)

    true if icon1 is equal to icon2. false otherwise.

#from_tokens(tokens, num_tokens, version) ⇒ Gio::Icon

Parameters:

  • tokens (String)
  • num_tokens (Integer)
  • version (Integer)

Returns:

#hash(icon) ⇒ Integer

use in a GHash::Table or similar data structure.

Parameters:

  • icon (Gio::Icon)

    #gconstpointer to an icon object.

Returns:

  • (Integer)

    a #guint containing a hash for the icon, suitable for

#serialize(icon) ⇒ GLib::Variant

Returns a #GVariant, or nil when serialization fails.

Parameters:

Returns:

  • (GLib::Variant)

    a #GVariant, or nil when serialization fails.

#to_stringString

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 GFile::Icon, 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 `spath/to/my%20icon.png`).

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

nil if icon can’t be serialized. Use g_free() to free.

Returns:

  • (String)

    An allocated NUL-terminated UTF8 string or

#to_tokens(icon, tokens, out_version) ⇒ TrueClass

nil if icon can’t be serialized. Use g_free() to free.

Parameters:

  • icon (Gio::Icon)

    a #GIcon.

  • tokens (Array<GObject>)
  • out_version (Integer)

Returns:

  • (TrueClass)

    An allocated NUL-terminated UTF8 string or