<?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&amp; 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&lt; KMessageLength &gt; buf;
        buf.AppendNum( code );
        // Show the code
        iEikonEnv-&gt;InfoMsg(buf);
        // Forward the key event to the focused control
        if( iListBox-&gt;IsFocused() )
            {
            response = iListBox-&gt;OfferKeyEventL( aKeyEvent, aType );
            }
        else if( iEditView-&gt;IsFocused() )
            {
            response =
            iEditView-&gt;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&amp; aKeyEvent,TEventCode /*aType*/)
    {
    if( iTabGroup == NULL )
        {
        return EKeyWasNotConsumed;
        }

    TInt active = iTabGroup-&gt;ActiveTabIndex();
    TInt count = iTabGroup-&gt;TabCount();

    switch( aKeyEvent.iCode )
        {
        case EKeyLeftArrow:
            if ( active &gt; 0 )
                {
                active--;
                iTabGroup-&gt;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-&gt;TabIdFromIndex( active ) ) );
                }
            break;
        case EKeyRightArrow:
            if( ( active + 1 ) &lt; count )
                {
                active++;
                iTabGroup-&gt;SetActiveTabByIndex( active );
                // ActivateLocalViewL() is used to change the view. 
                // To change view from another application we would use ActivateViewL()
                ActivateLocalViewL( TUid::Uid( iTabGroup-&gt;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>