EOAssociation
- Inherits from:
- EODelayedObserver (EOControl) : NSObject
- Conforms to:
- NSCoding
- EOObserving (EODelayedObserver)
- NSObject (NSObject)
Declared in:
- EOInterface/EOAssociation.h
Class at a Glance
An EOAssociation maintains a two-way binding between the properties of a display object, such as a text field or combo box, and the properties of one or more enterprise objects contained in one or more EODisplayGroups. You typically create and configure associations in Interface Builder, using the programmatic interface only when you write your own EOAssociation subclasses.
Principal Attributes
- A display object (such as a text field or combo box)
- Aspects that control different parameters of the display object (such as value and enabled)
- One or more EODisplayGroups (no more than one per aspect)
- One or more keys (enteprise object properties) (as many as one key per aspect)
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. For information on the different EOAssociation subclasses you can use, see the following subclass specifications:
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:
- "How EOAssociations Work"
- "Setting up an EOAssociation Programmatically"
- "Creating a Subclass of EOAssociation"
Adopted Protocols
NSCoding
- - encodeWithCoder:
- - initWithCoder:
Method Types
- Declaring capabilities
- + aspects
- + aspectSignatures
- + objectKeysTaken (Yellow Box)
- + isUsableWithObject:
- + associationClassesSuperseded
- + displayName
- + primaryAspect
- - canBindAspect:displayGroup:key:
- Getting all possible EOAssociations for a display object
- + associationClassesForObject:
- Creating and configuring instances
- - initWithObject:
- - bindAspect:displayGroup:key:
- - establishConnection
- - breakConnection
- - copyMatchingBindingsFromAssociation:
- Getting the display object
- - object
- Examining bindings
- - displayGroupForAspect:
- - displayGroupKeyForAspect:
- Updating values
- - subjectChanged
- - endEditing
- Accessing enterprise object values
- - setValue:forAspect:
- - setValue:forAspect:atIndex:
- - valueForAspect:
- - valueForAspect:atIndex:
- Handling validation errors
- - shouldEndEditingForAspect:invalidInput:errorDescription:
- - shouldEndEditingForAspect:invalidInput:errorDescription:index:
Constructors
Class Methods
aspects
+ (NSArray *)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
+ (NSArray *)aspectSignatures
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:
+ (NSArray *)associationClassesForObject:(id)aDisplayObject
Returns the subclasses of EOAssociation usable with aDisplayObject. Sends isUsableWithObject: to every loaded subclass of EOAssociation, adding those that respond YES to the array. Subclasses shouldn't override this method; override isUsableWithObject: instead.
associationClassesSuperseded
+ (NSArray *)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 EOPopUpAssociation is always more appropriate to use with pop-up buttons.
displayName
+ (NSString *)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:
+ (BOOL)isUsableWithObject:(id)aDisplayObject
Overridden by subclasses to return YES if instances of the receiving class are usable with aDisplayObject, NO 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
+ (NSArray *)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
+ (NSString *)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 nil.
Instance Methods
bindAspect:displayGroup:key:
- (void)bindAspect:(NSString
*)aspectName
displayGroup:(EODisplayGroup *)aDisplayGroup
key:(NSString *)key
See Also: - initWithObject:, - establishConnection
breakConnection
- (void)breakConnection
See Also: - establishConnection
canBindAspect:displayGroup:key:
- (BOOL)canBindAspect:(NSString
*)aspectName
displayGroup:(EODisplayGroup *)aDisplayGroup
key:(NSString *)key
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 YES.
See Also: - localKeys (EODisplayGroup), - attributeKeys (EOClassDescription), - toOneRelationshipKeys (EOClassDescription), - toManyRelationshipKeys (EOClassDescription)
copyMatchingBindingsFromAssociation:
- (void)copyMatchingBindingsFromAssociation:(EOAssociation
*)anAssociation
displayGroupForAspect:
- (EODisplayGroup *)displayGroupForAspect:(NSString
*)aspectName
See Also: - displayGroupKeyForAspect:
displayGroupKeyForAspect:
- (NSString *)displayGroupKeyForAspect:(NSString
*)aspectName
See Also: - displayGroupForAspect:
endEditing
- (BOOL)endEditing
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 YES.
establishConnection
- (void)establishConnection
See "Setting up an EOAssociation Programmatically" in the class description for more information.
See Also: - breakConnection
initWithObject:
- (id)initWithObject:(id)aDisplayObject
See Also: - bindAspect:displayGroup:key:, - establishConnection
object
- (id)object
See Also: - initWithObject:
setValue:forAspect:
- (BOOL)setValue:(id)value
forAspect:(NSString *)aspectName
See Also: - valueForAspect:
setValue:forAspect:atIndex:
- (BOOL)setValue:(id)value
forAspect:(NSString *)aspectName
atIndex:(unsigned int)index
See Also: - valueForAspect:atIndex:
shouldEndEditingForAspect:invalidInput:errorDescription:
- (BOOL)shouldEndEditingForAspect:(NSString
*)aspectName
invalidInput:(NSString *)inputString
errorDescription:(NSString *)errorDescription
For
example, an association bound to an NSControl object (Application
Kit) receives a control:didFailToFormatString:errorDescription: delegate
message when the control's formatter fails to format the input
string. Its implementation of that method invokes shouldEndEditingForAspect:invalidInput:errorDescription:.
See Also: - shouldEndEditingForAspect:invalidInput:errorDescription:index:
shouldEndEditingForAspect:invalidInput:errorDescription:index:
- (BOOL)shouldEndEditingForAspect:(NSString
*)aspectName
invalidInput:(NSString *)inputString
errorDescription:(NSString *)errorDescription
index:(unsigned int)index
subjectChanged
- (void)subjectChanged
valueForAspect:
- (id)valueForAspect:(NSString
*)aspectName
See Also: - setValue:forAspect:
valueForAspect:atIndex:
- (id)valueForAspect:(NSString
*)aspectName
atIndex:(unsigned int)index
See Also: - setValue:forAspect:atIndex: