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

## javax.microedition.lcdui
Class List

    java.lang.Object
      javax.microedition.lcdui.Displayable
          javax.microedition.lcdui.Screen
              javax.microedition.lcdui.List

All Implemented Interfaces:
  Choice

public class List
extends Screen
implements Choice

A `Screen` containing list of choices. Most of its behavior is common with class `ChoiceGroup`, and their common API. The different `List` types in particular, are defined in interface `Choice`. When a `List` is present on the display, the user can interact with it by selecting elements and possibly by traversing and scrolling among them. Traversing and scrolling operations do not cause application-visible events. The system notifies the application only when a `Command` is invoked by notifying its `CommandListener`. The `List` class also supports a select command that may be invoked specially depending upon the capabilities of the device.

The notion of a select operation on a `List` element is central to the user's interaction with the `List`. On devices that have a dedicated hardware "select" or "go" key, the select operation is implemented with that key. Devices that do not have a dedicated key must provide another means to do the select operation, for example, using a soft key. The behavior of the select operation within the different types of lists is described in the following sections.

`List` objects may be created with `Choice` types of `Choice.EXCLUSIVE`, `Choice.MULTIPLE`, and `Choice.IMPLICIT`. The `Choice` type `Choice.POPUP` is not allowed on `List` objects.

### Selection in `EXCLUSIVE` and `MULTIPLE` Lists

The select operation is not associated with a `Command` object, so the application has no means of setting a label for it or being notified when the operation is performed. In `Lists` of type `EXCLUSIVE`, the select operation selects the target element and deselects the previously selected element. In `Lists` of type `MULTIPLE`, the select operation toggles the selected state of the target element, leaving the selected state of other elements unchanged. Devices that implement the select operation using a soft key will need to provide a label for it. The label should be something similar to "Select" for `Lists` of type `EXCLUSIVE`, and it should be something similar to "Mark" or "Unmark" for `Lists` of type `MULTIPLE`.

### Selection in `IMPLICIT` Lists

The select operation is associated with a `Command` object referred to as the select command. When the user performs the select operation, the system will invoke the select command by notifying the `List's` `CommandListener`. The default select command is the system-provided command `SELECT_COMMAND`. The select command may be modified by the application through use of the `setSelectCommand` method. Devices that implement the select operation using a soft key will use the label from the select command. If the select command is `SELECT_COMMAND`, the device may choose to provide its own label instead of using the label attribute of `SELECT_COMMAND`. Applications should generally provide their own select command to replace `SELECT_COMMAND`. This allows applications to provide a meaningful label, instead of relying on the one provided by the system for `SELECT_COMMAND`. The implementation must not invoke the select command if there are no elements in the `List`, because if the `List` is empty the selection does not exist. In this case the implementation should remove or disable the select command if it would appear explicitly on a soft button or in a menu. Other commands can be invoked normally when the `List` is empty.

### Use of `IMPLICIT` Lists

`IMPLICIT` `Lists` can be used to construct menus by providing operations as `List` elements. The application provides a `Command` that is used to select a `List` element and then defines this `Command` to be used as the select command. The application must also register a `CommandListener` that is called when the user selects or activates the `Command`:

         String[] elements = { ... }; //Menu items as List elements
         List menuList = new List("Menu", List.IMPLICIT, elements, null);
         Command selectCommand = new Command("Open", Command.ITEM, 1);
         menuList.setSelectCommand(selectCommand);
         menuList.setCommandListener(...);

The listener can query the `List` to determine which element is selected and then perform the corresponding action. Note that setting a command as the select command adds it to the `List` as a side effect.

The select command should be considered as a default operation that takes place when a select key is pressed. For example, a `List` displaying email headers might have three operations: read, reply, and delete. Read is considered to be the default operation.

         List list = new List("Email", List.IMPLICIT, headers);
         readCommand = new Command("Read", Command.ITEM, 1);
         replyCommand = new Command("Reply", Command.ITEM, 2);
         deleteCommand = new Command("Delete", Command.ITEM, 3);
         list.setSelectCommand(readCommand);
         list.addCommand(replyCommand);
         list.addCommand(deleteCommand);
         list.setCommandListener(...);

On a device with a dedicated select key, pressing this key will invoke `readCommand`. On a device without a select key, the user is still able to invoke the read command, since it is also provided as an ordinary `Command`.

