/*

* Copyright (c) 2002, 2006 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: A control that can be used to display an animation. It can be constructed from 

*   a skin, or from resource.

* 

*

*/

// AKNBITMAPANIMATION.H

//

#if !defined(__AKNBITMAPANIMATION_H__)

#define __AKNBITMAPANIMATION_H__

#if !defined(__COECNTRL_H__)

#include <coecntrl.h>

#endif

#include <bmpancli.h>

#include <AknControl.h>

#include <AknIconUtils.h>

/**

 * Client class for wserv animations based on bitmaps.

 * 

 * Enables a client to package animation data, and send it to the window server for display.

 * Requires the RAnimDll to be already instantiated. Also provides functionality for sending

 * specific messages to configure the animation.

 *

 *  @lib avkon

 *  @since S60 0.9

 */

class RAknBitmapAnim : public RBitmapAnim

    {

public:

    /**

     * Constructor. 

     *

     * @param aAnimDll must be already instantiated.

     */

    RAknBitmapAnim(RAnimDll& aAnimDll);

    /**

     * Starts the animation, and displays the last frame when finished.

     */

    void StartAndKeepLastFrameL();

    /**

     * Stops the animation.

     *

     * @return the error value returned from wserv

     */

    TInt Stop();

    };

// FORWARD DECLARATIONS

class TResourceReader;

class TAknsItemID;

/*

 * A control that can be used to display an animation.

 */

