    {- |
    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.Atk.Interfaces.Action.Action' should be implemented by instances of 'GI.Atk.Objects.Object.Object' classes
    with which the user can interact directly, i.e. buttons,
    checkboxes, scrollbars, e.g. components which are not \"passive\"
    providers of UI information.

    Exceptions: when the user interaction is already covered by another
    appropriate interface such as 'GI.Atk.Interfaces.EditableText.EditableText' (insert\/delete text,
    etc.) or 'GI.Atk.Interfaces.Value.Value' (set value) then these actions should not be
    exposed by 'GI.Atk.Interfaces.Action.Action' as well.

    Though most UI interactions on components should be invocable via
    keyboard as well as mouse, there will generally be a close mapping
    between \"mouse actions\" that are possible on a component and the
    AtkActions.  Where mouse and keyboard actions are redundant in
    effect, 'GI.Atk.Interfaces.Action.Action' should expose only one action rather than
    exposing redundant actions if possible.  By convention we have been
    using \"mouse centric\" terminology for 'GI.Atk.Interfaces.Action.Action' names.
    -}

    #define ENABLE_OVERLOADING \
           (!defined(__HADDOCK_VERSION__))

    module GI.Atk.Interfaces.Action
        (

    -- * Exported types
        Action(..)                              ,
        noAction                                ,
        IsAction                                ,

     -- * Methods
    -- ** doAction #method:doAction#

    #if ENABLE_OVERLOADING
        ActionDoActionMethodInfo                ,
    #endif
        actionDoAction                          ,

    -- ** getDescription #method:getDescription#

    #if ENABLE_OVERLOADING
        ActionGetDescriptionMethodInfo          ,
    #endif
        actionGetDescription                    ,

    -- ** getKeybinding #method:getKeybinding#

    #if ENABLE_OVERLOADING
        ActionGetKeybindingMethodInfo           ,
    #endif
        actionGetKeybinding                     ,

    -- ** getLocalizedName #method:getLocalizedName#

    #if ENABLE_OVERLOADING
        ActionGetLocalizedNameMethodInfo        ,
    #endif
        actionGetLocalizedName                  ,

    -- ** getNActions #method:getNActions#

    #if ENABLE_OVERLOADING
        ActionGetNActionsMethodInfo             ,
    #endif
        actionGetNActions                       ,

    -- ** getName #method:getName#

    #if ENABLE_OVERLOADING
        ActionGetNameMethodInfo                 ,
    #endif
        actionGetName                           ,

    -- ** setDescription #method:setDescription#

    #if ENABLE_OVERLOADING
        ActionSetDescriptionMethodInfo          ,
    #endif
        actionSetDescription                    ,

        ) 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

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

    #if ENABLE_OVERLOADING
    type instance O.SignalList Action = ActionSignalList
    type ActionSignalList = ('[ ] :: [(Symbol, *)])

    #endif

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

    #if ENABLE_OVERLOADING
    type family ResolveActionMethod (t :: Symbol) (o :: *) :: * where
        ResolveActionMethod "doAction" o = ActionDoActionMethodInfo
        ResolveActionMethod "getDescription" o = ActionGetDescriptionMethodInfo
        ResolveActionMethod "getKeybinding" o = ActionGetKeybindingMethodInfo
        ResolveActionMethod "getLocalizedName" o = ActionGetLocalizedNameMethodInfo
        ResolveActionMethod "getNActions" o = ActionGetNActionsMethodInfo
        ResolveActionMethod "getName" o = ActionGetNameMethodInfo
        ResolveActionMethod "setDescription" o = ActionSetDescriptionMethodInfo
        ResolveActionMethod l o = O.MethodResolutionFailed l o

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

    #if MIN_VERSION_base(4,9,0)
    instance (info ~ ResolveActionMethod t Action, O.MethodInfo info Action p) => O.IsLabel t (Action -> 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 Action::do_action
    -- method type : OrdinaryMethod
    -- Args : [Arg {argCName = "action", argType = TInterface (Name {namespace = "Atk", name = "Action"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GObject instance that implements AtkActionIface", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing},Arg {argCName = "i", argType = TBasicType TInt, direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "the action index corresponding to the action to be performed", 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 "atk_action_do_action" atk_action_do_action ::
        Ptr Action ->                           -- action : TInterface (Name {namespace = "Atk", name = "Action"})
        Int32 ->                                -- i : TBasicType TInt
        IO CInt

    {- |
    Perform the specified action on the object.
    -}
    actionDoAction ::
        (B.CallStack.HasCallStack, MonadIO m, IsAction a) =>
        a
        {- ^ /@action@/: a 'GI.GObject.Objects.Object.Object' instance that implements AtkActionIface -}
        -> Int32
        {- ^ /@i@/: the action index corresponding to the action to be performed -}
        -> m Bool
        {- ^ __Returns:__ 'True' if success, 'False' otherwise -}
    actionDoAction action i = liftIO $ do
        action' <- unsafeManagedPtrCastPtr action
        result <- atk_action_do_action action' i
        let result' = (/= 0) result
        touchManagedPtr action
        return result'

    #if ENABLE_OVERLOADING
    data ActionDoActionMethodInfo
    instance (signature ~ (Int32 -> m Bool), MonadIO m, IsAction a) => O.MethodInfo ActionDoActionMethodInfo a signature where
        overloadedMethod _ = actionDoAction

    #endif

    -- method Action::get_description
    -- method type : OrdinaryMethod
    -- Args : [Arg {argCName = "action", argType = TInterface (Name {namespace = "Atk", name = "Action"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GObject instance that implements AtkActionIface", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing},Arg {argCName = "i", argType = TBasicType TInt, direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "the action index corresponding to the action to be performed", 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 "atk_action_get_description" atk_action_get_description ::
        Ptr Action ->                           -- action : TInterface (Name {namespace = "Atk", name = "Action"})
        Int32 ->                                -- i : TBasicType TInt
        IO CString

    {- |
    Returns a description of the specified action of the object.
    -}
    actionGetDescription ::
        (B.CallStack.HasCallStack, MonadIO m, IsAction a) =>
        a
        {- ^ /@action@/: a 'GI.GObject.Objects.Object.Object' instance that implements AtkActionIface -}
        -> Int32
        {- ^ /@i@/: the action index corresponding to the action to be performed -}
        -> m (Maybe T.Text)
        {- ^ __Returns:__ a description string, or 'Nothing' if /@action@/ does
    not implement this interface. -}
    actionGetDescription action i = liftIO $ do
        action' <- unsafeManagedPtrCastPtr action
        result <- atk_action_get_description action' i
        maybeResult <- convertIfNonNull result $ \result' -> do
            result'' <- cstringToText result'
            return result''
        touchManagedPtr action
        return maybeResult

    #if ENABLE_OVERLOADING
    data ActionGetDescriptionMethodInfo
    instance (signature ~ (Int32 -> m (Maybe T.Text)), MonadIO m, IsAction a) => O.MethodInfo ActionGetDescriptionMethodInfo a signature where
        overloadedMethod _ = actionGetDescription

    #endif

    -- method Action::get_keybinding
    -- method type : OrdinaryMethod
    -- Args : [Arg {argCName = "action", argType = TInterface (Name {namespace = "Atk", name = "Action"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GObject instance that implements AtkActionIface", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing},Arg {argCName = "i", argType = TBasicType TInt, direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "the action index corresponding to the action to be performed", 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 "atk_action_get_keybinding" atk_action_get_keybinding ::
        Ptr Action ->                           -- action : TInterface (Name {namespace = "Atk", name = "Action"})
        Int32 ->                                -- i : TBasicType TInt
        IO CString

    {- |
    Gets the keybinding which can be used to activate this action, if one
    exists. The string returned should contain localized, human-readable,
    key sequences as they would appear when displayed on screen. It must
    be in the format \"mnemonic;sequence;shortcut\".

    * The mnemonic key activates the object if it is presently enabled onscreen.
    This typically corresponds to the underlined letter within the widget.
    Example: \"n\" in a traditional \"New...\" menu item or the \"a\" in \"Apply\" for
    a button.
    * The sequence is the full list of keys which invoke the action even if the
    relevant element is not currently shown on screen. For instance, for a menu
    item the sequence is the keybindings used to open the parent menus before
    invoking. The sequence string is colon-delimited. Example: \"Alt+F:N\" in a
    traditional \"New...\" menu item.
    * The shortcut, if it exists, will invoke the same action without showing
    the component or its enclosing menus or dialogs. Example: \"Ctrl+N\" in a
    traditional \"New...\" menu item.

    Example: For a traditional \"New...\" menu item, the expected return value
    would be: \"N;Alt+F:N;Ctrl+N\" for the English locale and \"N;Alt+D:N;Strg+N\"
    for the German locale. If, hypothetically, this menu item lacked a mnemonic,
    it would be represented by \";;Ctrl+N\" and \";;Strg+N\" respectively.
    -}
    actionGetKeybinding ::
        (B.CallStack.HasCallStack, MonadIO m, IsAction a) =>
        a
        {- ^ /@action@/: a 'GI.GObject.Objects.Object.Object' instance that implements AtkActionIface -}
        -> Int32
        {- ^ /@i@/: the action index corresponding to the action to be performed -}
        -> m (Maybe T.Text)
        {- ^ __Returns:__ the keybinding which can be used to activate
    this action, or 'Nothing' if there is no keybinding for this action. -}
    actionGetKeybinding action i = liftIO $ do
        action' <- unsafeManagedPtrCastPtr action
        result <- atk_action_get_keybinding action' i
        maybeResult <- convertIfNonNull result $ \result' -> do
            result'' <- cstringToText result'
            return result''
        touchManagedPtr action
        return maybeResult

    #if ENABLE_OVERLOADING
    data ActionGetKeybindingMethodInfo
    instance (signature ~ (Int32 -> m (Maybe T.Text)), MonadIO m, IsAction a) => O.MethodInfo ActionGetKeybindingMethodInfo a signature where
        overloadedMethod _ = actionGetKeybinding

    #endif

    -- method Action::get_localized_name
    -- method type : OrdinaryMethod
    -- Args : [Arg {argCName = "action", argType = TInterface (Name {namespace = "Atk", name = "Action"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GObject instance that implements AtkActionIface", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing},Arg {argCName = "i", argType = TBasicType TInt, direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "the action index corresponding to the action to be performed", 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 "atk_action_get_localized_name" atk_action_get_localized_name ::
        Ptr Action ->                           -- action : TInterface (Name {namespace = "Atk", name = "Action"})
        Int32 ->                                -- i : TBasicType TInt
        IO CString

    {- |
    Returns the localized name of the specified action of the object.
    -}
    actionGetLocalizedName ::
        (B.CallStack.HasCallStack, MonadIO m, IsAction a) =>
        a
        {- ^ /@action@/: a 'GI.GObject.Objects.Object.Object' instance that implements AtkActionIface -}
        -> Int32
        {- ^ /@i@/: the action index corresponding to the action to be performed -}
        -> m (Maybe T.Text)
        {- ^ __Returns:__ a name string, or 'Nothing' if /@action@/ does not
    implement this interface. -}
    actionGetLocalizedName action i = liftIO $ do
        action' <- unsafeManagedPtrCastPtr action
        result <- atk_action_get_localized_name action' i
        maybeResult <- convertIfNonNull result $ \result' -> do
            result'' <- cstringToText result'
            return result''
        touchManagedPtr action
        return maybeResult

    #if ENABLE_OVERLOADING
    data ActionGetLocalizedNameMethodInfo
    instance (signature ~ (Int32 -> m (Maybe T.Text)), MonadIO m, IsAction a) => O.MethodInfo ActionGetLocalizedNameMethodInfo a signature where
        overloadedMethod _ = actionGetLocalizedName

    #endif

    -- method Action::get_n_actions
    -- method type : OrdinaryMethod
    -- Args : [Arg {argCName = "action", argType = TInterface (Name {namespace = "Atk", name = "Action"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GObject instance that implements AtkActionIface", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
    -- Lengths : []
    -- returnType : Just (TBasicType TInt)
    -- throws : False
    -- Skip return : False

    foreign import ccall "atk_action_get_n_actions" atk_action_get_n_actions ::
        Ptr Action ->                           -- action : TInterface (Name {namespace = "Atk", name = "Action"})
        IO Int32

    {- |
    Gets the number of accessible actions available on the object.
    If there are more than one, the first one is considered the
    \"default\" action of the object.
    -}
    actionGetNActions ::
        (B.CallStack.HasCallStack, MonadIO m, IsAction a) =>
        a
        {- ^ /@action@/: a 'GI.GObject.Objects.Object.Object' instance that implements AtkActionIface -}
        -> m Int32
        {- ^ __Returns:__ a the number of actions, or 0 if /@action@/ does not
    implement this interface. -}
    actionGetNActions action = liftIO $ do
        action' <- unsafeManagedPtrCastPtr action
        result <- atk_action_get_n_actions action'
        touchManagedPtr action
        return result

    #if ENABLE_OVERLOADING
    data ActionGetNActionsMethodInfo
    instance (signature ~ (m Int32), MonadIO m, IsAction a) => O.MethodInfo ActionGetNActionsMethodInfo a signature where
        overloadedMethod _ = actionGetNActions

    #endif

    -- method Action::get_name
    -- method type : OrdinaryMethod
    -- Args : [Arg {argCName = "action", argType = TInterface (Name {namespace = "Atk", name = "Action"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GObject instance that implements AtkActionIface", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing},Arg {argCName = "i", argType = TBasicType TInt, direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "the action index corresponding to the action to be performed", 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 "atk_action_get_name" atk_action_get_name ::
        Ptr Action ->                           -- action : TInterface (Name {namespace = "Atk", name = "Action"})
        Int32 ->                                -- i : TBasicType TInt
        IO CString

    {- |
    Returns a non-localized string naming the specified action of the
    object. This name is generally not descriptive of the end result
    of the action, but instead names the \'interaction type\' which the
    object supports. By convention, the above strings should be used to
    represent the actions which correspond to the common point-and-click
    interaction techniques of the same name: i.e.
    \"click\", \"press\", \"release\", \"drag\", \"drop\", \"popup\", etc.
    The \"popup\" action should be used to pop up a context menu for the
    object, if one exists.

    For technical reasons, some toolkits cannot guarantee that the
    reported action is actually \'bound\' to a nontrivial user event;
    i.e. the result of some actions via 'GI.Atk.Interfaces.Action.actionDoAction' may be
    NIL.
    -}
    actionGetName ::
        (B.CallStack.HasCallStack, MonadIO m, IsAction a) =>
        a
        {- ^ /@action@/: a 'GI.GObject.Objects.Object.Object' instance that implements AtkActionIface -}
        -> Int32
        {- ^ /@i@/: the action index corresponding to the action to be performed -}
        -> m (Maybe T.Text)
        {- ^ __Returns:__ a name string, or 'Nothing' if /@action@/ does not
    implement this interface. -}
    actionGetName action i = liftIO $ do
        action' <- unsafeManagedPtrCastPtr action
        result <- atk_action_get_name action' i
        maybeResult <- convertIfNonNull result $ \result' -> do
            result'' <- cstringToText result'
            return result''
        touchManagedPtr action
        return maybeResult

    #if ENABLE_OVERLOADING
    data ActionGetNameMethodInfo
    instance (signature ~ (Int32 -> m (Maybe T.Text)), MonadIO m, IsAction a) => O.MethodInfo ActionGetNameMethodInfo a signature where
        overloadedMethod _ = actionGetName

    #endif

    -- method Action::set_description
    -- method type : OrdinaryMethod
    -- Args : [Arg {argCName = "action", argType = TInterface (Name {namespace = "Atk", name = "Action"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GObject instance that implements AtkActionIface", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing},Arg {argCName = "i", argType = TBasicType TInt, direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "the action index corresponding to the action to be performed", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing},Arg {argCName = "desc", argType = TBasicType TUTF8, direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "the description to be assigned to this action", 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 "atk_action_set_description" atk_action_set_description ::
        Ptr Action ->                           -- action : TInterface (Name {namespace = "Atk", name = "Action"})
        Int32 ->                                -- i : TBasicType TInt
        CString ->                              -- desc : TBasicType TUTF8
        IO CInt

    {- |
    Sets a description of the specified action of the object.
    -}
    actionSetDescription ::
        (B.CallStack.HasCallStack, MonadIO m, IsAction a) =>
        a
        {- ^ /@action@/: a 'GI.GObject.Objects.Object.Object' instance that implements AtkActionIface -}
        -> Int32
        {- ^ /@i@/: the action index corresponding to the action to be performed -}
        -> T.Text
        {- ^ /@desc@/: the description to be assigned to this action -}
        -> m Bool
        {- ^ __Returns:__ a gboolean representing if the description was successfully set; -}
    actionSetDescription action i desc = liftIO $ do
        action' <- unsafeManagedPtrCastPtr action
        desc' <- textToCString desc
        result <- atk_action_set_description action' i desc'
        let result' = (/= 0) result
        touchManagedPtr action
        freeMem desc'
        return result'

    #if ENABLE_OVERLOADING
    data ActionSetDescriptionMethodInfo
    instance (signature ~ (Int32 -> T.Text -> m Bool), MonadIO m, IsAction a) => O.MethodInfo ActionSetDescriptionMethodInfo a signature where
        overloadedMethod _ = actionSetDescription

    #endif