It should be noted that this kind of default operation must be used carefully, and the usability of the resulting user interface must always kept in mind. The default operation should always be the most intuitive operation on a particular List.

Since:
  MIDP 1.0

Field Summary
`static Command` | `SELECT_COMMAND` The default select command for `IMPLICIT` `Lists`.

Fields inherited from interface javax.microedition.lcdui.Choice
`EXCLUSIVE, IMPLICIT, MULTIPLE, POPUP, TEXT_WRAP_DEFAULT, TEXT_WRAP_OFF, TEXT_WRAP_ON`

Constructor Summary
`List(String title, int listType)` Creates a new, empty `List`, specifying its title and the type of the list.
`List(String title, int listType, String[] stringElements, Image[] imageElements)` Creates a new `List`, specifying its title, the type of the `List`, and an array of `Strings` and `Images` to be used as its initial contents.

Method Summary
`int` | `append(String stringPart, Image imagePart)` Appends an element to the `List`.
`void` | `delete(int elementNum)` Deletes the element referenced by `elementNum`.
`void` | `deleteAll()` Deletes all elements from this List.
`int` | `getFitPolicy()` Gets the application's preferred policy for fitting `Choice` element contents to the available screen space.
`Font` | `getFont(int elementNum)` Gets the application's preferred font for rendering the specified element of this `Choice`.
`Image` | `getImage(int elementNum)` Gets the `Image` part of the element referenced by `elementNum`.
`int` | `getSelectedFlags(boolean[] selectedArray_return)` Queries the state of a `List` and returns the state of all elements in the boolean array `selectedArray_return`.
`int` | `getSelectedIndex()` Returns the index number of an element in the `List` that is selected.
`String` | `getString(int elementNum)` Gets the `String` part of the element referenced by `elementNum`.
`void` | `insert(int elementNum, String stringPart, Image imagePart)` Inserts an element into the `List` just prior to the element specified.
`boolean` | `isSelected(int elementNum)` Gets a boolean value indicating whether this element is selected.
`void` | `removeCommand(Command cmd)` The same as `Displayable.removeCommand` but with the following additional semantics.
`void` | `set(int elementNum, String stringPart, Image imagePart)` Sets the `String` and `Image` parts of the element referenced by `elementNum`, replacing the previous contents of the element.
`void` | `setFitPolicy(int fitPolicy)` Sets the application's preferred policy for fitting `Choice` element contents to the available screen space.
`void` | `setFont(int elementNum, Font font)` Sets the application's preferred font for rendering the specified element of this `Choice`.
`void` | `setSelectCommand(Command command)` Sets the `Command` to be used for an `IMPLICIT` `List` selection action.
`void` | `setSelectedFlags(boolean[] selectedArray)` Sets the selected state of all elements of the `List`.
`void` | `setSelectedIndex(int elementNum, boolean selected)` Sets the selected state of an element.
`void` | `setTicker(Ticker ticker)` Sets a ticker for use with this `Displayable`, replacing any previous ticker.
`void` | `setTitle(String s)` Sets the title of the `Displayable`.
`int` | `size()` Gets the number of elements in the `List`.

Methods inherited from class javax.microedition.lcdui.Displayable
`addCommand, getHeight, getTicker, getTitle, getWidth, isShown, setCommandListener, sizeChanged`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### SELECT_COMMAND

    public static final Command SELECT_COMMAND

  The default select command for `IMPLICIT` `Lists`. Applications using an `IMPLICIT` `List` should set their own select command using `setSelectCommand`.

  The field values of `SELECT_COMMAND` are:
  - `label = ""` (an empty string)
  - `type = SCREEN`
  - `priority = 0`

  (It would be more appropriate if the type were `ITEM`, but the type of `SCREEN` is retained for historical purposes.)

  The application should not use these values for recognizing the `SELECT_COMMAND`. Instead, object identities of the `Command` and `Displayable` (`List`) should be used.

  `SELECT_COMMAND` is treated as an ordinary `Command` if it is used with other `Displayable` types.

Constructor Detail

### List

    public List(String title,
                int listType)

  Creates a new, empty `List`, specifying its title and the type of the list.

Parameters:
  `title` - the screen's title (see `Displayable`)
  `listType` - one of `IMPLICIT`, `EXCLUSIVE`, or `MULTIPLE`
Throws:
  `IllegalArgumentException` - if `listType` is not one of `IMPLICIT`, `EXCLUSIVE`, or `MULTIPLE`
See Also:
  `Choice`

### List

    public List(String title,
                int listType,
                String[] stringElements,
                Image[] imageElements)

  Creates a new `List`, specifying its title, the type of the `List`, and an array of `Strings` and `Images` to be used as its initial contents.

  The `stringElements` array must be non-null and every array element must also be non-null. The length of the `stringElements` array determines the number of elements in the `List`. The `imageElements` array may be `null` to indicate that the `List` elements have no images. If the `imageElements` array is non-null, it must be the same length as the `stringElements` array. Individual elements of the `imageElements` array may be `null` in order to indicate the absence of an image for the corresponding `List` element. Non-null elements of the `imageElements` array may refer to mutable or immutable images.

Parameters:
  `title` - the screen's title (see `Displayable`)
  `listType` - one of `IMPLICIT`, `EXCLUSIVE`, or `MULTIPLE`
  `stringElements` - set of strings specifying the string parts of the `List` elements
  `imageElements` - set of images specifying the image parts of the `List` elements
Throws:
  `NullPointerException` - if `stringElements` is `null`
  `NullPointerException` - if the `stringElements` array contains any null elements
  `IllegalArgumentException` - if the `imageElements` array is non-null and has a different length from the `stringElements` array
  `IllegalArgumentException` - if `listType` is not one of `IMPLICIT`, `EXCLUSIVE`, or `MULTIPLE`
See Also:
  `Choice.EXCLUSIVE`, `Choice.MULTIPLE`, `Choice.IMPLICIT`

Method Detail

### setTicker

    public void setTicker(Ticker ticker)

  Sets a ticker for use with this `Displayable`, replacing any previous ticker. If `null`, removes the ticker object from this `Displayable`. The same ticker may be shared by several `Displayable` objects within an application. This is done by calling `setTicker()` with the same `Ticker` object on several different `Displayable` objects. If the `Displayable` is actually visible on the display, the implementation should update the display as soon as it is feasible to do so.

  The existence of a ticker may affect the size of the area available for `Displayable's` contents. If the application adds, removes, or sets the ticker text at runtime, this can dynamically change the size of the content area. This is most important to be aware of when using the `Canvas` class.

  Overrides:
    `setTicker` in class `Displayable`
  Parameters:
    `ticker` - the ticker object used on this screen
  Since:
    MIDP 2.0
  See Also:
    `Displayable.getTicker()`

### setTitle

    public void setTitle(String s)

  Sets the title of the `Displayable`. If `null` is given, removes the title.

  If the `Displayable` is actually visible on the display, the implementation should update the display as soon as it is feasible to do so.

  The existence of a title may affect the size of the area available for `Displayable` content. If the application adds, removes, or sets the title text at runtime, this can dynamically change the size of the content area. This is most important to be aware of when using the `Canvas` class.

  Overrides:
    `setTitle` in class `Displayable`
  Parameters:
    `s` - the new title, or `null` for no title
  Since:
    MIDP 2.0
  See Also:
    `Displayable.getTitle()`

### size

    public int size()

  Gets the number of elements in the `List`.

  Specified by:
    `size` in interface `Choice`
  Returns:
    the number of elements in the `List`

### getString

    public String getString(int elementNum)

  Gets the `String` part of the element referenced by `elementNum`.

  Specified by:
    `getString` in interface `Choice`
  Parameters:
    `elementNum` - the index of the element to be queried
  Returns:
    the string part of the element
  Throws:
    `IndexOutOfBoundsException` - if `elementNum` is invalid
  See Also:
    `getImage(int)`

### getImage

    public Image getImage(int elementNum)

  Gets the `Image` part of the element referenced by `elementNum`.

  Specified by:
    `getImage` in interface `Choice`
  Parameters:
    `elementNum` - the number of the element to be queried
  Returns:
    the image part of the element, or `null` if there is no image
  Throws:
    `IndexOutOfBoundsException` - if `elementNum` is invalid
  See Also:
    `getString(int)`

### append

    public int append(String stringPart,
                      Image imagePart)

  Appends an element to the `List`.

  Specified by:
    `append` in interface `Choice`
  Parameters:
    `stringPart` - the string part of the element to be added
    `imagePart` - the image part of the element to be added, or `null` if there is no image part
  Returns:
    the assigned index of the element
  Throws:
    `NullPointerException` - if `stringPart` is `null`

