|
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-1614B24F-5DB2-43AA-9A18-723BD61B8B4C" xml:lang="en"><title>Handling |
|
13 key events in your application</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>The application framework offers key events to UI controls on the control |
|
15 stack by calling <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aOfferKeyEventL%28const%20TKeyEvent%20%26amp%3b%2cTEventCode%29" format="application/java-archive"><parmname>CCoeControl::OfferKeyEventL()</parmname></xref> for each |
|
16 UI control until the key event is consumed or until there are no more UI controls |
|
17 on the control stack. To handle an event in a UI control, you must override <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aOfferKeyEventL%28const%20TKeyEvent%20%26amp%3b%2cTEventCode%29" format="application/java-archive"><parmname>CCoeControl::OfferKeyEventL()</parmname></xref>. If a UI |
|
18 control is a compound control, then forward key events to other controls within |
|
19 the compound control. The control that consumes the event must be a <xref href="GUID-352850A9-227F-45DB-8DCD-C6268954B4ED.dita">window-owning control</xref>. |
|
20 An example of an implementation is as follows:</p> |
|
21 <codeblock id="GUID-D93EBAD0-6C04-4E97-ABE2-9999EAA6F442" xml:space="preserve">KeyResponse CMyAppView::OfferKeyEventL(const TKeyEvent& aKeyEvent, TEventCode aType) |
|
22 { |
|
23 TKeyResponse response = EKeyWasNotConsumed; |
|
24 //Check first that event type is EEventKey. It could be also |
|
25 //EEventKeyUp or EEventKeyDown which just inform that some key |
|
26 // is pressed or released. |
|
27 if( aType == EEventKey ) |
|
28 { |
|
29 // Take out the code of the key |
|
30 TInt code = aKeyEvent.iCode; |
|
31 TBuf< KMessageLength > buf; |
|
32 buf.AppendNum( code ); |
|
33 // Show the code |
|
34 iEikonEnv->InfoMsg(buf); |
|
35 // Forward the key event to the focused control |
|
36 if( iListBox->IsFocused() ) |
|
37 { |
|
38 response = iListBox->OfferKeyEventL( aKeyEvent, aType ); |
|
39 } |
|
40 else if( iEditView->IsFocused() ) |
|
41 { |
|
42 response = |
|
43 iEditView->OfferKeyEventL( aKeyEvent, aType ); |
|
44 } |
|
45 } |
|
46 // Return the key consumption status |
|
47 return response; |
|
48 } |
|
49 </codeblock> |
|
50 <p><parmname>CMyAppView</parmname> is a window-owning compound control |
|
51 and <parmname>iListBox</parmname> and <parmname>iEditView</parmname> are controls |
|
52 inside <parmname>CMyAppView</parmname>. Key events are offered to controls |
|
53 depending on the focus.</p> |
|
54 <p>If your implementation consumes the event handed to it, you must return <parmname>EKeyWasConsumed</parmname>. |
|
55 If your implementation does not process the event, your code must return <parmname>EKeyWasNotConsumed</parmname>. |
|
56 The application framework continues to offer the event to controls registered |
|
57 with the control stack from top to bottom until the event is consumed or until |
|
58 there are no more controls, in which case the event is handed to the UI controller |
|
59 by calling <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeAppUiClass.html#%3a%3aCCoeAppUi%3a%3aHandleKeyEventL%28const%20TKeyEvent%20%26amp%3b%2cTEventCode%29" format="application/java-archive"><parmname>CCoeAppUI::HandleKeyEventL()</parmname></xref> for the UI |
|
60 controller. </p> |
|
61 <p>Handle key events in your UI controller by overriding <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeAppUiClass.html#%3a%3aCCoeAppUi%3a%3aHandleKeyEventL%28const%20TKeyEvent%20%26amp%3b%2cTEventCode%29" format="application/java-archive"><parmname>CCoeAppUI::HandleKeyEventL()</parmname></xref>. An example |
|
62 of an implementation is as follows:</p> |
|
63 <codeblock id="GUID-3A2D3630-C28F-4165-8589-73AA4627D008" xml:space="preserve">TKeyResponse CMyViewAppUi::HandleKeyEventL( const TKeyEvent& aKeyEvent,TEventCode /*aType*/) |
|
64 { |
|
65 if( iTabGroup == NULL ) |
|
66 { |
|
67 return EKeyWasNotConsumed; |
|
68 } |
|
69 |
|
70 TInt active = iTabGroup->ActiveTabIndex(); |
|
71 TInt count = iTabGroup->TabCount(); |
|
72 |
|
73 switch( aKeyEvent.iCode ) |
|
74 { |
|
75 case EKeyLeftArrow: |
|
76 if ( active > 0 ) |
|
77 { |
|
78 active--; |
|
79 iTabGroup->SetActiveTabByIndex( active ); |
|
80 // ActivateLocalViewL() is used to change the view. |
|
81 // To change view from another application we would use ActivateViewL() |
|
82 // Send an empty message |
|
83 ActivateLocalViewL( TUid::Uid( iTabGroup->TabIdFromIndex( active ) ) ); |
|
84 } |
|
85 break; |
|
86 case EKeyRightArrow: |
|
87 if( ( active + 1 ) < count ) |
|
88 { |
|
89 active++; |
|
90 iTabGroup->SetActiveTabByIndex( active ); |
|
91 // ActivateLocalViewL() is used to change the view. |
|
92 // To change view from another application we would use ActivateViewL() |
|
93 ActivateLocalViewL( TUid::Uid( iTabGroup->TabIdFromIndex( active ) ) ); |
|
94 } |
|
95 break; |
|
96 default: |
|
97 return EKeyWasNotConsumed; |
|
98 break; |
|
99 } |
|
100 |
|
101 return EKeyWasConsumed; |
|
102 } |
|
103 </codeblock> |
|
104 <p><parmname>CMyAppView</parmname> is a UI controller that is using key |
|
105 events from the selection key of a mobile device to switch between two <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknView.html" format="application/java-archive"><parmname>CAknView</parmname></xref>-derived |
|
106 views. <parmname>EKeyLeftArrow</parmname> and <parmname>EKeyRightArrow</parmname> are |
|
107 codes enumerated in <parmname>TKeyCode</parmname> and are contained in <parmname>KeyEvent.iCode</parmname>.</p> |
|
108 <note> |
|
109 <p>The above code snippet was taken from the <i>MyView</i> example application |
|
110 provided in the <parmname>S60 Platform: Platform Application Views</parmname> package |
|
111 available from <xref href="http://www.forum.nokia.com/info/sw.nokia.com/id/9c5f21fd-2162-42da-aaf6-17a59b943475/S60_Platform_Application_Views_v2_0_en.zip.html" scope="external">Forum Nokia</xref> . </p> |
|
112 </note> |
|
113 <p>For more information on <parmname>TKeyCode</parmname>, see <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Kernel_Architecture_2/e32keys.hGlobals.html#%3a%3aTKeyCode" format="application/java-archive"><parmname>TKeyCode</parmname></xref>.</p> |
|
114 </conbody></concept> |