--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-05D6AB1C-8548-58C6-AA6C-EE362FF49247.dita	Fri Jun 11 12:39:03 2010 +0100
@@ -0,0 +1,171 @@
+<?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>
\ No newline at end of file