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

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

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

"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: 

-->

<!DOCTYPE concept

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

<concept id="GUID-05D6AB1C-8548-58C6-AA6C-EE362FF49247" xml:lang="en"><title>Bitmap

Animation Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-44C21503-6654-4590-996F-969D5B8B6869"><title>Purpose</title> <p>This document shows you how to create an

animation using the Bitmap Animation framework. </p> </section>

<section id="GUID-3968A450-B383-4F55-A89D-817908FD67BE"><title>Architectural relationships</title> <p>The Bitmap Animation

framework (<filepath>bmpanim.dll</filepath>) uses the font and bitmap server

(<filepath>fbscli.dll</filepath>) to provide the bitmap images (<xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> s). </p> <p>An

animation DLL (<filepath>bmpansrv.dll</filepath>), loaded by the Window Server,

is used to perform the animation. </p> <p>The animation DLL uses the bitgdi

component (<filepath>bitgdi.dll</filepath>) to draw the bitmaps. </p> </section>

<section id="GUID-0CE251DB-D48D-43D2-AF0D-420D7AAF6414"><title>Description</title> <p>To use a bitmap animation in your application

you need to: </p> <ul>

<li id="GUID-F6367722-F765-550C-8B85-65FFEA38369A"><p>define one or more animation

frames, each of which owns a bitmap, </p> </li>

<li id="GUID-7B1EB74D-0057-52D6-8560-A96A301F0ED3"><p>assign the frames to

an animation container, </p> </li>

<li id="GUID-4C005026-80CE-59B4-A9EE-DAFD2EB71DFA"><p>create an animation

player object and pass the animation container to it. This communicates with

the window server to start and stop playing the animation inside a window. </p> </li>

</ul> <p>Collectively, these steps make up the Bitmap Animation framework.

The key client side classes that are involved in these steps are: </p> <ul>

<li id="GUID-64D5B1E5-7FDD-5AD1-BD0F-906D27B118B1"><p> <xref href="GUID-D88261C5-BCD8-36C4-9A46-6DA0A7FB5594.dita"><apiname>CBitmapFrameData</apiname></xref>, </p> </li>

<li id="GUID-0F881880-38C8-5E94-869E-835D90960C45"><p> <xref href="GUID-780B280B-A3D9-31C8-9F82-55353DC7E056.dita"><apiname>CBitmapAnimClientData</apiname></xref>, </p> </li>

<li id="GUID-7330A56E-0371-5AE7-942F-E461F7D697F1"><p> <xref href="GUID-0282B941-2A58-3F3D-8875-DFBA72F46F48.dita"><apiname>RBitmapAnim</apiname></xref>. </p> </li>

</ul> <p>The rest of this document describes each of these steps, starting

with the animation frame. </p> </section>

<section id="GUID-112ED5AB-2CFA-415A-8CA2-9B327BADC99A"><title>Defining an animation frame</title> <p>The <codeph>CBitmapFrameData</codeph> class

represents a single frame in an animation. The following properties of a frame

can be set: </p> <ul>

<li id="GUID-DEC005F2-FBAC-59AA-BA41-E4B3B025B19C"><p>the bitmap image, </p> </li>

<li id="GUID-D1829CD2-786B-55DF-AF9A-49EBC2765906"><p>the mask, which is used

for making parts of the image transparent, </p> </li>

<li id="GUID-1371D69B-D45F-5A1E-8BA5-37210ED0FABA"><p>the time the frame is

displayed, in milliseconds, </p> </li>

<li id="GUID-8290AB20-F4E2-5FBC-84FA-BD55D4AE8EB4"><p>the position in the

window where the frame is displayed. </p> </li>

</ul> <p>These properties can either be set in <xref href="GUID-D88261C5-BCD8-36C4-9A46-6DA0A7FB5594.dita#GUID-D88261C5-BCD8-36C4-9A46-6DA0A7FB5594/GUID-83DBA551-0023-399B-8791-EC4CEB4BEF53"><apiname>CBitmapFrameData::NewL()</apiname></xref> or

