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:

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.
 void deleteAll()
          Deletes all the items from this Form, leaving it with zero items.
 Item get(int itemNum)
           Gets the item at given position.
 int getHeight()
          Returns the height in pixels of the displayable area available for items.
 int getWidth()
          Returns the width in pixels of the displayable area available for items.
 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, sizeChanged
 
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
Since:
JDE 4.0.2

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
Since:
JDE 4.0.2

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
Since:
JDE 4.0.2

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
Since:
JDE 4.0.2

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
Since:
JDE 4.0.2

deleteAll

public void deleteAll()
Deletes all the items from this Form, leaving it with zero items. This method does nothing if the Form is already empty.
Since:
MIDP 2.0

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
Since:
JDE 4.0.2

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
Since:
JDE 4.0.2

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
Since:
JDE 4.0.2

size

public int size()
Gets the number of items in the Form.
Returns:
the number of items

getWidth

public int getWidth()
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.
Overrides:
getWidth in class Displayable
Returns:
the width of the Form in pixels
Since:
MIDP 2.0

getHeight

public int getHeight()
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.
Overrides:
getHeight in class Displayable
Returns:
the height of the displayable area of the Form in pixels
Since:
MIDP 2.0


Copyright 1999-2004 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.