/* * @(#)Command.java 1.27 01/07/10 * Copyright (c) 1999-2001 Sun Microsystems, Inc. All Rights Reserved. * * This software is the confidential and proprietary information of Sun * Microsystems, Inc. ("Confidential Information"). You shall not * disclose such Confidential Information and shall use it only in * accordance with the terms of the license agreement you entered into * with Sun. * * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING * THIS SOFTWARE OR ITS DERIVATIVES. */ package javax.microedition.lcdui; import com.sun.midp.lcdui.CommandAccess; /** * 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 * {@link CommandListener 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 * {@link #BACK BACK}, * {@link #CANCEL CANCEL}, * {@link #EXIT EXIT}, * {@link #HELP HELP}, * {@link #ITEM ITEM}, * {@link #OK OK}, * {@link #SCREEN SCREEN}, * and * {@link #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.SCREEN, 1); * new Command("Info", Command.SCREEN, 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. */ public class Command { /** * Specifies an application-defined command that pertains to the current * screen. Examples could be "Load" and "Save". * * Value 1 is assigned to SCREEN. */ public static final int SCREEN = 1; /** * 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 {@link CommandListener#commandAction 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 #CANCEL * @see #STOP */ public static final int BACK = 2; /** * 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 {@link CommandListener#commandAction 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 #BACK * @see #STOP */ public static final int CANCEL = 3; /** * 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 {@link CommandListener#commandAction 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 #CANCEL */ public static final int OK = 4; /** * This command specifies a request for on-line help. * No help information is shown automatically by the implementation. * The * {@link CommandListener#commandAction commandAction} provided by the * application is responsible for showing the help information. * * Value 5 is assigned to HELP. */ public static final int HELP = 5; /** * 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 {@link CommandListener#commandAction 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 #BACK * @see #CANCEL */ public static final int STOP = 6; /** * A command used for exiting from the application. When the user * invokes this command, the implementation does not exit automatically. * The application's * {@link CommandListener#commandAction commandAction} * will be called, and it should exit the application if it * is appropriate to do so. * * Value 7 is assigned to EXIT. */ public static final int EXIT = 7; /** * 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 8 is assigned to ITEM. */ public static final int ITEM = 8; /** * Creates a new command object with the given label, type, * and priority. * * * * @param label the label string * * @param commandType the command's type, one of * {@link #BACK BACK}, * {@link #CANCEL CANCEL}, * {@link #EXIT EXIT}, * {@link #HELP HELP}, * {@link #ITEM ITEM}, * {@link #OK OK}, * {@link #SCREEN SCREEN}, * or * {@link #STOP STOP} * * @param priority the command's priority value * * @throws IllegalArgumentException if the commandType is an invalid * type * @throws NullPointerException if label is null */ public Command(String label, int commandType, int priority) { if ((commandType < SCREEN) || (commandType > ITEM)) { throw new IllegalArgumentException(); } if (label == null) { throw new NullPointerException(); } this.label = label; this.commandType = commandType; this.priority = priority; synchronized (this) { this.id = commandRef++; } } /** * Gets the label of the command. * * @return label of the Command */ public String getLabel() { // SYNC NOTE: return of atomic value, no locking necessary return label; } /** * Gets the type of the command. * * @return type of the Command */ public int getCommandType() { // SYNC NOTE: return of atomic value, no locking necessary return commandType; } /** * Gets the priority of the command. * * @return priority of the Command */ public int getPriority() { // SYNC NOTE: return of atomic value, no locking necessary return priority; } /** * Set the internal ID for this command * (Used by Displayable only) * * @param id The integer id associated with this specific Command */ void setID(int id) { this.id = id; } /** * Get the internal ID of this Command * * @return int The integer id associated with this specific Command */ int getID() { return id; } /** * The label for this Command */ final String label; /** * The type of this Command */ final int commandType; /** * The priority of this Command */ final int priority; /** * This is a private id created at constructor time * such that the Command may be easily identified at a later * date only by its id */ private int id; /** * This is a static rolling value assigned to each new Command * as its created. Note: the commandRef must always be a positive * integer due to the way menus.c uses the return of the integer * value to flag certain menu selections to the java code */ private static int commandRef; } // class Command
