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-4941C035-C359-4968-9BD5-31F44EE5F810" xml:lang="en"><title>Commands</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    13 <p>The term command refers to events that are received when a device user

    14 selects an option in the <b>Options</b> menu or presses a softkey (for more

    15 information, see <xref href="GUID-0F593BE1-1220-4403-B04E-B8E8A9A49701.dita">UI concepts</xref>).

    16 The device user input results in the application framework returning a command

    17 ID that corresponds to the softkey or <b>Options</b> menu selection. Command

    18 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

    19 definitions. You can use either custom command IDs, which must be defined

    20 in your application <xref href="GUID-D52E98C3-F5EE-4CE1-A4F5-2EF41A066B8A.dita"><parmname>hrh</parmname></xref> resource

    21 file, or <xref href="GUID-CBB00F6A-CBA7-4872-B0A1-A86A863725F5.dita">precompiled

    22 values available from the Symbian platform</xref> in your resource definitions.

    23 At runtime, the application framework catches the command ID values and passes

    24 them to the application that has focus for handling. The following commands

    25 have special requirements:</p>

    26 <ul>

    27 <li><p><parmname>EEikCmdExit</parmname>, which is sent by the application

    28 framework to exit open applications. This command ID must not be used in the

    29 resource file definitions, as it is reserved for the application framework.

    30 For more information on the special requirements for handling this command,

    31 see <xref href="GUID-11FE772A-E662-4B88-B871-97A40A40FBAB.dita">Handling

    32 EEikCmdExit</xref>.</p>

    33 </li>

    34 <li><p><parmname>EAknSoftKeyBack</parmname>, which is delivered

    35 in response to a device user pressing the <parmname>Back</parmname> softkey.

    36 The behavior required in response to this command depends on the context,

    37 but if an exit is required it needs to be handled in the same manner as with

    38 the <parmname>EEikCmdExit</parmname> command.</p></li>

    39 <li><p><parmname>EAknSoftkeyOptions</parmname>, which is associated

    40 with the <parmname>Options</parmname> softkey, is handled by the application

    41 framework directly and results in the <parmname>Options</parmname> menu being

    42 presented to the device user.</p></li>

    43 </ul>

    44 <p>For more information on resource files, see <xref href="GUID-0FB60233-993A-4BF2-9E8C-E03AD092359B.dita">Managing

    45 resource files</xref>.</p>

    46 <p>For an example of a resource file, see <xref href="GUID-411ACFE6-0324-4330-ABCD-97A925759A3C.dita">Resource

    47 management example: HelloWorldBasic</xref>.</p>

    48 <fig id="GUID-9BA6CBBE-E2F5-4C23-A528-F49A9467F542"><title>Options menu</title><image href="GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e42562_href.png"/></fig>

    49 <p>Commands are passed to the object with which the menu is associated.

    50 The object that receives the command should handle the command if it is specific

    51 to the object. If the command is relevant to another object, then it should

    52 be passed onto the other application object. The actual implementation depends

    53 on the design of your application.</p>

    54 <p>If the application above uses an <xref href="GUID-68B999C2-0993-4804-9624-42C3D88BE5C7.dita">Symbian

    55 view architecture</xref>, then the command handling functions as follows.</p>

    56 <ul>

    57 <li><p>If a device user selects <parmname>Create New</parmname>,

    58 then the application framework returns the command associated with that menu

    59 item to the <xref href="GUID-DAC32BB9-C0EB-42FF-A596-C2F1A90A4BD7.dita">view controller</xref> for

    60 the view indicated by the first tab.</p></li>

    61 <li><p>Since this command is unique to this view, the command must

    62 be handled in the view controller for this view.</p></li>

    63 <li><p>If there was an <parmname>Exit</parmname> menu item that

    64 was applicable for the application generally, then you must pass the command

    65 for this menu item to the <xref href="GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita">UI

    66 controller</xref> and handle the command there.</p></li>

    67 </ul>

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

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

    70 <ul>

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

    72 Symbian UI application architecture</xref>, the command needs to be handled

    73 in the <xref href="GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita">UI controller</xref>.

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

    75 <itemgroup>

    76 <codeblock id="GUID-29CD264C-D073-4145-9FF5-41C7D3FFA40C" xml:space="preserve">void CMyCommandHandlingAppUi::HandleCommandL(TInt aCommand)

    77     {

    78     switch(aCommand)

    79         {

    80         case EEikCmdExit:

    81         case EAknSoftkeyExit:

    82             {

    83             Exit();

    84             break;

    85             }

    86 

    87         case EMyCommandID1:

    88            {

    89            //do something

    90            }

    91            break;

    92             

    93        default:

    94            break;

    95        }

    96    }</codeblock>

    97 <p>where <parmname>EEikCmdExit</parmname> is provided from the application

    98 framework, <parmname>EAknSoftkeyExit</parmname> is the command ID that the

    99 application framework returns when a device user presses the <parmname>Back</parmname> softkey,

   100 and <parmname>EMyCommandID1</parmname> is a command ID from your application <parmname>hrh</parmname> file.</p>

   101 <p>For more information on the handling of the exit command IDs, see <xref href="GUID-11FE772A-E662-4B88-B871-97A40A40FBAB.dita">Handling

   102 EEikCmdExit</xref>.</p>

   103 </itemgroup>

   104 </li>

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

   106 view architecture</xref>, the command is received by the active <xref href="GUID-DAC32BB9-C0EB-42FF-A596-C2F1A90A4BD7.dita">view</xref>.

   107 It should be handled by the view if the command is view specific, otherwise

   108 it should be passed to the UI controller <xref href="GUID-2DBA2DA9-3DA7-381C-842C-9F6FEEDF973E.dita"><apiname>CAknViewAppUi</apiname></xref>(-derived

   109 class). For an example of view-specific command handling, see the following: </p>

   110 <itemgroup>

   111 <codeblock id="GUID-C55E09E4-08A9-4997-B198-E00B61D24508" xml:space="preserve">void CMyCommandHandlingViewClass::HandleCommandL(TInt aCommand)

   112     {   

   113     switch ( aCommand )

   114         {

   115         case EAknSoftkeyExit:

   116             {

   117             AppUi()->HandleCommandL(EEikCmdExit);

   118             break;

   119             }

   120 

   121         case EMyCommandID1:

   122             {

   123             // Do something.

   124             break;

   125             }

   126 

   127         default:

   128             {

   129             AppUi()->HandleCommandL( aCommand );

   130             break;

   131             }

   132         }

   133     }

   134 </codeblock>

   135 <p>where <parmname>EEikCmdExit</parmname> is provided from the application

   136 framework, <parmname>EAknSoftkeyExit</parmname> is the command ID that the

   137 application framework returns when a device user presses the <parmname>Back</parmname> softkey,

   138 and <parmname>EMyCommandID1</parmname> is a command ID from your application <parmname>hrh</parmname> file.</p>

   139 <p>In this example, the last case (default) hands over unhandled commands

   140 to the UI controller.</p>

   141 <p>For more information on the handling of the exit command IDs, see:</p>

   142 </itemgroup>

   143 </li>

   144 </ul>

   145 </conbody></concept>