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

</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<CMyContainerControl*>(Parent());

                parent->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->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<CCoeControl>()) != NULL)

            {

            if (ctrl->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

</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>