form.java

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

/*
 * @(#)Form.java	1.134 01/08/29
 * 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 Form is a Screen that contains an arbitrary mixture of items: images,
 * read-only text fields, editable text fields, editable date fields, gauges,
 * and choice groups. In general, any subclass of the
 * {@link Item Item} class may be contained within a form.
 * The implementation handles layout, traversal, and scrolling.
 * None of the components contained
 * within has any internal scrolling; the entire contents
 * scrolls together. Note that this differs
 * from the behavior of other classes, the List for example,
 * where only the interior scrolls. <P>
 *
 * <p> The items contained within a Form may be edited using append, delete,
 * insert, and set methods.  Items within a Form are referred to by their
 * indexes, which are consecutive integers in the range from zero to size()-1,
 * with zero referring to the first item and size()-1 to the last item.  </p>
 *
 * <p> An item may be placed within at most one Form. If the application
 * attempts to place an item into a Form, and the item is already owned by this
 * or another Form, an IllegalStateException is thrown. The application must
 * remove the item from its currently containing Form before inserting it into
 * the new Form. </p>
 *
 * <p> As with other screens, the layout policy in most devices is
 * vertical. In forms this applies to items involving user
 * input. So, a new line is always started for focusable items like
 * TextField, DateField, Gauge or ChoiceGroup. </p>
 *
 * <P>Strings and images, which do not involve user interactions,
 * behave differently; they are
 * filled in horizontal lines, unless newline is embedded in the
 * string or layout directives of the {@link ImageItem ImageItem}
 * force a new line.
 * Contents will be wrapped (for text) or clipped (for
 * images) to fit the width of the display, and scrolling will
 * occur vertically as necessary. There will be no horizontal
 * scrolling. </P>
 *
 * <p> If the Form is visible on the display when changes to its contents are
 * requested by the application, the changes take place immediately. That is,
 * applications need not take any special action to refresh a Form's display
 * after its contents have been modified. </p>
 *
 * <p> When a Form is present on the display the user can interact
 * with it and its Items indefinitely (for instance, traversing
 * from Item to Item 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 Item 
 * contained within the Form.  This notification is accomplished by calling the
 * {@link ItemStateListener#itemStateChanged itemStateChanged()}
 * method of the listener declared to the Form with the
 * {@link #setItemStateListener setItemStateListener()} method. </p>
 *
 * <p> As with other Displayable objects, a Form 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>
 * 
 * <P><B>Notes for application developers:</B></P>
 * <UL>
 * <LI>Although this class allows creation of arbitrary combination 
 * of components
 * the application developers should keep the small screen size in mind.
 * Form 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 new screen is popping up when the element is edited.</LI>
 * </UL>
 *
 * @see Item
 */
public class Form extends Screen {

    /**
     * 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;

    /** Item currently displayed (not -1 if there is at least 1 item) */
    private int curItemIndex = -1;
    /** Y position of the currently selected item */
    private int curItemY;   // = 0; in coordinate system of Form's child

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

    /**
     * Creates a new, empty Form.
     *
     * @param title the Form's title, or null for no title
     */
    public Form(String title) {
        this(title, null);
    }
    
    /**
     * Creates a new Form with the specified contents. This is identical to
     * creating an empty Form and then using a set of <code>append</code>
     * methods.  The 
     * items array may be null, in which case the Form is created empty.  If 
     * the items array is non-null, each element must be a valid Item not 
     * already contained within another Form.
     *
     * @param title the Form's title string
     * @param items the array of items to be placed in the Form, or null 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 null
     */
    public Form(String title, Item[] items) {
        super(title);

        synchronized (Display.LCDUILock) {

            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;

            TaGLayout lastTagLayout = null;

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

                // Group adjacent StringItems and ImageItems into TaGLayouts
                if (items[i].isGroupable()) {
                    if (lastTagLayout == null) {
                        lastTagLayout = new TaGLayout(Screen.CONTENT_FONT);
                    }
                    lastTagLayout.insert(null, items[i]);
                } else {
                    lastTagLayout = null;
                }
                this.items[i] = items[i];
            }
        } // synchronized
    }


    /**
     * Adds an Item into the Form. Strings are filled so that current line
     * is continued if possible. If the text width is greater that the remaining
     * horizontal space on the current line, the implementation inserts
     * a new line
     * and appends the rest of the text. Whenever possible the implementation
     * should avoid breaking words into two lines. Instead, occurrences of white
     * space (space or tab) should be used as potential places for splitting the
     * lines. Also, a newline character in the string causes starting of a new
     * line. <P>
     *
     * Images are laid out in the same manner as strings, unless the layout
     * directives of {@link ImageItem ImageItem} specify otherwise. Focusable
     * items (TextField, ChoiceGroup, DateField, and Gauge) are placed on their
     * own horizontal lines. <p>
     *
     * @param item the {@link Item Item} to be added.
     * @return the assigned index of the Item
     * @throws IllegalStateException if the item is already owned by
     * a container
     * @throws NullPointerException if item is null
     */
    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);
        }
    }

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

        synchronized (Display.LCDUILock) {
            return insertImpl(numOfItems, new StringItem(null, str));
        }
    }
    
    /**
     * <p> Adds an item consisting of one Image to the form. The effect visible
     * to the application is identical to </p>
     *
     * <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 Item
     * @throws IllegalArgumentException if the image is mutable
     * @throws NullPointerException if img is null
     */
    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));
        }
    }

    /**
     * <p> Inserts an item into the Form just prior to the item specified.
     * The size of the Form grows by one.  The itemNum parameter must be 
     * within the range [0..size()], inclusive.
     * The index of the last item is size()-1, and 
     * so there is actually no item whose index is size(). If this value
     * is used for itemNum, the new item is inserted immediately after
     * the last item. In this case, the effect is identical to
     * {@link #append(Item) append(Item)}. </p>
     *
     * <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 itemNum is invalid
     * @throws IllegalStateException if the item is already owned by
     * a container
     * @throws NullPointerException if item is null
     */
    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();
            }

            if (itemNum < 0 || itemNum > numOfItems) {
                throw new IndexOutOfBoundsException();
            }
            insertImpl(itemNum, item);
        }
    }

    /**
     * <p> Deletes the Item referenced by itemNum. The size of the Form
     * shrinks by one. It is legal to delete all items from a Form.
     * The itemNum parameter must be 
     * within the range [0..size()-1], inclusive. </p>
     *
     * @param itemNum the index of the item to be deleted
     * @throws IndexOutOfBoundsException if itemNum is invalid
     */
    public void delete(int itemNum) {
        synchronized (Display.LCDUILock) {
            if (itemNum < 0 || itemNum >= numOfItems) {
                throw new IndexOutOfBoundsException();
            }

            Item deletedItem = items[itemNum];
            int deletedHeight =
                initLayoutDone() ? -deletedItem.getHeight() : 0;

            if (deletedItem.isGroupable()) {
                
                // delete this item from the layout
                deletedHeight =
                    ((TaGLayout)deletedItem.layouts[0]).delete(deletedItem);

            } else if (itemNum > 0 && itemNum < numOfItems - 1) {

                // it is possible that deleted item was surrounded
                // StringItems and/or ImageItems 
                // that now have to be grouped
                if (items[itemNum-1].isGroupable() && 
                    items[itemNum+1].isGroupable()) {