1 /*

     2 * Copyright (c) 2005 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  ?Description

    15 *

    16 */

    17 

    18 #ifndef AKNSEFFECTANIM_H

    19 #define AKNSEFFECTANIM_H

    20 

    21 // INCLUDE FILES

    22 #include <gdi.h> // For TDisplayMode

    23 

    24 // CONSTANTS

    25 enum TAknsAnimState

    26     {

    27     EAknsAnimStateStopped       = 0,

    28     EAknsAnimStateRunning       = 1,

    29     EAknsAnimStatePaused        = 2,

    30     EAknsAnimStateFinished      = 3

    31     };

    32 

    33 // In milliseconds

    34 const TInt KAknsEffectAnimDefaultIdleInterval = 333;

    35 

    36 // FORWARD DECLARATIONS

    37 class CFbsBitGc;

    38 class CWindowGc;

    39 class CBitmapContext;

    40 class CFbsBitmap;

    41 class TAknsItemID;

    42 

    43 class CAknsAlAnimatorBmp;

    44 

    45 // CLASS DECLARATION

    46 /**

    47 * Animation user must implement this interface to receive notification when a

    48 * new animation frame is ready to be drawn.

    49 *

    50 * @since 3.0

    51 */

    52 class MAknsEffectAnimObserver

    53     {

    54     public:

    55         /**

    56         * Animation frame is ready to be drawn.

    57         *

    58         * @param aError  KErrNone if frame has been succesfully created and is

    59         *   available for drawing. If !KErrNone the animation has internally

    60         *   failed.

    61         * @param aAnimId  Reserved for future use

    62         */

    63         virtual void AnimFrameReady( TInt aError, TInt aAnimId ) = 0;

    64     };

    65 

    66 // CLASS DECLARATION

    67 /**

    68 * Animation controller for using effect animations.

    69 *

    70 * @since 3.0

    71 */

    72 class CAknsEffectAnim: public CBase

    73     {

    74 public: // Constructors

    75     /**

    76     * Creates a new animation controller. Full construction requires a call to

    77     * ConstructFromSkinL. Leaves with KErrNotSupported if highlight animations

    78     * have been disabled, see AknsUtils::SetAvkonHighlightAnimationEnabledL.

    79     *

    80     * @param aObserver Must be non-NULL

    81     */

    82     IMPORT_C static CAknsEffectAnim* NewL( MAknsEffectAnimObserver* aObserver );

    83     IMPORT_C virtual ~CAknsEffectAnim();

    84 

    85     /**

    86     * Constructs animation from skin item. Leaves if animation construction

    87     * fails.

    88     * @param aItemID Animation skin item ID

    89     * @return ETrue if the animation was found from the skin, EFalse if it was

    90     *         not found.

    91     */

    92     IMPORT_C TBool ConstructFromSkinL( const TAknsItemID& aItemID );

    93 

    94 private:

    95     CAknsEffectAnim();

    96     void ConstructL( MAknsEffectAnimObserver* aObserver );

    97 

    98 public: // Interface for using the animation

    99     /**

   100     * Starts the animation from the very beginning.

   101     *

   102     * @return Error code, KErrNone if operation was succesfull. If returned

   103     *   error code != KErrNone the operation has failed (OOM, internal

   104     *   misconfiguration etc). Recommended action is to delete the animation

   105     *   and fall back to normal rendering. Returns KErrNotReady if input layers

   106     *   have not been configured.

   107     */

   108     IMPORT_C TInt Start();

   109 

   110     /**

   111     * Stops the animation. Input layers are released, output layer is kept.

   112     *

   113     * @return Error code, KErrNone if operation was succesfull. If returned

   114     *   error code != KErrNone the operation has failed (OOM, internal

   115     *   misconfiguration etc). Recommended action is to delete the animation

   116     *   and fall back to normal rendering.

   117     */

   118     IMPORT_C TInt Stop();

   119 

   120     /**

   121     * Pauses the animation. Input layers are not released.

   122     *

   123     * @return Error code, KErrNone if operation was succesfull. If returned

   124     *   error code != KErrNone the operation has failed (OOM, internal

   125     *   misconfiguration etc). Recommended action is to delete the animation

   126     *   and fall back to normal rendering.

   127     */

   128     IMPORT_C TInt Pause();

   129 

   130     /**

   131     * Continues the animation from the state where it was paused.

   132     *

   133     * @return Error code, KErrNone if operation was succesfull. If returned

   134     *   error code != KErrNone the operation has failed (OOM, internal

   135     *   misconfiguration etc). Recommended action is to delete the animation

   136     *   and fall back to normal rendering.

   137     */

   138     IMPORT_C TInt Continue();

   139 

   140     /**

   141     * @return The current state of animation. Possible state values are

   142     * described in TAknsAnimState.

   143     */

   144     IMPORT_C TInt State();

   145 

   146     /**

   147     * Renders the current animation frame with the provided graphics context.

   148     * The animation may have an output mask. The output mask will be used in

   149     * the rendering if it exists. Otherwise nonmasked renderig will be used.

   150     * Rendering will use BitBlt. For more specialized rendering use the exposed

   151     * output bitmaps.

   152     *

   153     * @param aGc The graphics context used for rendering.

   154     * @param aGcRect The frame is blit to this rectangle on the graphics

   155     *   context target.

   156     * @return ETrue if rendering was successfull, EFalse otherwise.

   157     */

   158     IMPORT_C TBool Render( CFbsBitGc& aGc, const TRect& aGcRect ) const;

   159 

   160     /**

   161     * Similar to the other Render, this version is just for the window graphics

   162     * context.

   163     */

   164     IMPORT_C TBool Render( CWindowGc& aGc, const TRect& aGcRect ) const;

   165 

   166     /**

   167     * Similar to the other renders, this version is just for the bitmap

   168     * graphics context.

   169     *

   170     * @since 3.1

   171     */

   172     IMPORT_C TBool Render( CBitmapContext& aGc, const TRect& aGcRect ) const;

   173 

   174     /**

   175     * @return The current animation output frame. Can be NULL if e.g. called

   176     *         before configuring animation layers.

   177     */

   178     IMPORT_C const CFbsBitmap* OutputRgb() const;

   179 

   180     /**

   181     * @return The current animation output frame mask. Output mask is optional

   182     *         --> can be NULL at any given time.

   183     */

   184     IMPORT_C const CFbsBitmap* OutputAlpha() const;

   185 

   186     /**

   187     * @return The minimum allowed size of animation.

   188     */

   189     IMPORT_C TSize MinimumSize() const;

   190 

   191     /**

   192     * @return The current size of animation.

   193     */

   194     IMPORT_C TSize Size() const;

   195 

   196     /**

   197     * @return ETrue if input layer is required for correct rendering but it is

   198     *         not currently present.

   199     */

   200     IMPORT_C TBool NeedsInputLayer() const;

   201 

   202     /**

   203     * Starts configuring input layers, should be called prior to Begin() and

   204     * Continue() to restore input layers to animation. Configure sequence is as

   205     * follows:

   206     * 1. Call BeginConfigLayers to start configuration

   207     * 2. Use InputRgbGc and InputAlphaGc to prepare input layers

   208     * 3. Call EndConfigLayers to end configuration

   209     *

   210     * @param aNewSize  The layer size, must be larger than or equal to minimum

   211     *   size. Providing size smaller than minimum size will lead to leave with

   212     *   KErrArgument.

   213     * @param aAboutToStart If animation is about to be started or continued

   214     *   after layer configuration this should be set to ETrue (to keep input

   215     *   layers). Otherwise EFalse should be used.

   216     */

   217     IMPORT_C void BeginConfigInputLayersL( const TSize& aNewSize,

   218                                            TBool aAboutToStart );

   219 

   220     /**

   221     * Graphics context for drawing the input layer RGB. Can be NULL, in this

   222     * case animation is not expecting input layer.

   223     */

   224     IMPORT_C CFbsBitGc* InputRgbGc() const;

   225 

   226     /**

   227     * Graphics context for drawing the input layer alpha. Can be NULL, in this

   228     * case animation is not expecting input layer alpha.

   229     */

   230     IMPORT_C CFbsBitGc* InputAlphaGc() const;

   231 

   232     /**

   233     * Ends layer configuration.

   234     */

   235     IMPORT_C void EndConfigInputLayersL();

   236 

   237     /**

   238     * Renders the output layer once without notifying the animation observer.

   239     * Doesn't set animator error state if fails.

   240     * @return The status of rendering, if KErrNone rendering was ok, if

   241     *         !KErrNone either rendering failed or animator is already in

   242     *         error state.

   243     */

   244     IMPORT_C TInt UpdateOutput();

   245 

   246     /**

   247     * When animation is idling it won't update the actual animation. Observer

   248     * AnimFrameReady will be called when idle timer timeouts. Animation

   249     * observer should check there whether or not animation is idling and ignore

   250     * redraw calls caused by idling.

   251     *

   252     * Only animations in state EAknsAnimStateRunning can be set idling. Setting

   253     * idling causes the animation to go in paused state. Trying to idle

   254     * animation in any other state will be silently ignored. Also, idling is

   255     * interrupted when animation is started, stoppped, paused or continued.

   256     * Idling is not interrupted if the animation is resized when being idled.

   257     * Idling can be reset, e.g. calling SetIdling multiple times is ok.

   258     *

   259     * @param aInterval Idling interval in milliseconds. Using the default value

   260     *                  KAknsEffectAnimDefaultIdleInterval is recommended.

   261     */

   262     IMPORT_C void SetIdling( TInt aIntervalMs );

   263 

   264     /**

   265     * @return ETrue if animation is idling, EFalse otherwise.

   266     */

   267     IMPORT_C TBool IsIdling() const;

   268 

   269 private:

   270     CAknsAlAnimatorBmp* iAnim;

   271     TInt iAboutToStart;

   272     };

   273 

   274 #endif // AKNSEFFECTANIM_H