NONSHARABLE_CLASS(CAknBitmapAnimation) : public CAknControl

    {

public:

    /**

     * 2 phase construction. The pattern for constructing this class is non-standard. Call 

     * NewL, set the container window, then call the appropriate method to contruct from

     * either skin or resource.

     */

    IMPORT_C static CAknBitmapAnimation* NewL();

    /**

     * Destructor.

     */

    IMPORT_C virtual ~CAknBitmapAnimation();

public:

    /**

     * gives access to RBitmapAnimation.

     *

     * @return the RBitmapAnim

     */

    IMPORT_C RBitmapAnim& Animation();

    /**

     * gives access to CBitmapAnimClientData.

     *

     * @return the CBitmapAnimClientData

     */

    IMPORT_C CBitmapAnimClientData* BitmapAnimData() const;

    /**

     * Cancels the animation.

     *

     * @return the error code from stopping the animation

     */

    IMPORT_C TInt CancelAnimation();

    /**

     * Sets the frame index, initialising the animation if necessary.

     *

     * @param aIndex the frame index

     */

    IMPORT_C void SetFrameIndexL(TInt aIndex);

    /**

     * Sets the frame interval in milliSeconds, initialising the animation if necessary.

     *

     * @param aFrameIntervalInMilliSeconds the frame interval

     */

    IMPORT_C void SetFrameIntervalL(TInt aFrameIntervalInMilliSeconds);

    /**

     * Starts the animation, initialising the animation if necessary, and starting the timer

     * if necessary.

     */

    IMPORT_C void StartAnimationL();

    /**

    * Sets the scale mode for the animation frames that is used when the

    * animation frames are scaled to the size of the control.

    * Default scale mode is EAspectRatioPreserved.

    *

    * @since 3.1

    * @param aMode scale mode

    */

    IMPORT_C void SetScaleModeForAnimationFrames(TScaleMode aMode);

    /**

    * Sets the scale mode for the animation background frame that is used when the

    * animation background frame is scaled to the size of the control.

    * Default scale mode is EAspectRatioPreserved.

    *

    * @since 3.1

    * @param aMode scale mode

    */

    IMPORT_C void SetScaleModeForAnimationBackgroundFrame(TScaleMode aMode);

    /**

    * Excludes the animation frames from the icon cache.    

    * Note that this method should be called before setting the size of the control

    * to be in effect. If the animation frames are created outside of the scope of this 

    * class method AknIconUtils::ExcludeFromCache should be called for animation frames

    * to get the same effect.

    * 

    * By default scalable animation frames are being put to icon cache after they are

    * no longer used. 

    * This makes it possible to retrieve recently used animation frames fast

    * without the need to render them again.

    * Excluding infrequently used animation frames from icon cache could 

    * improve performance and memory usage of the system.

    * 

    * @since 3.1    

    */

    IMPORT_C void ExcludeAnimationFramesFromCache();

public: 

    /**

     * Records whether the animation has started. If there is a timer, it is cancelled.

     *

     * @param aHasStarted if ETrue, started flag is recorded; if EFalse, the existing flag value is not changed.

     * @return returns KErrNone in the case of no error occurring.

     */

    TInt AnimationHasStarted(TBool aHasStarted);

public:

    /**

    * Construct the animation from skin.

    *

    * Usually this method should be called before ConstructFromResourceL,

    * and if EFalse is returned the caller should try to construct the

    * same animation with ConstructFromResourceL. The ownership of the

    * constructed animation and its frames is vested in this class.

    * Furthermore, the animation is not automatically updated during

    * a skin change.

    *

    * @since 2.0

    * @param aItemID Item ID of the animation.

    * @return ETrue if the animation was found and succesfully constructed.

    *   EFalse if the animation (or at least one of its frames) was not

    *   found.

    */

    IMPORT_C TBool ConstructFromSkinL( const TAknsItemID& aItemID );

public: // from CCoeControl

    /**

     * Construct animation from resource. This can be called after a call to NewL. Can

     * also be called after a failed attempt to call ConstructFromSkinL.

     * 

     * @param aResourceReader the resource reader

     */

    IMPORT_C virtual void ConstructFromResourceL(TResourceReader& aResourceReader);

    /**

     * Minimum size.

     */

    IMPORT_C virtual TSize MinimumSize();

public:

    /**

     * Starts the animation, initialising the animation if necessary, and starting the timer

     * if necessary.

     */

    IMPORT_C void StartAnimationL( TBool aKeepLastFrame );

private: // from CCoeControl

    /*

     * Size changed.

     */

    virtual void SizeChanged();

    /*

     * Position Changed

     */

    virtual void PositionChanged();

    /*

     * Draw

     *

     * @parm aRect the drawing rect

     */

    virtual void Draw(const TRect& aRect) const;

    /*

     * Focus Changed

     */

    virtual void FocusChanged(TDrawNow aDrawNow);

private:

    /* 

     * Constructor

     */

    CAknBitmapAnimation();

    /*

     * Second phase construction

     */

    void ConstructL();

    /*

     * Complete animation initialisation. Sets the animation window, 

     * the position, and the animation data. Records the fact that 

     * initialisation has occurred.

     */

    void CompleteAnimationInitialisationL();

    /*

     * Checks the animation initialisation completion flag

     *

     * @return the initialisation flag

     */

    TBool IsInitialisationCompleted();

    /*

     * Create frame data, by extracting the interval and position from

     * the resource, and the frame data from the animation itself.

     *

     * @param aFramesReader the resource reader

     * @param aFileName the animation file

     * @param aVersion version of BMPANIM_DATA

     * @return the frame data

     */

	CBitmapFrameData* CreateFrameDataFromResourceL(TResourceReader& aFramesReader, const TDesC& aFileName, const TInt8 aVersion);

    /*

     * Set animation window

     */

    void SetAnimationWindowL();

private: // timer

    /*

     * Callback for the animation timer

     *

     * @param aPtr pointer to the owning class

     * @return any error value from the timer

     */

    static TInt AnimationStartedCallback(TAny* aPtr);

private:

    CBitmapAnimClientData* iBitmapAnimData;

    RAnimDll iAnimDll;

    RAknBitmapAnim iAnimation;

    TInt iFlags;

    CPeriodic* iTimer;

    TScaleMode iScaleModeFrames;

    TScaleMode iScaleModeBackgroundFrame;

    TBool iGainedFocus;

    };

#endif