<?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><title>Communication between an input driver and the Window Server</title> <p>Figure

1 below 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_d0e215295_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>Figure 2 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_d0e215409_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>Figure 3 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_d0e216360_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>