Command

In Series 40 and S60 devices, Commands are mapped directly to a softkey or placed in an expandable menu (the common 'Options' menu) according to Nokia user interface guidelines. It is essential to use logically proper and correct types for Commands. If right types for the Commands are used, the Command mapping works as expected.

The placement of Commands in the UI is decided by assigning them a Command type and a priority value. The order of Commands of the same type is handled with the priority value. A Command that has been assigned the smaller priority value is placed before the other Commands of the same type in a menu. When Commands are presented in Options menu, the Commands mapped to the menu are shown in the following order based on their type:

  1. STOP

  2. OK

  3. CANCEL

  4. ITEM

  5. SCREEN

  6. HELP

  7. BACK

  8. EXIT

Commands can be divided into four categories:

Commonly, every Command is associated with a Displayable or a Form Item. Commands can generally be applied to any screen, including Alerts.

As the Commands handle the main functionality and navigation in the MIDlet, the developer MUST always add an EXIT Command in order for the application to allow mobile device users exit the application gracefully. If the application has more than one display, or has other components, the required navigation Commands to these items must be added as well.

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 S60, 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.

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 and how the EXIT Command is by default placed under the right softkey.

Figure 28: 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();
        }
    }
}

For more information about S60-specific Command features, see Command implementation notes.

© Nokia 2008.