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.

Figure 1. 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:

• Handling EEikCmdExit