/*
* 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