Module: Gio::Icon

Defined in:
lib/gio2/icon.rb

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 [classGio.ThemedIcon]), or the path to an icon
(see [ifaceGio.LoadableIcon]).

To obtain a hash of a GIcon, see [methodGio.Icon.hash].

To check if two GIcons are equal, see [methodGio.Icon.equal].

For serializing a GIcon, use [methodGio.Icon.serialize] and
[funcGio.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:
[ifaceGio.LoadableIcon], [classGio.ThemedIcon] and [classGio.EmblemedIcon].
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 [ifaceGio.LoadableIcon].

If your application or library provides one or more GIcon
implementations you need to ensure that your new implementation also
implements [ifaceGio.LoadableIcon]. Additionally, you must provide an
implementation of [methodGio.Icon.serialize] that gives a result that is
understood by [funcGio.Icon.deserialize], yielding one of the built-in
icon types.

Instance Method Summary collapse

Instance Method Details

#eql?(other) ⇒ Boolean

Returns:

  • (Boolean) 


19
20
21
22
 
# File 'lib/gio2/icon.rb', line 19

def eql?(other)
  other.is_a?(self.class) and
    hash == other.hash
end

#equal(icon1, icon2) ⇒ Boolean

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:

  • (Boolean) —

    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

Returns a #guint containing a hash for the icon, suitable for
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
    use in a GHash::Table or similar data structure.

#serialize(icon) ⇒ GLib::Variant

Returns a #GVariant, or nil when serialization fails. The #GVariant will not be floating.

Parameters:

Returns:

  • (GLib::Variant) —

    a #GVariant, or nil when serialization fails. The #GVariant will not be floating.

#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 sftp://path/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) ⇒ Boolean

Returns true if serialization took place, false otherwise.

Parameters:

  • icon (Gio::Icon) —

    The #GIcon

  • tokens (Array<String>) —

    The array to fill with tokens

  • out_version (Integer) —

    version of serialized tokens

Returns:

  • (Boolean) —

    true if serialization took place, false otherwise