|
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_d0e43689_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& 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& 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<CMyContainerControl*>(Parent()); |
|
56 parent->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& 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& 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->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<CCoeControl>()) != NULL) |
|
98 { |
|
99 if (ctrl->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> |