gi-gio-2.0.32: Gio bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | Safe-Inferred
Language | Haskell2010

GI.Gio.Interfaces.Icon

Contents

- Exported types
- Methods
  - deserialize
  - equal
  - hash
  - newForString
  - serialize
  - toString

Description

`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 `iconHash`.

To check if two `GIcon`s are equal, see `iconEqual`.

For serializing a `GIcon`, use `iconSerialize` and [func`gio`.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: `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 `iconSerialize` that gives a result that is understood by [func`gio`.Icon.deserialize], yielding one of the built-in icon types.

Synopsis

- newtype Icon = Icon (ManagedPtr Icon)
- class (GObject o, IsDescendantOf Icon o) => IsIcon o
- toIcon :: (MonadIO m, IsIcon o) => o -> m Icon
- iconDeserialize :: (HasCallStack, MonadIO m) => GVariant -> m (Maybe Icon)
- iconEqual :: (HasCallStack, MonadIO m, IsIcon a, IsIcon b) => a -> Maybe b -> m Bool
- iconHash :: (HasCallStack, MonadIO m, IsIcon a) => a -> m Word32
- iconNewForString :: (HasCallStack, MonadIO m) => Text -> m Icon
- iconSerialize :: (HasCallStack, MonadIO m, IsIcon a) => a -> m (Maybe GVariant)
- iconToString :: (HasCallStack, MonadIO m, IsIcon a) => a -> m (Maybe Text)

# Exported types

newtype Icon Source #

Memory-managed wrapper type.

Constructors

Icon (ManagedPtr Icon) |

#### Instances

Instances details

Eq Icon Source # |
Instance details Defined in GI.Gio.Interfaces.Icon Methods (==) :: Icon -> Icon -> Bool Source # (/=) :: Icon -> Icon -> Bool Source #
GObject Icon Source # |
Instance details Defined in GI.Gio.Interfaces.Icon
ManagedPtrNewtype Icon Source # |
Instance details Defined in GI.Gio.Interfaces.Icon Methods toManagedPtr :: Icon -> ManagedPtr Icon Source #
TypedObject Icon Source # |
Instance details Defined in GI.Gio.Interfaces.Icon Methods glibType :: IO GType Source #
HasParentTypes Icon Source # |
Instance details Defined in GI.Gio.Interfaces.Icon
IsGValue (Maybe Icon) Source # | Convert `Icon` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gio.Interfaces.Icon Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe Icon -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe Icon) Source #
type ParentTypes Icon Source # |
Instance details Defined in GI.Gio.Interfaces.Icon type ParentTypes Icon = '[Object]

class (GObject o, IsDescendantOf Icon o) => IsIcon o Source #

Type class for types which can be safely cast to `Icon`, for instance with `toIcon`.

#### Instances

Instances details

(GObject o, IsDescendantOf Icon o) => IsIcon o Source # |
Instance details Defined in GI.Gio.Interfaces.Icon

toIcon :: (MonadIO m, IsIcon o) => o -> m Icon Source #

Cast to `Icon`, for types for which this is known to be safe. For general casts, use `castTo`.

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

bindProperty, bindPropertyFull, equal, forceFloating, freezeNotify, getv, hash, isFloating, notify, notifyByPspec, ref, refSink, runDispose, serialize, stealData, stealQdata, thawNotify, toString, unref, watchClosure.

#### Getters

getData, getProperty, getQdata.

#### Setters

setData, setDataFull, setProperty.

## deserialize

iconDeserialize Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> GVariant | `value`: a `GVariant` created with `iconSerialize`
-> m (Maybe Icon) | Returns: a `Icon`, or `Nothing` when deserialization fails.

Deserializes a `Icon` previously serialized using `iconSerialize`.

Since: 2.38

## equal

iconEqual Source #

Arguments

:: (HasCallStack, MonadIO m, IsIcon a, IsIcon b) |
=> a | `icon1`: pointer to the first `Icon`.
-> Maybe b | `icon2`: pointer to the second `Icon`.
-> m Bool | Returns: `True` if `icon1` is equal to `icon2`. `False` otherwise.

Checks if two icons are equal.

## hash

iconHash Source #

Arguments

:: (HasCallStack, MonadIO m, IsIcon a) |
=> a | `icon`: `gconstpointer` to an icon object.
-> m Word32 | Returns: a `guint` containing a hash for the `icon`, suitable for use in a `HashTable` or similar data structure.

Gets a hash for an icon.

## newForString

iconNewForString Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `str`: A string obtained via `iconToString`.
-> m Icon | Returns: An object implementing the `Icon` interface or `Nothing` if `error` is set. (Can throw `GError`)

Generate a `Icon` instance from `str`. This function can fail if `str` is not valid - see `iconToString` for discussion.

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

Since: 2.20

## serialize

iconSerialize Source #

Arguments

:: (HasCallStack, MonadIO m, IsIcon a) |
=> a | `icon`: a `Icon`
-> m (Maybe GVariant) | Returns: a `GVariant`, or `Nothing` when serialization fails. The `GVariant` will not be floating.

Serializes a `Icon` into a `GVariant`. An equivalent `Icon` can be retrieved back by calling `iconDeserialize` 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.

Since: 2.38

## toString

iconToString Source #

Arguments

:: (HasCallStack, MonadIO m, IsIcon a) |
=> a | `icon`: a `Icon`.
-> m (Maybe Text) | Returns: An allocated NUL-terminated UTF8 string or `Nothing` if `icon` can't be serialized. Use `free` to free.

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 `iconNewForString` to get `icon` back from the returned string.

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

- If `icon` is a `FileIcon`, the returned string is a native path (such as `/path/to/my icon.png`) without escaping if the `File` for `icon` is a native file. If the file is not native, the returned string is the result of `fileGetUri` (such as `sftp://path/to/my%20icon.png`).
- If `icon` is a `ThemedIcon` with exactly one name and no fallbacks, the encoding is simply the name (such as `network-server`).

Since: 2.20