item.java

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

    }

    /**
     * Sets a listener for <code>Commands</code> to this <code>Item</code>,
     * replacing any previous
     * <code>ItemCommandListener</code>. A <code>null</code> reference
     * is allowed and has the effect of
     * removing any existing listener.
     *
     * <p>It is illegal to call this method if this <code>Item</code>
     * is contained within an <code>Alert</code>.</p>
     *
     * @param l the new listener, or <code>null</code>.
     * @throws IllegalStateException if this <code>Item</code> is contained
     * within an <code>Alert</code>
     * @since MIDP 2.0
     */
    public void setItemCommandListener(ItemCommandListener l) {
        synchronized (Display.LCDUILock) {
            commandListener = l;
        }
    }

    /**
     * Gets the preferred width of this <code>Item</code>.  
     * If the application has locked
     * the width to a specific value, this method returns that value.
     * Otherwise, the return value is computed based on the 
     * <code>Item's</code> contents,
     * possibly with respect to the <code>Item's</code> preferred height 
     * if it is locked.
     * See <a href="#sizes">Item Sizes</a> for a complete discussion.
     *
     * @return the preferred width of the Item
     * @see #getPreferredHeight
     * @see #setPreferredSize
     * @since MIDP 2.0
     */
    public int getPreferredWidth() {
        synchronized (Display.LCDUILock) {
            return (lockedWidth != -1) ? lockedWidth :
                        callPreferredWidth(lockedHeight);
        }
    }

    /**
     * Gets the preferred height of this <code>Item</code>.  
     * If the application has locked
     * the height to a specific value, this method returns that value.
     * Otherwise, the return value is computed based on the 
     * <code>Item's</code> contents,
     * possibly with respect to the <code>Item's</code> preferred 
     * width if it is locked.
     * See <a href="#sizes">Item Sizes</a> for a complete discussion.
     *
     * @return the preferred height of the <code>Item</code>
     * @see #getPreferredWidth
     * @see #setPreferredSize
     * @since MIDP 2.0
     */
    public int getPreferredHeight() {
        synchronized (Display.LCDUILock) {
            return (lockedHeight != -1) ? lockedHeight :
                        callPreferredHeight(lockedWidth);
        }
    }

    /**
     * Sets the preferred width and height for this <code>Item</code>.
     * Values for width and height less than <code>-1</code> are illegal.
     * If the width is between zero and the minimum width, inclusive,
     * the minimum width is used instead.
     * If the height is between zero and the minimum height, inclusive,
     * the minimum height is used instead.
     *
     * <p>Supplying a width or height value greater than the minimum width or 
     * height <em>locks</em> that dimension to the supplied
     * value.  The implementation may silently enforce a maximum dimension for 
     * an <code>Item</code> based on factors such as the screen size. 
     * Supplying a value of
     * <code>-1</code> for the width or height unlocks that dimension.
     * See <a href="#sizes">Item Sizes</a> for a complete discussion.</p>
     * 
     * <p>It is illegal to call this method if this <code>Item</code> 
     * is contained within  an <code>Alert</code>.</p>
     * 
     * @param width the value to which the width should be locked, or
     * <code>-1</code> to unlock
     * @param height the value to which the height should be locked, or 
     * <code>-1</code> to unlock
     * @throws IllegalArgumentException if width or height is less than 
     * <code>-1</code>
     * @throws IllegalStateException if this <code>Item</code> is contained
     * within an <code>Alert</code>
     * @see #getPreferredHeight
     * @see #getPreferredWidth
     * @since MIDP 2.0
     */
    public void setPreferredSize(int width, int height) {
        if (width < -1 || height < -1) {
            throw new IllegalArgumentException();
        }

        synchronized (Display.LCDUILock) {
            if (owner != null && owner instanceof Alert) {
                throw new IllegalStateException();
            }

            int minWidth  = getMinimumWidth();
            int minHeight = getMinimumHeight();

            this.lockedWidth  = (width != -1 && width < minWidth) 
                              ? minWidth 
                              : width;

            this.lockedHeight = (height != -1 && height < minHeight) 
                              ? minHeight 
                              : height;

            if (visible) {
                if (lockedWidth != bounds[WIDTH] ||
                        lockedHeight != bounds[HEIGHT]) {
                    invalidate();
                }
            }
        } // synchronized
    }

    /**
     * Gets the minimum width for this <code>Item</code>.  This is a width
     * at which the item can function and display its contents,
     * though perhaps not optimally.
     * See <a href="#sizes">Item Sizes</a> for a complete discussion.
     * 
     * @return the minimum width of the item
     * @since MIDP 2.0
     */
    public int getMinimumWidth() {
        synchronized (Display.LCDUILock) {
            return callMinimumWidth();
        }
    }

    /**
     * Gets the minimum height for this <code>Item</code>.  This is a height
     * at which the item can function and display its contents,
     * though perhaps not optimally.
     * See <a href="#sizes">Item Sizes</a> for a complete discussion.
     *
     * @return the minimum height of the item
     * @since MIDP 2.0
     */
    public int getMinimumHeight() {
        synchronized (Display.LCDUILock) {
            return callMinimumHeight();
        }
    }

    /**
     * Sets default <code>Command</code> for this <code>Item</code>.  
     * If the <code>Item</code> previously had a
     * default <code>Command</code>, that <code>Command</code> 
     * is no longer the default, but it
     * remains present on the <code>Item</code>.
     *
     * <p>If not <code>null</code>, the <code>Command</code> object
     * passed becomes the default <code>Command</code>
     * for this <code>Item</code>.  If the <code>Command</code> object
     * passed is not currently present
     * on this <code>Item</code>, it is added as if {@link #addCommand}
     * had been called
     * before it is made the default <code>Command</code>.</p>
     *
     * <p>If <code>null</code> is passed, the <code>Item</code> is set to
     * have no default <code>Command</code>.
     * The previous default <code>Command</code>, if any, remains present
     * on the <code>Item</code>.
     * </p>
     *
     * <p>It is illegal to call this method if this <code>Item</code>
     * is contained within  an <code>Alert</code>.</p>
     * 
     * @param cmd the command to be used as this <code>Item's</code> default
     * <code>Command</code>, or <code>null</code> if there is to 
     * be no default command
     *
     * @throws IllegalStateException if this <code>Item</code> is contained
     * within an <code>Alert</code>
     * @since MIDP 2.0
     */
    public void setDefaultCommand(Command cmd) {
        if (cmd != null) {
            addCommand(cmd);
        }
        defaultCommand = cmd;
    }

    /**
     * Causes this <code>Item's</code> containing <code>Form</code> to notify
     * the <code>Item's</code> {@link ItemStateListener}.
     * The application calls this method to inform the
     * listener on the <code>Item</code> that the <code>Item's</code>
     * state has been changed in
     * response to an action.  Even though this method simply causes a call
     * to another part of the application, this mechanism is useful for
     * decoupling the implementation of an <code>Item</code> (in particular, the
     * implementation of a <code>CustomItem</code>, though this also applies to
     * subclasses of other items) from the consumer of the item.
     *
     * <p>If an edit was performed by invoking a separate screen, and the
     * editor now wishes to &quot;return&quot; to the form which contained the
     * selected <code>Item</code>, the preferred method is
     * <code>Display.setCurrent(Item)</code>
     * instead of <code>Display.setCurrent(Displayable)</code>,
     * because it allows the
     * <code>Form</code> to restore focus to the <code>Item</code>
     * that initially invoked the editor.</p>
     *
     * <p>In order to make sure that the documented behavior of
     * <code>ItemStateListener</code> is maintained, it is up to the caller
     * (application) to guarantee that this function is
     * not called unless:</p>
     *
     * <ul>
     * <li>the <code>Item's</code> value has actually been changed, and</li>
     * <li>the change was the result of a user action (an &quot;edit&quot;)
     * and NOT as a result of state change via calls to
     * <code>Item's</code> APIs </li>
     * </ul>
     *
     * <p>The call to <code>ItemStateListener.itemStateChanged</code>
     * may be delayed in order to be serialized with the event stream.
     * The <code>notifyStateChanged</code> method does not block awaiting
     * the completion of the <code>itemStateChanged</code> method.</p>
     *
     * @throws IllegalStateException if the <code>Item</code> is not owned
     * by a <code>Form</code>
     * @since MIDP 2.0
     */
    public void notifyStateChanged() { 
        // get a copy of the object reference to item's owning form
        Screen owner = this.owner;

        if (owner == null || !(owner instanceof Form)) {
            throw new IllegalStateException();
        }

        owner.itemStateChanged(this);
    }

