FileDocCategorySizeDatePackage
Form.javaAPI DocphoneME MR2 API (J2ME)37830Wed May 02 18:00:24 BST 2007javax.microedition.lcdui

Form

public class Form extends Screen
A Form is a Screen that contains an arbitrary mixture of items: images, read-only text fields, editable text fields, editable date fields, gauges, choice groups, and custom items. In general, any subclass of the {@link Item Item} class may be contained within a form. The implementation handles layout, traversal, and scrolling. The entire contents of the Form scrolls together.

Item Management

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.

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.

If the Form is visible on the display when changes to its contents are requested by the application, updates to the display take place as soon as it is feasible for the implementation to do so. Applications need not take any special action to refresh a Form's display after its contents have been modified.

Layout

Layout policy in Form is organized around rows. Rows are typically related to the width of the screen, respective of margins, scroll bars, and such. All rows in a particular Form will have the same width. Rows do not vary in width based on the Items contained within the Form, although they may all change width in certain circumstances, such as when a scroll bar needs to be added or removed. Forms generally do not scroll horizontally.

Forms grow vertically and scroll vertically as necessary. The height of a Form varies depending upon the number of rows and the height of each row. The height of each row is determined by the items that are positioned on that row. Rows need not all have the same height. Implementations may also vary row heights to provide proper padding or vertical alignment of Item labels.

An implementation may choose to lay out Items in a left-to-right or right-to-left direction depending upon the language conventions in use. The same choice of layout direction must apply to all rows within a particular Form.

Prior to the start of the layout algorithm, the Form is considered to have one empty row at the top. The layout algorithm considers each Item in turn, starting at Item zero and proceeding in order through each Item until the last Item in the Form has been processed. If the layout direction (as described above) is left-to-right, the beginning of the row is the left edge of the Form. If the layout direction is right-to-left, the beginning of the row is the right edge of the Form. Items are laid out at the beginning of each row, proceeding across each row in the chosen layout direction, packing as many Items onto each row as will fit, unless a condition occurs that causes the packing of a row to be terminated early. A new row is then added, and Items are packed onto it as described above. Items are packed onto rows, and new rows are added below existing rows as necessary until all Items have been processed by the layout algorithm.

The layout algorithm has a concept of a current alignment. It can have the value LAYOUT_LEFT, LAYOUT_CENTER, or LAYOUT_RIGHT. The value of the current alignment at the start of the layout algorithm depends upon the layout direction in effect for this Form. If the layout direction is left-to-right, the initial alignment value must be LAYOUT_LEFT. If the layout direction is right-to-left, the initial alignment value must be LAYOUT_RIGHT. The current alignment changes when the layout algorithm encounters an Item that has one of the layout directives LAYOUT_LEFT, LAYOUT_CENTER, or LAYOUT_RIGHT. If none of these directives is present on an Item, the current layout directive does not change. This rule has the effect of grouping the contents of the Form into sequences of consecutive Items sharing an alignment value. The alignment value of each Item is maintained internally to the Form and does not affect the Items' layout value as reported by the {@link Item#getLayout Item.getLayout} method.

The layout algorithm generally attempts to place an item on the same row as the previous item, unless certain conditions occur that cause a "row break." When there is a row break, the current item will be placed at the beginning of a new row instead of being placed after the previous item, even if there is room.

A row break occurs before an item if any of the following conditions occurs:

  • the previous item has a row break after it;
  • it has the LAYOUT_NEWLINE_BEFORE directive; or
  • it is a StringItem whose contents starts with "\n";
  • it is a ChoiceGroup, DateField, Gauge, or a TextField, and the LAYOUT_2 directive is not set; or
  • this Item has a LAYOUT_LEFT, LAYOUT_CENTER, or LAYOUT_RIGHT directive that differs from the Form's current alignment.

A row break occurs after an item if any of the following conditions occurs:

  • it is a StringItem whose contents ends with "\n"; or
  • it has the LAYOUT_NEWLINE_AFTER directive; or
  • it is a ChoiceGroup, DateField, Gauge, or a TextField, and the LAYOUT_2 directive is not set.

