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
-
#equal(icon1, icon2) ⇒ TrueClass
True if icon1 is equal to icon2.
- #from_tokens(tokens, num_tokens, version) ⇒ Gio::Icon
-
#hash(icon) ⇒ Integer
use in a GHash::Table or similar data structure.
-
#serialize(icon) ⇒ GLib::Variant
A #GVariant, or nil when serialization fails.
-
#to_string ⇒ 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.
-
#to_tokens(icon, tokens, out_version) ⇒ TrueClass
nil if icon can’t be serialized.
Instance Method Details
#equal(icon1, icon2) ⇒ TrueClass
Returns true if icon1 is equal to icon2. false otherwise.
#from_tokens(tokens, num_tokens, version) ⇒ Gio::Icon
#hash(icon) ⇒ Integer
use in a GHash::Table or similar data structure.
#serialize(icon) ⇒ GLib::Variant
Returns a #GVariant, or nil when serialization fails.
#to_string ⇒ 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.
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.
#to_tokens(icon, tokens, out_version) ⇒ TrueClass
nil if icon can’t be serialized. Use g_free() to free.