by calling various setter functions, described below. </p> <p><b>Setting the

image and mask bitmaps </b> </p> <p>The following code loads the bitmap and

mask from a multi bitmap file, and constructs the frame, setting its bitmap

and mask, which it takes ownership of: </p> <codeblock id="GUID-2B408AB3-8816-51B6-95DD-6848EB83EC84" xml:space="preserve">CFbsBitmap* bitmap=new (ELeave) CFbsBitmap; // load the image bitmap from an mbm file 

CleanupStack::PushL(bitmap);

User::LeaveIfError(bitmap->Load(KMBMFileName, EMbmAnimFrame1));

CFbsBitmap* mask=new (ELeave) CFbsBitmap; // load the mask from the same mbm file

CleanupStack::PushL(mask);

User::LeaveIfError(mask->Load(KMBMFileName, EMbmAnimFrameMask1));

CBitmapFrameData* frame1 = CBitmapFrameData::NewL(bitmap, mask);

CleanupStack::Pop(2); // bitmap, mask</codeblock> <p> <xref href="GUID-D88261C5-BCD8-36C4-9A46-6DA0A7FB5594.dita#GUID-D88261C5-BCD8-36C4-9A46-6DA0A7FB5594/GUID-E1FFD12D-5139-3532-8207-1D94C75ACBE8"><apiname>CBitmapFrameData::SetBitmap()</apiname></xref> and <xref href="GUID-D88261C5-BCD8-36C4-9A46-6DA0A7FB5594.dita#GUID-D88261C5-BCD8-36C4-9A46-6DA0A7FB5594/GUID-D7EB7A35-006B-3A89-9EBA-3BFD28D02518"><apiname>CBitmapFrameData::SetMask()</apiname></xref> could alternatively be used. </p> <p>An animation can have multiple frames,

each of which has an image and mask bitmap. Each frame stores a flag to indicate

whether or not it owns the bitmaps. If the frame owns the bitmaps, they are

deleted in the frame’s destructor. This flag can be set or unset by calling <xref href="GUID-D88261C5-BCD8-36C4-9A46-6DA0A7FB5594.dita#GUID-D88261C5-BCD8-36C4-9A46-6DA0A7FB5594/GUID-15F4E778-0D5C-3653-8722-9352F4386C76"><apiname>CBitmapFrameData::SetBitmapsOwnedExternally()</apiname></xref>.

By default, bitmaps are owned by the frame. </p> <p>The mask is used in the

standard way for a bitmap mask, so pixels in the bitmap image that map to

black pixels in the mask are drawn, while pixels that map to white pixels

in the mask are not, so appear transparent. </p> <p><b>Setting the time interval </b> </p> <p>The

time period for the frame to be displayed on the screen is set in milliseconds: </p> <codeblock id="GUID-7D886BE6-2660-5937-83F6-740D98E9A002" xml:space="preserve">frame1-&gt;SetInterval(125);</codeblock> <p>Note

that a default time interval can be set in the frame container (described

in the next section) by calling <xref href="GUID-780B280B-A3D9-31C8-9F82-55353DC7E056.dita#GUID-780B280B-A3D9-31C8-9F82-55353DC7E056/GUID-A7CEB917-12B5-38E8-9BBA-5F42B695EA92"><apiname>CBitmapAnimClientData::SetFrameInterval()</apiname></xref>.

Any value set in the container will apply to frames that have not set an interval

themselves. </p> <p><b>Setting the frame’s position </b> </p> <p>The position

of the frame relative to the animation window is set using <xref href="GUID-D88261C5-BCD8-36C4-9A46-6DA0A7FB5594.dita#GUID-D88261C5-BCD8-36C4-9A46-6DA0A7FB5594/GUID-EA74CED1-0AE0-30D2-9FFF-AAB321FC119C"><apiname>CBitmapFrameData::SetPosition()</apiname></xref>: </p> <codeblock id="GUID-2344FB5E-F8DC-54C1-8995-A2B21DDA5D24" xml:space="preserve">TPoint framePos(3,6);

frame1-&gt;SetPosition(framePos);</codeblock> <p>Note that the position can also

be specified in <xref href="GUID-0282B941-2A58-3F3D-8875-DFBA72F46F48.dita"><apiname>RBitmapAnim</apiname></xref>; if so, this value applies

to all frames. </p> <p>When you have finished defining the animation frame(s),

use the frame container class, <xref href="GUID-780B280B-A3D9-31C8-9F82-55353DC7E056.dita"><apiname>CBitmapAnimClientData</apiname></xref>, to

create the animation. </p> </section>

<section id="GUID-598D3A59-6DC6-40C9-9CFA-30D5AB656040"><title>Defining an animation</title> <p>Frames are grouped into an

animation frame container (<xref href="GUID-780B280B-A3D9-31C8-9F82-55353DC7E056.dita"><apiname>CBitmapAnimClientData</apiname></xref>), which

allows the following behaviour to be set: </p> <ul>

<li id="GUID-3DB97BEC-DE20-5514-AE79-D21D6B3C257D"><p>append frames to the

container, </p> </li>

<li id="GUID-13AA19C6-45E7-5AEC-A202-2D8FCA16BC4D"><p>set a default display

interval for all frames, (note that the time interval set by an individual

frame takes precedence, for that frame, over the default interval), </p> </li>

<li id="GUID-CC7DA6F4-DDA9-5296-8348-9FA4D2D9B203"><p>set one of the following

play modes for the animation: play once, loop or bounce (plays forwards and

backwards), </p> </li>

<li id="GUID-B32243AD-62F2-547D-B31B-C8B520F71D78"><p>set the animation to

flash, </p> </li>

<li id="GUID-F8251606-6004-5752-B74A-23CF280248B9"><p>provide an additional

bitmap frame to use for the background to the animation (explained below). </p> </li>

</ul> <p><b>Appending frames </b> </p> <p>First, create the frame container,

and append the frame(s) to it in the correct sequence: </p> <codeblock id="GUID-67B754F6-1802-5361-9CB9-40E6D025AB04" xml:space="preserve">CBitmapAnimClientData* animFrames=CBitmapAnimClientData::NewL();

CleanupStack::PushL(animFrames);

animFrames->AppendFrameL(*frame1);

animFrames-&gt;AppendFrameL(*frame2); // etc.</codeblock> <p><b>Setting the default

display interval </b> </p> <p>A default display interval can be set for the

animation: </p> <codeblock id="GUID-126F763A-DB9C-50F4-BEB5-70093895CB03" xml:space="preserve">animFrames-&gt;SetFrameInterval(100);</codeblock> <p>This

applies only to frames which have not specified their own interval (using <xref href="GUID-D88261C5-BCD8-36C4-9A46-6DA0A7FB5594.dita#GUID-D88261C5-BCD8-36C4-9A46-6DA0A7FB5594/GUID-4EE6A625-B3AD-3389-93F0-D92D6FC3FC68"><apiname>CBitmapFrameData::SetInterval()</apiname></xref>).

In this example, the default interval for frames without their own interval

is 100 milliseconds (0.1 second). It can be used to ensure that all frames

are displayed for the same length of time. </p> <p><b>Setting the play mode </b> </p> <p>There

are three play modes: play once, play repeatedly in the same direction ('loop')

and play forwards and backwards repeatedly ('bounce'). This code sets the

