Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 appendItem 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()-1], inclusive.

  The semantics are otherwise identical to `append`.

  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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a comment or suggestion Version 0.95 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.