Copyright	Will Thompson Iñaki García Etxebarria and Jonas Platte
License	LGPL-2.1
Maintainer	Iñaki García Etxebarria (garetxe@gmail.com)
Safe Haskell	None
Language	Haskell2010

GI.Gio.Interfaces.Icon

Contents

Exported types
Methods

Description

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.

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

To obtain a hash of a Icon, see iconHash.

To check if two GIcons are equal, see iconEqual.

For serializing a Icon, use iconSerialize and iconDeserialize.

If you want to consume Icon (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 Icon implementations outside of GIO must implement LoadableIcon.

If your application or library provides one or more Icon 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 iconDeserialize, yielding one of the built-in icon types.

Synopsis

newtype Icon = Icon (ManagedPtr Icon)
noIcon :: Maybe Icon
class GObject o => IsIcon o
toIcon :: (MonadIO m, IsIcon o) => o -> m Icon
iconDeserialize :: (HasCallStack, MonadIO m) => GVariant -> m Icon
iconEqual :: (HasCallStack, MonadIO m, IsIcon a, IsIcon b) => a -> Maybe b -> m Bool
iconHash :: (HasCallStack, MonadIO m) => Ptr () -> m Word32
iconNewForString :: (HasCallStack, MonadIO m) => Text -> m Icon
iconSerialize :: (HasCallStack, MonadIO m, IsIcon a) => a -> m 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

GObject Icon Source #
Instance details Defined in GI.Gio.Interfaces.Icon Methods gobjectType :: Icon -> IO GType #
IsObject Icon Source #
Instance details Defined in GI.Gio.Interfaces.Icon
IsIcon Icon Source #
Instance details Defined in GI.Gio.Interfaces.Icon

noIcon :: Maybe Icon Source #

A convenience alias for Nothing :: Maybe Icon.

class GObject o => IsIcon o Source #

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

Instances

(GObject a, (UnknownAncestorError Icon a :: Constraint)) => IsIcon a Source #
Instance details Defined in GI.Gio.Interfaces.Icon
IsIcon Icon Source #
Instance details Defined in GI.Gio.Interfaces.Icon
IsIcon LoadableIcon Source #
Instance details Defined in GI.Gio.Interfaces.LoadableIcon
IsIcon BytesIcon Source #
Instance details Defined in GI.Gio.Objects.BytesIcon
IsIcon Emblem Source #
Instance details Defined in GI.Gio.Objects.Emblem
IsIcon EmblemedIcon Source #
Instance details Defined in GI.Gio.Objects.EmblemedIcon
IsIcon FileIcon Source #
Instance details Defined in GI.Gio.Objects.FileIcon
IsIcon ThemedIcon Source #
Instance details Defined in GI.Gio.Objects.ThemedIcon

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

deserialize

iconDeserialize Source #

Arguments

:: (HasCallStack, MonadIO m)
=> GVariant	`value`: a `GVariant` created with `iconSerialize`
-> m 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)
=> Ptr ()	`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 GVariant	Returns: a `GVariant`, or `Nothing` when serialization fails.

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, the encoding is simply the name (such as network-server).

Since: 2.20