How to Write a List Selection Listener

List selection events occur when the selection in a list or table is either changing or has just changed. The events are fired from an object that implements the ListSelectionModel interface. ^[19] To get a list or table's list selection model object, use the getSelectionModel method.

^[19] ListSelectionModel API documentation: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/ListSelectionModel.html.

To detect list selection events, you register a listener on the appropriate list selection model object. The JList class also gives you the option of registering a listener on the list itself, rather than directly on the list selection model. This section looks at an example that shows how to listen to list selection events on a selection model. Examples That Use List Selection Listeners (page 688) lists examples that listen on the list directly.

The selection model is shared by a list and a table. Figure 9 is a picture of the example running. You can dynamically change the selection mode to any of the three supported modes:

• Single selection mode

• Single interval selection mode

• Multiple interval selection mode

Figure 9. The ListSelectionDemo application.

Try This:

1. 

   Run ListSelectionEventDemo using Java Web Start or compile and run the example yourself. ^[20]

   ^[20] To run ListSelectionEventDemo using Java Web Start, click the ListSelectionEventDemo link on the RunExamples/events.html page on the CD. You can find the source files here: JavaTutorial/uiswing/events/example-1dot4/index.html#ListSelectionEventDemo .

2. Select and deselect items in the list and table. The mouse and keyboard commands required to select items depend on the look and feel. For the Java look and feel, click the left mouse button to begin a selection, use the Shift key to extend a selection contiguously, and use the Control key to extend a selection discontiguously. Dragging the mouse moves or extends the selection, depending on the list selection mode.

Here's the code from ListSelectionDemo.java that sets up the selection model and adds a listener to it:

  ...//where the member variables are defined  JList list; JTable table;  ...//in the init method:  listSelectionModel = list.getSelectionModel();     listSelectionModel.addListSelectionListener(                             new SharedListSelectionHandler());     ...     table.setSelectionModel(listSelectionModel); 

And here's the code for the listener, which works for all the possible selection modes:

 class SharedListSelectionHandler implements ListSelectionListener {     public void valueChanged(ListSelectionEvent e) {         ListSelectionModel lsm = (ListSelectionModel)e.getSource();         int firstIndex = e.getFirstIndex();         int lastIndex = e.getLastIndex();         boolean isAdjusting = e.getValueIsAdjusting();         output.append("Event for indexes "                       + firstIndex + " - " + lastIndex                       + "; isAdjusting is " + isAdjusting                       + "; selected indexes:");         if (lsm.isSelectionEmpty()) {             output.append(" <none>");         } else {             // Find out which indexes are selected.             int minIndex = lsm.getMinSelectionIndex();             int maxIndex = lsm.getMaxSelectionIndex();             for (int i = minIndex; i <= maxIndex; i++) {                 if (lsm.isSelectedIndex(i)) {                     output.append(" " + i);                 }             }         }         output.append(newline);     } } 

This valueChanged method displays the first and last indices reported by the event, the value of the event's isAdjusting flag, and the indices currently selected.

Note that the first and last indices reported by the event indicate the inclusive range of items for which the selection has changed. If the selection mode is multiple interval selection, some items within the range might not have changed. The isAdjusting flag is true if the user is still manipulating the selection, and false if the user has finished changing it.

The ListSelectionEvent ^[21] object passed into valueChanged indicates only that the selection has changed. The event contains no information about the current selection. So, this method queries the selection model to figure out the current selection.

^[21] ListSelectionEvent API documentation: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/event/ListSelectionEvent.html.

The List Selection Listener API

Table 22 lists the methods in the ListSelectionListener interface and Table 23 describes the methods in the ListSelectionEvent class. Note that because ListSelectionListener has only one method, it has no corresponding adapter class. Also refer to the List- SelectionListener API documentation at: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/event/ListSelectionListener.html. The ListSelectionEvent API documentation is online at: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/event/ListSelectionEvent.html.

Table 22. The ListSelectionListener Interface

Method	Purpose
valueChanged(ListSelectionEvent)	Called when the selection in the listened-to component is changing, as well as just after the selection has changed.

Table 23. The ListSelectionEvent API

Method	Purpose
Object getSource() ( in java.util.EventObject)	Return the object that fired the event. If you register a list selection listener on a list directly, then the source for each event is the list. Otherwise, the source is the selection model.
int getFirstIndex()	Return the index of the first item whose selection value has changed. Note that for multiple interval selection, the first and last items are guaranteed to have changed but items between them might not have.
int getLastIndex()	Return the index of the last item whose selection value has changed. Note that for multiple interval selection, the first and last items are guaranteed to have changed but items between them might not have.
boolean getValueIsAdjusting()	Return true if the selection is still changing. Many list selection listeners are interested only in the final state of the selection and can ignore list selection events when this method returns true.

Examples That Use List Selection Listeners

The following examples use list selection listeners.

Example	Where Described	Notes
ListSelectionDemo	This section	Reports all list selection events that occur on a list and on a table. The table and the list share a list selection model, so only one listener is required. Lets the user dynamically change the selection mode.
ListDemo	How to Use Lists (page 267)	Listens to events on a single-selection list (not on its selection model). Enables and disables a button depending on whether any items are selected in the list.
SplitPaneDemo	How to Use Lists (page 267)	Listens to events on a single-selection list (not on its selection model).
SimpleTableSelectionDemo	How to Use Tables (page 388)	Uses two different list selection listeners on one table. One listener listens to list selection events on table columns ; the other listens to list selection events on table rows.