This tutorial will show you how to use lists in Java.

A list is an instance of the class JList. It is a component that exposes items that can be selected in 3 different modes:

• Single selection: A single item can be selected at a time.
• Single interval selection: Multiple items can be selected at a time, provided that they are contiguous.
• Multiple interval selection: All combinations are allowed.

A list can be displayed in a single column or in multiple columns. As an example, the following picture shows a frame containing a single-column list (with single selection mode) that exposes languages starting with the letter A:




Here is the code:


The code above is quite minimalistic. Therefore, all the properties of the list are left to their default values except the selection mode which is set by the call to the method setSelectionMode. The possible values are ListSelectionModel.SINGLE_SELECTION, ListSelectionModel.SINGLE_INTERVAL_SELECTION and ListSelectionModel.MULTIPLE_INTERVAL_SELECTION (the default).

Usually, lists are in a single column as in the above example. However, you can set another layout orientation by invoking the method setLayoutOrientation. The possible values are JList.VERTICAL (the default), JList.HORIZONTAL_WRAP and JList.VERTICAL_WRAP. The value HORIZONTAL_WRAP places the list's items in rows, adding new rows as necessary whereas VERTICAL_WRAP places the items in columns, adding new columns as necessary.

The list that I created in the above example is immutable. You cannot add or remove elements from the list after it is created. Furthermore, the events fired by the list are not handled. The next sections will show you how to add/remove items from a list and also how to handle events.



To be able to add or remove items from a list, you must provide an instance of the class DefaultListModel and pass it to the constructor of the class JList like this:


Next, to remove items, you can use one of the methods provided by the class DefaultListModel: remove(int index), removeAllElements, removeElement(Object obj), removeElementAt(int index) or removeRange(int fromIndex, int toIndex).

To add items to the list, use add(int index, Object element), addElement(Object obj) or set(int index, Object element).



List selection events are fired by a list when the selection changes. If you want to listen to those events, you can register a list selection listener on the list by calling the method addListSelectionListener(ListSelectionListener listener). For example, the sample shown below registers a listener which simply prints the selected item of a list to the standard output:


You might have noticed the call to the method getValueIsAdjusting provided by the class ListSelectionEvent. It simply returns false if the user has finished interacting with the list and true otherwise.

The method getSelectedValue returns the first selected value if the list allows multiple selection. If the list does not allow multiple selection, getSelectedValue returns the selected value. The class JList also provides a method named getSelectedIndex which returns the smallest selected index.

If you are working with a list that allows multiple items selection, you can use the method getSelectedIndices or getSelectedValues to get the array of selected indices or the array of selected values, depending on your needs.



This section will show you a practical example of two lists placed in a frame like this: there is a list on the left hand side and another one on the right hand side. Between the lists, two buttons allow the user to move items from one list to another. Here is what it looks like:




The code follows: