Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.jgoodies.binding.list
Class SelectionInList

    java.lang.Object
      com.jgoodies.binding.beans.Model
          com.jgoodies.binding.value.AbstractValueModel
              com.jgoodies.binding.list.SelectionInList

All Implemented Interfaces:
  Observable, ValueModel, Serializable, ListModel

    public final class SelectionInList

extends AbstractValueModel
implements ListModel

Represents a selection in a list of objects. Provides bound bean properties for the list, the selection, the selection index, and the selection empty state. The SelectionInList implements ValueModel with the selection as value. Selection changes fire an event only if the old and new value are not equal. If you need to compare the identity you can use and observe the selection index instead of the selection or value.

The SelectionInList uses three ValueModels to hold the list, the selection and selection index and provides bound bean properties for these models. You can access, observe and replace these ValueModels. This is useful to connect a SelectionInList with other ValueModels; for example you can use the SelectionInList's selection holder as bean channel for a PresentationModel. Since the SelectionInList is a ValueModel, it is often used as bean channel. See the Binding tutorial classes for examples on how to connect a SelectionInList with a PresentationModel.

This class also implements the `ListModel` interface that allows API users to observe fine grained changes in the structure and contents of the list. Hence instances of this class can be used directly as model of a JList. If you want to use a SelectionInList with a JComboBox or JTable, you can convert the SelectionInList to the associated component model interfaces using the adapter classes `ComboBoxAdapter` and `AbstractTableAdapter` respectively. These classes are part of the Binding library too.

The SelectionInList supports two list types as content of its list holder: `List` and `ListModel`. The two modes differ in how precise this class can fire events about changes to the content and structure of the list. If you use a List, this class can only report that the list changes completely; this is done by emitting a PropertyChangeEvent for the list property. Also, a `ListDataEvent` is fired that reports a complete change. In contrast, if you use a ListModel it will report the same PropertyChangeEvent. But fine grained changes in the list model will be fired by this class to notify observes about changes in the content, added and removed elements.

If the list content doesn't change at all, or if it always changes completely, you can work well with both List content and ListModel content. But if the list structure or content changes, the ListModel reports more fine grained events to registered ListDataListeners, which in turn allows list views to chooser better user interface gestures: for example, a table with scroll pane may retain the current selection and scroll offset.

An example for using a ListModel in a SelectionInList is the asynchronous transport of list elements from a server to a client. Let's say you transport the list elements in portions of 10 elements to improve the application's responsiveness. The user can then select and work with the SelectionInList as soon as the ListModel gets populated. If at a later time more elements are added to the list model, the SelectionInList can retain the selection index (and selection) and will just report a ListDataEvent about the interval added. JList, JTable and JComboBox will then just add the new elements at the end of the list presentation.

If you want to combine List operations and the ListModel change reports, you may consider using an implementation that combines these two interfaces, for example `ArrayListModel` or `LinkedListModel`.

Imporant Note: If you change the ListModel instance, either by calling `#setListModel(ListModel)` or by setting a new value to the underlying list holder, you must ensure that the list holder throws a PropertyChangeEvent whenever the instance changes. This event is used to remove a ListDataListener from the old ListModel instance and is later used to add it to the new ListModel instance. It is easy to violate this constraint, just because Java's standard PropertyChangeSupport helper class that is used by many beans, checks a changed property value via `#equals`, not `==`. For example, if you change the SelectionInList's list model from an empty list `L1` to another empty list instance `L2`, the PropertyChangeSupport won't generate a PropertyChangeEvent, and so, the SelectionInList won't know about the change, which may lead to unexpected behavior.

This binding library provides some help for firing PropertyChangeEvents if the old ListModel and new ListModel are equal but not the same. Class `ExtendedPropertyChangeSupport` allows to permanently or individually check the identity (using `==`) instead of checking the equity (using `#equals`). Class `Model` uses this extended property change support. And class `ValueHolder` uses it too and can be configured to always test the identity.

