form.java

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

 * can interact
 * with it and its <code>Items</code> indefinitely (for instance,
 * traversing from <code>Item</code>
 * to <code>Item</code>
 * and possibly
 * scrolling). These traversing and scrolling operations do not cause
 * application-visible events. The system notifies
 * the application when the user modifies the state of an interactive
 * <code>Item</code>
 * contained within the <code>Form</code>.  This notification is
 * accomplished by calling the
 * {@link ItemStateListener#itemStateChanged itemStateChanged()}
 * method of the listener declared to the <code>Form</code> with the
 * {@link #setItemStateListener setItemStateListener()} method. </p>
 *
 * <p> As with other <code>Displayable</code> objects, a
 * <code>Form</code> can declare
 * {@link Command commands} and declare a command listener with the
 * {@link Displayable#setCommandListener setCommandListener()} method.
 * {@link CommandListener CommandListener}
 * objects are distinct from
 * {@link ItemStateListener ItemStateListener} objects, and they are declared
 * and invoked separately. </p>
 *
 * <h2>Notes for Application Developers</h2>
 *
 * <UL>
 * <LI>Although this class allows creation of arbitrary combination of
 * components
 * the application developers should keep the small screen size in mind.
 * <code>Form</code> is designed to contain a <em>small number of
 * closely related</em>
 * UI elements. </LI>
 *
 * <LI>If the number of items does not fit on the screen, the
 * implementation may choose to make it scrollable or to fold some components
 * so that a separate screen appears when the element is edited.</LI>
 * </UL>
 *
 * <p>
 * </p>
 *
 * @see Item
 * @since MIDP 1.0
 */

public class Form extends Screen {

// ************************************************************
//  public member variables
// ************************************************************

// ************************************************************
//  protected member variables
// ************************************************************

// ************************************************************
//  package private member variables
// ************************************************************

    /**
     * A boolean declaring whether the contents of the viewport
     * can be traversed using the horizontal traversal keys,
     * ie, left and right
     */
    final boolean TRAVERSE_HORIZONTAL = true;

    /**
     * A boolean declaring whether the contents of the viewport
     * can be traversed using the vertical traversal keys,
     * ie, up and down
     */
    final boolean TRAVERSE_VERTICAL = true;

    /** The spacing, in pixels, between cells */
    static final int CELL_SPACING = 4;
//    static final int CELL_SPACING = 6;

    /** A static identifying a one pixel box for a traversal indicator */
    static final int ONE_PIXEL_BOX = 0;

    /** A static identifying a traversal indicator using triangles */
    static final int TRIANGLE_CORNERS = 1;

    /** A static holding the type of traversal indicator to draw */
    static final int TRAVERSE_INDICATOR = ONE_PIXEL_BOX;
//    static final int TRAVERSE_INDICATOR = TRIANGLE_CORNERS;

    /** A static holding the color of the traversal indicator */
//    static final int TRAVERSE_INDICATOR_COLOR = 0;
    static final int TRAVERSE_INDICATOR_COLOR = Item.DARK_GRAY_COLOR;

    /** A bit mask to capture the horizontal layout directive of an item */
    static final int LAYOUT_HMASK = 0x03;

    /** A bit mask to capture the vertical layout directive of an item */
    static final int LAYOUT_VMASK = 0x30;

// ************************************************************
//  private member variables
// ************************************************************

    /**
     * A Form is always in one of 2 modes:
     *  1. traversing the Form
     *  2. traversing within an Item
     *
     * These 2 modes map to the values:
     *  FORM_TRAVERSE
     *  ITEM_TRAVERSE
     */
    private int formMode;

    /**
     * A value indicating this Form is in "form traverse" mode
     */
    private static final int FORM_TRAVERSE = 0;

    /**
     * A value indicating this Form is in "item traverse" mode
     */
    private static final int ITEM_TRAVERSE = 2;

    /** The item index which has the traversal focus */
    private int traverseIndex = -1;

    /**
     * The traversal indicator should only be shown when the current
     * traversal item is actually interactive. indicateTraverse is
     * true when the traversal indicator should be drawn around the
     * current traversal item.
     */
    private boolean indicateTraverse = true;

    /**
     * Items must have their show/hide notify methods called when
     * they come into and go out of view. This essentially only
     * happens on scrolling, however their method is called in
     * paint(). This flag tells us wether we should be calling
     * the method in the paint routine, and is set in the scroll
     * routine
     */
    private boolean validateVisibility = true;

    /**
     * 'viewable' contains the dimensions and location of the child
     * viewable object within the viewport
     */
    private int[] viewable;

    /**
     * When a Form calls an Item's traverse() method, it passes in
     * an in-out int[] that represents the Item's internal traversal
     * bounds. This gets cached in the visRect variable
     */
    private int[] visRect;

    /**
     * This is the rate at wich the internal array of Items grows if
     * it gets filled up
     */
    private static final int GROW_SIZE = 4;

    /** Array of Items that were added to this form. */
    private Item items[];

    /** The number of actual Items added is numOfItems. */
    private int  numOfItems; // = 0;

    /** itemStateListener that has to be notified of any state changes */
    private ItemStateListener itemStateListener;

    /** 
     * true if a callPointerPressed event has occured without
     * a corresponding callPointerReleased. false otherwise
     */
    private boolean pointerPressed;

// ************************************************************
//  Static initializer, constructor
// ************************************************************

    /**
     * Creates a new, empty <code>Form</code>.
     *
     * @param title the <code>Form's</code> title, or
     * <code>null</code> for no title
     */
    public Form(String title) {
        this(title, null);
    }

    /**
     * Creates a new <code>Form</code> with the specified
     * contents. This is identical to
     * creating an empty <code>Form</code> and then using a set of
     * <code>append</code>
     * methods.  The
     * items array may be <code>null</code>, in which case the
     * <code>Form</code> is created empty.  If
     * the items array is non-null, each element must be a valid
     * <code>Item</code> not
     * already contained within another <code>Form</code>.
     *
     * @param title the <code>Form's</code> title string
     * @param items the array of items to be placed in the
     * <code>Form</code>, or <code>null</code> if there are no
     * items
     * @throws IllegalStateException if one of the items is already owned by
     * another container
     * @throws NullPointerException if an element of the items array is
     * <code>null</code>
     */
    public Form(String title, Item[] items) {
        super(title);

        synchronized (Display.LCDUILock) {

            // Initialize the in-out rect for Item traversal
            visRect = new int[4];

            if (items == null) {
                this.items = new Item[GROW_SIZE];
                // numOfItems was initialized to 0
                // so there is no need to update it
                return;

            } else {
                this.items = new Item[items.length > GROW_SIZE ?
                                      items.length : GROW_SIZE];
            }

            // We have to check all items first so that some
            // items would not be added to a form that was not
            // instanciated
            for (int i = 0; i < items.length; i++) {
                // NullPointerException will be thrown by
                // items[i].getOwner() if items[i] == null;
                if (items[i].getOwner() != null) {
                    throw new IllegalStateException();
                }
            }

            numOfItems = items.length;

            for (int i = 0; i < numOfItems; i++) {
                items[i].setOwner(this);
                this.items[i] = items[i];
            }

        } // synchronized
    }

// ************************************************************
//  public methods
// ************************************************************

    /**
     * Adds an <code>Item</code> into the <code>Form</code>.  The newly
     * added <code>Item</code> becomes the last <code>Item</code> in the
     * <code>Form</code>, and the size of the <code>Form</code> grows
     * by one.
     *
     * @param item the {@link Item Item} to be added.
     * @return the assigned index of the <code>Item</code>
     * @throws IllegalStateException if the item is already owned by
     * a container
     * @throws NullPointerException if item is <code>null</code>
     */
    public int append(Item item) {
        synchronized (Display.LCDUILock) {
            // NullPointerException will be thrown
            // by item.getOwner() if item == null
            if (item.getOwner() != null) {
                throw new IllegalStateException();
            }

            return insertImpl(numOfItems, item);
        }
    }

    /**
     * Adds an item consisting of one <code>String</code> to the
     * <code>Form</code>. The effect of
     * this method is identical to 
     *
     * <p> <code>
     * append(new StringItem(null, str))
     * </code> </p>
     *
     * @param str the <code>String</code> to be added
     * @return the assigned index of the <code>Item</code>
     * @throws NullPointerException if str is <code>null</code>
     */
    public int append(String str) {
        if (str == null) {
            throw new NullPointerException();
        }

        synchronized (Display.LCDUILock) {
            return insertImpl(numOfItems, new StringItem(null, str));
        }
    }
    
    /**
     * Adds an item consisting of one <code>Image</code> to the
     * <code>Form</code>. The effect of
     * this method is identical to 
     *
     * <p> <code>
     * append(new ImageItem(null, img, ImageItem.LAYOUT_DEFAULT, null))
     * </code> </p>
     *
     * @param img the image to be added
     * @return the assigned index of the <code>Item</code>
     * @throws NullPointerException if <code>img</code> is <code>null</code>
     */
    public int append(Image img) {
        if (img == null) {
            throw new NullPointerException();
        }

        synchronized (Display.LCDUILock) {
            return insertImpl(numOfItems,
                new ImageItem(null, img, ImageItem.LAYOUT_DEFAULT, null));
        }
    }

    /**
     * Inserts an item into the <code>Form</code> just prior to
     * the item specified.
     * The size of the <code>Form</code> grows by one.  The
     * <code>itemNum</code> parameter must be
     * within the range <code>[0..size()]</code>, inclusive.
     * The index of the last item is <code>size()-1</code>, and 
     * so there is actually no item whose index is
     * <code>size()</code>. If this value
     * is used for <code>itemNum</code>, the new item is inserted
     * immediately after
     * the last item. In this case, the effect is identical to
     * {@link #append(Item) append(Item)}. 
     *
     * <p> The semantics are otherwise identical to
     * {@link #append(Item) append(Item)}. </p>
     *
     * @param itemNum the index where insertion is to occur
     * @param item the item to be inserted
     * @throws IndexOutOfBoundsException if <code>itemNum</code> is invalid
     * @throws IllegalStateException if the item is already owned by
     * a container
     * @throws NullPointerException if <code>item</code> is
     * <code>null</code>
     */
    public void insert(int itemNum, Item item) {
        synchronized (Display.LCDUILock) {
            // NullPointerException will be thrown
            // by item.getOwner() if item == null
            if (item.getOwner() != null) {
                throw new IllegalStateException();