1 /*

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

    15 *   a skin, or from resource.

    16 * 

    17 *

    18 */

    19 

    20 // AKNBITMAPANIMATION.H

    21 //

    22 

    23 #if !defined(__AKNBITMAPANIMATION_H__)

    24 #define __AKNBITMAPANIMATION_H__

    25 

    26 #if !defined(__COECNTRL_H__)

    27 #include <coecntrl.h>

    28 #endif

    29 

    30 #include <bmpancli.h>

    31 #include <AknControl.h>

    32 #include <AknIconUtils.h>

    33 

    34 /**

    35  * Client class for wserv animations based on bitmaps.

    36  * 

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

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

    39  * specific messages to configure the animation.

    40  *

    41  *  @lib avkon

    42  *  @since S60 0.9

    43  */

    44 class RAknBitmapAnim : public RBitmapAnim

    45     {

    46 public:

    47     /**

    48      * Constructor. 

    49      *

    50      * @param aAnimDll must be already instantiated.

    51      */

    52     RAknBitmapAnim(RAnimDll& aAnimDll);

    53 

    54     /**

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

    56      */

    57     void StartAndKeepLastFrameL();

    58 

    59     /**

    60      * Stops the animation.

    61      *

    62      * @return the error value returned from wserv

    63      */

    64     TInt Stop();

    65     };

    66 

    67 // FORWARD DECLARATIONS

    68 class TResourceReader;

    69 class TAknsItemID;

    70 

    71 /*

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

    73  */

    74 NONSHARABLE_CLASS(CAknBitmapAnimation) : public CAknControl

    75     {

    76 public:

    77     /**

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

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

    80      * either skin or resource.

    81      */

    82     IMPORT_C static CAknBitmapAnimation* NewL();

    83 

    84     /**

    85      * Destructor.

    86      */

    87     IMPORT_C virtual ~CAknBitmapAnimation();

    88 

    89 public:

    90     /**

    91      * gives access to RBitmapAnimation.

    92      *

    93      * @return the RBitmapAnim

    94      */

    95     IMPORT_C RBitmapAnim& Animation();

    96 

    97     /**

    98      * gives access to CBitmapAnimClientData.

    99      *

   100      * @return the CBitmapAnimClientData

   101      */

   102     IMPORT_C CBitmapAnimClientData* BitmapAnimData() const;

   103 

   104     /**

   105      * Cancels the animation.

   106      *

   107      * @return the error code from stopping the animation

   108      */

   109     IMPORT_C TInt CancelAnimation();

   110 

   111     /**

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

   113      *

   114      * @param aIndex the frame index

   115      */

   116     IMPORT_C void SetFrameIndexL(TInt aIndex);

   117 

   118     /**

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

   120      *

   121      * @param aFrameIntervalInMilliSeconds the frame interval

   122      */

   123     IMPORT_C void SetFrameIntervalL(TInt aFrameIntervalInMilliSeconds);

   124 

   125     /**

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

   127      * if necessary.

   128      */

   129     IMPORT_C void StartAnimationL();

   130 

   131     /**

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

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

   134     * Default scale mode is EAspectRatioPreserved.

   135     *

   136     * @since 3.1

   137     * @param aMode scale mode

   138     */

   139     IMPORT_C void SetScaleModeForAnimationFrames(TScaleMode aMode);

   140 

   141     /**

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

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

   144     * Default scale mode is EAspectRatioPreserved.

   145     *

   146     * @since 3.1

   147     * @param aMode scale mode

   148     */

   149     IMPORT_C void SetScaleModeForAnimationBackgroundFrame(TScaleMode aMode);

   150 

   151     /**

   152     * Excludes the animation frames from the icon cache.    

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

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

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

   156     * to get the same effect.

   157     * 

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

   159     * no longer used. 

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

   161     * without the need to render them again.

   162     * Excluding infrequently used animation frames from icon cache could 

   163     * improve performance and memory usage of the system.

   164     * 

   165     * @since 3.1    

   166     */

   167     IMPORT_C void ExcludeAnimationFramesFromCache();

   168     

   169 public: 

   170     /**

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

   172      *

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

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

   175      */

   176     TInt AnimationHasStarted(TBool aHasStarted);

   177 

   178 public:

   179     /**

   180     * Construct the animation from skin.

   181     *

   182     * Usually this method should be called before ConstructFromResourceL,

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

   184     * same animation with ConstructFromResourceL. The ownership of the

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

   186     * Furthermore, the animation is not automatically updated during

   187     * a skin change.

   188     *

   189     * @since 2.0

   190     * @param aItemID Item ID of the animation.

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

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

   193     *   found.

   194     */

   195     IMPORT_C TBool ConstructFromSkinL( const TAknsItemID& aItemID );

   196 

   197 public: // from CCoeControl

   198     /**

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

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

   201      * 

   202      * @param aResourceReader the resource reader

   203      */

   204     IMPORT_C virtual void ConstructFromResourceL(TResourceReader& aResourceReader);

   205 

   206     /**

   207      * Minimum size.

   208      */

   209     IMPORT_C virtual TSize MinimumSize();

   210     

   211 public:

   212     /**

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

   214      * if necessary.

   215      */

   216     IMPORT_C void StartAnimationL( TBool aKeepLastFrame );

   217 

   218 private: // from CCoeControl

   219     

   220     /*

   221      * Size changed.

   222      */

   223     virtual void SizeChanged();

   224     

   225     /*

   226      * Position Changed

   227      */

   228     virtual void PositionChanged();

   229     

   230     /*

   231      * Draw

   232      *

   233      * @parm aRect the drawing rect

   234      */

   235     virtual void Draw(const TRect& aRect) const;

   236 

   237     /*

   238      * Focus Changed

   239      */

   240     virtual void FocusChanged(TDrawNow aDrawNow);

   241 private:

   242 

   243     /* 

   244      * Constructor

   245      */

   246     CAknBitmapAnimation();

   247     

   248     /*

   249      * Second phase construction

   250      */

   251     void ConstructL();

   252     

   253     /*

   254      * Complete animation initialisation. Sets the animation window, 

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

   256      * initialisation has occurred.

   257      */

   258     void CompleteAnimationInitialisationL();

   259     

   260     /*

   261      * Checks the animation initialisation completion flag

   262      *

   263      * @return the initialisation flag

   264      */

   265     TBool IsInitialisationCompleted();

   266     

   267     /*

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

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

   270      *

   271      * @param aFramesReader the resource reader

   272      * @param aFileName the animation file

   273      * @param aVersion version of BMPANIM_DATA

   274      * @return the frame data

   275      */

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

   277     

   278     /*

   279      * Set animation window

   280      */

   281     void SetAnimationWindowL();

   282 

   283 private: // timer

   284     /*

   285      * Callback for the animation timer

   286      *

   287      * @param aPtr pointer to the owning class

   288      * @return any error value from the timer

   289      */

   290     static TInt AnimationStartedCallback(TAny* aPtr);

   291 

   292 private:

   293     CBitmapAnimClientData* iBitmapAnimData;

   294     RAnimDll iAnimDll;

   295     RAknBitmapAnim iAnimation;

   296     TInt iFlags;

   297     CPeriodic* iTimer;

   298     TScaleMode iScaleModeFrames;

   299     TScaleMode iScaleModeBackgroundFrame;

   300     TBool iGainedFocus;

   301     };

   302 

   303 #endif