Collapse all Symbian^3 Application Developer Library

Support for Multiple Pointers in the Emulator Overview

This topic provides an overview of support for multiple pointers in the emulator. Two mice are used to provide two independent pointer positions. The emulator responds to the mice’s individual button-clicks, moves, and mouse wheel scrolls as if two human fingers are moving, touching or hovering over the screen.

The emulator can be extended to support more than two mice or other pointer devices.

Variant : ScreenPlay . Target audience : Application developers.

The following figure shows two Windows pointers on the emulator screen, each representing a mouse device. The ordinal integer (starting from 0) beside each pointer is the unique device identifier. The position of each mouse on the screen is represented by the X and Y coordinates. The pressure (a positive value) and proximity (a negative value) information captured by the mouse wheel is represented by the Z coordinate. Notice that the status bar shows the identifier and the dynamic X, Y and Z values of each pointer.

Figure 1. Two pointers are displayed in the emulator

The delivery of pointer events from the emulator driver to the Window Server is the same when there are multiple pointers as in the single pointer environment. This means the raw events for a mouse move, button click and mouse wheel movement are delivered to the Window Server as usual. Each mouse has a unique device identifier, which makes it possible to ascertain which mouse the events relate to. The raw events for each individual mouse include the following:

TRawEvent::EPointerMove indicates a mouse move or a mouse wheel movement event.
TRawEvent::EButton1Down indicates that the left mouse button is pressed down.
TRawEvent::EButton1Up indicates that the left mouse button is released.
TRawEvent::EPointerOutOfRange indicates that the proximity of a mouse is out of range. This means that the Z coordinate value of the mouse has reached HALData::EPointer3DMaxProximity .

Pressure and proximity emulation

The Z coordinate value is used to represent the pressure and proximity to the screen. In the emulator, the Z value is captured and tuned by the mouse wheel movement.

Z < 0 indicates the proximity of the device from the screen.
Z > 0 indicates pressure.

See Advanced Pointer Overview for more information about pressure and proximity.

The mouse wheel combines the features of a wheel and a mouse button. The wheel has discrete, evenly spaced notches. Rotating the wheel backwards or forwards has the effect of changing the pressure or proximity.

When the mouse wheel is rotated, a device-specific message is sent to the emulator window that has focus as each notch is encountered.
The Z coordinate is initiated as 0. Then when the wheel is moved forward, the Z value enters the pressure range and increases by one pressure step. When the wheel is moved backward, the Z value enters the proximity range and decreases by one proximity step.

The pressure or proximity step can be customized in the epoc.ini file. See Enabling Multiple Pointers in the Emulator Tutorial for more information.
When the Z value is in the pressure range (Z > 0), moving the wheel forward by one notch increases Z by one pressure step. Moving the wheel backward by one notch decreases Z by one pressure step, until Z returns to 0.
When the Z value is in the proximity range (Z < 0), moving the wheel backward by one notch decreases Z by one proximity step. Moving the wheel forward by one notch increases Z by one proximity step, until Z returns to 0.
There are limits to the values of the Z coordinate. This means that the Symbian emulator does not allow Z to exceed the upper boundary HALData::EPointer3DMaxPressure (a positive value) and lower boundary HALData::EPointer3DMaxProximity (a negative value). If Z is at the lower boundary, when the mouse wheel is moved backward next time, Z does not change. A new Out of Range pointer event is generated and sent to the Window Server. Similarly when Z is at the upper boundary, Z does not change when the mouse wheel is moved forward.
When the mouse button down or up event ( TRawEvent::EButton1Down or TRawEvent::EButton1Up ) is generated, Z is reset to 0.

Parent topic: Support for Multiple Pointers in the Emulator

Related concepts

Advanced Pointers

Enabling Multiple Pointers in the Emulator Tutorial