Since version 1.0.2 this class provides public convenience methods for firing ListDataEvents, see the methods `#fireContentsChanged`, `#fireIntervalAdded`, and `#fireIntervalRemoved`. These are automatically invoked if the list holder holds a ListModel that fires these events. If on the other hand the underlying List or ListModel does not fire a required ListDataEvent, you can use these methods to notify presentations about a change. It is recommended to avoid sending duplicate ListDataEvents; hence check if the underlying ListModel fires the necessary events or not. Typically an underlying ListModel will fire the add and remove events; but often it'll lack an event if the (seletcted) contents has changed. A convenient way to indicate that change is `#fireSelectedContentsChanged`. See the tutorial's AlbumManagerModel for an example how to use this feature.

Constraints: The list holder holds instances of `List` or `ListModel`, the selection holder values of type `Object` and the selection index holder of type `Integer`. The selection index holder must hold non-null index values; however, when firing an index value change event, both the old and new value may be null. If the ListModel changes, the underyling ValueModel must fire a PropertyChangeEvent.

TODO: Consider renaming members names `*ListHolder` to `*ListModelHolder`. If so, mark the old methods as deprecated.

Version:
  $Revision: 1.12 $
Author:
  Karsten Lentzsch
See Also:
  `ValueModel`, `List`, `ListModel`, `ComboBoxAdapter`, `AbstractTableAdapter`, `ExtendedPropertyChangeSupport`, `Model`, `ValueHolder`, Serialized Form

Field Summary
`static String` | `PROPERTYNAME_LIST` The name of the bound write-only list property.
`static String` | `PROPERTYNAME_LIST_HOLDER` The name of the bound read-write listHolder property.
`static String` | `PROPERTYNAME_SELECTION` The name of the bound read-write selection property.
`static String` | `PROPERTYNAME_SELECTION_EMPTY` The name of the bound read-only selectionEmpty property.
`static String` | `PROPERTYNAME_SELECTION_HOLDER` The name of the bound read-write selection holder property.
`static String` | `PROPERTYNAME_SELECTION_INDEX` The name of the bound read-write selectionIndex property.
`static String` | `PROPERTYNAME_SELECTION_INDEX_HOLDER` The name of the bound read-write selection index holder property.

Fields inherited from class com.jgoodies.binding.value.AbstractValueModel
`PROPERTYNAME_VALUE`

Constructor Summary
`SelectionInList()` Constructs a SelectionInList with an empty initial `ArrayListModel` using defaults for the selection holder and selection index holder.
`SelectionInList(List list)` Constructs a SelectionInList on the given list using defaults for the selection holder and selection index holder.
`SelectionInList(ListModel listModel)` Constructs a SelectionInList on the given list model using defaults for the selection holder and selection index holder.
`SelectionInList(ListModel listModel, ValueModel selectionHolder)` Constructs a SelectionInList on the given list model and selection holder using a default selection index holder.
`SelectionInList(ListModel listModel, ValueModel selectionHolder, ValueModel selectionIndexHolder)` Constructs a SelectionInList on the given list model, selection holder, and selection index holder.
`SelectionInList(List list, ValueModel selectionHolder)` Constructs a SelectionInList on the given list and selection holder using a default selection index holder.
`SelectionInList(List list, ValueModel selectionHolder, ValueModel selectionIndexHolder)` Constructs a SelectionInList on the given list, selection holder, and selection index holder.
`SelectionInList(Object[] listItems)` Constructs a SelectionInList on the given item array using defaults for the selection holder and selection index holder.
`SelectionInList(Object[] listItems, ValueModel selectionHolder)` Constructs a SelectionInList on the given item array and selection holder using a default selection index holder.
`SelectionInList(Object[] listItems, ValueModel selectionHolder, ValueModel selectionIndexHolder)` Constructs a SelectionInList on the given item array and selection holder using a default selection index holder.
`SelectionInList(ValueModel listHolder)` Constructs a SelectionInList on the given list holder using defaults for the selection holder and selection index holder.
`SelectionInList(ValueModel listHolder, ValueModel selectionHolder)` Constructs a SelectionInList on the given list holder, selection holder and selection index holder.
`SelectionInList(ValueModel listHolder, ValueModel selectionHolder, ValueModel selectionIndexHolder)` Constructs a SelectionInList on the given list holder, selection holder and selection index holder.

