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 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.
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
Command.BACK BACK ,
Command.CANCEL CANCEL ,
Command.EXIT EXIT ,
Command.HELP HELP ,
Command.ITEM ITEM ,
Command.OK OK ,
Command.SCREEN SCREEN ,
and
Command.STOP 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.
since:
MIDP 1.0 | 