/*
* Copyright (c) 2005 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:  ?Description
*
*/

#ifndef AKNSEFFECTANIM_H
#define AKNSEFFECTANIM_H

// INCLUDE FILES
#include <gdi.h> // For TDisplayMode

// CONSTANTS
enum TAknsAnimState
    {
    EAknsAnimStateStopped       = 0,
    EAknsAnimStateRunning       = 1,
    EAknsAnimStatePaused        = 2,
    EAknsAnimStateFinished      = 3
    };

// In milliseconds
const TInt KAknsEffectAnimDefaultIdleInterval = 333;

// FORWARD DECLARATIONS
class CFbsBitGc;
class CWindowGc;
class CBitmapContext;
class CFbsBitmap;
class TAknsItemID;

class CAknsAlAnimatorBmp;

// CLASS DECLARATION
/**
* Animation user must implement this interface to receive notification when a
* new animation frame is ready to be drawn.
*
* @since 3.0
*/
class MAknsEffectAnimObserver
    {
    public:
        /**
        * Animation frame is ready to be drawn.
        *
        * @param aError  KErrNone if frame has been succesfully created and is
        *   available for drawing. If !KErrNone the animation has internally
        *   failed.
        * @param aAnimId  Reserved for future use
        */
        virtual void AnimFrameReady( TInt aError, TInt aAnimId ) = 0;
    };