Method Summary
`void` | `addListDataListener(ListDataListener l)` Adds a listener to the list that's notified each time a change to the data model occurs.
`void` | `clearSelection()` Clears the selection of this SelectionInList - if any.
`void` | `fireContentsChanged(int index0, int index1)` Notifies all registered ListDataListeners that the contents of one or more list elements has changed.
`void` | `fireIntervalAdded(int index0, int index1)` Notifies all registered ListDataListeners that one or more elements have been added to this SelectionInList's List/ListModel.
`void` | `fireIntervalRemoved(int index0, int index1)` Notifies all registered ListDataListeners that one or more elements have been removed from this SelectionInList's List/ListModel.
`void` | `fireSelectedContentsChanged()` Notifies all registered ListDataListeners that the contents of the selected list item - if any - has changed.
`Object` | `getElementAt(int index)` Returns the value at the specified index, `null` if the list model is `null`.
`ListDataListener[]` | `getListDataListeners()` Returns an array of all the list data listeners registered on this `SelectionInList`.
`ValueModel` | `getListHolder()` Returns the list holder.
`ListModel` | `getListModel()` Returns the contents of the list holder as `ListModel`.
`Object` | `getSelection()` Looks up and returns the current selection using the current selection index.
`ValueModel` | `getSelectionHolder()` Returns the selection holder.
`int` | `getSelectionIndex()` Returns the selection index.
`ValueModel` | `getSelectionIndexHolder()` Returns the selection index holder.
`int` | `getSize()` Returns the length of the list, `0` if the list model is `null`.
`Object` | `getValue()` Returns the current selection, `null` if the selection index does not represent a selection in the list.
`boolean` | `hasSelection()` Checks and answers if an element is selected.
`protected int` | `indexOf(Object element)` Returns the index in the list of the first occurrence of the specified element, or -1 if the list does not contain this element.
`boolean` | `isEmpty()` Checks and answers if the list is empty or `null`.
`boolean` | `isSelectionEmpty()` Checks and answers whether the selection is empty or not.
`void` | `removeListDataListener(ListDataListener l)` Removes a listener from the list that's notified each time a change to the data model occurs.
`void` | `setList(List newList)` Sets the given list as value of the list holder.
`void` | `setListHolder(ValueModel newListHolder)` Sets a new list holder.
`void` | `setListModel(ListModel newListModel)` Sets the given list model as value of the list holder.
`void` | `setSelection(Object newSelection)` Sets the first list element that equals the given new selection as new selection.
`void` | `setSelectionHolder(ValueModel newSelectionHolder)` Sets a new selection holder.
`void` | `setSelectionIndex(int newSelectionIndex)` Sets a new selection index.
`void` | `setSelectionIndexHolder(ValueModel newSelectionIndexHolder)` Sets a new selection index holder.
`void` | `setValue(Object newValue)` Sets the first list element that equals the given value as selection.

Methods inherited from class com.jgoodies.binding.value.AbstractValueModel
`addValueChangeListener, booleanValue, doubleValue, fireValueChange, fireValueChange, fireValueChange, fireValueChange, fireValueChange, fireValueChange, fireValueChange, floatValue, getString, intValue, longValue, removeValueChangeListener, setValue, setValue, setValue, setValue, setValue, toString`

Methods inherited from class com.jgoodies.binding.beans.Model
`addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, addVetoableChangeListener, equals, fireMulticastPropertyChange, fireMultiplePropertiesChanged, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, getPropertyChangeListeners, getPropertyChangeListeners, getVetoableChangeListeners, getVetoableChangeListeners, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, removeVetoableChangeListener`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### PROPERTYNAME_LIST

    public static final String PROPERTYNAME_LIST

  The name of the bound write-only list property.

  See Also:
    Constant Field Values

