|
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-9AD75103-CD56-5279-B639-5CA2BBF979B5" xml:lang="en"><title>Advanced |
|
13 Pointer States and Event Communication</title><shortdesc>The Window Server provides advanced pointer features, such as support |
|
14 for multiple pointers and proximity and pressure coordinates. This topic provides |
|
15 a summary of advanced pointer states and the events that communicate changes |
|
16 of their state. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
17 <p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target |
|
18 audience</b>: Application developers. </p> |
|
19 <p>This topic builds on the <xref href="GUID-9C269F45-F160-5A4B-ABF8-896D2A538E3B.dita">Advanced |
|
20 Pointer Overview</xref>. </p> |
|
21 <section><title>Communication between an input driver and the Window Server</title> <p>Figure |
|
22 1 below shows how an input driver communicates changes in pointer state to |
|
23 the Window Server. The diagram shows the logical pointer states and how <xref href="GUID-668CEA36-3933-3BBE-A980-CAB62617B4FD.dita"><apiname>TRawEvent</apiname></xref> types |
|
24 change those states. From the driver's perspective, the pointer can be in |
|
25 one of three basic logical states: <i>Up</i>, <i>Down</i> or <i>OutOfRange</i>. </p> <p>The |
|
26 driver sends a number of types of event to move the pointer between these |
|
27 states. For example, <xref href="GUID-0FD31DF6-3EA2-3EB3-8940-05F187B98B86.dita"><apiname>EButton1Up</apiname></xref> is an <i>Up</i> event that |
|
28 changes the pointer from the <i>Down</i> to the <i>Up</i> state. <xref href="GUID-2786B13B-B95C-3D15-B7D2-205E99A64FBC.dita"><apiname>EButton1Down</apiname></xref> is |
|
29 a <i>Down</i> event. <codeph>EButton1Down</codeph> changes the pointer from |
|
30 the <i>Up</i> to the <i>Down</i> state, and from <i>OutOfRange</i> to the <i>Down</i> state. </p> <p>There |
|
31 can be any number of pointers, and each pointer has a maximum of three buttons. |
|
32 A platform UI is free to implement buttons in any way. However, the Window |
|
33 Server interprets only Button1 as an <b>action</b> and does not interpret |
|
34 the other buttons. </p> <fig id="GUID-2664573F-C5E8-573F-9427-783074351585"> |
|
35 <title> Driver communicates pointer state changes to the Window Server |
|
36 </title> |
|
37 <image href="GUID-35521A99-3F1F-5EE1-8078-FFD8A298C0BD_d0e215295_href.png" placement="inline"/> |
|
38 </fig> <p>For a complete list of pointer states, the events that can be sent |
|
39 by the driver, and the associated events that the Window Server sends to the |
|
40 client, see the <xref href="GUID-9AD75103-CD56-5279-B639-5CA2BBF979B5.dita#GUID-9AD75103-CD56-5279-B639-5CA2BBF979B5/GUID-EC2B9C82-D678-5DFE-89A8-8CFCF5376244">Pointer |
|
41 states and event communication</xref> table below. </p> </section> |
|
42 <section id="GUID-3698CDAC-A904-5C44-BFD1-669D9673D02B"><title> Pointer states</title> <p>Pointing |
|
43 devices can be in one of the following basic states: </p> <table id="GUID-5255E70E-EF7C-5AA6-9F94-AF720B5B805F"> |
|
44 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
45 <thead> |
|
46 <row> |
|
47 <entry>State</entry> |
|
48 <entry>Description</entry> |
|
49 </row> |
|
50 </thead> |
|
51 <tbody> |
|
52 <row> |
|
53 <entry><p> <b>Out of range</b> </p> </entry> |
|
54 <entry><p>Not detected by the device's sensors. </p> </entry> |
|
55 </row> |
|
56 <row> |
|
57 <entry><p> <b>Up</b> </p> </entry> |
|
58 <entry><p>Detected by sensors, coordinates available, not performing an action. </p> </entry> |
|
59 </row> |
|
60 <row> |
|
61 <entry><p> <b>Down</b> </p> </entry> |
|
62 <entry><p>Detected by sensors, coordinates available, performing an action |
|
63 (as defined above). </p> </entry> |
|
64 </row> |
|
65 </tbody> |
|
66 </tgroup> |
|
67 </table> <p>Figure 2 shows the extension of the <i>Up</i> and <i>Down</i> states |
|
68 with additional substates. <i>Up</i> is extended with substates describing |
|
69 the <b>closeness</b> of the pointer to the screen. <i>Down</i> is extended |
|
70 with substates describing <b>pressing</b>. </p> <fig id="GUID-54DA3BEC-A650-5223-8E46-5B68F414A909"> |
|
71 <title> Extension of Up and Down states with substates </title> |
|
72 <image href="GUID-4E1D4E5D-7CE6-5A93-9170-BEF2937FC953_d0e215409_href.png" placement="inline"/> |
|
73 </fig> <p>The Window Server generates the following events for changes of |
|
74 closeness and pressing: </p> <ul> |
|
75 <li id="GUID-72265325-882B-5B38-ABE7-EFDF05758B97"><p> <codeph>EExitCloseProximity</codeph> </p> </li> |
|
76 <li id="GUID-D22BF039-8D17-53A4-83C1-3390EBDFBE46"><p> <codeph>EEnterCloseProximity</codeph> </p> </li> |
|
77 <li id="GUID-5968A499-B87B-54D2-9926-EF446ED1BCCD"><p> <codeph>EExitHighPressure</codeph> </p> </li> |
|
78 <li id="GUID-4FB8633D-29F1-5794-A922-65603035F23A"><p> <codeph>EEnterHighPressure</codeph> </p> </li> |
|
79 </ul> <p>These are all types of <xref href="GUID-1FFA0073-3D83-388E-A824-08C31F90CC54.dita"><apiname>TPointerEvent</apiname></xref>. Because |
|
80 these state changes depend on the pressure and proximity of the pointer, both |
|
81 of these values are checked each time a new <xref href="GUID-668CEA36-3933-3BBE-A980-CAB62617B4FD.dita"><apiname>TRawEvent</apiname></xref> concerning |
|
82 the pointer arrives from the driver. <xref href="GUID-668CEA36-3933-3BBE-A980-CAB62617B4FD.dita#GUID-668CEA36-3933-3BBE-A980-CAB62617B4FD/GUID-C7FB5C5F-B7E1-3738-B72D-1AD81699414F"><apiname>TRawEvent::EPointer3DOutOfRange</apiname></xref> means |
|
83 that the proximity is infinite and pressure is zero. </p> <p>These events |
|
84 are based on four thresholds: </p> <ul> |
|
85 <li id="GUID-6B27FB3B-EFFE-5D25-B039-FA84F0BFCE66"><p>The <codeph>EExitHighPressure</codeph> threshold |
|
86 (<codeph>EPointer3DExitHighPressureThreshold</codeph> in HAL) </p> <p>This |
|
87 is a threshold on the pointer's Z coordinate. In general, if the pointer crosses |
|
88 this threshold by decreasing pressure (thus decreasing its Z coordinate), |
|
89 the Window Server generates <xref href="GUID-1FFA0073-3D83-388E-A824-08C31F90CC54.dita#GUID-1FFA0073-3D83-388E-A824-08C31F90CC54/GUID-9062D892-DE16-3F74-AC0D-76A7F047B52B"><apiname>TPointerEvent::EExitHighPressure</apiname></xref> and |
|
90 sends it to the client. </p> </li> |
|
91 <li id="GUID-6F8E2E38-59A5-5FF3-B332-5D68252749B9"><p>The <codeph>EEnterHighPressure</codeph> threshold |
|
92 (<codeph>EPointer3DEnterHighPressureThreshold</codeph> in HAL) </p> <p>This |
|
93 is a threshold on the pointer's Z coordinate. In general, if the pointer crosses |
|
94 this threshold by increasing pressure (thus increasing its Z coordinate), |
|
95 the Window Server generates <xref href="GUID-1FFA0073-3D83-388E-A824-08C31F90CC54.dita#GUID-1FFA0073-3D83-388E-A824-08C31F90CC54/GUID-39963088-400D-3F0B-B7B1-36064CE92A67"><apiname>TPointerEvent::EEnterHighPressure</apiname></xref> and |
|
96 sends it to the client. </p> </li> |
|
97 <li id="GUID-CB32D252-B1CD-56D4-A5CF-88E99C2BCDD8"><p>The <codeph>EEnterCloseProximity</codeph> threshold |
|
98 (<codeph> EPointer3DEnterCloseProximityThreshold</codeph> in |
|
99 HAL) </p> <p>This is a threshold on the pointer's Z coordinate. In general, |
|
100 if the pointer crosses this threshold by decreasing its proximity from the |
|
101 device (thus increasing its Z coordinate), the Window Server generates <xref href="GUID-1FFA0073-3D83-388E-A824-08C31F90CC54.dita#GUID-1FFA0073-3D83-388E-A824-08C31F90CC54/GUID-7BDBA988-0D3A-35B2-A5AE-FFA56CC48D12"><apiname>TPointerEvent::EEnterCloseProximity</apiname></xref> and |
|
102 sends it to the client. </p> </li> |
|
103 <li id="GUID-C60E937A-E786-55CE-BEEC-655E78B6ED41"><p>The <codeph>EExitCloseProximity</codeph> threshold |
|
104 (<codeph>EPointer3DExitCloseProximityThreshold</codeph> in HAL) </p> <p>This |
|
105 is a threshold on the pointer's Z coordinate. In general, if the pointer crosses |
|
106 this threshold by increasing its proximity from the device (thus decreasing |
|
107 its Z coordinate), the Window Server generates <xref href="GUID-1FFA0073-3D83-388E-A824-08C31F90CC54.dita#GUID-1FFA0073-3D83-388E-A824-08C31F90CC54/GUID-C9226074-F285-3934-83C1-5533485FE6A6"><apiname>TPointerEvent::EExitCloseProximity</apiname></xref> and |
|
108 sends it to the client. </p> </li> |
|
109 </ul> <p>Applications can configure these thresholds at runtime by using Window |
|
110 Server APIs in <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>RWsSession</apiname></xref>. All applications can read these |
|
111 thresholds. However, only code with <codeph>WriteDeviceData</codeph> capability |
|
112 can change them because these changes should be made only by the device's |
|
113 configuration application. </p> </section> |
|
114 <section id="GUID-EC2B9C82-D678-5DFE-89A8-8CFCF5376244"><title>Pointer states |
|
115 and event communication</title> <p>The table below shows all possible pointer |
|
116 states. For each state it shows all of the events that can be sent by the |
|
117 driver and all of the events that are sent by the Window Server to the client. |
|
118 The end state of the pointer is also shown. There are five pointer zones (states) |
|
119 and four thresholds. An event is generated when the pointer's z position crosses |
|
120 a threshold. </p> <table id="GUID-630982B7-0367-558B-A1B0-B115EB7625A9"> |
|
121 <tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/> |
|
122 <thead> |
|
123 <row> |
|
124 <entry> Pointer state</entry> |
|
125 <entry> <codeph>TRawEvent</codeph> received from driver</entry> |
|
126 <entry> <codeph>TPointerEvent</codeph> sent by Window Server</entry> |
|
127 <entry>Resulting pointer state</entry> |
|
128 </row> |
|
129 </thead> |
|
130 <tbody> |
|
131 <row> |
|
132 <entry><p>OutOfRange </p> </entry> |
|
133 <entry><p> <codeph>EPointer3DOutOfRange</codeph> </p> </entry> |
|
134 <entry><p>— </p> </entry> |
|
135 <entry><p> <codeph>EOutOfRange</codeph> </p> </entry> |
|
136 </row> |
|
137 <row> |
|
138 <entry><p>OutOfRange </p> </entry> |
|
139 <entry><p> <codeph>EMove</codeph> (Z < <codeph>EEnterCloseProximity</codeph> threshold) </p> </entry> |
|
140 <entry><p> <codeph>EMove</codeph> </p> </entry> |
|
141 <entry><p>Up/OutOfCloseProximity </p> </entry> |
|
142 </row> |
|
143 <row> |
|
144 <entry><p>OutOfRange </p> </entry> |
|
145 <entry><p> <codeph> EMove</codeph> (Z >= <codeph>EEnterCloseProximity</codeph> threshold) </p> </entry> |
|
146 <entry><p> <codeph>EEnterCloseProximity</codeph> </p> </entry> |
|
147 <entry><p>Up/InCloseProximity </p> </entry> |
|
148 </row> |
|
149 <row> |
|
150 <entry><p>OutOfRange </p> </entry> |
|
151 <entry><p> <codeph>EButton1Down</codeph> (Z < <codeph>EEnterHighPressure</codeph> threshold) </p> </entry> |
|
152 <entry><p> <codeph>EButton1Down</codeph> </p> </entry> |
|
153 <entry><p>Down/NotPressing </p> </entry> |
|
154 </row> |
|
155 <row> |
|
156 <entry><p>OutOfRange </p> </entry> |
|
157 <entry><p> <codeph> EButton1Down</codeph> (Z >= <codeph>EEnterHighPressure</codeph> threshold) </p> </entry> |
|
158 <entry><p> <codeph>EButton1Down</codeph>, <codeph>EEnterHighPressure</codeph> </p> </entry> |
|
159 <entry><p>Down/Pressing </p> </entry> |
|
160 </row> |
|
161 <row> |
|
162 <entry><p>Up/OutOfCloseProximity </p> </entry> |
|
163 <entry><p> <codeph>EPointer3DOutOfRange</codeph> </p> </entry> |
|
164 <entry><p> <codeph>EOutOfRange</codeph> </p> </entry> |
|
165 <entry><p>OutOfRange </p> </entry> |
|
166 </row> |
|
167 <row> |
|
168 <entry><p>Up/OutOfCloseProximity </p> </entry> |
|
169 <entry><p> <codeph>EMove</codeph> (Z < <codeph>EEnterCloseProximity</codeph> threshold) </p> </entry> |
|
170 <entry><p> <codeph>EMove</codeph> </p> </entry> |
|
171 <entry><p>Up/OutOfCloseProximity </p> </entry> |
|
172 </row> |
|
173 <row> |
|
174 <entry><p>Up/OutOfCloseProximity </p> </entry> |
|
175 <entry><p> <codeph>EMove</codeph> (Z >= <codeph>EEnterCloseProximity</codeph> threshold) </p> </entry> |
|
176 <entry><p> <codeph>EEnterCloseProximity</codeph> </p> </entry> |
|
177 <entry><p>Up/InCloseProximity </p> </entry> |
|
178 </row> |
|
179 <row> |
|
180 <entry><p>Up/OutOfCloseProximity </p> </entry> |
|
181 <entry><p> <codeph>EButton1Down</codeph> (Z < <codeph>EEnterHighPressure</codeph> threshold) </p> </entry> |
|
182 <entry><p> <codeph>EButton1Down</codeph> </p> </entry> |
|
183 <entry><p>Down/OutOfHighPressure </p> </entry> |
|
184 </row> |
|
185 <row> |
|
186 <entry><p>Up/OutOfCloseProximity </p> </entry> |
|
187 <entry><p> <codeph>EButton1Down</codeph> (Z >= <codeph>EEnterHighPressure</codeph> threshold) </p> </entry> |
|
188 <entry><p> <codeph>EButton1Down</codeph>, <codeph>EEnterHighPressure</codeph> </p> </entry> |
|
189 <entry><p>Down/InHighPressure </p> </entry> |
|
190 </row> |
|
191 <row> |
|
192 <entry><p>Up/InCloseProximity </p> </entry> |
|
193 <entry><p> <codeph>EPointer3DOutOfRange</codeph> </p> </entry> |
|
194 <entry><p> <codeph>EOutOfRange</codeph> </p> </entry> |
|
195 <entry><p>OutOfRange </p> </entry> |
|
196 </row> |
|
197 <row> |
|
198 <entry><p>Up/InCloseProximity </p> </entry> |
|
199 <entry><p> <codeph>EMove</codeph> (Z < <codeph>EExitCloseProximity</codeph> threshold) </p> </entry> |
|
200 <entry><p> <codeph>EExitCloseProximity</codeph> </p> </entry> |
|
201 <entry><p>Up/OutOfCloseProximity </p> </entry> |
|
202 </row> |
|
203 <row> |
|
204 <entry><p>Up/InCloseProximity </p> </entry> |
|
205 <entry><p> <codeph>EMove</codeph> (Z >= <codeph>EExitCloseProximity</codeph> threshold) </p> </entry> |
|
206 <entry><p> <codeph>EMove</codeph> </p> </entry> |
|
207 <entry><p>Up/InCloseProximity </p> </entry> |
|
208 </row> |
|
209 <row> |
|
210 <entry><p>Up/InCloseProximity </p> </entry> |
|
211 <entry><p> <codeph>EButton1Down</codeph> (Z < <codeph>EEnterHighPressure</codeph> threshold) </p> </entry> |
|
212 <entry><p> <codeph>EButton1Down</codeph> </p> </entry> |
|
213 <entry><p>Down/OutOfHighPressure </p> </entry> |
|
214 </row> |
|
215 <row> |
|
216 <entry><p>Up/InCloseProximity </p> </entry> |
|
217 <entry><p> <codeph>EButton1Down</codeph> (Z >= <codeph>EEnterHighPressure</codeph> threshold) </p> </entry> |
|
218 <entry><p> <codeph>EButton1Down</codeph>, <codeph>EEnterHighPressure</codeph> </p> </entry> |
|
219 <entry><p>Down/InHighPressure </p> </entry> |
|
220 </row> |
|
221 <row> |
|
222 <entry><p>Down/OutOfHighPressure </p> </entry> |
|
223 <entry><p> <codeph>EButton1Up</codeph> (Z < <codeph>EExitCloseProximity</codeph> threshold) </p> </entry> |
|
224 <entry><p> <codeph>EButton1Up</codeph>, <codeph>EExitCloseProximity</codeph> </p> </entry> |
|
225 <entry><p>Up/OutOfCloseProximity </p> </entry> |
|
226 </row> |
|
227 <row> |
|
228 <entry><p>Down/OutOfHighPressure </p> </entry> |
|
229 <entry><p> <codeph>EButton1Up</codeph> (Z >= <codeph>EExitCloseProximity</codeph> threshold) </p> </entry> |
|
230 <entry><p> <codeph>EButton1Up</codeph> </p> </entry> |
|
231 <entry><p>Up/InCloseProximity </p> </entry> |
|
232 </row> |
|
233 <row> |
|
234 <entry><p>Down/OutOfHighPressure </p> </entry> |
|
235 <entry><p> <codeph>EMove</codeph> (Z < <codeph>EEnterHighPressure</codeph> threshold) </p> </entry> |
|
236 <entry><p> <codeph>EDrag</codeph> </p> </entry> |
|
237 <entry><p>Down/OutOfHighPressure </p> </entry> |
|
238 </row> |
|
239 <row> |
|
240 <entry><p>Down/OutOfHighPressure </p> </entry> |
|
241 <entry><p> <codeph>EMove</codeph> (Z >= <codeph>EEnterHighPressure</codeph> threshold) </p> </entry> |
|
242 <entry><p> <codeph>EEnterHighPressure</codeph> </p> </entry> |
|
243 <entry><p>Down/InHighPressure </p> </entry> |
|
244 </row> |
|
245 <row> |
|
246 <entry><p>Down/InHighPressure </p> </entry> |
|
247 <entry><p> <codeph>EButton1Up</codeph> (Z < <codeph>EExitCloseProximity</codeph> threshold) </p> </entry> |
|
248 <entry><p> <codeph>EButton1Up</codeph>, <codeph>EExitCloseProximity</codeph> </p> </entry> |
|
249 <entry><p>Up/OutOfCloseProximity </p> </entry> |
|
250 </row> |
|
251 <row> |
|
252 <entry><p>Down/InHighPressure </p> </entry> |
|
253 <entry><p> <codeph>EButton1Up</codeph> (Z >= <codeph>EExitCloseProximity</codeph> threshold) </p> </entry> |
|
254 <entry><p> <codeph>EButton1Up</codeph> </p> </entry> |
|
255 <entry><p>Up/InCloseProximity </p> </entry> |
|
256 </row> |
|
257 <row> |
|
258 <entry><p>Down/InHighPressure </p> </entry> |
|
259 <entry><p> <codeph>EMove</codeph> (Z < <codeph>EExitHighPressure</codeph> threshold) </p> </entry> |
|
260 <entry><p> <codeph>EExitHighPressure</codeph> </p> </entry> |
|
261 <entry><p>Down/OutOfHighPressure </p> </entry> |
|
262 </row> |
|
263 <row> |
|
264 <entry><p>Down/InHighPressure </p> </entry> |
|
265 <entry><p> <codeph>EMove</codeph> (Z >= <codeph>EExitHighPressure</codeph> threshold) </p> </entry> |
|
266 <entry><p> <codeph>EDrag</codeph> </p> </entry> |
|
267 <entry><p>Down/InHighPressure </p> </entry> |
|
268 </row> |
|
269 </tbody> |
|
270 </tgroup> |
|
271 </table> <p>The driver is prohibited from sending <codeph>EPointer3DOutOfRange</codeph> when |
|
272 the pointer is in the Down state. Therefore this is not included in this table. |
|
273 Because <codeph>TRawEvent</codeph>'s <codeph>EPointer3DOutOfRange</codeph> events |
|
274 do not have coordinates, the Window Server makes sure the event is delivered |
|
275 to the place where the previous event for the same pointer occurred. It does |
|
276 this by maintaining the last state of the pointer. </p> <p>Figure 3 shows |
|
277 the events sent from the Window Server to the client while the pointer traverses |
|
278 the full cycle of events—from OutOfRange, through Down/InHighPressure and |
|
279 back to OutOfRange. This diagram does not show all of the possible state transitions |
|
280 that are described in the table above. </p> <fig id="GUID-C39B447C-0908-5F9A-95EC-2F97E56E2C20"> |
|
281 <title> Events sent from Window Server to client while the pointer traverses |
|
282 the full cycle of states. </title> |
|
283 <image href="GUID-8F4C626F-3490-50BC-A97F-FD1972FFF65B_d0e216360_href.png" placement="inline"/> |
|
284 </fig> </section> |
|
285 </conbody><related-links> |
|
286 <link href="GUID-9C269F45-F160-5A4B-ABF8-896D2A538E3B.dita"><linktext>Advanced |
|
287 Pointer Overview</linktext></link> |
|
288 <link href="GUID-C60DC070-572B-5960-B394-550426FDB909.dita"><linktext>Advanced |
|
289 Pointer Tutorial</linktext></link> |
|
290 </related-links></concept> |