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. 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 elements override this rule and place an element-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).

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

For information about supported new line character combinations, see section New line handling.

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 softkey labels and Command labels in the Options menu even when they are visible.

On Form, addition or 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 mapping to action buttons in the full touch UI

In the full touch UI, the header bar is displayed below the status bar and shows the title of the current view. The header bar contains placeholders for two action buttons to which Commands and IconCommands can be mapped:

• Action button 1 is positioned to the right of the view title and functions as the primary action button. It displays the highest-priority positive command. You can define a custom icon for the command by using an IconCommand.

• Action button 2 is positioned to the left of the view title and always shows an options icon. Selecting it opens the list of remaining commands (assuming any are available).

Figure: Action buttons in the header bar

For more information about the main elements of the full touch UI, see section Full touch devices.

Command mapping for Canvas and Form elements

The following table lists the various scenarios of how commands are mapped to the action buttons and the Back button. The scenarios only apply to commands added to Canvas or Form elements.

Ordering of commands under action button 2

Commands within a command list are shown in the following order:

1. Any STOP commands

2. Any OK commands

3. Any CANCEL commands

4. Any FORM ITEM commands

5. Any SCREEN commands

6. Any HELP commands

7. Any EXIT commands

UI element operations and item-specific commands are only accessible by a long tap. If there is more than one of any type of command, within each command type group placement, the individual commands are ordered according to the general rules specified above.

Command mapping in Nokia Asha software platform devices

In Nokia Asha software platform devices, up to four IconCommands can be mapped to CategoryBar.

Figure: IconCommands in CategoryBar and Commands in Options menu

Command mapping and handling

In Nokia Asha software platform devices, Commands are mapped to Options menu. The first Command (by priority) is shown on the bottom of the screen as a button within the Toolbar. All the other Commands are listed in the Options menu.

Options menu

The Options menu should contain functions related to the current view, and is presented as a textual list. It is initially hidden in the view, and an indicator is displayed when it is available. The Options menu is accessed by swiping up from bottom of the screen.

Commands in Options menu are shown in the order of their priority. Commands of the same priority are shown in the following order:

1. Any ITEM commands

2. Any STOP commands

3. Any CANCEL commands

4. Any EXIT commands

5. Any BACK commands

6. Any HELP commands

7. Any OK commands

8. Any SCREEN commands

Item-specific Commands should use Command.ITEM type. If there is more than one of any type of Command, within each Command type group placement, the individual Commands are ordered according to the general rules specified above. The order of Commands of the same type is done based on the Commands’ priority numbers.

On both Series 40 and Nokia Asha software platform devices, tapping outside the Options Menu closes the Menu. If the Options Menu contains more Commands than can fit in its visible area, dragging or flicking the Menu, scrolls through the items. On Series 40 touch and type devices, no scrollbar is shown, regardless of whether the menu needs scrolling. On Series 40 full touch the scrollbar is visible upon the launch of the Options Menu, and it is hidden upon inactivity and is brought back to the foreground when the user drags or flicks the list of available Commands. On Nokia Asha software platform devices, the scrollbar in Options Menu is always visible.

Back key

In Nokia Asha software platform devices, the back key is a hardware button located under the display.

The back key works as follows:

• Pressing back key in home screen, toggles between two home screens (activity screen and apps screen).

• Pressing back key in application view, takes back to previous UI state.

• Pressing and holding back key in any view will close current view and directly go to previously visited home screen.

• Pressing back key when both BACK and EXIT Commands are added to Displayable, the BACK Command takes precedence.

Command mapping and back key handling

The BACK and EXIT Commands when implemented in a MIDlet make the back key to work as follows:

• If Displayable has EXIT Command implemented, but not BACK Command, pressing back key closes the MIDlet.

• If Displayable has BACK Command implemented, pressing back key handles the BACK Command.

• If Displayable has BACK and EXIT Commands implemented, BACK Command is mapped to the Back key and EXIT Command is mapped to the Options menu.

• If EXIT Command is mapped to the back key, it is normally handled by using commandAction() method (it is possible, for example, to show confirmation dialog before exiting).

Command example

This example illustrates how Commands are mapped to the Options menu and the Toolbar on Nokia Asha software platform devices 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();
        }
    }
}

More information