Image.hs


{- |
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.Atk.Interfaces.Image.Image' should be implemented by 'GI.Atk.Objects.Object.Object' subtypes on behalf of
components which display image\/pixmap information onscreen, and
which provide information (other than just widget borders, etc.)
via that image content.  For instance, icons, buttons with icons,
toolbar elements, and image viewing panes typically should
implement 'GI.Atk.Interfaces.Image.Image'.

'GI.Atk.Interfaces.Image.Image' primarily provides two types of information: coordinate
information (useful for screen review mode of screenreaders, and
for use by onscreen magnifiers), and descriptive information.  The
descriptive information is provided for alternative, text-only
presentation of the most significant information present in the
image.
-}

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

module GI.Atk.Interfaces.Image
    ( 

-- * Exported types
    Image(..)                               ,
    noImage                                 ,
    IsImage                                 ,


 -- * Methods
-- ** getImageDescription #method:getImageDescription#

#if ENABLE_OVERLOADING
    ImageGetImageDescriptionMethodInfo      ,
#endif
    imageGetImageDescription                ,


-- ** getImageLocale #method:getImageLocale#

#if ENABLE_OVERLOADING
    ImageGetImageLocaleMethodInfo           ,
#endif
    imageGetImageLocale                     ,


-- ** getImagePosition #method:getImagePosition#

#if ENABLE_OVERLOADING
    ImageGetImagePositionMethodInfo         ,
#endif
    imageGetImagePosition                   ,


-- ** getImageSize #method:getImageSize#

#if ENABLE_OVERLOADING
    ImageGetImageSizeMethodInfo             ,
#endif
    imageGetImageSize                       ,


-- ** setImageDescription #method:setImageDescription#

#if ENABLE_OVERLOADING
    ImageSetImageDescriptionMethodInfo      ,
#endif
    imageSetImageDescription                ,




    ) 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 {-# SOURCE #-} qualified GI.Atk.Enums as Atk.Enums

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

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

#endif

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


#if ENABLE_OVERLOADING
type family ResolveImageMethod (t :: Symbol) (o :: *) :: * where
    ResolveImageMethod "getImageDescription" o = ImageGetImageDescriptionMethodInfo
    ResolveImageMethod "getImageLocale" o = ImageGetImageLocaleMethodInfo
    ResolveImageMethod "getImagePosition" o = ImageGetImagePositionMethodInfo
    ResolveImageMethod "getImageSize" o = ImageGetImageSizeMethodInfo
    ResolveImageMethod "setImageDescription" o = ImageSetImageDescriptionMethodInfo
    ResolveImageMethod l o = O.MethodResolutionFailed l o

instance (info ~ ResolveImageMethod t Image, O.MethodInfo info Image p) => OL.IsLabel t (Image -> 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 Image::get_image_description
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "image", argType = TInterface (Name {namespace = "Atk", name = "Image"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GObject instance that implements AtkImageIface", 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_image_get_image_description" atk_image_get_image_description :: 
    Ptr Image ->                            -- image : TInterface (Name {namespace = "Atk", name = "Image"})
    IO CString

{- |
Get a textual description of this image.
-}
imageGetImageDescription ::
    (B.CallStack.HasCallStack, MonadIO m, IsImage a) =>
    a
    {- ^ /@image@/: a 'GI.GObject.Objects.Object.Object' instance that implements AtkImageIface -}
    -> m T.Text
    {- ^ __Returns:__ a string representing the image description -}
imageGetImageDescription image = liftIO $ do
    image' <- unsafeManagedPtrCastPtr image
    result <- atk_image_get_image_description image'
    checkUnexpectedReturnNULL "imageGetImageDescription" result
    result' <- cstringToText result
    touchManagedPtr image
    return result'

#if ENABLE_OVERLOADING
data ImageGetImageDescriptionMethodInfo
instance (signature ~ (m T.Text), MonadIO m, IsImage a) => O.MethodInfo ImageGetImageDescriptionMethodInfo a signature where
    overloadedMethod _ = imageGetImageDescription

#endif

-- method Image::get_image_locale
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "image", argType = TInterface (Name {namespace = "Atk", name = "Image"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "An #AtkImage", 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_image_get_image_locale" atk_image_get_image_locale :: 
    Ptr Image ->                            -- image : TInterface (Name {namespace = "Atk", name = "Image"})
    IO CString

{- |
/No description available in the introspection data./

/Since: 1.12/
-}
imageGetImageLocale ::
    (B.CallStack.HasCallStack, MonadIO m, IsImage a) =>
    a
    {- ^ /@image@/: An 'GI.Atk.Interfaces.Image.Image' -}
    -> m (Maybe T.Text)
    {- ^ __Returns:__ a string corresponding to the POSIX
LC_MESSAGES locale used by the image description, or 'Nothing' if the
image does not specify a locale. -}
imageGetImageLocale image = liftIO $ do
    image' <- unsafeManagedPtrCastPtr image
    result <- atk_image_get_image_locale image'
    maybeResult <- convertIfNonNull result $ \result' -> do
        result'' <- cstringToText result'
        return result''
    touchManagedPtr image
    return maybeResult

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

#endif

-- method Image::get_image_position
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "image", argType = TInterface (Name {namespace = "Atk", name = "Image"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GObject instance that implements AtkImageIface", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing},Arg {argCName = "x", argType = TBasicType TInt, direction = DirectionOut, mayBeNull = False, argDoc = Documentation {rawDocText = Just "address of #gint to put x coordinate position; otherwise, -1 if value cannot be obtained.", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferEverything},Arg {argCName = "y", argType = TBasicType TInt, direction = DirectionOut, mayBeNull = False, argDoc = Documentation {rawDocText = Just "address of #gint to put y coordinate position; otherwise, -1 if value cannot be obtained.", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferEverything},Arg {argCName = "coord_type", argType = TInterface (Name {namespace = "Atk", name = "CoordType"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "specifies whether the coordinates are relative to the screen\nor to the components top level window", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
-- Lengths : []
-- returnType : Nothing
-- throws : False
-- Skip return : False

foreign import ccall "atk_image_get_image_position" atk_image_get_image_position :: 
    Ptr Image ->                            -- image : TInterface (Name {namespace = "Atk", name = "Image"})
    Ptr Int32 ->                            -- x : TBasicType TInt
    Ptr Int32 ->                            -- y : TBasicType TInt
    CUInt ->                                -- coord_type : TInterface (Name {namespace = "Atk", name = "CoordType"})
    IO ()

{- |
Gets the position of the image in the form of a point specifying the
images top-left corner.
-}
imageGetImagePosition ::
    (B.CallStack.HasCallStack, MonadIO m, IsImage a) =>
    a
    {- ^ /@image@/: a 'GI.GObject.Objects.Object.Object' instance that implements AtkImageIface -}
    -> Atk.Enums.CoordType
    {- ^ /@coordType@/: specifies whether the coordinates are relative to the screen
or to the components top level window -}
    -> m ((Int32, Int32))
imageGetImagePosition image coordType = liftIO $ do
    image' <- unsafeManagedPtrCastPtr image
    x <- allocMem :: IO (Ptr Int32)
    y <- allocMem :: IO (Ptr Int32)
    let coordType' = (fromIntegral . fromEnum) coordType
    atk_image_get_image_position image' x y coordType'
    x' <- peek x
    y' <- peek y
    touchManagedPtr image
    freeMem x
    freeMem y
    return (x', y')

#if ENABLE_OVERLOADING
data ImageGetImagePositionMethodInfo
instance (signature ~ (Atk.Enums.CoordType -> m ((Int32, Int32))), MonadIO m, IsImage a) => O.MethodInfo ImageGetImagePositionMethodInfo a signature where
    overloadedMethod _ = imageGetImagePosition

#endif

-- method Image::get_image_size
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "image", argType = TInterface (Name {namespace = "Atk", name = "Image"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GObject instance that implements AtkImageIface", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing},Arg {argCName = "width", argType = TBasicType TInt, direction = DirectionOut, mayBeNull = False, argDoc = Documentation {rawDocText = Just "filled with the image width, or -1 if the value cannot be obtained.", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferEverything},Arg {argCName = "height", argType = TBasicType TInt, direction = DirectionOut, mayBeNull = False, argDoc = Documentation {rawDocText = Just "filled with the image height, or -1 if the value cannot be obtained.", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferEverything}]
-- Lengths : []
-- returnType : Nothing
-- throws : False
-- Skip return : False

foreign import ccall "atk_image_get_image_size" atk_image_get_image_size :: 
    Ptr Image ->                            -- image : TInterface (Name {namespace = "Atk", name = "Image"})
    Ptr Int32 ->                            -- width : TBasicType TInt
    Ptr Int32 ->                            -- height : TBasicType TInt
    IO ()

{- |
Get the width and height in pixels for the specified image.
The values of /@width@/ and /@height@/ are returned as -1 if the
values cannot be obtained (for instance, if the object is not onscreen).
-}
imageGetImageSize ::
    (B.CallStack.HasCallStack, MonadIO m, IsImage a) =>
    a
    {- ^ /@image@/: a 'GI.GObject.Objects.Object.Object' instance that implements AtkImageIface -}
    -> m ((Int32, Int32))
imageGetImageSize image = liftIO $ do
    image' <- unsafeManagedPtrCastPtr image
    width <- allocMem :: IO (Ptr Int32)
    height <- allocMem :: IO (Ptr Int32)
    atk_image_get_image_size image' width height
    width' <- peek width
    height' <- peek height
    touchManagedPtr image
    freeMem width
    freeMem height
    return (width', height')

#if ENABLE_OVERLOADING
data ImageGetImageSizeMethodInfo
instance (signature ~ (m ((Int32, Int32))), MonadIO m, IsImage a) => O.MethodInfo ImageGetImageSizeMethodInfo a signature where
    overloadedMethod _ = imageGetImageSize

#endif

-- method Image::set_image_description
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "image", argType = TInterface (Name {namespace = "Atk", name = "Image"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GObject instance that implements AtkImageIface", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing},Arg {argCName = "description", argType = TBasicType TUTF8, direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a string description to set for @image", 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_image_set_image_description" atk_image_set_image_description :: 
    Ptr Image ->                            -- image : TInterface (Name {namespace = "Atk", name = "Image"})
    CString ->                              -- description : TBasicType TUTF8
    IO CInt

{- |
Sets the textual description for this image.
-}
imageSetImageDescription ::
    (B.CallStack.HasCallStack, MonadIO m, IsImage a) =>
    a
    {- ^ /@image@/: a 'GI.GObject.Objects.Object.Object' instance that implements AtkImageIface -}
    -> T.Text
    {- ^ /@description@/: a string description to set for /@image@/ -}
    -> m Bool
    {- ^ __Returns:__ boolean TRUE, or FALSE if operation could
not be completed. -}
imageSetImageDescription image description = liftIO $ do
    image' <- unsafeManagedPtrCastPtr image
    description' <- textToCString description
    result <- atk_image_set_image_description image' description'
    let result' = (/= 0) result
    touchManagedPtr image
    freeMem description'
    return result'

#if ENABLE_OVERLOADING
data ImageSetImageDescriptionMethodInfo
instance (signature ~ (T.Text -> m Bool), MonadIO m, IsImage a) => O.MethodInfo ImageSetImageDescriptionMethodInfo a signature where
    overloadedMethod _ = imageSetImageDescription

#endif