<?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-4941C035-C359-4968-9BD5-31F44EE5F810" xml:lang="en"><title>Commands</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>The term command refers to events that are received when a device user
selects an option in the <b>Options</b> menu or presses a softkey (for more
information, see <xref href="GUID-0F593BE1-1220-4403-B04E-B8E8A9A49701.dita">UI concepts</xref>).
The device user input results in the application framework returning a command
ID that corresponds to the softkey or <b>Options</b> menu selection. Command
IDs are mapped to the selection options in the <xref href="GUID-A4F3738C-CBFD-4151-9132-26FE05966715.dita">CBA</xref> and <xref href="GUID-5918ED8A-B26B-41A0-94A6-AB6D51BF80A1.dita">Menu bar</xref> resource
definitions. You can use either custom command IDs, which must be defined
in your application <xref href="GUID-D52E98C3-F5EE-4CE1-A4F5-2EF41A066B8A.dita"><parmname>hrh</parmname></xref> resource
file, or <xref href="GUID-CBB00F6A-CBA7-4872-B0A1-A86A863725F5.dita">precompiled
values available from the Symbian platform</xref> in your resource definitions.
At runtime, the application framework catches the command ID values and passes
them to the application that has focus for handling. The following commands
have special requirements:</p>
<ul>
<li><p><parmname>EEikCmdExit</parmname>, which is sent by the application
framework to exit open applications. This command ID must not be used in the
resource file definitions, as it is reserved for the application framework.
For more information on the special requirements for handling this command,
see <xref href="GUID-11FE772A-E662-4B88-B871-97A40A40FBAB.dita">Handling
EEikCmdExit</xref>.</p>
</li>
<li><p><parmname>EAknSoftKeyBack</parmname>, which is delivered
in response to a device user pressing the <parmname>Back</parmname> softkey.
The behavior required in response to this command depends on the context,
but if an exit is required it needs to be handled in the same manner as with
the <parmname>EEikCmdExit</parmname> command.</p></li>
<li><p><parmname>EAknSoftkeyOptions</parmname>, which is associated
with the <parmname>Options</parmname> softkey, is handled by the application
framework directly and results in the <parmname>Options</parmname> menu being
presented to the device user.</p></li>
</ul>
<p>For more information on resource files, see <xref href="GUID-0FB60233-993A-4BF2-9E8C-E03AD092359B.dita">Managing
resource files</xref>.</p>
<p>For an example of a resource file, see <xref href="GUID-411ACFE6-0324-4330-ABCD-97A925759A3C.dita">Resource
management example: HelloWorldBasic</xref>.</p>
<fig id="GUID-9BA6CBBE-E2F5-4C23-A528-F49A9467F542"><title>Options menu</title><image href="GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e36995_href.png"/></fig>
<p>Commands are passed to the object with which the menu is associated.
The object that receives the command should handle the command if it is specific
to the object. If the command is relevant to another object, then it should
be passed onto the other application object. The actual implementation depends
on the design of your application.</p>
<p>If the application above uses an <xref href="GUID-68B999C2-0993-4804-9624-42C3D88BE5C7.dita">Symbian
view architecture</xref>, then the command handling functions as follows.</p>
<ul>
<li><p>If a device user selects <parmname>Create New</parmname>,
then the application framework returns the command associated with that menu
item to the <xref href="GUID-DAC32BB9-C0EB-42FF-A596-C2F1A90A4BD7.dita">view controller</xref> for
the view indicated by the first tab.</p></li>
<li><p>Since this command is unique to this view, the command must
be handled in the view controller for this view.</p></li>
<li><p>If there was an <parmname>Exit</parmname> menu item that
was applicable for the application generally, then you must pass the command
for this menu item to the <xref href="GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita">UI
controller</xref> and handle the command there.</p></li>
</ul>
<p>To handle commands, you must override <xref href="GUID-1185F595-0488-3E93-8D60-6B3A1A3AC32E.dita#GUID-1185F595-0488-3E93-8D60-6B3A1A3AC32E/GUID-D6E5C363-CF39-3E56-B717-57CCEE8DC96F"><apiname>CEikAppUi::HandleCommandL()</apiname></xref> .</p>
<p>The options are as follows:</p>
<ul>
<li><p>In a <xref href="GUID-B5DE1C86-2B16-4B22-887F-7079E54A8ED6.dita">traditional
Symbian UI application architecture</xref>, the command needs to be handled
in the <xref href="GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita">UI controller</xref>.
An example of an implementation is as follows:</p>
<itemgroup>
<codeblock id="GUID-29CD264C-D073-4145-9FF5-41C7D3FFA40C" xml:space="preserve">void CMyCommandHandlingAppUi::HandleCommandL(TInt aCommand)
    {
    switch(aCommand)
        {
        case EEikCmdExit:
        case EAknSoftkeyExit:
            {
            Exit();
            break;
            }

        case EMyCommandID1:
           {
           //do something
           }
           break;
            
       default:
           break;
       }
   }</codeblock>
<p>where <parmname>EEikCmdExit</parmname> is provided from the application
framework, <parmname>EAknSoftkeyExit</parmname> is the command ID that the
application framework returns when a device user presses the <parmname>Back</parmname> softkey,
and <parmname>EMyCommandID1</parmname> is a command ID from your application <parmname>hrh</parmname> file.</p>
<p>For more information on the handling of the exit command IDs, see <xref href="GUID-11FE772A-E662-4B88-B871-97A40A40FBAB.dita">Handling
EEikCmdExit</xref>.</p>
</itemgroup>
</li>
<li><p>In an <xref href="GUID-68B999C2-0993-4804-9624-42C3D88BE5C7.dita">Symbian
view architecture</xref>, the command is received by the active <xref href="GUID-DAC32BB9-C0EB-42FF-A596-C2F1A90A4BD7.dita">view</xref>.
It should be handled by the view if the command is view specific, otherwise
it should be passed to the UI controller <xref href="GUID-2DBA2DA9-3DA7-381C-842C-9F6FEEDF973E.dita"><apiname>CAknViewAppUi</apiname></xref>(-derived
class). For an example of view-specific command handling, see the following: </p>
<itemgroup>
<codeblock id="GUID-C55E09E4-08A9-4997-B198-E00B61D24508" xml:space="preserve">void CMyCommandHandlingViewClass::HandleCommandL(TInt aCommand)
    {   
    switch ( aCommand )
        {
        case EAknSoftkeyExit:
            {
            AppUi()-&gt;HandleCommandL(EEikCmdExit);
            break;
            }

        case EMyCommandID1:
            {
            // Do something.
            break;
            }

        default:
            {
            AppUi()-&gt;HandleCommandL( aCommand );
            break;
            }
        }
    }
</codeblock>
<p>where <parmname>EEikCmdExit</parmname> is provided from the application
framework, <parmname>EAknSoftkeyExit</parmname> is the command ID that the
application framework returns when a device user presses the <parmname>Back</parmname> softkey,
and <parmname>EMyCommandID1</parmname> is a command ID from your application <parmname>hrh</parmname> file.</p>
<p>In this example, the last case (default) hands over unhandled commands
to the UI controller.</p>
<p>For more information on the handling of the exit command IDs, see:</p>
</itemgroup>
</li>
</ul>
</conbody></concept>