|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.jgoodies.binding.beans.Model
com.jgoodies.binding.list.ListHolder
com.jgoodies.binding.extras.SelectionInList2
public final class SelectionInList2
Represents a selection in a List. Provides bound bean properties for the list, the selection, the selection index, and the selection empty state. 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.
Note: This class is not yet part of the binary Binding library; it comes with the Binding distributions as an extra. The API is work in progress and may change without notice; this class may even be completely removed from future distributions. If you want to use this class, you may consider copying it into your codebase.
The SelectionInList2 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 SelectionInList2 with other ValueModels; for example you can use the SelectionInList2's selection holder as bean channel for a PresentationModel. See the Binding tutorial classes for examples on how to connect a SelectionInList2 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 SelectionInList2 with a JComboBox or JTable,
you can convert the SelectionInList2 to the associated component model
interfaces using the adapter classes
ComboBoxAdapter
and AbstractTableAdapter
respectively.
These classes are part of the Binding library too.
Unlike the older SelectionInList, the SelectionInList2 supports only
List
s as content of its List holder. The SelectionInListModel
supports ListModel
s as content of its ListModel holder.
The SelectionInList2 and SelectionInListModel differ in how precise
they can fire events about changes to the content and structure of
the underlying List or ListModel content. The SelectionInList2
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.
The SelectionInListModel reports the same PropertyChangeEvent.
But fine grained changes in the ListModel will be forwarded
as fine grained changes in the content, added and removed elements.
If the List or ListModel content doesn't change at all, or if it always changes completely, there's no differences between the SelectionInListModel and the SelectionInList2. 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 the benefit of fine grained ListDataEvents 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 work with the SelectionInListModel as soon as the ListModel gets populated. If at a later time more elements are added to the ListModel, the SelectionInListModel 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
.
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.
This class inherits 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
, 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.
SelectionInListModel
,
ValueModel
,
List
,
ListModel
,
ComboBoxAdapter
,
AbstractTableAdapter
,
ExtendedPropertyChangeSupport
,
Model
,
ValueHolder
,
Serialized FormField Summary | |
---|---|
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.list.ListHolder |
---|
list, PROPERTYNAME_LIST, PROPERTYNAME_LIST_HOLDER |
Constructor Summary | |
---|---|
SelectionInList2()
Constructs a SelectionInList2 with an empty initial ArrayList using defaults for the selection holder and selection index holder. |
|
SelectionInList2(List list)
Constructs a SelectionInList2 on the given List using defaults for the selection holder and selection index holder. |
|
SelectionInList2(List list,
ValueModel selectionHolder)
Constructs a SelectionInList2 on the given List and selection holder using a default selection index holder. |
|
SelectionInList2(List list,
ValueModel selectionHolder,
ValueModel selectionIndexHolder)
Constructs a SelectionInList2 on the given List, selection holder, and selection index holder. |
|
SelectionInList2(Object[] listItems)
Constructs a SelectionInList2 on the given item array using defaults for the selection holder and selection index holder. |
|
SelectionInList2(Object[] listItems,
ValueModel selectionHolder)
Constructs a SelectionInList2 on the given item array and selection holder using a default selection index holder. |
|
SelectionInList2(Object[] listItems,
ValueModel selectionHolder,
ValueModel selectionIndexHolder)
Constructs a SelectionInList2 on the given item array and selection holder using a default selection index holder. |
|
SelectionInList2(ValueModel listHolder)
Constructs a SelectionInList2 on the given list holder using defaults for the selection holder and selection index holder. |
|
SelectionInList2(ValueModel listHolder,
ValueModel selectionHolder)
Constructs a SelectionInList2 on the given list holder, selection holder and selection index holder. |
|
SelectionInList2(ValueModel listHolder,
ValueModel selectionHolder,
ValueModel selectionIndexHolder)
Constructs a SelectionInList2 on the given list holder, selection holder and selection index holder. |
Method Summary | |
---|---|
void |
clearSelection()
Clears the selection of this SelectionInList2 - if any. |
void |
fireSelectedContentsChanged()
Notifies all registered ListDataListeners that the contents of the selected list item - if any - has changed. |
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. |
boolean |
hasSelection()
Checks and answers if an element is selected. |
boolean |
isSelectionEmpty()
Checks and answers whether the selection is empty or not. |
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. |
protected void |
updateList(List oldList,
List newList)
Updates the selection index and fires a property change for the list and a contents change event. |
Methods inherited from class com.jgoodies.binding.list.ListHolder |
---|
addListDataListener, fireContentsChanged, fireIntervalAdded, fireIntervalRemoved, fireListChanged, getElementAt, getList, getListDataListeners, getListHolder, getSize, getSize, isEmpty, removeListDataListener, setList, setListHolder |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final String PROPERTYNAME_SELECTION
public static final String PROPERTYNAME_SELECTION_EMPTY
public static final String PROPERTYNAME_SELECTION_HOLDER
public static final String PROPERTYNAME_SELECTION_INDEX
public static final String PROPERTYNAME_SELECTION_INDEX_HOLDER
Constructor Detail |
---|
public SelectionInList2()
public SelectionInList2(Object[] listItems)
Changes to the list "write through" to the array, and changes to the array contents will be reflected in the list.
listItems
- the array of initial items
NullPointerException
- if listItems
is null
public SelectionInList2(Object[] listItems, ValueModel selectionHolder)
Changes to the list "write through" to the array, and changes to the array contents will be reflected in the list.
listItems
- the array of initial itemsselectionHolder
- holds the selection
NullPointerException
- if listItems
or
selectionHolder
is null
public SelectionInList2(Object[] listItems, ValueModel selectionHolder, ValueModel selectionIndexHolder)
Changes to the list "write through" to the array, and changes to the array contents will be reflected in the list.
listItems
- the array of initial itemsselectionHolder
- holds the selectionselectionIndexHolder
- holds the selection index
NullPointerException
- if listItems
,
selectionHolder
, or selectionIndexHolder
is null
public SelectionInList2(List list)
list
- the initial listpublic SelectionInList2(List list, ValueModel selectionHolder)
list
- the initial listselectionHolder
- holds the selection
NullPointerException
- if selectionHolder
is null
public SelectionInList2(List list, ValueModel selectionHolder, ValueModel selectionIndexHolder)
list
- the initial listselectionHolder
- holds the selectionselectionIndexHolder
- holds the selection index
NullPointerException
- if selectionHolder
,
or selectionIndexHolder
is null
public SelectionInList2(ValueModel listHolder)
listHolder
- holds the list
NullPointerException
- if listHolder
is null
public SelectionInList2(ValueModel listHolder, ValueModel selectionHolder)
listHolder
- holds the listselectionHolder
- holds the selection
NullPointerException
- if listHolder
or selectionHolder
is null
public SelectionInList2(ValueModel listHolder, ValueModel selectionHolder, ValueModel selectionIndexHolder)
listHolder
- holds the listselectionHolder
- holds the selectionselectionIndexHolder
- holds the selection index
NullPointerException
- if listHolder
,
selectionHolder
, or selectionIndexHolder
is null
IllegalArgumentException
- if the listHolder contents
is neither a List nor a ListModelMethod Detail |
---|
public Object getSelection()
null
if
no object is selected or if the list has no elements.
null
if none is selectedpublic void setSelection(Object newSelection)
newSelection
- the object to be set as new selectionpublic ValueModel getSelectionHolder()
public void setSelectionHolder(ValueModel newSelectionHolder)
newSelectionHolder
- the selection holder to set
NullPointerException
- if the new selection holder is nullpublic int getSelectionIndex()
NullPointerException
- if the selection index holder
has a null Object setpublic void setSelectionIndex(int newSelectionIndex)
newSelectionIndex
- the selection index to be set
IndexOutOfBoundsException
- if the new selection index
is outside the bounds of the listpublic ValueModel getSelectionIndexHolder()
public void setSelectionIndexHolder(ValueModel newSelectionIndexHolder)
newSelectionIndexHolder
- the selection index holder to set
NullPointerException
- if the new selection index holder is null
IllegalArgumentException
- if the value of the new selection index
holder is nullpublic boolean hasSelection()
public boolean isSelectionEmpty()
clearSelection()
,
hasSelection()
public void clearSelection()
public void fireSelectedContentsChanged()
If the list holder holds a ListModel, this SelectionInList2 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.
ListModel
,
ListDataListener
,
ListDataEvent
protected void updateList(List oldList, List newList)
updateList
in class ListHolder
oldList
- the old List contentnewList
- the new List content
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |