item.java

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

/*
 * @(#)Item.java	1.71 01/08/09
 * 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;

/**
 * A superclass for components that can be added to a {@link Form
 * Form} and {@link Alert Alert}. All Item objects have a label field, which
 * is a string that is attached to the item. The label is typically displayed
 * near the component when it is displayed within a screen.
 * This means that the implementation tries to keep the label on 
 * the same horizontal
 * row with the item or directly above the item.
 * If the screen is scrolling, the implementation tries to keep
 * the label visible
 * at the same time with the Item.<P>
 *
 * In some cases,
 * when the user attempts to interact with an Item, the system will switch to
 * a system-generated screen where the actual interaction takes places. If
 * this occurs, the label will generally be carried along and displayed within
 * this new screen in order to provide the user with some context for the
 * operation. For this reason it is recommended that applications supply a
 * label to all interactive Item objects. However, this is not required, and
 * a null value for a label is legal and specifies the absence of a label.
 */
abstract public class Item {

    /**
     * The label for this Item
     */
    private String label;
    /**
     * The owner Screen for this Item
     */
    private Screen owner;
    /**
     * A flag signaling this Item has focus
     */
    private boolean focus;  // = false;

    /**
     * An array holding the layouts required to render this Item
     */
    Layout layouts[];

    /**
     * Creates a new item with a given label.
     * NOTE: If subclasses know the number of Layouts at
     * constructor time, they should use the constructor
     * below with a num parameter. Otherwise, labels
     * may not appear, among other problems.
     * @param label the label string; null is allowed
     */
    Item(String label) {
        this.label = label;
    }

    /**
     * Creates a new item with a given label.
     *
     * @param label the label string; null is allowed
     * @param num The number of layouts needed for this Item
     */
    Item(String label, int num) {
        // SYNC NOTE: probably safe, but since subclasses can't lock
        // around their call to super(), we'll lock it here
        synchronized (Display.LCDUILock) {
            this.label = label;

            if (num > 0) {
                layouts = new Layout[num];
                layouts[0] = new StringLayout(label, Screen.CONTENT_FONT);
            }
        }
    }

    /**
     * Sets the label of the Item. If label is null, specifies that this
     * item has no label.
     * @param label the label string
     *
     * @see #getLabel
     */
    public void setLabel(String label) {
        // SYNC NOTE: This method must be called from inside a lock of
        // LCDUILock. All subclasses of Item override setLabel(), obtain
        // LCDUILock and call super.setLabel() from within that lock, which
        // is why we can leave it unlocked here.
        this.label = label;
    }
    
    /**
     * Gets the label of this Item object.
     * @return the label string
     *
     * @see #setLabel
     */
    public String getLabel() {
        // SYNC NOTE: return of atomic value, no locking necessary
        return label;
    }

    // package private

    /*
     * Forms contain several items. Changes to items have
     * to be reported to the form. That is why getOwner()
     * setOwner() are needed.
     * Also ChoiceGroup item is used to implement List.
     * As a result ChoiceGroup item can be added to Form or List.
     * That is why owner is a screen.
     */

    /**
     * Get the owner of this Item
     *
     * @return Screen The owner of this Item
     */
    Screen getOwner() {
        return owner;
    }

    /**
     * Set the Screen owner of this Item
     *
     * @param owner The Screen containing this Item
     */
    void setOwner(Screen owner) {
        if (this.owner != null && owner != null) {
            throw new IllegalStateException();
        }
        this.owner = owner;

        if (owner == null) {
            focus = false;
        }
    }

    /**
     * Signal this Item that its focus has changed
     */
    void focusChanged() {
        if (initLayoutDone()) {
            int itemY = owner instanceof Form ? 
                        ((Form)owner).getItemY(this) : 0;
            owner.repaintContent(0, itemY, Display.WIDTH, getHeight());
        }
    }

