Advanced +Pointer States and Event Communication

Variant: ScreenPlay. Target +audience: Application developers.

This topic builds on the Advanced +Pointer Overview.

Communication between an input driver and the Window Server

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 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.

+ 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.

+ + +

Detected by sensors, coordinates available, not performing an action.

+ + +

Down

Detected by sensors, coordinates available, performing an action +(as defined above).

+ + + +

Figure 2 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.

+ 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.

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.

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