Programming Wireless Devices with the Java2 Platform

8.5 Commands

Abstract Commands are the operations that the applications add to the user interface. Commands can be added to all Displayables, so they are part of the application when using both high-level or low-level API. The most common task for Commands is to provide users with a way to navigate between different Displayables of an application. Normally, if there are no Commands in a Displayable, the user has no way to proceed to other Displayables.

Commands are added to a Displayable using addCommand method. There is also removeCommand to remove already-added commands. This allows to dynamically change available operations within displayables.

When the user selects a Command from the user interface, the device calls the CommandListener's commandAction method and passes the Command object and the Displayable instance in which the Command was activated.

In the next sections, the idea of Command abstraction is described first. Then the proper use of Commands in applications is summarized.

8.5.1 Command Mapping to Device User Interface

Since the MIDP user interface API is highly abstract, it does not dictate any concrete user interaction technique such as softkeys,^[4] buttons, or menus. An abstract command mechanism allows an application to adjust to the widely varying input mechanisms of MIDP target devices and also allows it to be unaware of device specifics, such as number of keys, key locations, and key bindings. Low-level user interactions such as traversal or scrolling are not visible to the application, which helps the devices implement the high-level components in very different user interface styles. This also leverages application portability between devices.

^[4] Softkeys are very common in mobile devices. Softkey is a keypad key positioned near the device display so that there is an changeable label present on the display that indicates the operation associated with the softkey.

MIDP applications define Commands, and the implementation can provide user control over these with softkeys, buttons, menus, or whatever mechanisms are appropriate for the device. Generally, Commands may be implemented using any user interface construct that has the semantics for activating a single action.

Commands are added to a Displayable (Canvas or Screen) with the method addCommand of class Displayable. The Commands can also be removed with the removeCommand method. This allows, for example, the application to control which Commands are available at a given time, based on user interaction. Some Commands can be paired with others or presented only in certain situations or context.

Each command has a type and a priority. Command types and priorities allow the device to place the commands to match the native user interface style of the device, and the device might put certain types of commands in standard places. For example, the "Go back" operation might always be mapped to the right softkey in a user interface style of a device. The device may decide to map a command with the BACK type to the right softkey. The Command class allows the application to communicate the abstract semantics of an action associated with a Command to the device so that action placements that are standard for that device can be used.

However, the device does not provide any automatic behavior for the Command. The type of a Command is used only for mapping it onto the user interface. The actual behavior of a Command is always implemented by the application in a CommandListener, which is set by the application to the Displayable.

The mapping of Commands to concrete user interface constructs might also depend on the total number of commands. If an application uses more commands than can be mapped onto the available physical buttons on a particular device, the device may use an alternate human interface such as a menu. For example, the abstract commands that cannot be mapped onto physical buttons may be placed in a menu, and the label "Menu" can be mapped onto one of the programmable buttons.

8.5.2 Command Properties

Each Command object has a string label, a command type and a priority:

• Label: The label strings are what the application requests to be shown to the user to represent this Command. A single Command can have two versions of labels: short and long. The long label is optional. The implementation decides whether the short or long version is appropriate for a given situation. For example, a device can choose to use a short version of a given Command near a softkey and the long version of the Command in a menu. The short label string should be as short as possible so that it consumes a minimum of screen real estate. The long label can be longer and more descriptive, but it should be no longer than a few words. For example, a Command's short label might be "Play," and its long label might be "Play Sound Clip."

• Command type: The purpose of a command, selected from a defined set of constant types. The defined types are BACK, CANCEL, EXIT, HELP, ITEM, OK, SCREEN, and STOP. The implementation will use the command type for placing the command appropriately within the device's user interface. Commands with similar types may, for example, be found near each other in certain dedicated places in the user interface. Often, devices will have policy for the placement and presentation of certain operations. For example, a "backward navigation" command might be always placed on the right softkey on a particular device, but it might be placed on the left softkey on a different device. The Command class provides a fixed set of command types that provide MIDlets with the capability to tell the device implementation the intent of a Command. The application can use the BACK command type for commands that perform backward navigation. On the devices mentioned above, this type of information would be used to assign the command to the appropriate softkey.

• Priority: A number that defines the relative importance between Commands of the same type on the same Displayable. A lower number indicates greater importance. A Command with a lower numeric priority value is more important than a Command of the same type but with a higher int priority value. If possible, a more important Command is presented before, or is more easily accessible than, a less important one.

Typically, the implementation first chooses the placement of a Command based on the type of Command and then places similar Commands based on a priority order. This could mean that the Command with the highest priority (lowest numeric priority value) is placed so that the user can trigger it directly and that Commands with a lower priority (higher numeric priority value) are placed on a menu. It is not an error to define Commands on the same screen with the same priorities and types. If this occurs, the implementation will choose the order in which the Commands are presented.

