--- a/Symbian3/SDK/Source/GUID-9AD75103-CD56-5279-B639-5CA2BBF979B5.dita Wed Mar 31 11:11:55 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-9AD75103-CD56-5279-B639-5CA2BBF979B5.dita Fri Jun 11 12:39:03 2010 +0100
@@ -1,291 +1,291 @@
-<?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_d0e197572_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_d0e197686_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 < <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 >= <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 < <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 >= <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 < <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 >= <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 < <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 >= <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 < <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 >= <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 < <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 >= <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 < <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 >= <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 < <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 >= <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 < <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 >= <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 < <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 >= <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_d0e198639_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>
+<?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 < <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 >= <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 < <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 >= <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 < <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 >= <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 < <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 >= <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 < <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 >= <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 < <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 >= <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 < <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 >= <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 < <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 >= <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 < <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 >= <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 < <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 >= <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>
\ No newline at end of file