Class JListBinding<E,SS,TS>
- java.lang.Object
-
- org.jdesktop.beansbinding.Binding<SS,SV,TS,TV>
-
- org.jdesktop.beansbinding.AutoBinding<SS,java.util.List<E>,TS,java.util.List>
-
- org.jdesktop.swingbinding.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
)
public final class JListBinding<E,SS,TS> extends AutoBinding<SS,java.util.List<E>,TS,java.util.List>
Binds aList
of objects to act as the elements of aJList
. Each object in the sourceList
provides one element in theJList
. By setting aDetailBinding
you can specify the property to use to derive each list element from its corresponding object in the sourceList
. The defaultDetailBinding
uses the objects directly. Instances ofJListBinding
are obtained by calling one of thecreateJListBinding
methods in theSwingBindings
class.Here is an example of creating a binding from a
List
ofPerson
objects to aJList
:// 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 aJListBinding
acts as a live view of the objects in the sourceList
, regardless of the update strategy (the meaning of the update strategy is clarified later in this document).JListBinding
listens to the property specified for anyDetailBinding
, for all objects in theList
, and updates the values displayed in theJList
in response to change. If theList
is an instance ofObservableList
, then changes to theList
contents (such as adding, removing or replacing an object) are also reflected in theJList
. Important: Changing the contents of a non-observableList
while it is participating in aJListBinding
is unsupported, resulting in undefined behavior and possible exceptions.JListBinding
requires extra clarification on the operation of therefresh
andsave
methods and the meaning of the update strategy. The target property of aJListBinding
is not the targetJList
property provided in the constructor, but rather a private synthetic property representing theList
of objects to show in the targetJList
. This synthetic property is readable/writeable only when theJListBinding
is bound and the targetJList
property is readable with anon-null
value.It is this private synthetic property on which the
refresh
andsave
methods operate; meaning that these methods simply cause syncing between the value of the sourceList
property and the value of the synthetic target property (representing theList
to be shown in the targetJList
). These methods do not, therefore, have anything to do with refreshing values in theJList
. Likewise, the update strategy, which simply controls whenrefresh
andsave
are automatically called, also has nothing to do with refreshing values in theJList
.Note: At the current time, the
READ_WRITE
update strategy is not useful forJListBinding
. To prevent unwanted confusion,READ_WRITE
is translated toREAD
byJListBinding's
constructor.JListBinding
works by installing a custom model on the targetJList
, as appropriate, to represent the sourceList
. The model is installed on a targetJList
with the first succesful call torefresh
with thatJList
as the target. Subsequent calls torefresh
update the elements in this already-installed model. The model is uninstalled from a targetJList
when either theJListBinding
is unbound or when the targetJList
property changes to no longer represent thatJList
. Note: When the model is uninstalled from aJList
, it is replaced with aDefaultListModel
, in order to leave theJList
functional.Some of the above is easier to understand with an example. Let's consider a
JListBinding
(binding
), with update strategyREAD
, between a property representing aList
(listP
) and a property representing aJList
(jListP
).listP
andjListP
both start off readable, referring to anon-null
List
andnon-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 targetJList
, representing list of objects2 listP
changes to a newList
- refresh()
is called
- model is updated with new list of objects3 jListP
changes to a newJList
- model is uninstalled from old JList
4 explicit call to binding.refresh()
- model is installed on target JList
, representing list of objects5 listP
changes to a newList
- refresh()
is called
- model is updated with new list of objects6 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 newJList
did not automatically get the model with the elements applied to it. A change to the target value should not cause anAutoBinding
to sync the target from the source. Step 4 forces a sync by explicitly callingrefresh
. Alternatively, it could be caused by any other action that results in arefresh
(for example, the source property changing value, or an explicit call tounbind
followed bybind
).DetailBindings
are managed by theJList
. They are not to be explicitly bound, unbound, added to aBindingGroup
, 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 aJList
. When binding to the selection of aJList
backed by aJListBinding
, the selection is always in terms of elements from the sourceList
, regardless of anyDetailBinding
specified. See the list of interesting swing properties in the package summary for more details.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description class
JListBinding.DetailBinding
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 Modifier Constructor Description protected
JListBinding(AutoBinding.UpdateStrategy strategy, SS sourceObject, Property<SS,java.util.List<E>> sourceListProperty, TS targetObject, Property<TS,? extends javax.swing.JList> targetJListProperty, java.lang.String name)
Constructs an instance ofJListBinding
.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description protected void
bindImpl()
Called byBinding.bind()
to allow subclasses to initiate binding.JListBinding.DetailBinding
getDetailBinding()
Returns theDetailBinding
for thisJListBinding
.JListBinding.DetailBinding
setDetailBinding(Property<E,?> detailProperty)
Creates aDetailBinding
and sets it as theDetailBinding
for thisJListBinding
.JListBinding.DetailBinding
setDetailBinding(Property<E,?> detailProperty, java.lang.String name)
Creates a namedDetailBinding
and sets it as theDetailBinding
for thisJListBinding
.protected void
unbindImpl()
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 Detail
-
JListBinding
protected JListBinding(AutoBinding.UpdateStrategy strategy, SS sourceObject, Property<SS,java.util.List<E>> sourceListProperty, TS targetObject, Property<TS,? extends javax.swing.JList> targetJListProperty, java.lang.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:
java.lang.IllegalArgumentException
- if the source property or target property isnull
-
-
Method Detail
-
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.- Overrides:
bindImpl
in classAutoBinding<SS,java.util.List<E>,TS,java.util.List>
- See Also:
Binding.unbindImpl()
-
unbindImpl
protected void unbindImpl()
Description copied from class:Binding
Called byBinding.unbind()
to allow subclasses to uninitiate binding.- Overrides:
unbindImpl
in classAutoBinding<SS,java.util.List<E>,TS,java.util.List>
- See Also:
Binding.bindImpl()
-
setDetailBinding
public JListBinding.DetailBinding setDetailBinding(Property<E,?> detailProperty)
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.DetailBinding setDetailBinding(Property<E,?> detailProperty, java.lang.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
public JListBinding.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:
setDetailBinding(Property, String)
-
-