MID Profile

javax.microedition.lcdui
Class List

java.lang.Object
  |
  +--javax.microedition.lcdui.Displayable
        |
        +--javax.microedition.lcdui.Screen
              |
              +--javax.microedition.lcdui.List

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 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:

If the list of type IMPLICIT, the select operation also calls the method commandAction with parameter selectCommand. 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 selectCommand
          selectCommand 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 appendElement(String stringPart, Image imagePart)
          Implementation of appendElement of interface Choice.
 void deleteElement(int elementNum)
          Implementation of deleteElement of interface Choice.
 Image getImage(int elementNum)
          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.
 int getSize()
          Implementation of getSize of interface Choice.
 String getString(int elementNum)
          Implementation of getString of interface Choice.
 void insertElement(int elementNum, String stringPart, Image imagePart)
          Implementation of insertElement of interface Choice.
 boolean isSelected(int elementNum)
          Implementation of isSelected of interface Choice.
 void setElement(int elementNum, String stringPart, Image imagePart)
          Implementation of setElement of interface Choice.
 void setSelectedFlags(boolean[] selectedArray)
          Implementation of setSelectedFlags of interface Choice.
 void setSelectedIndex(int elementNum, boolean selected)
          Implementation of getSelectedIndex 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, setListener
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

selectCommand

public static final Command selectCommand
selectCommand is a special command that commandAction can use to recognize the user did the select operation on a IMPLICIT List.
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 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.
Parameters:
title - the screen title {@see Screen}
listType - one of IMPLICIT, EXCLUSIVE, or MULTIPLE
stringElements - set of strings specifying the visible representation of the elements.
imageElements - set of images specifying the visible representation of the elements. Empty image is marked with null, and if no images are given, the parameter imageElements may be null..
Throws:
IllegalArgumentException - if the length of stringElements is different from imageElements and imageElements is non-null.
IllegalArgumentException - if listType is not one of IMPLICIT, EXCLUSIVE, or MULTIPLE.
See Also:
Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT
Method Detail

getSize

public int getSize()
Implementation of getSize of interface Choice.
Specified by:
getSize in interface Choice
Returns:
number of elements in the Choice.

getString

public String getString(int elementNum)
Implementation of getString of interface Choice.
Specified by:
getString in interface Choice
Parameters:
elementNum - the number of the element
Returns:
the string part of the element
Throws:
ArrayIndexOutOfBoundsException - if elementNum is invalid
See Also:
getImage(int)

getImage

public Image getImage(int elementNum)
Implementation of getImage of interface Choice.
Specified by:
getImage in interface Choice
Parameters:
elementNum - the number of the element
Returns:
the image part of the element, or null if there is no image
Throws:
ArrayIndexOutOfBoundsException - if elementNum is invalid
See Also:
getString(int), getString(int)

appendElement

public int appendElement(String stringPart,
                         Image imagePart)
Implementation of appendElement of interface Choice.
Specified by:
appendElement 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 number of the element
Throws:
IllegalArgumentException - if the image is mutable

insertElement

public void insertElement(int elementNum,
                          String stringPart,
                          Image imagePart)
Implementation of insertElement of interface Choice.
Specified by:
insertElement in interface Choice
Parameters:
elementNum - the number of the element
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:
ArrayIndexOutOfBoundsException - if elementNum is invalid
IllegalArgumentException - if the image is mutable
NullPointerException - if stringPart is null

deleteElement

public void deleteElement(int elementNum)
Implementation of deleteElement of interface Choice.
Specified by:
deleteElement in interface Choice
Parameters:
elementNum - the number of the element to be deleted
Throws:
ArrayIndexOutOfBoundsException - if elementNum is invalid

setElement

public void setElement(int elementNum,
                       String stringPart,
                       Image imagePart)
Implementation of setElement of interface Choice.
Specified by:
setElement in interface Choice
Parameters:
elementNum - the number of the element
stringPart - the string part of the new element
imagePart - the image part of the element, or null if there is no image part
Throws:
ArrayIndexOutOfBoundsException - if elementNum is invalid
IllegalArgumentException - if the image is mutable
NullPointerException - if stringPart is null

isSelected

public boolean isSelected(int elementNum)
Implementation of isSelected of interface Choice.
Specified by:
isSelected in interface Choice
Parameters:
elementNum - index to element of interest
Returns:
selection status of an element
Throws:
ArrayIndexOutOfBoundsException - if elementNum specifies an invalid 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
Throws:
IllegalArgumentException - if selectedArray_return is shorter than the size of the List.

setSelectedIndex

public void setSelectedIndex(int elementNum,
                             boolean selected)
Implementation of getSelectedIndex of interface Choice.
Specified by:
setSelectedIndex in interface Choice
Parameters:
elementNum - the number of the element. Indexing of the elements is zero-based.
selected - the new state of the element true=selected, false=not selected.
Throws:
ArrayIndexOutOfBoundException - if elementNum<0 or elementNum > getSize().

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
Throws:
IllegalArgumentException - if selectedArray is shorter than the size of the List.

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.