Command

Invoking Commands

Commands mapped to softkeys conform to the following rules:

• Softkey 1 (left softkey)

  Multiple Commands can be mapped to the left softkey. If there are multiple Commands, an Options label is presented on the left softkey and selecting it opens a menu of commands. If there is only a single 'positive' Command (OK, ITEM, SCREEN, or HELP), it is presented directly on the left softkey. If there is more than one 'negative' Command, they are presented in the Options menu that is accessed with the left softkey.

• Softkey 2 (right softkey)

  There can only be one 'negative' Command (STOP, CANCEL, BACK, or EXIT) mapped to the right softkey, and the Command mapped there is directly invoked by the softkey press. If there are multiple 'negative' Commands, the one that has the highest priority value is mapped to the right softkey and the rest are placed in the menu of commands under the left softkey.

• Selection key (formerly middle softkey)

  In Series 40, only a single context sensitive Command (OK, ITEM) is mapped to the selection key. In Symbian, multiple Commands can be mapped to the Selection key. If there's only a single Command, it is shown directly in softkey, otherwise the Commands are visible in a context sensitive menu that can be opened with the Selection key.

  Note: Some UI components override this rule and place a component specific operation directly to the Selection key. For example, POPUP ChoiceGroup has Open operation in the Selection key.

• Enter key (on QWERTY keyboard)

  Has the same effect as the Selection key, unless it is bound to a displayable specific operation.

The behavior that the command activates is not encapsulated in the specific object. This means that when the mobile device user invokes a Command, the actual functionality is not executed automatically by the implementation. Instead, the action is defined in a CommandListener interface.

Labeling Commands

Application specified Command labels are used:

• as a label in the softkey to which the Command was mapped (in case where only one Command is mapped to a specific softkey) or

• as a label in the Options or context sensitive menu item (in case where more than one Command is mapped to a softkey) or

In S60 3rd Edition FP 2 onwards, the Selection key has a label describing the function attached to it:

• If the Selection key executes a Command, the short label of the Command is shown as the Selection key label.

• If the Selection key opens a context sensitive menu, a menu icon is shown as the Selection key label.

• If the Selection key does the same operation as left softkey, a platform provided dot icon is shown as the Selection key label.

The Selection key labeling functionality is available only in the portrait mode. The Selection key functions normally both in portrait and in landscape modes, but in landscape mode the label cannot be shown due to space restrictions.

Dynamic command addition or removal

If a Command is added or removed after the Commands for a displayable have been presented to the user, all the Commands are mapped again based on the rules presented in the previous sections. This may update the softkeys and Command list items even when they are visible.

Form, addition / removal of Commands may be performed by both the implementation and the MIDlet, as the user traverses different Items, since each Item may have its own specific Commands. This may result in scenarios where sometimes a particular Command is displayed on the left softkey, while at other times "Options" is displayed.

If another Displayable appears over the Options list while it is open (by a system application or by the MIDlet itself), then upon that Displayable’s removal the user will not be returned to the options list.

Command example

This example illustrates how Commands are mapped to softkeys. Commands in this example are used to insert a short string to a TextBox or to exit the MIDlet. Note how the priority setting affects the order of Commands in the left softkey. The EXIT Command is also placed under the right softkey, but is covered by the default Cancel text when the left softkey menu is open.

Figure: An example showing Commands mapped to softkeys

Source code for the example:

import javax.microedition.midlet.*;
import javax.microedition.lcdui.*;

public class ExampleCommand extends MIDlet implements CommandListener {
    
    private Display display;
    private TextBox textbox;
    private Command apple;
    private Command orange;
    private Command pear;
    private Command lemon;
    private Command exit;
    private Command clear;
    
    public ExampleCommand() {
        display = Display.getDisplay(this);
        apple = new Command("Apple", Command.SCREEN, 1);
        orange = new Command("Orange", Command.SCREEN, 4);
        pear = new Command("Pear", Command.SCREEN, 2);
        lemon = new Command("Lemon", Command.SCREEN, 3);
        exit = new Command("Exit", Command.EXIT, 1);
        clear = new Command("Clear", Command.SCREEN, 5);
        textbox = new TextBox("Today's menu:", "The command you select will be presented here", 100, TextField.ANY);
        textbox.addCommand(exit);
        textbox.addCommand(apple);
        textbox.addCommand(orange);
        textbox.addCommand(pear);
        textbox.addCommand(lemon);
        textbox.addCommand(clear);
        textbox.setCommandListener(this);
        }

    public void startApp() {
        display.setCurrent(textbox);
        }

    public void pauseApp() {
        }

    public void destroyApp(boolean unconditional) {
        }
    
    public void commandAction(Command command, Displayable displayable) {
        if (command == apple) {
            textbox.setString(apple.getLabel() + " selected");
            }
        else if (command == orange) {
            textbox.setString(orange.getLabel() + " selected");
            }
        else if (command == lemon) {
            textbox.setString(lemon.getLabel() + " selected");
            }        
        else if (command == pear) {
            textbox.setString(pear.getLabel() + " selected");
            }        
        else if (command == clear) {
          textbox.setString("");
        }
        else if (command == exit) {
            destroyApp(false);
            notifyDestroyed();
        }
    }
}