<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-9126A296-0301-4077-A183-3D703F77C548" xml:lang="en"><title>Support for Multiple Pointers in the Emulator Overview</title><shortdesc>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.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The emulator can be extended to support more than two mice or other

pointer devices.</p>

<p><b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target audience</b>: Application developers. </p>

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

<fig id="GUID-03428614-06B1-4821-A284-C3B6DB8E053C">

<title>Two pointers are displayed in the emulator</title>

<image href="GUID-3E80A006-F8D8-45C5-9773-7CC239AE86D9_d0e247182_href.png" placement="inline"/>

</fig>

<p>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: </p>

<ul>

<li><p><codeph>TRawEvent::EPointerMove</codeph> indicates a mouse

move or a mouse wheel movement event.</p></li>

<li><p><codeph>TRawEvent::EButton1Down</codeph> indicates that the

left mouse button is pressed down.</p></li>

<li><p><codeph>TRawEvent::EButton1Up</codeph> indicates that the left

mouse button is released.</p></li>

<li><p><codeph>TRawEvent::EPointerOutOfRange</codeph> indicates that

the proximity of a mouse is out of range. This means that the Z coordinate

value of the mouse has reached <codeph>HALData::EPointer3DMaxProximity</codeph>.</p></li>

</ul>

<section id="GUID-44C3561D-92A1-421E-9AD3-0D8648919C46-GENID-1-12-1-15-1-1-9-1-6-1-6-1-9-1-9-1-8-1-5-1-3-7">       <title>Pressure and proximity emulation</title><p>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.</p><ul>

<li><p>Z &lt; 0 indicates the proximity of the device from the screen.</p></li>

<li><p>Z &gt; 0 indicates pressure.</p></li>

</ul><p>See <xref href="GUID-9C269F45-F160-5A4B-ABF8-896D2A538E3B.dita">Advanced Pointer Overview</xref> for more information about pressure

and proximity.</p><p>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.</p><ul>

<li><p>When the mouse wheel is rotated, a device-specific message

is sent to the emulator window that has focus as each notch is encountered.</p></li>

<li><p>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.</p><p>The pressure or proximity step can be customized in the <filepath>epoc.ini</filepath> file. See <xref href="GUID-930F1E88-2A03-4BD1-AA2A-3A0128A844BD.dita">Enabling Multiple

Pointers in the Emulator Tutorial</xref> for more information.</p></li>

<li><p>When the Z value is in the pressure range (Z &gt; 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.</p></li>

<li><p>When the Z value is in the proximity range (Z &lt; 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. </p></li>

<li><p>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 <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-BF464EF0-D685-3B12-9E13-65A86BAED610"><apiname>HALData::EPointer3DMaxPressure</apiname></xref> (a positive value) and lower

boundary <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-7FCDA198-1E26-3BC9-A5A1-C4AF67016615"><apiname>HALData::EPointer3DMaxProximity</apiname></xref> (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 <codeph>Out of Range</codeph> 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.</p></li>

<li><p>When the mouse button down or up event (<codeph>TRawEvent::EButton1Down</codeph> or <codeph>TRawEvent::EButton1Up</codeph>) is generated, Z is reset

to 0.</p></li>

</ul>     </section>

</conbody><related-links>

<link href="GUID-A12A66ED-2C8F-5CE6-8F3E-332B045A35B4.dita"><linktext>Advanced

Pointers</linktext></link>

<link href="GUID-930F1E88-2A03-4BD1-AA2A-3A0128A844BD.dita"><linktext>Enabling

Multiple Pointers in the Emulator Tutorial</linktext></link>

</related-links></concept>