Previous | Next | Trail Map | Creating a GUI with JFC/Swing | Using Swing Components

How to Use Lists

A JList(in the API reference documentation) presents the user with a group of items to choose from. A list can have many items or can grow to have many items, so lists are often used in a scroll pane. Because of this, JList is a scroll-savvy class.

In addition to lists, the following Swing components present multiple selectable items to the user: combo boxes, menus, tables, and groups of check boxes or radio buttons, Only tables, lists, and groups of check boxes allow multiple items to be selected at the same time.

This application uses a JList to display a list of image names. When the user clicks on an image name, the application displays the image.

Try this:
  1. Compile and run the application. The main source file is SplitPaneDemo.java. imagenames.properties provides the image names to put in the JList. You can download the entire swing lesson to get the image files used or you can modify the properties file to use images you already have.
  2. Choose an image from the list. Use the scroll bar to see more names.
  3. Refer to How to Use Split Panes to find out about this demo's use of a split pane.
Below is the code from SplitPaneDemo.java that creates and sets up the list: 
...where member variables are declared
   this Vector is initialized from a properties file...
static Vector imageList;
...where the GUI is created...
// Create the list of images and put it in a scroll pane
JList list = new JList(imageList);
list.setSelectionMode(ListSelectionModel.SINGLE_SELECTION);
list.setSelectedIndex(0);
list.addListSelectionListener(this);
JScrollPane listScrollPane = new JScrollPane(list);
The example initializes the list with a Vector filled with strings that were read in from a properties file.

After a list has been created and initialized, you can replace the entire set of items in the list with either the setModel or setListData methods. However, the JList class itself does not provide API for adding, removing, or changing individual items in a list. To individually modify the items in a list, you modify the list's list model object.

A list manages its items using an object that adheres to the ListModel(in the API reference documentation) interface. The constructor used in the previous example implicitly creates a list model, which you can retrieve with getModel. The model created by this constructor is immutable--its items cannot be changed individually. To create a list whose items can be changed individually, set the list's model to an instance of a mutable list model class-- such as an instance of DefaultListModel(in the API reference documentation). You can set a list's model two ways:

See Modifying a List for an example.

The SplitPaneDemo example fills the list with String objects. However, the values in the list can be any Object, in which case the Object's toString method provides the text to display. To display an item as an image or other non-text value, you must provide a custom cell renderer with setCellRenderer. The tutorial does not provide an example of a list with a custom cell renderer. You can find an example in the SwingSet application shipped with Swing. [PENDING: check the following] A list's cell renderer is similar to a table's cell renderer. For a custom table cell renderer example, see [PENDING: table cell renderer].

Selecting Items in a List

A list uses an instance of ListSelectionModel(in the API reference documentation) to manage its selection. By default, a list selection model allows any combination of items to be selected at a time. You can specify a different selection mode by calling the setSelectionMode method on the list. For example, SplitPaneDemo sets the selection mode to SINGLE_SELECTION (a constant defined by ListSelectionModel) so that only one item in the list can be selected. The following table describes the three list selection modes:

ModeDescriptionExample
SINGLE_SELECTION Only one item can be selected at a time. When the user selects an item, any previously selected item is deselected first.
SINGLE_INTERVAL_SELECTION Multiple, contiguous items can be selected. When the user begins a new selection, any previously selected items are deselected first.
MULTIPLE_INTERVAL_SELECTION The default. Any combination of items can be selected. The user must explicitly deselect items.

No matter which selection mode your list uses, the list fires list selection events whenever the selection changes. You can process these events by adding a list selection listener to the list with the addListSelectionListener method. A list selection listener must implement one method: valueChanged. Here's the valueChanged method for the listener in SplitPaneDemo: 

public void valueChanged(ListSelectionEvent e) {
    if (e.getValueIsAdjusting())
        return;

    JList theList = (JList)e.getSource();
    if (theList.isSelectionEmpty()) {
        picture.setIcon(null);
    } else {
        int index = theList.getSelectedIndex();
        ImageIcon newImage = new ImageIcon("images/" +
                                 (String)imageList.elementAt(index));
        picture.setIcon(newImage);
        picture.setPreferredSize(new Dimension(newImage.getIconWidth(),
                                               newImage.getIconHeight() ));
        picture.revalidate();
    }
}
Many list selection events can be generated from a single user action such as a mouse click. The getValueIsAdjusting method returns true if the user is still manipulating the selection. This particular program is interested only in the final result of the user's action, so the valueChanged method updates the image only if getValueIsAdjusting returns false.

Because the list is in single selection mode, this code can use getSelectedIndex to get the index of the just-selected item. JList provides other methods for setting or getting the selection when the selection mode allows more than one item to be selected. Alternatively, you can listen for events on the list's list selection model rather than on the list itself. Examples of Handling List Selection Events provides an example that shows how to listen for list selection events on the list selection model and let's you change the selection mode of a list dynamically

Modifying a List
Here's an application that lets a user modify a list of employees by hiring and firing them:
Try this:
  1. Compile and run the application. The source file is ListDemo.java.
  2. Select a name from the list and click the Fire button.
  3. Type in a new name and click the Hire button.