animation to play once: </p> <codeblock id="GUID-13F860DF-A4E7-505E-AAD3-92C7BDF68886" xml:space="preserve">animFrames-&gt;SetPlayMode(CBitmapAnimClientData::EPlay);</codeblock> <p><b>Other properties </b> </p> <p> <xref href="GUID-780B280B-A3D9-31C8-9F82-55353DC7E056.dita#GUID-780B280B-A3D9-31C8-9F82-55353DC7E056/GUID-E1BDF09C-2154-3E60-BFBD-B4400C3EA295"><apiname>CBitmapAnimClientData::SetFlash()</apiname></xref> and <xref href="GUID-780B280B-A3D9-31C8-9F82-55353DC7E056.dita#GUID-780B280B-A3D9-31C8-9F82-55353DC7E056/GUID-C2B4666A-A755-313D-BAC5-CEF74C09BDB2"><apiname>CBitmapAnimClientData::SetBackgroundFrame()</apiname></xref> are used to set/unset the flash flag and the background frame, respectively.

The flash flag determines whether the animation should flash or not. </p> <p>The

background frame, which is optional, is used to clear the current frame before

drawing the next one. If no background frame is provided by the client, the

window server creates its own background frame using the original screen contents,

and updates it when the animation window is redrawn. </p> <p>If the client-provided

background frame contains an image bitmap and a mask, the background image

used is a combination of the screen contents and the supplied background bitmap.

If the client-provided background frame has a bitmap but no mask, the bitmap

is used as the background. </p> </section>

<section id="GUID-7299DDF6-52E7-43FB-A940-DD8D3059AE6E"><title>Playing the animation</title> <p>When the animation is ready

to play, it must be packaged and sent to the window server’s animation DLL.

This is done through an animation player (<xref href="GUID-0282B941-2A58-3F3D-8875-DFBA72F46F48.dita"><apiname>RBitmapAnim</apiname></xref>)

object. </p> <p> <codeph>RBitmapAnim</codeph> allows you to do the following: </p> <ul>

<li id="GUID-FE236CAC-38D1-5A3C-BE6A-35897F564592"><p>specify the window in

which the animation is displayed, </p> </li>

<li id="GUID-C0D41155-63B9-5038-924E-D7F3193FF65F"><p>associate the animation

with an <xref href="GUID-800B3667-F45F-391F-A8A9-F876FB4ABC34.dita"><apiname>RAnimDll</apiname></xref> object, which provides a connection to

the window server, </p> </li>

<li id="GUID-301E0D0B-2010-56CF-8780-FBE322CD9FDA"><p>pass the animation object

to the window server’s animation DLL, </p> </li>

<li id="GUID-610C8A64-4BC6-5E59-8DC4-809B47328F02"><p>specify the number of

times the animation should play, </p> </li>

<li id="GUID-2384FF48-9281-5D4E-9298-D822B7566E52"><p>start and stop playing

the animation. Optionally the animation can start playing from a particular

frame. </p> </li>

</ul> <p>Note that after the animation object has been set up and passed to

the window server, the general attributes of the animation, namely the flash

property, the default display time for each frame and the play mode can still

be changed, using the following <codeph>RBitmapAnim</codeph> functions: </p> <ul>

<li id="GUID-8DA50426-3BD1-5B8E-B8D7-B0D8F19409DF"><p> <codeph>SetFlashL()</codeph>, </p> </li>

<li id="GUID-C237DFD6-427F-5953-AFB6-0AA64B0D97FE"><p> <codeph>SetFrameIntervalL()</codeph>, </p> </li>

<li id="GUID-8020158F-10BA-554E-9088-E51CE00DBBC6"><p> <codeph>SetPlayModeL()</codeph>. </p> </li>

</ul> <p>Any changes to these properties made using <codeph>RBitmapAnim</codeph> will

override the values previously set in <codeph>CBitmapAnimClientData</codeph>. </p> <p><b>Constructing

the animation player </b> </p> <p> <xref href="GUID-800B3667-F45F-391F-A8A9-F876FB4ABC34.dita"><apiname>RAnimDll</apiname></xref> is a handle

to the server-side animation DLL. It is used to load the window server animation

DLL, <filepath>bmpansrv.dll</filepath>, which provides the functions that

perform the frames animation. The <codeph>RAnimDll</codeph> instance is passed

