--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-E9191C31-4D09-4C95-85E4-4282ADEE1D82.dita	Tue Mar 30 11:56:28 2010 +0100
@@ -0,0 +1,138 @@
+<?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-E9191C31-4D09-4C95-85E4-4282ADEE1D82" xml:lang="en"><title>Handling
+pointer events in custom controls</title><shortdesc>The Symbian platform passes touch events to applications by calling <parmname>CCoeControl::HandlePointerEventL()</parmname>.
+The application that receives these events is the one that owns the window.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>While this method has been available since S60 3.0, it previously has been
+an optional method. If you have derived a custom control from <parmname>CCoeControl</parmname>,
+then you must implement the <parmname>CCoeControl::HandlePointerEventL()</parmname> method.
+Otherwise, your application cannot react to the touch events passed to it.</p>
+<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
+your own custom UI components. If you have a container control that owns other
+controls, you have to remember to call the base class implementation of <codeph>CCoeControl::HandlePointerEventL()</codeph> before
+your additional code as illustrated below:</p>
+<codeblock xml:space="preserve">void CMyContainerControl::HandlePointerEventL()
+    {
+    // Remember to call base class implementation
+    CCoeControl::HandlePointerEventL();
+    
+    // Your additional code here
+    // ...
+    }</codeblock>
+<p>The following figure illustrates changes in the code. Items marked with
+a black frame indicate usage of features in earlier editions, and items marked
+with a red frame are new features.</p>
+<fig id="GUID-A8FE0B16-FCA8-48FB-BAE8-EE141CED39C0">
+<title><parmname>CCoeControl::HandlePointerEventL()</parmname> usage</title>
+<image href="GUID-52783B69-09FC-4123-849A-79FF61406129_d0e71327_href.png" placement="inline"/>
+</fig>
+<p>To handle pointer events in your custom control:</p>
+<ol>
+<li id="GUID-CFB37EC0-E28A-4E28-9D7E-FEE90F21C1E5"><itemgroup><p>In your custom
+control header file, include the <parmname>CCoeControl::HandlePointerEventL()</parmname> method.</p><codeblock xml:space="preserve">    public: // from CCoeControl
+    void HandlePointerEventL(const TPointerEvent&amp; aPointerEvent);</codeblock></itemgroup></li>
+<li id="GUID-096D3B29-AD1F-4BBA-90FD-8A850A353BA3"><itemgroup><p>In your custom
+control, implement the <parmname>CCoeControl::HandlePointerEventL()</parmname> method.</p><codeblock xml:space="preserve">void CMyControl::HandlePointerEventL(const TPointerEvent&amp; aPointerEvent)
+    {
+    switch( aPointerEvent.iType )
+        {
+        case TPointerEvent::EButton1Up:
+            {
+            // Is the pointer position on this component?
+            if (Rect().Contains(aPointerEvent.iPosition))
+                {
+                SetFocus(ETrue);
+                // Tell container control that this is focused control
+                CMyContainerControl* parent = static_cast&lt;CMyContainerControl*&gt;(Parent());
+                parent-&gt;SetLastFocusedControl(this);
+                }
+            break;
+            }
+        default:
+            {
+            break;
+            }
+        }
+    }</codeblock><p>By default, the Symbian platform only passes <parmname>EButton1Down</parmname> and <parmname>EButton1Up</parmname> events
+to <parmname>CCoeControl::HandlePointerEventL()</parmname>. To enable drag
+events, see <xref href="GUID-33D93E96-98A9-4116-9028-3241D76A1036.dita">Enabling
+additional touch events for your application</xref>.</p></itemgroup></li>
+<li id="GUID-6725474A-66CA-4AEE-99AA-7608E4219780"><itemgroup><p>In your custom
+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>
+<li id="GUID-0166F02C-5B77-40D5-9CC5-FAEF53E8639A"><itemgroup><p>In your custom
+container control, implement the <parmname>CCoeControl::HandlePointerEventL()</parmname> method.</p><codeblock xml:space="preserve">void CMyContainerControl::HandlePointerEventL(const TPointerEvent&amp; aPointerEvent)
+    {
+    // Check if touch is enabled or not
+    if( !AknLayoutUtils::PenEnabled() )
+        {
+        return;
+        }
+ 
+    // Remove last focus
+    if (iLastFocusedControl)
+        {
+        iLastFocusedControl-&gt;SetFocus(EFalse);
+        }
+    
+    // Call base class method, that forwards pointer event the right child
+    // component
+    CCoeControl::HandlePointerEventL(aPointerEvent);
+    
+    // Check all button up cases again
+    if (aPointerEvent.iType == TPointerEvent::EButton1Up)
+        {
+        // Find which control was focused / received pointer event
+        CCoeControlArray::TCursor cursor = Components().Begin();
+        CCoeControl* ctrl = NULL;
+        TInt counter = 0;
+        while ((ctrl = cursor.Control&lt;CCoeControl&gt;()) != NULL)
+            {
+            if (ctrl-&gt;Rect().Contains(aPointerEvent.iPosition))
+                {
+                // Set focused index for the scroll bar
+                iFocusedIndex = counter;
+                break;
+                }
+            cursor.Next();
+            counter++;
+            }
+        }
+ 
+    // Do drawing
+    UpdateScrollBarFrameL();
+    DrawNow();
+    }</codeblock><note importance="normal"><p>For information on the <parmname>AknLayoutUtils::PenEnabled()</parmname> method,
+see <xref href="GUID-DB2E0959-C24E-4E6E-BC6D-064B91BDE662.dita">Checking for touch
+support at runtime</xref>.</p></note></itemgroup></li>
+</ol>
+<ul>
+<li><itemgroup><p>Features introduced:</p><ul>
+<li><p>Optional <parmname>TPointerEvent::EDrag()</parmname> for receiving
+events indicating that a mobile device user is dragging it across the screen.</p><p>For
+more information on this and other touch event options, see <xref href="GUID-33D93E96-98A9-4116-9028-3241D76A1036.dita">Enabling
+additional touch events for your application</xref>.</p></li>
+<li><p>Optional <parmname>MTouchFeedback</parmname> observer for sending a
+vibration when a mobile device user touches a control with the feedback interface.</p><p>For
+more information on tactile feedback, see <xref href="GUID-581A8E4B-12BE-41C0-A20E-3087A80FEECF.dita">Tactile
+feedback</xref>.</p></li>
+</ul></itemgroup></li>
+</ul>
+</conbody><related-links>
+<linklist><title>Related information</title>
+<link href="GUID-33D93E96-98A9-4116-9028-3241D76A1036.dita"><linktext>Enabling
+additional touch events for your application</linktext></link>
+<link href="GUID-581A8E4B-12BE-41C0-A20E-3087A80FEECF.dita"><linktext>Providing
+tactile feedback</linktext></link>
+<link href="GUID-1614B24F-5DB2-43AA-9A18-723BD61B8B4C.dita"><linktext>Handling
+key events in your application</linktext></link>
+</linklist>
+</related-links></concept>
\ No newline at end of file