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