### PROPERTYNAME_LIST_HOLDER

    public static final String PROPERTYNAME_LIST_HOLDER

  The name of the bound read-write listHolder property.

  See Also:
    Constant Field Values

### PROPERTYNAME_SELECTION

    public static final String PROPERTYNAME_SELECTION

  The name of the bound read-write selection property.

  See Also:
    Constant Field Values

### PROPERTYNAME_SELECTION_EMPTY

    public static final String PROPERTYNAME_SELECTION_EMPTY

  The name of the bound read-only selectionEmpty property.

  See Also:
    Constant Field Values

### PROPERTYNAME_SELECTION_HOLDER

    public static final String PROPERTYNAME_SELECTION_HOLDER

  The name of the bound read-write selection holder property.

  See Also:
    Constant Field Values

### PROPERTYNAME_SELECTION_INDEX

    public static final String PROPERTYNAME_SELECTION_INDEX

  The name of the bound read-write selectionIndex property.

  See Also:
    Constant Field Values

### PROPERTYNAME_SELECTION_INDEX_HOLDER

    public static final String PROPERTYNAME_SELECTION_INDEX_HOLDER

  The name of the bound read-write selection index holder property.

  See Also:
    Constant Field Values

Constructor Detail

### SelectionInList

    public SelectionInList()

  Constructs a SelectionInList with an empty initial `ArrayListModel` using defaults for the selection holder and selection index holder.

### SelectionInList

    public SelectionInList(Object[] listItems)

  Constructs a SelectionInList on the given item array using defaults for the selection holder and selection index holder. The specified array will be converted to a List.

  Changes to the list "write through" to the array, and changes to the array contents will be reflected in the list.

  Parameters:
    `listItems` - the array of initial items
  Throws:
    `NullPointerException` - if `listItems` is `null`

### SelectionInList

    public SelectionInList(Object[] listItems,
                           ValueModel selectionHolder)

  Constructs a SelectionInList on the given item array and selection holder using a default selection index holder. The specified array will be converted to a List.

  Changes to the list "write through" to the array, and changes to the array contents will be reflected in the list.

  Parameters:
    `listItems` - the array of initial items
    `selectionHolder` - holds the selection
  Throws:
    `NullPointerException` - if `listItems` or `selectionHolder` is `null`

### SelectionInList

    public SelectionInList(Object[] listItems,
                           ValueModel selectionHolder,
                           ValueModel selectionIndexHolder)

  Constructs a SelectionInList on the given item array and selection holder using a default selection index holder. The specified array will be converted to a List.

  Changes to the list "write through" to the array, and changes to the array contents will be reflected in the list.

  Parameters:
    `listItems` - the array of initial items
    `selectionHolder` - holds the selection
    `selectionIndexHolder` - holds the selection index
  Throws:
    `NullPointerException` - if `listItems`, `selectionHolder`, or `selectionIndexHolder` is `null`

### SelectionInList

    public SelectionInList(List list)

  Constructs a SelectionInList on the given list using defaults for the selection holder and selection index holder.

  Note: Favor `ListModel` over `List` when working with the SelectionInList. Why? The SelectionInList can work with both types. What's the difference? ListModel provides all list access features required by the SelectionInList's. In addition it reports more fine grained change events, instances of `ListDataEvents`. In contrast developer often create Lists and operate on them and the ListModel may be inconvenient for these operations.

  A convenient solution for this situation is to use the `ArrayListModel` and `LinkedListModel` classes. These implement both List and ListModel, offer the standard List operations and report the fine grained ListDataEvents.

  Parameters:
    `list` - the initial list

