How to create a basic animation

The animation framework provides a concrete implementation of the CAnimation class called CBasicAnimation class to create a basic client-side animation. A basic client-side animation needs data, which can range from a simple file to a complex data structure. The data provider is responsible for handling this data and cater to the needs of the animation whenever required. The CICLAnimationDataProvider class acts as a data provider and handles the data needed for any type of animation.

To create a basic client-side animation, create an object of the CICLAnimationDataProvider class. Associate the data required for the animation with the data provider object. In the example used below, the data needed for the animation is a simple animated GIF file.

The following code shows how to create a data provider object and associate a GIF file with it:

//Path to the GIF file
_LIT(KAnimExGuitarPlayer,"Z:\\resource\\apps\\AnimExample\\GuitarPlayer.gif");

//Creating the data provider object and setting the GIF file using the string literal created above.
//The iEikonEnv macro is used to open a session with the file system, before setting the GIF file to the data provider. 
CICLAnimationDataProvider* basicDataProvider = new (ELeave)CICLAnimationDataProvider;
basicDataProvider->SetFileL(iEikonEnv->FsSession(), KAnimExGuitarPlayer());

Now that the data provider object is ready with the required data, you can create an object of CBasicAnimation class. The control and behaviour for the animation is defined using the TAnimationConfig class. You should create such an object and provide it to the animation. The behaviour of the animation can be set to any of the following:

Play in a loop: Set the iFlags variable of the TAnimationConfig class to ELoop, and set the number of cycles the animation should complete using the iData variable. If you want the animation to be played for an indefinite number of cycles, set iData to -1.
Play immediately: Set the iFlags variable of the TAnimationConfig class to EStartImmediately. By default, the animations will wait till the data is loaded completely.
Play only specified number of frames: Set the iFlags variable of the TAnimationConfig class to ECountFrames, and set the number of frames the animation should play using the iData variable.
Stop the animation at the last frame: Set the iFlags variable of the TAnimationConfig class to EEndOnLastFrame. By default, when animations stop they return to the first frame.

In this case, the animation is configured to play in an infinite loop.

The following code shows how to create and start a basic client-side animation. It loads an animated GIF file and plays it in an infinite loop :

//Integer constant defining the X and Y co-ordinates of the animation
const TInt KAnimExBasicPositionX = 300;
const TInt KAnimExBasicPositionY = 100;
TPoint position = TPoint(KAnimExBasicPositionX, KAnimExBasicPositionY);

//configure the animation to play in an infinite loop
TAnimationConfig config;
config.iFlags = TAnimationConfig::ELoop;
config.iData = -1;

//Creating the basic animation object using the data provider object and the X and Y coordinates defined above
iBasicAnim = CBasicAnimation::NewL(basicDataProvider,position, iEikonEnv->WsSession(), Window());        

//Starting the animation using the configuration created above
iBasicAnim->Start(config);

The animation will be visible only when it is rendered to the window. To do so, implement a private virtual member function of CCoeControl class called Draw() in your client application view class. This function should in-turn call the CBasicAnimation::Draw function by passing the windows graphics context as an argument.

The following code shows how to draw the animation to the window:

void CClientAppView::Draw(const TRect&) const
{
    
    CWindowGc& gc = SystemGc();    
    if( iBasicAnim )
        {
        iBasicAnim->Draw( gc );    
        }
}

Note that you should include proper error checks in the given code before using it for production.

When a new frame is required for the animation, the entire window or an area within in the window need to be redrawn using the RWindow::Invalidate() function. This function will force a client redraw.

This code creates a client-side animation which loads an animated GIF file and plays it in an infinite loop.

Related concepts

Animation overview