    {- |
    Copyright  : Will Thompson, Iñaki García Etxebarria and Jonas Platte
    License    : LGPL-2.1
    Maintainer : Iñaki García Etxebarria (garetxe@gmail.com)

    'GI.Gio.Interfaces.Icon.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.

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

    To obtain a hash of a 'GI.Gio.Interfaces.Icon.Icon', see 'GI.Gio.Functions.iconHash'.

    To check if two @/GIcons/@ are equal, see 'GI.Gio.Interfaces.Icon.iconEqual'.

    For serializing a 'GI.Gio.Interfaces.Icon.Icon', use 'GI.Gio.Interfaces.Icon.iconSerialize' and
    'GI.Gio.Functions.iconDeserialize'.

    If you want to consume 'GI.Gio.Interfaces.Icon.Icon' (for example, in a toolkit) you must
    be prepared to handle at least the three following cases:
    'GI.Gio.Interfaces.LoadableIcon.LoadableIcon', 'GI.Gio.Objects.ThemedIcon.ThemedIcon' and 'GI.Gio.Objects.EmblemedIcon.EmblemedIcon'.  It may also make
    sense to have fast-paths for other cases (like handling @/GdkPixbuf/@
    directly, for example) but all compliant 'GI.Gio.Interfaces.Icon.Icon' implementations
    outside of GIO must implement 'GI.Gio.Interfaces.LoadableIcon.LoadableIcon'.

    If your application or library provides one or more 'GI.Gio.Interfaces.Icon.Icon'
    implementations you need to ensure that your new implementation also
    implements 'GI.Gio.Interfaces.LoadableIcon.LoadableIcon'.  Additionally, you must provide an
    implementation of 'GI.Gio.Interfaces.Icon.iconSerialize' that gives a result that is
    understood by 'GI.Gio.Functions.iconDeserialize', yielding one of the built-in icon
    types.
    -}

    #define ENABLE_OVERLOADING \
           (!defined(__HADDOCK_VERSION__))

    module GI.Gio.Interfaces.Icon
        (

    -- * Exported types
        Icon(..)                                ,
        noIcon                                  ,
        IsIcon                                  ,
        toIcon                                  ,

     -- * Methods
    -- ** deserialize #method:deserialize#

        iconDeserialize                         ,

    -- ** equal #method:equal#

    #if ENABLE_OVERLOADING
        IconEqualMethodInfo                     ,
    #endif
        iconEqual                               ,

    -- ** hash #method:hash#

        iconHash                                ,

    -- ** newForString #method:newForString#

        iconNewForString                        ,

    -- ** serialize #method:serialize#

    #if ENABLE_OVERLOADING
        IconSerializeMethodInfo                 ,
    #endif
        iconSerialize                           ,

    -- ** toString #method:toString#

    #if ENABLE_OVERLOADING
        IconToStringMethodInfo                  ,
    #endif
        iconToString                            ,

        ) where

    import Data.GI.Base.ShortPrelude
    import qualified Data.GI.Base.ShortPrelude as SP
    import qualified Data.GI.Base.Overloading as O
    import qualified Prelude as P

    import qualified Data.GI.Base.Attributes as GI.Attributes
    import qualified Data.GI.Base.ManagedPtr as B.ManagedPtr
    import qualified Data.GI.Base.GError as B.GError
    import qualified Data.GI.Base.GVariant as B.GVariant
    import qualified Data.GI.Base.GValue as B.GValue
    import qualified Data.GI.Base.GParamSpec as B.GParamSpec
    import qualified Data.GI.Base.CallStack as B.CallStack
    import qualified Data.Text as T
    import qualified Data.ByteString.Char8 as B
    import qualified Data.Map as Map
    import qualified Foreign.Ptr as FP

    import qualified GI.GObject.Objects.Object as GObject.Object

    -- interface Icon
    -- | Memory-managed wrapper type.
    newtype Icon = Icon (ManagedPtr Icon)
    -- | A convenience alias for `Nothing` :: `Maybe` `Icon`.
    noIcon :: Maybe Icon
    noIcon = Nothing

    #if ENABLE_OVERLOADING
    type instance O.SignalList Icon = IconSignalList
    type IconSignalList = ('[ '("notify", GObject.Object.ObjectNotifySignalInfo)] :: [(Symbol, *)])

    #endif

    foreign import ccall "g_icon_get_type"
        c_g_icon_get_type :: IO GType

    instance GObject Icon where
        gobjectType _ = c_g_icon_get_type

    -- | Type class for types which can be safely cast to `Icon`, for instance with `toIcon`.
    class GObject o => IsIcon o
    #if MIN_VERSION_base(4,9,0)
    instance {-# OVERLAPPABLE #-} (GObject a, O.UnknownAncestorError Icon a) =>
        IsIcon a
    #endif
    instance IsIcon Icon
    instance GObject.Object.IsObject Icon

    -- | Cast to `Icon`, for types for which this is known to be safe. For general casts, use `Data.GI.Base.ManagedPtr.castTo`.
    toIcon :: (MonadIO m, IsIcon o) => o -> m Icon
    toIcon = liftIO . unsafeCastTo Icon

    #if ENABLE_OVERLOADING
    instance O.HasAttributeList Icon
    type instance O.AttributeList Icon = IconAttributeList
    type IconAttributeList = ('[ ] :: [(Symbol, *)])
    #endif

    #if ENABLE_OVERLOADING
    #endif

    #if ENABLE_OVERLOADING
    type family ResolveIconMethod (t :: Symbol) (o :: *) :: * where
        ResolveIconMethod "bindProperty" o = GObject.Object.ObjectBindPropertyMethodInfo
        ResolveIconMethod "bindPropertyFull" o = GObject.Object.ObjectBindPropertyFullMethodInfo
        ResolveIconMethod "equal" o = IconEqualMethodInfo
        ResolveIconMethod "forceFloating" o = GObject.Object.ObjectForceFloatingMethodInfo
        ResolveIconMethod "freezeNotify" o = GObject.Object.ObjectFreezeNotifyMethodInfo
        ResolveIconMethod "getv" o = GObject.Object.ObjectGetvMethodInfo
        ResolveIconMethod "isFloating" o = GObject.Object.ObjectIsFloatingMethodInfo
        ResolveIconMethod "notify" o = GObject.Object.ObjectNotifyMethodInfo
        ResolveIconMethod "notifyByPspec" o = GObject.Object.ObjectNotifyByPspecMethodInfo
        ResolveIconMethod "ref" o = GObject.Object.ObjectRefMethodInfo
        ResolveIconMethod "refSink" o = GObject.Object.ObjectRefSinkMethodInfo
        ResolveIconMethod "runDispose" o = GObject.Object.ObjectRunDisposeMethodInfo
        ResolveIconMethod "serialize" o = IconSerializeMethodInfo
        ResolveIconMethod "stealData" o = GObject.Object.ObjectStealDataMethodInfo
        ResolveIconMethod "stealQdata" o = GObject.Object.ObjectStealQdataMethodInfo
        ResolveIconMethod "thawNotify" o = GObject.Object.ObjectThawNotifyMethodInfo
        ResolveIconMethod "toString" o = IconToStringMethodInfo
        ResolveIconMethod "unref" o = GObject.Object.ObjectUnrefMethodInfo
        ResolveIconMethod "watchClosure" o = GObject.Object.ObjectWatchClosureMethodInfo
        ResolveIconMethod "getData" o = GObject.Object.ObjectGetDataMethodInfo
        ResolveIconMethod "getProperty" o = GObject.Object.ObjectGetPropertyMethodInfo
        ResolveIconMethod "getQdata" o = GObject.Object.ObjectGetQdataMethodInfo
        ResolveIconMethod "setData" o = GObject.Object.ObjectSetDataMethodInfo
        ResolveIconMethod "setProperty" o = GObject.Object.ObjectSetPropertyMethodInfo
        ResolveIconMethod l o = O.MethodResolutionFailed l o

    instance (info ~ ResolveIconMethod t Icon, O.MethodInfo info Icon p) => O.IsLabelProxy t (Icon -> p) where
        fromLabelProxy _ = O.overloadedMethod (O.MethodProxy :: O.MethodProxy info)

    #if MIN_VERSION_base(4,9,0)
    instance (info ~ ResolveIconMethod t Icon, O.MethodInfo info Icon p) => O.IsLabel t (Icon -> p) where
    #if MIN_VERSION_base(4,10,0)
        fromLabel = O.overloadedMethod (O.MethodProxy :: O.MethodProxy info)
    #else
        fromLabel _ = O.overloadedMethod (O.MethodProxy :: O.MethodProxy info)
    #endif
    #endif

    #endif

    -- method Icon::equal
    -- method type : OrdinaryMethod
    -- Args : [Arg {argCName = "icon1", argType = TInterface (Name {namespace = "Gio", name = "Icon"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "pointer to the first #GIcon.", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing},Arg {argCName = "icon2", argType = TInterface (Name {namespace = "Gio", name = "Icon"}), direction = DirectionIn, mayBeNull = True, argDoc = Documentation {rawDocText = Just "pointer to the second #GIcon.", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
    -- Lengths : []
    -- returnType : Just (TBasicType TBoolean)
    -- throws : False
    -- Skip return : False

    foreign import ccall "g_icon_equal" g_icon_equal ::
        Ptr Icon ->                             -- icon1 : TInterface (Name {namespace = "Gio", name = "Icon"})
        Ptr Icon ->                             -- icon2 : TInterface (Name {namespace = "Gio", name = "Icon"})
        IO CInt

    {- |
    Checks if two icons are equal.
    -}
    iconEqual ::
        (B.CallStack.HasCallStack, MonadIO m, IsIcon a, IsIcon b) =>
        a
        {- ^ /@icon1@/: pointer to the first 'GI.Gio.Interfaces.Icon.Icon'. -}
        -> Maybe (b)
        {- ^ /@icon2@/: pointer to the second 'GI.Gio.Interfaces.Icon.Icon'. -}
        -> m Bool
        {- ^ __Returns:__ 'True' if /@icon1@/ is equal to /@icon2@/. 'False' otherwise. -}
    iconEqual icon1 icon2 = liftIO $ do
        icon1' <- unsafeManagedPtrCastPtr icon1
        maybeIcon2 <- case icon2 of
            Nothing -> return nullPtr
            Just jIcon2 -> do
                jIcon2' <- unsafeManagedPtrCastPtr jIcon2
                return jIcon2'
        result <- g_icon_equal icon1' maybeIcon2
        let result' = (/= 0) result
        touchManagedPtr icon1
        whenJust icon2 touchManagedPtr
        return result'

    #if ENABLE_OVERLOADING
    data IconEqualMethodInfo
    instance (signature ~ (Maybe (b) -> m Bool), MonadIO m, IsIcon a, IsIcon b) => O.MethodInfo IconEqualMethodInfo a signature where
        overloadedMethod _ = iconEqual

    #endif

    -- method Icon::serialize
    -- method type : OrdinaryMethod
    -- Args : [Arg {argCName = "icon", argType = TInterface (Name {namespace = "Gio", name = "Icon"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GIcon", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
    -- Lengths : []
    -- returnType : Just TVariant
    -- throws : False
    -- Skip return : False

    foreign import ccall "g_icon_serialize" g_icon_serialize ::
        Ptr Icon ->                             -- icon : TInterface (Name {namespace = "Gio", name = "Icon"})
        IO (Ptr GVariant)

    {- |
    Serializes a 'GI.Gio.Interfaces.Icon.Icon' into a 'GVariant'. An equivalent 'GI.Gio.Interfaces.Icon.Icon' can be retrieved
    back by calling 'GI.Gio.Functions.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/
    -}
    iconSerialize ::
        (B.CallStack.HasCallStack, MonadIO m, IsIcon a) =>
        a
        {- ^ /@icon@/: a 'GI.Gio.Interfaces.Icon.Icon' -}
        -> m GVariant
        {- ^ __Returns:__ a 'GVariant', or 'Nothing' when serialization fails. -}
    iconSerialize icon = liftIO $ do
        icon' <- unsafeManagedPtrCastPtr icon
        result <- g_icon_serialize icon'
        checkUnexpectedReturnNULL "iconSerialize" result
        result' <- B.GVariant.wrapGVariantPtr result
        touchManagedPtr icon
        return result'

    #if ENABLE_OVERLOADING
    data IconSerializeMethodInfo
    instance (signature ~ (m GVariant), MonadIO m, IsIcon a) => O.MethodInfo IconSerializeMethodInfo a signature where
        overloadedMethod _ = iconSerialize

    #endif

    -- method Icon::to_string
    -- method type : OrdinaryMethod
    -- Args : [Arg {argCName = "icon", argType = TInterface (Name {namespace = "Gio", name = "Icon"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GIcon.", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
    -- Lengths : []
    -- returnType : Just (TBasicType TUTF8)
    -- throws : False
    -- Skip return : False

    foreign import ccall "g_icon_to_string" g_icon_to_string ::
        Ptr Icon ->                             -- icon : TInterface (Name {namespace = "Gio", name = "Icon"})
        IO CString

    {- |
    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 'GI.Gio.Functions.iconNewForString' to
    get /@icon@/ back from the returned string.

    The encoding of the returned string is proprietary to 'GI.Gio.Interfaces.Icon.Icon' except
    in the following two cases

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

    /Since: 2.20/
    -}
    iconToString ::
        (B.CallStack.HasCallStack, MonadIO m, IsIcon a) =>
        a
        {- ^ /@icon@/: a 'GI.Gio.Interfaces.Icon.Icon'. -}
        -> m (Maybe T.Text)
        {- ^ __Returns:__ An allocated NUL-terminated UTF8 string or
    'Nothing' if /@icon@/ can\'t be serialized. Use 'GI.GLib.Functions.free' to free. -}
    iconToString icon = liftIO $ do
        icon' <- unsafeManagedPtrCastPtr icon
        result <- g_icon_to_string icon'
        maybeResult <- convertIfNonNull result $ \result' -> do
            result'' <- cstringToText result'
            freeMem result'
            return result''
        touchManagedPtr icon
        return maybeResult

    #if ENABLE_OVERLOADING
    data IconToStringMethodInfo
    instance (signature ~ (m (Maybe T.Text)), MonadIO m, IsIcon a) => O.MethodInfo IconToStringMethodInfo a signature where
        overloadedMethod _ = iconToString

    #endif

    -- method Icon::deserialize
    -- method type : MemberFunction
    -- Args : [Arg {argCName = "value", argType = TVariant, direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GVariant created with g_icon_serialize()", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
    -- Lengths : []
    -- returnType : Just (TInterface (Name {namespace = "Gio", name = "Icon"}))
    -- throws : False
    -- Skip return : False

    foreign import ccall "g_icon_deserialize" g_icon_deserialize ::
        Ptr GVariant ->                         -- value : TVariant
        IO (Ptr Icon)

    {- |
    Deserializes a 'GI.Gio.Interfaces.Icon.Icon' previously serialized using 'GI.Gio.Interfaces.Icon.iconSerialize'.

    /Since: 2.38/
    -}
    iconDeserialize ::
        (B.CallStack.HasCallStack, MonadIO m) =>
        GVariant
        {- ^ /@value@/: a 'GVariant' created with 'GI.Gio.Interfaces.Icon.iconSerialize' -}
        -> m Icon
        {- ^ __Returns:__ a 'GI.Gio.Interfaces.Icon.Icon', or 'Nothing' when deserialization fails. -}
    iconDeserialize value = liftIO $ do
        value' <- unsafeManagedPtrGetPtr value
        result <- g_icon_deserialize value'
        checkUnexpectedReturnNULL "iconDeserialize" result
        result' <- (wrapObject Icon) result
        touchManagedPtr value
        return result'

    #if ENABLE_OVERLOADING
    #endif

    -- method Icon::hash
    -- method type : MemberFunction
    -- Args : [Arg {argCName = "icon", argType = TBasicType TPtr, direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "#gconstpointer to an icon object.", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
    -- Lengths : []
    -- returnType : Just (TBasicType TUInt)
    -- throws : False
    -- Skip return : False

    foreign import ccall "g_icon_hash" g_icon_hash ::
        Ptr () ->                               -- icon : TBasicType TPtr
        IO Word32

    {- |
    Gets a hash for an icon.
    -}
    iconHash ::
        (B.CallStack.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 'GI.GLib.Structs.HashTable.HashTable' or similar data structure. -}
    iconHash icon = liftIO $ do
        result <- g_icon_hash icon
        return result

    #if ENABLE_OVERLOADING
    #endif

    -- method Icon::new_for_string
    -- method type : MemberFunction
    -- Args : [Arg {argCName = "str", argType = TBasicType TUTF8, direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "A string obtained via g_icon_to_string().", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
    -- Lengths : []
    -- returnType : Just (TInterface (Name {namespace = "Gio", name = "Icon"}))
    -- throws : True
    -- Skip return : False

    foreign import ccall "g_icon_new_for_string" g_icon_new_for_string ::
        CString ->                              -- str : TBasicType TUTF8
        Ptr (Ptr GError) ->                     -- error
        IO (Ptr Icon)

    {- |
    Generate a 'GI.Gio.Interfaces.Icon.Icon' instance from /@str@/. This function can fail if
    /@str@/ is not valid - see 'GI.Gio.Interfaces.Icon.iconToString' for discussion.

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

    /Since: 2.20/
    -}
    iconNewForString ::
        (B.CallStack.HasCallStack, MonadIO m) =>
        T.Text
        {- ^ /@str@/: A string obtained via 'GI.Gio.Interfaces.Icon.iconToString'. -}
        -> m Icon
        {- ^ __Returns:__ An object implementing the 'GI.Gio.Interfaces.Icon.Icon'
             interface or 'Nothing' if /@error@/ is set. /(Can throw 'Data.GI.Base.GError.GError')/ -}
    iconNewForString str = liftIO $ do
        str' <- textToCString str
        onException (do
            result <- propagateGError $ g_icon_new_for_string str'
            checkUnexpectedReturnNULL "iconNewForString" result
            result' <- (wrapObject Icon) result
            freeMem str'
            return result'
         ) (do
            freeMem str'
         )

    #if ENABLE_OVERLOADING
    #endif