Collapse all Symbian^3 Application Developer Library

Advanced Pointer States and Event Communication

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.

Variant : ScreenPlay . Target audience : Application developers.

This topic builds on the Advanced Pointer Overview .

Communication between an input driver and the Window Server

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 TRawEvent types change those states. From the driver's perspective, the pointer can be in one of three basic logical states: Up , Down or OutOfRange .

The driver sends a number of types of event to move the pointer between these states. For example, EButton1Up is an Up event that changes the pointer from the Down to the Up state. EButton1Down is a Down event. EButton1Down changes the pointer from the Up to the Down state, and from OutOfRange to the Down state.

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 action and does not interpret the other buttons.

Figure 1. Driver communicates pointer state changes to the Window Server

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 Pointer states and event communication table below.

Pointer states

Pointing devices can be in one of the following basic states:

State	Description
Out of range	Not detected by the device's sensors.
Up	Detected by sensors, coordinates available, not performing an action.
Down	Detected by sensors, coordinates available, performing an action (as defined above).

The following diagram shows the extension of the Up and Down states with additional substates. Up is extended with substates describing the closeness of the pointer to the screen. Down is extended with substates describing pressing .

Figure 2. Extension of Up and Down states with substates

The Window Server generates the following events for changes of closeness and pressing:

EExitCloseProximity
EEnterCloseProximity
EExitHighPressure
EEnterHighPressure

These are all types of TPointerEvent . Because these state changes depend on the pressure and proximity of the pointer, both of these values are checked each time a new TRawEvent concerning the pointer arrives from the driver. TRawEvent::EPointer3DOutOfRange means that the proximity is infinite and pressure is zero.

These events are based on four thresholds:

The EExitHighPressure threshold ( EPointer3DExitHighPressureThreshold in HAL)

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 TPointerEvent::EExitHighPressure and sends it to the client.
The EEnterHighPressure threshold ( EPointer3DEnterHighPressureThreshold in HAL)

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 TPointerEvent::EEnterHighPressure and sends it to the client.
The EEnterCloseProximity threshold ( EPointer3DEnterCloseProximityThreshold in HAL)

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 TPointerEvent::EEnterCloseProximity and sends it to the client.
The EExitCloseProximity threshold ( EPointer3DExitCloseProximityThreshold in HAL)

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 TPointerEvent::EExitCloseProximity and sends it to the client.

Applications can configure these thresholds at runtime by using Window Server APIs in RWsSession . All applications can read these thresholds. However, only code with WriteDeviceData capability can change them because these changes should be made only by the device's configuration application.

Pointer states and event communication

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.

Pointer state	`TRawEvent` received from driver	`TPointerEvent` sent by Window Server	Resulting pointer state
OutOfRange	`EPointer3DOutOfRange`	—	`EOutOfRange`
OutOfRange	`EMove` (Z < `EEnterCloseProximity` threshold)	`EMove`	Up/OutOfCloseProximity
OutOfRange	`EMove` (Z >= `EEnterCloseProximity` threshold)	`EEnterCloseProximity`	Up/InCloseProximity
OutOfRange	`EButton1Down` (Z < `EEnterHighPressure` threshold)	`EButton1Down`	Down/NotPressing
OutOfRange	`EButton1Down` (Z >= `EEnterHighPressure` threshold)	`EButton1Down` , `EEnterHighPressure`	Down/Pressing
Up/OutOfCloseProximity	`EPointer3DOutOfRange`	`EOutOfRange`	OutOfRange
Up/OutOfCloseProximity	`EMove` (Z < `EEnterCloseProximity` threshold)	`EMove`	Up/OutOfCloseProximity
Up/OutOfCloseProximity	`EMove` (Z >= `EEnterCloseProximity` threshold)	`EEnterCloseProximity`	Up/InCloseProximity
Up/OutOfCloseProximity	`EButton1Down` (Z < `EEnterHighPressure` threshold)	`EButton1Down`	Down/OutOfHighPressure
Up/OutOfCloseProximity	`EButton1Down` (Z >= `EEnterHighPressure` threshold)	`EButton1Down` , `EEnterHighPressure`	Down/InHighPressure
Up/InCloseProximity	`EPointer3DOutOfRange`	`EOutOfRange`	OutOfRange
Up/InCloseProximity	`EMove` (Z < `EExitCloseProximity` threshold)	`EExitCloseProximity`	Up/OutOfCloseProximity
Up/InCloseProximity	`EMove` (Z >= `EExitCloseProximity` threshold)	`EMove`	Up/InCloseProximity
Up/InCloseProximity	`EButton1Down` (Z < `EEnterHighPressure` threshold)	`EButton1Down`	Down/OutOfHighPressure
Up/InCloseProximity	`EButton1Down` (Z >= `EEnterHighPressure` threshold)	`EButton1Down` , `EEnterHighPressure`	Down/InHighPressure
Down/OutOfHighPressure	`EButton1Up` (Z < `EExitCloseProximity` threshold)	`EButton1Up` , `EExitCloseProximity`	Up/OutOfCloseProximity
Down/OutOfHighPressure	`EButton1Up` (Z >= `EExitCloseProximity` threshold)	`EButton1Up`	Up/InCloseProximity
Down/OutOfHighPressure	`EMove` (Z < `EEnterHighPressure` threshold)	`EDrag`	Down/OutOfHighPressure
Down/OutOfHighPressure	`EMove` (Z >= `EEnterHighPressure` threshold)	`EEnterHighPressure`	Down/InHighPressure
Down/InHighPressure	`EButton1Up` (Z < `EExitCloseProximity` threshold)	`EButton1Up` , `EExitCloseProximity`	Up/OutOfCloseProximity
Down/InHighPressure	`EButton1Up` (Z >= `EExitCloseProximity` threshold)	`EButton1Up`	Up/InCloseProximity
Down/InHighPressure	`EMove` (Z < `EExitHighPressure` threshold)	`EExitHighPressure`	Down/OutOfHighPressure
Down/InHighPressure	`EMove` (Z >= `EExitHighPressure` threshold)	`EDrag`	Down/InHighPressure

The driver is prohibited from sending EPointer3DOutOfRange when the pointer is in the Down state. Therefore this is not included in this table. Because TRawEvent 's EPointer3DOutOfRange 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.

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.

Figure 3. Events sent from Window Server to client while the pointer traverses the full cycle of states.

Parent topic: Advanced Pointers

Related concepts

Advanced Pointer Overview

Advanced Pointer Tutorial