{- | Copyright : Will Thompson, Iñaki García Etxebarria and Jonas Platte License : LGPL-2.1 Maintainer : Iñaki García Etxebarria (inaki@blueleaf.cc) '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 (MIN_VERSION_haskell_gi_overloading(1,0,0) \ && !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.GClosure as B.GClosure 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.GI.Base.Properties as B.Properties 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 GHC.OverloadedLabels as OL 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, O.IsDescendantOf Icon o) => IsIcon o instance (GObject o, O.IsDescendantOf Icon o) => IsIcon o instance O.HasParentTypes Icon type instance O.ParentTypes Icon = '[GObject.Object.Object] -- | 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) => OL.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 -- 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