### SelectionInList

    public SelectionInList(List list,
                           ValueModel selectionHolder)

  Constructs a SelectionInList on the given list and selection holder using a default selection index holder.

  Note: Favor `ListModel` over `List` when working with the SelectionInList. Why? The SelectionInList can work with both types. What's the difference? ListModel provides all list access features required by the SelectionInList's. In addition it reports more fine grained change events, instances of `ListDataEvents`. In contrast developer often create Lists and operate on them and the ListModel may be inconvenient for these operations.

  A convenient solution for this situation is to use the `ArrayListModel` and `LinkedListModel` classes. These implement both List and ListModel, offer the standard List operations and report the fine grained ListDataEvents.

  Parameters:
    `list` - the initial list
    `selectionHolder` - holds the selection
  Throws:
    `NullPointerException` - if `selectionHolder` is `null`

### SelectionInList

    public SelectionInList(List list,
                           ValueModel selectionHolder,
                           ValueModel selectionIndexHolder)

  Constructs a SelectionInList on the given list, selection holder, and selection index holder.

  Note: Favor `ListModel` over `List` when working with the SelectionInList. Why? The SelectionInList can work with both types. What's the difference? ListModel provides all list access features required by the SelectionInList's. In addition it reports more fine grained change events, instances of `ListDataEvents`. In contrast developer often create Lists and operate on them and the ListModel may be inconvenient for these operations.

  A convenient solution for this situation is to use the `ArrayListModel` and `LinkedListModel` classes. These implement both List and ListModel, offer the standard List operations and report the fine grained ListDataEvents.

  Parameters:
    `list` - the initial list
    `selectionHolder` - holds the selection
    `selectionIndexHolder` - holds the selection index
  Throws:
    `NullPointerException` - if `selectionHolder`, or `selectionIndexHolder` is `null`

### SelectionInList

    public SelectionInList(ListModel listModel)

  Constructs a SelectionInList on the given list model using defaults for the selection holder and selection index holder.

  Parameters:
    `listModel` - the initial list model

### SelectionInList

    public SelectionInList(ListModel listModel,
                           ValueModel selectionHolder)

  Constructs a SelectionInList on the given list model and selection holder using a default selection index holder.

  Parameters:
    `listModel` - the initial list model
    `selectionHolder` - holds the selection
  Throws:
    `NullPointerException` - if `selectionHolder` is `null`

### SelectionInList

    public SelectionInList(ListModel listModel,
                           ValueModel selectionHolder,
                           ValueModel selectionIndexHolder)

  Constructs a SelectionInList on the given list model, selection holder, and selection index holder.

  Parameters:
    `listModel` - the initial list model
    `selectionHolder` - holds the selection
    `selectionIndexHolder` - holds the selection index
  Throws:
    `NullPointerException` - if `selectionHolder`, or `selectionIndexHolder` is `null`

### SelectionInList

    public SelectionInList(ValueModel listHolder)

  Constructs a SelectionInList on the given list holder using defaults for the selection holder and selection index holder.

  Constraints: 1) The listHolder must hold instances of List or ListModel and 2) must report a value change whenever the value's identity changes. Note that many bean properties don't fire a PropertyChangeEvent if the old and new value are equal - and so would break this constraint. If you provide a ValueHolder, enable its identityCheck feature during construction. If you provide an adapted bean property from a bean that extends the JGoodies `Model` class, you can enable the identity check feature in the methods `#firePropertyChange` by setting the trailing boolean parameter to `true`.

  Parameters:
    `listHolder` - holds the list or list model
  Throws:
    `NullPointerException` - if `listHolder` is `null`

### SelectionInList

    public SelectionInList(ValueModel listHolder,
                           ValueModel selectionHolder)

  Constructs a SelectionInList on the given list holder, selection holder and selection index holder.

  Constraints: 1) The listHolder must hold instances of List or ListModel and 2) must report a value change whenever the value's identity changes. Note that many bean properties don't fire a PropertyChangeEvent if the old and new value are equal - and so would break this constraint. If you provide a ValueHolder, enable its identityCheck feature during construction. If you provide an adapted bean property from a bean that extends the JGoodies `Model` class, you can enable the identity check feature in the methods `#firePropertyChange` by setting the trailing boolean parameter to `true`.

  Parameters:
    `listHolder` - holds the list or list model
    `selectionHolder` - holds the selection
  Throws:
    `NullPointerException` - if `listHolder` or `selectionHolder` is `null`

