<?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-542550FA-F9F1-46D6-8182-6E7FAA013572" xml:lang="en"><title>Receiving

key event data in your application</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The <xref href="GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita">UI controller </xref>is

the default handler for key events. In order for other <xref href="GUID-5944FFF1-79C6-4F5E-95C8-F4833AFC64AB.dita">controls</xref> to

receive events, you must register them with the control stack with <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeAppUiClass.html#%3a%3aCCoeAppUi%3a%3aAddToStackL%28const%20MCoeView%20%26amp%3b%2cCCoeControl%20%2a%2cTInt%2cTInt%29" format="application/java-archive"><parmname>CCoeAppUi::AddToStackL()</parmname></xref>. Controls are

usually added to the control stack in the second phase constructor.</p>

<p>The options are as follows:</p>

<ul>

<li><p>In a <xref href="GUID-B5DE1C86-2B16-4B22-887F-7079E54A8ED6.dita">traditional

Symbian OS UI architecture</xref>, this is done in the UI controller construction

phase. An example of an implementation is as follows:</p>

<itemgroup>

<codeblock id="GUID-CC069DFD-545E-43BF-97A2-F76D2D0F903F" xml:space="preserve">void CAddressBookAppUi::ConstructL()

    {

    BaseConstructL();

    iCurrentView = CMyAppMainView::NewL( ClientRect() );

    AddToStackL( iCurrentView );

    }

</codeblock>

<p>This places <parmname>iCurrentView</parmname> on top of the control

stack, which means the UI controller is underneath it in the stack. When the

application framework passes an event to the application, the framework first

requests that <parmname>iCurrentView</parmname> handle it. If this control

does not consume the event, then the framework calls the method for the UI

controller to handle the event.</p>

<p><xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeAppUiClass.html#%3a%3aCCoeAppUi%3a%3aAddToStackL%28const%20MCoeView%20%26amp%3b%2cCCoeControl%20%2a%2cTInt%2cTInt%29" format="application/java-archive"><parmname>CCoeAppUi::AddToStackL()</parmname></xref> offers a parameter

to set the stack priority of a UI control.</p>

<p>You should use <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeAppUiClass.html#%3a%3aCCoeAppUi%3a%3aRemoveFromStack%28CCoeControl%20%2a%29" format="application/java-archive"><parmname>CCoeAppUi::RemoveFromStackL</parmname></xref> to remove a control from

the control stack when it should no longer receive events.</p>

</itemgroup>

</li>

<li><p>In an <xref href="GUID-68B999C2-0993-4804-9624-42C3D88BE5C7.dita">Symbian

view architecture</xref>, this is typically done with <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknView.html#486d490d911ce5e9495e0ee19b0442db" format="application/java-archive"><parmname>CAknView::DoActivateL()</parmname></xref> when

the UI controls are constructed. An example of an implementation for this

approach is as follows:</p>

<itemgroup>

<codeblock id="GUID-4DEDAE29-C6D9-4004-9687-530398F84E4A" xml:space="preserve">void CMyView::DoActivateL(const TVwsViewId&amp;, TUid , const TDesC8&amp;)

    {

    if (!iUIControl)

        {

        iUIControl = CMyUiControl::NewL( this, ClientRect() );

        AppUi()->AddToStackL( *this, iUiControl );

        } 

   }

</codeblock>

<p>This places <parmname>iUiControl</parmname> on top of the control stack,

which means the UI controller is underneath it in the stack. When the application

framework passes an event to the application, the framework first requests

that <parmname>iUIControl</parmname> handle it. If this control does not consume

the event, then the framework calls the method for the UI controller to handle

the event.</p>

<p><xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeAppUiClass.html#%3a%3aCCoeAppUi%3a%3aAddToStackL%28const%20MCoeView%20%26amp%3b%2cCCoeControl%20%2a%2cTInt%2cTInt%29" format="application/java-archive"><parmname>CCoeAppUi::AddToStackL()</parmname></xref> offers a parameter

to set the stack priority for a UI control.</p>

<p>You should use <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeAppUiClass.html#%3a%3aCCoeAppUi%3a%3aRemoveFromStack%28CCoeControl%20%2a%29" format="application/java-archive"><parmname>CCoeAppUi::RemoveFromStackL</parmname></xref> to remove a control from

the control stack when it should no longer receive events.</p>

</itemgroup>

</li>

</ul>