Commands

diff -r 43e37759235e -r 51a74ef9ed63 Symbian3/SDK/Source/GUID-4941C035-C359-4968-9BD5-31F44EE5F810.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-4941C035-C359-4968-9BD5-31F44EE5F810.dita Wed Mar 31 11:11:55 2010 +0100 @@ -0,0 +1,145 @@ + + + + + +Commands +

The term command refers to events that are received when a device user +selects an option in the Options menu or presses a softkey (for more +information, see UI concepts). +The device user input results in the application framework returning a command +ID that corresponds to the softkey or Options menu selection. Command +IDs are mapped to the selection options in the CBA and Menu bar resource +definitions. You can use either custom command IDs, which must be defined +in your application hrh resource +file, or precompiled +values available from the Symbian platform 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:

EEikCmdExit, 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 Handling +EEikCmdExit.
+
EAknSoftKeyBack, which is delivered +in response to a device user pressing the Back 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 EEikCmdExit command.
EAknSoftkeyOptions, which is associated +with the Options softkey, is handled by the application +framework directly and results in the Options menu being +presented to the device user.

For more information on resource files, see Managing +resource files.

For an example of a resource file, see Resource +management example: HelloWorldBasic.

+Options menu +

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.

If the application above uses an Symbian +view architecture, then the command handling functions as follows.

If a device user selects Create New, +then the application framework returns the command associated with that menu +item to the view controller for +the view indicated by the first tab.
Since this command is unique to this view, the command must +be handled in the view controller for this view.
If there was an Exit menu item that +was applicable for the application generally, then you must pass the command +for this menu item to the UI +controller and handle the command there.

To handle commands, you must override CEikAppUi::HandleCommandL() .

The options are as follows:

In a traditional +Symbian UI application architecture, the command needs to be handled +in the UI controller. +An example of an implementation is as follows:
+ +void CMyCommandHandlingAppUi::HandleCommandL(TInt aCommand) + { + switch(aCommand) + { + case EEikCmdExit: + case EAknSoftkeyExit: + { + Exit(); + break; + } + + case EMyCommandID1: + { + //do something + } + break; + + default: + break; + } + } +
where EEikCmdExit is provided from the application +framework, EAknSoftkeyExit is the command ID that the +application framework returns when a device user presses the Back softkey, +and EMyCommandID1 is a command ID from your application hrh file.
+
For more information on the handling of the exit command IDs, see Handling +EEikCmdExit.
+ +
In an Symbian +view architecture, the command is received by the active view. +It should be handled by the view if the command is view specific, otherwise +it should be passed to the UI controller CAknViewAppUi(-derived +class). For an example of view-specific command handling, see the following:
+ +void CMyCommandHandlingViewClass::HandleCommandL(TInt aCommand) + { + switch ( aCommand ) + { + case EAknSoftkeyExit: + { + AppUi()->HandleCommandL(EEikCmdExit); + break; + } + + case EMyCommandID1: + { + // Do something. + break; + } + + default: + { + AppUi()->HandleCommandL( aCommand ); + break; + } + } + } + +
where EEikCmdExit is provided from the application +framework, EAknSoftkeyExit is the command ID that the +application framework returns when a device user presses the Back softkey, +and EMyCommandID1 is a command ID from your application hrh file.
+
In this example, the last case (default) hands over unhandled commands +to the UI controller.
+
For more information on the handling of the exit command IDs, see:
+ +

+ \ No newline at end of file