javax.swing
Interface ListSelectionModel

All Known Implementing Classes:
DefaultListSelectionModel

public interface ListSelectionModel

A model that tracks the selection status of a list of items. Each item in the list is identified by a zero-based index only, so the model can be used to track the selection status of any type of list. The model supports three modes:

The model uses an event notification mechanism to notify listeners (see ListSelectionListener) about updates to the selection model.

This model is used to track row selections in the JList component, and row and column selections in the JTable component.


Field Summary
static int MULTIPLE_INTERVAL_SELECTION
          A selection mode in which any combination of items can be selected.
static int SINGLE_INTERVAL_SELECTION
          A selection mode in which a single interval can be selected (an interval is a range containing one or more contiguous items).
static int SINGLE_SELECTION
          A selection mode in which only one item can be selected.
 
Method Summary
 void addListSelectionListener(ListSelectionListener listener)
          Registers a listener with the model so that it receives notification of changes to the model.
 void addSelectionInterval(int anchor, int lead)
          Marks the items in the specified interval as selected.
 void clearSelection()
          Clears the current selection from the model.
 int getAnchorSelectionIndex()
          Returns the index of the anchor item.
 int getLeadSelectionIndex()
          Returns the index of the lead item.
 int getMaxSelectionIndex()
          Returns the highest selected index, or -1 if there is no selection.
 int getMinSelectionIndex()
          Returns the lowest selected index, or -1 if there is no selection.
 int getSelectionMode()
          Returns the selection mode, which is one of SINGLE_SELECTION, SINGLE_INTERVAL_SELECTION and MULTIPLE_INTERVAL_SELECTION.
 boolean getValueIsAdjusting()
          Returns a flag that is passed to registered listeners when changes are made to the model.
 void insertIndexInterval(int index, int length, boolean before)
          Inserts a new interval containing length items at the specified index (the before flag indicates whether the range is inserted before or after the existing item at index).
 boolean isSelectedIndex(int index)
          Returns true if the specified item is selected, and false otherwise.
 boolean isSelectionEmpty()
          Returns true if there is no selection, and false otherwise.
 void removeIndexInterval(int index0, int index1)
          Removes the items in the specified range (inclusive) from the selection model.
 void removeListSelectionListener(ListSelectionListener listener)
          Deregisters a listener so that it no longer receives notification of changes to the model.
 void removeSelectionInterval(int anchor, int lead)
          Marks the items in the specified interval as not selected.
 void setAnchorSelectionIndex(int index)
          Sets the index of the anchor item.
 void setLeadSelectionIndex(int index)
          Sets the index of the lead item.
 void setSelectionInterval(int anchor, int lead)
          Sets the selection interval to the specified range (note that anchor can be less than, equal to, or greater than lead).
 void setSelectionMode(int mode)
          Sets the selection mode.
 void setValueIsAdjusting(boolean valueIsAdjusting)
          Sets the flag that is passed to listeners for each change notification.
 

Field Detail

SINGLE_SELECTION

static final int SINGLE_SELECTION
A selection mode in which only one item can be selected.

See Also:
setSelectionMode(int), Constant Field Values

SINGLE_INTERVAL_SELECTION

static final int SINGLE_INTERVAL_SELECTION
A selection mode in which a single interval can be selected (an interval is a range containing one or more contiguous items).

See Also:
setSelectionMode(int), Constant Field Values

MULTIPLE_INTERVAL_SELECTION

static final int MULTIPLE_INTERVAL_SELECTION
A selection mode in which any combination of items can be selected.

See Also:
setSelectionMode(int), Constant Field Values
Method Detail

setSelectionMode

void setSelectionMode(int mode)
Sets the selection mode.

FIXME: The spec is silent about what happens to existing selections, for example when changing from an interval selection to single selection.

Parameters:
mode - one of SINGLE_SELECTION, SINGLE_INTERVAL_SELECTION and MULTIPLE_INTERVAL_SELECTION.
Throws:
IllegalArgumentException - if mode is not one of the specified values.
See Also:
getSelectionMode()

getSelectionMode

int getSelectionMode()
Returns the selection mode, which is one of SINGLE_SELECTION, SINGLE_INTERVAL_SELECTION and MULTIPLE_INTERVAL_SELECTION.

Returns:
The selection mode.
See Also:
setSelectionMode(int)

clearSelection

void clearSelection()
Clears the current selection from the model. If the selection state changes (that is, the existing selection is non-empty) a ListSelectionEvent should be sent to all registered listeners.

FIXME: what happens to the anchor and lead selection indices (the spec is silent about this)? See:

http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4334792


getMinSelectionIndex