### SelectionInList

    public SelectionInList(ValueModel listHolder,
                           ValueModel selectionHolder,
                           ValueModel selectionIndexHolder)

  Constructs a SelectionInList on the given list holder, selection holder and selection index holder.

  Constraints: 1) The listHolder must hold instances of List or ListModel and 2) must report a value change whenever the value's identity changes. Note that many bean properties don't fire a PropertyChangeEvent if the old and new value are equal - and so would break this constraint. If you provide a ValueHolder, enable its identityCheck feature during construction. If you provide an adapted bean property from a bean that extends the JGoodies `Model` class, you can enable the identity check feature in the methods `#firePropertyChange` by setting the trailing boolean parameter to `true`.

  Parameters:
    `listHolder` - holds the list or list model
    `selectionHolder` - holds the selection
    `selectionIndexHolder` - holds the selection index
  Throws:
    `NullPointerException` - if the `listModelHolder`, `selectionHolder`, or `selectionIndexHolder` is `null`
    `IllegalArgumentException` - if the listHolder is a ValueHolder that doesn't check the identity when changing its value
    `ClassCastException` - if the listModelHolder contents is neither a List nor a ListModel

Method Detail

### getSize

    public int getSize()

  Returns the length of the list, `0` if the list model is `null`.

  Specified by:
    `getSize` in interface `ListModel`
  Returns:
    the size of the list, `0` if the list model is `null`

### getElementAt

    public Object getElementAt(int index)

  Returns the value at the specified index, `null` if the list model is `null`.

  Specified by:
    `getElementAt` in interface `ListModel`
  Parameters:
    `index` - the requested index
  Returns:
    the value at `index`, `null` if the list model is `null`
  Throws:
    `NullPointerException` - if the list holder's content is null

### addListDataListener

    public void addListDataListener(ListDataListener l)

  Adds a listener to the list that's notified each time a change to the data model occurs.

  Specified by:
    `addListDataListener` in interface `ListModel`
  Parameters:
    `l` - the `ListDataListener` to be added

### removeListDataListener

    public void removeListDataListener(ListDataListener l)

  Removes a listener from the list that's notified each time a change to the data model occurs.

  Specified by:
    `removeListDataListener` in interface `ListModel`
  Parameters:
    `l` - the `ListDataListener` to be removed

### getListDataListeners

    public ListDataListener[] getListDataListeners()

  Returns an array of all the list data listeners registered on this `SelectionInList`.

  Returns:
    all of this model's `ListDataListener`s, or an empty array if no list data listeners are currently registered
  See Also:
    `addListDataListener(ListDataListener)`, `removeListDataListener(ListDataListener)`

### fireSelectedContentsChanged

    public void fireSelectedContentsChanged()

  Notifies all registered ListDataListeners that the contents of the selected list item - if any - has changed. Useful to update a presentation after editing the selection. See the tutorial's AlbumManagerModel for an example how to use this feature.

  If the list holder holds a ListModel, this SelectionInList listens to ListDataEvents fired by that ListModel, and forwards these events by invoking the associated `#fireXXX` method, which in turn notifies all registered ListDataListeners. Therefore if you fire ListDataEvents in an underlying ListModel, you don't need this method and should not use it to avoid sending duplicate ListDataEvents.

  Since:
    1.0.2
  See Also:
    `ListModel`, `ListDataListener`, `ListDataEvent`

### fireContentsChanged

    public void fireContentsChanged(int index0,
                                    int index1)

  Notifies all registered ListDataListeners that the contents of one or more list elements has changed. The changed elements are specified by the closed interval index0, index1 -- the end points are included. Note that index0 need not be less than or equal to index1.

  If the list holder holds a ListModel, this SelectionInList listens to ListDataEvents fired by that ListModel, and forwards these events by invoking the associated `#fireXXX` method, which in turn notifies all registered ListDataListeners. Therefore if you fire ListDataEvents in an underlying ListModel, you don't need this method and should not use it to avoid sending duplicate ListDataEvents.

  Parameters:
    `index0` - one end of the new interval
    `index1` - the other end of the new interval
  Since:
    1.0.2
  See Also:
    `ListModel`, `ListDataListener`, `ListDataEvent`