### insert

    public void insert(int elementNum,
                       String stringPart,
                       Image imagePart)

  Inserts an element into the `List` just prior to the element specified.

  Specified by:
    `insert` in interface `Choice`
  Parameters:
    `elementNum` - the index of the element where insertion is to occur
    `stringPart` - the string part of the element to be inserted
    `imagePart` - the image part of the element to be inserted, or `null` if there is no image part
  Throws:
    `IndexOutOfBoundsException` - if `elementNum` is invalid
    `NullPointerException` - if `stringPart` is `null`

### delete

    public void delete(int elementNum)

  Deletes the element referenced by `elementNum`.

  Specified by:
    `delete` in interface `Choice`
  Parameters:
    `elementNum` - the index of the element to be deleted
  Throws:
    `IndexOutOfBoundsException` - if `elementNum` is invalid

### deleteAll

    public void deleteAll()

  Deletes all elements from this List.

  Specified by:
    `deleteAll` in interface `Choice`

### set

    public void set(int elementNum,
                    String stringPart,
                    Image imagePart)

  Sets the `String` and `Image` parts of the element referenced by `elementNum`, replacing the previous contents of the element.

  Specified by:
    `set` in interface `Choice`
  Parameters:
    `elementNum` - the index of the element to be set
    `stringPart` - the string part of the new element
    `imagePart` - the image part of the element, or `null` if there is no image part
  Throws:
    `IndexOutOfBoundsException` - if `elementNum` is invalid
    `NullPointerException` - if `stringPart` is `null`

### isSelected

    public boolean isSelected(int elementNum)

  Gets a boolean value indicating whether this element is selected.

  Specified by:
    `isSelected` in interface `Choice`
  Parameters:
    `elementNum` - index to element to be queried
  Returns:
    selection state of the element
  Throws:
    `IndexOutOfBoundsException` - if `elementNum` is invalid

### getSelectedIndex

    public int getSelectedIndex()

  Returns the index number of an element in the `List` that is selected.

  Specified by:
    `getSelectedIndex` in interface `Choice`
  Returns:
    index of selected element, or `-1` if none
  See Also:
    `setSelectedIndex(int, boolean)`

### getSelectedFlags

    public int getSelectedFlags(boolean[] selectedArray_return)

  Queries the state of a `List` and returns the state of all elements in the boolean array `selectedArray_return`.

  Specified by:
    `getSelectedFlags` in interface `Choice`
  Parameters:
    `selectedArray_return` - array to contain the results
  Returns:
    the number of selected elements in the `Choice`
  Throws:
    `IllegalArgumentException` - if `selectedArray_return` is shorter than the size of the List
    `NullPointerException` - if `selectedArray_return` is `null`
  See Also:
    `setSelectedFlags(boolean[])`

### setSelectedIndex

    public void setSelectedIndex(int elementNum,
                                 boolean selected)

  Sets the selected state of an element.

  Specified by:
    `setSelectedIndex` in interface `Choice`
  Parameters:
    `elementNum` - the index of the element, starting from zero
    `selected` - the state of the element, where `true` means selected and `false` means not selected
  Throws:
    `IndexOutOfBoundsException` - if `elementNum` is invalid
  See Also:
    `getSelectedIndex()`

### setSelectedFlags

    public void setSelectedFlags(boolean[] selectedArray)

  Sets the selected state of all elements of the `List`.

  Specified by:
    `setSelectedFlags` in interface `Choice`
  Parameters:
    `selectedArray` - an array in which the method collect the selection status
  Throws:
    `IllegalArgumentException` - if `selectedArray` is shorter than the size of the `List`
    `NullPointerException` - if `selectedArray` is `null`
  See Also:
    `getSelectedFlags(boolean[])`

### removeCommand

    public void removeCommand(Command cmd)

  The same as `Displayable.removeCommand` but with the following additional semantics.

  If the command to be removed happens to be the select command, the `List` is set to have no select command, and the command is removed from the `List`.

  The following code:

           // Command c is the select command on List list
           list.removeCommand(c);

  is equivalent to the following code:

           // Command c is the select command on List list
           list.setSelectCommand(null);
           list.removeCommand(c);

  Overrides:
    `removeCommand` in class `Displayable`
  Parameters:
    `cmd` - the command to be removed
  Since:
    MIDP 2.0

