Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.microedition.lcdui
Class Command

    java.lang.Object
      |
      +--javax.microedition.lcdui.Command

public class Command
extends Object

The Command class is a construct that encapsulates the semantic information of an action. The behavior that the command activates is not encapsulated in this object. This means that command contains only information about "command" not the actual action that happens when command is activated. The action is defined in a `CommandListener` associated with the Screen. Command objects are presented in the user interface and the way they are presented may depend on the semantic information contained within the command.

Commands may be implemented in any user interface construct that has semantics for activating a single action. This, for example, can be a soft button, item in a menu, or some other direct user interface construct. For example, a speech interface may present these commands as voice tags.

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

A command contains three pieces of information: a label, a type, and a priority. The label is used for the visual representation of the command, whereas the type and the priority indicate the semantics of the command.

### Label

Each command includes a label string. The label string is what the application requests to be shown to the user to represent this command. For example, this string may appear next to a soft button on the device or as an element in a menu. For command types other than SCREEN, this label may be overridden by a system-specific label that is more appropriate for this command on this device. The contents of the label string are otherwise not interpreted by the implementation.

### Type

The application uses the command type to specify the intent of this command. For example, if the application specifies that the command is of type BACK, and if the device has a standard of placing the "back" operation on a certain soft-button, the implementation can follow the style of the device by using the semantic information as a guide. The defined types are `BACK`, `CANCEL`, `EXIT`, `HELP`, `ITEM`, `MENU`, `OK`, `SCREEN`, and `STOP`.

### Priority

The application uses the priority value to describe the importance of this command relative to other commands on the same screen. Priority values are integers, where a lower number indicates greater importance. The actual values are chosen by the application. A priority value of one might indicate the most important command, priority values of two, three, four, and so on indicate commands of lesser importance.

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 is placed so that user can trigger it directly and that commands with lower priority are placed on a menu. It is not an error for there to be commands on the same screen with the same priorities and types. If this occurs, the implementation will choose the order in which they are presented.

For example, if the application has the following set of commands:

        new Command("Buy", Command.SCREEN, 1);
        new Command("Info", Command.SCREEN, 1);
        new Command("Back", Command.BACK, 1);

An implementation with two soft buttons, may map back commant to right soft button and "Options" is created to left soft button.
When user presses right soft button, a menu with the two remaining Commands appear:
If the application had three soft buttons, all commands can be mapped to soft buttons:

The application is always responsible for providing the means for the user to progress through different screens. An application may set up a screen that has no commands. This is allowed by the API but is generally not useful; if this occurs the user would have no means to move to another screen. Such program would simply considered to be in error. A typical device should provide a means for the user to direct the application manager to kill the erroneous application.

Field Summary
`static int` | `BACK` A navigation command that returns the user to the logically previous screen.
`static int` | `CANCEL` A command that is a standard negative answer to a dialog implemented by current screen.
`static int` | `EXIT` A command used for exiting from the application.
`static int` | `HELP` This command specifies a request for on-line help.
`static int` | `ITEM` With this command type the application can hint to the implementation that the command is specific to a particular item on the screen.
`static int` | `MENU` A command used for initiating a menu.
`static int` | `OK` A command that is a standard positive answer to a dialog implemented by current screen.
`static int` | `SCREEN` Specifies an application-defined command that pertains to the current screen.
`static int` | `STOP` A command that will stop some currently running process, operation, etc.

Constructor Summary
`Command(String label, int commandType, int priority)` Creates a new command object with the given label, type, and priority.

Method Summary
`int` | `getCommandType()` Gets the type of the command.
`String` | `getLabel()` Gets the label of the command.
`int` | `getPriority()` Gets the priority of the command.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### SCREEN

    public static final int SCREEN

  Specifies an application-defined command that pertains to the current screen. Examples could be "Load" and "Save".

  Value 1 is assigned to SCREEN.

### BACK

    public static final int BACK

  A navigation command that returns the user to the logically previous screen. The jump to the previous screen is not done automatically by the implementation but by the `commandAction` provided by the application. Note that the application defines the actual action since the strictly previous screen may not be logically correct.

  Value 2 is assigned to BACK.

  See Also:
    `CANCEL`, `STOP`

### CANCEL

    public static final int CANCEL

  A command that is a standard negative answer to a dialog implemented by current screen. Nothing is cancelled automatically by the implementation; cancellation is implemented by the `commandAction` provided by the application.

  With this command type, the application hints to the implementation that the user wants to dismiss the current screen without taking any action on anything that has been entered into the current screen, and usually that the user wants to return to the prior screen. In many cases CANCEL is interchangeable with BACK, but BACK is mainly used in a navigational sense, as in a browser-oriented applications.

  Value 3 is assigned to CANCEL.

  See Also:
    `BACK`, `STOP`

### OK

    public static final int OK

  A command that is a standard positive answer to a dialog implemented by current screen. Nothing is done automatically by the implementation; any action taken is implemented by the `commandAction` provided by the application.

  With this command type the application hints to the implementation that the user will use this command to ask the application to confirm the data that has been entered in the current screen and to proceed to the next logical screen.

  CANCEL is often used together with OK.

  Value 4 is assigned to OK.

  See Also:
    `CANCEL`

### HELP

    public static final int HELP

  This command specifies a request for on-line help. No help information is shown automatically by the implementation. The `commandAction` provided by the application is responsible for showing the help information.

  Value 5 is assigned to HELP.

### STOP

    public static final int STOP

  A command that will stop some currently running process, operation, etc. Nothing is stopped automatically by the implementation. The cessation must be performed by the `commandAction` provided by the application.

  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.

  Value 6 is assigned to STOP.

  See Also:
    `BACK`, `CANCEL`

### EXIT

    public static final int EXIT

  A command used for exiting from the application. When the user invokes this command, the implementation does not exit automatically. The application's `commandAction` will be called, and it should exit the application if it is appropriate to do so.

  Value 7 is assigned to EXIT.

### MENU

    public static final int MENU

  A command used for initiating a menu. When the user invokes this command, the implementation does not show a menu automatically. The application's `commandAction` will be called, and it should show the menu itself. A menu is typically implemented using a List object of type `IMPLICIT`.

  Value 8 is assigned to MENU.

### ITEM

    public static final int ITEM

  With this command type the application can hint to the implementation that the command is specific to a particular item on the screen. For example, an implementation of List can use this information for creating context sensitive menus.

  Value 9 is assigned to ITEM.

Constructor Detail

### Command

    public Command(String label,
                   int commandType,
                   int priority)

  Creates a new command object with the given label, type, and priority.

  Parameters:
    `label` - the label string
    `commandType` - the command's type, one of `BACK`, `CANCEL`, `HELP`, `OK`, `SCREEN`, or `STOP`
    `priority` - the command's priority value
  Throws:
    IllegalArgumentException - if the commandType is an invalid type

Method Detail

### getLabel

    public String getLabel()

  Gets the label of the command.
  Returns:
    label of the Command

### getCommandType

    public int getCommandType()

  Gets the type of the command.
  Returns:
    type of the Command

### getPriority

    public int getPriority()

  Gets the priority of the command.
  Returns:
    priority of the Command

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a comment or suggestion Version 0.95 of MID Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A. All Rights Reserved.