The presence of the LAYOUT_NEWLINE_BEFORE or LAYOUT_NEWLINE_AFTER directive does not cause an additional row break if there is one already present. For example, if a LAYOUT_NEWLINE_BEFORE directive appears on a StringItem whose contents starts with "\n", there is only a single row break. A similar rule applies with a trailing "\n" and LAYOUT_NEWLINE_AFTER. Also, there is only a single row break if an item has the LAYOUT_NEWLINE_AFTER directive and the next item has the LAYOUT_NEWLINE_BEFORE directive. However, the presence of consecutive "\n" characters, either within a single StringItem or in adjacent StringItems, will cause as many row breaks as there are "\n" characters. This will cause empty rows to be present. The height of an empty row is determined by the prevailing font height of the StringItem within which the "\n" that ends the row occurs.

Implementations may provide additional conditions under which a row break occurs. For example, an implementation's layout policy may lay out labels specially, implicitly causing a break before every Item that has a label. Or, as another example, a particular implementation's user interface style may dictate that a DateField item always appears on a row by itself. In this case, this implementation may cause row breaks to occur both before and after every DateField item.

Given two items with adjacent Form indexes, if none of the specified or implementation-specific conditions for a row break between them occurs, and if space permits, these items should be placed on the same row.

When packing Items onto a row, the width of the item is compared with the remaining space on the row. For this purpose, the width used is the Item's preferred width, unless the Item has the LAYOUT_SHRINK directive, in which case the Item's minimum width is used. If the Item is too wide to fit in the space remaining on the row, the row is considered to be full, a new row is added beneath this one, and the Item is laid out on this new row.

Once the contents of a row have been determined, the space available on the row is distributed by expanding items and by adding space between items. If any items on this row have the LAYOUT_SHRINK directive (that is, they are shrinkable), space is first distributed to these items. Space is distributed to each of these items proportionally to the difference between the each Item's preferred size and its minimum size. At this stage, no shrinkable item is expanded beyond its preferred width.

For example, consider a row that has 30 pixels of space available and that has two shrinkable items A and B. Item A's preferred size is 15 and its minimum size is 10. Item B's preferred size is 30 and its minimum size is 20. The difference between A's preferred and minimum size is 5, and B's difference is 10. The 30 pixels are distributed to these items proportionally to these differences. Therefore, 10 pixels are distributed to item A and 20 pixels to item B.

If after expanding all the shrinkable items to their preferred widths, there is still space left on the row, this remaining space is distributed equally among the Items that have the LAYOUT_EXPAND directive (the stretchable Items). The presence of any stretchable items on a row will cause the Items on this row to occupy the full width of the row.

If there are no stretchable items on this row, and there is still space available on this row, the Items are packed as tightly as possible and are placed on the row according to the alignment value shared by the Items on this row. (Since changing the current alignment causes a row break, all Items on the same row must share the same alignment value.) If the alignment value is LAYOUT_LEFT, the Items are positioned at the left end of the row and the remaining space is placed at the right end of the row. If the alignment value is LAYOUT_RIGHT, the Items are positioned at the right end of the row and the remaining space is placed at the left end of the row. If the alignment value is LAYOUT_CENTER, the Items are positioned in the middle of the row such that the remaining space on the row is divided evenly between the left and right ends of the row.

Given the set of items on a particular row, the heights of these Items are inspected. For each Item, the height that is used is the preferred height, unless the Item has the LAYOUT_VSHRINK directive, in which case the Item's minimum height is used. The height of the tallest Item determines the height of the row. Items that have the LAYOUT_VSHRINK directive are expanded to their preferred height or to the height of the row, whichever is smaller. Items that are still shorter than the row height and that have the LAYOUT_VEXPAND directive will expand to the height of the row. The LAYOUT_VEXPAND directive on an item will never increase the height of a row.

Remaining Items shorter than the row height will be positioned vertically within the row using the LAYOUT_TOP, LAYOUT_BOTTOM, and LAYOUT_VCENTER directives. If no vertical layout directive is specified, the item must be aligned along the bottom of the row.

