FileDocCategorySizeDatePackage
List.javaAPI DocJ2ME MIDP 2.031693Thu Nov 07 12:02:28 GMT 2002javax.microedition.lcdui

List

public class List extends Screen implements Choice
A Screen containing list of choices. Most of its behavior is common with class {@link ChoiceGroup ChoiceGroup}, and their common API. The different List types in particular, are defined in interface {@link Choice 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 {@link Command Command} is invoked by notifying its {@link 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 {@link Choice#EXCLUSIVE}, {@link Choice#MULTIPLE}, and {@link Choice#IMPLICIT}. The Choice type {@link 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 {@link CommandListener 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 {@link #setSelectCommand(Command command) 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

Fields Summary
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 {@link #setSelectCommand(Command command) 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.

private Form
form
An internal Form to render this List (basically, a List is just a Form with a choiceGroup in it
private ChoiceGroup
cg
An internal choicegroup to handle the selections
private Command
selectCommand
This is an internal Command which represents the callback to a selection event of an IMPLICIT list. By default, this command is the predefined List.SELECT_COMMAND. This can be overridden however using the setSelectCommand().
Constructors Summary
public List(String title, int listType)
Creates a new, empty List, specifying its title and the type of the list.

param
title the screen's title (see {@link Displayable Displayable})
param
listType one of IMPLICIT, EXCLUSIVE, or MULTIPLE
throws
IllegalArgumentException if listType is not one of IMPLICIT, EXCLUSIVE, or MULTIPLE
see
Choice


    // constructors //

                                                       
         
        this(title, listType, new String[] {}, new Image[] {});
    
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.

param
title the screen's title (see {@link Displayable Displayable})
param
listType one of IMPLICIT, EXCLUSIVE, or MULTIPLE
param
stringElements set of strings specifying the string parts of the List elements
param
imageElements set of images specifying the image parts of the List elements
throws
NullPointerException if stringElements is null
throws
NullPointerException if the stringElements array contains any null elements
throws
IllegalArgumentException if the imageElements array is non-null and has a different length from the stringElements array
throws
IllegalArgumentException if listType is not one of IMPLICIT, EXCLUSIVE, or MULTIPLE
see
Choice#EXCLUSIVE
see
Choice#MULTIPLE
see
Choice#IMPLICIT


        super(title);

        if (!(listType == IMPLICIT   ||
              listType == EXCLUSIVE  ||
              listType == MULTIPLE)) {
            throw new IllegalArgumentException();
        }

        synchronized (Display.LCDUILock) {

            cg = new ChoiceGroup(null, listType,
                                 stringElements, imageElements, true);
            cg.isList = true;

            form = new Form(title);
            form.paintDelegate = this;
            form.append(cg);
        }
    
Methods Summary
public intappend(java.lang.String stringPart, Image imagePart)
Appends an element to the List.

param
stringPart the string part of the element to be added
param
imagePart the image part of the element to be added, or null if there is no image part
return
the assigned index of the element
throws
NullPointerException if stringPart is null

        return cg.append(stringPart, imagePart);
    
voidcallHideNotify(Display d)
Notify this Displayable it is being hidden on the given Display

param
d the Display hiding this Displayable

        super.callHideNotify(d);
        form.callHideNotify(d);
    
voidcallInvalidate(Item src)
Called by the event thread to invalidate the contents of this List

param
src the Item which may have caused the invalidation

        form.callInvalidate(src);
    
voidcallItemStateChanged(Item src)
Called by the event thread to notify an ItemStateChangeListener that an item has changed

param
src the Item which has changed

        form.callItemStateChanged(src);
    
voidcallKeyPressed(int keyCode)
Handle a key pressed event

param
keyCode The key that was pressed


        form.callKeyPressed(keyCode);

        if (keyCode == Display.KEYCODE_SELECT) {

	    // don't invoke the select command if there are
	    // no elements in the List
	    if (cg.size() == 0) {
		return;
	    }

            CommandListener cl = null;
            synchronized (Display.LCDUILock) {
                cl = listener;
            }

            if (cl != null) {
                try {
                    // SYNC NOTE: We lock on calloutLock around any calls
                    // into application code
                    synchronized (Display.calloutLock) {
                        cl.commandAction(selectCommand, this);
                    }
                } catch (Throwable thr) {
                    Display.handleThrowable(thr);
                }
            }
        }
    
voidcallPaint(Graphics g, java.lang.Object target)
Display calls this method on it's current Displayable. SYNC NOTE: The caller of this method handles synchronization.

param
g the graphics context to paint into.
param
target the target Object of this repaint

        form.callPaint(g, target);
    
voidcallShowNotify(Display d)
Notify this Displayable it is being shown on the given Display

param
d the Display showing this Displayable

        super.callShowNotify(d);
        form.callShowNotify(d);
    
public voiddelete(int elementNum)
Deletes the element referenced by elementNum.

param
elementNum the index of the element to be deleted
throws
IndexOutOfBoundsException if elementNum is invalid

        cg.delete(elementNum);
    
public voiddeleteAll()
Deletes all elements from this List.

        cg.deleteAll();
    
public intgetFitPolicy()
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.

return
one of {@link #TEXT_WRAP_DEFAULT}, {@link #TEXT_WRAP_ON}, or {@link #TEXT_WRAP_OFF}
see
#setFitPolicy
since
MIDP 2.0

        return cg.getFitPolicy();
    
public FontgetFont(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.

param
elementNum the index of the element, starting from zero
return
the preferred font to use to render the element
throws
IndexOutOfBoundsException if elementNum is invalid
see
#setFont(int elementNum, Font font)
since
MIDP 2.0

        return cg.getFont(elementNum);
    
public ImagegetImage(int elementNum)
Gets the Image part of the element referenced by elementNum.

param
elementNum the number of the element to be queried
return
the image part of the element, or null if there is no image
throws
IndexOutOfBoundsException if elementNum is invalid
see
#getString(int)

        return cg.getImage(elementNum);
    
public intgetSelectedFlags(boolean[] selectedArray_return)
Queries the state of a List and returns the state of all elements in the boolean array selectedArray_return.

param
selectedArray_return array to contain the results
return
the number of selected elements in the Choice
throws
IllegalArgumentException if selectedArray_return is shorter than the size of the List
throws
NullPointerException if selectedArray_return is null
see
#setSelectedFlags

        return cg.getSelectedFlags(selectedArray_return);
    
public intgetSelectedIndex()
Returns the index number of an element in the List that is selected.

return
index of selected element, or -1 if none
see
#setSelectedIndex

        return cg.getSelectedIndex();
    
public java.lang.StringgetString(int elementNum)
Gets the String part of the element referenced by elementNum.

param
elementNum the index of the element to be queried
return
the string part of the element
throws
IndexOutOfBoundsException if elementNum is invalid
see
#getImage(int)

        return cg.getString(elementNum);
    
public voidinsert(int elementNum, java.lang.String stringPart, Image imagePart)
Inserts an element into the List just prior to the element specified.

param
elementNum the index of the element where insertion is to occur
param
stringPart the string part of the element to be inserted
param
imagePart the image part of the element to be inserted, or null if there is no image part
throws
IndexOutOfBoundsException if elementNum is invalid
throws
NullPointerException if stringPart is null

        cg.insert(elementNum, stringPart, imagePart);
    
public booleanisSelected(int elementNum)
Gets a boolean value indicating whether this element is selected.

param
elementNum index to element to be queried
return
selection state of the element
throws
IndexOutOfBoundsException if elementNum is invalid

        return cg.isSelected(elementNum);
    
public voidremoveCommand(Command cmd)
The same as {@link Displayable#removeCommand 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); 

param
cmd the command to be removed
since
MIDP 2.0

        synchronized (Display.LCDUILock) {
            super.removeCommandImpl(cmd);
            if (cmd == selectCommand) {
                selectCommand = null;
            }
        } // synchronized
    
public voidset(int elementNum, java.lang.String stringPart, Image imagePart)
Sets the String and Image parts of the element referenced by elementNum, replacing the previous contents of the element.

param
elementNum the index of the element to be set
param
stringPart the string part of the new element
param
imagePart the image part of the element, or null if there is no image part
throws
IndexOutOfBoundsException if elementNum is invalid
throws
NullPointerException if stringPart is null

        cg.set(elementNum, stringPart, imagePart);
    
public voidsetFitPolicy(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 {@link #TEXT_WRAP_DEFAULT}, {@link #TEXT_WRAP_ON}, and {@link #TEXT_WRAP_OFF}. Fit policy is a hint, and the implementation may disregard the application's preferred policy.

param
fitPolicy preferred content fit policy for choice elements
throws
IllegalArgumentException if fitPolicy is invalid
see
#getFitPolicy
since
MIDP 2.0

        cg.setFitPolicy(fitPolicy);
    
public voidsetFont(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.

param
elementNum the index of the element, starting from zero
param
font the preferred font to use to render the element
throws
IndexOutOfBoundsException if elementNum is invalid
see
#getFont
since
MIDP 2.0

	    cg.setFont(elementNum, font);
    
public voidsetSelectCommand(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.

param
command the command to be used for an IMPLICIT list selection action, or null if there is none
since
MIDP 2.0

        // If we're not an IMPLICIT List, ignore this method
        // call entirely
        if (cg.getType() != Choice.IMPLICIT) {
            return;
        }

        // Here we're just resetting the default behavior
        // of this implicit List
        if (command == List.SELECT_COMMAND) {
            selectCommand = command;
            return;
        }

        // Here we're deciding there is no appropriate default
        // command for a selection
        if (command == null) {
            selectCommand = null;
            return;
        }

        // SYNC NOTE: We grab the lock here because we need to determine
        // if the command is in the Displayables command set AND we need
        // to protect ourselves from the Command being removed from the
        // set just after we've done the check. #See how we override the
        // removeCommand() method in this class
        synchronized (Display.LCDUILock) {
            // We ensure that the provided Command has been added
            // to this List.
	    addCommandImpl(command);

            selectCommand = command;
        }

    
public voidsetSelectedFlags(boolean[] selectedArray)
Sets the selected state of all elements of the List.

param
selectedArray an array in which the method collect the selection status
throws
IllegalArgumentException if selectedArray is shorter than the size of the List
throws
NullPointerException if selectedArray is null
see
#getSelectedFlags

        cg.setSelectedFlags(selectedArray);
    
public voidsetSelectedIndex(int elementNum, boolean selected)
Sets the selected state of an element.

param
elementNum the index of the element, starting from zero
param
selected the state of the element, where true means selected and false means not selected
throws
IndexOutOfBoundsException if elementNum is invalid
see
#getSelectedIndex

        cg.setSelectedIndex(elementNum, selected);
    
public voidsetTicker(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.

param
ticker the ticker object used on this screen
since
MIDP 2.0
see
#getTicker

        super.setTicker(ticker);

        // We override this method from Displayable to set the ticker
        // on our internal Form which is doing all our rendering

        form.setTicker(ticker);
    
public voidsetTitle(java.lang.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.

param
s the new title, or null for no title
since
MIDP 2.0
see
#getTitle

        super.setTitle(s);

        // We override this method from Displayable to set the title
        // on our internal Form which is doing all our rendering

        form.setTitle(s);
    
public intsize()
Gets the number of elements in the List.

return
the number of elements in the List

        return cg.size();