JList Class

Package: javax.swing

Using this creates a list component, which displays lists of objects within a box. Depending on how the list is configured, the user can be allowed to select one item in the list or multiple items. In addition, you have amazing control of how the items in the list are displayed.

Lists are almost always used in conjunction with scroll panes to allow the user to scroll the contents of the list. For more information, see JScrollPane Class.

Figure 5-8 shows a list component.

Figure 5-8

Constructors

Constructor	Description
JList()	Creates an empty list
JList(ListModel list)	Creates a list that uses the specified list model
JList(Object[] items)	Creates a list and fills it with the values in the array
JList(Vector[] items)	Creates a list and fills it with the values in the vector
void clearSelection()	Clears all selections

Methods

Method	Description
int getSelectedIndex()	Returns the index of the first selected item, or –1 if no items are selected.
int[] getSelected Indexes()	Returns an array with the index of each selected item. The array is empty if no items are selected.
Object getSelected Value()	Returns the first selected item or null if no items are selected.
Object[] getSelected Values()	Returns an array with all the selected items. The array is empty if no items are selected.
boolean isSelected Index(int index)	Returns true if the item at the specified index is selected.
boolean isSelection Empty()	Returns true if no items are selected.
void setFixedCell Height(int height)	Sets the height of each row.
void setFixedCell Width(int width)	Sets the width of each row.
void setSelected Index(int index)	Selects the item at the specified index.
void setSelected Indices(int[] indices)	Selects the items at the indices specified in the array.
void setSelection Mode(int mode)	Sets the selection mode. Allowable values are ListSelectionModel.SINGLE_SELECTION, ListSelectionModel.SINGLE_INTERVAL_SELECTION, and ListSelectionModel.MULTIPLE_INTERVAL_SELECTION.
void setVisible RowCount(int count)	Sets the number of rows displayed by the list.

Creating a list

To create a list and specify its items, you pass an array to the JList constructor. Then you call the setVisibleRowCount method to set the number of rows you want to be visible, add the list to a scroll pane, and add the scroll pane to a panel that you can later add to the frame. Here’s an example:

String[] toppings = {“Pepperoni”, “Sausage”,

“Linguica”, “Canadian Bacon”,

“Salami”, “Tuna”, “Olives”,

“Mushrooms”, “Tomatoes”,

“Pineapple”, “Kiwi”,

“Gummy Worms”};

list1 = new JList(toppings);

list1.setVisibleRowCount(5);

JScrollPane scroll = new JScrollPane(list1);

To control the type of selections the user can make, use the setSelectionMode method. You can pass this method one of three fields defined by the ListSelectionModel class:

ListSelectionModel.SINGLE_SELECTION: The user can select only one item at a time.

ListSelectionModel.SINGLE_INTERVAL_ SELECTION: The user can select multiple items, provided that all of them are within a single range.

ListSelectionModel.MULTIPLE_INTERVAL_ SELECTION: The user can select any combination of items.

This statement restricts the list to a single selection:

list1.setSelectionMode(ListSelectionModel.SINGLE_SELECTION);

The default is to allow any combination of multiple selections.

Getting items from a list

For a list that allows only a single selection, you can retrieve the selected item by calling the getSelectedValue method. You have to cast the value to the appropriate type before you use it, as in this example:

String topping = (String)list1.getSelectedValue();

If the list allows multiple selections, getSelectedValue returns just the first selected item. To get all the selections, you must use the getSelectedValues method instead. This method returns an array of objects that includes each item selected by the user.

Changing list items

By default, the items in a JList component can’t be changed after you create the list. If you want to create a list whose items can be changed, you must use another class — DefaultList Model — to create an object called a list model that contains the items you want to display in the JList component. Then you pass the list model object to the JList constructor. The list model is responsible for managing the list that’s displayed by the JList component. As a result, you can use the list model’s methods to add or remove items, and then the JList component automatically updates itself to reflect the list changes.

For more information, see DefaultListModel Class.