command.java

用于移动设备上的java虚拟机源代码

     * 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> 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
     * <code>STOP</code>
     * command does
     * not necessarily imply a switch to another screen. </p>
     *
     * <P>Value <code>6</code> is assigned to <code>STOP</code>.</P>
     *
     * @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.
     *
     * <P>Value <code>7</code> is assigned to <code>EXIT</code>.</P>
     */
    public static final int EXIT = 7;

    /**
     * With this command type the application can hint to the
     * implementation that the command is specific to the items of
     * the <code>Screen</code> or the elements of a
     * <code>Choice</code>. Normally this
     * means that command relates to the focused item or element.
     * For example, an implementation of <code>List</code> can use
     * this information for
     * creating context sensitive menus.
     * 
     * <P>Value <code>8</code> is assigned to <code>ITEM</code>.</P>
     */
    public static final int ITEM = 8;

    // protected members //

    /**
     * The label rendered on the screen for this Command.
     * Chosen from the available set of labels.
     */
    String      shortLabel;
    /**
     * The long Label for this Command
     */
    String      longLabel;
    /**
     * The type of this Command
     */
    int         commandType;
    /**
     * The priority of this Command
     */
    int         priority;

    // private members //

    /**
     * This is a private id that is set when adding a command to 
     * a Displayable,
     * such that the Command may be easily identified at a later
     * date only by its id
     */
    private int     id;

    // Constructors //

    /**
     * Creates a new command object with the given short
     * 
     * <a href="#label">label</a>,
     * <a href="#type">type</a>, and
     * <a href="#priority">priority</a>.
     *
     * The newly created command has no long label.  This constructor is
     * identical to <code>Command(label, null, commandType, priority)</code>.
     *
     * @param label the command's short label
     * @param commandType the command's type
     * @param priority the command's priority value
     *
     * @throws NullPointerException if label is <code>null</code>
     * @throws IllegalArgumentException if the <code>commandType</code>
     * is an invalid type
     *
     * @see #Command(String, String, int, int)
     */
    public Command(String label, int commandType, int priority) {
	this(label, null, commandType, priority);
    }

    /**
     * Creates a new command object with the given
     * <a href="#label">labels</a>,
     * <a href="#type">type</a>, and
     * <a href="#priority">priority</a>.
     *
     * <p>The short label is required and must not be
     * <code>null</code>.  The long label is
     * optional and may be <code>null</code> if the command is to have
     * no long label.</p>
     * 
     * @param shortLabel the command's short label
     * @param longLabel the command's long label, or <code>null</code> if none
     * @param commandType the command's type
     * @param priority the command's priority value
     * 
     * @throws NullPointerException if <code>shortLabel</code> is
     * <code>null</code>
     * @throws IllegalArgumentException if the <code>commandType</code> is an
     * invalid type
     * 
     * @since MIDP 2.0
     */
    public Command(String shortLabel, String longLabel, int commandType,
		   int priority) {
        initialize(commandType, priority);
        setLabel(shortLabel, longLabel);
    }

    // public method implementations //

    /**
     * Gets the short label of the command.
     * 
     * @return the <code>Command's</code> short label
     */
    public String getLabel() {
        // SYNC NOTE: return of atomic value, no locking necessary
        return shortLabel;
    }

    /**
     * Gets the long label of the command.
     * 
     * @return the <code>Command's</code> long label, or
     * <code>null</code> if the <code>Command</code> has no long
     * label
     * 
     * @since MIDP 2.0
     */
    public String getLongLabel() {
        // SYNC NOTE: return of atomic value, no locking necessary
        return longLabel;
    }

    /**
     * Gets the type of the command.
     *
     * @return type of the <code>Command</code>
     */
    public int getCommandType() {
        // SYNC NOTE: return of atomic value, no locking necessary
        return commandType;
    }
    
    /**
     * Gets the priority of the command.
     *
     * @return priority of the <code>Command</code>
     */
    public int getPriority() {
        // SYNC NOTE: return of atomic value, no locking necessary
        return priority;
    }

    // protected method implementations //

    /**
     * Get the internal ID of this Command
     *
     * @return int  The integer id associated with this specific Command
     */
    int getID() {
        return id;
    }

    // package private method implementations //

    /**
     * Sets the internal id used to uniquely identify
     * this command.
     * This method is intended to be called from Displayable
     * addCommand()
     *
     * @param num the int to set this id to
     */
    void setInternalID(int num) {
	this.id = num;
    }

    // private method implementations //

    /**
     * Sets the label of the command. If the label is null
     * throw NullPointerException.
     * @param shortLabel the short Label string
     * @param longLabel the long Label string
     * @since MIDP 2.0
     */
    private void setLabel(String shortLabel, String longLabel) {

        if (shortLabel == null) {
	    throw new NullPointerException();
        }
        this.shortLabel = shortLabel;
        this.longLabel = longLabel;
    }

    /**
     * This method will initialize this Command object is only called
     * by its constructors.
     *
     * @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, or if any one of
     *                                  the array of labels is null
     */
    private final void initialize(int commandType, int priority) {

        if ((commandType < SCREEN) || (commandType > ITEM)) {
            throw new IllegalArgumentException();
        }

        this.commandType = commandType;
        this.priority    = priority;
    }

} // class Command