1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept xml:lang="en" id="GUID-A97AD7EB-43C2-545A-9756-57D65A4905D9"><title>How to create a basic animation</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>The animation framework provides a concrete implementation of the <xref href="GUID-40CEAB8C-2202-3E88-929F-35DA5BD554A4.dita"><apiname>CAnimation</apiname></xref> class called <xref href="GUID-12B29886-1D43-37ED-8DC0-6F43D3E591E8.dita"><apiname>CBasicAnimation</apiname></xref> 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 <xref href="GUID-467B3417-C343-3637-B3AE-C1971C4C0BE3.dita"><apiname>CICLAnimationDataProvider</apiname></xref> class acts as a data provider and handles the data needed for any type of animation. </p> <p>To create a basic client-side animation, create an object of the <codeph>CICLAnimationDataProvider</codeph> 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 <filepath>GIF</filepath> file. </p> <p>The following code shows how to create a data provider object and associate a <filepath>GIF</filepath> file with it: </p> <codeblock id="GUID-9E8D5A00-0166-51A1-A4B6-8C3600916CA0" xml:space="preserve">//Path to the GIF file

    13 _LIT(KAnimExGuitarPlayer,"Z:\\resource\\apps\\AnimExample\\GuitarPlayer.gif");

    14 

    15 //Creating the data provider object and setting the GIF file using the string literal created above.

    16 //The iEikonEnv macro is used to open a session with the file system, before setting the GIF file to the data provider. 

    17 CICLAnimationDataProvider* basicDataProvider = new (ELeave)CICLAnimationDataProvider;

    18 basicDataProvider-&gt;SetFileL(iEikonEnv-&gt;FsSession(), KAnimExGuitarPlayer());</codeblock> <p>Now that the data provider object is ready with the required data, you can create an object of <codeph>CBasicAnimation</codeph> class. The control and behaviour for the animation is defined using the <xref href="GUID-7B02B3D6-D460-3274-8CE6-839549E6EFD3.dita"><apiname>TAnimationConfig</apiname></xref> 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: </p> <ul><li id="GUID-9A2A1585-3D12-5FFE-8F73-069A5848B5FA"><p>Play in a loop: Set the <codeph>iFlags</codeph> variable of the <codeph>TAnimationConfig</codeph> class to <codeph>ELoop</codeph>, and set the number of cycles the animation should complete using the <codeph>iData</codeph> variable. If you want the animation to be played for an indefinite number of cycles, set <codeph>iData</codeph> to <codeph>-1</codeph>. </p> </li> <li id="GUID-F554156C-6481-5E8E-AADA-3DA956BB29B4"><p>Play immediately: Set the <codeph>iFlags</codeph> variable of the <codeph>TAnimationConfig</codeph> class to <codeph>EStartImmediately</codeph>. By default, the animations will wait till the data is loaded completely. </p> </li> <li id="GUID-A5DF5715-5A9F-5EC5-A1D7-7309B2FA2174"><p>Play only specified number of frames: Set the <codeph>iFlags</codeph> variable of the <codeph>TAnimationConfig</codeph> class to <codeph>ECountFrames</codeph>, and set the number of frames the animation should play using the <codeph>iData</codeph> variable. </p> </li> <li id="GUID-0A7DC95B-0ECC-597E-9008-132C9E67DC95"><p>Stop the animation at the last frame: Set the <codeph>iFlags</codeph> variable of the <codeph>TAnimationConfig</codeph> class to <codeph>EEndOnLastFrame</codeph>. By default, when animations stop they return to the first frame. </p> </li> </ul> <p>In this case, the animation is configured to play in an infinite loop. </p> <p>The following code shows how to create and start a basic client-side animation. It loads an animated <filepath>GIF</filepath> file and plays it in an infinite loop : </p> <codeblock id="GUID-8E743CED-5EAF-5717-B098-F4111F143893" xml:space="preserve">//Integer constant defining the X and Y co-ordinates of the animation

    19 const TInt KAnimExBasicPositionX = 300;

    20 const TInt KAnimExBasicPositionY = 100;

    21 TPoint position = TPoint(KAnimExBasicPositionX, KAnimExBasicPositionY);

    22 

    23 //configure the animation to play in an infinite loop

    24 TAnimationConfig config;

    25 config.iFlags = TAnimationConfig::ELoop;

    26 config.iData = -1;

    27 

    28 //Creating the basic animation object using the data provider object and the X and Y coordinates defined above

    29 iBasicAnim = CBasicAnimation::NewL(basicDataProvider,position, iEikonEnv->WsSession(), Window());        

    30 

    31 //Starting the animation using the configuration created above

    32 iBasicAnim-&gt;Start(config);</codeblock> <p>The animation will be visible only when it is rendered to the window. To do so, implement a private virtual member function of <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita"><apiname>CCoeControl</apiname></xref> class called <codeph>Draw()</codeph> in your client application view class. This function should in-turn call the <xref href="GUID-12B29886-1D43-37ED-8DC0-6F43D3E591E8.dita#GUID-12B29886-1D43-37ED-8DC0-6F43D3E591E8/GUID-07FA25D5-3B07-3611-B838-C850C648006C"><apiname>CBasicAnimation::Draw</apiname></xref> function by passing the windows graphics context as an argument. </p> <p>The following code shows how to draw the animation to the window: </p> <codeblock id="GUID-A1314244-8C18-54E9-A403-3D5786CDD6BF" xml:space="preserve">void CClientAppView::Draw(const TRect&amp;) const

    33 {

    34     

    35     CWindowGc& gc = SystemGc();    

    36     if( iBasicAnim )

    37         {

    38         iBasicAnim->Draw( gc );    

    39         }

    40 }</codeblock> <p> <i>Note that you should include proper error checks in the given code before using it for production.</i>  </p> <p>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 <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-28202F81-52FE-30F5-8B8C-ABED0915822E"><apiname>RWindow::Invalidate()</apiname></xref> function. This function will force a client redraw. </p> <p>This code creates a client-side animation which loads an animated <filepath>GIF</filepath> file and plays it in an infinite loop. </p> </conbody><related-links><link href="GUID-829761B6-ECF7-5E15-A475-AEE357687067.dita"><linktext>Animation

    41                 overview</linktext> </link> </related-links></concept>