int getMinSelectionIndex()
Returns the lowest selected index, or -1 if there is no selection.

Returns:
The lowest selected index.
See Also:
getMaxSelectionIndex()

getMaxSelectionIndex

int getMaxSelectionIndex()
Returns the highest selected index, or -1 if there is no selection.

Returns:
The highest selected index.
See Also:
getMinSelectionIndex()

isSelectedIndex

boolean isSelectedIndex(int index)
Returns true if the specified item is selected, and false otherwise. Special note: if index is negative, this method should return false (no exception should be thrown).

Parameters:
index - the item index (zero-based).
Returns:
true if the specified item is selected, and false otherwise.

isSelectionEmpty

boolean isSelectionEmpty()
Returns true if there is no selection, and false otherwise.

Returns:
true if there is no selection, and false otherwise.

setSelectionInterval

void setSelectionInterval(int anchor,
                          int lead)
Sets the selection interval to the specified range (note that anchor can be less than, equal to, or greater than lead). If this results in the selection being changed, a ListSelectionEvent is sent to all registered listeners.

If the selection mode is SINGLE_SELECTION, only the lead item is selected.

Parameters:
anchor - the anchor index.
lead - the lead index.

addSelectionInterval

void addSelectionInterval(int anchor,
                          int lead)
Marks the items in the specified interval as selected. The behaviour of this method depends on the selection mode: Note that anchor can be less than, equal to, or greater than lead.

Parameters:
anchor - the index of the anchor item
lead - the index of the lead item.

removeSelectionInterval

void removeSelectionInterval(int anchor,
                             int lead)
Marks the items in the specified interval as not selected. The behaviour of this method depends on the selection mode: Note that anchor can be less than, equal to, or greater than lead.

Parameters:
anchor - the index of the anchor item
lead - the index of the lead item.

insertIndexInterval

void insertIndexInterval(int index,
                         int length,
                         boolean before)
Inserts a new interval containing length items at the specified index (the before flag indicates whether the range is inserted before or after the existing item at index). FIXME: What is the selection status of the new items? Bug 4870694. FIXME: What event is generated?

Parameters:
index - the index of the item.
length - the number of items in the interval to be inserted.
before - if true, the interval should be inserted before index, otherwise it is inserted after.
See Also:
removeIndexInterval(int, int)

removeIndexInterval

void removeIndexInterval(int index0,
                         int index1)
Removes the items in the specified range (inclusive) from the selection model. This method should be called when an interval is deleted from the underlying list. FIXME: what happens to the lead and anchor indices if they are part of the range that is removed? FIXME: what event is generated

Parameters:
index0 - XXX
index1 - XXX
See Also:
insertIndexInterval(int, int, boolean)

getAnchorSelectionIndex

int getAnchorSelectionIndex()
Returns the index of the anchor item.

Returns:
The index of the anchor item.
See Also:
setAnchorSelectionIndex(int)

setAnchorSelectionIndex

void setAnchorSelectionIndex(int index)
Sets the index of the anchor item.

Parameters:
index - the item index.
See Also:
getAnchorSelectionIndex()

getLeadSelectionIndex

int getLeadSelectionIndex()
Returns the index of the lead item.

Returns:
The index of the lead item.
See Also:
setLeadSelectionIndex(int)

setLeadSelectionIndex

void setLeadSelectionIndex(int index)
Sets the index of the lead item.

Parameters:
index - the item index.
See Also:
getLeadSelectionIndex()

setValueIsAdjusting

void setValueIsAdjusting(boolean valueIsAdjusting)
Sets the flag that is passed to listeners for each change notification. If a sequence of changes is made to the selection model, this flag should be set to true at the start of the sequence, and false for the last change - this gives listeners the option to ignore interim changes if that is more efficient.

Parameters:
valueIsAdjusting - the flag value.
See Also:
getValueIsAdjusting()

getValueIsAdjusting

boolean getValueIsAdjusting()
Returns a flag that is passed to registered listeners when changes are made to the model. See the description for setValueIsAdjusting(boolean) for more information.

Returns:
The flag.

addListSelectionListener

void addListSelectionListener(ListSelectionListener listener)
Registers a listener with the model so that it receives notification of changes to the model.

Parameters:
listener - the listener (null ignored).
See Also:
removeListSelectionListener(ListSelectionListener)

removeListSelectionListener

void removeListSelectionListener(ListSelectionListener listener)
Deregisters a listener so that it no longer receives notification of changes to the model. If the specified listener is not registered with the model, or is null, this method does nothing.

Parameters:
listener - the listener (null ignored).
See Also:
addListSelectionListener(ListSelectionListener)