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, the application does not have a mean to set a label for a select key.

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 implementation of a Screen with a default operation that takes place when "select" is pressed. For example, the List may contain email headers, and three operations: read, reply, and delete. Read is consider to be the default operation.


 void initialize() {
     myScreen = new List("EMAIL", List.IMPLICIT);
     readCommand = new Command("read", Command.SCREEN, 1);
     replyCommand = new Command("reply", Command.SCREEN, 1);
     deleteCommand = new Command("delete", Command.SCREEN, 1);
     myScreen.addCommand(readCommand);
     myScreen.addCommand(replyCommand);
     myScreen.addCommand(deleteCommand);
     myScreen.setCommandListener(this);
 }
 

Because the list is 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:


 public void commandAction (Command c, Displayable d) {
     if (d == myScreen) {
         if (c == readCommand || c == List.SELECT_COMMAND) {
             // show the mail to the user
         }
         // ...
     }
 }
 

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.

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, 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 Choice.
 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 Choice and returns the state of all elements in the boolean array selectedArray_return.
 int getSelectedIndex()
          Returns the index number of an element in the Choice 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 Choice 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 element referenced by elementNum to the specified element, 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)
          Attempts to set the selected state of every element in the Choice.
 void setSelectedIndex(int elementNum, boolean selected)
          For MULTIPLE, this simply sets an individual element's selected state.
 int size()
          Gets the number of elements present.
 
Methods inherited from class javax.microedition.lcdui.Screen
getTicker, getTitle, setTicker, setTitle
 
Methods inherited from class javax.microedition.lcdui.Displayable
addCommand, getHeight, 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
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 = "" (an empty string)
- 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. Any elements present in the imageElements array must refer to immutable images.

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()
Description copied from interface: Choice

Gets the number of elements present.

Returns:
the number of elements in the List

getString

public String getString(int elementNum)
Description copied from interface: Choice

Gets the String part of the element referenced by elementNum. The elementNum parameter must be within the range [0..size()-1], inclusive.

Parameters:
elementNum - the index of the element to be queried
Returns:
the string part of the element
Throws:
IndexOutOfBoundsException - if elementNum is invalid
Since:
JDE 4.0.2
See Also:
getImage(int)

getImage

public Image getImage(int elementNum)
Description copied from interface: Choice

Gets the Image part of the element referenced by elementNum. The elementNum parameter must be within the range [0..size()-1], inclusive.

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
Since:
JDE 4.0.2
See Also:
getString(int), getString(int)

append

public int append(String stringPart,
                  Image imagePart)
Description copied from interface: Choice

Appends an element to the Choice. The added element will be the last element of the Choice. The size of the Choice grows by one.

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:
IllegalArgumentException - if the image is mutable
NullPointerException - if stringPart is null
Since:
JDE 4.0.2

insert

public void insert(int elementNum,
                   String stringPart,
                   Image imagePart)
Description copied from interface: Choice

Inserts an element into the Choice just prior to the element specified. The size of the Choice grows by one. The elementNum parameter must be within the range [0..size()], inclusive. The index of the last element is size()-1, and so there is actually no element whose index is size(). If this value is used for elementNum, the new element is inserted immediately after the last element. In this case, the effect is identical to append().

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
IllegalArgumentException - if the image is mutable
NullPointerException - if stringPart is null
Since:
JDE 4.0.2

delete

public void delete(int elementNum)
Description copied from interface: Choice

Deletes the element referenced by elementNum. The size of the Choice shrinks by one. It is legal to delete all elements from a Choice. The elementNum parameter must be within the range [0..size()-1], inclusive.

Parameters:
elementNum - the index of the element to be deleted
Throws:
IndexOutOfBoundsException - if elementNum is invalid
Since:
JDE 4.0.2

deleteAll

public void deleteAll()
Deletes all elements from this List.
Since:
JDE 4.0.0

set

public void set(int elementNum,
                String stringPart,
                Image imagePart)
Description copied from interface: Choice

Sets the element referenced by elementNum to the specified element, replacing the previous contents of the element. The elementNum parameter must be within the range [0..size()-1], inclusive.

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
IllegalArgumentException - if the image is mutable
NullPointerException - if stringPart is null
Since:
JDE 4.0.2

isSelected

public boolean isSelected(int elementNum)
Description copied from interface: Choice

Gets a boolean value indicating whether this element is selected. The elementNum parameter must be within the range [0..size()-1], inclusive.

Parameters:
elementNum - index to element to be queried
Returns:
selection state of the element
Throws:
IndexOutOfBoundsException - if elementNum is invalid
Since:
JDE 4.0.2

getSelectedIndex

public int getSelectedIndex()
Description copied from interface: Choice

Returns the index number of an element in the Choice that is selected. For Choice types EXCLUSIVE and IMPLICIT there is at most one element selected, so this method is useful for determining the user's choice. Returns -1 if the Choice has no elements (and therefore has no selected elements).

For MULTIPLE, this always returns -1 because no single value can in general represent the state of such a Choice. To get the complete state of a MULTIPLE Choice, see getSelectedFlags.

Returns:
index of selected element, or -1 if none

getSelectedFlags

public int getSelectedFlags(boolean[] selectedArray_return)
Description copied from interface: Choice

Queries the state of a Choice and returns the state of all elements in the boolean array selectedArray_return. NOTE: this is a result parameter. It must be at least as long as the size of the Choice as returned by size(). If the array is longer, the extra elements are set to false.

This call is valid for all types of Choices. For MULTIPLE, any number of elements may be selected and set to true in the result array. For EXCLUSIVE and IMPLICIT exactly one element will be selected (unless there are zero elements in the 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
Since:
JDE 4.0.2

setSelectedIndex

public void setSelectedIndex(int elementNum,
                             boolean selected)
Description copied from interface: Choice

For MULTIPLE, this simply sets an individual element's selected state.

For EXCLUSIVE, this can be used only to select any element, that is, the selected parameter must be true . When an element is selected, the previously selected element is deselected. If selected is false , this call is ignored. If element was already selected, the call has no effect.

For IMPLICIT, this can be used only to select any element, that is, the selected parameter must be true . When an element is selected, the previously selected element is deselected. If selected is false , this call is ignored. If element was already selected, the call has no effect.

The call to setSelectedIndex does not cause implicit activation of any Command.

For all list types, the elementNum parameter must be within the range [0..size()-1], inclusive.

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
Since:
JDE 4.0.2

setSelectedFlags

public void setSelectedFlags(boolean[] selectedArray)
Description copied from interface: Choice

Attempts to set the selected state of every element in the Choice. The array must be at least as long as the size of the Choice. If the array is longer, the additional values are ignored.

For Choice objects of type MULTIPLE, this sets the selected state of every element in the Choice. An arbitrary number of elements may be selected.

For Choice objects of type EXCLUSIVE and IMPLICIT, exactly one array element must have the value true. If no element is true, the first element in the Choice will be selected. If two or more elements are true, the implementation will choose the first true element and select it.

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
Since:
JDE 4.0.2

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

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.

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)


Copyright 1999-2004 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.