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.