8.5.3 Command Types

Since the command type is the most important means for an application to adapt to the user interface style of a device, it is important that the applications correctly define the command types. Selecting a correct type for a Command makes applications more consistent with the native applications in a device. There are six command types that are used for more specific purposes:

• BACK: Returns the user to the logically previous screen. The actual jump to the previous screen is done by the CommandListener provided by the application. The application is responsible, for example, for calling the setCurrent method in CommandListener to change the current displayable to the previous one. Note that the application defines the actual action, since the previous screen may not always be the logically correct place to jump to.

• OK and CANCEL: Standard positive and negative answers to a dialog implemented by the current screen. With the OK command type, the application hints to the implementation that the user wants to use the command to confirm the data that has been entered in the current screen and to proceed to the next logical screen. With the CANCEL command type, the application hints to the implementation that the user wants to dismiss the current screen without taking any action on the data that has been entered in the current screen, and that the user (usually) wants to return to the prior screen. OK and CANCEL types should be used together if both positive and negative responses are available in a dialog. In many cases CANCEL is interchangeable with BACK, but BACK should be used for navigation only.

• HELP: Activates online help. The help information should be presented using the Form class.

• EXIT: Used for exiting the application. All applications should provide an exit function, and thus should have at least one EXIT type command.

• STOP: Stops some currently running process, operation, or other action. With this command type, the application hints to the implementation that the user will use this command to stop any currently running process visible to the user on the current screen. Examples of running processes might include downloading or sending of data. Use of the STOP command does not necessarily imply a switch to another screen. STOP must not be used when Command is used to close the application; in this case the EXIT type must be used.

If none of the above command types describe the intent of the Command, then one of the two more generic command types must be used:

• ITEM: With this command type the application can hint to the implementation that the command is specific to the items of the Screen or the elements of a Choice. Normally this means that command relates to the focused item or element. For example, an e-mail application might present the list of mail headers using a List screen. "Delete" or "Read" labeled commands in the List have ITEM type. Delete or Read commands only affect the highlighted List element, not all the elements in the List. The commands either delete the mail or open the mail in reader view.

• SCREEN: This command type is used for commands that generally relate to or affect all of the items of a Screen or elements of a List. Examples could be "Delete all," "Load," or "Save." The SCREEN type should be used also if no other type is relevant for the intent of a Command. A SCREEN command generally applies to the entire screen contents or to navigation among screens. This is in contrast with the ITEM type, which applies to the currently activated or focused item or element contained within the screen.

class CommandExample extends Canvas implements CommandListener {
    Command save = new Command("Save", Command.SCREEN, 1);
    Command soundOff = new Command("Sound off", Command.SCREEN, 2);
    Command soundOn = new Command("Sound on", Command.SCREEN, 2);
    Command exit = new Command("Exit", Command.EXIT, 3);
    MIDlet midlet;

    public CommandExample(MIDlet owner) {
        midlet = owner;
        setCommandListener(this);
        addCommand(save);
        addCommand(soundOff);
        addCommand(exit);
    }

    public void setSound(boolean sound) {
        // ... implementation-dependent ...
    }

    public void paint(Graphics g) {
        // ... implementation-dependent ...
    }

    public void commandAction(Command cmd, Displayable d) {
        // (see code in next section)
    }
}

8.5.4 Command Listeners

The application-level handling of Commands is based on a listener model. Each Displayable object has a single listener. When the user invokes a Command on a Displayable, its listener is called. Listeners are registered using the method Displayable.setCommandListener. To define itself as a listener, an object must implement the interface CommandListener, which has following method:

void commandAction(Command c, Displayable d)

The application receives these command events if the Screen or Canvas has attached Commands and if there is a registered listener. Only a unicast version of the listener model is adopted, so the Screen or Canvas can have only one listener at a time. Here is a sample CommandListener interface method implementation for the CommandExample class defined above.

public void commandAction(Command cmd, Displayable d) {
    if (cmd == save) {
        // Save game state and show confirmation dialog
        Alert alert = new Alert(null, "Saved",
                                null, AlertType.CONFIRMATION);
        Display.getDisplay(midlet).setCurrent(alert);
    } else if (cmd == soundOff) {
        removeCommand(soundOff);
        addCommand(soundOn);
        setSound(false);
        Alert alert = new Alert(null, "Sound off",
                                null, AlertType.CONFIRMATION);
        Display.getDisplay(midlet).setCurrent(alert);
    } else if (cmd == soundOn) {
        removeCommand(soundOn);
        addCommand(soundOff);
        setSound(true);
        Alert alert = new Alert(null, "Sound on",
                                null, AlertType.CONFIRMATION);
        Display.getDisplay(midlet).setCurrent(alert);
    } else if (cmd == exit) {
        // Exit the application
        midlet.notifyDestroyed();
    }
}