Symbian3/PDK/Source/GUID-C60DC070-572B-5960-B394-550426FDB909.dita
changeset 1 25a17d01db0c
child 3 46218c8b8afa
equal deleted inserted replaced
0:89d6a7a84779 1:25a17d01db0c
       
     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-C60DC070-572B-5960-B394-550426FDB909" xml:lang="en"><title> Advanced
       
    13 Pointer Tutorial</title><shortdesc>This tutorial provides step-by-step instructions and sample code
       
    14 to help you write applications using advanced pointers. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
       
    15 <p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target
       
    16 audience</b>: Application developers. </p>
       
    17 <section><title>Required background </title> <p>This topic builds on the material
       
    18 in the following topics: </p> <ul>
       
    19 <li id="GUID-C4209FBD-3860-5F4B-8458-87D22D483953"><p><xref href="GUID-9C269F45-F160-5A4B-ABF8-896D2A538E3B.dita">Advanced
       
    20 Pointer Overview</xref>  </p> </li>
       
    21 <li id="GUID-9D3C3B31-F43A-5201-A1EC-A1F2848CFF43"><p><xref href="GUID-9AD75103-CD56-5279-B639-5CA2BBF979B5.dita">Advanced
       
    22 Pointer States and Event Communication</xref>  </p> </li>
       
    23 </ul> </section>
       
    24 <section><title>Using advanced pointers</title> <p>This topic covers the following: </p> <ul>
       
    25 <li id="GUID-C3AD43AA-09C0-5BA2-8496-5B87D40C89F5"><p><xref href="GUID-C60DC070-572B-5960-B394-550426FDB909.dita#GUID-C60DC070-572B-5960-B394-550426FDB909/GUID-8CBE862B-0C1D-5088-89B7-9B3EC898E4FC">Enabling multi-touch for a window</xref>  </p> </li>
       
    26 <li id="GUID-177323F2-55C6-56D9-B3D2-A8DDACF69E10"><p><xref href="GUID-C60DC070-572B-5960-B394-550426FDB909.dita#GUID-C60DC070-572B-5960-B394-550426FDB909/GUID-C026DAB9-C11C-5D29-A1EA-6730E914250F">Getting Z coordinates from TPointerEvent</xref>  </p> </li>
       
    27 <li id="GUID-91CEA92C-A692-5853-96F0-625A76B7DC8D"><p><xref href="GUID-C60DC070-572B-5960-B394-550426FDB909.dita#GUID-C60DC070-572B-5960-B394-550426FDB909/GUID-B7057F69-191F-5AA4-8C61-EBECE66D92F6"> Pinch zooming</xref>  </p> </li>
       
    28 </ul> </section>
       
    29 <section id="GUID-8CBE862B-0C1D-5088-89B7-9B3EC898E4FC"><title>Enabling multi-touch
       
    30 in a window</title> <ol id="GUID-210D17A8-4869-5F9B-B71C-672101AC591C">
       
    31 <li id="GUID-81A2AC5C-7837-5216-8F47-FC5959C27522"><p> <xref href="GUID-637F82AF-0CF9-3C85-834D-7C1A0866DF87.dita"><apiname>RWindow</apiname></xref> provides
       
    32 a handle to a standard window. Call <codeph>RWindow</codeph> to create an
       
    33 instance of a window. </p> <codeblock id="GUID-0E31C3F6-3719-5F16-9F74-C405850604B8" xml:space="preserve">
       
    34 RWindow window(ws);
       
    35 
       
    36 User::LeaveIfError(window.Construct(wg, reinterpret_cast&lt;TUint32&gt;(&amp;wg) + 1));
       
    37 </codeblock> </li>
       
    38 <li id="GUID-B67D3702-1A8F-5C6A-AB0F-FEA7C4D04A07"><p>Call <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-05293539-F1B0-3C7D-BB14-3FD42F23D5C8"><apiname>RWindow::EnableAdvancedPointers()</apiname></xref> to
       
    39 enable advanced pointers. Then call <xref href="GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34.dita#GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34/GUID-4E02165A-DFCC-3D18-BB18-18726B28E90A"><apiname>RWindowBase::Activate()</apiname></xref> to
       
    40 display the window and enable the window to receive events. <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> inherits
       
    41 from <xref href="GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34.dita"><apiname>RWindowBase</apiname></xref>, so you can call the <codeph>Activate()</codeph> function
       
    42 on <codeph>RWindow</codeph>. </p> <codeblock id="GUID-DB2FB570-2BB0-5C5F-9E4F-076D6A0E469E" xml:space="preserve">
       
    43 window.EnableAdvancedPointers();
       
    44 window.Activate();
       
    45 </codeblock> <p>When an application needs to receive advanced pointer events
       
    46 in a window, it must call <codeph>RWindowBase::EnableAdvancedPointers()</codeph> for
       
    47 the window <i>before</i> it is activated. </p> <p>If advanced pointers are
       
    48 not enabled for a window, it receives only standard <xref href="GUID-1FFA0073-3D83-388E-A824-08C31F90CC54.dita"><apiname>TPointerEvent</apiname></xref> information
       
    49 from a single pointer with no pressure and proximity data. The single pointer
       
    50 environment rules describe the way in which pointer events coming from many
       
    51 pointers in the multi-pointer model are transformed into events of one pointer.
       
    52 They are necessary to ensure that old single-pointer applications work in
       
    53 a multi-touch environment intuitively and as expected by the user. </p> <p>However,
       
    54 the new <codeph>TPointerEvent</codeph> types, <xref href="GUID-239D0A8B-2759-321D-AD48-976E80192239.dita"><apiname>EEnterCloseProximity</apiname></xref>, <xref href="GUID-8C6264B4-5E19-33A7-92B0-BB79C871BEC7.dita"><apiname>EExitCloseProximity</apiname></xref>, <xref href="GUID-F02DB96E-1541-3223-9B7B-79D45840DB7B.dita"><apiname>EEnterHighPressure</apiname></xref> and <xref href="GUID-15B5991C-B075-3110-B0A4-540EC282AA56.dita"><apiname>EExitHighPressure</apiname></xref>, are delivered to all windows,
       
    55 even to those that do not enable advanced pointers. </p> </li>
       
    56 </ol> </section>
       
    57 <section id="GUID-C026DAB9-C11C-5D29-A1EA-6730E914250F"><title>Getting Z coordinates
       
    58 from TPointerEvent</title> <ol id="GUID-4CC2271D-1798-51B3-9A9D-E7E0B9A33DAE">
       
    59 <li id="GUID-184B5B63-4EFC-55CD-8D1F-E015EEBACBE2"><p>Call <xref href="GUID-1FFA0073-3D83-388E-A824-08C31F90CC54.dita#GUID-1FFA0073-3D83-388E-A824-08C31F90CC54/GUID-E961DA4D-AD38-31F0-88DD-A07D36346DCB"><apiname>TPointerEvent::AdvancedPointerEvent()</apiname></xref> on
       
    60 a <codeph>TPointerEvent</codeph> to return a pointer to a <xref href="GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023.dita"><apiname>TAdvancedPointerEvent</apiname></xref>. </p> <codeblock id="GUID-6E81680A-3070-546B-B575-49EA9E34FAF9" xml:space="preserve">
       
    61 TZType aZType;
       
    62 TPointerEvent&amp; aPointerEvent;
       
    63 TInt* aZ; 
       
    64 TInt* aPoint3D;
       
    65 
       
    66 TAdvancedPointerEvent *advancedP = aPointerEvent.AdvancedPointerEvent();
       
    67 </codeblock> <p> <codeph>TPointerEvent</codeph> is a struct that contains
       
    68 details of a pointer event. <codeph>TZType</codeph> is a struct provided by
       
    69 the programmer containing members to hold proximity, pressure, and "proximity
       
    70 and pressure" data. </p> </li>
       
    71 <li id="GUID-ABA8FA09-5F57-51BC-8CAE-43649B5ED6D3"><p>Now we need to test
       
    72 whether the pointer event contains advanced pointer data. If it is not an
       
    73 advanced pointer, the code leaves. </p> <p>If it is an advanced pointer, we
       
    74 call functions to detect proximity, pressure, "proximity and pressure" data
       
    75 and coordinates. </p> <codeblock id="GUID-DF109643-2564-51A0-B0F6-33BF4DA1F6E3" xml:space="preserve">
       
    76 if(!advancedP)
       
    77     {
       
    78     // The TPointerEvent isn't an instance of TAdvancedPointerEvent
       
    79     User::Leave(KErrArgument);
       
    80     }
       
    81 
       
    82 switch(aZType)
       
    83     {
       
    84     case EZTypeProximity:
       
    85         aZ = advancedP-&gt;Proximity();
       
    86         aPoint3D = advancedP-&gt;Proximity3D(); 
       
    87         break;
       
    88     case EZTypePressure:
       
    89         aZ = advancedP-&gt;Pressure();
       
    90         aPoint3D = advancedP-&gt;Pressure3D();
       
    91         break;
       
    92     case EZTypeProximityAndPressure:
       
    93         aZ = advancedP-&gt;ProximityAndPressure();
       
    94         aPoint3D = advancedP-&gt;ProximityAndPressure3D();
       
    95         break;
       
    96     default: 
       
    97         User::Leave(KErrArgument);
       
    98         break;
       
    99     }
       
   100 </codeblock> <ul>
       
   101 <li id="GUID-40C01884-AC86-5882-935D-2EC2E27C9004"><p> <xref href="GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023.dita#GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023/GUID-0ED4B1CC-0655-3246-8645-AAC9E0C27298"><apiname>TAdvancedPointerEvent::Proximity()</apiname></xref> returns
       
   102 the proximity. </p> </li>
       
   103 <li id="GUID-16A9A86B-A837-5E43-BB3A-F5A04A7F4552"><p> <xref href="GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023.dita#GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023/GUID-15DEBFBF-7B7D-3FCF-9929-C973824A5FD3"><apiname>TAdvancedPointerEvent::Pressure()</apiname></xref> returns
       
   104 the pressure. </p> </li>
       
   105 <li id="GUID-3E614890-C317-596E-A5B9-FD76426DBD12"><p> <xref href="GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023.dita#GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023/GUID-114AE77E-D0BD-321E-BFCB-1388B35582EC"><apiname>TAdvancedPointerEvent::ProximityAndPressure()</apiname></xref> returns
       
   106 the proximity and pressure combined. </p> </li>
       
   107 <li id="GUID-6F62C0D1-FAE4-5F8F-B451-68ABA404A369"><p> <xref href="GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023.dita#GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023/GUID-E5AA7737-D217-3FDE-9E4D-AAA7F5D2C300"><apiname>TAdvancedPointerEvent::
       
   108 Position3D()</apiname></xref> returns the proximity and the X, Y and Z coordinates. </p> </li>
       
   109 <li id="GUID-5AD1811D-BCBF-5A44-B6E7-EB71BF254BCA"><p> <xref href="GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023.dita#GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023/GUID-2F30A8F5-75BA-3FE3-84B7-3C772ED75857"><apiname>TAdvancedPointerEvent::Pressure3D()</apiname></xref> returns
       
   110 the pressure and the X and Y coordinates. </p> </li>
       
   111 </ul> <p>Proximity is <i>always</i> negative and pressure is <i>always</i> positive.
       
   112 Internally they are combined together as a Z coordinate. When Z &gt; 0, the proximity
       
   113 is 0 and the Z value represents the pressure. When Z &lt; 0, the pressure
       
   114 is 0 and the Z value represents the proximity. Some APIs use only a Z coordinate
       
   115 (such as the threshold getters and setters and <xref href="GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023.dita#GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023/GUID-114AE77E-D0BD-321E-BFCB-1388B35582EC"><apiname>TAdvancedPointerEvent::ProximityAndPressure()</apiname></xref>).
       
   116 In these, the Z coordinate is interpreted in terms of pressure and proximity. </p> </li>
       
   117 </ol> <fig id="GUID-7A49B143-5458-5916-B937-55D98B77BB2C">
       
   118 <title> Relationships between the pointer proximity, pressure and Z      
       
   119        coordinate            </title>
       
   120 <image href="GUID-1A0FB98B-8DB3-5067-9B71-FF838F6AE402_d0e216655_href.png" placement="inline"/>
       
   121 </fig> </section>
       
   122 <section id="GUID-B7057F69-191F-5AA4-8C61-EBECE66D92F6"><title>Pinch zooming</title> <p>This
       
   123 example shows an easy way to pinch zoom an image when the screen receives
       
   124 pointer events from two pointers. There are two functions in this code that
       
   125 must be implemented by the programmer: <codeph>BitmapCoordinates()</codeph> and <codeph>MoveBitmap()</codeph>.
       
   126 They are not included in the example because they involve complex calculations
       
   127 that are not related to advanced pointers. </p> <p>The high-level steps to
       
   128 perform pinch zooming are: </p> <ol id="GUID-AEF3917C-AAFE-5C25-9609-396D08478AC0">
       
   129 <li id="GUID-7839E665-C4E1-59C8-BA89-22A62615EFA3"><p>Define the coordinates,
       
   130 equivalent to the given on-screen coordinates. In the code example, this is
       
   131 done using the function <codeph>BitmapCoordinates()</codeph>. </p> </li>
       
   132 <li id="GUID-FC4B1BDA-8120-53C9-9C88-BEFEF1AD54B4"><p>Define the ID of the
       
   133 pointer by using <xref href="GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023.dita#GUID-FADA3278-FF8B-308F-90AD-3DCF8911A023/GUID-67593D7E-CE40-303F-B847-81D6FC0578B1"><apiname>TAdvancedPointerEvent::PointerNumber()</apiname></xref>.
       
   134 If the device can handle two pointers (two fingers) at the same time, their
       
   135 numbers are 0 and 1. The pointer number enables you to distinguish a given
       
   136 pointer from other pointers. </p> </li>
       
   137 <li id="GUID-1E8F7D23-EEAD-5EA5-8863-276076D6B54E"><p>For each pointer assign
       
   138 its coordinates to a local variable. We assume there are only two pointers
       
   139 handled by the system here. </p> </li>
       
   140 <li id="GUID-E44B3D9B-560A-5959-996D-A63CBD4C3786"><p>Use the <codeph>MoveBitmap()</codeph> function
       
   141 to achieve the zoom effect. </p> <codeblock id="GUID-D85CCFDD-8F65-530A-ACD7-93DD1D435FC6" xml:space="preserve">
       
   142 /**
       
   143 Receives pointer events from two pointers to perform Pinch Zoom of the image.
       
   144 Function will finish when EButton1Up is received for any of the pointers.
       
   145 @param aPointer1    Coordinates of pointer number 1 when zoom is started
       
   146 @param aPointer2    Coordinates of pointer number 2 when zoom is started
       
   147 */
       
   148 
       
   149 void PinchZoom(TPoint aPointer1, TPoint aPointer2)
       
   150     {
       
   151     TPoint actualP1 = aPointer1;
       
   152     TPoint actualP2 = aPointer2;
       
   153     
       
   154     // translate on-screen pointer coordinates to coordinates of displayed bitmap
       
   155     TPoint bitmapCatching1 = BitmapCoordinates(aPointer1);
       
   156     TPoint bitmapCatching2 = BitmapCoordinates(aPointer2);
       
   157     
       
   158     TBool repaint = EFalse;
       
   159                                 
       
   160     while (ETrue)
       
   161         {
       
   162         TAdvancedPointerEvent event = GetNextPointerEvent();
       
   163         
       
   164         if (event.iType == TPointerEvent::EDrag)
       
   165             { 
       
   166             if (event.PointerNumber() == 1)
       
   167                 { 
       
   168                 actualP1 = event.iPosition;
       
   169                 repaint = ETrue;
       
   170                 }
       
   171             else if (event.PointerNumber() == 2)
       
   172                 {
       
   173                 actualP2 = event.iPosition;
       
   174                 repaint = ETrue;
       
   175                 }
       
   176             }
       
   177         else if (event.iType == TPointerEvent::EButton1Up)
       
   178             {
       
   179             break;
       
   180             }
       
   181         
       
   182         if (repaint)
       
   183             {
       
   184             // move bitmap on the screen in the way that
       
   185             // bitmapCatching1 point of the bitmap will be displayed at actualP1 screen coordinate,
       
   186             // bitmapCatching2 point of the bitmap will be displayed at actualP2 screen coordinate.
       
   187             MoveBitmap(bitmapCatching1, actualP1, bitmapCatching2, actualP2);
       
   188             repaint = EFalse;
       
   189             }
       
   190         }
       
   191     }
       
   192 </codeblock> </li>
       
   193 </ol> </section>
       
   194 </conbody><related-links>
       
   195 <link href="GUID-9C269F45-F160-5A4B-ABF8-896D2A538E3B.dita"><linktext>Advanced
       
   196 Pointer                 Overview</linktext></link>
       
   197 <link href="GUID-9AD75103-CD56-5279-B639-5CA2BBF979B5.dita"><linktext>Advanced
       
   198 Pointer States and                 Event Communication</linktext></link>
       
   199 </related-links></concept>