net.wotonomy.ui.swing
Class TextAssociation

java.lang.Object
  net.wotonomy.control.EODelayedObserver
      net.wotonomy.ui.EOAssociation
          net.wotonomy.ui.swing.TextAssociation

All Implemented Interfaces:

java.awt.event.ActionListener, java.awt.event.FocusListener, java.util.EventListener, java.util.Observer, javax.swing.event.DocumentListener, net.wotonomy.control.EOObserving

public class TextAssociation
extends net.wotonomy.ui.EOAssociation
implements java.awt.event.FocusListener, java.awt.event.ActionListener, javax.swing.event.DocumentListener

TextAssociation binds JTextComponents and other objects with getText() and setText() methods to a display group. Note that JLabels are supported with both the Text and Icon aspects. Bindings are:

• value: a property convertable to/from a string
• editable: a boolean property that determines whether the user can edit the text in the field
• enabled: a boolean property that determines whether the user can select the text in the field
• visible: a boolean property that determines whether the field is visible
• label: a boolean property that determines whether field should appear as a read-only, selectable label
• icon: a property that returns a Swing icon, for use with JLabels and other components with setIcon() methods. If bound to a static string, the string will be used to load an image resource from the selected object's class.

Version:

$Revision: 904 $

Author:

michael@mpowers.net, $Author: cgruber $

Field Summary

protected boolean	activeUpdate
protected static java.lang.String	EMPTY_STRING
protected java.text.Format	format
protected boolean	hasDocument
protected boolean	isListening
protected java.lang.Class	lastKnownType
protected boolean	needsUpdate
protected boolean	wasNull

Fields inherited from class net.wotonomy.ui.EOAssociation

ActionAspect, ArgumentAspect, aspectToGroup, aspectToKey, AttributeAspectSignature, AttributeToManyAspectSignature, AttributeToOneAspectSignature, AttributeToOneToManyAspectSignature, BoldAspect, ChildrenAspect, control, DestinationAspect, EditableAspect, EnabledAspect, IconAspect, IsLeafAspect, ItalicAspect, LabelAspect, NullAspectSignature, ObjectsAspect, ParentAspect, SelectedObjectAspect, SelectedTitleAspect, SourceAspect, TitlesAspect, ToManyAspectSignature, ToOneAspectSignature, ToOneToManyAspectSignature, URLAspect, ValueAspect, VisibleAspect

Fields inherited from class net.wotonomy.control.EODelayedObserver

ObserverNumberOfPriorities, ObserverPriorityFifth, ObserverPriorityFirst, ObserverPriorityFourth, ObserverPriorityImmediate, ObserverPriorityLater, ObserverPrioritySecond, ObserverPrioritySixth, ObserverPriorityThird

Constructor Summary

TextAssociation(java.lang.Object anObject)
Constructor specifying the object to be controlled by this association.

Method Summary