### fireIntervalAdded

    public void fireIntervalAdded(int index0,
                                  int index1)

  Notifies all registered ListDataListeners that one or more elements have been added to this SelectionInList's List/ListModel. The new elements are specified by a closed interval index0, index1 -- the end points are included. Note that index0 need not be less than or equal to index1.

  If the list holder holds a ListModel, this SelectionInList listens to ListDataEvents fired by that ListModel, and forwards these events by invoking the associated `#fireXXX` method, which in turn notifies all registered ListDataListeners. Therefore if you fire ListDataEvents in an underlying ListModel, you don't need this method and should not use it to avoid sending duplicate ListDataEvents.

  Parameters:
    `index0` - one end of the new interval
    `index1` - the other end of the new interval
  Since:
    1.0.2
  See Also:
    `ListModel`, `ListDataListener`, `ListDataEvent`

### fireIntervalRemoved

    public void fireIntervalRemoved(int index0,
                                    int index1)

  Notifies all registered ListDataListeners that one or more elements have been removed from this SelectionInList's List/ListModel. `index0` and `index1` are the end points of the interval that's been removed. Note that `index0` need not be less than or equal to `index1`.

  If the list holder holds a ListModel, this SelectionInList listens to ListDataEvents fired by that ListModel, and forwards these events by invoking the associated `#fireXXX` method, which in turn notifies all registered ListDataListeners. Therefore if you fire ListDataEvents in an underlying ListModel, you don't need this method and should not use it to avoid sending duplicate ListDataEvents.

  Parameters:
    `index0` - one end of the removed interval, including `index0`
    `index1` - the other end of the removed interval, including `index1`
  Since:
    1.0.2
  See Also:
    `ListModel`, `ListDataListener`, `ListDataEvent`

### isEmpty

    public boolean isEmpty()

  Checks and answers if the list is empty or `null`.

  Returns:
    true if the list is empty or `null`, false otherwise

### getListModel

    public ListModel getListModel()

  Returns the contents of the list holder as `ListModel`. If the list content is `null` an empty `ListModel` is returned; if it is a `ListModel` the content is returned; otherwise it is a `List` that will be converted to a `ListModel` using a wrapper.

  Note: This method will be removed from the SelectionInList in version 1.2. It'll be replaced by `#getList`. And the SelectionInListModel provides a `#getListModel` that just returns the ListModel holder's value.

  Returns:
    the list content as `ListModel`
  See Also:
    `setList(List)`, `setListModel(ListModel)`, `ListHolder`, `ListModelHolder`, `SelectionInList2`, `SelectionInListModel`

### setListModel

    public void setListModel(ListModel newListModel)

  Sets the given list model as value of the list holder.

  Parameters:
    `newListModel` - the list model to be set as new list content
  See Also:
    `getListModel()`, `setList(List)`

### setList

    public void setList(List newList)

  Sets the given list as value of the list holder.

  Note: Favor `ListModel` over `List` when working with the SelectionInList. Why? The SelectionInList can work with both types. What's the difference? ListModel provides all list access features required by the SelectionInList's. In addition it reports more fine grained change events, instances of `ListDataEvents`. In contrast developer often create Lists and operate on them and the ListModel may be inconvenient for these operations.

  A convenient solution for this situation is to use the `ArrayListModel` and `LinkedListModel` classes. These implement both List and ListModel, offer the standard List operations and report the fine grained ListDataEvents.

  Parameters:
    `newList` - the list to be set as new list content
  See Also:
    `setListModel(ListModel)`

### getSelection

    public Object getSelection()

  Looks up and returns the current selection using the current selection index. Returns `null` if no object is selected or if the list has no elements.

  Returns:
    the current selection, `null` if none is selected

