MID Profile

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 container object (an instance of either Form or Alert) may be edited using append, delete, insert, and set methods. An item may be placed within at most one container object. If the application attempts to place an item into a container, and the item is already owned by this or another container, IllegalStateException is thrown. The application must remove the item from its container before inserting it into the new container.

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.

Notes for application developers:


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 appendImage(Image img)
           Adds an item consisting of one Image to the form.
 int appendItem(Item item)
          Adds an Item into the Form.
 int appendString(String str)
           Adds an item consisting of one String to the form.
 void deleteItem(int itemNum)
          Deletes the Item referenced by itemNum.
 Item getItemAt(int itemNum)
          Gets the item at given position.
 int getSize()
          Gets the number of items in the Form.
 int insertItem(int itemNum, Item item)
           Inserts an item into the Form just prior to the item specified.
 void setItem(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.
 
Methods inherited from class javax.microedition.lcdui.Screen
getTicker, getTitle, setTicker, setTitle
 
Methods inherited from class javax.microedition.lcdui.Displayable
addCommand, isShown, removeCommand, setListener
 
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 appendItem methods.
Parameters:
title - the Form's title string
items - the array of Items to be added.
Throws:
IllegalStateException - if one of the items is already owned by another container
Method Detail

appendItem

public int appendItem(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 number of the Item
Throws:
IllegalStateException - if the item is already owned by a container
NullPointerException - if item is null

appendString

public int appendString(String str)

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

appendItem(new StringItem(null, str))

Parameters:
str - the String to be added
Returns:
the assigned number of the Item
Throws:
NullPointerException - if str is null

appendImage

public int appendImage(Image img)

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

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

Parameters:
img - the image to be added
Returns:
the assigned number of the Item.
Throws:
IllegalArgumentException - if the image is mutable
NullPointerException - if img is null

insertItem

public int insertItem(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 semantics are otherwise identical to appendItem.

Parameters:
itemNum - the number of the item. Indexing of the items is zero-based.
item - the item to be added
Returns:
the assigned number of the Item
Throws:
ArrayIndexOutOfBoundsException - if itemNum specifies an invalid item
IllegalStateException - if the item is already owned by a container
NullPointerException - if item is null

deleteItem

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

Parameters:
itemNum - the number of the item. Indexing of the items is zero-based.
Throws:
ArrayIndexOutOfBoundsException - if itemNum specifies an invalid item.

setItem

public void setItem(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 end result is equal to

insertItem(n, item); deleteItem(n+1);
although the implementation may optimize the repainting and usage of the array that stores the items.

Parameters:
itemNum - the number of the item. Indexing of the items is zero-based.
item - the item to be replaced.
Throws:
ArrayIndexOutOfBoundsException - if itemNum specifies an invalid item.
IllegalStateException - if the item is already owned by a container

getItemAt

public Item getItemAt(int itemNum)
Gets the item at given position. The first position is zero.
Parameters:
itemNum - the index of item
Returns:
Item at the given position
Throws:
ArrayIndexOutOfBoundsException - if itemNum is less than zero or greater than or equal to size of the Form.

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

getSize

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

MID Profile

Submit a comment or suggestion Version 0.9 of MID Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A. All Rights Reserved.