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

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

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

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

    16 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

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

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

    19 <ul>

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

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

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

    23 <itemgroup>

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

    25     {

    26     BaseConstructL();

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

    28     AddToStackL( iCurrentView );

    29     }

    30 </codeblock>

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

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

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

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

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

    36 controller to handle the event.</p>

    37 <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

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

    39 <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

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

    41 </itemgroup>

    42 </li>

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

    44 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

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

    46 approach is as follows:</p>

    47 <itemgroup>

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

    49     {

    50     if (!iUIControl)

    51         {

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

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

    54         } 

    55    }

    56 </codeblock>

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

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

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

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

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

    62 the event.</p>

    63 <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

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

    65 <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

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

    67 </itemgroup>

    68 </li>

    69 </ul>

    70 </conbody></concept>