Prev Class | Next Class | Frames | No Frames |
Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
java.lang.Object
com.jgoodies.binding.beans.Model
com.jgoodies.binding.list.IndirectListModel<E>
com.jgoodies.binding.list.SelectionInList<E>
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 firing
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
.
Important 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 (selected) 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.
The SelectionInList is partially defined for Lists and ListModels
that contain null
. Setting the selection to null
on a SelectionInList that contains null
won't set the selection index
to the index of the first null
element. For details see the
setSelection(Object)
JavaDocs. This is because the current
implementation interprets a null
selection as unspecified,
which maps better to a cleared selection than to a concrete selection index.
Anyway, as long as you work with the selection index and selection index
holder, such a SelectionInList will work fine. This is the case if you bind
a SelectionInList to a JList or JTable. Binding such a SelectionInList
to a JComboBox won't synchronize the selection index if null
is selected.
Constraints: The list holder holds instances of List
or ListModel
, the selection holder values of type E
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 underlying ValueModel must fire
a PropertyChangeEvent.
ValueModel
, List
, ListModel
, ComboBoxAdapter
, AbstractTableAdapter
, ExtendedPropertyChangeSupport
, Model
, ValueHolder
Field Summary | |
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
Fields inherited from class com.jgoodies.binding.list.IndirectListModel<E> | |
PROPERTYNAME_LIST , PROPERTYNAME_LIST_HOLDER |
Constructor Summary | |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
|
Method Summary | |
protected @Override |
|
void |
|
void |
|
void |
|
E |
|
ValueModel |
|
int |
|
ValueModel |
|
E |
|
boolean |
|
boolean |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
@Override |
|
protected @Override |
|
Methods inherited from class com.jgoodies.binding.list.IndirectListModel<E> | |
addListDataListener , createListDataChangeHandler , fireContentsChanged , fireIntervalAdded , fireIntervalRemoved , fireListChanged , getElementAt , getList , getListDataListeners , getListHolder , getListModel , getSize , getSize , isEmpty , release , removeListDataListener , setList , setListHolder , setListModel , updateList |
public static final String PROPERTYNAME_SELECTION
The name of the bound read-write selection property.
public static final String PROPERTYNAME_SELECTION_EMPTY
The name of the bound read-only selectionEmpty property.
public static final String PROPERTYNAME_SELECTION_HOLDER
The name of the bound read-write selection holder property.
public static final String PROPERTYNAME_SELECTION_INDEX
The name of the bound read-write selectionIndex property.
public static final String PROPERTYNAME_SELECTION_INDEX_HOLDER
The name of the bound read-write selection index holder property.
public static final String PROPERTYNAME_VALUE
The name of the bound read-write value property.
public SelectionInList()
Constructs a SelectionInList with an empty initialArrayListModel
using defaults for the selection holder and selection index holder.
public SelectionInList(E[] 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
public SelectionInList(E[] 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 itemsselectionHolder
- holds the selection
public SelectionInList(E[] 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 itemsselectionHolder
- holds the selectionselectionIndexHolder
- holds the selection index
public SelectionInList(Listlist)
Constructs a SelectionInList on the given list using defaults for the selection holder and selection index holder. Note: FavorListModel
overList
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 ofListDataEvents
. 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 theArrayListModel
andLinkedListModel
classes. These implement both List and ListModel, offer the standard List operations and report the fine grained ListDataEvents.
- Parameters:
list
- the initial list
public SelectionInList(Listlist, ValueModel selectionHolder)
Constructs a SelectionInList on the given list and selection holder using a default selection index holder. Note: FavorListModel
overList
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 ofListDataEvents
. 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 theArrayListModel
andLinkedListModel
classes. These implement both List and ListModel, offer the standard List operations and report the fine grained ListDataEvents.
- Parameters:
list
- the initial listselectionHolder
- holds the selection
public SelectionInList(Listlist, ValueModel selectionHolder, ValueModel selectionIndexHolder)
Constructs a SelectionInList on the given list, selection holder, and selection index holder. Note: FavorListModel
overList
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 ofListDataEvents
. 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 theArrayListModel
andLinkedListModel
classes. These implement both List and ListModel, offer the standard List operations and report the fine grained ListDataEvents.
- Parameters:
list
- the initial listselectionHolder
- holds the selectionselectionIndexHolder
- holds the selection index
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
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 modelselectionHolder
- holds the selection
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 modelselectionHolder
- holds the selectionselectionIndexHolder
- holds the selection index
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 JGoodiesModel
class, you can enable the identity check feature in the methods#firePropertyChange
by setting the trailing boolean parameter totrue
.
- Parameters:
listHolder
- holds the list or list model
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 JGoodiesModel
class, you can enable the identity check feature in the methods#firePropertyChange
by setting the trailing boolean parameter totrue
.
- Parameters:
listHolder
- holds the list or list modelselectionHolder
- holds the selection
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 JGoodiesModel
class, you can enable the identity check feature in the methods#firePropertyChange
by setting the trailing boolean parameter totrue
.
- Parameters:
listHolder
- holds the list or list modelselectionHolder
- holds the selectionselectionIndexHolder
- holds the selection index
protected @Override ListDataListener createListDataChangeHandler()
Creates and returns the ListDataListener used to observe changes in the underlying ListModel. It is re-registered in#updateListModel
.
- Returns:
- the ListDataListener that handles changes in the underlying ListModel
public void addValueChangeListener(PropertyChangeListener l)
Registers the given PropertyChangeListener with this model. The listener will be notified if the value has changed. The PropertyChangeEvents delivered to the listener have the name set to "value". In other words, the listeners won't get notified when a PropertyChangeEvent is fired that has a null object as the name to indicate an arbitrary set of the event source's properties have changed. In the rare case, where you want to notify a PropertyChangeListener even with PropertyChangeEvents that have no property name set, you can register the listener with #addPropertyChangeListener, not #addValueChangeListener.
- Specified by:
- addValueChangeListener in interface ValueModel
- Parameters:
l
- the listener to add
- See Also:
ValueModel
public void clearSelection()
Clears the selection of this SelectionInList - if any.
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
public E getSelection()
Looks up and returns the current selection using the current selection index. Returnsnull
if no object is selected or if the list has no elements.
- Returns:
- the current selection,
null
if none is selected
public ValueModel getSelectionHolder()
Returns the selection holder.
- Returns:
- the selection holder
public int getSelectionIndex()
Returns the selection index.
- Returns:
- the selection index
public ValueModel getSelectionIndexHolder()
Returns the selection index holder.
- Returns:
- the selection index holder
public E 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
public boolean hasSelection()
Checks and answers if an element is selected.
- Returns:
- true if an element is selected, false otherwise
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()
public void removeValueChangeListener(PropertyChangeListener l)
Removes the given PropertyChangeListener from the model.
- Specified by:
- removeValueChangeListener in interface ValueModel
- Parameters:
l
- the listener to remove
public void setSelection(E newSelection)
Sets the selection index to the index of the first list element that equalsnewSelection
. IfnewSelection
isnull
, it is interpreted as unspecified and the selection index is set to -1, and this SelectionInList has no selection. Does nothing if the list is empty ornull
.
- Parameters:
newSelection
- the object to be set as new selection, ornull
to set the selection index to -1
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
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
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
public void setValue(Object newValue)
Sets the selection index to the index of the first list element that equalsnewValue
. IfnewValue
isnull
, it is interpreted as unspecified and the selection index is set to -1, and this SelectionInList has no selection. Does nothing if the list is empty ornull
.
- Specified by:
- setValue in interface ValueModel
- Parameters:
newValue
- the object to be set as new selection, ornull
to set the selection index to -1
public @Override void release()
Removes the internal listeners from the list holder, selection holder, selection index holder. If the current list is a ListModel, the internal ListDataListener is removed from the list model. This SelectionInList must not be used after calling#release
. To avoid memory leaks it is recommended to invoke this method, if the list holder, selection holder, or selection index holder live much longer than this SelectionInList. Instead of releasing the SelectionInList, you typically make the list holder, selection holder, and selection index holder obsolete by releasing the PresentationModel or BeanAdapter that has created them before. As an alternative you may use ValueModels that in turn use event listener lists implemented usingWeakReference
. Basically this release method performs the reverse operation performed during the SelectionInList construction.
- Since:
- 1.2
- See Also:
PresentationModel.release()
,BeanAdapter.release()
,java.lang.ref.WeakReference
protected @Override void updateList(Object oldList, int oldSize, Object newList)
Removes the list data change handler from the old list in case it is aListModel
and adds it to new one in case it is aListModel
. It then fires a property change for the list and a contents change event for the list content. Finally it tries to restore the previous selection - if any. Since version 1.1 the selection will be restored after the list content change has been indicated. This is because some listeners may clear the selection in a side-effect. For example a JTable that is bound to this SelectionInList via an AbstractTableAdapter and a SingleSelectionAdapter will clear the selection if the new list has a size other than the old list.
- Parameters:
oldList
- the old list contentoldSize
- the size of the old List contentnewList
- the new list content
- See Also:
javax.swing.JTable.tableChanged(javax.swing.event.TableModelEvent)