StringItems are treated specially in the above algorithm. If the contents of a StringItem (its string value, exclusive of its label) contain a newline character ("\n"), the string should be split at that point and the remainder laid out starting on the next row.

If one or both dimensions of the preferred size of a StringItem have been locked, the StringItem is wrapped to fit that width and height and is treated as a rectangle whose minimum and preferred width and height are the width and height of this rectangle. In this case, the LAYOUT_SHRINK, LAYOUT_EXPAND, and LAYOUT_VEXPAND directives are ignored.

If both dimensions of the preferred size of a StringItem are unlocked, the text from the StringItem may be wrapped across multiple rows. At the point in the layout algorithm where the width of the Item is compared to the remaining space on the row, as much text is taken from the beginning of the StringItem as will fit onto the current row. The contents of this row are then positioned according to the current alignment value. The remainder of the text in the StringItem is line-wrapped to the full width of as many new rows as are necessary to accommodate the text. Each full row is positioned according to the current alignment value. The last line of the text might leave space available on its row. If there is no row break following this StringItem, subsequent Items are packed into the remaining space and the contents of the row are positioned according to the current alignment value. This rule has the effect of displaying the contents of a StringItem as a paragraph of text set flush-left, flush-right, or centered, depending upon whether the current alignment value is LAYOUT_LEFT, LAYOUT_RIGHT, or LAYOUT_CENTER, respectively. The preferred width and height of a StringItem wrapped across multiple rows, as reported by the {@link Item#getPreferredWidth Item.getPreferredWidth} and {@link Item#getPreferredHeight Item.getPreferredHeight} methods, describe the width and height of the bounding rectangle of the wrapped text.

ImageItems are also treated specially by the above algorithm. The foregoing rules concerning the horizontal alignment value and the LAYOUT_LEFT, LAYOUT_RIGHT, and LAYOUT_CENTER directives, apply to ImageItems only when the LAYOUT_2 directive is also present on that item. If the LAYOUT_2 directive is not present on an ImageItem, the behavior of the LAYOUT_LEFT, LAYOUT_RIGHT, and LAYOUT_CENTER directives is implementation-specific.

A Form's layout is recomputed automatically as necessary. This may occur because of a change in an Item's size caused by a change in its contents or because of a request by the application to change the Item's preferred size. It may also occur if an Item's layout directives are changed by the application. The application does not need to perform any specific action to cause the Form's layout to be updated.

Line Breaks and Wrapping

For all cases where text is wrapped, line breaks must occur at each newline character ('\n' = Unicode 'U+000A'). If space does not permit the full text to be displayed it is truncated at line breaks. If there are no suitable line breaks, it is recommended that implementations break text at word boundaries. If there are no word boundaries, it is recommended that implementations break text at character boundaries.

Labels that contain line breaks may be truncated at the line break and cause the rest of the label not to be shown.

User Interaction

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.

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.

Notes for Application Developers

  • 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 small number of closely related UI elements.
  • 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.

see
Item
since
MIDP 1.0

Fields Summary
Item[]
items
Array of Items that were added to this form.
int
numOfItems
The number of actual Items added is numOfItems.
FormLF
formLF
The Form look&feel object associated with this Form
private static final int
GROW_SIZE
This is the rate at which the internal array of Items grows if it gets filled up
private ItemStateListener
itemStateListener
itemStateListener that has to be notified of any state changes
Constructors Summary
public Form(String title)
Creates a new, empty Form.

param
title the Form's title, or null for no title

        this(title, null);
public Form(String title, Item[] items)
Creates a new Form with the specified contents. This is identical to creating an empty Form and then using a set of append 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

        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

            } 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
                // instantiated
                for (int i = 0; i < items.length; i++) {
                    // NullPointerException will be thrown by
                    // items[i].owner if items[i] == null;
                    if (items[i].owner != null) {
                        throw new IllegalStateException();
                    }
                }
                
                numOfItems = items.length;
                
                for (int i = 0; i < numOfItems; i++) {
                    items[i].lSetOwner(this);
                    this.items[i] = items[i];
                }
            }
            displayableLF = formLF = LFFactory.getFactory().getFormLF(this);
        } // synchronized
