|
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 mobile device |
|
14 user selects an option in the <b>Options</b> menu or presses a softkey (for |
|
15 more information, see <xref href="GUID-0F593BE1-1220-4403-B04E-B8E8A9A49701.dita">UI concepts</xref>). |
|
16 The mobile device user input results in the application framework returning |
|
17 a command ID that corresponds to the softkey or <b>Options</b> menu selection. |
|
18 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 |
|
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 mobile 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> |
|
39 <itemgroup> |
|
40 |
|
41 </itemgroup> |
|
42 </li> |
|
43 <li><p><parmname>EAknSoftkeyOptions</parmname>, which is associated |
|
44 with the <parmname>Options</parmname> softkey, is handled by the application |
|
45 framework directly and results in the <parmname>Options</parmname> menu being |
|
46 presented to the mobile device user.</p></li> |
|
47 </ul> |
|
48 <p>For more information on resource files, see <xref href="GUID-0FB60233-993A-4BF2-9E8C-E03AD092359B.dita">Managing |
|
49 resource files</xref>.</p> |
|
50 <p>For an example of a resource file, see <xref href="GUID-411ACFE6-0324-4330-ABCD-97A925759A3C.dita">Resource |
|
51 management example: HelloWorldBasic</xref>.</p> |
|
52 <fig id="GUID-2A400E35-185F-4E87-875E-DEB838D4A9A6"><title>Options menu</title><image href="GUID-5BCF45C6-B2F7-4078-AE6F-052128AC7FF7_d0e38954_href.png"/></fig> |
|
53 <p>Commands are passed to the object with which the menu is associated. |
|
54 The object that receives the command should handle the command if it is specific |
|
55 to the object. If the command is relevant to another object, then it should |
|
56 be passed onto the other application object. The actual implementation depends |
|
57 on the design of your application.</p> |
|
58 <p>If the application above uses an <xref href="GUID-68B999C2-0993-4804-9624-42C3D88BE5C7.dita">Symbian |
|
59 view architecture</xref>, then the command handling functions as follows.</p> |
|
60 <ul> |
|
61 <li><p>If a mobile device user selects <parmname>Create New</parmname>, |
|
62 then the application framework returns the command associated with that menu |
|
63 item to the <xref href="GUID-DAC32BB9-C0EB-42FF-A596-C2F1A90A4BD7.dita">view controller</xref> for |
|
64 the view indicated by the first tab.</p></li> |
|
65 <li><p>Since this command is unique to this view, the command must |
|
66 be handled in the view controller for this view.</p></li> |
|
67 <li><p>If there was an <parmname>Exit</parmname> menu item that |
|
68 was applicable for the application generally, then you must pass the command |
|
69 for this menu item to the <xref href="GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita">UI |
|
70 controller</xref> and handle the command there.</p></li> |
|
71 </ul> |
|
72 <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> |
|
73 <p>The options are as follows:</p> |
|
74 <ul> |
|
75 <li><p>In a <xref href="GUID-B5DE1C86-2B16-4B22-887F-7079E54A8ED6.dita">traditional |
|
76 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 |
|
77 example of an implementation is as follows:</p> |
|
78 <itemgroup> |
|
79 <codeblock id="GUID-29CD264C-D073-4145-9FF5-41C7D3FFA40C" xml:space="preserve">void CMyCommandHandlingAppUi::HandleCommandL(TInt aCommand) |
|
80 { |
|
81 switch(aCommand) |
|
82 { |
|
83 case EEikCmdExit: |
|
84 case EAknSoftkeyExit: |
|
85 { |
|
86 Exit(); |
|
87 break; |
|
88 } |
|
89 |
|
90 case EMyCommandID1: |
|
91 { |
|
92 //do something |
|
93 } |
|
94 break; |
|
95 |
|
96 default: |
|
97 break; |
|
98 } |
|
99 }</codeblock> |
|
100 <p>where <parmname>EEikCmdExit</parmname> is provided from the application |
|
101 framework, <parmname>EAknSoftkeyExit</parmname> is the command ID that the |
|
102 application framework returns when a mobile device user presses the <parmname>Back</parmname> softkey, |
|
103 and <parmname>EMyCommandID1</parmname> is a command ID from your application <parmname>hrh</parmname> file.</p> |
|
104 <p>For more information on the handling of the exit command IDs, see <xref href="GUID-11FE772A-E662-4B88-B871-97A40A40FBAB.dita">Handling |
|
105 EEikCmdExit</xref>.</p> |
|
106 </itemgroup> |
|
107 </li> |
|
108 <li><p>In an <xref href="GUID-68B999C2-0993-4804-9624-42C3D88BE5C7.dita">Symbian |
|
109 view architecture</xref>, the command is received by the active <xref href="GUID-DAC32BB9-C0EB-42FF-A596-C2F1A90A4BD7.dita">view</xref>. |
|
110 It should be handled by the view if the command is view specific, otherwise |
|
111 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 |
|
112 class). For an example of view-specific command handling, see the following: </p> |
|
113 <itemgroup> |
|
114 <codeblock id="GUID-C55E09E4-08A9-4997-B198-E00B61D24508" xml:space="preserve">void CMyCommandHandlingViewClass::HandleCommandL(TInt aCommand) |
|
115 { |
|
116 switch ( aCommand ) |
|
117 { |
|
118 case EAknSoftkeyExit: |
|
119 { |
|
120 AppUi()->HandleCommandL(EEikCmdExit); |
|
121 break; |
|
122 } |
|
123 |
|
124 case EMyCommandID1: |
|
125 { |
|
126 // Do something. |
|
127 break; |
|
128 } |
|
129 |
|
130 default: |
|
131 { |
|
132 AppUi()->HandleCommandL( aCommand ); |
|
133 break; |
|
134 } |
|
135 } |
|
136 } |
|
137 </codeblock> |
|
138 <p>where <parmname>EEikCmdExit</parmname> is provided from the application |
|
139 framework, <parmname>EAknSoftkeyExit</parmname> is the command ID that the |
|
140 application framework returns when a mobile device user presses the <parmname>Back</parmname> softkey, |
|
141 and <parmname>EMyCommandID1</parmname> is a command ID from your application <parmname>hrh</parmname> file.</p> |
|
142 <p>In this example, the last case (default) hands over unhandled commands |
|
143 to the UI controller.</p> |
|
144 <p>For more information on the handling of the exit command IDs, see <xref href="GUID-11FE772A-E662-4B88-B871-97A40A40FBAB.dita">Handling |
|
145 EEikCmdExit</xref>.</p> |
|
146 </itemgroup> |
|
147 </li> |
|
148 </ul> |
|
149 </conbody></concept> |