-- -*-haskell-*- -- Clutter Alpha -- -- Author : Matthew Arsenault -- -- Created: 22 Sep 2009 -- -- Copyright (C) 2009 Matthew Arsenault -- -- This library is free software; you can redistribute it and/or -- modify it under the terms of the GNU Lesser General Public -- License as published by the Free Software Foundation; either -- version 3 of the License, or (at your option) any later version. -- -- This library is distributed in the hope that it will be useful, -- but WITHOUT ANY WARRANTY; without even the implied warranty of -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -- Lesser General Public License for more details. -- {-# LANGUAGE ForeignFunctionInterface, TypeSynonymInstances #-} #include {# context lib="clutter" prefix="clutter" #} -- | A class for calculating an alpha value as a function of time. module Graphics.UI.Clutter.Alpha ( -- * Detail -- | 'Alpha' is a class for calculating an floating point value -- dependent only on the position of a 'Timeline'. -- -- A 'Alpha' binds a 'Timeline' to a progress function which -- translates the time T into an adimensional factor alpha. The factor -- can then be used to drive a 'Behaviour', which will translate the -- alpha value into something meaningful for a 'Actor'. -- -- You should provide a 'Timeline' and bind it to the 'Alpha' instance -- using 'alphaSetTimeline'. You should also set an \"animation -- mode\", either by using the ClutterAnimationMode values that -- Clutter itself provides or by registering custom functions using -- 'alphaRegisterFunc'. -- -- Instead of a 'AnimationMode' you may provide a function returning -- the alpha value depending on the progress of the timeline, using -- 'alphaSetFunc'. The alpha function will be executed each time a new -- frame in the 'Timeline' is reached. -- -- Since the alpha function is controlled by the timeline instance, -- you can pause, stop or resume the 'Alpha' from calling the alpha -- function by using the appropriate functions of the 'Timeline' -- object. -- -- 'Alpha' is used to \"drive\" a Behaviour instance, and it is -- internally used by the Animation API. -- -- * Figure 3. Easing modes provided by Clutter -- <> -- -- * Class Hierarchy -- | -- @ -- | 'GObject' -- | +----'Alpha' -- @ -- * Types Alpha, AlphaClass, AlphaFunc, -- * Constructors alphaNew, alphaNewFull, alphaNewWithFunc, -- * Methods alphaSetTimeline, alphaGetTimeline, alphaSetMode, alphaGetMode, alphaGetAlpha, alphaSetFunc, --alphaSetClosure, --alphaRegisterClosure, alphaRegisterFunc, -- * Attributes alphaTimeline, alphaMode, alphaAlpha ) where {# import Graphics.UI.Clutter.Types #} import C2HS import System.Glib.GObject import System.Glib.Attributes -- | Creates a new ClutterAlpha instance. You must set a function to -- compute the alpha value using 'alphaSetFunc' and bind a -- 'Timeline' object to the 'Alpha' instance using -- 'alphaSetTimeline'. -- -- You should use the newly created 'Alpha' instance inside a 'Behaviour' object. -- -- [@Returns@] the newly created empty 'Alpha' instance. -- -- * Since 0.2 -- {# fun unsafe alpha_new as ^ { } -> `Alpha' newAlpha* #} -- | Creates a new 'Alpha' instance and sets the timeline and animation mode. -- -- See also 'alphaSetTimeline' and 'alphaSetMode'. -- -- [@timeline@] 'Timeline' timeline -- -- [@mode@] animation mode -- -- [@Returns@] the newly created 'Αlpha' -- -- * Since 1.0 -- {# fun unsafe alpha_new_full as ^ { withTimeline* `Timeline', cFromEnum `AnimationMode' } -> `Alpha' newAlpha* #} -- | Creates a new ClutterAlpha instances and sets the timeline and the alpha function. -- -- This function will not register func as a global alpha function. -- -- See also alphaSetTimeline and 'alphaSetFunc'. -- -- * Since 1.0 -- alphaNewWithFunc :: Timeline -- ^ a 'Timeline' -> AlphaFunc -- ^ an 'AlphaFunc' -> IO Alpha -- ^ The newly created 'Alpha' alphaNewWithFunc tl af = withTimeline tl $ \tlptr -> do afptr <- newAlphaFunc af a <- {# call unsafe alpha_new_with_func #} tlptr afptr (castFunPtrToPtr afptr) destroyFunPtr newAlpha a -- | Binds alpha to timeline. -- -- [@alpha@] An 'Alpha' -- -- [@timeline@] A 'Timeline' -- -- * Since 0.2 -- {# fun unsafe alpha_set_timeline as ^ { withAlpha* `Alpha', withTimeline* `Timeline' } -> `()' #} -- | Gets the 'Timeline' bound to alpha. -- -- [@alpha@] an 'Alpha' -- -- [@timeline@] a 'Timeline' -- -- * Since 0.2 -- {# fun unsafe alpha_get_timeline as ^ { withAlpha* `Alpha' } -> `Timeline' newTimeline* #} --CHECKME/FIXME: AlphaMode can be something returned from register_func? --how does enum stuff handle this? -- | Sets the progress function of alpha using the symbolic value of -- mode, as taken by the 'AnimationMode' enumeration or using -- the value returned by 'alphaRegisterFunc'. -- -- [@alpha@] an 'Alpha' -- -- [@mode@] an 'AnimationMode' -- -- * Since 1.0 -- {# fun unsafe alpha_set_mode as ^ { withAlpha* `Alpha', cFromEnum `AnimationMode' } -> `()' #} -- | Retrieves the 'AnimationMode' used by an 'Αlpha'. -- -- * Since 0.2 -- {# fun unsafe alpha_get_mode as ^ { withAlpha* `Alpha' } -> `AnimationMode' cToEnum #} -- | Query the current alpha value -- -- * Since 0.2 -- {# fun unsafe alpha_get_alpha as ^ { withAlpha* `Alpha' } -> `Double' #} -- | Sets the 'AlphaFunc' function used to compute the alpha value at -- each frame of the 'Timeline' bound to alpha. -- This function will not register func as a global alpha function. -- -- * Since 1.0 -- alphaSetFunc :: Alpha -> AlphaFunc -> IO () alphaSetFunc alp af = withAlpha alp $ \alpPtr -> do afptr <- newAlphaFunc af {# call unsafe alpha_set_func #} alpPtr afptr (castFunPtrToPtr afptr) destroyFunPtr --TODO: some kind of ID Type for this. --TODO: What is CLUTTER_ANIMATION_LAST here? some kind of macro -- | Registers a global alpha function and returns its logical id to -- be used by 'alphaSetMode' or by 'Animation'. -- -- The logical id is always greater than CLUTTER_ANIMATION_LAST. -- -- * Since 1.0 -- alphaRegisterFunc :: AlphaFunc -> IO Word64 alphaRegisterFunc af = do afptr <- newAlphaFunc af ret <- {# call unsafe alpha_register_func #} afptr nullPtr return (cIntConv ret) --pretty sure don't care about gclosure --{# fun unsafe alpha_set_closure as ^ { withAlpha* `Alpha', `GClosure' } -> `()' #} --{# fun unsafe alpha_register_closure as ^ { `GClosure' } -> `GULong' #} -- | The alpha value as computed by the alpha function. The linear -- interval is 0.0 to 1.0, but the Alpha allows overshooting by one -- unit in each direction, so the valid interval is -1.0 to 2.0. -- Allowed values: [-1,2] -- -- Default value: 0 -- -- * Since 0.2 -- alphaAlpha :: ReadAttr Alpha Double alphaAlpha = readNamedAttr "alpha" alphaGetAlpha --CHECKME: The custom mode return -- | The progress function logical id - either a value from the -- 'AnimationMode' enumeration or a value returned by -- 'alphaRegisterFunc'. -- -- If CLUTTER_CUSTOM_MODE is used then the function set using -- 'alphaSetFunc' will be -- used. -- -- * Since 1.0 -- alphaMode :: Attr Alpha AnimationMode alphaMode = newNamedAttr "mode" alphaGetMode alphaSetMode -- | A 'Timeline' instance used to drive the alpha function -- -- * Since 0.2 -- alphaTimeline :: Attr Alpha Timeline alphaTimeline = newNamedAttr "timeline" alphaGetTimeline alphaSetTimeline