### setSelection

    public void setSelection(Object newSelection)

  Sets the first list element that equals the given new selection as new selection. Does nothing if the list is empty.

  Parameters:
    `newSelection` - the object to be set as new selection

### hasSelection

    public boolean hasSelection()

  Checks and answers if an element is selected.

  Returns:
    true if an element is selected, false otherwise

### isSelectionEmpty

    public boolean isSelectionEmpty()

  Checks and answers whether the selection is empty or not. Unlike #hasSelection, the underlying property #selectionEmpty for this method is bound. I.e. you can observe this property using a PropertyChangeListener to update UI state.

  Returns:
    true if nothing is selected, false if there's a selection
  See Also:
    `clearSelection()`, `hasSelection()`

### clearSelection

    public void clearSelection()

  Clears the selection of this SelectionInList - if any.

### getSelectionIndex

    public int getSelectionIndex()

  Returns the selection index.

  Returns:
    the selection index
  Throws:
    `NullPointerException` - if the selection index holder has a null Object set

### setSelectionIndex

    public void setSelectionIndex(int newSelectionIndex)

  Sets a new selection index. Does nothing if it is the same as before.

  Parameters:
    `newSelectionIndex` - the selection index to be set
  Throws:
    `IndexOutOfBoundsException` - if the new selection index is outside the bounds of the list

### getListHolder

    public ValueModel getListHolder()

  Returns the list holder.

  Returns:
    the list holder

### setListHolder

    public void setListHolder(ValueModel newListHolder)

  Sets a new list holder. Does nothing if old and new holder are equal. Removes the list change handler from the old holder and adds it to the new one. In case the list holder contents is a ListModel, the list data change handler is updated too by invoking `#updateListDataRegistration` in the same way as done in the list change handler.

  TODO: Check and verify whether the list data registration update can be performed in one step after the listHolder has been changed - instead of remove the list data change handler, then changing the listHolder, and finally adding the list data change handler.

  Parameters:
    `newListHolder` - the list holder to be set
  Throws:
    `NullPointerException` - if the new list holder is `null`
    `IllegalArgumentException` - if the listHolder is a ValueHolder that doesn't check the identity when changing its value

### getSelectionHolder

    public ValueModel getSelectionHolder()

  Returns the selection holder.

  Returns:
    the selection holder

### setSelectionHolder

    public void setSelectionHolder(ValueModel newSelectionHolder)

  Sets a new selection holder. Does nothing if the new is the same as before. The selection remains unchanged and is still driven by the selection index holder. It's just that future index changes will update the new selection holder and that future selection holder changes affect the selection index.

  Parameters:
    `newSelectionHolder` - the selection holder to set
  Throws:
    `NullPointerException` - if the new selection holder is null

### getSelectionIndexHolder

    public ValueModel getSelectionIndexHolder()

  Returns the selection index holder.

  Returns:
    the selection index holder

### setSelectionIndexHolder

    public void setSelectionIndexHolder(ValueModel newSelectionIndexHolder)

  Sets a new selection index holder. Does nothing if the new is the same as before.

  Parameters:
    `newSelectionIndexHolder` - the selection index holder to set
  Throws:
    `NullPointerException` - if the new selection index holder is null
    `IllegalArgumentException` - if the value of the new selection index holder is null

### getValue

    public Object getValue()

  Returns the current selection, `null` if the selection index does not represent a selection in the list.

  Specified by:
    `getValue` in interface `ValueModel`
  Returns:
    the selected element - if any

### setValue

    public void setValue(Object newValue)

  Sets the first list element that equals the given value as selection.

  Specified by:
    `setValue` in interface `ValueModel`
  Parameters:
    `newValue` - the new value to set

### indexOf

    protected int indexOf(Object element)

  Returns the index in the list of the first occurrence of the specified element, or -1 if the list does not contain this element.

  Parameters:
    `element` - the element to search for
  Returns:
    the index in the list of the first occurrence of the given element, or -1 if the list does not contain this element.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002-2006 JGoodies Karsten Lentzsch. All Rights Reserved.