<?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_d0e38122_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>