<?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()->HandleCommandL(EEikCmdExit);

            break;

            }

        case EMyCommandID1:

            {

            // Do something.

            break;

            }

        default:

            {

            AppUi()->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>