// CLASS DECLARATION
/**
* Animation controller for using effect animations.
*
* @since 3.0
*/
class CAknsEffectAnim: public CBase
    {
public: // Constructors
    /**
    * Creates a new animation controller. Full construction requires a call to
    * ConstructFromSkinL. Leaves with KErrNotSupported if highlight animations
    * have been disabled, see AknsUtils::SetAvkonHighlightAnimationEnabledL.
    *
    * @param aObserver Must be non-NULL
    */
    IMPORT_C static CAknsEffectAnim* NewL( MAknsEffectAnimObserver* aObserver );
    IMPORT_C virtual ~CAknsEffectAnim();

    /**
    * Constructs animation from skin item. Leaves if animation construction
    * fails.
    * @param aItemID Animation skin item ID
    * @return ETrue if the animation was found from the skin, EFalse if it was
    *         not found.
    */
    IMPORT_C TBool ConstructFromSkinL( const TAknsItemID& aItemID );

private:
    CAknsEffectAnim();
    void ConstructL( MAknsEffectAnimObserver* aObserver );

public: // Interface for using the animation
    /**
    * Starts the animation from the very beginning.
    *
    * @return Error code, KErrNone if operation was succesfull. If returned
    *   error code != KErrNone the operation has failed (OOM, internal
    *   misconfiguration etc). Recommended action is to delete the animation
    *   and fall back to normal rendering. Returns KErrNotReady if input layers
    *   have not been configured.
    */
    IMPORT_C TInt Start();

    /**
    * Stops the animation. Input layers are released, output layer is kept.
    *
    * @return Error code, KErrNone if operation was succesfull. If returned
    *   error code != KErrNone the operation has failed (OOM, internal
    *   misconfiguration etc). Recommended action is to delete the animation
    *   and fall back to normal rendering.
    */
    IMPORT_C TInt Stop();

    /**
    * Pauses the animation. Input layers are not released.
    *
    * @return Error code, KErrNone if operation was succesfull. If returned
    *   error code != KErrNone the operation has failed (OOM, internal
    *   misconfiguration etc). Recommended action is to delete the animation
    *   and fall back to normal rendering.
    */
    IMPORT_C TInt Pause();

    /**
    * Continues the animation from the state where it was paused.
    *
    * @return Error code, KErrNone if operation was succesfull. If returned
    *   error code != KErrNone the operation has failed (OOM, internal
    *   misconfiguration etc). Recommended action is to delete the animation
    *   and fall back to normal rendering.
    */
    IMPORT_C TInt Continue();

    /**
    * @return The current state of animation. Possible state values are
    * described in TAknsAnimState.
    */
    IMPORT_C TInt State();

    /**
    * Renders the current animation frame with the provided graphics context.
    * The animation may have an output mask. The output mask will be used in
    * the rendering if it exists. Otherwise nonmasked renderig will be used.
    * Rendering will use BitBlt. For more specialized rendering use the exposed
    * output bitmaps.
    *
    * @param aGc The graphics context used for rendering.
    * @param aGcRect The frame is blit to this rectangle on the graphics
    *   context target.
    * @return ETrue if rendering was successfull, EFalse otherwise.
    */
    IMPORT_C TBool Render( CFbsBitGc& aGc, const TRect& aGcRect ) const;

    /**
    * Similar to the other Render, this version is just for the window graphics
    * context.
    */
    IMPORT_C TBool Render( CWindowGc& aGc, const TRect& aGcRect ) const;

    /**
    * Similar to the other renders, this version is just for the bitmap
    * graphics context.
    *
    * @since 3.1
    */
    IMPORT_C TBool Render( CBitmapContext& aGc, const TRect& aGcRect ) const;

    /**
    * @return The current animation output frame. Can be NULL if e.g. called
    *         before configuring animation layers.
    */
    IMPORT_C const CFbsBitmap* OutputRgb() const;

    /**
    * @return The current animation output frame mask. Output mask is optional
    *         --> can be NULL at any given time.
    */
    IMPORT_C const CFbsBitmap* OutputAlpha() const;

    /**
    * @return The minimum allowed size of animation.
    */
    IMPORT_C TSize MinimumSize() const;

    /**
    * @return The current size of animation.
    */
    IMPORT_C TSize Size() const;

    /**
    * @return ETrue if input layer is required for correct rendering but it is
    *         not currently present.
    */
    IMPORT_C TBool NeedsInputLayer() const;

    /**
    * Starts configuring input layers, should be called prior to Begin() and
    * Continue() to restore input layers to animation. Configure sequence is as
    * follows:
    * 1. Call BeginConfigLayers to start configuration
    * 2. Use InputRgbGc and InputAlphaGc to prepare input layers
    * 3. Call EndConfigLayers to end configuration
    *
    * @param aNewSize  The layer size, must be larger than or equal to minimum
    *   size. Providing size smaller than minimum size will lead to leave with
    *   KErrArgument.
    * @param aAboutToStart If animation is about to be started or continued
    *   after layer configuration this should be set to ETrue (to keep input
    *   layers). Otherwise EFalse should be used.
    */
    IMPORT_C void BeginConfigInputLayersL( const TSize& aNewSize,
                                           TBool aAboutToStart );

    /**
    * Graphics context for drawing the input layer RGB. Can be NULL, in this
    * case animation is not expecting input layer.
    */
    IMPORT_C CFbsBitGc* InputRgbGc() const;

    /**
    * Graphics context for drawing the input layer alpha. Can be NULL, in this
    * case animation is not expecting input layer alpha.
    */
    IMPORT_C CFbsBitGc* InputAlphaGc() const;

    /**
    * Ends layer configuration.
    */
    IMPORT_C void EndConfigInputLayersL();

    /**
    * Renders the output layer once without notifying the animation observer.
    * Doesn't set animator error state if fails.
    * @return The status of rendering, if KErrNone rendering was ok, if
    *         !KErrNone either rendering failed or animator is already in
    *         error state.
    */
    IMPORT_C TInt UpdateOutput();

    /**
    * When animation is idling it won't update the actual animation. Observer
    * AnimFrameReady will be called when idle timer timeouts. Animation
    * observer should check there whether or not animation is idling and ignore
    * redraw calls caused by idling.
    *
    * Only animations in state EAknsAnimStateRunning can be set idling. Setting
    * idling causes the animation to go in paused state. Trying to idle
    * animation in any other state will be silently ignored. Also, idling is
    * interrupted when animation is started, stoppped, paused or continued.
    * Idling is not interrupted if the animation is resized when being idled.
    * Idling can be reset, e.g. calling SetIdling multiple times is ok.
    *
    * @param aInterval Idling interval in milliseconds. Using the default value
    *                  KAknsEffectAnimDefaultIdleInterval is recommended.
    */
    IMPORT_C void SetIdling( TInt aIntervalMs );

    /**
    * @return ETrue if animation is idling, EFalse otherwise.
    */
    IMPORT_C TBool IsIdling() const;

private:
    CAknsAlAnimatorBmp* iAnim;
    TInt iAboutToStart;
    };

#endif // AKNSEFFECTANIM_H