/*
* Copyright (c) 2007-2008 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: Declaration of CSAnimIhlCtrl class
*
*/
#ifndef SANIMIHLCTRL_H
#define SANIMIHLCTRL_H
#include <e32base.h>
#include <MIHLViewerObserver.h>
class MIHLBitmap;
class MIHLFileImage;
class MIHLImageViewer;
class MSAnimObserver;
class RFs;
/**
* Controls interaction with IHL.
*
* @lib None
* @since S60 3.2
*/
NONSHARABLE_CLASS( CSAnimIhlCtrl ) : public CActive,
public MIHLViewerObserver
{
public:
/**
* Constructs a CSAnimIhlCtrl object.
*
* @since S60 3.2
*
* @param aObserver Observer for screen update events.
* @param aFs Fileserver reference.
* @param aFileName Name of the image file to load.
* @param aDisplayMode Display mode to use, if supported by the image.
* @param aSize Requested size for the image.
* @param aFrameDelay Frame delay for animation, unless specified in the
* animation file itself.
* @param aScalingEnabled Identifies whether to try to scale the image to fit
* the screen size or just use the target size of the animation as it is.
* @return The new object
*/
static CSAnimIhlCtrl* NewL(
MSAnimObserver& aObserver,
RFs& aFs,
const TDesC& aFileName,
const TDisplayMode aDisplayMode,
const TSize& aSize,
const TTimeIntervalMicroSeconds32& aFrameDelay,
const TBool aScalingEnabled );
/**
* Destructor.
*
* @since S60 3.2
*/
virtual ~CSAnimIhlCtrl();
/**
* Get the backgroud colour of the image.
* Should only be called after successfully loading the image.
*
* @since S60 3.2
*
* @return The backgroud colour requested for the image.
*/
TRgb BackroundColour() const;
/**
* Start loading the animation.
*
* @since S60 3.2
*
* @param aCallBack To be called when the animation has been loaded.
*/
void Load( const TCallBack& aCallBack );
/**
* Start loading the animation.
*
* @since S60 3.2
*
* @param aCallBack To be called when the animation has been loaded.
*/
void Play( const TCallBack& aCallBack );
/**
* Returns a Symbian error code indicating the success / failure if loading
* a frame. Only returns useful data when called after a call-back event,
* before re-issuing LoadNextFrame.
*
* @since S60 3.2
*
* @return One of Symbian error codes.
*/
TInt SuccessCode() const;
/**
* Stop loading and playing the animation.
*
* @since S60 3.2
*/
void Stop();
protected:
/**
* From CActive.
* Implements cancellation of an outstanding request.
*
* @since S60 3.2
*/
virtual void DoCancel();
/**
* From CActive.
* Handles an active object's request completion event.
* Never leaves.
*
* @since S60 3.2
*/
virtual void RunL();
private:
/**
* First phase constructor.
*
* @since S60 3.2
*
* @param aObserver Observer for screen update events.
* @param aFrameDelay Frame delay for animation, unless specified in the
* animation file itself.
*/
CSAnimIhlCtrl(
MSAnimObserver& aObserver,
const TTimeIntervalMicroSeconds32& aFrameDelay );
/**
* Second phase constructor.
*
* @since S60 3.2
*
* @param aFs Fileserver reference.
* @param aFileName Name of the image file to load.
* @param aDisplayMode Display mode to use, if supported by the image.
* @param aSize Requested size for the image.
* @param aScalingEnabled Identifies whether to try to scale the image to fit
* the screen size or just use the target size of the animation as it is.
*/
void ConstructL(
RFs& aFs,
const TDesC& aFileName,
const TDisplayMode aDisplayMode,
const TSize& aSize,
const TBool aScalingEnabled );
/**
* Select size to load the image to.
*
* @since S60 3.2
*
* @param aSize Requested size for the image.
* @param aScalingEnabled Identifies whether to try to scale the image to fit
* the screen size or just use the target size of the animation as it is.
* @return A size that most closely matches the requested size but still
* can be used as a load size for the image.
*/
TSize SelectSize( const TSize& aSize, const TBool aScalingEnabled ) const;
/**
* Find an item in the array which is
* a) as close as the target as possible and
* b) smaller that the target (both width and height) and
* c) closer to the target than the optimal size.
* If there is no such item in the array, return the optimal size.
*
* @since S60 3.2
*
* @param aTarget Requested size.
* @param aOptimalSize The optimal size for the image.
* @param aOptions The available options.
* @return Selected item in the array, or TSize( 0, 0 ).
*/
TSize FindClosestMatch(
const TSize& aTarget,
const TSize& aOptimalSize,
const RArray<TSize>& aOptions ) const;
/**
* Start loading the image in a multi-frame file.
*
* @since S60 3.2
*/
void LoadNextSubImage();
/**
* If there are frames left, increment frame index, show the next frame and
* set the timer. Otherwise call the call-back function.
*
* @since S60 3.2
*/
void ShowNextFrame();
/**
* Update frame to screen.
*
* @since S60 3.2
*
* @param aFrameIndex Frame index to update.
*/
void UpdateFrameToScreen( TInt aFrameIndex ) const;
/**
* Starts frame timer.
*
* @since S60 3.2
*/
void StartFrameTimer();
/**
* Stops load or play before notifying client.
*
* @since S60 3.2
*
* @param aError System wide error code used in notification.
* @param aNextState Next state to enter
*/
void StopAndNotify( TInt aError, TInt aNextState );
/**
* Notifies client.
*
* @since S60 3.2
*
* @param aError System wide error code used in notification.
* @param aNextState Next state to enter
*/
void Notify( TInt aError, TInt aNextState );
private:
/**
* From MIHLViewerObserver.
* Handles notifications from IHL image viewer.
*
* @since S60 3.2
*/
void ViewerBitmapChangedL();
/**
* From MIHLViewerObserver.
* Handles error from IHL image viewer.
*
* @since S60 3.2
*
* @param aError System wide error code.
*/
void ViewerError( TInt aError );
private: // data
/** Handle to the file containing the animation to use. */
RFile iFile;
/** Observer for animation events. */
MSAnimObserver& iObserver;
/**
* Frame delay for animation, unless specified in the animation file itself.
*/
TTimeIntervalMicroSeconds32 iFrameDelay;
/** Image object from IHL. Owned. May not be NULL. */
MIHLFileImage* iImage;
/** Identifies the number of animation frames in the image. */
TInt iFrameCount;
/** Identifies the animation frame currently being loaded. */
TInt iFrameIndex;
/** Animation frames . */
RPointerArray<MIHLBitmap> iFrames;
/** To be called when a frame has been loaded. */
TCallBack iCallBack;
/**
* One of Symbian error codes indicating whether the loading of a frame
* was successful.
*/
TInt iSuccessCode;
enum TType
{
EStillImage = 1,
EAnimation,
EMultiFrame
};
/** Type of the image. */
TType iType;
enum TState
{
EInitial = 1,
ELoading,
ELoaded,
EPlaying,
EFinished,
EFailed
};
/** Internal state of the object. */
TInt iState;
/** Timer for timing the frame showing durations. */
RTimer iTimer;
/** Image viewer object from IHL. Owned. May be NULL. */
MIHLImageViewer* iViewer;
/** Size for IHL image viewer. */
TSize iViewerSize;
/* Buffer for image */
HBufC8* iBuffer;
};
#endif // SANIMIHLCTRL_H