Here's the code from ListDemo that creates a mutable list model object, puts the initial items in it, and uses the list model to create a list: 
listModel = new DefaultListModel();
listModel.addElement("Alison Huml");
listModel.addElement("Kathy Walrath");
listModel.addElement("Lisa Friendly");
listModel.addElement("Mary Campione");

list = new JList(listModel);
This particular program uses an instance of DefaultListModel, a class provided by Swing. In spite of its name, a list does not have a DefaultListModel unless your program explicitly make it so. If this class doesn't suit your needs, you can write a custom list model, which must adhere to the ListModel interface.

Here's the actionPerformed method for the action listener registered on the Fire button: 

public void actionPerformed(ActionEvent e) {
    int index = list.getSelectedIndex();
    listModel.remove(index);

    int size = listModel.getSize();

    //Nobody's left, disable firing
    if (size == 0) {
	fireButton.setEnabled(false);

    //Adjust the selection
    } else {
	if (index == listModel.getSize())//removed item in last position                    index--;
	list.setSelectedIndex(index);   //otherwise select same index
    }
}
The bold line of code removes the selected item in the list. The remaining lines in the method disable the fire button if the list is now empty, and make another selection.

Here's the actionPerformed method for the action listener shared by the Hire button and the text field: 

public void actionPerformed(ActionEvent e) {
    //User didn't type in a name...
    if (employeeName.getText().equals("")) {
	Toolkit.getDefaultToolkit().beep();
	return;
    }

    int index = list.getSelectedIndex();
    int size = listModel.getSize();

    //If no selection or if item in last position is selected,
    //add the new hire to end of list, and select new hire
    if (index == -1 || (index+1 == size)) {
	listModel.addElement(employeeName.getText());
	list.setSelectedIndex(size);

    //Otherwise insert the new hire after the current selection,
    //and select new hire
    } else {
	listModel.insertElementAt(employeeName.getText(), index+1);
	list.setSelectedIndex(index+1);
    }
}
This code uses the list model's addElement method to add the new name to the end of the list if the last item in the list is selected or if there's no selection. Otherwise, the code calls insertElementAt to insert the new name after the current selection.

The List API

The following tables list the commonly used JList constructors and methods. Other methods you're likely to call are defined by the JComponent(in the API reference documentation) and Component(in the API reference documentation) classes and include [PENDING: anything in particular for JList?]. [Link to JComponent and Component discussions.]

Much of the operation of a list is managed by other objects. For example, the items in the list are managed by a list model object, the selection is managed by a list selection model object, and most programs put a list in a scroll pane to handle scrolling. For the most part, you don't need to worry about these helper objects because JList creates them as necessary and you interact with them implicitly with JList's convenience methods.

That said, the API for using lists falls into these categories:

Setting the Items in the List
Method Purpose

JList(ListModel)
JList(Object[])
JList(Vector) 		Create a list with the initial list items specified. The second and third constructors implicitly create an immutable ListModel.
void setModel(ListModel)
ListModel getModel() 		Set or get the model that contains the contents of the list.
void setListData(Object[])
void setListData(Vector) 		Set the items in the list. These methods implicitly create an immutable ListModel.

Managing the List's Selection
Method Purpose
void addListSelectionListener(
ListSelectionListener) 		Register to receive notification of selection changes.
void setSelectedIndex(int)
void setSelectedIndices(int[])
void setSelectedValue(Object, boolean)
void setSelectedInterval(int, int) 		Set the current selection as indicated. Use setSelectionMode to set what ranges of selections are acceptable. The boolean argument specifies whether the list should attempt to scroll itself so that the selected item is visible.
int getSelectedIndex()
int getMinSelectionIndex()
int getMaxSelectionIndex()
int[] getSelectedIndices()
Object getSelectedValue()
Object[] getSelectedValues() 		Get information about the current selection as indicated.
void setSelectionMode(int)
int getSelectionMode() 		Set or get the selection mode. Acceptable values are: SINGLE_SELECTION, SINGLE_INTERVAL_SELECTION, or MULTIPLE_INTERVAL_SELECTION, which are defined in ListSelectionModel.
void clearSelection()
boolean isSelectionEmpty() 		Set or get whether any items are selected.
boolean isSelectedIndex(int) Determine whether the specified index is selected.

Working with a Scroll Pane
Method Purpose
void ensureIndexIsVisible(int) Scroll so that the specified index is visible within the viewport that this list is in.
int getFirstVisibleIndex()
int getLastVisibleIndex() 		Get the index of the first or last visible item.
void setVisibleRowCount(int)
int getVisibleRowCount() 		Set or get how many rows of the list are visible.

Examples that Use Lists

This table shows the examples that use JList and where those examples are described.

Example Where Described Notes
SplitPaneDemo.java This page and
How to Use Split Panes 		Contains a single selection, immutable list.
ListDemo.java This page Demonstrates how to add and remove items from a list at runtime.
ListDialog.java How to Use BoxLayout Implements a modal dialog with a single selection list.
ListSelectionDemo.java How to Write a List Selection Listener Contains a list and a table that share the same selection model. You can dynamically choose the selection mode.
SharedModelDemo.java Nowhere yet Modifies ListSelectionDemo so that the list and table share the same data model.

Previous | Next | Trail Map | Creating a GUI with JFC/Swing | Using Swing Components