Using Components, the GUI Building Blocks

How to Use Lists

The List class provides a scrollable area containing selectable text items (one per line). Generally, a user selects an item by clicking it, and indicates that an action should occur by double-clicking an item or pressing Return. Lists can allow either multiple selections or just one selection at a time. Other components that allow users to choose from multiple options are checkboxes, choices, and menus.

Below is an applet that shows two lists, along with a text area that displays information about events. The top list (which lists Spanish numbers) allows multiple selections. The bottom (which lists Italian numbers) allows a maximum of one selection. Note that the first item in each list has index 0.

Below is the code that creates each list and handles events on the lists. (Here's the whole program.) Note that the e.arg data for action events (which is passed into the action() method as the second argument) is the name of the acted-on item, similar to the argument for action events on other components such as buttons and even menus. However, the e.arg data for non-action list events is the index of the acted-on item.

    ...//Where instance variables are declared:
    TextArea output;
    List spanish, italian; 

    ...//Where initialization occurs:

    //Build first list, which allows multiple selections.
    spanish = new List(4, true); //prefer 4 items visible
    spanish.addItem("uno");
    spanish.addItem("dos");
    spanish.addItem("tres");
    spanish.addItem("cuatro");
    spanish.addItem("cinco");
    spanish.addItem("seis");
    spanish.addItem("siete");

    //Build second list, which allows one selection at a time.
    italian = new List(); //Defaults to none visible, only one selectable
    italian.addItem("uno");
    italian.addItem("due");
    italian.addItem("tre");
    italian.addItem("quattro");
    italian.addItem("cinque");
    italian.addItem("sei");
    italian.addItem("sette");

. . .

public boolean action(Event e, Object arg) {
    if (e.target instanceof List) {
        String language = (e.target == spanish) ?
                          "Spanish" : "Italian";
        output.appendText("Action event occurred on \""
                          + (String)arg  + "\" in "
                          + language + ".\n");
    }
    return true;
}

public boolean handleEvent(Event e) {
    if (e.target instanceof List) {
        List list = (List)(e.target);
        String language = (list == spanish) ?
                          "Spanish" : "Italian";
        switch (e.id) {
          case Event.LIST_SELECT:
            int sIndex = ((Integer)e.arg).intValue();
            output.appendText("Select event occurred on item #"
                                  + sIndex + " (\""
                                  + list.getItem(sIndex)  + "\") in "
                              + language + ".\n");
            break;
          case Event.LIST_DESELECT:
            int dIndex = ((Integer)e.arg).intValue();
            output.appendText("Deselect event occurred on item #"
                                  + dIndex + " (\""
                                  + list.getItem(dIndex)  + "\") in "
                              + language + ".\n");
        }
    }
    return super.handleEvent(e);
}

Besides the two constructors and the addItem() and getItem() methods shown above, List provides the following handy methods:

int countItems()

Returns the number of items in the List.

String getItem(int)

Returns the string displayed by the item at the specified index.

void addItem(String, int)

Adds the specified item at the specified index.

void replaceItem(String, int)

Replaces the item at the specified index.

void clear(), void delItem(int), void delItems(int, int)

Delete one or more items from the list. The clear() method empties the list. The delItem() method deletes the specified item from the list. The delItems() method deletes every item between (and including) the specified indexes from the list.

int getSelectedIndex()

Returns the index of the selected item in the list. Returns -1 if no item is selected or more than one item is selected.

int[] getSelectedIndexes()

Returns the indexes of the selected items in the list.

String getSelectedItem()

Like getSelectedIndex(), but returns the selected item's String instead of its index. Returns null if no item is selected or more than one item is selected.

String[] getSelectedItems()

Like getSelectedIndexes(), but returns the selected items' Strings instead of their indexes.

void select(int), void deselect(int)

Selects or deselects the item at the specified index.

boolean isSelected(int)

Returns true if the item at the specified index is selected.

int getRows()

Returns the number of visible lines in the list.

boolean allowsMultipleSelections(), boolean setMultipleSelections()

Returns or sets whether the list allows multiple items to be selected ("on") at the same time.

int getVisibleIndex(), void makeVisible(int),

The makeVisible() method forces the item at the specified index to be visible. The getVisibleIndex() method gets the index of the item that was last made visible by the makeVisible() method.

Using Components, the GUI Building Blocks