|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-9126A296-0301-4077-A183-3D703F77C548" xml:lang="en"><title>Multi-Touch |
|
13 Support in the Emulator Overview</title><shortdesc>This topic provides an overview of multi-touch support in the emulator. |
|
14 Two mice are used to provide two independent pointer positions. The emulator |
|
15 responds to the mice’s individual button-clicks, moves, and mouse wheel scrolls |
|
16 as if two human fingers are moving, touching or hovering over the screen.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
17 <p>The emulator can be extended to support more than two mice or other pointer |
|
18 devices.</p> |
|
19 <p><b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target |
|
20 audience</b>: Application developers. </p> |
|
21 <p>The following figure shows two Windows pointers on the emulator screen, |
|
22 each representing a mouse device. The ordinal integer (starting from 0) beside |
|
23 each pointer is the unique device identifier. The position of each mouse on |
|
24 the screen is represented by the X and Y coordinates. The pressure (a positive |
|
25 value) and proximity (a negative value) information captured by the mouse |
|
26 wheel is represented by the Z coordinate. Notice that the status bar shows |
|
27 the identifier and the dynamic X, Y and Z values of each pointer.</p> |
|
28 <fig id="GUID-03428614-06B1-4821-A284-C3B6DB8E053C"> |
|
29 <title>Two pointers are displayed in the emulator</title> |
|
30 <image href="GUID-3E80A006-F8D8-45C5-9773-7CC239AE86D9_d0e199057_href.png" placement="inline"/> |
|
31 </fig> |
|
32 <p>The delivery of pointer events from the emulator driver to the Window Server |
|
33 is the same in the multi-touch environment as in the single pointer environment. |
|
34 This means the raw events for a mouse move, button click and mouse wheel movement |
|
35 are delivered to the Window Server as usual. Each mouse has a unique device |
|
36 identifier, which makes it possible to ascertain which mouse the events relate |
|
37 to. The raw events for each individual mouse include the following: </p> |
|
38 <ul> |
|
39 <li><p><codeph>TRawEvent::EPointerMove</codeph> indicates a mouse move or |
|
40 a mouse wheel movement event.</p></li> |
|
41 <li><p><codeph>TRawEvent::EButton1Down</codeph> indicates that the left mouse |
|
42 button is pressed down.</p></li> |
|
43 <li><p><codeph>TRawEvent::EButton1Up</codeph> indicates that the left mouse |
|
44 button is released.</p></li> |
|
45 <li><p><codeph>TRawEvent::EPointerOutOfRange</codeph> indicates that the proximity |
|
46 of a mouse is out of range. This means that the Z coordinate value of the |
|
47 mouse has reached <codeph>HALData::EPointer3DMaxProximity</codeph>.</p></li> |
|
48 </ul> |
|
49 <section id="GUID-44C3561D-92A1-421E-9AD3-0D8648919C46-GENID-1-8-1-12-1-1-7-1-5-1-6-1-8-1-9-1-8-1-5-1-3-7"> <title>Pressure |
|
50 and proximity emulation</title><p>The Z coordinate value is used to represent |
|
51 the pressure and proximity to the screen. In the emulator, the Z value is |
|
52 captured and tuned by the mouse wheel movement.</p><ul> |
|
53 <li><p>Z < 0 indicates the proximity of the device from the screen.</p></li> |
|
54 <li><p>Z > 0 indicates pressure.</p></li> |
|
55 </ul><p>See <xref href="GUID-9C269F45-F160-5A4B-ABF8-896D2A538E3B.dita">Advanced |
|
56 Pointer Overview</xref> for more information about pressure and proximity.</p><p>The |
|
57 mouse wheel combines the features of a wheel and a mouse button. The wheel |
|
58 has discrete, evenly spaced notches. Rotating the wheel backwards or forwards |
|
59 has the effect of changing the pressure or proximity.</p><ul> |
|
60 <li><p>When the mouse wheel is rotated, a device-specific message is sent |
|
61 to the emulator window that has focus as each notch is encountered.</p></li> |
|
62 <li><p>The Z coordinate is initiated as 0. Then when the wheel is moved forward, |
|
63 the Z value enters the pressure range and increases by one pressure step. |
|
64 When the wheel is moved backward, the Z value enters the proximity range and |
|
65 decreases by one proximity step.</p><p>The pressure or proximity step can |
|
66 be customized in the <filepath>epoc.ini</filepath> file. See <xref href="GUID-930F1E88-2A03-4BD1-AA2A-3A0128A844BD.dita">Enabling |
|
67 Multi-Touch in the Emulator Tutorial</xref> for more information.</p></li> |
|
68 <li><p>When the Z value is in the pressure range (Z > 0), moving the wheel |
|
69 forward by one notch increases Z by one pressure step. Moving the wheel backward |
|
70 by one notch decreases Z by one pressure step, until Z returns to 0.</p></li> |
|
71 <li><p>When the Z value is in the proximity range (Z < 0), moving the wheel |
|
72 backward by one notch decreases Z by one proximity step. Moving the wheel |
|
73 forward by one notch increases Z by one proximity step, until Z returns to |
|
74 0. </p></li> |
|
75 <li><p>There are limits to the values of the Z coordinate. This |
|
76 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 |
|
77 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 |
|
78 negative value). If Z is at the lower boundary, when the mouse wheel is moved |
|
79 backward next time, Z does not change. A new <codeph>Out of Range</codeph> pointer |
|
80 event is generated and sent to the Window Server. Similarly when Z is at the |
|
81 upper boundary, Z does not change when the mouse wheel is moved forward.</p></li> |
|
82 <li><p>When the mouse button down or up event (<codeph>TRawEvent::EButton1Down</codeph> or <codeph>TRawEvent::EButton1Up</codeph>) |
|
83 is generated, Z is reset to 0.</p></li> |
|
84 </ul> </section> |
|
85 </conbody><related-links> |
|
86 <link href="GUID-A12A66ED-2C8F-5CE6-8F3E-332B045A35B4.dita"><linktext>Advanced |
|
87 Pointers</linktext></link> |
|
88 <link href="GUID-930F1E88-2A03-4BD1-AA2A-3A0128A844BD.dita"><linktext>Enabling |
|
89 Multi-Touch in the Emulator Tutorial</linktext></link> |
|
90 </related-links></concept> |