Symbian3/PDK/Source/GUID-E9191C31-4D09-4C95-85E4-4282ADEE1D82.dita
changeset 5 f345bda72bc4
child 9 59758314f811
equal deleted inserted replaced
4:4816d766a08a 5:f345bda72bc4
       
     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-E9191C31-4D09-4C95-85E4-4282ADEE1D82" xml:lang="en"><title>Handling
       
    13 pointer events in custom controls</title><shortdesc>The Symbian platform passes touch events to applications by calling <parmname>CCoeControl::HandlePointerEventL()</parmname>.
       
    14 The application that receives these events is the one that owns the window.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
       
    15 <p>While this method has been available since S60 3.0, it previously has been
       
    16 an optional method. If you have derived a custom control from <parmname>CCoeControl</parmname>,
       
    17 then you must implement the <parmname>CCoeControl::HandlePointerEventL()</parmname> method.
       
    18 Otherwise, your application cannot react to the touch events passed to it.</p>
       
    19 <p>You have to implement at least <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-5CF90E7A-4A91-36FF-BB3F-CF7CF687DED2"><apiname>CCoeControl::HandlePointerEventL()</apiname></xref> into
       
    20 your own custom UI components. If you have a container control that owns other
       
    21 controls, you have to remember to call the base class implementation of <codeph>CCoeControl::HandlePointerEventL()</codeph> before
       
    22 your additional code as illustrated below:</p>
       
    23 <codeblock xml:space="preserve">void CMyContainerControl::HandlePointerEventL()
       
    24     {
       
    25     // Remember to call base class implementation
       
    26     CCoeControl::HandlePointerEventL();
       
    27     
       
    28     // Your additional code here
       
    29     // ...
       
    30     }</codeblock>
       
    31 <p>The following figure illustrates changes in the code. Items marked with
       
    32 a black frame indicate usage of features in earlier editions, and items marked
       
    33 with a red frame are new features.</p>
       
    34 <fig id="GUID-A8FE0B16-FCA8-48FB-BAE8-EE141CED39C0">
       
    35 <title><parmname>CCoeControl::HandlePointerEventL()</parmname> usage</title>
       
    36 <image href="GUID-52783B69-09FC-4123-849A-79FF61406129_d0e71327_href.png" placement="inline"/>
       
    37 </fig>
       
    38 <p>To handle pointer events in your custom control:</p>
       
    39 <ol>
       
    40 <li id="GUID-CFB37EC0-E28A-4E28-9D7E-FEE90F21C1E5"><itemgroup><p>In your custom
       
    41 control header file, include the <parmname>CCoeControl::HandlePointerEventL()</parmname> method.</p><codeblock xml:space="preserve">    public: // from CCoeControl
       
    42     void HandlePointerEventL(const TPointerEvent&amp; aPointerEvent);</codeblock></itemgroup></li>
       
    43 <li id="GUID-096D3B29-AD1F-4BBA-90FD-8A850A353BA3"><itemgroup><p>In your custom
       
    44 control, implement the <parmname>CCoeControl::HandlePointerEventL()</parmname> method.</p><codeblock xml:space="preserve">void CMyControl::HandlePointerEventL(const TPointerEvent&amp; aPointerEvent)
       
    45     {
       
    46     switch( aPointerEvent.iType )
       
    47         {
       
    48         case TPointerEvent::EButton1Up:
       
    49             {
       
    50             // Is the pointer position on this component?
       
    51             if (Rect().Contains(aPointerEvent.iPosition))
       
    52                 {
       
    53                 SetFocus(ETrue);
       
    54                 // Tell container control that this is focused control
       
    55                 CMyContainerControl* parent = static_cast&lt;CMyContainerControl*&gt;(Parent());
       
    56                 parent-&gt;SetLastFocusedControl(this);
       
    57                 }
       
    58             break;
       
    59             }
       
    60         default:
       
    61             {
       
    62             break;
       
    63             }
       
    64         }
       
    65     }</codeblock><p>By default, the Symbian platform only passes <parmname>EButton1Down</parmname> and <parmname>EButton1Up</parmname> events
       
    66 to <parmname>CCoeControl::HandlePointerEventL()</parmname>. To enable drag
       
    67 events, see <xref href="GUID-33D93E96-98A9-4116-9028-3241D76A1036.dita">Enabling
       
    68 additional touch events for your application</xref>.</p></itemgroup></li>
       
    69 <li id="GUID-6725474A-66CA-4AEE-99AA-7608E4219780"><itemgroup><p>In your custom
       
    70 container control header file, include the <parmname>CCoeControl::HandlePointerEventL()</parmname> method.</p><codeblock xml:space="preserve">void HandlePointerEventL(const TPointerEvent&amp; aPointerEvent);</codeblock></itemgroup></li>
       
    71 <li id="GUID-0166F02C-5B77-40D5-9CC5-FAEF53E8639A"><itemgroup><p>In your custom
       
    72 container control, implement the <parmname>CCoeControl::HandlePointerEventL()</parmname> method.</p><codeblock xml:space="preserve">void CMyContainerControl::HandlePointerEventL(const TPointerEvent&amp; aPointerEvent)
       
    73     {
       
    74     // Check if touch is enabled or not
       
    75     if( !AknLayoutUtils::PenEnabled() )
       
    76         {
       
    77         return;
       
    78         }
       
    79  
       
    80     // Remove last focus
       
    81     if (iLastFocusedControl)
       
    82         {
       
    83         iLastFocusedControl-&gt;SetFocus(EFalse);
       
    84         }
       
    85     
       
    86     // Call base class method, that forwards pointer event the right child
       
    87     // component
       
    88     CCoeControl::HandlePointerEventL(aPointerEvent);
       
    89     
       
    90     // Check all button up cases again
       
    91     if (aPointerEvent.iType == TPointerEvent::EButton1Up)
       
    92         {
       
    93         // Find which control was focused / received pointer event
       
    94         CCoeControlArray::TCursor cursor = Components().Begin();
       
    95         CCoeControl* ctrl = NULL;
       
    96         TInt counter = 0;
       
    97         while ((ctrl = cursor.Control&lt;CCoeControl&gt;()) != NULL)
       
    98             {
       
    99             if (ctrl-&gt;Rect().Contains(aPointerEvent.iPosition))
       
   100                 {
       
   101                 // Set focused index for the scroll bar
       
   102                 iFocusedIndex = counter;
       
   103                 break;
       
   104                 }
       
   105             cursor.Next();
       
   106             counter++;
       
   107             }
       
   108         }
       
   109  
       
   110     // Do drawing
       
   111     UpdateScrollBarFrameL();
       
   112     DrawNow();
       
   113     }</codeblock><note importance="normal"><p>For information on the <parmname>AknLayoutUtils::PenEnabled()</parmname> method,
       
   114 see <xref href="GUID-DB2E0959-C24E-4E6E-BC6D-064B91BDE662.dita">Checking for touch
       
   115 support at runtime</xref>.</p></note></itemgroup></li>
       
   116 </ol>
       
   117 <ul>
       
   118 <li><itemgroup><p>Features introduced:</p><ul>
       
   119 <li><p>Optional <parmname>TPointerEvent::EDrag()</parmname> for receiving
       
   120 events indicating that a mobile device user is dragging it across the screen.</p><p>For
       
   121 more information on this and other touch event options, see <xref href="GUID-33D93E96-98A9-4116-9028-3241D76A1036.dita">Enabling
       
   122 additional touch events for your application</xref>.</p></li>
       
   123 <li><p>Optional <parmname>MTouchFeedback</parmname> observer for sending a
       
   124 vibration when a mobile device user touches a control with the feedback interface.</p><p>For
       
   125 more information on tactile feedback, see <xref href="GUID-581A8E4B-12BE-41C0-A20E-3087A80FEECF.dita">Tactile
       
   126 feedback</xref>.</p></li>
       
   127 </ul></itemgroup></li>
       
   128 </ul>
       
   129 </conbody><related-links>
       
   130 <linklist><title>Related information</title>
       
   131 <link href="GUID-33D93E96-98A9-4116-9028-3241D76A1036.dita"><linktext>Enabling
       
   132 additional touch events for your application</linktext></link>
       
   133 <link href="GUID-581A8E4B-12BE-41C0-A20E-3087A80FEECF.dita"><linktext>Providing
       
   134 tactile feedback</linktext></link>
       
   135 <link href="GUID-1614B24F-5DB2-43AA-9A18-723BD61B8B4C.dita"><linktext>Handling
       
   136 key events in your application</linktext></link>
       
   137 </linklist>
       
   138 </related-links></concept>