Using the JFC/Swing Packages

How to Use Lists

A JList presents the user with a list of options to choose from. The items in a list can change dynamically and can be any type of object. Other classes that provide the user with a list of items to choose from include combo boxes, menus, and radio buttons. Of these, list is the only one that supports multiple selection, either contiguous or not. [PENDING: should do a multiple selection example??]

Here's a picture of a demo application that uses a JList to display the names of images to view.

---

Try this:

1. Compile and run the application. The main source file is ImageChooser.java. imagenames.properties provides the image names to put in the JList. You can download the entire swing lesson to get the image files listed, or you can modify the properties file to list images you already have.
   See Getting Started with Swing if you need help compiling or running the program.
2. Choose an image from the list. Use the scroll bar to see more names.

---

Below is the code from ImageChooser.java that creates and sets up the list:

// Create the list
JList listOfImages = new JList(imageList);
listOfImages.setSelectedIndex(0);
listOfImages.addListSelectionListener(this);

// Put it in a scroll pane
JScrollPane scrollPane = new JScrollPane(listOfImages);

The code uses a Vector object to provide the list with its initial list items. In this example, the Vector contains strings obtained from a properties file. However, the values in the list can be any Object, in which case the Object's toString method provides the text to display. To put an image or other non-text value in the list, you must provide a custom cell renderer with setCellRenderer.

Next, the code adds a list selection listener to the list. List selection events are Swing-specific events that are fired from a list whenever the selection is changing or is about to change. How to Write a List Selection Listener discusses list selection events, using ImageChooser as an example.

Finally, the code puts the list into a scroll pane, so that the list has scroll bars.

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 and Component 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, and the selection is managed by a list selection model object. However, you usually don't need to deal with these objects, since JList provides default help objects and many convenience methods for working with them.

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

• Setting the Items in the List
• Managing the List's Selection
• Working with a Scroll Pane

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 a ListModel. [PENDING: check]
void setModel(ListModel) ListModel getModel()	Set or get the model that contains the contents of the list. You can dynamically modify the contents of the list by calling methods on the object returned by getModel. [PENDING: should probably do an example of that]
void setListData(Object[]) void setListData(Vector)	Set the items in the list. These methods implicitly create a ListModel. [PENDING: check]

Managing the List's Selection

Method	Purpose
void setSelectedIndex(int) setSelectedIndices(int[]) setSelectedValue(Object, bolean) setSelectedInterval(int, int)	Set the current selection as indicated. Note that JList supports multiple selection although by default multiple selection is turned off. Use setSelectionMode to set either single or multiple selection.
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_SELECTION.
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 JList

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

Example	Where Described
ImageChooser.java	This page and How to Write a List Selection Listener.

Using the JFC/Swing Packages