The List component presents the user with a scrolling list of text items. The list can be set up so that the user can choose either one item or multiple items.

For example, the code . . .

---

List lst = new List(4, false);
lst.add("Mercury");
lst.add("Venus");
lst.add("Earth");
lst.add("JavaSoft");
lst.add("Mars");
lst.add("Jupiter");
lst.add("Saturn");
lst.add("Uranus");
lst.add("Neptune");
lst.add("Pluto");
cnt.add(lst);

---

where cnt is a container, produces the following scrolling list:

If the List allows multiple selections, then clicking on an item that is already selected deselects it. In the preceding example, only one item from the scrolling list can be selected at a time, since the second argument when creating the new scrolling list is false. If the List does not allow multiple selections, selecting an item causes any other selected item to be deselected.

Note that the list in the example shown was created with four visible rows. Once the list has been created, the number of visible rows cannot be changed. A default List is created with four rows, so that lst = new List() is equivalent to list = new List(4, false).

Beginning with Java 1.1, the Abstract Window Toolkit sends the List object all mouse, keyboard, and focus events that occur over it. (The old AWT event model is being maintained only for backwards compatibility, and its use is discouraged.)

When an item is selected or deselected by the user, AWT sends an instance of ItemEvent to the list. When the user double-clicks on an item in a scrolling list, AWT sends an instance of ActionEvent to the list following the item event. AWT also generates an action event when the user presses the return key while an item in the list is selected.

If an application wants to perform some action based on an item in this list being selected or activated by the user, it should implement ItemListener or ActionListener as appropriate and register the new listener to receive events from this list.

For multiple-selection scrolling lists, it is considered a better user interface to use an external gesture (such as clicking on a button) to trigger the action.