// ************************************************************
//  protected methods
// ************************************************************

// ************************************************************
//  package private methods
// ************************************************************

    /**
     * Called to commit any pending user interaction for the item
     */
    void commitPendingInteraction() { }
        
    /**
     * Return the height of the label for this Item. If null,
     * returns 0, otherwise, returns LABEL_HEIGHT - which is
     * one line height, multi-line labels are currently disabled
     * by this method
     *
     * @param w the width available for the label (-1 means as wide
     *          as possible)
     * @return the height for the label
     */
    int getLabelHeight(int w) {
        if (label == null || label.length() == 0) {
            return 0;
        } 

        if (w == -1) {
            w = DEFAULT_WIDTH;
        }
        return Text.getHeightForWidth(label, LABEL_FONT, w, 0);
    }

    /**
     * Return the width of the label for this Item. If null,
     * returns 0, otherwise, returns the width in pixels of the
     * current label using LABEL_FONT.
     *
     * @return the width for the label
     */
    int getLabelWidth() {
        if (label == null || label.length() == 0) {
            return 0;
        }
        
        return Text.getWidestLineWidth(label.toCharArray(), 0, DEFAULT_WIDTH,
                                       LABEL_FONT);
    }

    /**
     * Get the preferred width of this Item
     *
     * @param height the tentative content height in pixels, or -1 if a
     * tentative height has not been computed
     * @return the preferred width
     */
    abstract int callPreferredWidth(int height);

    /**
     * Get the preferred height of this Item
     *
     * @param width the tentative content width in pixels, or -1 if a
     * tentative width has not been computed
     * @return the preferred height
     */
    abstract int callPreferredHeight(int width);

    /**
     * Get the minimum width of this Item
     *
     * @return the minimum width
     */
    abstract int callMinimumWidth();

    /**
     * Get the minimum height of this Item
     *
     * @return the minimum height
     */
    abstract int callMinimumHeight();

    /**
     * Determine if this Item should horizontally shrink
     *
     * @return true if it should horizontally shrink
     */
    boolean shouldHShrink() {
        return ((layout & LAYOUT_SHRINK) == LAYOUT_SHRINK);
    }

    /**
     * Determine if this Item should horizontally expand
     *
     * @return true if it should horizontally expand
     */
    boolean shouldHExpand() {
        return ((layout & LAYOUT_EXPAND) == LAYOUT_EXPAND);
    }

    /**
     * Determine if this Item should vertically shrink
     *
     * @return true if it should vertically shrink
     */
    boolean shouldVShrink() {
        return ((layout & LAYOUT_VSHRINK) == LAYOUT_VSHRINK);
    }

    /**
     * Determine if this Item should vertically expand
     *
     * @return true if it should vertically expand
     */
    boolean shouldVExpand() {
        return ((layout & LAYOUT_VEXPAND) == LAYOUT_VEXPAND);
    }

    /**
     * Determine if this Item should have a newline after it
     *
     * @return true if it should have a newline after
     */
    boolean equateNLA() {
        return ((layout & LAYOUT_NEWLINE_AFTER) == LAYOUT_NEWLINE_AFTER);
    }

    /**
     * Determine if this Item should have a newline before it
     *
     * @return true if it should have a newline before
     */
    boolean equateNLB() {
        return ((layout & LAYOUT_NEWLINE_BEFORE) == LAYOUT_NEWLINE_BEFORE);
    }

    /**
     * Determine if this Item should not be traversed to
     *
     * @return true if this Item should not be traversed to
     */
    boolean shouldSkipTraverse() {
        return false;
    }

    /**
     * Paint the content of this Item