to the <codeph>RBitmapAnim</codeph> constructor. </p> <codeblock id="GUID-04E123E6-306B-5C8B-9A0B-A415E6EBC74A" xml:space="preserve">RAnimDll animDLL(iEikonEnv-&gt;WsSession()); // session is used to interact with the window server

_LIT(KDllName, "BMPANSRV.DLL"); 

User::LeaveIfError(animDll.Load(KDllName)); 

RBitmapAnim animPlayer(animDLL);

animPlayer.ConstructL(Window());</codeblock> <p><b>Passing the animation object

to the window server </b> </p> <p>The animation frame container (<codeph>CBitmapAnimClientData</codeph>)

should be passed via the <codeph>RBitmapAnim</codeph> object to the window

server. This is done using the function <codeph>SetBitmapAnimDataL()</codeph>.

Note that calling this function does not cause the animation to start playing: </p> <codeblock id="GUID-F8CCC483-9B1F-58A4-AF93-E8E967A535B1" xml:space="preserve">animPlayer.SetBitmapAnimDataL(*animFrames);</codeblock> <p><b>Setting

the number of cycles </b> </p> <p>If the animation should play more than once,

the number of cycles should be set: </p> <codeblock id="GUID-549751F2-770E-54C4-8C78-7AFF633D9A4D" xml:space="preserve">animPlayer.SetNumberOfCyclesL(10);</codeblock> <p>Note that if the animation's play mode is 'bounce', the number of cycles

must be set to at least two to ensure a complete animation routine. </p> <p><b>Setting

the position </b> </p> <p>To set the animation’s position, use <codeph>SetPositionL()</codeph>.

This value is an offset from the origin of the animation window. </p> <codeblock id="GUID-3F4E29C5-A456-5BFC-AA10-0A7E29EAAB97" xml:space="preserve">TPoint animPos(20,40);

animPlayer.SetPositionL(animPos);</codeblock> <p><b>Starting/stopping the

animation </b> </p> <p>The <xref href="GUID-0282B941-2A58-3F3D-8875-DFBA72F46F48.dita#GUID-0282B941-2A58-3F3D-8875-DFBA72F46F48/GUID-E7C514C8-0335-3903-A997-C226170798C5"><apiname>RBitmapAnim::StartL()</apiname></xref> and <xref href="GUID-0282B941-2A58-3F3D-8875-DFBA72F46F48.dita#GUID-0282B941-2A58-3F3D-8875-DFBA72F46F48/GUID-DD8AFC9D-E742-36E7-8816-37E61392DEDF"><apiname>RBitmapAnim::StopL()</apiname></xref> functions

send commands to the animation DLL to start/stop the animation routine. </p> <p>Calling <xref href="GUID-0282B941-2A58-3F3D-8875-DFBA72F46F48.dita#GUID-0282B941-2A58-3F3D-8875-DFBA72F46F48/GUID-1E2FCA51-21BF-3C21-8D96-753E27F277B1"><apiname>RBitmapAnim::DisplayFrameL()</apiname></xref> before

the animation has started sets the frame from which the animation should start

playing. </p> <p><b>Freeing resources </b> </p> <p>After they have been finished

with, <codeph>Close()</codeph> should be called on the <codeph>RAnimDll</codeph> and <codeph>RBitmapAnim</codeph> objects. </p> <codeblock id="GUID-E7E87F97-9040-50F1-99F2-35AF517993E1" xml:space="preserve">animPlayer.Close();

animDLL.Close();</codeblock> </section>

<section id="GUID-CF40984F-2CA8-4EEE-98AD-C8F3E074407F"><title>See also</title> <ul>

<li><p><xref href="GUID-3D577CFE-A6C7-5C4C-A9AA-9382A062A3BE.dita">Animation Overview</xref></p></li>

<li><p><xref href="GUID-71DADA82-3ABC-52D2-8360-33FAEB2E5DE9.dita">Introduction

to the Font and Bitmap Server</xref></p></li>

</ul> </section>

</conbody></concept>