javax.microedition.lcdui
Class Command

java.lang.Object
  javax.microedition.lcdui.Command

public class Command
extends java.lang.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 Displayable. 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 than 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 four pieces of information: a short label, an optional long label, a type, and a priority. One of the labels is used for the visual representation of the command, whereas the type and the priority indicate the semantics of the command.

Labels

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

All commands have a short label. The long label is optional. If the long label is not present on a command, the short label is always used.

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".

The implementation chooses one of the labels to be presented in the user interface based on the context and the amount of space available. For example, the implementation might use the short label if the command appears on a soft button, and it might use the long label if the command appears on a menu, but only if there is room on the menu for the long label. The implementation may use the short labels of some commands and the long labels of other commands, and it is allowed to switch between using the short and long label at will. The application cannot determine which label is being used at any given time. If both short and long labels are too long to fit the command space, the short command label will be truncated to the available space.

From MIDP 3.0 the visible parts of a Command is mutable. This means that the labels may be set at any time by the setLabel() and setLongLabel() methods. It is up to the implementation to act on the change as soon as possible, at latest before the next invocation of the CommandListener for the Command in question.

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

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 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.ITEM, 1);
 new Command("Info", Command.ITEM, 1);
 new Command("Back", Command.BACK, 1);
 

An implementation with two soft buttons may map the BACK command to the right soft button and create an "Options" menu on the left soft button to contain the other commands.

When user presses the left soft button, a menu with the two remaining Commands appears:

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.

Exact placement of Commands

MIDP 3.0 adds the possibility of the application using exact placement of Commands when used as softkeys by using arguments to the addCommand method. How this is done is explained in the Displayable class.

Enabled

The application uses the enabled value to specify whether a command is enabled or not. If a command is not enabled, it should be rendered differently, for instance grayed out, and it should not be available for selection by the user.

Images

The application may add an Image to the Command to be shown together with the labels. The device shows the image on a best effort basis, depending on what can be done on the particular display. For example, a Command with an image is added to two different displays, one with high resolution and one with low, the implementation may decide either to show the image only on the high resolution display or ignore the image completely. Implementations may truncate or scale the icon image if it is larger than the size supported by device.

The Image may be mutable or immutable. If the Image is mutable, then a snapshot of its contents is taken before the Command() constructor or setImage() method returns. The snapshot is used whenever the contents of the Command are to be displayed. Even if the application subsequently draws into the Image, the snapshot is not modified until the next call to setImage(). If the Command is visible on the display then the display SHOULD be updated with the new snapshot as soon as it is feasible for the implementation to do so.

Applications can query the implementation's command icon size by calling Display.getBestImageWidth(int) and Display.getBestImageHeight(int) methods using the Display.COMMAND image type. The style and appearance of commands are platform-dependent. If the image is changed after the Command is first displayed, then it is up to the implementation to act on the change as soon as possible, at latest before the next invocation of the CommandListener for the Command in question.

Since:

MIDP 3.0

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 the items of the Screen or the elements of a Choice.
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(java.lang.String label, int commandType, int priority)
Creates a new command object with the given short label, type, and priority.

Command(java.lang.String shortLabel, java.lang.String longLabel, Image image, int commandType, int priority)
Creates a new command object with the given labels, image, type and priority.

Command(java.lang.String shortLabel, java.lang.String longLabel, int commandType, int priority)
Creates a new command object with the given labels, type, and priority.

Method Summary

int	getCommandType() Gets the type of the command.
boolean	getEnabled() Gets the enabled value of the command.
Font	getFont() Gets the application's preferred font for rendering this Command.
Image	getImage() Gets the image of the command.
java.lang.String	getLabel() Gets the short label of the command.
java.lang.String	getLongLabel() Gets the long label of the command.
int	getPriority() Gets the priority of the command.
void	onParentEnabled(boolean enabled) Informs the command of a change in its parent's enabled value.
void	setEnabled(boolean enabled) Sets the enabled value of the command.
void	setFont(Font font) Sets the application's preferred font for rendering this Command.
void	setImage(Image image) Sets the image of the command.
void	setLabel(java.lang.String label) Sets the label of the command.
void	setLongLabel(java.lang.String longLabel) Sets the long label 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". A SCREEN command generally applies to the entire screen's contents or to navigation among screens. This is in contrast to the ITEM type, which applies to the currently activated or focused item or element contained within this screen.

