williamr@2: /*
williamr@2: * Copyright (c) 2002, 2006 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@4: * under the terms of "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description: A control that can be used to display an animation. It can be constructed from 
williamr@2: *   a skin, or from resource.
williamr@2: * 
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: // AKNBITMAPANIMATION.H
williamr@2: //
williamr@2: 
williamr@2: #if !defined(__AKNBITMAPANIMATION_H__)
williamr@2: #define __AKNBITMAPANIMATION_H__
williamr@2: 
williamr@2: #if !defined(__COECNTRL_H__)
williamr@2: #include <coecntrl.h>
williamr@2: #endif
williamr@2: 
williamr@2: #include <bmpancli.h>
williamr@2: #include <AknControl.h>
williamr@2: #include <AknIconUtils.h>
williamr@2: 
williamr@2: /**
williamr@2:  * Client class for wserv animations based on bitmaps.
williamr@2:  * 
williamr@2:  * Enables a client to package animation data, and send it to the window server for display.
williamr@2:  * Requires the RAnimDll to be already instantiated. Also provides functionality for sending
williamr@2:  * specific messages to configure the animation.
williamr@2:  *
williamr@2:  *  @lib avkon
williamr@2:  *  @since S60 0.9
williamr@2:  */
williamr@2: class RAknBitmapAnim : public RBitmapAnim
williamr@2:     {
williamr@2: public:
williamr@2:     /**
williamr@2:      * Constructor. 
williamr@2:      *
williamr@2:      * @param aAnimDll must be already instantiated.
williamr@2:      */
williamr@2:     RAknBitmapAnim(RAnimDll& aAnimDll);
williamr@2: 
williamr@2:     /**
williamr@2:      * Starts the animation, and displays the last frame when finished.
williamr@2:      */
williamr@2:     void StartAndKeepLastFrameL();
williamr@2: 
williamr@2:     /**
williamr@2:      * Stops the animation.
williamr@2:      *
williamr@2:      * @return the error value returned from wserv
williamr@2:      */
williamr@2:     TInt Stop();
williamr@2:     };
williamr@2: 
williamr@2: // FORWARD DECLARATIONS
williamr@2: class TResourceReader;
williamr@2: class TAknsItemID;
williamr@2: 
williamr@2: /*
williamr@2:  * A control that can be used to display an animation.
williamr@2:  */
williamr@2: NONSHARABLE_CLASS(CAknBitmapAnimation) : public CAknControl
williamr@2:     {
williamr@2: public:
williamr@2:     /**
williamr@2:      * 2 phase construction. The pattern for constructing this class is non-standard. Call 
williamr@2:      * NewL, set the container window, then call the appropriate method to contruct from
williamr@2:      * either skin or resource.
williamr@2:      */
williamr@2:     IMPORT_C static CAknBitmapAnimation* NewL();
williamr@2: 
williamr@2:     /**
williamr@2:      * Destructor.
williamr@2:      */
williamr@2:     IMPORT_C virtual ~CAknBitmapAnimation();
williamr@2: 
williamr@2: public:
williamr@2:     /**
williamr@2:      * gives access to RBitmapAnimation.
williamr@2:      *
williamr@2:      * @return the RBitmapAnim
williamr@2:      */
williamr@2:     IMPORT_C RBitmapAnim& Animation();
williamr@2: 
williamr@2:     /**
williamr@2:      * gives access to CBitmapAnimClientData.
williamr@2:      *
williamr@2:      * @return the CBitmapAnimClientData
williamr@2:      */
williamr@2:     IMPORT_C CBitmapAnimClientData* BitmapAnimData() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Cancels the animation.
williamr@2:      *
williamr@2:      * @return the error code from stopping the animation
williamr@2:      */
williamr@2:     IMPORT_C TInt CancelAnimation();
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets the frame index, initialising the animation if necessary.
williamr@2:      *
williamr@2:      * @param aIndex the frame index
williamr@2:      */
williamr@2:     IMPORT_C void SetFrameIndexL(TInt aIndex);
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets the frame interval in milliSeconds, initialising the animation if necessary.
williamr@2:      *
williamr@2:      * @param aFrameIntervalInMilliSeconds the frame interval
williamr@2:      */
williamr@2:     IMPORT_C void SetFrameIntervalL(TInt aFrameIntervalInMilliSeconds);
williamr@2: 
williamr@2:     /**
williamr@2:      * Starts the animation, initialising the animation if necessary, and starting the timer
williamr@2:      * if necessary.
williamr@2:      */
williamr@2:     IMPORT_C void StartAnimationL();
williamr@2: 
williamr@2:     /**
williamr@2:     * Sets the scale mode for the animation frames that is used when the
williamr@2:     * animation frames are scaled to the size of the control.
williamr@2:     * Default scale mode is EAspectRatioPreserved.
williamr@2:     *
williamr@2:     * @since 3.1
williamr@2:     * @param aMode scale mode
williamr@2:     */
williamr@2:     IMPORT_C void SetScaleModeForAnimationFrames(TScaleMode aMode);
williamr@2: 
williamr@2:     /**
williamr@2:     * Sets the scale mode for the animation background frame that is used when the
williamr@2:     * animation background frame is scaled to the size of the control.
williamr@2:     * Default scale mode is EAspectRatioPreserved.
williamr@2:     *
williamr@2:     * @since 3.1
williamr@2:     * @param aMode scale mode
williamr@2:     */
williamr@2:     IMPORT_C void SetScaleModeForAnimationBackgroundFrame(TScaleMode aMode);
williamr@2: 
williamr@2:     /**
williamr@2:     * Excludes the animation frames from the icon cache.    
williamr@2:     * Note that this method should be called before setting the size of the control
williamr@2:     * to be in effect. If the animation frames are created outside of the scope of this 
williamr@2:     * class method AknIconUtils::ExcludeFromCache should be called for animation frames
williamr@2:     * to get the same effect.
williamr@2:     * 
williamr@2:     * By default scalable animation frames are being put to icon cache after they are
williamr@2:     * no longer used. 
williamr@2:     * This makes it possible to retrieve recently used animation frames fast
williamr@2:     * without the need to render them again.
williamr@2:     * Excluding infrequently used animation frames from icon cache could 
williamr@2:     * improve performance and memory usage of the system.
williamr@2:     * 
williamr@2:     * @since 3.1    
williamr@2:     */
williamr@2:     IMPORT_C void ExcludeAnimationFramesFromCache();
williamr@2:     
williamr@2: public: 
williamr@2:     /**
williamr@2:      * Records whether the animation has started. If there is a timer, it is cancelled.
williamr@2:      *
williamr@2:      * @param aHasStarted if ETrue, started flag is recorded; if EFalse, the existing flag value is not changed.
williamr@2:      * @return returns KErrNone in the case of no error occurring.
williamr@2:      */
williamr@2:     TInt AnimationHasStarted(TBool aHasStarted);
williamr@2: 
williamr@2: public:
williamr@2:     /**
williamr@2:     * Construct the animation from skin.
williamr@2:     *
williamr@2:     * Usually this method should be called before ConstructFromResourceL,
williamr@2:     * and if EFalse is returned the caller should try to construct the
williamr@2:     * same animation with ConstructFromResourceL. The ownership of the
williamr@2:     * constructed animation and its frames is vested in this class.
williamr@2:     * Furthermore, the animation is not automatically updated during
williamr@2:     * a skin change.
williamr@2:     *
williamr@2:     * @since 2.0
williamr@2:     * @param aItemID Item ID of the animation.
williamr@2:     * @return ETrue if the animation was found and succesfully constructed.
williamr@2:     *   EFalse if the animation (or at least one of its frames) was not
williamr@2:     *   found.
williamr@2:     */
williamr@2:     IMPORT_C TBool ConstructFromSkinL( const TAknsItemID& aItemID );
williamr@2: 
williamr@2: public: // from CCoeControl
williamr@2:     /**
williamr@2:      * Construct animation from resource. This can be called after a call to NewL. Can
williamr@2:      * also be called after a failed attempt to call ConstructFromSkinL.
williamr@2:      * 
williamr@2:      * @param aResourceReader the resource reader
williamr@2:      */
williamr@2:     IMPORT_C virtual void ConstructFromResourceL(TResourceReader& aResourceReader);
williamr@2: 
williamr@2:     /**
williamr@2:      * Minimum size.
williamr@2:      */
williamr@2:     IMPORT_C virtual TSize MinimumSize();
williamr@4:     
williamr@4: public:
williamr@4:     /**
williamr@4:      * Starts the animation, initialising the animation if necessary, and starting the timer
williamr@4:      * if necessary.
williamr@4:      */
williamr@4:     IMPORT_C void StartAnimationL( TBool aKeepLastFrame );
williamr@2: 
williamr@2: private: // from CCoeControl
williamr@2:     
williamr@2:     /*
williamr@2:      * Size changed.
williamr@2:      */
williamr@2:     virtual void SizeChanged();
williamr@2:     
williamr@2:     /*
williamr@2:      * Position Changed
williamr@2:      */
williamr@2:     virtual void PositionChanged();
williamr@2:     
williamr@2:     /*
williamr@2:      * Draw
williamr@2:      *
williamr@2:      * @parm aRect the drawing rect
williamr@2:      */
williamr@2:     virtual void Draw(const TRect& aRect) const;
williamr@2: 
williamr@2:     /*
williamr@2:      * Focus Changed
williamr@2:      */
williamr@2:     virtual void FocusChanged(TDrawNow aDrawNow);
williamr@2: private:
williamr@2: 
williamr@2:     /* 
williamr@2:      * Constructor
williamr@2:      */
williamr@2:     CAknBitmapAnimation();
williamr@2:     
williamr@2:     /*
williamr@2:      * Second phase construction
williamr@2:      */
williamr@2:     void ConstructL();
williamr@2:     
williamr@2:     /*
williamr@2:      * Complete animation initialisation. Sets the animation window, 
williamr@2:      * the position, and the animation data. Records the fact that 
williamr@2:      * initialisation has occurred.
williamr@2:      */
williamr@2:     void CompleteAnimationInitialisationL();
williamr@2:     
williamr@2:     /*
williamr@2:      * Checks the animation initialisation completion flag
williamr@2:      *
williamr@2:      * @return the initialisation flag
williamr@2:      */
williamr@2:     TBool IsInitialisationCompleted();
williamr@2:     
williamr@2:     /*
williamr@2:      * Create frame data, by extracting the interval and position from
williamr@2:      * the resource, and the frame data from the animation itself.
williamr@2:      *
williamr@2:      * @param aFramesReader the resource reader
williamr@2:      * @param aFileName the animation file
williamr@2:      * @param aVersion version of BMPANIM_DATA
williamr@2:      * @return the frame data
williamr@2:      */
williamr@2: 	CBitmapFrameData* CreateFrameDataFromResourceL(TResourceReader& aFramesReader, const TDesC& aFileName, const TInt8 aVersion);
williamr@2:     
williamr@2:     /*
williamr@2:      * Set animation window
williamr@2:      */
williamr@2:     void SetAnimationWindowL();
williamr@2: 
williamr@2: private: // timer
williamr@2:     /*
williamr@2:      * Callback for the animation timer
williamr@2:      *
williamr@2:      * @param aPtr pointer to the owning class
williamr@2:      * @return any error value from the timer
williamr@2:      */
williamr@2:     static TInt AnimationStartedCallback(TAny* aPtr);
williamr@2: 
williamr@2: private:
williamr@2:     CBitmapAnimClientData* iBitmapAnimData;
williamr@2:     RAnimDll iAnimDll;
williamr@2:     RAknBitmapAnim iAnimation;
williamr@2:     TInt iFlags;
williamr@2:     CPeriodic* iTimer;
williamr@2:     TScaleMode iScaleModeFrames;
williamr@2:     TScaleMode iScaleModeBackgroundFrame;
williamr@2:     TBool iGainedFocus;
williamr@2:     };
williamr@2: 
williamr@2: #endif