<?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< 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&amp; 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>