|
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-C60DC070-572B-5960-B394-550426FDB909" xml:lang="en"><title> Advanced |
|
13 Pointer Tutorial</title><shortdesc>This tutorial provides step-by-step instructions and sample code |
|
14 to help you write applications using advanced pointers. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target |
|
16 audience</b>: Application developers. </p> |
|
17 <section><title>Required background </title> <p>This topic builds on the material |
|
18 in the following topics: </p> <ul> |
|
19 <li id="GUID-C4209FBD-3860-5F4B-8458-87D22D483953"><p><xref href="GUID-9C269F45-F160-5A4B-ABF8-896D2A538E3B.dita">Advanced |
|
20 Pointer Overview</xref> </p> </li> |
|
21 <li id="GUID-9D3C3B31-F43A-5201-A1EC-A1F2848CFF43"><p><xref href="GUID-9AD75103-CD56-5279-B639-5CA2BBF979B5.dita">Advanced |
|
22 Pointer States and Event Communication</xref> </p> </li> |
|
23 </ul> </section> |
|
24 <section><title>Using advanced pointers</title> <p>This topic covers the following: </p> <ul> |
|
25 <li id="GUID-C3AD43AA-09C0-5BA2-8496-5B87D40C89F5"><p><xref href="GUID-C60DC070-572B-5960-B394-550426FDB909.dita#GUID-C60DC070-572B-5960-B394-550426FDB909/GUID-8CBE862B-0C1D-5088-89B7-9B3EC898E4FC">Enabling multi-touch for a window</xref> </p> </li> |
|
26 <li id="GUID-177323F2-55C6-56D9-B3D2-A8DDACF69E10"><p><xref href="GUID-C60DC070-572B-5960-B394-550426FDB909.dita#GUID-C60DC070-572B-5960-B394-550426FDB909/GUID-C026DAB9-C11C-5D29-A1EA-6730E914250F">Getting Z coordinates from TPointerEvent</xref> </p> </li> |
|
27 <li id="GUID-91CEA92C-A692-5853-96F0-625A76B7DC8D"><p><xref href="GUID-C60DC070-572B-5960-B394-550426FDB909.dita#GUID-C60DC070-572B-5960-B394-550426FDB909/GUID-B7057F69-191F-5AA4-8C61-EBECE66D92F6"> Pinch zooming</xref> </p> </li> |
|
28 </ul> </section> |
|
29 <section id="GUID-8CBE862B-0C1D-5088-89B7-9B3EC898E4FC"><title>Enabling multi-touch |
|
30 in a window</title> <ol id="GUID-210D17A8-4869-5F9B-B71C-672101AC591C"> |
|
31 <li id="GUID-81A2AC5C-7837-5216-8F47-FC5959C27522"><p> <xref href="GUID-637F82AF-0CF9-3C85-834D-7C1A0866DF87.dita"><apiname>RWindow</apiname></xref> provides |
|
32 a handle to a standard window. Call <codeph>RWindow</codeph> to create an |
|
33 instance of a window. </p> <codeblock id="GUID-0E31C3F6-3719-5F16-9F74-C405850604B8" xml:space="preserve"> |
|
34 RWindow window(ws); |
|
35 |
|
36 User::LeaveIfError(window.Construct(wg, reinterpret_cast<TUint32>(&wg) + 1)); |
|
37 </codeblock> </li> |
|
38 <li id="GUID-B67D3702-1A8F-5C6A-AB0F-FEA7C4D04A07"><p>Call <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-05293539-F1B0-3C7D-BB14-3FD42F23D5C8"><apiname>RWindow::EnableAdvancedPointers()</apiname></xref> to |
|
39 enable advanced pointers. Then call <xref href="GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34.dita#GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34/GUID-4E02165A-DFCC-3D18-BB18-18726B28E90A"><apiname>RWindowBase::Activate()</apiname></xref> to |
|
40 display the window and enable the window to receive events. <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> inherits |
|
41 from <xref href="GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34.dita"><apiname>RWindowBase</apiname></xref>, so you can call the <codeph>Activate()</codeph> function |
|
42 on <codeph>RWindow</codeph>. </p> <codeblock id="GUID-DB2FB570-2BB0-5C5F-9E4F-076D6A0E469E" xml:space="preserve"> |
|
43 window.EnableAdvancedPointers(); |
|
44 window.Activate(); |
|
45 </codeblock> <p>When an application needs to receive advanced pointer events |
|
46 in a window, it must call <codeph>RWindowBase::EnableAdvancedPointers()</codeph> for |
|
47 the window <i>before</i> it is activated. </p> <p>If advanced pointers are |
|
48 not enabled for a window, it receives only standard <xref href="GUID-1FFA0073-3D83-388E-A824-08C31F90CC54.dita"><apiname>TPointerEvent</apiname></xref> information |
|
49 from a single pointer with no pressure and proximity data. The single pointer |
|
50 environment rules describe the way in which pointer events coming from many |
|
51 pointers in the multi-pointer model are transformed into events of one pointer. |
|
52 They are necessary to ensure that old single-pointer applications work in |
|
53 a multi-touch environment intuitively and as expected by the user. </p> <p>However, |
|
54 the new <codeph>TPointerEvent</codeph> types, <xref href="GUID-239D0A8B-2759-321D-AD48-976E80192239.dita"><apiname>EEnterCloseProximity</apiname></xref>, <xref href="GUID-8C6264B4-5E19-33A7-92B0-BB79C871BEC7.dita"><apiname>EExitCloseProximity</apiname></xref>, <xref href="GUID-F02DB96E-1541-3223-9B7B-79D45840DB7B.dita"><apiname>EEnterHighPressure</apiname></xref> and <xref href="GUID-15B5991C-B075-3110-B0A4-540EC282AA56.dita"><apiname>EExitHighPressure</apiname></xref>, are delivered to all windows, |
|
55 even to those that do not enable advanced pointers. </p> </li> |
|
56 </ol> </section> |
|
57 <section id="GUID-C026DAB9-C11C-5D29-A1EA-6730E914250F"><title>Getting Z coordinates |
|
58 from TPointerEvent</title> <ol id="GUID-4CC2271D-1798-51B3-9A9D-E7E0B9A33DAE"> |
|
59 <li id="GUID-184B5B63-4EFC-55CD-8D1F-E015EEBACBE2"><p>Call <xref href="GUID-1FFA0073-3D83-388E-A824-08C31F90CC54.dita#GUID-1FFA0073-3D83-388E-A824-08C31F90CC54/GUID-E961DA4D-AD38-31F0-88DD-A07D36346DCB"><apiname>TPointerEvent::AdvancedPointerEvent()</apiname></xref> on |
|
60 a <codeph>TPointerEvent</codeph> to return a pointer to a <xref href="GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023.dita"><apiname>TAdvancedPointerEvent</apiname></xref>. </p> <codeblock id="GUID-6E81680A-3070-546B-B575-49EA9E34FAF9" xml:space="preserve"> |
|
61 TZType aZType; |
|
62 TPointerEvent& aPointerEvent; |
|
63 TInt* aZ; |
|
64 TInt* aPoint3D; |
|
65 |
|
66 TAdvancedPointerEvent *advancedP = aPointerEvent.AdvancedPointerEvent(); |
|
67 </codeblock> <p> <codeph>TPointerEvent</codeph> is a struct that contains |
|
68 details of a pointer event. <codeph>TZType</codeph> is a struct provided by |
|
69 the programmer containing members to hold proximity, pressure, and "proximity |
|
70 and pressure" data. </p> </li> |
|
71 <li id="GUID-ABA8FA09-5F57-51BC-8CAE-43649B5ED6D3"><p>Now we need to test |
|
72 whether the pointer event contains advanced pointer data. If it is not an |
|
73 advanced pointer, the code leaves. </p> <p>If it is an advanced pointer, we |
|
74 call functions to detect proximity, pressure, "proximity and pressure" data |
|
75 and coordinates. </p> <codeblock id="GUID-DF109643-2564-51A0-B0F6-33BF4DA1F6E3" xml:space="preserve"> |
|
76 if(!advancedP) |
|
77 { |
|
78 // The TPointerEvent isn't an instance of TAdvancedPointerEvent |
|
79 User::Leave(KErrArgument); |
|
80 } |
|
81 |
|
82 switch(aZType) |
|
83 { |
|
84 case EZTypeProximity: |
|
85 aZ = advancedP->Proximity(); |
|
86 aPoint3D = advancedP->Proximity3D(); |
|
87 break; |
|
88 case EZTypePressure: |
|
89 aZ = advancedP->Pressure(); |
|
90 aPoint3D = advancedP->Pressure3D(); |
|
91 break; |
|
92 case EZTypeProximityAndPressure: |
|
93 aZ = advancedP->ProximityAndPressure(); |
|
94 aPoint3D = advancedP->ProximityAndPressure3D(); |
|
95 break; |
|
96 default: |
|
97 User::Leave(KErrArgument); |
|
98 break; |
|
99 } |
|
100 </codeblock> <ul> |
|
101 <li id="GUID-40C01884-AC86-5882-935D-2EC2E27C9004"><p> <xref href="GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023.dita#GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023/GUID-0ED4B1CC-0655-3246-8645-AAC9E0C27298"><apiname>TAdvancedPointerEvent::Proximity()</apiname></xref> returns |
|
102 the proximity. </p> </li> |
|
103 <li id="GUID-16A9A86B-A837-5E43-BB3A-F5A04A7F4552"><p> <xref href="GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023.dita#GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023/GUID-15DEBFBF-7B7D-3FCF-9929-C973824A5FD3"><apiname>TAdvancedPointerEvent::Pressure()</apiname></xref> returns |
|
104 the pressure. </p> </li> |
|
105 <li id="GUID-3E614890-C317-596E-A5B9-FD76426DBD12"><p> <xref href="GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023.dita#GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023/GUID-114AE77E-D0BD-321E-BFCB-1388B35582EC"><apiname>TAdvancedPointerEvent::ProximityAndPressure()</apiname></xref> returns |
|
106 the proximity and pressure combined. </p> </li> |
|
107 <li id="GUID-6F62C0D1-FAE4-5F8F-B451-68ABA404A369"><p> <xref href="GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023.dita#GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023/GUID-E5AA7737-D217-3FDE-9E4D-AAA7F5D2C300"><apiname>TAdvancedPointerEvent:: |
|
108 Position3D()</apiname></xref> returns the proximity and the X, Y and Z coordinates. </p> </li> |
|
109 <li id="GUID-5AD1811D-BCBF-5A44-B6E7-EB71BF254BCA"><p> <xref href="GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023.dita#GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023/GUID-2F30A8F5-75BA-3FE3-84B7-3C772ED75857"><apiname>TAdvancedPointerEvent::Pressure3D()</apiname></xref> returns |
|
110 the pressure and the X and Y coordinates. </p> </li> |
|
111 </ul> <p>Proximity is <i>always</i> negative and pressure is <i>always</i> positive. |
|
112 Internally they are combined together as a Z coordinate. When Z > 0, the proximity |
|
113 is 0 and the Z value represents the pressure. When Z < 0, the pressure |
|
114 is 0 and the Z value represents the proximity. Some APIs use only a Z coordinate |
|
115 (such as the threshold getters and setters and <xref href="GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023.dita#GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023/GUID-114AE77E-D0BD-321E-BFCB-1388B35582EC"><apiname>TAdvancedPointerEvent::ProximityAndPressure()</apiname></xref>). |
|
116 In these, the Z coordinate is interpreted in terms of pressure and proximity. </p> </li> |
|
117 </ol> <fig id="GUID-7A49B143-5458-5916-B937-55D98B77BB2C"> |
|
118 <title> Relationships between the pointer proximity, pressure and Z |
|
119 coordinate </title> |
|
120 <image href="GUID-1A0FB98B-8DB3-5067-9B71-FF838F6AE402_d0e216655_href.png" placement="inline"/> |
|
121 </fig> </section> |
|
122 <section id="GUID-B7057F69-191F-5AA4-8C61-EBECE66D92F6"><title>Pinch zooming</title> <p>This |
|
123 example shows an easy way to pinch zoom an image when the screen receives |
|
124 pointer events from two pointers. There are two functions in this code that |
|
125 must be implemented by the programmer: <codeph>BitmapCoordinates()</codeph> and <codeph>MoveBitmap()</codeph>. |
|
126 They are not included in the example because they involve complex calculations |
|
127 that are not related to advanced pointers. </p> <p>The high-level steps to |
|
128 perform pinch zooming are: </p> <ol id="GUID-AEF3917C-AAFE-5C25-9609-396D08478AC0"> |
|
129 <li id="GUID-7839E665-C4E1-59C8-BA89-22A62615EFA3"><p>Define the coordinates, |
|
130 equivalent to the given on-screen coordinates. In the code example, this is |
|
131 done using the function <codeph>BitmapCoordinates()</codeph>. </p> </li> |
|
132 <li id="GUID-FC4B1BDA-8120-53C9-9C88-BEFEF1AD54B4"><p>Define the ID of the |
|
133 pointer by using <xref href="GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023.dita#GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023/GUID-67593D7E-CE40-303F-B847-81D6FC0578B1"><apiname>TAdvancedPointerEvent::PointerNumber()</apiname></xref>. |
|
134 If the device can handle two pointers (two fingers) at the same time, their |
|
135 numbers are 0 and 1. The pointer number enables you to distinguish a given |
|
136 pointer from other pointers. </p> </li> |
|
137 <li id="GUID-1E8F7D23-EEAD-5EA5-8863-276076D6B54E"><p>For each pointer assign |
|
138 its coordinates to a local variable. We assume there are only two pointers |
|
139 handled by the system here. </p> </li> |
|
140 <li id="GUID-E44B3D9B-560A-5959-996D-A63CBD4C3786"><p>Use the <codeph>MoveBitmap()</codeph> function |
|
141 to achieve the zoom effect. </p> <codeblock id="GUID-D85CCFDD-8F65-530A-ACD7-93DD1D435FC6" xml:space="preserve"> |
|
142 /** |
|
143 Receives pointer events from two pointers to perform Pinch Zoom of the image. |
|
144 Function will finish when EButton1Up is received for any of the pointers. |
|
145 @param aPointer1 Coordinates of pointer number 1 when zoom is started |
|
146 @param aPointer2 Coordinates of pointer number 2 when zoom is started |
|
147 */ |
|
148 |
|
149 void PinchZoom(TPoint aPointer1, TPoint aPointer2) |
|
150 { |
|
151 TPoint actualP1 = aPointer1; |
|
152 TPoint actualP2 = aPointer2; |
|
153 |
|
154 // translate on-screen pointer coordinates to coordinates of displayed bitmap |
|
155 TPoint bitmapCatching1 = BitmapCoordinates(aPointer1); |
|
156 TPoint bitmapCatching2 = BitmapCoordinates(aPointer2); |
|
157 |
|
158 TBool repaint = EFalse; |
|
159 |
|
160 while (ETrue) |
|
161 { |
|
162 TAdvancedPointerEvent event = GetNextPointerEvent(); |
|
163 |
|
164 if (event.iType == TPointerEvent::EDrag) |
|
165 { |
|
166 if (event.PointerNumber() == 1) |
|
167 { |
|
168 actualP1 = event.iPosition; |
|
169 repaint = ETrue; |
|
170 } |
|
171 else if (event.PointerNumber() == 2) |
|
172 { |
|
173 actualP2 = event.iPosition; |
|
174 repaint = ETrue; |
|
175 } |
|
176 } |
|
177 else if (event.iType == TPointerEvent::EButton1Up) |
|
178 { |
|
179 break; |
|
180 } |
|
181 |
|
182 if (repaint) |
|
183 { |
|
184 // move bitmap on the screen in the way that |
|
185 // bitmapCatching1 point of the bitmap will be displayed at actualP1 screen coordinate, |
|
186 // bitmapCatching2 point of the bitmap will be displayed at actualP2 screen coordinate. |
|
187 MoveBitmap(bitmapCatching1, actualP1, bitmapCatching2, actualP2); |
|
188 repaint = EFalse; |
|
189 } |
|
190 } |
|
191 } |
|
192 </codeblock> </li> |
|
193 </ol> </section> |
|
194 </conbody><related-links> |
|
195 <link href="GUID-9C269F45-F160-5A4B-ABF8-896D2A538E3B.dita"><linktext>Advanced |
|
196 Pointer Overview</linktext></link> |
|
197 <link href="GUID-9AD75103-CD56-5279-B639-5CA2BBF979B5.dita"><linktext>Advanced |
|
198 Pointer States and Event Communication</linktext></link> |
|
199 </related-links></concept> |