Methods Summary
public intappend(Item item)
Adds an Item into the Form. The newly added Item becomes the last Item in the Form, and the size of the Form grows by one.

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

        synchronized (Display.LCDUILock) {
            // NullPointerException will be thrown
            // by item.owner if item == null
            if (item.owner != null) {
                throw new IllegalStateException();
            }
            int i = insertImpl(numOfItems, item);
            formLF.lInsert(i, item);
            return i;
        }
public intappend(java.lang.String str)
Adds an item consisting of one String to the Form. The effect of this method is identical to

append(new StringItem(null, str))

param
str the String to be added
return
the assigned index of the Item
throws
NullPointerException if str is null

        if (str == null) {
            throw new NullPointerException();
        }

        synchronized (Display.LCDUILock) {
            Item item = new StringItem(null, str);
            int i = insertImpl(numOfItems, item);
            formLF.lInsert(i, item);
            return i;
        }
public intappend(Image img)
Adds an item consisting of one Image to the Form. The effect of this method is identical to

append(new ImageItem(null, img, ImageItem.LAYOUT_DEFAULT, null))

param
img the image to be added
return
the assigned index of the Item
throws
NullPointerException if img is null

        if (img == null) {
            throw new NullPointerException();
        }

        synchronized (Display.LCDUILock) {
            Item item = new ImageItem(null, img, 
                                      ImageItem.LAYOUT_DEFAULT, null);
            int i = insertImpl(numOfItems, item);
            formLF.lInsert(i, item);
            return i;
        }
public voiddelete(int itemNum)
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.

param
itemNum the index of the item to be deleted
throws
IndexOutOfBoundsException if itemNum is invalid

    	Item deletedItem;
        synchronized (Display.LCDUILock) {
            if (itemNum < 0 || itemNum >= numOfItems) {
                throw new IndexOutOfBoundsException();
            }

            deletedItem = items[itemNum];

            numOfItems--;

            if (itemNum < numOfItems) {
                System.arraycopy(items, itemNum + 1, items, itemNum,
                                 numOfItems - itemNum);
            }

            // Delete reference to the last item 
            // that was left after array copy
            items[numOfItems] = null;

            // The Form is clear; reset its state
            if (numOfItems == 0 && items.length > GROW_SIZE) {
                items = new Item[GROW_SIZE];                 // start fresh
            }

            formLF.lDelete(itemNum, deletedItem);

        } // synchronized
        
        deletedItem.itemDeleted();
public voiddeleteAll()
Deletes all the items from this Form, leaving it with zero items. This method does nothing if the Form is already empty.

    	Item[] itemsCopy;
        synchronized (Display.LCDUILock) {
            if (numOfItems == 0) {
                return;
            }
            itemsCopy = new Item[numOfItems];

            for (int x = 0; x < numOfItems; x++) {
                itemsCopy[x] = items[x];
                items[x] = null;
            }
            if (items.length > GROW_SIZE) {
                items = new Item[GROW_SIZE];                     // start fresh
            }

            // Reset form state
            numOfItems = 0;

            formLF.lDeleteAll();
        }
        
        for (int x = 0; x < itemsCopy.length; x++) {
            itemsCopy[x].itemDeleted();
        }
public Itemget(int itemNum)
Gets the item at given position. The contents of the Form are left unchanged. The itemNum parameter must be within the range [0..size()-1], inclusive.

param
itemNum the index of item
return
the item at the given position
throws
IndexOutOfBoundsException if itemNum is invalid

        synchronized (Display.LCDUILock) {
            if (itemNum < 0 || itemNum >= numOfItems) {
                throw new IndexOutOfBoundsException();
            }

            return items[itemNum];
        }
public intgetHeight()
Returns the height in pixels of the displayable area available for items. This value is the height of the form that can be displayed without scrolling. The value may depend on how the device uses the screen and may be affected by the presence or absence of the ticker, title, or commands.

return
the height of the displayable area of the Form in pixels

	synchronized (Display.LCDUILock) {
	    return formLF.lGetHeight();
	}
