Class JComboBoxBinding<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.JComboBoxBinding<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 toJComboBox
)
public final class JComboBoxBinding<E,SS,TS> extends AutoBinding<SS,java.util.List<E>,TS,java.util.List>
Binds aList
of objects to act as the items of aJComboBox
. Each object in the sourceList
is an item in theJComboBox
. Instances ofJComboBoxBinding
are obtained by calling one of thecreateJComboBoxBinding
methods in theSwingBindings
class.Here is an example of creating a binding from a
List
ofCountry
objects to aJComboBox
:// create the country list List
countries = createCountryList(); // create the binding from List to JComboBox JComboBoxBinding cb = SwingBindings.createJComboBoxBinding(READ, countries, jComboBox); // realize the binding cb.bind(); If the
List
is an instance ofObservableList
, then changes to theList
contents (such as adding, removing or replacing an object) are reflected in theJComboBox
. Important: Changing the contents of a non-observableList
while it is participating in aJComboBoxBinding
is unsupported, resulting in undefined behavior and possible exceptions.JComboBoxBinding
requires extra clarification on the operation of therefresh
andsave
methods and the meaning of the update strategy. The target property of aJComboBoxBinding
is not the targetJComboBox
property provided in the constructor, but rather a private synthetic property representing theList
of objects to show in the targetJComboBox
. This synthetic property is readable/writeable only when theJComboBoxBinding
is bound and the targetJComboBox
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 targetJComboBox
). These methods do not, therefore, have anything to do with refreshing values in theJComboBox
. Likewise, the update strategy, which simply controls whenrefresh
andsave
are automatically called, also has nothing to do with refreshing values in theJComboBox
.Note: At the current time, the
READ_WRITE
update strategy is not useful forJComboBoxBinding
. To prevent unwanted confusion,READ_WRITE
is translated toREAD
byJComboBoxBinding's
constructor.JComboBoxBinding
works by installing a custom model on the targetJComboBox
, as appropriate, to represent the sourceList
. The model is installed on a targetJComboBox
with the first succesful call torefresh
with thatJComboBox
as the target. Subsequent calls torefresh
update the elements in this already-installed model. The model is uninstalled from a targetJComboBox
when either theJComboBoxBinding
is unbound or when the targetJComboBox
property changes to no longer represent thatJComboBox
. Note: When the model is uninstalled from aJComboBox
, it is replaced with aDefaultComboBoxModel
, in order to leave theJComboBox
functional.Some of the above is easier to understand with an example. Let's consider a
JComboBoxBinding
(binding
), with update strategyREAD
, between a property representing aList
(listP
) and a property representing aJComboBox
(jComboBoxP
).listP
andjComboBoxP
both start off readable, referring to anon-null
List
andnon-null
JComboBox
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 targetJComboBox
, representing list of objects2 listP
changes to a newList
- refresh()
is called
- model is updated with new list of objects3 jComboBoxP
changes to a newJComboBox
- model is uninstalled from old JComboBox
4 explicit call to binding.refresh()
- model is installed on target JComboBox
, 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 JComboBox
Notice that in step 3, when the value of the
JComboBox
property changed, the newJComboBox
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
).In addition to binding the items of a
JComboBox
, it is possible to bind to the selected item of aJComboBox
. See the list of interesting swing properties in the package summary for more details.
-
-
Nested Class Summary
-
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
JComboBoxBinding(AutoBinding.UpdateStrategy strategy, SS sourceObject, Property<SS,java.util.List<E>> sourceListProperty, TS targetObject, Property<TS,? extends javax.swing.JComboBox> targetJComboBoxProperty, java.lang.String name)
Constructs an instance ofJComboBoxBinding
.
-
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.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
-
JComboBoxBinding
protected JComboBoxBinding(AutoBinding.UpdateStrategy strategy, SS sourceObject, Property<SS,java.util.List<E>> sourceListProperty, TS targetObject, Property<TS,? extends javax.swing.JComboBox> targetJComboBoxProperty, java.lang.String name)
Constructs an instance ofJComboBoxBinding
.- Parameters:
strategy
- the update strategysourceObject
- the source objectsourceListProperty
- a property on the source object that resolves to theList
of elementstargetObject
- the target objecttargetJComboBoxProperty
- a property on the target object that resolves to aJComboBox
name
- a name for theJComboBoxBinding
- 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()
-
-