[Chapter 11] 11.3 Lists
Author: Pat Niemeyer and Josh Peck
Date: Tue Jul 22 19:01:06 1997

#

| Chapter 11 Using and Creating GUI Components |

## 11.3 Lists

A `List` is a step up on the evolutionary chain. Lists let the user choose from a group of alternatives. They can be configured to force the user to choose a single selection or to allow multiple choices. Usually, only a small group of choices are displayed at a time; a built-in scrollbar lets you move to the choices that aren't visible.

A `List` generates two kinds of events. If the user single clicks on a selection, the `List` generates an `ItemEvent`. If the user double-clicks, a `List` generates an `ActionEvent`. Therefore, a `List` can register both `ItemListener`s and `ActionListener`s. In either case, the listener can use the event to figure out what the user selected.

The applet below, `SearchableListApplet`, contains a `List` and a text field. Several of the items in the list aren't visible, because the list is too long for the space we've allotted for it (enough to display three items). When you type the name of an item into the text field, the applet displays the item you want and selects it. Of course, you could do this with a scrollbar, but then we wouldn't have the opportunity to demonstrate how to work with lists.

#### Figure 11.4: The SearchableList applet

    import java.awt.*;
    import java.awt.event.*;
    public class SearchableListApplet extends java.applet.Applet {
        public void init() {
            String [] items = { "One", "Two", "Three", "Four", "Five", "Six" };
            add( new SearchableList( items ) );
        }
    }
    class SearchableList extends Container implements ActionListener {
        List list;
        TextField field;
        SearchableList( String [] items ) {
            list = new List( 3 );  // Let some scroll for this example
            for(int i=0; i< items.length; i++)
                list.addItem( items[i] );
            field = new TextField();
            field.addActionListener( this );
            setLayout( new BorderLayout() );
            add("Center", list);
            add("South", field);
        }
        public void actionPerformed( ActionEvent e ) {
            String search = field.getText();
            for (int i=0; i< list.getItemCount(); i++)
                if ( list.getItem( i ).equals( search ) ) {
                    list.select( i );
                    list.makeVisible( i );  // Scroll it into view
                    break;
                }
            field.setText(""); // clear the text field
        }
    }

We create the `List` and the `TextField` in a new class, `SearchableList`; the applet itself only displays the `SearchableList`. `SearchableList` itself is a new kind of animal; it is a lightweight component that subclasses `Container` directly. We'll talk a little more about lightweight components later in the chapter.

In the constructor for `SearchableList`, we create our `List` by calling its constructor, setting it to display at most three components. We then call the `addItem()` method to add the possible selections to the list; these are the numbers "One" through "Six," passed to us in an array.

We then create our `TextField`, and register ourselves (i.e., the `SearchableList`) as an `ActionListener` for the field's events. Finally, we set the layout for `SearchableList` to a border layout, put the `List` in the center of the layout, and the `TextField` at the bottom.

The `actionPerformed()` method is called whenever the user presses RETURN in our `TextField`. In this method, we call `getText()` to extract the text the user typed. Then we loop through all the items in the list to see if there's a match. `getItemCount()` tells us the number of items in the list; `getItem()` gives us the text associated with any particular item. When we find a match, we call `select()` to make the matching item the selected item, and we call `makeVisible()` to make sure that this item is displayed.

By default, a `List` only allows a single selection. We've done nothing in this example to allow multiple selections, so whenever a user chooses an item, the previous selection is automatically dropped. If you want a list that supports multiple selections, call `setMultipleMode(true)`. In this case, you must use the `deselect()` method to clear the user's selections.

Text Components |  | Menus and Choices