<?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-9AD75103-CD56-5279-B639-5CA2BBF979B5" xml:lang="en"><title>Advanced
Pointer States and Event Communication</title><shortdesc>The Window Server provides advanced pointer features, such as support
for multiple pointers and proximity and pressure coordinates. This topic provides
a summary of advanced pointer states and the events that communicate changes
of their state. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target
audience</b>: Application developers. </p>
<p>This topic builds on the <xref href="GUID-9C269F45-F160-5A4B-ABF8-896D2A538E3B.dita">Advanced
Pointer Overview</xref>. </p>
<section id="GUID-4B7318D7-29AB-4DE4-B37A-2AFAE055982E"><title>Communication
between an input driver and the Window Server</title> <p>The following diagram
shows how an input driver communicates changes in pointer state to 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
change those states. From the driver's perspective, the pointer can be in
one of three basic logical states: <i>Up</i>, <i>Down</i> or <i>OutOfRange</i>. </p> <p>The
driver sends a number of types of event to move the pointer between these
states. For example, <xref href="GUID-0FD31DF6-3EA2-3EB3-8940-05F187B98B86.dita"><apiname>EButton1Up</apiname></xref> is an <i>Up</i> event that
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
a <i>Down</i> event. <codeph>EButton1Down</codeph> changes the pointer from
the <i>Up</i> to the <i>Down</i> state, and from <i>OutOfRange</i> to the <i>Down</i> state. </p> <p>There
can be any number of pointers, and each pointer has a maximum of three buttons.
A platform UI is free to implement buttons in any way. However, the Window
Server interprets only Button1 as an <b>action</b> and does not interpret
the other buttons. </p> <fig id="GUID-2664573F-C5E8-573F-9427-783074351585">
<title> Driver communicates pointer state changes to the Window Server   
        </title>
