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

The List class is a Screen containing list of choices. Most of the behavior is common with class ChoiceGroup and the common API is defined in interface Choice. When a List is present on the display the user can interact with it indefinitely (for instance, traversing from element to element and possibly scrolling). These traversing and scrolling operations do not cause application-visible events. The system notifies the application when some Command is fired. The notification of the application is done with commandAction .

List, like any Choice, utilizes a dedicated "select" or "go" functionality of the devices. Typically, the select functionality is distinct from the soft-buttons, but some devices may use soft-buttons for the select. In any case, it is assumed that the select key does not have application-programmable label.

In respect to select functionality here are three types of Lists:

• IMPLICIT where select causes immediate notification of the application if there is an CommandListener registered. An implicit SELECT_COMMAND is a parameter for the notification.
• EXCLUSIVE where select operation changes the selected element in the list. Application is not notified.
• MULTIPLE where select operation toggles the selected state of the focused. Application is not notified.

IMPLICIT List can be used to construct menus by placing logical commands to elements. In this case no application defined Commands have to be attached. Application just has to register a CommandListener that is called when user "selects".

Another use might be a Screen with a default command. For example, the List may contain email headers, and the following Commands:

• (SCREEN, "read");
• (SCREEN, "reply");
• (SCREEN, "delete");

If the list of type IMPLICIT, the select operation also calls the method commandAction with parameter SELECT_COMMAND. The implementation of commandAction() can now do the obvious thing and start the read operation.

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 application can also set the currently selected element(s) prior to displaying the List.

The implementation may have keyboard shortcuts for focusing and selecting the choice elements, but the use of these shortcuts is not visible to the application program.

Note: Many of the essential methods have been documented in interface Choice.

Field Summary

static Command

SELECT_COMMAND SELECT_COMMAND is a special command that commandAction can use to recognize the user did the select operation on a IMPLICIT List.

Fields inherited from interface javax.microedition.lcdui.Choice

EXCLUSIVE, IMPLICIT, MULTIPLE

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 stringElement, Image imageElement) Implementation of appendElement of interface Choice.
void	delete(int index) Implementation of deleteElement of interface Choice.
Image	getImage(int index) Implementation of getImage of interface Choice.
int	getSelectedFlags(boolean[] selectedArray_return) Implementation of getSelectedFlags of interface Choice.
int	getSelectedIndex() Implementation of getSelectedIndex of interface Choice.
String	getString(int index) Implementation of getString of interface Choice.
void	insert(int index, String stringElement, Image imageElement) Implementation of insertElement of interface Choice.
boolean	isSelected(int index) Implementation of isSelected of interface Choice.
void	set(int index, String stringElement, Image imageElement) Implementation of setElement of interface Choice.
void	setSelectedFlags(boolean[] selectedArray) Implementation of setSelectedFlags of interface Choice.
void	setSelectedIndex(int index, boolean selected) Implementation of getSelectedIndex of interface Choice.
int	size() Implementation of getSize of interface Choice.

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

Field Detail

SELECT_COMMAND

public static final Command SELECT_COMMAND

SELECT_COMMAND is a special command that commandAction can use to recognize the user did the select operation on a IMPLICIT List. The field values of SELECT_COMMAND are:
- label = null
- type = SCREEN
- priority = 0
The application should not use these values for recognizing the SELECT_COMMAND. Instead, object identities of the Command and Displayable (List) should be used.

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 Screen)

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.

Parameters:

title - the screen's title (see Screen)

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.

IllegalArgumentException - if any image in the imageElements array is mutable

See Also:

Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT

Method Detail

size

public int size()

Implementation of getSize of interface Choice.

Specified by:

size in interface Choice

Returns:

number of elements in the Choice.

getString

public String getString(int index)

Implementation of getString of interface Choice.

Specified by:

getString in interface Choice

Parameters:

index - The index of the selected item

Returns:

the string part of the element

See Also:

getImage(int)

getImage

public Image getImage(int index)

Implementation of getImage of interface Choice.

Specified by:

getImage in interface Choice

Parameters:

index - the index of the selected item

Returns:

the image part of the element, or null if there is no image

See Also:

getString(int)

append

public int append(String stringElement,
                  Image imageElement)

Implementation of appendElement of interface Choice.

Specified by:

append in interface Choice

Parameters:

stringElement - String to be appended

imageElement - Image to be appended

Returns:

the assigned number of the element

insert

public void insert(int index,
                   String stringElement,
                   Image imageElement)

Implementation of insertElement of interface Choice.

Specified by:

insert in interface Choice

Parameters:

index - Index of the item to be inserted

stringElement - String of the item to be inserted

imageElement - Image of the item to be inserted

delete

public void delete(int index)

Implementation of deleteElement of interface Choice.

Specified by:

delete in interface Choice

Parameters:

index - Index of the element to be deleted

set

public void set(int index,
                String stringElement,
                Image imageElement)

Implementation of setElement of interface Choice.

Specified by:

set in interface Choice

Parameters:

index - Index of element to be set.

stringElement - String entry of element to be set.

imageElement - Image entry of element to be set.

isSelected

public boolean isSelected(int index)

Implementation of isSelected of interface Choice.

Specified by:

isSelected in interface Choice

Parameters:

index - Index of element to be selected.

Returns:

selection status of an element

getSelectedIndex

public int getSelectedIndex()

Implementation of getSelectedIndex of interface Choice.

Specified by:

getSelectedIndex in interface Choice

Returns:

index of selected element

getSelectedFlags

public int getSelectedFlags(boolean[] selectedArray_return)

Implementation of getSelectedFlags of interface Choice.

Specified by:

getSelectedFlags in interface Choice

Parameters:

selectedArray_return - array to contain the results. It must be at least as long as the size of the List as returned by getSize(). If the array is longer, the extra elements are set to false.

Returns:

the number of selected elements in the Choice

setSelectedIndex

public void setSelectedIndex(int index,
                             boolean selected)

Implementation of getSelectedIndex of interface Choice.

Specified by:

setSelectedIndex in interface Choice

Parameters:

selected - the new state of the element true=selected, false=not selected.

index - Index of element.

setSelectedFlags

public void setSelectedFlags(boolean[] selectedArray)

Implementation of setSelectedFlags of interface Choice.

Specified by:

setSelectedFlags in interface Choice

Parameters:

selectedArray - an array in which the method collect the selection status