javax.microedition.lcdui
Class Form

java.lang.Object
  |
  +--javax.microedition.lcdui.Displayable
        |
        +--javax.microedition.lcdui.Screen
              |
              +--javax.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, and choice groups. In general, any subclass of the 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.

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.

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.

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 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.

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.

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 itemStateChanged() method of the listener declared to the Form with the setItemStateListener() method.

As with other Displayable objects, a Form can declare commands and declare a command listener with the setCommandListener() method. CommandListener objects are distinct from 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 new screen is popping up when the element is edited.

See Also:

Item

Constructor Summary

Form(String title)
Creates a new, empty Form.

Form(String title, Item[] items)
Creates a new Form with the specified contents.

Method Summary

int	append(Image img) Adds an item consisting of one Image to the form.
int	append(Item item) Adds an Item into the Form.
int	append(String str) Adds an item consisting of one String to the form.
void	delete(int itemNum) Deletes the Item referenced by itemNum.
Item	get(int itemNum) Gets the item at given position.
void	insert(int itemNum, Item item) Inserts an item into the Form just prior to the item specified.
void	set(int itemNum, Item item) Sets the item referenced by itemNum to the specified item, replacing the previous item.
void	setItemStateListener(ItemStateListener iListener) Sets the ItemStateListener for the Form, replacing any previous ItemStateListener.
int	size() Gets the number of items in the Form.

Methods inherited from class javax.microedition.lcdui.Screen

getTicker, getTitle, setTicker, setTitle

Methods inherited from class javax.microedition.lcdui.Displayable

addCommand, isShown, removeCommand, setCommandListener

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Form

public Form(String title)

Creates a new, empty Form.

Parameters:

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

Form

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.

Parameters:

title - the Form's title string

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

NullPointerException - if an element of the items array is null

Method Detail

append

public int append(Item item)

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.

Images are laid out in the same manner as strings, unless the layout directives of ImageItem specify otherwise. Focusable items (TextField, ChoiceGroup, DateField, and Gauge) are placed on their own horizontal lines.

Parameters:

item - the Item to be added.

Returns:

the assigned index of the Item

Throws:

IllegalStateException - if the item is already owned by a container

NullPointerException - if item is null

append

public int append(String str)

Adds an item consisting of one String to the form. The effect visible to the application is identical to

append(new StringItem(null, str))

Parameters:

str - the String to be added

Returns:

the assigned index of the Item

Throws:

NullPointerException - if str is null

append

public int append(Image img)

Adds an item consisting of one Image to the form. The effect visible to the application is identical to

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

Parameters:

img - the image to be added

Returns:

the assigned index of the Item

Throws:

IllegalArgumentException - if the image is mutable

NullPointerException - if img is null

insert

public void insert(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 append(Item).

The semantics are otherwise identical to append(Item).

Parameters:

itemNum - the index where insertion is to occur

item - the item to be inserted

Throws:

IndexOutOfBoundsException - if itemNum is invalid

IllegalStateException - if the item is already owned by a container

NullPointerException - if item is null

delete

public void delete(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.

Parameters:

itemNum - the index of the item to be deleted

Throws:

IndexOutOfBoundsException - if itemNum is invalid

set

public void set(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.

Parameters:

itemNum - the index of the item to be replaced

item - the new item to be placed in the Form

Throws:

IndexOutOfBoundsException - if itemNum is invalid

IllegalStateException - if the item is already owned by a container

NullPointerException - if item is null

get

public Item get(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.

Parameters:

itemNum - the index of item

Returns:

the item at the given position

Throws:

IndexOutOfBoundsException - if itemNum is invalid

setItemStateListener

public void setItemStateListener(ItemStateListener iListener)

Sets the ItemStateListener for the Form, replacing any previous ItemStateListener. If iListener is null, simply removes the previous ItemStateListener.

Parameters:

iListener - the new listener, or null to remove it

size

public int size()

Gets the number of items in the Form.

Returns:

the number of items