Interface Icon

All Superinterfaces:
Proxy
All Known Subinterfaces:
LoadableIcon
All Known Implementing Classes:
BytesIcon, DmabufTexture, Emblem, EmblemedIcon, FileIcon, GLTexture, Icon.Icon$Impl, LoadableIcon.LoadableIcon$Impl, MemoryTexture, Pixbuf, Texture, Texture.Texture$Impl, ThemedIcon
@Generated("org.javagi.JavaGI") public interface Icon extends Proxy

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

To obtain a hash of a GIcon, see hash().

To check if two GIcons are equal, see equal(Icon).

For serializing a GIcon, use serialize() and deserialize(Variant).

If you want to consume GIcon (for example, in a toolkit) you must be prepared to handle at least the three following cases: LoadableIcon, ThemedIcon and 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 LoadableIcon.

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

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    Icon.Icon$Impl
    The Icon$Impl type represents a native instance of the Icon interface.
    static class 
    Icon.IconIface
    GIconIface is used to implement GIcon types for various different systems.

  • Method Summary

    Modifier and Type
    Method
    Description
    static @Nullable Icon
    deserialize(Variant value)
    Deserializes a GIcon previously serialized using g_icon_serialize().
    default boolean
    equal(@Nullable Icon icon2)
    Checks if two icons are equal.
    static @Nullable Type
    getType()
    Get the GType of the Icon class.
    default int
    hash()
    Gets a hash for an icon.
    static Icon
    newForString(String str)
    Generate a GIcon instance from str. This function can fail if str is not valid - see g_icon_to_string() for discussion.
    default @Nullable Variant
    serialize()
    Serializes a GIcon into a GVariant.
    default @Nullable String
    serializeToString()
    Generates a textual representation of this Icon that can be used for serialization such as when passing this Icon to a different process or saving it to persistent storage.

    Methods inherited from interface Proxy

    handle

  • Method Details

    • getType

      static @Nullable Type getType()
      Get the GType of the Icon class.
      Returns:
      the GType

    • deserialize

      static @Nullable Icon deserialize(Variant value)
      Deserializes a GIcon previously serialized using g_icon_serialize().
      Parameters:
      value - a GVariant created with g_icon_serialize()
      Returns:
      a GIcon, or null when deserialization fails.
      Since:
      2.38

    • newForString

      static Icon newForString(String str) throws GErrorException

      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().
      Returns:
      An object implementing the GIcon interface or null if error is set.
      Throws:
      GErrorException - see GError
      Since:
      2.20

    • equal

      default boolean equal(@Nullable Icon icon2)
      Checks if two icons are equal.
      Parameters:
      icon2 - pointer to the second GIcon.
      Returns:
      true if this Icon is equal to icon2. false otherwise.

    • hash

      default int hash()
      Gets a hash for an icon.
      Returns:
      a guint containing a hash for the icon, suitable for use in a GHashTable or similar data structure.

    • serialize

      default @Nullable Variant 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.
      Returns:
      a GVariant, or null when serialization fails. The GVariant will not be floating.
      Since:
      2.38

    • serializeToString

      default @Nullable String serializeToString()

      Generates a textual representation of this Icon that can be used for serialization such as when passing this Icon to a different process or saving it to persistent storage. Use g_icon_new_for_string() to get this Icon back from the returned string.

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

      • If this Icon is a GFileIcon, the returned string is a native path (such as /path/to/my icon.png) without escaping if the GFile for this 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 this Icon is a GThemedIcon with exactly one name and no fallbacks, the encoding is simply the name (such as network-server).

      Returns:
      An allocated NUL-terminated UTF8 string or null if this Icon can't be serialized. Use g_free() to free.
      Since:
      2.20