com.jgoodies.binding.adapter
Class TextComponentConnector

java.lang.Object
  extended by 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.12 $
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()
           
 
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()

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


Copyright © 2002-2008 JGoodies Karsten Lentzsch. All Rights Reserved.