### setSelectCommand

    public void setSelectCommand(Command command)

  Sets the `Command` to be used for an `IMPLICIT` `List` selection action. By default, an implicit selection of a List will result in the predefined `List.SELECT_COMMAND` being used. This behavior may be overridden by calling the `List.setSelectCommand()` method with an appropriate parameter value. If a `null` reference is passed, this indicates that no "select" action is appropriate for the contents of this `List`.

  If a reference to a command object is passed, and it is not the special command `List.SELECT_COMMAND`, and it is not currently present on this `List` object, the command object is added to this `List` as if `addCommand(command)` had been called prior to the command being made the select command. This indicates that this command is to be invoked when the user performs the "select" on an element of this `List`.

  The select command should have a command type of `ITEM` to indicate that it operates on the currently selected object. It is not an error if the command is of some other type. (`List.SELECT_COMMAND` has a type of `SCREEN` for historical purposes.) For purposes of presentation and placement within its user interface, the implementation is allowed to treat the select command as if it were of type `ITEM`.

  If the select command is later removed from the `List` with `removeCommand()`, the `List` is set to have no select command as if `List.setSelectCommand(null)` had been called.

  The default behavior can be reestablished explicitly by calling `setSelectCommand()` with an argument of `List.SELECT_COMMAND`.

  This method has no effect if the type of the `List` is not `IMPLICIT`.

  Parameters:
    `command` - the command to be used for an `IMPLICIT` list selection action, or `null` if there is none
  Since:
    MIDP 2.0

### setFitPolicy

    public void setFitPolicy(int fitPolicy)

  Sets the application's preferred policy for fitting `Choice` element contents to the available screen space. The set policy applies for all elements of the `Choice` object. Valid values are `Choice.TEXT_WRAP_DEFAULT`, `Choice.TEXT_WRAP_ON`, and `Choice.TEXT_WRAP_OFF`. Fit policy is a hint, and the implementation may disregard the application's preferred policy.

  Specified by:
    `setFitPolicy` in interface `Choice`
  Parameters:
    `fitPolicy` - preferred content fit policy for choice elements
  Throws:
    `IllegalArgumentException` - if `fitPolicy` is invalid
  Since:
    MIDP 2.0
  See Also:
    `getFitPolicy()`

### getFitPolicy

    public int getFitPolicy()

  Gets the application's preferred policy for fitting `Choice` element contents to the available screen space. The value returned is the policy that had been set by the application, even if that value had been disregarded by the implementation.

  Specified by:
    `getFitPolicy` in interface `Choice`
  Returns:
    one of `Choice.TEXT_WRAP_DEFAULT`, `Choice.TEXT_WRAP_ON`, or `Choice.TEXT_WRAP_OFF`
  Since:
    MIDP 2.0
  See Also:
    `setFitPolicy(int)`

### setFont

    public void setFont(int elementNum,
                        Font font)

  Sets the application's preferred font for rendering the specified element of this `Choice`. An element's font is a hint, and the implementation may disregard the application's preferred font.

  The `elementNum` parameter must be within the range `[0..size()-1]`, inclusive.

  The `font` parameter must be a valid `Font` object or `null`. If the `font` parameter is `null`, the implementation must use its default font to render the element.

  Specified by:
    `setFont` in interface `Choice`
  Parameters:
    `elementNum` - the index of the element, starting from zero
    `font` - the preferred font to use to render the element
  Throws:
    `IndexOutOfBoundsException` - if `elementNum` is invalid
  Since:
    MIDP 2.0
  See Also:
    `getFont(int)`

### getFont

    public Font getFont(int elementNum)

  Gets the application's preferred font for rendering the specified element of this `Choice`. The value returned is the font that had been set by the application, even if that value had been disregarded by the implementation. If no font had been set by the application, or if the application explicitly set the font to `null`, the value is the default font chosen by the implementation.

  The `elementNum` parameter must be within the range `[0..size()-1]`, inclusive.

  Specified by:
    `getFont` in interface `Choice`
  Parameters:
    `elementNum` - the index of the element, starting from zero
  Returns:
    the preferred font to use to render the element
  Throws:
    `IndexOutOfBoundsException` - if `elementNum` is invalid
  Since:
    MIDP 2.0
  See Also:
    `setFont(int elementNum, Font font)`

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

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