Commands

The term command refers to events that are received when a mobile device user selects an option in the Options menu or presses a softkey (for more information, see "UI concepts"). The mobile 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 S60 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 mobile 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.

For more information on the requirements for EAknSoftKeyBack behavior, see the S60 UI Style Guide.
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 mobile device user.

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

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

Figure 34: 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 S60 view architecture, then the command handling functions as follows.

If a mobile 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 OS UI 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 mobile 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 S60 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 mobile 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 "Handling EEikCmdExit".