{-# LANGUAGE TypeApplications #-}


-- | Copyright  : Will Thompson, Iñaki García Etxebarria and Jonas Platte
-- License    : LGPL-2.1
-- Maintainer : Iñaki García Etxebarria
-- 
-- The GObject type system supports dynamic loading of types.
-- The t'GI.GObject.Interfaces.TypePlugin.TypePlugin' interface is used to handle the lifecycle
-- of dynamically loaded types. It goes as follows:
-- 
-- 1. The type is initially introduced (usually upon loading the module
--    the first time, or by your main application that knows what modules
--    introduces what types), like this:
--    
-- === /C code/
-- >
-- >   new_type_id = g_type_register_dynamic (parent_type_id,
-- >                                          "TypeName",
-- >                                          new_type_plugin,
-- >                                          type_flags);
-- >   
-- 
--    where /@newTypePlugin@/ is an implementation of the
--    t'GI.GObject.Interfaces.TypePlugin.TypePlugin' interface.
-- 
-- 2. The type\'s implementation is referenced, e.g. through
--    'GI.GObject.Functions.typeClassRef' or through @/g_type_create_instance()/@ (this is
--    being called by @/g_object_new()/@) or through one of the above done on
--    a type derived from /@newTypeId@/.
-- 
-- 3. This causes the type system to load the type\'s implementation by
--    calling 'GI.GObject.Interfaces.TypePlugin.typePluginUse' and 'GI.GObject.Interfaces.TypePlugin.typePluginCompleteTypeInfo'
--    on /@newTypePlugin@/.
-- 
-- 4. At some point the type\'s implementation isn\'t required anymore,
--    e.g. after 'GI.GObject.Structs.TypeClass.typeClassUnref' or 'GI.GObject.Functions.typeFreeInstance' (called
--    when the reference count of an instance drops to zero).
-- 
-- 5. This causes the type system to throw away the information retrieved
--    from 'GI.GObject.Interfaces.TypePlugin.typePluginCompleteTypeInfo' and then it calls
--    'GI.GObject.Interfaces.TypePlugin.typePluginUnuse' on /@newTypePlugin@/.
-- 
-- 6. Things may repeat from the second step.
-- 
-- So basically, you need to implement a t'GI.GObject.Interfaces.TypePlugin.TypePlugin' type that
-- carries a use_count, once use_count goes from zero to one, you need
-- to load the implementation to successfully handle the upcoming
-- 'GI.GObject.Interfaces.TypePlugin.typePluginCompleteTypeInfo' call. Later, maybe after
-- succeeding use\/unuse calls, once use_count drops to zero, you can
-- unload the implementation again. The type system makes sure to call
-- 'GI.GObject.Interfaces.TypePlugin.typePluginUse' and 'GI.GObject.Interfaces.TypePlugin.typePluginCompleteTypeInfo' again
-- when the type is needed again.
-- 
-- t'GI.GObject.Objects.TypeModule.TypeModule' is an implementation of t'GI.GObject.Interfaces.TypePlugin.TypePlugin' that already
-- implements most of this except for the actual module loading and
-- unloading. It even handles multiple registered types per module.

#if (MIN_VERSION_haskell_gi_overloading(1,0,0) && !defined(__HADDOCK_VERSION__))
#define ENABLE_OVERLOADING
#endif

module GI.GObject.Interfaces.TypePlugin
    (

-- * Exported types
    TypePlugin(..)                          ,
    noTypePlugin                            ,
    IsTypePlugin                            ,


 -- * Methods
-- ** Overloaded methods #method:Overloaded methods#

#if defined(ENABLE_OVERLOADING)
    ResolveTypePluginMethod                 ,
#endif


-- ** completeInterfaceInfo #method:completeInterfaceInfo#

#if defined(ENABLE_OVERLOADING)
    TypePluginCompleteInterfaceInfoMethodInfo,
#endif
    typePluginCompleteInterfaceInfo         ,


-- ** completeTypeInfo #method:completeTypeInfo#

#if defined(ENABLE_OVERLOADING)
    TypePluginCompleteTypeInfoMethodInfo    ,
#endif
    typePluginCompleteTypeInfo              ,


-- ** unuse #method:unuse#

#if defined(ENABLE_OVERLOADING)
    TypePluginUnuseMethodInfo               ,
#endif
    typePluginUnuse                         ,


-- ** use #method:use#

#if defined(ENABLE_OVERLOADING)
    TypePluginUseMethodInfo                 ,
#endif
    typePluginUse                           ,




    ) 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.GI.Base.Signals as B.Signals
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 {-# SOURCE #-} qualified GI.GObject.Structs.InterfaceInfo as GObject.InterfaceInfo
import {-# SOURCE #-} qualified GI.GObject.Structs.TypeInfo as GObject.TypeInfo
import {-# SOURCE #-} qualified GI.GObject.Structs.TypeValueTable as GObject.TypeValueTable

-- interface TypePlugin 
-- | Memory-managed wrapper type.
newtype TypePlugin = TypePlugin (ManagedPtr TypePlugin)
    deriving (Eq)
-- | A convenience alias for `Nothing` :: `Maybe` `TypePlugin`.
noTypePlugin :: Maybe TypePlugin
noTypePlugin = Nothing

#if defined(ENABLE_OVERLOADING)
type instance O.SignalList TypePlugin = TypePluginSignalList
type TypePluginSignalList = ('[ ] :: [(Symbol, *)])

#endif

-- | Type class for types which implement `TypePlugin`.
class (ManagedPtrNewtype o, O.IsDescendantOf TypePlugin o) => IsTypePlugin o
instance (ManagedPtrNewtype o, O.IsDescendantOf TypePlugin o) => IsTypePlugin o
-- XXX Wrapping a foreign struct/union with no known destructor or size, leak?
instance WrappedPtr TypePlugin where
    wrappedPtrCalloc = return nullPtr
    wrappedPtrCopy = return
    wrappedPtrFree = Nothing


#if defined(ENABLE_OVERLOADING)
type family ResolveTypePluginMethod (t :: Symbol) (o :: *) :: * where
    ResolveTypePluginMethod "completeInterfaceInfo" o = TypePluginCompleteInterfaceInfoMethodInfo
    ResolveTypePluginMethod "completeTypeInfo" o = TypePluginCompleteTypeInfoMethodInfo
    ResolveTypePluginMethod "unuse" o = TypePluginUnuseMethodInfo
    ResolveTypePluginMethod "use" o = TypePluginUseMethodInfo
    ResolveTypePluginMethod l o = O.MethodResolutionFailed l o

instance (info ~ ResolveTypePluginMethod t TypePlugin, O.MethodInfo info TypePlugin p) => OL.IsLabel t (TypePlugin -> p) where
#if MIN_VERSION_base(4,10,0)
    fromLabel = O.overloadedMethod @info
#else
    fromLabel _ = O.overloadedMethod @info
#endif

#endif

-- method TypePlugin::complete_interface_info
-- method type : OrdinaryMethod
-- Args: [ Arg
--           { argCName = "plugin"
--           , argType =
--               TInterface Name { namespace = "GObject" , name = "TypePlugin" }
--           , direction = DirectionIn
--           , mayBeNull = False
--           , argDoc =
--               Documentation
--                 { rawDocText = Just "the #GTypePlugin" , sinceVersion = Nothing }
--           , argScope = ScopeTypeInvalid
--           , argClosure = -1
--           , argDestroy = -1
--           , argCallerAllocates = False
--           , transfer = TransferNothing
--           }
--       , Arg
--           { argCName = "instance_type"
--           , argType = TBasicType TGType
--           , direction = DirectionIn
--           , mayBeNull = False
--           , argDoc =
--               Documentation
--                 { rawDocText =
--                     Just
--                       "the #GType of an instantiable type to which the interface\n is added"
--                 , sinceVersion = Nothing
--                 }
--           , argScope = ScopeTypeInvalid
--           , argClosure = -1
--           , argDestroy = -1
--           , argCallerAllocates = False
--           , transfer = TransferNothing
--           }
--       , Arg
--           { argCName = "interface_type"
--           , argType = TBasicType TGType
--           , direction = DirectionIn
--           , mayBeNull = False
--           , argDoc =
--               Documentation
--                 { rawDocText =
--                     Just "the #GType of the interface whose info is completed"
--                 , sinceVersion = Nothing
--                 }
--           , argScope = ScopeTypeInvalid
--           , argClosure = -1
--           , argDestroy = -1
--           , argCallerAllocates = False
--           , transfer = TransferNothing
--           }
--       , Arg
--           { argCName = "info"
--           , argType =
--               TInterface Name { namespace = "GObject" , name = "InterfaceInfo" }
--           , direction = DirectionIn
--           , mayBeNull = False
--           , argDoc =
--               Documentation
--                 { rawDocText = Just "the #GInterfaceInfo to fill in"
--                 , sinceVersion = Nothing
--                 }
--           , argScope = ScopeTypeInvalid
--           , argClosure = -1
--           , argDestroy = -1
--           , argCallerAllocates = False
--           , transfer = TransferNothing
--           }
--       ]
-- Lengths: []
-- returnType: Nothing
-- throws : False
-- Skip return : False

foreign import ccall "g_type_plugin_complete_interface_info" g_type_plugin_complete_interface_info ::
    Ptr TypePlugin ->                       -- plugin : TInterface (Name {namespace = "GObject", name = "TypePlugin"})
    CGType ->                               -- instance_type : TBasicType TGType
    CGType ->                               -- interface_type : TBasicType TGType
    Ptr GObject.InterfaceInfo.InterfaceInfo -> -- info : TInterface (Name {namespace = "GObject", name = "InterfaceInfo"})
    IO ()

-- | Calls the /@completeInterfaceInfo@/ function from the
-- @/GTypePluginClass/@ of /@plugin@/. There should be no need to use this
-- function outside of the GObject type system itself.
typePluginCompleteInterfaceInfo ::
    (B.CallStack.HasCallStack, MonadIO m, IsTypePlugin a) =>
    a
    -- ^ /@plugin@/: the t'GI.GObject.Interfaces.TypePlugin.TypePlugin'
    -> GType
    -- ^ /@instanceType@/: the t'GType' of an instantiable type to which the interface
    --  is added
    -> GType
    -- ^ /@interfaceType@/: the t'GType' of the interface whose info is completed
    -> GObject.InterfaceInfo.InterfaceInfo
    -- ^ /@info@/: the t'GI.GObject.Structs.InterfaceInfo.InterfaceInfo' to fill in
    -> m ()
typePluginCompleteInterfaceInfo plugin instanceType interfaceType info = liftIO $ do
    plugin' <- unsafeManagedPtrCastPtr plugin
    let instanceType' = gtypeToCGType instanceType
    let interfaceType' = gtypeToCGType interfaceType
    info' <- unsafeManagedPtrGetPtr info
    g_type_plugin_complete_interface_info plugin' instanceType' interfaceType' info'
    touchManagedPtr plugin
    touchManagedPtr info
    return ()

#if defined(ENABLE_OVERLOADING)
data TypePluginCompleteInterfaceInfoMethodInfo
instance (signature ~ (GType -> GType -> GObject.InterfaceInfo.InterfaceInfo -> m ()), MonadIO m, IsTypePlugin a) => O.MethodInfo TypePluginCompleteInterfaceInfoMethodInfo a signature where
    overloadedMethod = typePluginCompleteInterfaceInfo

#endif

-- method TypePlugin::complete_type_info
-- method type : OrdinaryMethod
-- Args: [ Arg
--           { argCName = "plugin"
--           , argType =
--               TInterface Name { namespace = "GObject" , name = "TypePlugin" }
--           , direction = DirectionIn
--           , mayBeNull = False
--           , argDoc =
--               Documentation
--                 { rawDocText = Just "a #GTypePlugin" , sinceVersion = Nothing }
--           , argScope = ScopeTypeInvalid
--           , argClosure = -1
--           , argDestroy = -1
--           , argCallerAllocates = False
--           , transfer = TransferNothing
--           }
--       , Arg
--           { argCName = "g_type"
--           , argType = TBasicType TGType
--           , direction = DirectionIn
--           , mayBeNull = False
--           , argDoc =
--               Documentation
--                 { rawDocText = Just "the #GType whose info is completed"
--                 , sinceVersion = Nothing
--                 }
--           , argScope = ScopeTypeInvalid
--           , argClosure = -1
--           , argDestroy = -1
--           , argCallerAllocates = False
--           , transfer = TransferNothing
--           }
--       , Arg
--           { argCName = "info"
--           , argType =
--               TInterface Name { namespace = "GObject" , name = "TypeInfo" }
--           , direction = DirectionIn
--           , mayBeNull = False
--           , argDoc =
--               Documentation
--                 { rawDocText = Just "the #GTypeInfo struct to fill in"
--                 , sinceVersion = Nothing
--                 }
--           , argScope = ScopeTypeInvalid
--           , argClosure = -1
--           , argDestroy = -1
--           , argCallerAllocates = False
--           , transfer = TransferNothing
--           }
--       , Arg
--           { argCName = "value_table"
--           , argType =
--               TInterface Name { namespace = "GObject" , name = "TypeValueTable" }
--           , direction = DirectionIn
--           , mayBeNull = False
--           , argDoc =
--               Documentation
--                 { rawDocText = Just "the #GTypeValueTable to fill in"
--                 , sinceVersion = Nothing
--                 }
--           , argScope = ScopeTypeInvalid
--           , argClosure = -1
--           , argDestroy = -1
--           , argCallerAllocates = False
--           , transfer = TransferNothing
--           }
--       ]
-- Lengths: []
-- returnType: Nothing
-- throws : False
-- Skip return : False

foreign import ccall "g_type_plugin_complete_type_info" g_type_plugin_complete_type_info ::
    Ptr TypePlugin ->                       -- plugin : TInterface (Name {namespace = "GObject", name = "TypePlugin"})
    CGType ->                               -- g_type : TBasicType TGType
    Ptr GObject.TypeInfo.TypeInfo ->        -- info : TInterface (Name {namespace = "GObject", name = "TypeInfo"})
    Ptr GObject.TypeValueTable.TypeValueTable -> -- value_table : TInterface (Name {namespace = "GObject", name = "TypeValueTable"})
    IO ()

-- | Calls the /@completeTypeInfo@/ function from the @/GTypePluginClass/@ of /@plugin@/.
-- There should be no need to use this function outside of the GObject
-- type system itself.
typePluginCompleteTypeInfo ::
    (B.CallStack.HasCallStack, MonadIO m, IsTypePlugin a) =>
    a
    -- ^ /@plugin@/: a t'GI.GObject.Interfaces.TypePlugin.TypePlugin'
    -> GType
    -- ^ /@gType@/: the t'GType' whose info is completed
    -> GObject.TypeInfo.TypeInfo
    -- ^ /@info@/: the t'GI.GObject.Structs.TypeInfo.TypeInfo' struct to fill in
    -> GObject.TypeValueTable.TypeValueTable
    -- ^ /@valueTable@/: the t'GI.GObject.Structs.TypeValueTable.TypeValueTable' to fill in
    -> m ()
typePluginCompleteTypeInfo plugin gType info valueTable = liftIO $ do
    plugin' <- unsafeManagedPtrCastPtr plugin
    let gType' = gtypeToCGType gType
    info' <- unsafeManagedPtrGetPtr info
    valueTable' <- unsafeManagedPtrGetPtr valueTable
    g_type_plugin_complete_type_info plugin' gType' info' valueTable'
    touchManagedPtr plugin
    touchManagedPtr info
    touchManagedPtr valueTable
    return ()

#if defined(ENABLE_OVERLOADING)
data TypePluginCompleteTypeInfoMethodInfo
instance (signature ~ (GType -> GObject.TypeInfo.TypeInfo -> GObject.TypeValueTable.TypeValueTable -> m ()), MonadIO m, IsTypePlugin a) => O.MethodInfo TypePluginCompleteTypeInfoMethodInfo a signature where
    overloadedMethod = typePluginCompleteTypeInfo

#endif

-- method TypePlugin::unuse
-- method type : OrdinaryMethod
-- Args: [ Arg
--           { argCName = "plugin"
--           , argType =
--               TInterface Name { namespace = "GObject" , name = "TypePlugin" }
--           , direction = DirectionIn
--           , mayBeNull = False
--           , argDoc =
--               Documentation
--                 { rawDocText = Just "a #GTypePlugin" , sinceVersion = Nothing }
--           , argScope = ScopeTypeInvalid
--           , argClosure = -1
--           , argDestroy = -1
--           , argCallerAllocates = False
--           , transfer = TransferNothing
--           }
--       ]
-- Lengths: []
-- returnType: Nothing
-- throws : False
-- Skip return : False

foreign import ccall "g_type_plugin_unuse" g_type_plugin_unuse ::
    Ptr TypePlugin ->                       -- plugin : TInterface (Name {namespace = "GObject", name = "TypePlugin"})
    IO ()

-- | Calls the /@unusePlugin@/ function from the @/GTypePluginClass/@ of
-- /@plugin@/.  There should be no need to use this function outside of
-- the GObject type system itself.
typePluginUnuse ::
    (B.CallStack.HasCallStack, MonadIO m, IsTypePlugin a) =>
    a
    -- ^ /@plugin@/: a t'GI.GObject.Interfaces.TypePlugin.TypePlugin'
    -> m ()
typePluginUnuse plugin = liftIO $ do
    plugin' <- unsafeManagedPtrCastPtr plugin
    g_type_plugin_unuse plugin'
    touchManagedPtr plugin
    return ()

#if defined(ENABLE_OVERLOADING)
data TypePluginUnuseMethodInfo
instance (signature ~ (m ()), MonadIO m, IsTypePlugin a) => O.MethodInfo TypePluginUnuseMethodInfo a signature where
    overloadedMethod = typePluginUnuse

#endif

-- method TypePlugin::use
-- method type : OrdinaryMethod
-- Args: [ Arg
--           { argCName = "plugin"
--           , argType =
--               TInterface Name { namespace = "GObject" , name = "TypePlugin" }
--           , direction = DirectionIn
--           , mayBeNull = False
--           , argDoc =
--               Documentation
--                 { rawDocText = Just "a #GTypePlugin" , sinceVersion = Nothing }
--           , argScope = ScopeTypeInvalid
--           , argClosure = -1
--           , argDestroy = -1
--           , argCallerAllocates = False
--           , transfer = TransferNothing
--           }
--       ]
-- Lengths: []
-- returnType: Nothing
-- throws : False
-- Skip return : False

foreign import ccall "g_type_plugin_use" g_type_plugin_use ::
    Ptr TypePlugin ->                       -- plugin : TInterface (Name {namespace = "GObject", name = "TypePlugin"})
    IO ()

-- | Calls the /@usePlugin@/ function from the @/GTypePluginClass/@ of
-- /@plugin@/.  There should be no need to use this function outside of
-- the GObject type system itself.
typePluginUse ::
    (B.CallStack.HasCallStack, MonadIO m, IsTypePlugin a) =>
    a
    -- ^ /@plugin@/: a t'GI.GObject.Interfaces.TypePlugin.TypePlugin'
    -> m ()
typePluginUse plugin = liftIO $ do
    plugin' <- unsafeManagedPtrCastPtr plugin
    g_type_plugin_use plugin'
    touchManagedPtr plugin
    return ()

#if defined(ENABLE_OVERLOADING)
data TypePluginUseMethodInfo
instance (signature ~ (m ()), MonadIO m, IsTypePlugin a) => O.MethodInfo TypePluginUseMethodInfo a signature where
    overloadedMethod = typePluginUse

#endif