ItemStateListenergetItemStateListener()
Retrieve the ItemStateListener for this Form. NOTE: calls to this method should only occur from within a lock on LCDUILock.

return
ItemStateListener The ItemStateListener of this Form, null if there isn't one set

        return itemStateListener;
public intgetWidth()
Returns the width in pixels of the displayable area available for items. The value may depend on how the device uses the screen and may be affected by the presence or absence of the ticker, title, or commands. The Items of the Form are laid out to fit within this width.

return
the width of the Form in pixels

	synchronized (Display.LCDUILock) {
	    return formLF.lGetWidth();
	}
public voidinsert(int itemNum, Item item)
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)}.

The semantics are otherwise identical to {@link #append(Item) append(Item)}.

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

        synchronized (Display.LCDUILock) {
            // NullPointerException will be thrown
            // by item.owner if item == null
            if (item.owner != null) {
                throw new IllegalStateException();
            }

            if (itemNum < 0 || itemNum > numOfItems) {
                throw new IndexOutOfBoundsException();
            }
            insertImpl(itemNum, item);
            formLF.lInsert(itemNum, item);
        }
private intinsertImpl(int itemNum, Item item)
Insert an Item into this Form

param
itemNum The index into the Item array to insert this Item
param
item The Item to insert
return
int The index at which the newly inserted Item can be found


        if (items.length == numOfItems) {
            Item newItems[] = new Item[numOfItems + GROW_SIZE];
            System.arraycopy(items, 0, newItems, 0, itemNum);
            System.arraycopy(items, itemNum, newItems, itemNum + 1,
                             numOfItems - itemNum);
            items = newItems;
        } else {
            // if we're not appending
            if (itemNum != numOfItems) {
                System.arraycopy(items, itemNum, items, itemNum + 1,
                                 numOfItems - itemNum);
            }
        }

        numOfItems++;

        //
        // the arraycopy copied the reference to the item at this
        // spot. if we call setImpl without setting the index to null
        // setImpl will set the items owner to null.
        //
        item.lSetOwner(this);
        items[itemNum] = item;

        return itemNum;
public voidset(int itemNum, Item item)
Sets the item referenced by itemNum to the specified item, replacing the previous item. The previous item is removed from this Form. The itemNum parameter must be within the range [0..size()-1], inclusive.

The end result is equal to insert(n, item); delete(n+1);
although the implementation may optimize the repainting and usage of the array that stores the items.

param
itemNum the index of the item to be replaced
param
item the new item to be placed in the Form
throws
IndexOutOfBoundsException if itemNum is invalid
throws
IllegalStateException if the item is already owned by a container
throws
NullPointerException if item is null

        synchronized (Display.LCDUILock) {
            // NullPointerException will be thrown
            // by item.owner if item == null
            if (item.owner != null) {
                throw new IllegalStateException();
            }

            if (itemNum < 0 || itemNum >= numOfItems) {
                throw new IndexOutOfBoundsException();
            }

            items[itemNum].lSetOwner(null);
            item.lSetOwner(this);

            items[itemNum] = item;

            formLF.lSet(itemNum, item);
        }
public voidsetItemStateListener(ItemStateListener iListener)
Sets the ItemStateListener for the Form, replacing any previous ItemStateListener. If iListener is null, simply removes the previous ItemStateListener.

param
iListener the new listener, or null to remove it

        synchronized (Display.LCDUILock) {
            itemStateListener = iListener;
        }
public intsize()
Gets the number of items in the Form.

return
the number of items

        synchronized (Display.LCDUILock) {
	    return numOfItems;
	}
voiduCallItemStateChanged(Item item)
Used by the event handler to notify the ItemStateListener of a change in the given item

param
item the Item which state was changed

        // get a copy of the object reference to ItemStateListener
        ItemStateListener isl = itemStateListener;
        if (isl == null || item == null) {
            return;
        }

        // Protect from any unexpected application exceptions
        try {
            // SYNC NOTE: We lock on calloutLock around any calls
            // into application code
            synchronized (Display.calloutLock) {
                isl.itemStateChanged(item);
            }
        } catch (Throwable thr) {
            Display.handleThrowable(thr);
        }