<image href="GUID-35521A99-3F1F-5EE1-8078-FFD8A298C0BD_d0e192564_href.png" placement="inline"/>
</fig> <p>For a complete list of pointer states, the events that can be sent
by the driver, and the associated events that the Window Server sends to the
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
states and event communication</xref> table below. </p> </section>
<section id="GUID-3698CDAC-A904-5C44-BFD1-669D9673D02B"><title> Pointer states</title> <p>Pointing
devices can be in one of the following basic states: </p> <table id="GUID-5255E70E-EF7C-5AA6-9F94-AF720B5B805F">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<thead>
<row>
<entry>State</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><p> <b>Out of range</b>  </p> </entry>
<entry><p>Not detected by the device's sensors. </p> </entry>
</row>
<row>
<entry><p> <b>Up</b>  </p> </entry>
<entry><p>Detected by sensors, coordinates available, not performing an action. </p> </entry>
</row>
<row>
<entry><p> <b>Down</b>  </p> </entry>
<entry><p>Detected by sensors, coordinates available, performing an action
(as defined above). </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p>The following diagram shows the extension of the <i>Up</i> and <i>Down</i> states
with additional substates. <i>Up</i> is extended with substates describing
the <b>closeness</b> of the pointer to the screen. <i>Down</i> is extended
with substates describing <b>pressing</b>. </p> <fig id="GUID-54DA3BEC-A650-5223-8E46-5B68F414A909">
<title> Extension of Up and Down states with substates            </title>
<image href="GUID-4E1D4E5D-7CE6-5A93-9170-BEF2937FC953_d0e192678_href.png" placement="inline"/>
</fig> <p>The Window Server generates the following events for changes of
closeness and pressing: </p> <ul>
<li id="GUID-72265325-882B-5B38-ABE7-EFDF05758B97"><p> <codeph>EExitCloseProximity</codeph>  </p> </li>
<li id="GUID-D22BF039-8D17-53A4-83C1-3390EBDFBE46"><p> <codeph>EEnterCloseProximity</codeph>  </p> </li>
<li id="GUID-5968A499-B87B-54D2-9926-EF446ED1BCCD"><p> <codeph>EExitHighPressure</codeph>  </p> </li>
<li id="GUID-4FB8633D-29F1-5794-A922-65603035F23A"><p> <codeph>EEnterHighPressure</codeph>  </p> </li>
</ul> <p>These are all types of <xref href="GUID-1FFA0073-3D83-388E-A824-08C31F90CC54.dita"><apiname>TPointerEvent</apiname></xref>. Because
these state changes depend on the pressure and proximity of the pointer, both
of these values are checked each time a new <xref href="GUID-668CEA36-3933-3BBE-A980-CAB62617B4FD.dita"><apiname>TRawEvent</apiname></xref> concerning
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
that the proximity is infinite and pressure is zero. </p> <p>These events
are based on four thresholds: </p> <ul>
<li id="GUID-6B27FB3B-EFFE-5D25-B039-FA84F0BFCE66"><p>The <codeph>EExitHighPressure</codeph> threshold
(<codeph>EPointer3DExitHighPressureThreshold</codeph> in HAL) </p> <p>This
is a threshold on the pointer's Z coordinate. In general, if the pointer crosses
this threshold by decreasing pressure (thus decreasing its Z coordinate),
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
sends it to the client. </p> </li>
<li id="GUID-6F8E2E38-59A5-5FF3-B332-5D68252749B9"><p>The <codeph>EEnterHighPressure</codeph> threshold
(<codeph>EPointer3DEnterHighPressureThreshold</codeph> in HAL) </p> <p>This
is a threshold on the pointer's Z coordinate. In general, if the pointer crosses
this threshold by increasing pressure (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-39963088-400D-3F0B-B7B1-36064CE92A67"><apiname>TPointerEvent::EEnterHighPressure</apiname></xref> and
sends it to the client. </p> </li>
<li id="GUID-CB32D252-B1CD-56D4-A5CF-88E99C2BCDD8"><p>The <codeph>EEnterCloseProximity</codeph> threshold
(<codeph>                 EPointer3DEnterCloseProximityThreshold</codeph> in
HAL) </p> <p>This is a threshold on the pointer's Z coordinate. In general,
if the pointer crosses this threshold by decreasing its proximity from the
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
sends it to the client. </p> </li>
<li id="GUID-C60E937A-E786-55CE-BEEC-655E78B6ED41"><p>The <codeph>EExitCloseProximity</codeph> threshold
(<codeph>EPointer3DExitCloseProximityThreshold</codeph> in HAL) </p> <p>This
is a threshold on the pointer's Z coordinate. In general, if the pointer crosses
this threshold by increasing its proximity from the device (thus decreasing
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
sends it to the client. </p> </li>
</ul> <p>Applications can configure these thresholds at runtime by using Window
Server APIs in <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>RWsSession</apiname></xref>. All applications can read these
thresholds. However, only code with <codeph>WriteDeviceData</codeph> capability
can change them because these changes should be made only by the device's
configuration application. </p> </section>
<section id="GUID-EC2B9C82-D678-5DFE-89A8-8CFCF5376244"><title>Pointer states
and event communication</title> <p>The table below shows all possible pointer
states. For each state it shows all of the events that can be sent by the
driver and all of the events that are sent by the Window Server to the client.
The end state of the pointer is also shown. There are five pointer zones (states)
and four thresholds. An event is generated when the pointer's z position crosses
a threshold. </p> <table id="GUID-630982B7-0367-558B-A1B0-B115EB7625A9">
<tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/>
<thead>
<row>
<entry> Pointer state</entry>
<entry>  <codeph>TRawEvent</codeph> received from driver</entry>
<entry>  <codeph>TPointerEvent</codeph> sent by Window Server</entry>
<entry>Resulting pointer state</entry>
</row>
</thead>
<tbody>
<row>
<entry><p>OutOfRange </p> </entry>
<entry><p> <codeph>EPointer3DOutOfRange</codeph>  </p> </entry>
<entry><p>— </p> </entry>
<entry><p> <codeph>EOutOfRange</codeph>  </p> </entry>
</row>
<row>
<entry><p>OutOfRange </p> </entry>
<entry><p> <codeph>EMove</codeph> (Z &lt; <codeph>EEnterCloseProximity</codeph> threshold) </p> </entry>
<entry><p> <codeph>EMove</codeph>  </p> </entry>
<entry><p>Up/OutOfCloseProximity </p> </entry>
</row>
<row>
<entry><p>OutOfRange </p> </entry>
<entry><p> <codeph> EMove</codeph> (Z &gt;= <codeph>EEnterCloseProximity</codeph> threshold) </p> </entry>
<entry><p> <codeph>EEnterCloseProximity</codeph>  </p> </entry>
<entry><p>Up/InCloseProximity </p> </entry>
</row>
<row>
<entry><p>OutOfRange </p> </entry>
<entry><p> <codeph>EButton1Down</codeph> (Z &lt; <codeph>EEnterHighPressure</codeph> threshold) </p> </entry>
<entry><p> <codeph>EButton1Down</codeph>  </p> </entry>
<entry><p>Down/NotPressing </p> </entry>
</row>
<row>
<entry><p>OutOfRange </p> </entry>
<entry><p> <codeph> EButton1Down</codeph> (Z &gt;= <codeph>EEnterHighPressure</codeph> threshold) </p> </entry>
<entry><p> <codeph>EButton1Down</codeph>, <codeph>EEnterHighPressure</codeph>  </p> </entry>
<entry><p>Down/Pressing </p> </entry>
</row>
<row>
<entry><p>Up/OutOfCloseProximity </p> </entry>
<entry><p> <codeph>EPointer3DOutOfRange</codeph>  </p> </entry>
<entry><p> <codeph>EOutOfRange</codeph>  </p> </entry>
<entry><p>OutOfRange </p> </entry>
</row>
<row>
<entry><p>Up/OutOfCloseProximity </p> </entry>
<entry><p> <codeph>EMove</codeph> (Z &lt; <codeph>EEnterCloseProximity</codeph> threshold) </p> </entry>
<entry><p> <codeph>EMove</codeph>  </p> </entry>
<entry><p>Up/OutOfCloseProximity </p> </entry>
</row>
<row>
<entry><p>Up/OutOfCloseProximity </p> </entry>
<entry><p> <codeph>EMove</codeph> (Z &gt;= <codeph>EEnterCloseProximity</codeph> threshold) </p> </entry>
<entry><p> <codeph>EEnterCloseProximity</codeph>  </p> </entry>
<entry><p>Up/InCloseProximity </p> </entry>
</row>
<row>
<entry><p>Up/OutOfCloseProximity </p> </entry>
<entry><p> <codeph>EButton1Down</codeph> (Z &lt; <codeph>EEnterHighPressure</codeph> threshold) </p> </entry>
<entry><p> <codeph>EButton1Down</codeph>  </p> </entry>
<entry><p>Down/OutOfHighPressure </p> </entry>
</row>
<row>
<entry><p>Up/OutOfCloseProximity </p> </entry>
<entry><p> <codeph>EButton1Down</codeph> (Z &gt;= <codeph>EEnterHighPressure</codeph> threshold) </p> </entry>
<entry><p> <codeph>EButton1Down</codeph>, <codeph>EEnterHighPressure</codeph>  </p> </entry>
<entry><p>Down/InHighPressure </p> </entry>
</row>
<row>
<entry><p>Up/InCloseProximity </p> </entry>
<entry><p> <codeph>EPointer3DOutOfRange</codeph>  </p> </entry>
<entry><p> <codeph>EOutOfRange</codeph>  </p> </entry>
<entry><p>OutOfRange </p> </entry>
</row>
<row>
<entry><p>Up/InCloseProximity </p> </entry>
<entry><p> <codeph>EMove</codeph> (Z &lt; <codeph>EExitCloseProximity</codeph> threshold) </p> </entry>
<entry><p> <codeph>EExitCloseProximity</codeph>  </p> </entry>
<entry><p>Up/OutOfCloseProximity </p> </entry>
</row>
<row>
<entry><p>Up/InCloseProximity </p> </entry>
<entry><p> <codeph>EMove</codeph> (Z &gt;= <codeph>EExitCloseProximity</codeph> threshold) </p> </entry>
<entry><p> <codeph>EMove</codeph>  </p> </entry>
<entry><p>Up/InCloseProximity </p> </entry>
</row>
<row>
<entry><p>Up/InCloseProximity </p> </entry>
<entry><p> <codeph>EButton1Down</codeph> (Z &lt; <codeph>EEnterHighPressure</codeph> threshold) </p> </entry>
<entry><p> <codeph>EButton1Down</codeph>  </p> </entry>
<entry><p>Down/OutOfHighPressure </p> </entry>
</row>
<row>
<entry><p>Up/InCloseProximity </p> </entry>
<entry><p> <codeph>EButton1Down</codeph> (Z &gt;= <codeph>EEnterHighPressure</codeph> threshold) </p> </entry>
<entry><p> <codeph>EButton1Down</codeph>, <codeph>EEnterHighPressure</codeph>  </p> </entry>
<entry><p>Down/InHighPressure </p> </entry>
</row>
<row>
<entry><p>Down/OutOfHighPressure </p> </entry>
<entry><p> <codeph>EButton1Up</codeph> (Z &lt; <codeph>EExitCloseProximity</codeph> threshold) </p> </entry>
<entry><p> <codeph>EButton1Up</codeph>, <codeph>EExitCloseProximity</codeph>  </p> </entry>
<entry><p>Up/OutOfCloseProximity </p> </entry>
</row>
<row>
<entry><p>Down/OutOfHighPressure </p> </entry>
<entry><p> <codeph>EButton1Up</codeph> (Z &gt;= <codeph>EExitCloseProximity</codeph> threshold) </p> </entry>
<entry><p> <codeph>EButton1Up</codeph>  </p> </entry>
<entry><p>Up/InCloseProximity </p> </entry>
</row>
<row>
<entry><p>Down/OutOfHighPressure </p> </entry>
<entry><p> <codeph>EMove</codeph> (Z &lt; <codeph>EEnterHighPressure</codeph> threshold) </p> </entry>
<entry><p> <codeph>EDrag</codeph>  </p> </entry>
<entry><p>Down/OutOfHighPressure </p> </entry>
</row>
<row>
<entry><p>Down/OutOfHighPressure </p> </entry>
<entry><p> <codeph>EMove</codeph> (Z &gt;= <codeph>EEnterHighPressure</codeph> threshold) </p> </entry>
<entry><p> <codeph>EEnterHighPressure</codeph>  </p> </entry>
<entry><p>Down/InHighPressure </p> </entry>
</row>
<row>
<entry><p>Down/InHighPressure </p> </entry>
<entry><p> <codeph>EButton1Up</codeph> (Z &lt; <codeph>EExitCloseProximity</codeph> threshold) </p> </entry>
<entry><p> <codeph>EButton1Up</codeph>, <codeph>EExitCloseProximity</codeph>  </p> </entry>
<entry><p>Up/OutOfCloseProximity </p> </entry>
</row>
<row>
<entry><p>Down/InHighPressure </p> </entry>
<entry><p> <codeph>EButton1Up</codeph> (Z &gt;= <codeph>EExitCloseProximity</codeph> threshold) </p> </entry>
<entry><p> <codeph>EButton1Up</codeph>  </p> </entry>
<entry><p>Up/InCloseProximity </p> </entry>
</row>
<row>
<entry><p>Down/InHighPressure </p> </entry>
<entry><p> <codeph>EMove</codeph> (Z &lt; <codeph>EExitHighPressure</codeph> threshold) </p> </entry>
<entry><p> <codeph>EExitHighPressure</codeph>  </p> </entry>
<entry><p>Down/OutOfHighPressure </p> </entry>
</row>
<row>
<entry><p>Down/InHighPressure </p> </entry>
<entry><p> <codeph>EMove</codeph> (Z &gt;= <codeph>EExitHighPressure</codeph> threshold) </p> </entry>
<entry><p> <codeph>EDrag</codeph>  </p> </entry>
<entry><p>Down/InHighPressure </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p>The driver is prohibited from sending <codeph>EPointer3DOutOfRange</codeph> when
the pointer is in the Down state. Therefore this is not included in this table.
Because <codeph>TRawEvent</codeph>'s <codeph>EPointer3DOutOfRange</codeph> events
do not have coordinates, the Window Server makes sure the event is delivered
to the place where the previous event for the same pointer occurred. It does
this by maintaining the last state of the pointer. </p> <p>The following diagram
shows the events sent from the Window Server to the client while
the pointer traverses the full cycle of events—from OutOfRange, through Down/InHighPressure
and back to OutOfRange. This diagram does not show all of the possible state
transitions that are described in the table above. </p> <fig id="GUID-C39B447C-0908-5F9A-95EC-2F97E56E2C20">
<title> Events sent from Window Server to client while the pointer traverses
the full cycle of states.            </title>
<image href="GUID-8F4C626F-3490-50BC-A97F-FD1972FFF65B_d0e193631_href.png" placement="inline"/>
</fig> </section>
</conbody><related-links>
<link href="GUID-9C269F45-F160-5A4B-ABF8-896D2A538E3B.dita"><linktext>Advanced
Pointer Overview</linktext></link>
<link href="GUID-C60DC070-572B-5960-B394-550426FDB909.dita"><linktext>Advanced
Pointer Tutorial</linktext></link>
</related-links></concept>