Class JListBinding<E,SS,TS>
- Type Parameters:
E
- the type of elements in the sourceList
SS
- the type of source object (on which the source property resolves toList
)TS
- the type of target object (on which the target property resolves toJList
)
List
of objects to act as the elements of a JList
.
Each object in the source List
provides one element in the JList
.
By setting a DetailBinding
you can specify the property to use to derive each list element from its
corresponding object in the source List
. The default DetailBinding
uses
the objects directly. Instances of JListBinding
are obtained by
calling one of the createJListBinding
methods in the SwingBindings
class.
Here is an example of creating a binding from a List
of Person
objects to a JList
:
// create the person list
List people = createPersonList();
// create the binding from List to JList
JListBinding lb = SwingBindings.createJListBinding(READ, people, jList);
// define the property to be used to derive list elements
ELProperty fullNameP = ELProperty.create("${firstName} ${lastName}");
// add the detail binding
lb.setDetailBinding(fullNameP);
// realize the binding
lb.bind();
The JList
target of a JListBinding
acts as a live view of
the objects in the source List
, regardless of the update strategy (the
meaning of the update strategy is clarified later
in this document). JListBinding
listens to the property specified for
any DetailBinding
, for all objects in the List
, and updates
the values displayed in the JList
in response to change. If the
List
is an instance of ObservableList
, then changes to the
List
contents (such as adding, removing or replacing an object) are
also reflected in the JList
. Important: Changing the contents
of a non-observable List
while it is participating in a
JListBinding
is unsupported, resulting in undefined behavior and
possible exceptions.
JListBinding
requires
extra clarification on the operation of the
refresh
and save
methods and the meaning of the update
strategy. The target property of a JListBinding
is not the
target JList
property provided in the constructor, but rather a
private synthetic property representing the List
of objects to show
in the target JList
. This synthetic property is readable/writeable
only when the JListBinding
is bound and the target JList
property is readable with a non-null
value.
It is this private synthetic property on which the refresh
and
save
methods operate; meaning that these methods simply cause syncing
between the value of the source List
property and the value of the
synthetic target property (representing the List
to be shown in the
target JList
). These methods do not, therefore, have anything to do
with refreshing values in the JList
. Likewise, the update
strategy, which simply controls when refresh
and save
are
automatically called, also has nothing to do with refreshing values
in the JList
.
Note: At the current time, the READ_WRITE
update strategy
is not useful for JListBinding
. To prevent unwanted confusion,
READ_WRITE
is translated to READ
by JListBinding's
constructor.
JListBinding
works by installing a custom model on the target
JList
, as appropriate, to represent the source List
. The
model is installed on a target JList
with the first succesful call
to refresh
with that JList
as the target. Subsequent calls
to refresh
update the elements in this already-installed model.
The model is uninstalled from a target JList
when either the
JListBinding
is unbound or when the target JList
property
changes to no longer represent that JList
. Note: When the model is
uninstalled from a JList
, it is replaced with a DefaultListModel
,
in order to leave the JList
functional.
Some of the above is easier to understand with an example. Let's consider
a JListBinding
(binding
), with update strategy
READ
, between a property representing a List
(listP
)
and a property representing a JList
(jListP
). listP
and jListP
both start off readable, referring to a non-null
List
and non-null
JList
respectively. Let's look at
what happens for each of a sequence of events:
Sequence | Event | Result |
---|---|---|
1 | explicit call to binding.bind() |
- synthetic target property becomes readable/writeable
- refresh() is called
- model is installed on target JList , representing list of objects
|
2 | listP changes to a new List |
- refresh() is called
- model is updated with new list of objects |
3 | jListP changes to a new JList |
- model is uninstalled from old JList
|
4 | explicit call to binding.refresh() |
- model is installed on target JList , representing list of objects
|
5 | listP changes to a new List |
- refresh() is called
- model is updated with new list of objects |
6 | explicit call to binding.unbind() |
- model is uninstalled from target JList
|
Notice that in step 3, when the value
of the JList
property changed, the new JList
did not
automatically get the model with the elements applied to it. A change to the
target value should not cause an AutoBinding
to sync the target from
the source. Step 4 forces a sync by explicitly calling refresh
.
Alternatively, it could be caused by any other action that results
in a refresh
(for example, the source property changing value, or an
explicit call to unbind
followed by bind
).
DetailBindings
are managed by the JList
. They are not
to be explicitly bound, unbound, added to a BindingGroup
, or accessed
in a way that is not allowed for a managed binding.
In addition to binding the elements of a JList
, it is possible to
bind to the selection of a JList
. When binding to the selection of a JList
backed by a JListBinding
, the selection is always in terms of elements
from the source List
, regardless of any DetailBinding
specified.
See the list of
interesting swing properties in the package summary for more details.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionfinal class
DetailBinding
represents a binding between a property of the elements in theJListBinding's
sourceList
, and the values shown in theJList
.Nested classes/interfaces inherited from class org.jdesktop.beansbinding.AutoBinding
AutoBinding.UpdateStrategy
Nested classes/interfaces inherited from class org.jdesktop.beansbinding.Binding
Binding.SyncFailure, Binding.SyncFailureType, Binding.ValueResult<V>
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprotected void
bindImpl()
Called byBinding.bind()
to allow subclasses to initiate binding.Returns theDetailBinding
for thisJListBinding
.setDetailBinding
(Property<E, ?> detailProperty) Creates aDetailBinding
and sets it as theDetailBinding
for thisJListBinding
.setDetailBinding
(Property<E, ?> detailProperty, String name) Creates a namedDetailBinding
and sets it as theDetailBinding
for thisJListBinding
.protected void
Called byBinding.unbind()
to allow subclasses to uninitiate binding.Methods inherited from class org.jdesktop.beansbinding.AutoBinding
getUpdateStrategy, paramString, sourceChangedImpl, targetChangedImpl
Methods inherited from class org.jdesktop.beansbinding.Binding
addBindingListener, addPropertyChangeListener, addPropertyChangeListener, bind, bindUnmanaged, firePropertyChange, getBindingListeners, getConverter, getName, getPropertyChangeListeners, getPropertyChangeListeners, getSourceNullValue, getSourceObject, getSourceProperty, getSourceUnreadableValue, getSourceValueForTarget, getTargetNullValue, getTargetObject, getTargetProperty, getTargetValueForSource, getValidator, isBound, isManaged, isSourceUnreadableValueSet, notifySynced, notifySyncFailed, refresh, refreshAndNotify, refreshAndNotifyUnmanaged, refreshUnmanaged, removeBindingListener, removePropertyChangeListener, removePropertyChangeListener, save, saveAndNotify, saveAndNotifyUnmanaged, saveUnmanaged, setConverter, setManaged, setSourceNullValue, setSourceObject, setSourceObjectUnmanaged, setSourceProperty, setSourceUnreadableValue, setTargetNullValue, setTargetObject, setTargetObjectUnmanaged, setTargetProperty, setValidator, throwIfBound, throwIfManaged, throwIfUnbound, toString, unbind, unbindUnmanaged, unsetSourceUnreadableValue
-
Constructor Details
-
JListBinding
protected JListBinding(AutoBinding.UpdateStrategy strategy, SS sourceObject, Property<SS, List<E>> sourceListProperty, TS targetObject, Property<TS, ? extends JList> targetJListProperty, String name) Constructs an instance ofJListBinding
.- Parameters:
strategy
- the update strategysourceObject
- the source objectsourceListProperty
- a property on the source object that resolves to theList
of elementstargetObject
- the target objecttargetJListProperty
- a property on the target object that resolves to aJList
name
- a name for theJListBinding
- Throws:
IllegalArgumentException
- if the source property or target property isnull
-
-
Method Details
-
bindImpl
protected void bindImpl()Description copied from class:Binding
Called byBinding.bind()
to allow subclasses to initiate binding. Subclasses typically need not installPropertyStateListeners
on the source property and target property as they will be notified by calls toBinding.sourceChangedImpl(org.jdesktop.beansbinding.PropertyStateEvent)
andBinding.targetChangedImpl(org.jdesktop.beansbinding.PropertyStateEvent)
when the source and target properties change respectively. -
unbindImpl
protected void unbindImpl()Description copied from class:Binding
Called byBinding.unbind()
to allow subclasses to uninitiate binding.- Overrides:
unbindImpl
in classAutoBinding<SS,
List<E>, TS, List> - See Also:
-
setDetailBinding
Creates aDetailBinding
and sets it as theDetailBinding
for thisJListBinding
. ADetailBinding
specifies the property of the objects in the sourceList
to be used as the elements of theJList
. If thedetailProperty
parameter isnull
, theDetailBinding
specifies that the objects themselves be used.- Parameters:
detailProperty
- the property with which to derive each list value from its corresponding object in the sourceList
- Returns:
- the
DetailBinding
-
setDetailBinding
public JListBinding<E,SS, setDetailBindingTS>.DetailBinding (Property<E, ?> detailProperty, String name) Creates a namedDetailBinding
and sets it as theDetailBinding
for thisJListBinding
. ADetailBinding
specifies the property of the objects in the sourceList
to be used as the elements of theJList
. If thedetailProperty
parameter isnull
, theDetailBinding
specifies that the objects themselves be used.- Parameters:
detailProperty
- the property with which to derive each list value from its corresponding object in the sourceList
- Returns:
- the
DetailBinding
-
getDetailBinding
Returns theDetailBinding
for thisJListBinding
. ADetailBinding
specifies the property of the sourceList
elements to be used as the elements of theJList
.- Returns:
- the
DetailBinding
- See Also:
-