--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-4941C035-C359-4968-9BD5-31F44EE5F810.dita Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,149 @@
+<?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 mobile 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 mobile 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 mobile 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>
+<itemgroup>
+
+</itemgroup>
+</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 mobile 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-2A400E35-185F-4E87-875E-DEB838D4A9A6"><title>Options menu</title><image href="GUID-5BCF45C6-B2F7-4078-AE6F-052128AC7FF7_d0e38954_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 mobile 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="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/UIKON/CEikAppUiClass.html#%3a%3aCEikAppUi%3a%3aHandleCommandL%28%29" format="application/java-archive"><parmname>CEikAppUi::HandleCommandL</parmname></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 OS UI 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 mobile 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="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknViewAppUi.html" format="application/java-archive"><parmname>CAknViewAppUi</parmname></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 mobile 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 <xref href="GUID-11FE772A-E662-4B88-B871-97A40A40FBAB.dita">Handling
+EEikCmdExit</xref>.</p>
+</itemgroup>
+</li>
+</ul>
+</conbody></concept>
\ No newline at end of file