Inherits From:
EODelayedObserver (EOControl) : Object (Java Client)
EODelayedObserver (EOControl) : NSObject (Yellow Box)
EOObserving (EODelayedObserver)
Inherits From:
com.apple.client.eointerface (Java Client)
com.apple.yellow.eointerface (Yellow Box)
value
and enabled
)
Class Description
EOAssociation defines the mechanism that transfers values between EODisplayGroups and the user interface of an application. An EOAssociation instance is tied to a single display object, a user interface object or other kind of object that manages values intended for display. The EOAssociation takes over certain outlets of the display object and sets its value according to the selection in the EODisplayGroup. An EOAssociation also has various aspects, which define the different parameters of the display object that it controls, such as the value or values displayed and whether the display object is enabled or editable. Each aspect can be bound to an EODisplayGroup with a key denoting a property of the enterprise objects in the EODisplayGroup. The value or values of this property determine the value for the EOAssociation's aspect.
EOAssociation is an abstract class, defining only the general mechanism for binding display objects to EODisplayGroups. You always create instances of its various subclasses, which define behavior specific to different kinds of display objects. See the listing in the Class at a Glance section for standard EOAssociation subclasses.
You normally set up EOAssociations using Interface Builder; each of the class specifications for EOAssociation's subclasses provide an example using Interface Builder to set them up. EOAssociation's programmatic interface is more important when defining custom EOAssociation subclasses. For more information on EOAssociations, see the sections:
aspects
public static NSArray aspects
()
This method is available for Yellow Box applications only; the Java Client equivalent is the instance method aspects
.
Overridden by subclasses to return the names of the receiving class's aspects as an array of string objects. Subclasses should include their superclass's aspects and add their own when overriding this method.
aspectSignatures
public static NSArray aspectSignatures
()
This method is available for Yellow Box applications only; the Java Client equivalent is the instance method aspectSignatures
.
Overridden by subclasses to return the signatures of the receiver's aspects, an array of string objects matching its aspects array index for index. Each signature string can contain the following characters:
Signature Character | Meaning |
---|---|
A | The aspect can be bound to attributes. |
1 (one) | The aspect can be bound to to-one relationships. |
M | The aspect can be bound to to-many relationships. |
An aspect signature string of "A1", for example, means the corresponding aspect can be bound to either attributes or to-one relationships. An empty signature indicates that the corresponding aspect can be bound to an EODisplayGroup without a key (that is, the key is irrelevant). Interface Builder uses aspect signatures to enable and disable keys in its Connections inspectors.
EOAssociation's implementation of this method returns an array of "A1M" of the length of its aspects array.
associationClassesForObject
public static NSArray associationClassesForObject
(java.lang.Object aDisplayObject)
Returns the subclasses of EOAssociation usable with aDisplayObject. Sends isUsableWithObject
to every loaded subclass of EOAssociation, adding those that respond true
to the array. Subclasses shouldn't override this method; override isUsableWithObject:
instead.
associationClassesSuperseded
public static NSArray associationClassesSuperseded
()
This method is available for Yellow Box applications only; the Java Client equivalent is the instance method associationClassesSuperseded
.
Overridden by subclasses to return the other EOAssociation classes that the receiver supplants. This allows a subclass to mask its superclasses from the Connection Inspector's pop-up list in Interface Builder, since the subclass always includes the aspects and functionality of its superclasses. For example, EOPopUpAssociation supersedes EOControlAssociation, because for pop-up buttons an EOPopUpAssociation is always more appropriate to use.
displayName
public static java.lang.String displayName
()
This method is available for Yellow Box applications only; the Java Client equivalent is the instance method displayName
.
Returns the name used by Interface Builder in the Connection Inspector's pop-up list. EOAssociation's implementation simply returns the name of the receiving class.
isUsableWithObject
public static boolean isUsableWithObject
(java.lang.Object aDisplayObject)
This method is available for Yellow Box applications only; the Java Client equivalent is the instance method isUsableWithObject
.
Overridden by subclasses to return true
if instances of the receiving class are usable with aDisplayObject, false
if they aren't. The receiving class can examine any relevant characteristic of aDisplayObject-its class, configuration (such as whether an NSMatrix operates in radio mode), and so on.
objectKeysTaken
public static NSArray objectKeysTaken
()
This method is available for Yellow Box applications only; the Java Client equivalent is the instance method objectKeysTaken
.
Overridden by subclasses to return the names of display object outlets that instances assume control of, such as "target" and "delegate". Interface Builder uses this information to disable connections from these outlets in its Connections Inspector.
primaryAspect
public static java.lang.String primaryAspect
()
This method is available for Yellow Box applications only; the Java Client equivalent is the instance method primaryAspect
.
Overridden by subclasses to return the default aspect, usually one denoting the displayed value, which by convention is named "value". EOAssociation's implementation returns null
.
Instance Methods
aspects
public NSArray aspects
()
This method is available for Java Client applications only; the Yellow Box equivalent is the static method aspects
.
Overridden by subclasses to return the names of the receiving class's aspects, as string objects. Subclasses should include their superclass's aspects and add their own when overriding this method.
aspectSignatures
public NSArray aspectSignatures
()
This method is available for Java Client applications only; the Yellow Box equivalent is the static method aspectSignatures
.
Overridden by subclasses to return the signatures of the receiver's aspects, an array of string objects matching its aspects array index for index. Each signature string can contain the following characters:
Signature Character | Meaning |
---|---|
A | The aspect can be bound to attributes. |
1 (one) | The aspect can be bound to to-one relationships. |
M | The aspect can be bound to to-many relationships. |
An aspect signature string of "A1", for example, means the corresponding aspect can be bound to either attributes or to-one relationships. An empty signature indicates that the corresponding aspect can be bound to an EODisplayGroup without a key (that is, the key is irrelevant). Interface Builder uses aspect signatures to enable and disable keys in its Connections inspectors.
EOAssociation's implementation of this method returns an array of "A1M" of the length of its aspects array.
bindAspect
public void bindAspect
(
java.lang.String aspectName,
EODisplayGroup aDisplayGroup,
java.lang.String key)
Defines the receiver's link between its display object and aDisplayGroup. aspectName is the name of the aspect it observer in its display object, and key is the name of the property it observes in aDisplayGroup. Invoke establishConnection
after this method to finish setting up the binding. See "Setting up an EOAssociation Programmatically" in the class description for more information.
See also:
establishConnection
breakConnection
public void breakConnection
()
Removes the receiver from its EODisplayGroup and display object. Subclasses should override this method to remove the receiver from any outlets of the display object and invoke super
's implementation at the end.
See also:
establishConnection
canBindAspect
public boolean canBindAspect
(
java.lang.String aspectName,
EODisplayGroup aDisplayGroup,
java.lang.String key)
Overridden by subclasses to return true
if the receiver can tie an aspect named aspectName from its display object to the property identified by key in aDisplayGroup, false
if it can't. aspectName should name an aspect supported by the receiver's class.
Interface Builder uses this information to disable aspects in its Connections Inspector. Subclasses can override this method to base their answers on other binds already made, or on characteristics of the receiver's display object or of aDisplayGroup. EOAssociation's implementation always returns true
.
See also:
localKeys
(EODisplayGroup), attributeKeys (EOClassDescription), toOneRelationshipKeys (EOClassDescription), toManyRelationshipKeys (EOClassDescription)
copyMatchingBindingsFromAssociation
public void copyMatchingBindingsFromAssociation
(EOAssociation anAssociation)
Duplicates the bindings of anAssociation in the receiver. For each aspect of anAssociation that has an EODisplayGroup, invokes bindAspect
with the EODisplayGroup and key for that aspect.
displayGroupForAspect
public EODisplayGroup displayGroupForAspect
(java.lang.String aspectName)
Returns the EODisplayGroup bound to the receiver for aspectName, or null
if there's no such object.
See also:
displayGroupKeyForAspect
displayGroupKeyForAspect
public java.lang.String displayGroupKeyForAspect
(java.lang.String aspectName)
Returns the EODisplayGroup key bound to the receiver for aspectName, or null
if there's no EODisplayGroup.
See also:
displayGroupForAspect
displayName
public java.lang.String displayName
()
This method is available for Java Client applications only; the Yellow Box equivalent is the static method displayName
.
Returns the name used for display purposes. EOAssociation's implementation simply returns the name of the receiver's class.
endEditing
public boolean endEditing
()
Overridden by subclasses to pass the value of the receiver's display object to the EODisplayGroup, by invoking setValueForAspect
with the display object's value and the appropriate aspect (typically "value"). Returns true
if successful, false
if not-specifically if setValueForAspect
returns false
. The receiver should also send an associationDidEndEditing:
message to its EODisplayGroup.
Subclasses whose display objects immediately pass their changes back to the EOAssociation-such as a button or pop-up list-need not override this method. It's only needed when the display object's value is edited rather than simply set.
EOAssociation's implementation does nothing but return true
.
establishConnection
public void establishConnection
()
Overridden by subclasses to attach the receiver to the outlets of its display object, and to otherwise configure the display object (such as by setting its
super
's implementation after establishing their own connections.See "Setting up an EOAssociation Programmatically" in the class description for more information.
See also:
breakConnection
isUsableWithObject
public boolean isUsableWithObject
(java.lang.Object aDisplayObject)
This method is available for Java Client applications only; the Yellow Box equivalent is the static method isUsableWithObject
.
Overridden by subclasses to return true
if instances of the receiving class are usable with aDisplayObject, false
if they aren't. The receiving class can examine any relevant characteristic of aDisplayObject-its class, configuration, and so on. EOAssociation's implementation returns false
.
object
public java.lang.Object object
()
Returns the receiver's display object.
See also:
Overridden by subclasses to return the names of display object outlets that instances assume control of, such as . Interface Builder uses this information to disable connections from these outlets in its Connections Inspector.
primaryAspect
public java.lang.String primaryAspect
()
This method is available for Java Client applications only; the Yellow Box equivalent is the static method primaryAspect
.
Overridden by subclasses to return the default aspect, usually one denoting the displayed value, which by convention is named "value". EOAssociation's implementation returns null
.
setValueForAspect
public boolean setValueForAspect
(
java.lang.Object value,
java.lang.String aspectName)
Sets a value of the selected enterprise object in the EODisplayGroup bound to aspectName. Retrieves the display group and key bound to aspectName, and sends the display group a setSelectedObjectValue
message with value and the key as arguments. Returns true
if successful, or if there's no display group bound to aspectName. Returns false
if there's an display group and it doesn't accept the new value.
See also:
valueForAspect
setValueForAspectAtIndex
public boolean setValueForAspectAtIndex
(
java.lang.Object value,
java.lang.String aspectName,
int index)
Sets a value of the enterprise object at index in the EODisplayGroup bound to aspectName. Retrieves the display group and key bound to aspectName, and sends the display group a setValueForObjectAtIndex
message with value, index, and the key as arguments. Returns true
if successful, or if there's no display group bound to aspectName. Returns false
if there's a display group and it doesn't accept the new value.
See also:
valueForAspectAtIndex
shouldEndEditing
public boolean shouldEndEditingAtIndex
(
java.lang.String aspectName,
java.lang.String inputString,
java.lang.String errorDescription)
Invoked by subclasses when the display object fails to validate its input, this method informs the EODisplayGroup bound to aspectName with an associationFailedToValidateValue
message, using the display group's selected object. Returns the result of that message, or true
if there's no display group.
For example, an association bound to an NSControl object (Application Kit) receives a
shouldEndEditingForAspect:invalidInput:errorDescription:
.
See also:
shouldEndEditingAtIndex
shouldEndEditingAtIndex
public boolean shouldEndEditing
(
java.lang.String aspectName,
java.lang.String inputString,
java.lang.String errorDescription,
int index)
Works in the same manner as shouldEndEditing
, but allows you to specify a particular object by index rather than implicitly specifying the selected object.
subjectChanged
public void subjectChanged
()
Overridden by subclasses to update state based when an EODisplayGroup's selection or contents changes. This method is invoked automatically anytime a display group that's bound to the receiver changes. The receiver can query its display group with selectionChanged
and contentsChanged
messages to determine how it needs to update.
valueForAspect
public java.lang.Object valueForAspect
(java.lang.String aspectName)
Returns a value of the selected enterprise object in the EODisplayGroup bound to aspectName. Retrieves the display group and key bound to aspectName, and sends the display group a selectedObjectValueForKey
message with the key. Returns null
if there's no display group or key bound to aspectName.
See also:
setValueForAspect
valueForAspectAtIndex
public java.lang.Object valueForAspectAtIndex
(
java.lang.String aspectName,
int index)
Returns a value of the enterprise object at index in the EODisplayGroup bound to aspectName. Retrieves the display group and key bound to aspectName, and sends the display group a valueForObjectAtIndex
message with index and the key. Returns null
if there's no display group or key bound to aspectName.
See also:
setValueForAspectAtIndex