void	actionPerformed(java.awt.event.ActionEvent evt) Updates object on action performed.
static net.wotonomy.foundation.NSArray	aspects() Returns a List that describes the aspects supported by this class.
static net.wotonomy.foundation.NSArray	aspectSignatures() Returns a List of aspect signatures whose contents correspond with the aspects list.
static net.wotonomy.foundation.NSArray	associationClassesSuperseded() Returns a List of EOAssociation subclasses that, for the objects that are usable for this association, are less suitable than this association.
void	bindAspect(java.lang.String anAspect, net.wotonomy.ui.EODisplayGroup aDisplayGroup, java.lang.String aKey) Binds the specified aspect of this association to the specified key on the specified display group.
void	breakConnection() Breaks the connection between this association and its object.
boolean	canBindAspect(java.lang.String anAspect, net.wotonomy.ui.EODisplayGroup aDisplayGroup, java.lang.String aKey) Returns whether this association can bind to the specified display group on the specified key for the specified aspect.
void	changedUpdate(javax.swing.event.DocumentEvent e)
boolean	endEditing() Forces this association to cause the object to stop editing and validate the user's input.
void	establishConnection() Establishes a connection between this association and the controlled object.
void	focusGained(java.awt.event.FocusEvent evt) Notifies of beginning of edit.
void	focusLost(java.awt.event.FocusEvent evt) Updates object on focus lost and notifies of end of edit.
java.text.Format	format() Gets the Format that is used to convert values from the display group to and from text that is displayed in the component.
void	handleNotification(net.wotonomy.foundation.NSNotification aNotification) Handles idle notification.
void	insertUpdate(javax.swing.event.DocumentEvent e)
boolean	isActiveUpdate() Returns whether the text association is configured to actively update the model in response to changes in the component.
static boolean	isUsableWithObject(java.lang.Object anObject) Returns whether this class can control the specified object.
protected boolean	needToReadValueFromDisplayGroup(java.lang.Object aValue, net.wotonomy.foundation.NSSelector aSelector) Called to determine whether the controlled component needs to be updated.
protected boolean	needToWriteValueToDisplayGroup(java.lang.Object aValue, net.wotonomy.ui.EODisplayGroup aDisplayGroup) Called to determine whether the display group needs to be updated.
static net.wotonomy.foundation.NSArray	objectKeysTaken() Returns a List of properties of the controlled object that are controlled by this class.
void	objectWillChange(java.lang.Object anObject)
static java.lang.String	primaryAspect() Returns the aspect that is considered primary or default.
protected void	queueUpdate(javax.swing.event.DocumentEvent e) Queues a notification to PostWhenIdle.
void	removeUpdate(javax.swing.event.DocumentEvent e)
void	setActiveUpdate(boolean isActiveUpdate) Sets whether the text association should actively update the model in response to changes in the component.
void	setFormat(java.text.Format aFormat) Sets the Format that is used to convert values from the display group to and from text that is displayed in the component.
void	subjectChanged() Called when either the selection or the contents of an associated display group have changed.
protected boolean	writeValueToDisplayGroup() Writes the value currently in the component to the selected object in the display group bound to the value aspect.

Methods inherited from class net.wotonomy.ui.EOAssociation

associationClassesForObject, copyMatchingBindingsFromAssociation, displayGroupForAspect, displayGroupKeyForAspect, displayName, object, setValueForAspect, setValueForAspectAtIndex, shouldEndEditing, shouldEndEditingAtIndex, valueForAspect, valueForAspectAtIndex

Methods inherited from class net.wotonomy.control.EODelayedObserver

discardPendingNotification, observerQueue, priority, update

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

wasNull

protected boolean wasNull

EMPTY_STRING

protected static final java.lang.String EMPTY_STRING

See Also:

Constant Field Values

needsUpdate

protected boolean needsUpdate

hasDocument

protected boolean hasDocument

isListening

protected boolean isListening

format

protected java.text.Format format

activeUpdate

protected boolean activeUpdate

lastKnownType

protected java.lang.Class lastKnownType

Constructor Detail

TextAssociation

public TextAssociation(java.lang.Object anObject)

Constructor specifying the object to be controlled by this association. Does not establish connection.

Method Detail

aspectSignatures

public static net.wotonomy.foundation.NSArray aspectSignatures()

Returns a List of aspect signatures whose contents correspond with the aspects list. Each element is a string whose characters represent a capability of the corresponding aspect.

• "A" attribute: the aspect can be bound to an attribute.
• "1" to-one: the aspect can be bound to a property that returns a single object.
• "M" to-one: the aspect can be bound to a property that returns multiple objects.

An empty signature "" means that the aspect can bind without needing a key. This implementation returns "A1M" for each element in the aspects array.

aspects

public static net.wotonomy.foundation.NSArray aspects()

Returns a List that describes the aspects supported by this class. Each element in the list is the string name of the aspect. This implementation returns an empty list.

associationClassesSuperseded

public static net.wotonomy.foundation.NSArray associationClassesSuperseded()

Returns a List of EOAssociation subclasses that, for the objects that are usable for this association, are less suitable than this association.

isUsableWithObject

public static boolean isUsableWithObject(java.lang.Object anObject)

Returns whether this class can control the specified object.

objectKeysTaken

public static net.wotonomy.foundation.NSArray objectKeysTaken()

Returns a List of properties of the controlled object that are controlled by this class. For example, "stringValue", or "selected".

primaryAspect

public static java.lang.String primaryAspect()

Returns the aspect that is considered primary or default. This is typically "value" or somesuch.

canBindAspect

public boolean canBindAspect(java.lang.String anAspect,
                             net.wotonomy.ui.EODisplayGroup aDisplayGroup,
                             java.lang.String aKey)

Returns whether this association can bind to the specified display group on the specified key for the specified aspect.

Overrides:

canBindAspect in class net.wotonomy.ui.EOAssociation

bindAspect

