--- a/Symbian3/SDK/Source/GUID-05D6AB1C-8548-58C6-AA6C-EE362FF49247-GENID-1-8-1-3-1-1-5-1-3-1.dita	Wed Mar 31 11:11:55 2010 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,171 +0,0 @@
-<?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-GENID-1-8-1-3-1-1-5-1-3-1" xml:lang="en"><title>Bitmap
-Animation Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>
-<section id="GUID-44C21503-6654-4590-996F-969D5B8B6869-GENID-1-8-1-3-1-1-5-1-3-1-2-1"><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-GENID-1-8-1-3-1-1-5-1-3-1-2-2"><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-GENID-1-8-1-3-1-1-5-1-3-1-2-3"><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-GENID-1-8-1-3-1-1-5-1-3-1-2-3-3-1"><p>define one or more animation
-frames, each of which owns a bitmap, </p> </li>
-<li id="GUID-7B1EB74D-0057-52D6-8560-A96A301F0ED3-GENID-1-8-1-3-1-1-5-1-3-1-2-3-3-2"><p>assign the frames to
-an animation container, </p> </li>
-<li id="GUID-4C005026-80CE-59B4-A9EE-DAFD2EB71DFA-GENID-1-8-1-3-1-1-5-1-3-1-2-3-3-3"><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-GENID-1-8-1-3-1-1-5-1-3-1-2-3-5-1"><p> <xref href="GUID-D88261C5-BCD8-36C4-9A46-6DA0A7FB5594.dita"><apiname>CBitmapFrameData</apiname></xref>, </p> </li>
-<li id="GUID-0F881880-38C8-5E94-869E-835D90960C45-GENID-1-8-1-3-1-1-5-1-3-1-2-3-5-2"><p> <xref href="GUID-780B280B-A3D9-31C8-9F82-55353DC7E056.dita"><apiname>CBitmapAnimClientData</apiname></xref>, </p> </li>
-<li id="GUID-7330A56E-0371-5AE7-942F-E461F7D697F1-GENID-1-8-1-3-1-1-5-1-3-1-2-3-5-3"><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-GENID-1-8-1-3-1-1-5-1-3-1-2-4"><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-GENID-1-8-1-3-1-1-5-1-3-1-2-4-3-1"><p>the bitmap image, </p> </li>
-<li id="GUID-D1829CD2-786B-55DF-AF9A-49EBC2765906-GENID-1-8-1-3-1-1-5-1-3-1-2-4-3-2"><p>the mask, which is used
-for making parts of the image transparent, </p> </li>
-<li id="GUID-1371D69B-D45F-5A1E-8BA5-37210ED0FABA-GENID-1-8-1-3-1-1-5-1-3-1-2-4-3-3"><p>the time the frame is
-displayed, in milliseconds, </p> </li>
-<li id="GUID-8290AB20-F4E2-5FBC-84FA-BD55D4AE8EB4-GENID-1-8-1-3-1-1-5-1-3-1-2-4-3-4"><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-GENID-1-8-1-3-1-1-5-1-3-1-2-4-7" 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-GENID-1-8-1-3-1-1-5-1-3-1-2-4-13" 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-GENID-1-8-1-3-1-1-5-1-3-1-2-4-17" 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-GENID-1-8-1-3-1-1-5-1-3-1-2-5"><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-GENID-1-8-1-3-1-1-5-1-3-1-2-5-3-1"><p>append frames to the
-container, </p> </li>
-<li id="GUID-13AA19C6-45E7-5AEC-A202-2D8FCA16BC4D-GENID-1-8-1-3-1-1-5-1-3-1-2-5-3-2"><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-GENID-1-8-1-3-1-1-5-1-3-1-2-5-3-3"><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-GENID-1-8-1-3-1-1-5-1-3-1-2-5-3-4"><p>set the animation to
-flash, </p> </li>
-<li id="GUID-F8251606-6004-5752-B74A-23CF280248B9-GENID-1-8-1-3-1-1-5-1-3-1-2-5-3-5"><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-GENID-1-8-1-3-1-1-5-1-3-1-2-5-6" 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-GENID-1-8-1-3-1-1-5-1-3-1-2-5-9" 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-GENID-1-8-1-3-1-1-5-1-3-1-2-5-13" 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-GENID-1-8-1-3-1-1-5-1-3-1-2-6"><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-GENID-1-8-1-3-1-1-5-1-3-1-2-6-4-1"><p>specify the window in
-which the animation is displayed, </p> </li>
-<li id="GUID-C0D41155-63B9-5038-924E-D7F3193FF65F-GENID-1-8-1-3-1-1-5-1-3-1-2-6-4-2"><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-GENID-1-8-1-3-1-1-5-1-3-1-2-6-4-3"><p>pass the animation object
-to the window server’s animation DLL, </p> </li>
-<li id="GUID-610C8A64-4BC6-5E59-8DC4-809B47328F02-GENID-1-8-1-3-1-1-5-1-3-1-2-6-4-4"><p>specify the number of
-times the animation should play, </p> </li>
-<li id="GUID-2384FF48-9281-5D4E-9298-D822B7566E52-GENID-1-8-1-3-1-1-5-1-3-1-2-6-4-5"><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-GENID-1-8-1-3-1-1-5-1-3-1-2-6-6-1"><p> <codeph>SetFlashL()</codeph>, </p> </li>
-<li id="GUID-C237DFD6-427F-5953-AFB6-0AA64B0D97FE-GENID-1-8-1-3-1-1-5-1-3-1-2-6-6-2"><p> <codeph>SetFrameIntervalL()</codeph>, </p> </li>
-<li id="GUID-8020158F-10BA-554E-9088-E51CE00DBBC6-GENID-1-8-1-3-1-1-5-1-3-1-2-6-6-3"><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-GENID-1-8-1-3-1-1-5-1-3-1-2-6-10" 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-GENID-1-8-1-3-1-1-5-1-3-1-2-6-13" 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-GENID-1-8-1-3-1-1-5-1-3-1-2-6-16" 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-GENID-1-8-1-3-1-1-5-1-3-1-2-6-20" 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-GENID-1-8-1-3-1-1-5-1-3-1-2-6-26" xml:space="preserve">animPlayer.Close();
-animDLL.Close();</codeblock> </section>
-<section id="GUID-CF40984F-2CA8-4EEE-98AD-C8F3E074407F-GENID-1-8-1-3-1-1-5-1-3-1-2-7"><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