Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.jgoodies.binding.adapter
Class Bindings

    java.lang.Object
      com.jgoodies.binding.adapter.Bindings

    public final class Bindings

extends Object

Consists only of static methods that bind Swing components to ValueModels. This is one of two helper classes that assist you in establishing a binding: 1) this Bindings class binds components that have been created before; it wraps ValueModels with the adapters from package `com.jgoodies.binding.adapter`. 2) the BasicComponentFactory creates Swing components that are then bound using this Bindings class.

If you have an existing factory that vends Swing components, you can use this Bindings class to bind them to ValueModels. If you don't have such a factory, you can use the BasicComponentFactory or a custom subclass to create and bind Swing components.

The binding process for JCheckBox, JRadioButton, and other AbstractButtons retains the former enablement state. Before the new (adapting) model is set, the enablement is requested from the model, not the button. This enablement is set after the new model has been set.

TODO: Consider adding binding methods for JProgressBar, JSlider, JSpinner, and JTabbedPane.

TODO: Consider adding connection methods for pairs of bean properties. In addition to the PropertyConnector's `connect` method, this could add boolean operators such as: not, and, or, nor.

Version:
  $Revision: 1.41 $
Author:
  Karsten Lentzsch
See Also:
  `ValueModel`, `BasicComponentFactory`

Method Summary
`static void` | `addComponentPropertyHandler(JComponent component, ValueModel valueModel)` If the given model is a ComponentValueModel, a component property handler is registered with this model.
`static void` | `bind(AbstractButton toggleButton, ValueModel valueModel)` Binds a JToggleButton to the given ValueModel in check box style.
`static void` | `bind(AbstractButton toggleButton, ValueModel model, Object choice)` Binds a JToggleButton to the given ValueModel in radio button style.
`static void` | `bind(AbstractButton toggleButton, ValueModel valueModel, Object selectedValue, Object deselectedValue)` Binds a JToggleButton to the given ValueModel in check box style.
`static void` | `bind(JColorChooser colorChooser, ValueModel valueModel)` Binds a JColorChooser to the given Color-typed ValueModel.
`static void` | `bind(JColorChooser colorChooser, ValueModel valueModel, Color defaultColor)` Binds a JColorChooser to the given Color-typed ValueModel.
`static void` | `bind(JComboBox comboBox, ComboBoxModel model)` Binds a non-editable JComboBox to the given ComboBoxModel.
`static void` | `bind(JComboBox comboBox, ComboBoxModel model, String nullText)` Binds a JComboBox to the given ComboBoxModel using the specified text to represent `null`.
`static
`<E> void`
` | `bind(JComboBox comboBox, SelectionInList<E> selectionInList)` Binds a non-editable JComboBox to the given SelectionInList using the SelectionInList's ListModel as list data provider and the SelectionInList's selection index holder for the combo box model's selected item.
`static
`<E> void`
` | `bind(JComboBox comboBox, SelectionInList<E> selectionInList, String nullText)` Binds a non-editable JComboBox to the given SelectionInList using the SelectionInList's ListModel as list data provider and the SelectionInList's selection index holder for the combo box model's selected item.
`static void` | `bind(JComponent component, String propertyName, ValueModel valueModel)` Binds the specified property of the given JComponent to the specified ValueModel.
`static void` | `bind(JFormattedTextField textField, ValueModel valueModel)` Binds the given JFormattedTextField to the specified ValueModel.
`static void` | `bind(JLabel label, ValueModel valueModel)` Binds the given JLabel to the specified ValueModel.
`static
`<E> void`
` | `bind(JList list, SelectionInList<E> selectionInList)` Binds a JList to the given SelectionInList using the SelectionInList's ListModel as list data provider and the SelectionInList's selection index holder for the selection model.
`static void` | `bind(JTable table, ListModel listModel, ListSelectionModel listSelectionModel)` Sets the given ListModel as the table's underlying row-data provider, and sets the given ListSelectionModel in the table.
`static void` | `bind(JTable table, SelectionInList selectionInList)` Sets the given SelectionInList as the table's row-data provider, and binds the SelectionInList's selection index to the table's selection.
`static void` | `bind(JTextArea textArea, ValueModel valueModel)` Binds a text area to the given ValueModel.
`static void` | `bind(JTextArea textArea, ValueModel valueModel, boolean commitOnFocusLost)` Binds a text area to the given ValueModel.
`static void` | `bind(JTextField textField, ValueModel valueModel)` Bind a text fields or password field to the given ValueModel.
`static void` | `bind(JTextField textField, ValueModel valueModel, boolean commitOnFocusLost)` Binds a text field or password field to the given ValueModel.
`static void` | `commitImmediately()` Commits a pending edit - if any.
`static boolean` | `flushImmediately()` Flushes a pending edit in the focused text component - if any.
`static boolean` | `isFocusOwnerBuffering()` Checks and answers whether the focus owner is a component that buffers a pending edit.
`static void` | `removeComponentPropertyHandler(JComponent component)` If the given component holds a ComponentValueModel and a ComponentPropertyHandler in its client properties, the handler is removed as listener from the model, and the model and handler are removed from the client properties.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### bind

    public static void bind(AbstractButton toggleButton,
                            ValueModel valueModel)

  Binds a JToggleButton to the given ValueModel in check box style. The bound button is selected if and only if the model's value equals `Boolean.TRUE`. Retains the enablement state.

  The value model is converted to the required interface ToggleButtonModel using a ToggleButtonAdapter.

  Parameters:
    `toggleButton` - the toggle button to be bound
    `valueModel` - the model that provides a Boolean value
  Throws:
    `NullPointerException` - if the checkBox or valueModel is `null`

