11

Multi-Select List

Features of JCMultiSelectList  Properties  Constructors and Methods  Examples

---

11.1 Features of JCMultiSelectList

JCMultiSelectList matches the API for JList except that two lists instead of one appear in the component's GUI. There are four buttons between the two lists that move items back and forth. The left-hand list contains non-selected items and the right-hand list contains the selected items. In the context of a JCMultiSelectList, if an item is marked as selected, it means more than simply being highlighted. Besides providing a visual division of list items into the two columns, selected and non-selected, there are numerous methods for dealing with the values and indices of a set of selected values.

• JCMultiSelectList provides a visual component that clearly distinguishes items chosen from a given list by removing them from the original list and placing them in another container. See the next figure for details.
• You can create a JCMultiSelectList using one of its five constructors, four of which correspond to the constructors of a JList. The remaining constructor has an empty ListModel, but has a parameter for setting the horizontal gap between the two lists.
• As with a JList, you can specify content using the ListModel interface, or you can supply content using Objects or Vectors.
• You are able to modify content in various ways depending on which objects you used to populate the main list.
• End users may perform single or multiple, contiguous or non-contiguous selections of list items.
• The ListSelectionModel generates a ListSelectionEvent to allow you to process user interactions.

Four buttons control the movement of items in one list to the other. They are shown in the next figure. The top button moves selected items from the left-hand list to the right-hand list. The second from the top moves all items out of the left-hand list to the right-hand list. The bottom two buttons perform the analogous operation, but in the other direction.

Figure 41 :  GUI for JCMultiSelectList.

You set a ListModel on the component, or you can use the default model that is provided. In the latter case, you simply add Objects to the existing component. The component uses getSelected() to determine which items should appear in the right-hand list. Only the non-selected items show on the left.

---

11.2 Properties

A selection of JCMultiSelectList's properties are shown in the following table. Please see Properties of JCMultiSelectList and Bean Properties Reference in Appendix A for a complete list.

Property	Description
model	Gets or sets the model associated with the list.
prototypeCellValue	Sets the prototypical cell value, a cell used for the calculation of cell widths, rather than forcing the calculation to inspect every item in the list.
toolTipText	Gets or sets the text that appears in the tool tip.

---

11.3 Constructors and Methods

Constructors

There are constructors for ListModel, array, and Vector types of data models.

Methods

JCMultiSelectList subclasses from JComponent, giving it a host of inherited methods. It overrides some, like addListSelectionListener, to provide specific functionality. The table shows a few frequently used methods. Please refer to the API for a full list.

Method Name	Description
addListSelectionListener()	Adds a listener to the ListSelectionListener's list. Its parameters are a javax.swing.event and a ListSelectionListener.
addSelectionInterval()	Adds the specified interval to the current selection. It takes two int parameters that specify the beginning and ending positions of the interval.
clearSelection()	Clears the selection.
deselectAll()	Moves all items from the right list to the left list.
deselectItem()	Moves the items selected in the right list to the left list.
fireSelectionValueChanged()	Forwards the given notification event to all registered listeners. It takes two int parameters that specify the begin and end positions of the interval, and a third boolean parameter that specifies whether this is one of a rapidly occurring series of events. Parameters are int firstIndex, int lastIndex, boolean isAdjusting   See javax.swing.event.ListSelectionEvent.
getAnchorSelectionIndex()	Returns the first index argument from the most recent interval selection.
getSelectedIndex()	Returns the index of the first selected cell.
getSelectedIndices()	Returns the array of indices of selected items.
getSelectedValues()	Returns an array of the selected cell values.
setModel()	Sets the list's data model. Its single parameter is a javax.swing.ListModel.

---

11.4 Examples

See examples.elements.MultiSelectList for a full listing of this example.

One of JCMultiSelectList's constructors takes an array of list items as its parameter. Call this array data and define it as follows:

static String[] data = {"Tom", "Dick", "Harry"};

Create a JCMultiSelectList and give it the data:

JCMultiSelectList list = new JCMultiSelectList(data);

You process events generated by the list by implementing the valueChanged() method of the ListSelectionListener interface.