|
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 id="GUID-05D6AB1C-8548-58C6-AA6C-EE362FF49247" xml:lang="en"><title>Bitmap |
|
13 Animation Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-44C21503-6654-4590-996F-969D5B8B6869"><title>Purpose</title> <p>This document shows you how to create an |
|
15 animation using the Bitmap Animation framework. </p> </section> |
|
16 <section id="GUID-3968A450-B383-4F55-A89D-817908FD67BE"><title>Architectural relationships</title> <p>The Bitmap Animation |
|
17 framework (<filepath>bmpanim.dll</filepath>) uses the font and bitmap server |
|
18 (<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 |
|
19 animation DLL (<filepath>bmpansrv.dll</filepath>), loaded by the Window Server, |
|
20 is used to perform the animation. </p> <p>The animation DLL uses the bitgdi |
|
21 component (<filepath>bitgdi.dll</filepath>) to draw the bitmaps. </p> </section> |
|
22 <section id="GUID-0CE251DB-D48D-43D2-AF0D-420D7AAF6414"><title>Description</title> <p>To use a bitmap animation in your application |
|
23 you need to: </p> <ul> |
|
24 <li id="GUID-F6367722-F765-550C-8B85-65FFEA38369A"><p>define one or more animation |
|
25 frames, each of which owns a bitmap, </p> </li> |
|
26 <li id="GUID-7B1EB74D-0057-52D6-8560-A96A301F0ED3"><p>assign the frames to |
|
27 an animation container, </p> </li> |
|
28 <li id="GUID-4C005026-80CE-59B4-A9EE-DAFD2EB71DFA"><p>create an animation |
|
29 player object and pass the animation container to it. This communicates with |
|
30 the window server to start and stop playing the animation inside a window. </p> </li> |
|
31 </ul> <p>Collectively, these steps make up the Bitmap Animation framework. |
|
32 The key client side classes that are involved in these steps are: </p> <ul> |
|
33 <li id="GUID-64D5B1E5-7FDD-5AD1-BD0F-906D27B118B1"><p> <xref href="GUID-D88261C5-BCD8-36C4-9A46-6DA0A7FB5594.dita"><apiname>CBitmapFrameData</apiname></xref>, </p> </li> |
|
34 <li id="GUID-0F881880-38C8-5E94-869E-835D90960C45"><p> <xref href="GUID-780B280B-A3D9-31C8-9F82-55353DC7E056.dita"><apiname>CBitmapAnimClientData</apiname></xref>, </p> </li> |
|
35 <li id="GUID-7330A56E-0371-5AE7-942F-E461F7D697F1"><p> <xref href="GUID-0282B941-2A58-3F3D-8875-DFBA72F46F48.dita"><apiname>RBitmapAnim</apiname></xref>. </p> </li> |
|
36 </ul> <p>The rest of this document describes each of these steps, starting |
|
37 with the animation frame. </p> </section> |
|
38 <section id="GUID-112ED5AB-2CFA-415A-8CA2-9B327BADC99A"><title>Defining an animation frame</title> <p>The <codeph>CBitmapFrameData</codeph> class |
|
39 represents a single frame in an animation. The following properties of a frame |
|
40 can be set: </p> <ul> |
|
41 <li id="GUID-DEC005F2-FBAC-59AA-BA41-E4B3B025B19C"><p>the bitmap image, </p> </li> |
|
42 <li id="GUID-D1829CD2-786B-55DF-AF9A-49EBC2765906"><p>the mask, which is used |
|
43 for making parts of the image transparent, </p> </li> |
|
44 <li id="GUID-1371D69B-D45F-5A1E-8BA5-37210ED0FABA"><p>the time the frame is |
|
45 displayed, in milliseconds, </p> </li> |
|
46 <li id="GUID-8290AB20-F4E2-5FBC-84FA-BD55D4AE8EB4"><p>the position in the |
|
47 window where the frame is displayed. </p> </li> |
|
48 </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 |
|
49 by calling various setter functions, described below. </p> <p><b>Setting the |
|
50 image and mask bitmaps </b> </p> <p>The following code loads the bitmap and |
|
51 mask from a multi bitmap file, and constructs the frame, setting its bitmap |
|
52 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 |
|
53 CleanupStack::PushL(bitmap); |
|
54 User::LeaveIfError(bitmap->Load(KMBMFileName, EMbmAnimFrame1)); |
|
55 CFbsBitmap* mask=new (ELeave) CFbsBitmap; // load the mask from the same mbm file |
|
56 CleanupStack::PushL(mask); |
|
57 User::LeaveIfError(mask->Load(KMBMFileName, EMbmAnimFrameMask1)); |
|
58 CBitmapFrameData* frame1 = CBitmapFrameData::NewL(bitmap, mask); |
|
59 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, |
|
60 each of which has an image and mask bitmap. Each frame stores a flag to indicate |
|
61 whether or not it owns the bitmaps. If the frame owns the bitmaps, they are |
|
62 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>. |
|
63 By default, bitmaps are owned by the frame. </p> <p>The mask is used in the |
|
64 standard way for a bitmap mask, so pixels in the bitmap image that map to |
|
65 black pixels in the mask are drawn, while pixels that map to white pixels |
|
66 in the mask are not, so appear transparent. </p> <p><b>Setting the time interval </b> </p> <p>The |
|
67 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->SetInterval(125);</codeblock> <p>Note |
|
68 that a default time interval can be set in the frame container (described |
|
69 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>. |
|
70 Any value set in the container will apply to frames that have not set an interval |
|
71 themselves. </p> <p><b>Setting the frame’s position </b> </p> <p>The position |
|
72 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); |
|
73 frame1->SetPosition(framePos);</codeblock> <p>Note that the position can also |
|
74 be specified in <xref href="GUID-0282B941-2A58-3F3D-8875-DFBA72F46F48.dita"><apiname>RBitmapAnim</apiname></xref>; if so, this value applies |
|
75 to all frames. </p> <p>When you have finished defining the animation frame(s), |
|
76 use the frame container class, <xref href="GUID-780B280B-A3D9-31C8-9F82-55353DC7E056.dita"><apiname>CBitmapAnimClientData</apiname></xref>, to |
|
77 create the animation. </p> </section> |
|
78 <section id="GUID-598D3A59-6DC6-40C9-9CFA-30D5AB656040"><title>Defining an animation</title> <p>Frames are grouped into an |
|
79 animation frame container (<xref href="GUID-780B280B-A3D9-31C8-9F82-55353DC7E056.dita"><apiname>CBitmapAnimClientData</apiname></xref>), which |
|
80 allows the following behaviour to be set: </p> <ul> |
|
81 <li id="GUID-3DB97BEC-DE20-5514-AE79-D21D6B3C257D"><p>append frames to the |
|
82 container, </p> </li> |
|
83 <li id="GUID-13AA19C6-45E7-5AEC-A202-2D8FCA16BC4D"><p>set a default display |
|
84 interval for all frames, (note that the time interval set by an individual |
|
85 frame takes precedence, for that frame, over the default interval), </p> </li> |
|
86 <li id="GUID-CC7DA6F4-DDA9-5296-8348-9FA4D2D9B203"><p>set one of the following |
|
87 play modes for the animation: play once, loop or bounce (plays forwards and |
|
88 backwards), </p> </li> |
|
89 <li id="GUID-B32243AD-62F2-547D-B31B-C8B520F71D78"><p>set the animation to |
|
90 flash, </p> </li> |
|
91 <li id="GUID-F8251606-6004-5752-B74A-23CF280248B9"><p>provide an additional |
|
92 bitmap frame to use for the background to the animation (explained below). </p> </li> |
|
93 </ul> <p><b>Appending frames </b> </p> <p>First, create the frame container, |
|
94 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(); |
|
95 CleanupStack::PushL(animFrames); |
|
96 animFrames->AppendFrameL(*frame1); |
|
97 animFrames->AppendFrameL(*frame2); // etc.</codeblock> <p><b>Setting the default |
|
98 display interval </b> </p> <p>A default display interval can be set for the |
|
99 animation: </p> <codeblock id="GUID-126F763A-DB9C-50F4-BEB5-70093895CB03" xml:space="preserve">animFrames->SetFrameInterval(100);</codeblock> <p>This |
|
100 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>). |
|
101 In this example, the default interval for frames without their own interval |
|
102 is 100 milliseconds (0.1 second). It can be used to ensure that all frames |
|
103 are displayed for the same length of time. </p> <p><b>Setting the play mode </b> </p> <p>There |
|
104 are three play modes: play once, play repeatedly in the same direction ('loop') |
|
105 and play forwards and backwards repeatedly ('bounce'). This code sets the |
|
106 animation to play once: </p> <codeblock id="GUID-13F860DF-A4E7-505E-AAD3-92C7BDF68886" xml:space="preserve">animFrames->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. |
|
107 The flash flag determines whether the animation should flash or not. </p> <p>The |
|
108 background frame, which is optional, is used to clear the current frame before |
|
109 drawing the next one. If no background frame is provided by the client, the |
|
110 window server creates its own background frame using the original screen contents, |
|
111 and updates it when the animation window is redrawn. </p> <p>If the client-provided |
|
112 background frame contains an image bitmap and a mask, the background image |
|
113 used is a combination of the screen contents and the supplied background bitmap. |
|
114 If the client-provided background frame has a bitmap but no mask, the bitmap |
|
115 is used as the background. </p> </section> |
|
116 <section id="GUID-7299DDF6-52E7-43FB-A940-DD8D3059AE6E"><title>Playing the animation</title> <p>When the animation is ready |
|
117 to play, it must be packaged and sent to the window server’s animation DLL. |
|
118 This is done through an animation player (<xref href="GUID-0282B941-2A58-3F3D-8875-DFBA72F46F48.dita"><apiname>RBitmapAnim</apiname></xref>) |
|
119 object. </p> <p> <codeph>RBitmapAnim</codeph> allows you to do the following: </p> <ul> |
|
120 <li id="GUID-FE236CAC-38D1-5A3C-BE6A-35897F564592"><p>specify the window in |
|
121 which the animation is displayed, </p> </li> |
|
122 <li id="GUID-C0D41155-63B9-5038-924E-D7F3193FF65F"><p>associate the animation |
|
123 with an <xref href="GUID-800B3667-F45F-391F-A8A9-F876FB4ABC34.dita"><apiname>RAnimDll</apiname></xref> object, which provides a connection to |
|
124 the window server, </p> </li> |
|
125 <li id="GUID-301E0D0B-2010-56CF-8780-FBE322CD9FDA"><p>pass the animation object |
|
126 to the window server’s animation DLL, </p> </li> |
|
127 <li id="GUID-610C8A64-4BC6-5E59-8DC4-809B47328F02"><p>specify the number of |
|
128 times the animation should play, </p> </li> |
|
129 <li id="GUID-2384FF48-9281-5D4E-9298-D822B7566E52"><p>start and stop playing |
|
130 the animation. Optionally the animation can start playing from a particular |
|
131 frame. </p> </li> |
|
132 </ul> <p>Note that after the animation object has been set up and passed to |
|
133 the window server, the general attributes of the animation, namely the flash |
|
134 property, the default display time for each frame and the play mode can still |
|
135 be changed, using the following <codeph>RBitmapAnim</codeph> functions: </p> <ul> |
|
136 <li id="GUID-8DA50426-3BD1-5B8E-B8D7-B0D8F19409DF"><p> <codeph>SetFlashL()</codeph>, </p> </li> |
|
137 <li id="GUID-C237DFD6-427F-5953-AFB6-0AA64B0D97FE"><p> <codeph>SetFrameIntervalL()</codeph>, </p> </li> |
|
138 <li id="GUID-8020158F-10BA-554E-9088-E51CE00DBBC6"><p> <codeph>SetPlayModeL()</codeph>. </p> </li> |
|
139 </ul> <p>Any changes to these properties made using <codeph>RBitmapAnim</codeph> will |
|
140 override the values previously set in <codeph>CBitmapAnimClientData</codeph>. </p> <p><b>Constructing |
|
141 the animation player </b> </p> <p> <xref href="GUID-800B3667-F45F-391F-A8A9-F876FB4ABC34.dita"><apiname>RAnimDll</apiname></xref> is a handle |
|
142 to the server-side animation DLL. It is used to load the window server animation |
|
143 DLL, <filepath>bmpansrv.dll</filepath>, which provides the functions that |
|
144 perform the frames animation. The <codeph>RAnimDll</codeph> instance is passed |
|
145 to the <codeph>RBitmapAnim</codeph> constructor. </p> <codeblock id="GUID-04E123E6-306B-5C8B-9A0B-A415E6EBC74A" xml:space="preserve">RAnimDll animDLL(iEikonEnv->WsSession()); // session is used to interact with the window server |
|
146 _LIT(KDllName, "BMPANSRV.DLL"); |
|
147 User::LeaveIfError(animDll.Load(KDllName)); |
|
148 RBitmapAnim animPlayer(animDLL); |
|
149 animPlayer.ConstructL(Window());</codeblock> <p><b>Passing the animation object |
|
150 to the window server </b> </p> <p>The animation frame container (<codeph>CBitmapAnimClientData</codeph>) |
|
151 should be passed via the <codeph>RBitmapAnim</codeph> object to the window |
|
152 server. This is done using the function <codeph>SetBitmapAnimDataL()</codeph>. |
|
153 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 |
|
154 the number of cycles </b> </p> <p>If the animation should play more than once, |
|
155 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 |
|
156 must be set to at least two to ensure a complete animation routine. </p> <p><b>Setting |
|
157 the position </b> </p> <p>To set the animation’s position, use <codeph>SetPositionL()</codeph>. |
|
158 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); |
|
159 animPlayer.SetPositionL(animPos);</codeblock> <p><b>Starting/stopping the |
|
160 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 |
|
161 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 |
|
162 the animation has started sets the frame from which the animation should start |
|
163 playing. </p> <p><b>Freeing resources </b> </p> <p>After they have been finished |
|
164 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(); |
|
165 animDLL.Close();</codeblock> </section> |
|
166 <section id="GUID-CF40984F-2CA8-4EEE-98AD-C8F3E074407F"><title>See also</title> <ul> |
|
167 <li><p><xref href="GUID-3D577CFE-A6C7-5C4C-A9AA-9382A062A3BE.dita">Animation Overview</xref></p></li> |
|
168 <li><p><xref href="GUID-71DADA82-3ABC-52D2-8360-33FAEB2E5DE9.dita">Introduction |
|
169 to the Font and Bitmap Server</xref></p></li> |
|
170 </ul> </section> |
|
171 </conbody></concept> |