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 TextComponentConnector

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

    public final class TextComponentConnector

extends Object

Connects a String typed ValueModel and a JTextField or JTextArea. At construction time the text component content is updated with the subject's contents.

This connector has been designed for text components that display a plain String. In case of a JEditorPane, the binding may require more information then the plain String, for example styles. Since this is outside the scope of this connector, the public constructors prevent a construction for general JTextComponents. If you want to establish a one-way binding for a display JEditorPane, use a custom listener instead.

This class provides limited support for handling subject value modifications while updating the subject. If a Document change initiates a subject value update, the subject will be observed and a property change fired by the subject will be handled - if any. In most cases, the subject will notify about a change to the text that was just set by this connector. However, in some cases the subject may decide to modify this text, for example to ensure upper case characters. Since at this moment, this adapter's Document is still write-locked, the Document update is performed later using `SwingUtilities#invokeLater`.

Note: Such an update will typically change the Caret position in JTextField's and other JTextComponent's that are synchronized using this class. Hence, the subject value modifications can be used with commit-on-focus-lost text components, but typically not with a commit-on-key-typed component. For the latter case, you may consider using a custom `DocumentFilter`.

Constraints: The ValueModel must be of type `String`.

Examples:

     ValueModel lastNameModel = new PropertyAdapter(customer, "lastName", true);
     JTextField lastNameField = new JTextField();
     TextComponentConnector.connect(lastNameModel, lastNameField);

     ValueModel codeModel = new PropertyAdapter(shipment, "code", true);
     JTextField codeField = new JTextField();
     TextComponentConnector connector =
         new TextComponentConnector(codeModel, codeField);
     connector.updateTextComponent();

Since:
  1.2
Version:
  $Revision: 1.17 $
Author:
  Karsten Lentzsch
See Also:
  `ValueModel`, `Document`, `PlainDocument`

Constructor Summary
`TextComponentConnector(ValueModel subject, JTextArea textArea)` Constructs a TextComponentConnector that connects the specified String-typed subject ValueModel with the given text area.
`TextComponentConnector(ValueModel subject, JTextField textField)` Constructs a TextComponentConnector that connects the specified String-typed subject ValueModel with the given text field.

Method Summary
`static void` | `connect(ValueModel subject, JTextArea textArea)` Establishes a synchronization between the specified String-typed subject ValueModel and the given text area.
`static void` | `connect(ValueModel subject, JTextField textField)` Establishes a synchronization between the specified String-typed subject ValueModel and the given text field.
`void` | `release()` Removes the internal listeners from the subject, text component, and text component's document.
`void` | `updateSubject()` Reads the current text from the document and sets it as new value of the subject.
`void` | `updateTextComponent()` Reads the current value from the model and updates the text component.

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

Constructor Detail

### TextComponentConnector

    public TextComponentConnector(ValueModel subject,
                                  JTextArea textArea)

  Constructs a TextComponentConnector that connects the specified String-typed subject ValueModel with the given text area.

  In case you don't need the TextComponentConnector instance, you better use one of the static `#connect` methods. This constructor may confuse developers, if you just use the side effects performed in the constructor; this is because it is quite unconventional to instantiate an object that you never use.

  Parameters:
    `subject` - the underlying String typed ValueModel
    `textArea` - the JTextArea to be synchronized with the ValueModel
  Throws:
    `NullPointerException` - if the subject or text area is `null`

### TextComponentConnector

    public TextComponentConnector(ValueModel subject,
                                  JTextField textField)

  Constructs a TextComponentConnector that connects the specified String-typed subject ValueModel with the given text field.

  In case you don't need the TextComponentConnector instance, you better use one of the static `#connect` methods. This constructor may confuse developers, if you just use the side effects performed in the constructor; this is because it is quite unconventional to instantiate an object that you never use.

  Parameters:
    `subject` - the underlying String typed ValueModel
    `textField` - the JTextField to be synchronized with the ValueModel
  Throws:
    `NullPointerException` - if the subject or text field is `null`

Method Detail

### connect

    public static void connect(ValueModel subject,
                               JTextArea textArea)

  Establishes a synchronization between the specified String-typed subject ValueModel and the given text area. Does not synchronize now.

  Parameters:
    `subject` - the underlying String typed ValueModel
    `textArea` - the JTextArea to be synchronized with the ValueModel
  Throws:
    `NullPointerException` - if the subject or text area is `null`

### connect

    public static void connect(ValueModel subject,
                               JTextField textField)

  Establishes a synchronization between the specified String-typed subject ValueModel and the given text field. Does not synchronize now.

  Parameters:
    `subject` - the underlying String typed ValueModel
    `textField` - the JTextField to be synchronized with the ValueModel
  Throws:
    `NullPointerException` - if the subject or text area is `null`

### updateSubject

    public void updateSubject()

  Reads the current text from the document and sets it as new value of the subject.

### updateTextComponent

    public void updateTextComponent()

  Reads the current value from the model and updates the text component.

### release

    public void release()

  Removes the internal listeners from the subject, text component, and text component's document. This connector must not be used after calling `#release`.

  To avoid memory leaks it is recommended to invoke this method, if the ValueModel lives much longer than the text component. Instead of releasing a text connector, you typically make the ValueModel obsolete by releasing the PresentationModel or BeanAdapter that has created the ValueModel.

  As an alternative you may use ValueModels that in turn use event listener lists implemented using `WeakReference`.

  See Also:
    `PresentationModel.release()`, `BeanAdapter.release()`, `WeakReference`

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.