### bind

    public static void bind(AbstractButton toggleButton,
                            ValueModel valueModel,
                            Object selectedValue,
                            Object deselectedValue)

  Binds a JToggleButton to the given ValueModel in check box style. The bound button is selected if and only if the model's value equals `Boolean.TRUE`. Retains the enablement state.

  The value model is converted to the required interface ToggleButtonModel using a ToggleButtonAdapter.

  Parameters:
    `toggleButton` - the toggle button to be bound
    `valueModel` - the model that provides a Boolean value
    `selectedValue` - the model's value if the button is selected
    `deselectedValue` - the model's value if the button is deselected
  Throws:
    `NullPointerException` - if the checkBox or valueModel is `null`

### bind

    public static void bind(AbstractButton toggleButton,
                            ValueModel model,
                            Object choice)

  Binds a JToggleButton to the given ValueModel in radio button style. The bound button is selected if and only if the model's value equals the specified choice value. Retains the enablement state.

  The model is converted to the required interface ToggleButtonModel using a RadioButtonAdapter.

  Parameters:
    `toggleButton` - the button to be bound to the given model
    `model` - the model that provides the current choice
    `choice` - this button's value
  Throws:
    `NullPointerException` - if the valueModel is `null`

### bind

    public static void bind(JColorChooser colorChooser,
                            ValueModel valueModel)

  Binds a JColorChooser to the given Color-typed ValueModel. The ValueModel must be of type Color and must allow read-access to its value.

  Also, it is strongly recommended (though not required) that the underlying ValueModel provides only non-null values. This is so because the ColorSelectionModel behavior is undefined for `null` values and it may have unpredictable results. To avoid these problems, you may bind the ColorChooser with a default color using `bind(JColorChooser, ValueModel, Color)`.

  Since the color chooser is considered a container, not a single component, it is not synchronized with the valueModel's `ComponentValueModel` properties - if any.

  Note: There's a bug in Java 1.4.2, Java 5 and Java 6 that affects this binding. The BasicColorChooserUI doesn't listen to changes in the selection model, and so the preview panel won't update if the selected color changes. As a workaround you can use `BasicComponentFactory.createColorChooser(ValueModel)`, or you could use a Look&Feel that fixes the bug mentioned above.

  Parameters:
    `colorChooser` - the color chooser to be bound
    `valueModel` - the model that provides non-`null` Color values.
  Throws:
    `NullPointerException` - if the color chooser or value model is `null`
  Since:
    1.0.3
  See Also:
    `bind(JColorChooser, ValueModel, Color)`

