List

When a List is being displayed, the user can interact with it, for instance, by traversing from element to element. The traversal may cause the List to be scrolled. These traversing and scrolling operations are handled by the system and do not generate any events that are visible to the MIDP application. The system notifies the application only when a Command is fired. The notification to the application is carried out via the CommandListener of the Screen. This means that the application operations associated with list elements are added to the List as ITEM or SCREEN type commands, depending upon whether the operation affects only the selected element or the entire list.

Here is an example of List creation:

List list = new List("Fruits",
                     Choice.IMPLICIT);
list.append("Apple", null);
list.append("Pear", null);
list.append("Orange", null);
list.append("Banana", null);
list.append("Pineapple", null);
list.append("Mandarin", null);
list.setCommandListener(this);
list.addCommand(backCommand);

The implicit List automatically selects the currently focused element when any Command is initiated. To be notified of the selection, the List must have a CommandListener set. The application can query the selection state of a List from CommandListener using the methods getSelectedIndex or isSelected.

The implicit List also has the concept of a select command. A select command is a command that the user can activate with the select operation of the device. This user action delivers the select command to the CommandListener of the List. An application can set a select command with the method setSelectCommand. Initially, when a List is constructed, the select command is set to be the built-in List.SELECT_COMMAND. As a general rule, applications should provide their own select command to replace the built-in SELECT_COMMAND. This allows applications to provide a meaningful label instead of relying on the one provided by the system for SELECT_COMMAND.

If there is more than one ITEM command on a List, the select command can be considered as a default operation for the List. The following code sample illustrates how this can be accomplished. The code creates a list that presents the message headers of an e-mail messaging application. Two of the commands, openCommand and removeCommand, are related to the List elements, so they have type ITEM. The openCommand is considered to be a default operation, invoked when a select operation in the List is activated by the user.

The following code initializes the List:

// Construct a list of message headers
List list = new List("Messages", Choice.IMPLICIT,
                     messageHeaders, messageStateIcons);

// The command handler is implemented in the same class
list.setCommandListener(this);

// Command for "opening" the selected message
Command openCommand = new Command("Open", Command.ITEM, 1);

// Command for "removing" the selected message
Command removeCommand = new Command("Remove", Command.ITEM, 2);

// Command for going "back"
Command backCommand = new Command("Back", Command.BACK, 3);

list.addCommand(openCommand);
list.addCommand(removeCommand);
list.addCommand(backCommand);
list.setSelectCommand(openCommand); // openCommand is the default

The following code defines the command handler of the List:

public void commandAction(Command cmd, Displayable d) {
    int selectedIndex = ((List) d).getSelectedIndex();
    if (cmd == openCommand) {
        // Handle "open" command based on selectedIndex
    } else if (cmd == removeCommand) {
        // Handle "remove" command based on selectedIndex
    } else if (cmd == backCommand) {
        // Handle backward navigation
    }
}

An Exclusive List allows the user to select only a single element. This type of a List is commonly rendered to the screen as a group of radio buttons. When the user selects an element, any previously selected element is automatically deselected. Selecting an element does not notify the application. Notification to the List's CommandListener occurs when a Command on the List is chosen. When the listener is invoked, it can determine which element is selected with the List.getSelected method. An exclusive List must have Commands added to it, or the user will not be able to trigger any action and will be stuck on the screen. In the example below, the user is able to pick one element and then can select either the OK or BACK command.

List list =
  new List("Border Style", Choice.EXCLUSIVE);
list.append("None", null);
list.append("Plain", null);
list.append("Fancy", null);
list.addCommand(backCommand);
list.addCommand(okCommand);
...

public void commandAction(Command cmd, Displayable d) {
    List list = (List) d;
    if (cmd == okCommand) {
        int i = list.getSelectedIndex();
        // Use the index of the selected list element...
    } else if (cmd == backCommand) {
        // Handle the back command
    }
}

A Multiple Choice List allows the user to select zero or more elements. Each element can be selected or deselected individually. Typically, this kind of List is presented on the screen as a set of check boxes. Each element has an indicator displaying whether or not the element it is currently selected, and the user can toggle individual elements on or off. Toggling the selection of an element does not notify the application. Notification to the List's CommandListener occurs when a Command on the List is chosen. When the listener is invoked, it can determine which element(s) are selected with the List.getSelectedFlags or List.isSelected method. A multiple choice List must have Commands added to it, or the user will not be able to trigger any action and will be stuck on the screen.

In this example, the user can individually select and deselect the choices "Red", "Green", and "Blue." When satisfied with the choices, the user can select either the OK or BACK command to exit the screen.

List list = new List("Colors to mix",
                     Choice.MULTIPLE);
list.append("Red", null);
list.append("Green", null);
list.append("Blue", null);
list.addCommand(backCommand);
list.addCommand(okCommand);
...

public void commandAction(Command cmd,
                          Displayable d) {
    if (cmd == okCommand) {
        List list = (List) d;
        for (int i = 0; i < list.size(); i++) {
            boolean selected = list.isSelected(i);
            // If selected, take action...
        }
    }
}

9.1.4 Long List Elements

In MIDP 2.0, an application can set a preference indicating what to do with longer element text that does not fit in a single line in a List. The setFitPolicy(int fitPolicy) method controls this preference, but a device may decide to ignore the application preference. The valid settings of the element fit policy are TEXT_WRAP_DEFAULT, TEXT_WRAP_ON, and TEXT_WRAP_OFF. The initial value of the element fit policy is TEXT_WRAP_DEFAULT, which indicates that the normal device-specific wrapping policy is used.

9.1.5 List Element Fonts

Each List element has a Font that may be used in drawing the text part of the element. An element font that is set by an application is just a hint from the application; some devices might not use it for rendering the text. The same Font class used in the low-level Graphics API is used in element fonts. An application can set the Font of an element with the method setFont(int elementNum, Font font). By default, all elements of a List have the same font. The default Font is determined by the device and is the font most commonly used in selection lists. If an application changes the element font, it can later restore the default font with the call setFont(elementNum, null).

There are two general usage scenarios for setting a font for a List that differs from the default. First, the element fonts with differing styles (such as plain, bold, or italic) might be used to highlight some implicit difference in elements. For example, in an e-mail client application, "unread" items might be presented using a bold font, and "read" items with plain font. Because the default font can itself be bold or plain, the application should, as a general rule, set all the element fonts, or else it should query the default font and create a variant font based on the properties of the default font. This also helps ensure that the font sizes of different elements remain consistent:

// Get the default font
Font defaultFont = list.getFont(0);
int defaultFontFace = defaultFont.getFace();
int defaultFontSize = defaultFont.getSize();

// Define a style that differs from the default font
int readFontStyle;
if (defaultFont.isBold()) {
    // If default is itself bold, use bold and italic
    readFontStyle = Font.STYLE_BOLD | Font.STYLE_ITALIC;
} else {
    // Otherwise use simply bold
    readFontStyle = Font.STYLE_BOLD;
}

// Get a new font with only the style differing from default font
Font readElementFont = Font.getFont(defaultFontFace, readFontStyle,
                                   defaultFontSize);
// Set the readElementFont for "unread" elements
for (int i = 0 ; i < list.size() ; i++) {
    // readState array contains boolean true if item is read
    if (!readState[i]) {
        list.setFont(i, readElementFont);
    }
}

The second general use case is that the setFont method can be passed a font that differs in size from the default font. If this is done, the application should change the font of all elements to have the same size. If the List element font sizes differ from element to element, this could result in awkward-looking user interfaces. Some devices might limit the element sizes of Lists, so it might not be possible for the application to completely control the font sizes.