Value 1 is assigned to SCREEN.

See Also:

Constant Field Values

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, Constant Field Values

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 for navigation as in a browser-oriented applications.

Value 3 is assigned to CANCEL.

See Also:

BACK, STOP, Constant Field Values

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, Constant Field Values

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.

See Also:

Constant Field Values

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, Constant Field Values

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.

See Also:

Constant Field Values

ITEM

public static final int 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 implementation of List can use this information for creating context sensitive menus.

Value 8 is assigned to ITEM.

See Also:

Constant Field Values

Constructor Detail

Command

public Command(java.lang.String label,
               int commandType,
               int priority)

Creates a new command object with the given short label, type, and priority. The newly created command has no long label. This constructor is identical to Command(label, null, commandType, priority).

Parameters:

label - the command's short label

commandType - the command's type

priority - the command's priority value

Throws:

java.lang.NullPointerException - if label is null

java.lang.IllegalArgumentException - if the commandType is an invalid type

See Also:

Command(String, String, int, int)

Command

public Command(java.lang.String shortLabel,
               java.lang.String longLabel,
               int commandType,
               int priority)

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

The short label is required and must not be null. The long label is optional and may be null if the command is to have no long label.

Parameters:

shortLabel - the command's short label

longLabel - the command's long label, or null if none

commandType - the command's type

priority - the command's priority value

Throws:

java.lang.NullPointerException - if shortLabel is null

java.lang.IllegalArgumentException - if the commandType is an invalid type

Since:

MIDP 2.0

Command

public Command(java.lang.String shortLabel,
               java.lang.String longLabel,
               Image image,
               int commandType,
               int priority)

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

The short label is required and must not be null. The long label is optional and may be null if the command is to have no long label.

If the image is mutable then a snapshot is created before this method returns.

Parameters:

shortLabel - the command's short label

longLabel - the command's long label, or null if none

commandType - the command's type

priority - the command's priority value

image - the command's image; may be null.

Throws:

java.lang.NullPointerException - if shortLabel is null

java.lang.IllegalArgumentException - if the commandType is an invalid type

Since:

MIDP 3.0

Method Detail

getLabel

public java.lang.String getLabel()

Gets the short label of the command.

Returns:

the Command's short label

getLongLabel

public java.lang.String getLongLabel()

Gets the long label of the command.

Returns:

the Command's long label, or null if the Command has no long label

Since:

MIDP 2.0

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

getImage

public Image getImage()

Gets the image of the command. The image may be null if the Command has no image.

Returns:

image of the Command

Since:

MIDP 3.0

getEnabled

public boolean getEnabled()

Gets the enabled value of the command.

Returns:

enabled value of the Command

Since:

MIDP 3.0

setLabel

public void setLabel(java.lang.String label)

Sets the label of the command.

Throws:

java.lang.NullPointerException - if label is null

Since:

MIDP 3.0

setLongLabel

public void setLongLabel(java.lang.String longLabel)

Sets the long label of the command.

Since:

MIDP 3.0

setImage

public void setImage(Image image)

Sets the image of the command. If the image is mutable then a snapshot is created before this method returns.

For example, after painting into a mutable image contained by a Command, the application refreshes the snapshot by calling:

     command.setImage(command.getImage());
 

Parameters:

image - the command's image; may be null.

Since:

MIDP 3.0

setFont

public void setFont(Font font)

Sets the application's preferred font for rendering this Command. A Command's font is a hint, and the implementation may disregard the application's preferred font.

The font parameter must be a valid Font object or null. If the font parameter is null, the implementation must use its default font to render the element.

Parameters:

font - the preferred font to use to render the command

Since:

MIDP 3.0

See Also:

getFont()

getFont

public Font getFont()

Gets the application's preferred font for rendering this Command. A Command's font is a hint, and the implementation may disregard the application's preferred font.

Returns:

font the preferred font to use to render the command; null if the system is using the default font.

Since:

MIDP 3.0

See Also:

setFont(javax.microedition.lcdui.Font)

setEnabled

public void setEnabled(boolean enabled)

Sets the enabled value of the command.

Since:

MIDP 3.0

onParentEnabled

public void onParentEnabled(boolean enabled)

Informs the command of a change in its parent's enabled value. The application must itself decide how the Command should handle this information, the default is to do nothing.

Since:

MIDP 3.0