### bind

    public static void bind(JColorChooser colorChooser,
                            ValueModel valueModel,
                            Color defaultColor)

  Binds a JColorChooser to the given Color-typed ValueModel. The ValueModel must be of type Color and must allow read-access to its value. The default color will be used if the valueModel returns `null`.

  Since the color chooser is considered a container, not a single component, it is not synchronized with the valueModel's `ComponentValueModel` properties - if any.

  Note: There's a bug in Java 1.4.2, Java 5 and Java 6 that affects this binding. The BasicColorChooserUI doesn't listen to changes in the selection model, and so the preview panel won't update if the selected color changes. As a workaround you can use `BasicComponentFactory.createColorChooser(ValueModel)`, or you could use a Look&Feel that fixes the bug mentioned above.

  Parameters:
    `colorChooser` - the color chooser to be bound
    `valueModel` - the model that provides non-`null` Color values.
    `defaultColor` - the color used if the valueModel returns null
  Throws:
    `NullPointerException` - if the color chooser, value model, or default color is `null`
  Since:
    1.1

### bind

    public static void bind(JComboBox comboBox,
                            ComboBoxModel model)

  Binds a non-editable JComboBox to the given ComboBoxModel.

  Parameters:
    `comboBox` - the combo box to be bound
    `model` - provides the data and selection
  Throws:
    `NullPointerException` - if the combo box or model is `null`
  Since:
    2.7
  See Also:
    `ComboBoxAdapter`

### bind

    public static void bind(JComboBox comboBox,
                            ComboBoxModel model,
                            String nullText)

  Binds a JComboBox to the given ComboBoxModel using the specified text to represent `null`.

  Parameters:
    `comboBox` - the combo box to be bound
    `model` - provides the data and selection
    `nullText` - the text used to represent `null`
  Throws:
    `NullPointerException` - if the combo box or model is `null`
  Since:
    2.7

### bind

    public static <E> void bind(JComboBox comboBox,
                                SelectionInList<E> selectionInList)

  Binds a non-editable JComboBox to the given SelectionInList using the SelectionInList's ListModel as list data provider and the SelectionInList's selection index holder for the combo box model's selected item.

  There are a couple of other possibilities to bind a JComboBox. See the constructors and the class comment of the `ComboBoxAdapter`.

  Since version 2.0 the combo's enabled and visible state is synchronized with the selectionInList's selection holder, if it's a `ComponentValueModel`.

  Type Parameters:
    `E` - the type of the combo box items
  Parameters:
    `comboBox` - the combo box to be bound
    `selectionInList` - provides the list and selection; if the selection holder is a ComponentValueModel, it is synchronized with the comboBox properties visible and enabled
  Throws:
    `NullPointerException` - if the combo box or the selectionInList is `null`
  Since:
    1.0.1
  See Also:
    `ComboBoxAdapter`

### bind

    public static <E> void bind(JComboBox comboBox,
                                SelectionInList<E> selectionInList,
                                String nullText)

  Binds a non-editable JComboBox to the given SelectionInList using the SelectionInList's ListModel as list data provider and the SelectionInList's selection index holder for the combo box model's selected item.

  There are a couple of other possibilities to bind a JComboBox. See the constructors and the class comment of the `ComboBoxAdapter`.

  Since version 2.0 the combo's enabled and visible state is synchronized with the selectionInList's selection holder, if it's a `ComponentValueModel`.

  Type Parameters:
    `E` - the type of the combo box items
  Parameters:
    `comboBox` - the combo box to be bound
    `selectionInList` - provides the list and selection; if the selection holder is a ComponentValueModel, it is synchronized with the comboBox properties visible and enabled
    `nullText` - the text used to represent `null`
  Throws:
    `NullPointerException` - if `combo box`, `selectionInList`, or `nullText` is `null`
  Since:
    2.3
  See Also:
    `ComboBoxAdapter`

### bind

    public static void bind(JFormattedTextField textField,
                            ValueModel valueModel)

  Binds the given JFormattedTextField to the specified ValueModel. Synchronized the ValueModel's value with the text field's value by means of a PropertyConnector.

  Parameters:
    `textField` - the JFormattedTextField that is to be bound
    `valueModel` - the model that provides the value
  Throws:
    `NullPointerException` - if the text field or valueModel is `null`

