<?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-&gt;Load(KMBMFileName, EMbmAnimFrame1));
CFbsBitmap* mask=new (ELeave) CFbsBitmap; // load the mask from the same mbm file
CleanupStack::PushL(mask);
User::LeaveIfError(mask-&gt;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-&gt;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>