public void bindAspect(java.lang.String anAspect,
                       net.wotonomy.ui.EODisplayGroup aDisplayGroup,
                       java.lang.String aKey)

Binds the specified aspect of this association to the specified key on the specified display group.

Overrides:

bindAspect in class net.wotonomy.ui.EOAssociation

establishConnection

public void establishConnection()

Establishes a connection between this association and the controlled object. This implementation attempts to add this class as an ActionListener and as a FocusListener to the specified object.

Overrides:

establishConnection in class net.wotonomy.ui.EOAssociation

breakConnection

public void breakConnection()

Breaks the connection between this association and its object. Override to stop listening for events from the object.

Overrides:

breakConnection in class net.wotonomy.ui.EOAssociation

objectWillChange

public void objectWillChange(java.lang.Object anObject)

Specified by:

objectWillChange in interface net.wotonomy.control.EOObserving

Overrides:

objectWillChange in class net.wotonomy.control.EODelayedObserver

subjectChanged

public void subjectChanged()

Called when either the selection or the contents of an associated display group have changed.

Overrides:

subjectChanged in class net.wotonomy.ui.EOAssociation

endEditing

public boolean endEditing()

Forces this association to cause the object to stop editing and validate the user's input.

Overrides:

endEditing in class net.wotonomy.ui.EOAssociation

Returns:

false if there were problems validating, or true to continue.

writeValueToDisplayGroup

protected boolean writeValueToDisplayGroup()

Writes the value currently in the component to the selected object in the display group bound to the value aspect.

Returns:

false if there were problems validating, or true to continue.

needToWriteValueToDisplayGroup

protected boolean needToWriteValueToDisplayGroup(java.lang.Object aValue,
                                                 net.wotonomy.ui.EODisplayGroup aDisplayGroup)

Called to determine whether the display group needs to be updated. This implementation reads the value from the display group and only returns true if the specified value is different. This is done as an optimization since writes are more expensive than reads. Override to customize this behavior.

needToReadValueFromDisplayGroup

protected boolean needToReadValueFromDisplayGroup(java.lang.Object aValue,
                                                  net.wotonomy.foundation.NSSelector aSelector)
                                           throws java.lang.IllegalAccessException,
                                                  java.lang.reflect.InvocationTargetException,
                                                  java.lang.NoSuchMethodException

Called to determine whether the controlled component needs to be updated. This implementation reads the value from the selector and only returns true if the specified value is different. This is done as an optimization since updating the component can be an expensive operation. Override to customize this behavior.

Throws:

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

java.lang.NoSuchMethodException

setFormat

public void setFormat(java.text.Format aFormat)

Sets the Format that is used to convert values from the display group to and from text that is displayed in the component.

format

public java.text.Format format()

Gets the Format that is used to convert values from the display group to and from text that is displayed in the component.

isActiveUpdate

public boolean isActiveUpdate()

Returns whether the text association is configured to actively update the model in response to changes in the component.

setActiveUpdate

public void setActiveUpdate(boolean isActiveUpdate)

Sets whether the text association should actively update the model in response to changes in the component. Default is true. False indicates that the model will be updated only when the component loses focus or fires an action event.

actionPerformed

public void actionPerformed(java.awt.event.ActionEvent evt)

Updates object on action performed.

Specified by:

actionPerformed in interface java.awt.event.ActionListener

focusGained

public void focusGained(java.awt.event.FocusEvent evt)

Notifies of beginning of edit.

Specified by:

focusGained in interface java.awt.event.FocusListener

focusLost

public void focusLost(java.awt.event.FocusEvent evt)

Updates object on focus lost and notifies of end of edit.

Specified by:

focusLost in interface java.awt.event.FocusListener

queueUpdate

protected void queueUpdate(javax.swing.event.DocumentEvent e)

Queues a notification to PostWhenIdle.

handleNotification

public void handleNotification(net.wotonomy.foundation.NSNotification aNotification)

Handles idle notification.

insertUpdate

public void insertUpdate(javax.swing.event.DocumentEvent e)

Specified by:

insertUpdate in interface javax.swing.event.DocumentListener

removeUpdate

public void removeUpdate(javax.swing.event.DocumentEvent e)

Specified by:

removeUpdate in interface javax.swing.event.DocumentListener

changedUpdate

public void changedUpdate(javax.swing.event.DocumentEvent e)

Specified by:

changedUpdate in interface javax.swing.event.DocumentListener