    /**
     * Set the focus state of this Item
     *
     * @param newFocus A flag indicating this Item has focus or not
     */
    void setFocus(boolean newFocus) {
        if (newFocus != focus) {
            focus = newFocus;
            focusChanged();
        }
    }

    /**
     * Determine if this Item has the focus or not
     *
     * @return boolean A flag indicating this Item has focus or not
     */
    boolean hasFocus() {
        return focus;
    }

    /**
     * Determine if this Item can accept focus or not
     *
     * @return boolean Always returns true by default
     */
    boolean takesFocus() {
        return true;
    }

    /**
     * Initialize the highlight of this Item
     *
     * @param vpY
     * @param vpH
     * @return int Always returns 0
     */
    int initHilight(int vpY, int vpH) {
        return 0;
    }

    /**
     * Traverse this Item
     *
     * @param dir
     * @param top
     * @param bottom
     * @param traversingIn
     * @param allowTraverseOut
     * @return int
     */
    int traverse(int dir, int top, int bottom, 
                    boolean traversingIn,  boolean allowTraverseOut) {
        return Form.traverse(dir == Canvas.DOWN, top, bottom,
                             getHeight(), Screen.CONTENT_HEIGHT, 
                             traversingIn, takesFocus());
    }

    /**
     * Returns height of this item.
     *
     * @return item's height; has to be null when height is not set
     */
    abstract int getHeight();

    /**
     * Sets width of this item. All layout should be done in this 
     * method. Note that height should be at least lineHeight high.
     *
     * @param width The allowable width for this Item
     * @return new height of this item
     */
    abstract int setWidth(int width);

    /**
     * Paint this Item
     *
     * @param g The Graphics context to paint to
     */
    abstract void paint(Graphics g);

    // This method is used by subclasses to repaint only
    // a portion of their display when possible.
    /**
     * Repaint a portion of this Item
     *
     * @param x The x coordinate of the repaint rectangle
     * @param y The y coordinate of the repaint rectangle
     * @param width The width of the repaint rectangle
     * @param height The height of the repaint rectangle
     */
    final void repaint(int x, int y, int width, int height) {
        if (initLayoutDone()) {
            int itemY = owner instanceof Form ?
                ((Form)owner).getItemY(this) : 0;
            owner.repaintContent(x, itemY + y, width, height);
        }
    }

    /**
     * Determine if this Item can be selected
     *
     * @return boolean Always returns false by default
     */
    boolean select() {
        return false;
    }

    /**
     * Indicate that a key has been pressed in relation
     * to this Item.
     *
     * @param keyCode   The code of the key which was pressed
     * @return boolean  A flag of whether this Item has changed
     *                  indicating the appropriate ItemStateListener
     *                  should be notified.
     */
    boolean keyPressed(int keyCode) {
        return false;
    }

    /**
     * Handle a key typed from the keyboard
     *
     * @param c The char entered from the keyboard
     */
    void keyTyped(char c) {}

    /**
     * Signal this Item that its content has changed and it
     * needs to re-layout
     *
     * @param x The x coordinate of the change
     * @param y The y coordinate of the change
     * @param deltaHeight The change in height
     */
    void contentChanged(int x, int y, int deltaHeight) {
        if (initLayoutDone()) {
            owner.contentChanged(this, x, y, deltaHeight);
        }
    }

    /**
     * Several items could be grouped together
     * (their layout will happen at once).
     * Such items will be treated as a group during traversal as well.
     *
     * @param item  to be checked against
     * @return true if this Item and passed in item are part of the 
     *         same group, otherwise false is returned
     */
    boolean isGrouped(Item item) {
        return item == this;
    }

    /**
     * Determines if that item can be grouped with other items in a
     * common layout.
     * @return true if this item can be grouped with others; 
     *         false - otherwise
     */
    boolean isGroupable() {
        return false;
    }

    /**
     * Determine if the initial layout has been done
     *
     * @return boolean A flag indicating this Item has been layed out
     */
    boolean initLayoutDone() {
        return owner != null && owner.initLayoutDone();
    }    
}