gio.Icon
Prev | PyGio Class Reference | Next

## gio.Icon

gio.Icon — Interface for icons.

## Synopsis

    class gio.Icon(gobject.GInterface):
        def equal(icon2)
        def to_string()

    Functions

        def gio.icon_new_from_string()

## Ancestry

    +-- gobject.GInterface
      +-- gio.Icon

## Known Derived Interfaces

`gio.Icon` is required by `gio.LoadableIcon`.

## Known Implementation

`gio.Icon` is implemented by `gio.ThemedIcon`, `gio.FileIcon`, `gio.Emblem`, `gio.EmblemedIcon`.

## Description

`gio.Icon` 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.

`gio.Icon` does not provide the actual pixmap for the icon as this is out of GIO's scope, however implementations of `gio.Icon` may contain the name of an icon (see `gio.ThemedIcon`), or the path to an icon (see `gio.LoadableIcon`).

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

For serializing a `gio.Icon`, use `gio.Icon.to_string`() and `gio.Icon.new_from_string`().

If your application or library provides one or more `gio.Icon` implementations you need to ensure that each GType is registered with the type system prior to calling `gio.icon_new_from_string`().

## Methods

### gio.Icon.equal

        def equal(icon2)

`icon2` : | the second `gio.Icon`

The `equal`() method checks if two icons are equal.

### gio.Icon.to_string

        def to_string()

Returns : | An UTF8 string or `None` if icon can't be serialized.

The `to_string`() method 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 `gio.icon_new_from_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 `gio.FileIcon`, the returned string is a native path (such as /path/to/my icon.png) without escaping if the `gio.File` for icon is a native file. If the file is not native, the returned string is the result of `gio.File.get_uri`() (such as sftp://path/to/my%20icon.png).

If icon is a `gio.ThemedIcon` with exactly one name, the encoding is simply the name (such as network-server).

## Functions

### gio.icon_new_from_string

        def icon_new_from_string(str)

`str` : | A string obtained via `gio.Icon.to_string`().
Returns : | An object implementing the `gio.Icon` interface or `None` if error is set.

The `icon_new_from_string`() function generate a `gio.Icon` instance from str. This function can fail if str is not valid - see `gio.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 `gio.icon_new_from_string`().

Prev | Up | Next
gio.FilterOutputStream | Home | gio.InputStream