|
||||||||||
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.value.AbstractValueModel
com.jgoodies.binding.list.SelectionInList
public final class SelectionInList
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.
ValueModel
,
List
,
ListModel
,
ComboBoxAdapter
,
AbstractTableAdapter
,
ExtendedPropertyChangeSupport
,
Model
,
ValueHolder
,
Serialized FormField 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 java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final String PROPERTYNAME_LIST
public static final String PROPERTYNAME_LIST_HOLDER
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 SelectionInList()
ArrayListModel
using defaults for the selection holder
and selection index holder.
public SelectionInList(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 SelectionInList(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 SelectionInList(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 SelectionInList(List list)
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.
list
- the initial listpublic SelectionInList(List list, ValueModel selectionHolder)
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.
list
- the initial listselectionHolder
- holds the selection
NullPointerException
- if selectionHolder
is null
public SelectionInList(List list, ValueModel selectionHolder, ValueModel selectionIndexHolder)
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.
list
- the initial listselectionHolder
- holds the selectionselectionIndexHolder
- holds the selection index
NullPointerException
- if selectionHolder
,
or selectionIndexHolder
is null
public SelectionInList(ListModel listModel)
listModel
- the initial list modelpublic SelectionInList(ListModel listModel, ValueModel selectionHolder)
listModel
- the initial list modelselectionHolder
- holds the selection
NullPointerException
- if selectionHolder
is null
public SelectionInList(ListModel listModel, ValueModel selectionHolder, ValueModel selectionIndexHolder)
listModel
- the initial list modelselectionHolder
- holds the selectionselectionIndexHolder
- holds the selection index
NullPointerException
- if selectionHolder
,
or selectionIndexHolder
is null
public SelectionInList(ValueModel listHolder)
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
.
listHolder
- holds the list or list model
NullPointerException
- if listHolder
is null
public SelectionInList(ValueModel listHolder, ValueModel selectionHolder)
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
.
listHolder
- holds the list or list modelselectionHolder
- holds the selection
NullPointerException
- if listHolder
or selectionHolder
is null
public SelectionInList(ValueModel listHolder, ValueModel selectionHolder, ValueModel selectionIndexHolder)
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
.
listHolder
- holds the list or list modelselectionHolder
- holds the selectionselectionIndexHolder
- holds the selection index
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 ListModelMethod Detail |
---|
public int getSize()
0
if the list model
is null
.
getSize
in interface ListModel
0
if the list model is
null
public Object getElementAt(int index)
null
if the list model is null
.
getElementAt
in interface ListModel
index
- the requested index
index
, null
if the list model is null
NullPointerException
- if the list holder's content is nullpublic void addListDataListener(ListDataListener l)
addListDataListener
in interface ListModel
l
- the ListDataListener
to be addedpublic void removeListDataListener(ListDataListener l)
removeListDataListener
in interface ListModel
l
- the ListDataListener
to be removedpublic ListDataListener[] getListDataListeners()
SelectionInList
.
ListDataListener
s,
or an empty array if no list data listeners
are currently registeredaddListDataListener(ListDataListener)
,
removeListDataListener(ListDataListener)
public void fireSelectedContentsChanged()
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.
ListModel
,
ListDataListener
,
ListDataEvent
public void fireContentsChanged(int index0, int 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.
index0
- one end of the new intervalindex1
- the other end of the new intervalListModel
,
ListDataListener
,
ListDataEvent
public void fireIntervalAdded(int index0, int 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.
index0
- one end of the new intervalindex1
- the other end of the new intervalListModel
,
ListDataListener
,
ListDataEvent
public void fireIntervalRemoved(int index0, int index1)
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.
index0
- one end of the removed interval,
including index0
index1
- the other end of the removed interval,
including index1
ListModel
,
ListDataListener
,
ListDataEvent
public boolean isEmpty()
null
.
null
, false otherwisepublic ListModel getListModel()
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.
ListModel
setList(List)
,
setListModel(ListModel)
,
ListHolder
,
ListModelHolder
,
SelectionInList2
,
SelectionInListModel
public void setListModel(ListModel newListModel)
newListModel
- the list model to be set as new list contentgetListModel()
,
setList(List)
public void setList(List newList)
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.
newList
- the list to be set as new list contentsetListModel(ListModel)
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 boolean hasSelection()
public boolean isSelectionEmpty()
clearSelection()
,
hasSelection()
public void clearSelection()
public 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 getListHolder()
public void setListHolder(ValueModel newListHolder)
#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.
newListHolder
- the list holder to be set
NullPointerException
- if the new list holder is null
IllegalArgumentException
- if the listHolder is a ValueHolder
that doesn't check the identity when changing its valuepublic ValueModel getSelectionHolder()
public void setSelectionHolder(ValueModel newSelectionHolder)
newSelectionHolder
- the selection holder to set
NullPointerException
- if the new selection holder is nullpublic 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 Object getValue()
null
if the selection index
does not represent a selection in the list.
getValue
in interface ValueModel
public void setValue(Object newValue)
setValue
in interface ValueModel
newValue
- the new value to setprotected int indexOf(Object element)
element
- the element to search for
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |