Java Doc for List.java in  » 6.0-JDK-Modules » j2me » javax » microedition » lcdui » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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

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.

The stringElements array must be non-null and every array element must also be non-null.

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

The font parameter must be a valid Font object or null.

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.

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.

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

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

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.

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.