Advanced -Pointer States and Event Communication

Advanced -Pointer States and Event CommunicationThe 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.

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

- - - -

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.

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

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

-Advanced -Pointer Overview -Advanced -Pointer Tutorial + + + + + +Advanced +Pointer States and Event CommunicationThe 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.

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

+ + + +

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.

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

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

+Advanced +Pointer Overview +Advanced +Pointer Tutorial

\ No newline at end of file