| 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