### bind

    public static void bind(JLabel label,
                            ValueModel valueModel)

  Binds the given JLabel to the specified ValueModel.

  Parameters:
    `label` - a label that shall be bound to the given value model
    `valueModel` - the model that provides the value
  Throws:
    `NullPointerException` - if the label or valueModel is `null`

### bind

    public static <E> void bind(JList list,
                                SelectionInList<E> selectionInList)

  Binds a JList to the given SelectionInList using the SelectionInList's ListModel as list data provider and the SelectionInList's selection index holder for the selection model.

  Since version 2.0 the list's enabled and visible state is synchronized with the selectionInList's selection holder, if it's a `ComponentValueModel`.

  Type Parameters:
    `E` - the type of the list items
  Parameters:
    `list` - the list to be bound
    `selectionInList` - provides the list and selection; if the selection holder is a ComponentValueModel, it is synchronized with the list properties visible and enabled
  Throws:
    `NullPointerException` - if the list or the selectionInList is `null`

### bind

    public static void bind(JTable table,
                            SelectionInList selectionInList)

  Sets the given SelectionInList as the table's row-data provider, and binds the SelectionInList's selection index to the table's selection. As a precondition, the table's TableModel must implement `ListModelBindable`.

  Since version 2.9 this binding supports JTable sorting. If a JTable has a RowSorter, this method sets a `TableRowSorterListSelectionModel` as `table`'s selection model that is then synchronized with the selection index holder of the given `selectionInList`.

  Parameters:
    `table` - the table to be bound
    `selectionInList` - a ListModel plus selection index
  Throws:
    `NullPointerException` - if `selectionInList` is `null`
    `IllegalArgumentException` - if the table's model does not implement ListModelBindable
  Since:
    2.2

### bind

    public static void bind(JTable table,
                            ListModel listModel,
                            ListSelectionModel listSelectionModel)

  Sets the given ListModel as the table's underlying row-data provider, and sets the given ListSelectionModel in the table. As a precondition, the table's TableModel must implement `ListModelBindable`.

  Since version 2.9 this binding supports JTable sorting. If a JTable has a RowSorter, this method sets a `TableRowSorterListSelectionModel` as `table`'s selection model that is then synchronized with the given `listSelectionModel`.

  Parameters:
    `table` - the table to be bound
    `listModel` - provides the table model's row data
    `listSelectionModel` - manages the list selection
  Throws:
    `IllegalArgumentException` - if the table's model does not implement ListModelBindable
    `NullPointerException` - if `listSelectionModel` is `null`
  Since:
    2.2

### bind

    public static void bind(JTextArea textArea,
                            ValueModel valueModel)

  Binds a text area to the given ValueModel. The model is updated on every character typed.

  TODO: Consider changing the semantics to commit on focus lost. This would be consistent with the text component vending factory methods in the BasicComponentFactory that have no boolean parameter.

  Parameters:
    `textArea` - the text area to be bound to the value model
    `valueModel` - the model that provides the text value
  Throws:
    `NullPointerException` - if the text component or valueModel is `null`

### bind

    public static void bind(JTextArea textArea,
                            ValueModel valueModel,
                            boolean commitOnFocusLost)

  Binds a text area to the given ValueModel. The model can be updated on focus lost or on every character typed. The DocumentAdapter used in this binding doesn't filter newlines.

  Parameters:
    `textArea` - the text area to be bound to the value model
    `valueModel` - the model that provides the text value
    `commitOnFocusLost` - true to commit text changes on focus lost, false to commit text changes on every character typed
  Throws:
    `NullPointerException` - if the text component or valueModel is `null`

### bind

    public static void bind(JTextField textField,
                            ValueModel valueModel)

  Bind a text fields or password field to the given ValueModel. The model is updated on every character typed.

  Security Note: If you use this method to bind a JPasswordField, the field's password will be requested as Strings from the field and will be held as String by the given ValueModel. These password String could potentially be observed in a security fraud. For stronger security it is recommended to request a character array from the JPasswordField and clear the array after use by setting each character to zero. Method `JPasswordField.getPassword()` return's the field's password as a character array.

  TODO: Consider changing the semantics to commit on focus lost. This would be consistent with the text component vending factory methods in the BasicComponentFactory that have no boolean parameter.

  Parameters:
    `textField` - the text field to be bound to the value model
    `valueModel` - the model that provides the text value
  Throws:
    `NullPointerException` - if the text component or valueModel is `null`
  See Also:
    `JPasswordField.getPassword()`

