--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-1614B24F-5DB2-43AA-9A18-723BD61B8B4C.dita Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,113 @@
+<?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-1614B24F-5DB2-43AA-9A18-723BD61B8B4C" xml:lang="en"><title>Handling
+key events in your application</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>The application framework offers key events to UI controls on the control
+stack by calling <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-47C26178-E83E-3B21-95A3-FD6370000844"><apiname>CCoeControl::OfferKeyEventL()</apiname></xref> for each
+UI control until the key event is consumed or until there are no more UI controls
+on the control stack. To handle an event in a UI control, you must override <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-47C26178-E83E-3B21-95A3-FD6370000844"><apiname>CCoeControl::OfferKeyEventL()</apiname></xref>.
+If a UI control is a compound control, then forward key events to other controls
+within 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>.
+An example of an implementation is as follows:</p>
+<codeblock id="GUID-D93EBAD0-6C04-4E97-ABE2-9999EAA6F442" xml:space="preserve">KeyResponse CMyAppView::OfferKeyEventL(const TKeyEvent& aKeyEvent, TEventCode aType)
+ {
+ TKeyResponse response = EKeyWasNotConsumed;
+ //Check first that event type is EEventKey. It could be also
+ //EEventKeyUp or EEventKeyDown which just inform that some key
+ // is pressed or released.
+ if( aType == EEventKey )
+ {
+ // Take out the code of the key
+ TInt code = aKeyEvent.iCode;
+ TBuf< KMessageLength > buf;
+ buf.AppendNum( code );
+ // Show the code
+ iEikonEnv->InfoMsg(buf);
+ // Forward the key event to the focused control
+ if( iListBox->IsFocused() )
+ {
+ response = iListBox->OfferKeyEventL( aKeyEvent, aType );
+ }
+ else if( iEditView->IsFocused() )
+ {
+ response =
+ iEditView->OfferKeyEventL( aKeyEvent, aType );
+ }
+ }
+ // Return the key consumption status
+ return response;
+ }
+</codeblock>
+<p><parmname>CMyAppView</parmname> is a window-owning compound control
+and <parmname>iListBox</parmname> and <parmname>iEditView</parmname> are controls
+inside <parmname>CMyAppView</parmname>. Key events are offered to controls
+depending on the focus.</p>
+<p>If your implementation consumes the event handed to it, you must return <parmname>EKeyWasConsumed</parmname>.
+If your implementation does not process the event, your code must return <parmname>EKeyWasNotConsumed</parmname>.
+The application framework continues to offer the event to controls registered
+with the control stack from top to bottom until the event is consumed or until
+there are no more controls, in which case the event is handed to the UI controller
+by calling <xref href="GUID-92361912-7768-3D2C-835E-BD3EF1366D6D.dita#GUID-92361912-7768-3D2C-835E-BD3EF1366D6D/GUID-D4D9CA3F-19A2-3D29-91D6-0DD8C8B2C2FE"><apiname>CCoeAppUI::HandleKeyEventL()</apiname></xref> for the UI controller. </p>
+<p>Handle key events in your UI controller by overriding <xref href="GUID-92361912-7768-3D2C-835E-BD3EF1366D6D.dita#GUID-92361912-7768-3D2C-835E-BD3EF1366D6D/GUID-D4D9CA3F-19A2-3D29-91D6-0DD8C8B2C2FE"><apiname>CCoeAppUI::HandleKeyEventL()</apiname></xref>.
+An example of an implementation is as follows:</p>
+<codeblock id="GUID-3A2D3630-C28F-4165-8589-73AA4627D008" xml:space="preserve">TKeyResponse CMyViewAppUi::HandleKeyEventL( const TKeyEvent& aKeyEvent,TEventCode /*aType*/)
+ {
+ if( iTabGroup == NULL )
+ {
+ return EKeyWasNotConsumed;
+ }
+
+ TInt active = iTabGroup->ActiveTabIndex();
+ TInt count = iTabGroup->TabCount();
+
+ switch( aKeyEvent.iCode )
+ {
+ case EKeyLeftArrow:
+ if ( active > 0 )
+ {
+ active--;
+ iTabGroup->SetActiveTabByIndex( active );
+ // ActivateLocalViewL() is used to change the view.
+ // To change view from another application we would use ActivateViewL()
+ // Send an empty message
+ ActivateLocalViewL( TUid::Uid( iTabGroup->TabIdFromIndex( active ) ) );
+ }
+ break;
+ case EKeyRightArrow:
+ if( ( active + 1 ) < count )
+ {
+ active++;
+ iTabGroup->SetActiveTabByIndex( active );
+ // ActivateLocalViewL() is used to change the view.
+ // To change view from another application we would use ActivateViewL()
+ ActivateLocalViewL( TUid::Uid( iTabGroup->TabIdFromIndex( active ) ) );
+ }
+ break;
+ default:
+ return EKeyWasNotConsumed;
+ break;
+ }
+
+ return EKeyWasConsumed;
+ }
+</codeblock>
+<p><parmname>CMyAppView</parmname> is a UI controller that is using key
+events from the selection key of a device to switch between two <xref href="GUID-11967EBB-7439-3775-B287-7560ECA0AF1F.dita"><apiname>CAknView</apiname></xref>-derived
+views. <parmname>EKeyLeftArrow</parmname> and <parmname>EKeyRightArrow</parmname> are
+codes enumerated in <parmname>TKeyCode</parmname> and are contained in <parmname>KeyEvent.iCode</parmname>.</p>
+<note>
+<p>The above code snippet was taken from the <i>MyView</i> example application
+provided in the <parmname>Platform Application Views</parmname> package available
+from <xref href="http://www.forum.nokia.com/info/sw.nokia.com/id/226649f9-4118-4c8a-92e6-6d72fb251ae1/S60_Platform_Application_Views_v2_1_en.zip.html" scope="external">Forum Nokia</xref> . </p>
+</note>
+<p>See <xref href="GUID-B67B6ED5-6C8F-3B36-934C-B47A109A515F.dita"><apiname>TKeyCode</apiname></xref> for more information.</p>
+</conbody></concept>
\ No newline at end of file