customitem.java

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

 * <h2>Item Appearance</h2>
 *
 * <p>The visual appearance of each item consists of a
 * label (handled by the implementation)
 * and its contents (handled by the subclass).</p>
 *
 * <p>Labels are the responsibility of the implementation, not the item.  The
 * screen area that is allocated to the <code>CustomItem</code>
 * for its contents is
 * separate from the area that the implementation uses to display the
 * <code>CustomItem's</code> label. 
 * The implementation controls the rendering of the label
 * and its layout with respect to the content area.</p>
 *
 * <p>The <code>CustomItem</code> is responsible for 
 * painting its contents whenever
 * the <code>paint</code> method is called.</p>
 *
 * <p>The colors for foreground, background, highlighted foreground,
 * highlighted background, border, and highlighted border should be
 * retrieved from {@link Display#getColor}.  
 * This will allow <code>CustomItems</code> to
 * match the color scheme of other items provided with the device.
 * The <code>CustomItem</code> is responsible for keeping 
 * track of its own highlighted and
 * unhighlighted state.</p>
 *
 * <p>The fonts used should be retrieved from {@link Font#getFont}.
 * This will allow them to match the fonts used by other items
 * on the device for a consistent visual appearance. </p>
 *
 * @since MIDP 2.0
 */
abstract public class CustomItem extends Item {

    /**
     * Interaction mode bit indicating support of horizontal traversal
     * internal to the <code>CustomItem</code>.
     *
     * <p><code>TRAVERSE_HORIZONTAL</code> has the value <code>1</code>.</p>
     *
     * @see #getInteractionModes
     * @see #traverse
     */
    protected static final int TRAVERSE_HORIZONTAL = 1;

    /**
     * Interaction mode bit indicating support for vertical traversal
     * internal to the <code>CustomItem</code>.
     *
     * <p><code>TRAVERSE_VERTICAL</code> has the value <code>2</code>.</p>
     *
     * @see #getInteractionModes
     * @see #traverse
     */
    protected static final int TRAVERSE_VERTICAL = 2;

    /**
     * Interaction mode bit indicating support for key pressed events.
     *
     * <p><code>KEY_PRESS</code> has the value <code>4</code>.</p>
     *
     * @see #getInteractionModes
     * @see #keyPressed
     */
    protected static final int KEY_PRESS = 4;

    /**
     * Interaction mode bit indicating support for key released events.
     *
     * <p><code>KEY_RELEASE</code> has the value <code>8</code>.</p>
     *
     * @see #getInteractionModes
     * @see #keyReleased
     */
    protected static final int KEY_RELEASE = 8;

    /**
     * Interaction mode bit indicating support for key repeated events.
     *
     * <p><code>KEY_REPEAT</code> has the value <code>0x10</code>.</p>
     *
     * @see #getInteractionModes
     * @see #keyRepeated
     */
    protected static final int KEY_REPEAT = 0x10;

    /**
     * Interaction mode bit indicating support for point pressed events.
     *
     * <p><code>POINTER_PRESS</code> has the value <code>0x20</code>.</p>
     *
     * @see #getInteractionModes
     * @see #pointerPressed
     */
    protected static final int POINTER_PRESS = 0x20;

    /**
     * Interaction mode bit indicating support for point released events.
     *
     * <p><code>POINTER_RELEASE</code> has the value<code> 0x40</code>.</p>
     *
     * @see #getInteractionModes
     * @see #pointerReleased
     */
    protected static final int POINTER_RELEASE = 0x40;

    /**
     * Interaction mode bit indicating support for point dragged events.
     *
     * <p><code>POINTER_DRAG</code> has the value <code>0x80</code>.</p>
     *
     * @see #getInteractionModes
     * @see #pointerDragged
     */
    protected static final int POINTER_DRAG = 0x80;

    /**
     * A value for traversal direction that indicates that traversal has
     * entered or has changed location within this item, but that no specific
     * direction is associated with this traversal event.
     *
     * <p><code>NONE</code> has the value <code>0</code>.</p>
     *
     * @see #traverse
     */
    protected static final int NONE = 0;

    /**
     * labelHeight caches the height of the label for this CustomItem,
     * as it is not included when reporting dimensions to the subclass
     */
    private int labelHeight = 0;

    /**
     * Superclass constructor, provided so that the
     * <code>CustomItem</code> subclass can specify its label.
     *
     * @param label the <code>CustomItem's</code> label
     */
    protected CustomItem(String label) { 
        super(label);
    }

    /**
     * Gets the game action associated with the given key code of the
     * device.  Returns zero if no game action is associated with this key
     * code.  See the
     * <a href="Canvas.html#gameactions">Game Actions</a>
     * section of class <code>Canvas</code> for further discussion
     * of game actions.
     *
     * <p>The mapping of key codes to game actions may differ between
     * <code>CustomItem</code> and <code>Canvas</code>.</p>
     *
     * @param keyCode the key code
     * @return the game action corresponding to this key, or <code>0</code>
     * if none
     * @throws IllegalArgumentException if <code>keyCode</code> is not
     * a valid key code
     */
    public int getGameAction(int keyCode) {
        int n = Display.getGameAction(keyCode);

        if (n == -1) {
            throw new IllegalArgumentException();
        }

        return n;
    }

    /**
     * Gets the available interaction modes.  This method is intended to be
     * called by <code>CustomItem</code> subclass code in order
     * for it to determine what
     * kinds of input are available from this device.  The modes available may
     * be dependent upon several factors: the hardware keys on the actual
     * device, which of these keys are needed for the system to do proper
     * navigation, the presence of a pointing device, etc.  See <a
     * href="#interaction">Interaction Modes</a> for further discussion.  If
     * this method returns <code>0</code>, the only interaction available 
     * is through item commands.
     *
     * @return a bitmask of the available interaction modes
     */
    protected final int getInteractionModes() { 
        return (TRAVERSE_HORIZONTAL | TRAVERSE_VERTICAL | 
                KEY_PRESS | KEY_RELEASE | KEY_REPEAT |
	        POINTER_PRESS | POINTER_RELEASE | POINTER_DRAG);
    }

    /**
     * Implemented by the subclass to return the minimum width of the content
     * area, in pixels.  This method is called by the implementation as part
     * of its layout algorithm.  The actual width granted is reported in the
     * {@link #sizeChanged sizeChanged} and {@link #paint paint} methods.
     *
     * @return the minimum content width in pixels
     */
    protected abstract int getMinContentWidth();

    /**
     * Implemented by the subclass to return the minimum height of the content
     * area, in pixels.  This method is called by the implementation as part
     * of its layout algorithm.  The actual height granted is reported in the
     * {@link #sizeChanged sizeChanged} and {@link #paint paint} methods.
     *
     * @return the minimum content height in pixels
     */
    protected abstract int getMinContentHeight();

    /**
     * Implemented by the subclass to return the preferred width of the content
     * area, in pixels.  This method is called by the implementation as part 
     * of its layout algorithm.
     *
     * <p>The <code>height</code> parameter is the tentative height assigned 
     * to the content area.  The subclass code may use this value in its 
     * computation of the preferred width.  The <code>height</code> parameter 
     * will be -1 if the implementation has not assigned a tentative value 
     * for the height.  Otherwise, <code>height</code> will have a specific 
     * value if the application has locked the height of the
     * <code>CustomItem</code> or if the container's layout algorithm has 
     * already computed a tentative height at the time of this call.  The 
     * subclass must not assume that the tentative height passed or the
     * preferred width returned will be granted.
     * The actual size granted is reported in the
     * {@link #sizeChanged sizeChanged} and {@link #paint paint} methods.
     * </p>
     *
     * @param height the tentative content height in pixels, or -1 if a
     * tentative height has not been computed
     * @return the preferred content width in pixels
     */
    protected abstract int getPrefContentWidth(int height);

    /**
     * Implemented by the subclass to return the preferred height of the
     * content area, in pixels.  This method is called by the implementation
     * as part of its layout algorithm.
     *
     * <p>The <code>width</code> parameter is the tentative width assigned 
     * to the content area.  The subclass code may use this value in its 
     * computation of the preferred height.  The <code>width</code> parameter 
     * will be -1 if the implementation has not assigned a tentative value 
     * for the width.  Otherwise, <code>width</code> will have a specific
     * value if the application has locked the width of the
     * <code>CustomItem</code> or if the container's layout algorithm has 
     * already computed a tentative width at the time of this call.  The 
     * subclass must not assume that the tentative width passed or the
     * preferred height returned will be granted.
     * The actual size granted is reported in the
     * {@link #sizeChanged sizeChanged} and {@link #paint paint} methods.
     * </p>
     *
     * @param width the tentative content width in pixels, or -1 if a
     * tentative width has not been computed
     * @return the preferred content height in pixels
     */
    protected abstract int getPrefContentHeight(int width);

    /**
     * Implemented by the subclass in order to handle size change events.
     * This method is called by the system when the size of the content area
     * of this <code>CustomItem</code> has changed.
     *
     * <p>If the size of a <code>CustomItem</code> changes while it is
     * visible on the display, it may trigger an automatic
     * repaint request.  If this occurs, the call to
     * <code>sizeChanged</code> will occur prior to the call to
     * <code>paint</code>.  If the <code>CustomItem</code> has become
     * smaller, the implementation may choose not to trigger a repaint
     * request if the remaining contents of the <code>CustomItem</code>
     * have been preserved.  Similarly, if the <code>CustomItem</code>
     * has become larger, the implementation may choose to trigger a
     * repaint only for the new region.  In both cases, the preserved
     * contents must remain stationary with respect to the origin of the
     * <code>CustomItem</code>.  If the size change is significant to
     * the contents of the <code>CustomItem</code>, the application must
     * explicitly issue a repaint request for the changed areas.  Note
     * that the application's repaint request should not cause multiple
     * repaints, since it can be coalesced with repaint requests that
     * are already pending.</p>
     *
     * <p>If the size of the item's content area
     * changes while it is not visible, calls to this method may be deferred.
     * If the size had changed while the item was not visible,
     * <code>sizeChanged</code> will be called at least once before the item
     * becomes visible once again.</p>
     *
     * <p>The default implementation of this method does
     * nothing.</p>
     *
     * @param w the new width of the item's content area
     * @param h the new height of the item's content area
     */
    protected void sizeChanged(int w, int h) { }

    /**
     * Signals that the <code>CustomItem's</code> size and traversal
     * location need to be updated. 
     * This method is intended to be called by <code>CustomItem</code>