gi-gio-2.0.25: Gio bindings

CopyrightWill Thompson Iñaki García Etxebarria and Jonas Platte
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria
Safe HaskellNone
LanguageHaskell2010

GI.Gio.Interfaces.Icon

Contents

Description

tIcon 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.

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

To obtain a hash of a tIcon, see iconHash.

To check if two GIcons are equal, see iconEqual.

For serializing a tIcon, use iconSerialize and iconDeserialize.

If you want to consume tIcon (for example, in a toolkit) you must be prepared to handle at least the three following cases: tLoadableIcon, tThemedIcon and tEmblemedIcon. It may also make sense to have fast-paths for other cases (like handling GdkPixbuf directly, for example) but all compliant tIcon implementations outside of GIO must implement tLoadableIcon.

If your application or library provides one or more tIcon implementations you need to ensure that your new implementation also implements tLoadableIcon. 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

Exported types

newtype Icon Source #

Memory-managed wrapper type.

Constructors

Icon (ManagedPtr Icon) 
Instances
Eq Icon Source # 
Instance details

Defined in GI.Gio.Interfaces.Icon

Methods

(==) :: Icon -> Icon -> Bool

(/=) :: Icon -> Icon -> Bool

GObject Icon Source # 
Instance details

Defined in GI.Gio.Interfaces.Icon

Methods

gobjectType :: IO GType

IsGValue Icon Source #

Convert Icon to and from GValue with toGValue and fromGValue.

Instance details

Defined in GI.Gio.Interfaces.Icon

Methods

toGValue :: Icon -> IO GValue

fromGValue :: GValue -> IO Icon

HasParentTypes Icon Source # 
Instance details

Defined in GI.Gio.Interfaces.Icon

type ParentTypes Icon Source # 
Instance details

Defined in GI.Gio.Interfaces.Icon

type ParentTypes Icon = Object ': ([] :: [Type])

noIcon :: Maybe Icon Source #

A convenience alias for Nothing :: Maybe Icon.

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
(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

Overloaded methods

deserialize

iconDeserialize Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> GVariant

value: a tGVariant created with iconSerialize

-> m Icon

Returns: a tIcon, or Nothing when deserialization fails.

Deserializes a tIcon previously serialized using iconSerialize.

Since: 2.38

equal

iconEqual Source #

Arguments

:: (HasCallStack, MonadIO m, IsIcon a, IsIcon b) 
=> a

icon1: pointer to the first tIcon.

-> Maybe b

icon2: pointer to the second tIcon.

-> 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 tHashTable 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 tIcon interface or Nothing if error is set. (Can throw GError)

Generate a tIcon 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 tIcon implementations you need to ensure that each tGType 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 tIcon

-> m GVariant

Returns: a tGVariant, or Nothing when serialization fails.

Serializes a tIcon into a tGVariant. An equivalent tIcon 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 tGVariant 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 tIcon.

-> 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 tIcon except in the following two cases

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

Since: 2.20