### bind

    public static void bind(JTextField textField,
                            ValueModel valueModel,
                            boolean commitOnFocusLost)

  Binds a text field or password field to the given ValueModel. The model can be updated on focus lost or on every character typed.

  Security Note: If you use this method to bind a JPasswordField, the field's password will be requested as Strings from the field and will be held as String by the given ValueModel. These password String could potentially be observed in a security fraud. For stronger security it is recommended to request a character array from the JPasswordField and clear the array after use by setting each character to zero. Method `JPasswordField.getPassword()` return's the field's password as a character array.

  Parameters:
    `textField` - the text field to be bound to the value model
    `valueModel` - the model that provides the text value
    `commitOnFocusLost` - true to commit text changes on focus lost, false to commit text changes on every character typed
  Throws:
    `NullPointerException` - if the text component or valueModel is `null`
  See Also:
    `JPasswordField.getPassword()`

### bind

    public static void bind(JComponent component,
                            String propertyName,
                            ValueModel valueModel)

  Binds the specified property of the given JComponent to the specified ValueModel. Synchronizes the ValueModel's value with the component's property by means of a PropertyConnector.

  Parameters:
    `component` - the JComponent that is to be bound
    `propertyName` - the name of the property to be bound
    `valueModel` - the model that provides the value
  Throws:
    `NullPointerException` - if the component or value model or property name is `null`
    `IllegalArgumentException` - if `propertyName` is blank or whitespace
  Since:
    1.2

### addComponentPropertyHandler

    public static void addComponentPropertyHandler(JComponent component,
                                                   ValueModel valueModel)

  If the given model is a ComponentValueModel, a component property handler is registered with this model. This handler updates the component state if the ComponentValueModel indicates a change in one of its properties, for example: visible, enabled, and editable.

  Also the ComponentValueModel and the component handler are stored as client properties with the component. This way they can be removed later using `#removeComponentPropertyHandler`.

  Parameters:
    `component` - the component where the handler is registered
    `valueModel` - the model to observe
  Since:
    1.1
  See Also:
    `removeComponentPropertyHandler(JComponent)`, `ComponentValueModel`

### removeComponentPropertyHandler

    public static void removeComponentPropertyHandler(JComponent component)

  If the given component holds a ComponentValueModel and a ComponentPropertyHandler in its client properties, the handler is removed as listener from the model, and the model and handler are removed from the client properties.

  Parameters:
    `component` - the component to remove the listener from
  Since:
    1.1
  See Also:
    `addComponentPropertyHandler(JComponent, ValueModel)`, `ComponentValueModel`

### commitImmediately

    public static void commitImmediately()

  Commits a pending edit - if any. Useful to ensure that edited values in bound text components that commit on focus-lost are committed before an operation is performed that uses the value to be committed after a focus lost.

  For example, before you save a form, a value that has been edited shall be committed, so the validation can check whether the save is allowed or not.

  Since:
    1.2

### flushImmediately

    public static boolean flushImmediately()

  Flushes a pending edit in the focused text component - if any. Useful to revert edited values in bound text components that commit on focus-lost. This operation can be performed on an escape key event like the Cancel action in the JFormattedTextField.

  Returns whether an edit has been reset. Useful to decide whether a key event shall be consumed or not.

  Returns:
    `true` if a pending edit has been reset, `false` if the focused component isn't buffering or doesn't buffer at all
  Since:
    2.0.1
  See Also:
    `isFocusOwnerBuffering()`

### isFocusOwnerBuffering

    public static boolean isFocusOwnerBuffering()

  Checks and answers whether the focus owner is a component that buffers a pending edit. Useful to enable or disable a text component Action that resets the edited value.

  See also the JFormattedTextField's internal `CancelAction`.

  Returns:
    `true` if the focus owner is a JTextComponent that commits on focus-lost and is buffering
  Since:
    2.0.1
  See Also:
    `flushImmediately()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002-2013 JGoodies Software GmbH. All Rights Reserved.