command.java

有关j2me的很好的例子可以研究一下

/*
 * @(#)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;

/**
 * <P>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 <em>presented</em>
 * in the user interface and the way they are presented
 * may depend on the semantic information contained within the command.
 * </p>
 *
 * <P>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. </P>
 *
 * <P>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. </P>
 *
 * <p>A command contains three pieces of information: a <em>label</em>, a
 * <em>type</em>, and a <em>priority</em>. The label is used for the visual
 * representation of the command, whereas the type and the priority indicate
 * the semantics of the command. </p>
 *
 * <a name="label"></a>
 * <h3>Label</h3>
 *
 * <p> 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. </p>
 *
 * <a name="type"></a>
 * <h3>Type</h3>
 *
 * <p> 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}. </p>
 *
 * <a name="priority"></a>
 * <h3>Priority</h3>
 *
 * <p> 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. </p>
 *
 * <p>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. </p>
 *
 * <p>For example, if the application has the following set of commands:
 * <PRE>
 *    new Command("Buy", Command.SCREEN, 1);
 *    new Command("Info", Command.SCREEN, 1);
 *    new Command("Back", Command.BACK, 1);
 * </PRE>
 * 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.<BR>
 * <IMG SRC="doc-files/command1.gif"><BR>
 * When user presses the left soft button, a menu with the two remaining
 * Commands appears:<BR>
 * <IMG SRC="doc-files/command2.gif"><BR>
 * If the application had three soft buttons, all commands can be mapped
 * to soft buttons:
 * <BR><IMG SRC="doc-files/command3.gif"></P>
 *
 * <p>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 {
    /**
     * <P>Specifies an application-defined command that pertains to the current
     * screen. Examples could be "Load" and "Save".</P>
     *
     * <P>Value 1 is assigned to SCREEN.</P>
     */
    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.
     *
     * <P>Value 2 is assigned to BACK.</P>
     *
     * @see #CANCEL
     * @see #STOP
     */
    public static final int BACK = 2;

    /**
     * <P>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.</P>
     *
     * <p> 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. </p>
     *
     * <P>Value 3 is assigned to CANCEL.</P>
     *
     * @see #BACK
     * @see #STOP
     */
    public static final int CANCEL = 3;

    /**
     * <P>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.</P>
     *
     * <p> 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. </p>
     *
     * <P>CANCEL is often used together with OK.</P>
     *
     * <P>Value 4 is assigned to OK.</P>
     *
     * @see #CANCEL
     */
    public static final int OK = 4;

    /**
     * <P> 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. </p>
     *
     * <P>Value 5 is assigned to HELP.</P>
     */
    public static final int HELP = 5;

    /**
     * <P>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.</P>
     *
     * <p> 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. </p>
     *
     * <P>Value 6 is assigned to STOP.</P>
     *
     * @see #BACK
     * @see #CANCEL
     */
    public static final int STOP = 6;

    /**
     * <P>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.</P>
     *
     * <P>Value 7 is assigned to EXIT.</P>
     */
    public static final int EXIT = 7;

    /**
     * <P>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.</P>
     *
     * <P>Value 8 is assigned to ITEM.</P>
     */
    public static final int ITEM = 8;

    /**
     * <p> Creates a new command object with the given label, type,
     * and priority.
     * </p>
     *
     *
     * @param label the <a href="#label">label</a> string
     *
     * @param commandType the command's <a href="#type">type</a>, 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 <a href="#priority">priority</a> 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