Copyright: Copyright © NeXT Software Inc. 1996


EOActionAssociation

Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

Inherits From:	EOAssociation : EODelayedObserver : NSObject

Conforms To:	NSCoding (EOAssociation)

EOObserving (EODelayedObserver)

NSObject (NSObject)

Declared In:	EOInterface/EOActionAssociation.h

Purpose

An EOActionAssociation displays no values, but instead sends a message to the objects selected in its EODisplayGroup when the display object, an NSControl or NSActionCell, sends its action.

Usable With

Any NSControl or NSActionCell

Aspects

action	Bound to a key that names a method implemented by the objects. The method must take no arguments if the argument aspect isn’t bound, one argument if it is.

argument	An object attribute or relationship of the selected object, passed as an argument to the action method. (Usually bound to a different EODisplayGroup than that bound to action.)

enabled	A boolean attribute of the selected object, which determines whether the display object is enabled.

Object Keys Taken

target	On receiving an action message from the display object, an EOActionAssocation sends its action to the selected objects.

Class Description

EOActionAssociation allows you to set up an interface object, such as a button, to send a message to the selected objects when it’s acted on.

Examples

Suppose you have an application that manages member accounts, each of which has a restriction on the outstanding balance allowed. Further, the Member class defines a boostRestrictions method that increases the limit by 20%. You can set up a button in the application to invoke this method by connecting it to the Member display group and binding the action aspect to the “boostRestrictions” key (which you add in Interface Builder).

In another scenario, one EODisplayGroup shows Members, while another shows video tapes available for rent. Here, you can bind a button to the Members EODisplayGroup with the action rentVideoTape:. Similarly, you bind the VideoTape EODisplayGroup to the argument aspect. Now, when the user selects a Member and a VideoTape and clicks the button, the Member is sent a rentVideoTape: message with the VideoTape.


EOActionCellAssociation

Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

Inherits From:	EOGenericControlAssociation : EOAssociation : EODelayedObserver : NSObject

Conforms To:	NSCoding (EOAssociation)

EOObserving (EODelayedObserver)

NSObject (NSObject)

Declared In:	EOInterface/EOControlAssociation.h

Purpose

An EOActionCellAssociation displays a single attribute value in its display object (an NSActionCell) and updates that value in the selected object when the NSActionCell changes.

Usable With

Any NSActionCell

Aspects

value	An attribute of the selected object, displayed in the NSActionCell.

enabled	A boolean attribute of the selected object, which determines whether the NSActionCell is enabled.

Object Keys Taken

target	On receiving an action message from the NSActionCell, an EOActionCellAssociation sends the NSActionCell’s value to the EODisplayGroup.

delegate	See the class description.

Class Description

EOActionCellAssociation is the default EOAssociation subclass for use with NSActionCells. An EOActionCellAssociation displays the value of the selected object in its NSActionCell, and updates the object when the NSActionCell’s value changes. A sibling class, EOControlAssociation, can be used with independent controls such as NSButtons and NSTextFields. Some other subclasses of EOAssociation, such as EOPopUpAssociation and EOColumnAssociation, supersede these classes for more specialized behavior.

When multiple EOActionCellAssociations are bound to cells in the same control, one of them becomes the delegate of the control and forwards appropriate messages, such as control:isValidObject:, to the others. This eliminates the need to add an EOControlAssociation just to handle delegate messages.

EOActionCellAssociations access values using NSActionCell’s setObjectValue: method, which allows values with non-string representations to be displayed. An EOActionCellAssociation can be bound to an NSImageCell, for example, with an attribute whose class is NSImage.

Examples

To display a movie’s budget in an NSTextFieldCell, create an EOControlAssociation to the Movie display group and bind the value aspect to the “budget” key. If the NSTextFieldCell is editable, then when the user types a new value and presses Enter or Tab, the selected movie’s budget attribute is changed.

Assuming that Movie objects implement an isBudgetNegotiable method, you can make the NSTextFieldCell uneditable depending on the selected movie. To do so, add an “isBudgetNegotiable” key to the Movie display group in Interface Builder and bind the “enabled” key to it.

Instance Methods

control

− (NSControl *)control

Returns the NSControl that owns the receiver’s display object.

See also:	− object (EOAssociation), − controlView (NSActionCell class of the Application Kit)

editingAssociation

− (EOGenericControlAssociation *)editingAssociation

For EOActionCellAssociations in an NSMatrix or other multi-celled control, returns the EOActionCellAssociation that’s currently selected (or editing text).


EOActionInsertionAssociation

Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

Inherits From:	EOAssociation : EODelayedObserver : NSObject

Conforms To:	NSCoding (EOAssociation)

EOObserving (EODelayedObserver)

NSObject (NSObject)

Declared In:	EOInterface/EOActionInsertionAssociation.h

Purpose

An EOActionInsertionAssociation inserts objects from one EODisplayGroup into another when its display object sends an action message.

Usable With

Any object that responds to setAction:

Aspects

source	Bound to the EODisplayGroup containing objects to insert. This aspect doesn’t use a key.

destination	A relationship of the selected object into which objects from the source EODisplayGroup are inserted. Usually bound to a different EODisplayGroup than source.

enabled	A boolean attribute of the selected object (usually in the destination EODisplayGroup), which determines whether the NSControl is enabled.

Object Keys Taken

target	On receiving an action message from the display object, an EOActionInsertionAssociation inserts objects from the source EODisplayGroup into the destination EODisplayGroup.

Class Description

EOActionInsertionAssociations display no values, instead using a control’s action method as a signal to insert the objects selected in one display group into the relationship of another’s first selected object.

Example

Suppose you form an association from a button, binding the source aspect to a Talent display group and the destination aspect to a Movie display group’s “directors” key. When the user presses the button, the objects selected in the Talent display group are added to the directors relationship of the selected Movie.


EOAssociation

Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

Inherits From:	EODelayedObserver : NSObject

Conforms To:	NSCoding

EOObserving (EODelayedObserver)

NSObject (NSObject)

Declared In:	EOInterface/EOAssociation.h

Purpose

An EOAssociation maintains a two-way binding between the properties of a display object, typically a control, and the properties of one or more enterprise objects contained in one or more EODIsplayGroups. You typically set them up using Interface Builder, using the programmatic interface most often when defining subclasses. See these subclass specifications for information on the different kinds of EOAssociations:

•	EOActionAssociation	•	EOActionInsertionAssociation

•	EOColumnAssociation	•	EOTableViewAssociation

•	EOControlAssociation 	•	EOActionCellAssociation

•	EODetailSelectionAssociation	•	EOPickTextAssociation

•	EOMasterDetailAssociation	•	EOMasterPeerAssociation

•	EOPopUpAssociation	•	EOTextAssociation

Principal Attributes

•	Monitors a single display object

•	Has multiple aspects that control state of the display object

•	Can be bound to multiple EODisplayGroups

Creation

Interface Builder

− initWithObject:	Designated initializer.

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 instantiate 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; “Setting up an EOAssociation Programmatically” below shows how to set them up in code. EOAssociation’s programmatic interface is more important when defining custom EOAssociation subclasses. “Creating a Subclass of EOAssociation” discusses this process in detail.

How EOAssociations Work

An EOAssociation monitors its display object for changes in its value and for other events, and monitors its EODisplayGroups for changes in the selection or in the contents (the enterprise objects). A change at either end causes the EOAssociation to query the object at that end for whatever needs to be done, and to take action on the object at the other end. For example, when the selection changes in the EODisplayGroup, the EOAssociation gets the new value from the selected enterprise object and puts it in the display object. The following sections describe in detail how the EOAssociation works with the object at either end.

The Display Object

An EOAssociation is tied to a single display object, which owns it. Each EOAssociation subclass takes over a particular set of the display object’s outlets, such as its target, delegate, or data source, and acts in that role by receiving the messages defined for it. For example, an EOControlAssociation sets itself as the target of its display object, an NSControl, and assigns the control’s action method to a method that it implements. When the control is acted upon, it sends its action to the EOAssociation, which takes the control’s value and sends it to the EODisplayGroup to update the selected enterprise object. An EOControlAssociation also sets itself as the control’s delegate to receive various editing and validation delegate messages.

Because the EOAssociation takes over various outlets of its display object, these outlets can’t be set or used for other purposes. EOAssociation’s objectKeysTaken class method returns the names of these outlets. Interface Builder also disables them in its Connections Inspector when a display object has an EOAssociation assigned to it. For example, a button with an EOControlAssociation has its target outlet dimmed in the inspector.

Although display objects are typically user-interface objects such as text fields and pop-up lists, they can in fact be any kind of object. Two notable examples of non-interface display objects are EODisplayGroups in master-detail and master-peer configurations. These configurations result in the detail or peer EODisplayGroup displaying the destination values for a to-many relationship selected in the master EODisplayGroup. See the EOMasterDetailAssociation, EOMasterPeerAssociation, and EODetailSelectionAssociation class specifications for more information on master-detail and master-peer configurations.

Bindings: Aspects, EODisplayGroups, and Keys

Though an EOAssociation has only one display object, it can have any number of aspects, which define what the EOAssociation monitors in its EODisplayGroups. Aspects are bound to EODisplayGroups through keys describing class properties or other properties of the enterprise objects in the EODisplayGroups. Depending on the type of EOAssociation, there may be only one aspect or several aspects. Where there are several, they can be optional or mandatory; they may all have to be bound to a single EODisplayGroup; they may be bound to different EODisplayGroups; or they may be mutually exclusive, in that if one is used the other must not be used.

An aspect reflects a characteristic of the EOAssociation’s display object: the value it displays, the list of possible values it can contain, whether it’s enabled or editable, and so on. Most EOAssociations have a “value” aspect, for example. The aspect’s value is determined by the values of enterprise object properties in the EODisplayGroup that the aspect is bound to. The value can be taken from all of the enterprise objects in the EODisplayGroup, or from just the selected ones. Some aspects are “read-only” from the EODisplayGroup, merely causing changes in the display object when the EODisplayGroup changes; others affect the properties of enterprise objects in the EODisplayGroup when the EOAssociation’s display object changes.

For example, an EOControlAssociation defines the aspects “value” and “enabled”. To set up a text field so that it displays the salary for the selected enterprise object, you create an EOControlAssociation for the text field, and bind its “value” aspect to the “salary” key of the EODisplayGroup containing the enterprise objects. You can also bind its “enabled” aspect to some key such as “eligibleForRaise”, so that if this property has a non-zero value the user can edit the salary value in the text field. Then, when the user presses the Return key or otherwise finishes editing, the new value is sent to the EODisplayGroup.

A multi-valued aspect can represent the destination of a to-many relationship, or it can define the range of possible values for an individual object’s property. One such EOAssociation subclass, EOPopUpAssociation, has a “titles” aspect that’s set to all of the possible values for a given key; these values then make up the list of items in the pop-up list. It also has a “selectedObject” aspect, bound to an EODisplayGroup whose entities use those value, that selects the pop-up list item for the value of the selected enterprise object in the EODisplayGroup. Binding the “titles” aspect to the “name” key of a Department entity’s EODisplayGroup, for example, results in a pop-up list containing the names of all departments.

EOAssociations register themselves with their EODisplayGroups in order to be notified of changes in their enterprise objects. When an EODisplayGroup changes its selection or contents, its EOAssociations are sent a subjectChanged message. This message doesn’t indicate which EODisplayGroup has changed, so the EOAssociation must query each of its EODisplayGroup as described below under “Monitoring Changes from the EODisplayGroup.” When the EOAssociation needs to send a change to an EODisplayGroup, it typically does so by invoking setValue:forAspect:. This process is described under “Monitoring Changes from the Display Object.”

Setting up an EOAssociation Programmatically

Though you normally set up EOAssociations with the Interface Builder application, you can do so programmatically as well. Because EOAssociations coordinate the actions of many objects, linking a display object to a control group is a multi-step process, as shown by this code fragment:

NSTextField *salaryField;        /* Assume this exists. */

EODisplayGroup *employeeGroup;   /* Assume this exists. */

EOControlAssociation *myAssoc;

myAssoc = [[EOControlAssociation alloc] initWithObject:salaryField];

[myAssoc bindAspect:@"value" displayGroup:employeeGroup key:@"salary"];

[myAssoc bindAspect:@"enabled" displayGroup:employeeGroup key:@"eligibleForRaise"];

[myAssoc establishConnection];

[myAssoc release];

This example first allocates an EOAssociation subclass and initializes it with the display object it monitors, in this case salaryField. At this point the EOAssociation is tenuously linked to salaryField; it hasn’t appropriated any of the field’s outlets, and hasn’t been retained by the field. Before this can happen, the EOAssociation must have at least one aspect bound to an EODisplayGroup. This is accomplished by the two bindAspect:displayGroup:key: messages, which define the nature of the field’s interaction with employeeGroup. Now all of the potential connections have been put in place, and an establishConnection message causes them to be confirmed: salaryField is made to assume myAssoc as its target and delegate, and myAssoc is registered as an observer of employeeGroup. At this point myAssoc is retained by the field, so it can be safely released.

Creating a Subclass of EOAssociation

If none of the standard EOAssociation subclasses meets your needs, you can create a new one without much effort. To do so, you need to define four areas of functionality:

•	What your subclass monitors and which display objects is can work with.

•	How your subclass establishes its connections with its display object and its EODisplayGroups.

•	How it monitors the EODisplayGroups and updates the display object.

•	How it monitors the display object and updates the EODisplayGroups.

The following four sections describe how to do each of these.

Defining Capabilities

A significant part of creating an EOAssociation subclass is defining and advertising what the subclass works with. This allows Interface Builder to make your subclass available in its Connections Inspector pop-up list, just like any other. The characteristics that your subclass should define are:

Aspects (required). Your EOAssociation subclass must define an aspects class method that returns an NSArray of aspect names, as NSStrings. Some standard aspects are:

Aspect Name	Use

value	The value of an attribute or relationship

enabled	Whether the control should be enabled

titles	All existing values for an attribute

selectedTitle	The value of the selected attribute (bound to the same key as “titles”)

What the subclass works with (required). Interface Builder asks each EOAssociation subclass if it can work with a given object when it displays its Connections Inspector. Your subclass should implement the isUsableWithObject: class method to examine the object provided and return YES if it can work with that object. This method can examine the class of the object provided, or any of its attributes, to determine whether it can work with the object. For example, EOPopUpAssociation verifies that the object is an NSPopUpButton, while EOMasterDetailAssociation checks that the object is an EODisplayGroup whose data source is an EODetailDataSource.

Aspect signatures (optional). Aspects by default are made available for any kind of property—single-valued attributes, to-one relationships, and to-many relationships. If your subclass has aspects that only have meaning for one or two of these, it should define an aspectSignatures class method that returns an NSArray of NSStrings corresponding to the aspects. Each string should contain a subset of the string “A1M”, where “A” indicates that the aspect can be used with attributes (where the value is a value-bearing object such as NSString or NSNumber), “1” that it can be used with to-one relationships (where the value is an enterprise object), and “M” indicates that the aspect can be used with to-many relationships (where the value is an array of enterprise objects). EOControlAssociation only displays single attributes, so its aspect signature for “value” and “enabled” is “A”, “A”. EOMasterDetailAssociation only works with relationships, so its aspect signature for “parent” is “1M”.

Which outlets it uses (optional). Interface Builder disables connections to outlets used by an EOAssociation, so if your subclass uses any it should advertise them by defining the objectKeysTaken class method to return an NSArray containing the names of the outlets. These are typically the standard “target”, “delegate”, “dataSource”, and so on.

EOAssociation classes superseded (optional). If your EOAssociation subclass applies uniquely to display objects that other kinds of EOAssociations simply happen to work with, it should implement the associationClassesSuperseded class method to return an array of these classes. EOPopUpAssociation, for example, works with EOPopUpButton, which as a subclass of NSControl is also eligible for the EOControlAssociation. Since this isn’t a meaningful or useful EOAssociation for a pop-up button, EOPopUpAssociation supersedes it, and Interface Builder doesn’t present it in its Connections Inspector when a pop-up button is selected.

Display name (optional). If you want your subclass to be listed in Interface Builder’s Associations pop-up list with a name other than that of its class, it can override the displayName to return that name. This is often done to truncate long names so they fit in the pop-up button.

Primary aspect (optional). If your subclass implements the primaryAspect class method, Interface Builder automatically selects it the first time the user drags a connection from the display object and chooses your EOAssociation subclass in the Connections Inspector.

Binding ability (optional). If your subclass defines aspects that are mutually exclusive, available only for a particular kind of display object, or are otherwise not always available, you might want to implement the instance method canBindAspect:displayGroup:key: to check these types of conditions. Interface Builder uses this information to enable and disable aspects, to guide the user in property setting up EOAssociations.

Priority (optional). EOAssociation uses the default EODelayedObserver priority of EODelayedObserverPriorityThird. If your subclass need a higher or lower priority, it should override the priority method appropriately. EOMasterDetailAssociation, for example, uses EODelayedObserverPrioritySecond to catch updates before other EOAssociations based on it.

Setting Up

EOAssociation’s designated initializer is initWithObject:, but you rarely need to override this method. Instead, you override establishConnection, which is where the real initialization takes place, as described above in “Setting up an EOAssociation Programmatically.” Your implementation of this method should invoke super’s implementation to establish the aspect bindings, which makes the EOAssociation an observer of its EODisplayGroups, then set the outlets and other state of the display object (and any associated objects). This usually takes the form of setTarget:, setDelegate:, and other messages to plug in the outlets, along with messages such as setAction: to register a method that your EOAssociation subclass implements and that should be invoked by the display object. For display objects that work with others, such as NSControls and NSCells, your subclass might even need to get the companion object to set something.

Once your EOAssociation object has tied itself to its EODisplayGroups and its display object, it’s ready to work.

Monitoring Changes from the EODisplayGroup

An EOAssociation is notified of changes in its EODisplayGroups through the subjectChanged method. This lets the EOAssociation object know that one or more of its EODisplayGroups has changed its selection or its contents, or both. Your EOAssociation can then query each of its EODisplayGroups for what’s changed, and update its display object accordingly. To get the EODisplayGroup for a given aspect, you can use the displayGroupForAspect: method, and to get the key it’s bound to, use displayGroupKeyForAspect:.

How your EOAssociation handles this message depends on whether the aspect represents a single value, as a text field does, or multiple values, as a table column or matrix does. A single-value aspect needs only to be updated with the new value. Your EOAssociation can do this by invoking its own valueForAspect: method and passing that value to the display object in whatever way necessary, such as with a setObjectValue: or setEnabled: message.

A multi-valued aspect requires a bit more care for efficiency’s sake. In this case, your EOAssociation should send the EODisplayGroup contentsChanged and selectionChanged messages to determine what has changed. If the contents have changed, your EOAssociation should reload all values for the aspect in question and update its display object accordingly. If only the selection has changed, your EOAssociation should simply get the selection indexes from the EODisplayGroup and update the selection in its display object, if appropriate. For aspects that don’t reflect the selection, your EOAssociation need do nothing.

Monitoring Changes from the Display Object

Changes in the display object make their way to your EOAssociation through whatever messages are defined for the outlets the EOAssociation took over. A control EOAssociation sends its display object a setAction: message to register an action method, which is then invoked when the uses clicks the button, edits text and presses Return, or otherwise operates the control. This method should then perform whatever operation is necessary, whether that be to update a value in the EODisplayGroup or send a message to the EODisplayGroup or to its enterprise objects. For example, an EOAssociation used to display a value must update the value of the selected enterprise object by invoking setValue:forAspect: with the “value” aspect. Another EOAssociation might be tied to a Grant Raise button that sends a raiseSalary message to the selected enterprise objects when the button is clicked.

EOAssociations that work with multiple EODisplayGroups and enterprise objects might need to interact more directly with the EODisplayGroups. They can retrieve the EODisplayGroup for a particular aspect using displayGroupForAspect:, and the key it’s bound by with displayGroupKeyForAspect:. Once it has these, the EOAssociation can send the EODisplayGroup setSelectedObjectValue:forKey:, setValue:forObject:key:, or setValue:forObjectAtIndex:key: messages as needed to effect its changes.

For display objects that must be edited to change their values, such as text fields, the EOAssociation must respond to messages indicating that the display object has begun and ended editing, and inform the EODisplayGroup for its primary or value aspect with associationDidBeginEditing: and associationDidEndEditing: messages. EODisplayGroups may need to end editing themselves, such as when saving changes. Your EOAssociation subclass should implement endEditing to handle this case by sending whatever value it currently has back to the EOAssociation using a setValue:forAspect: message. If it can’t do this, the EOAssociation should return NO to disallow whatever operation invoked endEditing.

EOAssociations for display objects that present multiple values must also monitor the selection in the display object, updating the EODisplayGroup with a setSelectionIndexes: message any time the selection changes in the display object.

Validation

Although validation of values entered by the user can happen in several places, EOAssociations generally concern themselves only with data entry errors. These errors are typically caught by the display object or an NSFormatter, and result in a message to the delegate of the display object. For example, an NSControl sends control:isValidObject: and control:didFailToFormatString:errorDescription: to its delegate, allowing the delegate to validate values itself or to handle errors caught by an NSFormatter. Your implementation of a method such as control:isValidObject: should simply try to save the new value, using EOAssociation’s setValue:forAspect: or setValue:forAspect:atIndex:, returning YES or NO as that message does. For control:didFailToFormatString:errorDescription:, the typical response should be to invoke shouldEndEditingForAspect:invalidInput:errorDescription: or shouldEndEditingForAspect:invalidInput:errorDescription:index:.

Adopted Protocols

NSCoding	− encodeWithCoder:

− initWithCoder:

Method Types

Declaring capabilities	+ aspects

+ aspectSignatures

+ objectKeysTaken

+ 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:

Class Methods

aspects

+ (NSArray *)aspects

Overridden by subclasses to return the names of the receiving class’s aspects, as NSStrings. Subclasses should include their superclass’s aspects and add their own when overriding this method.

See also:	+ aspectSignatures

aspectSignatures

+ (NSArray *)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.

See also:	+ aspects

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 for pop-up buttons an EOPopUpAssociation is always more appropriate to use.

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

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:	− initWithObject:, − establishConnection

breakConnection

− (void)breakConnection

Removes the receiver from its EODisplayGroup and display object. This causes it to be released, so be sure to retain the EOAssociation before invoking this method if you want to keep it for another use. Subclasses should override this method to remove the receiver from any outlets of the display object, such as target or delegate, and invoke super’s implementation at the end.

See also:	− establishConnection

canBindAspect:displayGroup:key:

− (BOOL)canBindAspect:(NSString *)aspectName

displayGroup:(EODisplayGroup *)aDisplayGroup

key:(NSString *)key

Overridden by subclasses to return YES if the receiver can tie an aspect named aspectName from its display object to the property identified by key in aDisplayGroup, NO 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 YES.

See also:	+ aspects, − localKeys (EODisplayGroup), − attributeKeys (EOClassDescription), − toOneRelationshipKeys (EOClassDescription), − toManyRelationshipKeys (EOClassDescription)

copyMatchingBindingsFromAssociation:

− (void)copyMatchingBindingsFromAssociation:(EOAssociation *)anAssociation

Duplicates the bindings of anAssociation in the receiver. For each aspect of anAssociation that has an EODisplayGroup, invokes bindAspect:displayGroup:key: with the EODisplayGroup and key for that aspect.

See also:	− displayGroupForAspect:, − displayGroupKeyForAspect:

displayGroupForAspect:

− (EODisplayGroup *)displayGroupForAspect:(NSString *)aspectName

Returns the EODisplayGroup bound to the receiver for aspectName, or nil if there’s no such object.

See also:	− displayGroupKeyForAspect:

displayGroupKeyForAspect:

− (NSString *)displayGroupKeyForAspect:(NSString *)aspectName

Returns the EODisplayGroup key bound to the receiver for aspectName, or nil if there’s no EODisplayGroup.

See also:	− displayGroupForAspect:

endEditing

− (BOOL)endEditing

Overridden by subclasses to pass the value of the receiver’s display object to the EODisplayGroup, by invoking setValue:forAspect: with the display object’s value and the appropriate aspect (typically “value”). Returns YES if successful, NO if not—specifically if setValue:forAspect: returns NO. 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 YES.

establishConnection

− (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 action method). EOAssociation’s implementation subscribes the receiver as an observer of its EODisplayGroups and causes the display object to retain the receiver. Subclasses should invoke super’s implementation after establishing their own connections.

See “Setting up an EOAssociation Programmatically” in the class description for more information.

See also:	− breakConnection

initWithObject:

− (id)initWithObject:(id)aDisplayObject

Initializes the receiver to monitor and update the value in aDisplayObject, which is typically a user-interface object or an EODisplayGroup. This is the designated initializer for the EOAssociation class. Returns self.

Note:	Because of the way that EOAssociations are set up, this method doesn’t retain aDisplayObject. See “Setting up an EOAssociation Programmatically” in the class description for more information.

See also:	− bindAspect:displayGroup:key:, − establishConnection

object

− (id)object

Returns the receiver’s display object.

See also:	− initWithObject:

setValue:forAspect:

− (BOOL)setValue:(id)value forAspect:(NSString *)aspectName

Sets a value of the selected enterprise object in the EODisplayGroup bound to aspectName. Retrieves the EODisplayGroup and key bound to aspectName, and sends the EODisplayGroup a setSelectedObjectValue:forKey: message with value and the key as arguments. Returns YES if successful, or if there’s no EODisplayGroup bound to aspectName. Returns NO if there’s an EODisplayGroup and it doesn’t accept the new value.

See also:	− setValue:forAspect:atIndex:, − valueForAspect:

setValue:forAspect:atIndex:

− (BOOL)setValue:(id)value

forAspect:(NSString *)aspectName

atIndex:(unsigned int)index

Sets a value of the enterprise object at index in the EODisplayGroup bound to aspectName. Retrieves the EODisplayGroup and key bound to aspectName, and sends the EODisplayGroup a setValue:forObjectAtIndex:key: message with value, index, and the key as arguments. Returns YES if successful, or if there’s no EODisplayGroup bound to aspectName. Returns NO if there’s an EODisplayGroup and it doesn’t accept the new value.

See also:	− setValue:forAspect:, − valueForAspect:atIndex:

shouldEndEditingForAspect:invalidInput:errorDescription:

− (BOOL)shouldEndEditingForAspect:(NSString *)aspectName

invalidInput:(NSString *)inputString

errorDescription:(NSString *)errorDescription

Invoked by subclasses when the display object fails to validate its input, this method informs the EODisplayGroup bound to aspectName with an association:failedToValidateValue:forKey:object:errorDescription: message, using the EODisplayGroup’s selected object. Returns the result of that message, or YES if there’s no EODisplayGroup.

For example, an EOAssociation tied to an NSControl object 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

Works in the same manner as shouldEndEditingForAspect:invalidInput:errorDescription:, but allows you to specify a particular object by index rather than implicitly specifying the selected object.

subjectChanged

− (void)subjectChanged

Overridden by subclasses to update its state based on its EODisplayGroups, whose selection or contents may have changed. This method is invoked automatically anytime an EODisplayGroup bound to the receiver changes. The receiver can query its EODisplayGroup with selectionChanged and contentsChanged messages to determine how it needs to update.

valueForAspect:

− (id)valueForAspect:(NSString *)aspectName

Returns a value of the selected enterprise object in the EODisplayGroup bound to aspectName. Retrieves the EODisplayGroup and key bound to aspectName, and sends the EODisplayGroup a selectedObjectValueForKey: message with the key. Returns nil if there’s no EODisplayGroup or key bound to aspectName.

See also:	− valueForAspect:atIndex:, − setValue:forAspect:

valueForAspect:atIndex:

− (id)valueForAspect:(NSString *)aspectName atIndex:(unsigned int)index

Returns a value of the enterprise object at index in the EODisplayGroup bound to aspectName. Retrieves the EODisplayGroup and key bound to aspectName, and sends the EODisplayGroup a valueForObjectAtIndex:key: message with index and the key. Returns nil if there’s no EODisplayGroup or key bound to aspectName.

See also:	− valueForAspect:, − setValue:forAspect:atIndex:


EOColumnAssociation

Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

Inherits From:	EOAssociation : EODelayedObserver : NSObject

Conforms To:	NSCoding (EOAssociation)

EOObserving (EODelayedObserver)

NSObject (NSObject)

Declared In:	EOInterface/EOColumnAssociation.h

Purpose

An EOColumnAssociation links an NSTableColumn to a single attribute of all displayed objects in an EODisplayGroup. The value of each object is displayed in its corresponding row.

Usable With

NSTableColumn

Aspects

value	An attribute of the objects, displayed in each row of the NSTableColumn.

enabled	A boolean attribute of the objects, which determines whether each object’s value cell is editable. Note that because EOTableViewAssociation also uses this aspect, you can use it with different keys to limit editability to the whole row or to an individual cell (column) in that row.

Object Keys Taken

identifier	An EOColumnAssociations sets itself as the identifer of its NSTableColumn. (Note: This key isn’t formally reserved by the objectKeysTaken method, as Interface Builder doesn’t treat it as an outlet.)

Class Description

EOColumnAssociations cooperate with an EOTableViewAssociation to display values in the columns of an NSTableView. The EOTableViewAssociation receives target, delegate, and data source messages from the NSTableView, and forwards them as needed to the appropriate EOColumnAssociation. The EOColumnAssociations provide values for the cells of each NSTableColumn, and also accept edited values to set in their EODisplayGroups.

EOColumnAssociations provide values using NSTableView’s tableView:setObjectValue:forTableColumn:row: and tableView:objectValueForTableColumn: methods. This allows values with non-string representations to be displayed. For example, if an NSImageCell is used as an NSTableColumn’s data cell, an EOColumnAssociation can be used to display NSImages in the NSTableView.

Example

To display the last and first names of objects in the Talent EODisplayGroup, bind two NSTableColumns to the “lastName” and “firstName” keys of the EODisplayGroup (this automatically creates an EOTableViewAssociation to manage the individual columns). When you run the application, the last and first names of each Talent object in the EODisplayGroup’s displayedObjects array are put in the correponding row.

Instance Methods

setSortingSelector:

− (void)setSortingSelector:(SEL)aSelector

Sets the method selector used to sort rows to aSelector, one of:

Defined Name	Selector

EOCompareAscending	compareAscending:

EOCompareDescending	compareDescending:

EOCompareCaseInsensitiveAscending	compareCaseInsensitiveAscending:

EOCompareCaseInsensitiveDescending	compareCaseInsensitiveDescending:

nil	(none; the column isn’t sorted)

If the EOTableViewAssociation for the receiver’s NSTableView sorts its rows, it applies this method as needed to sort them. The default sorting selector is EOCompareAscending. See the compare... methods in the Value Class Additions specification for details on the sorting methods.

See also:	− sortsByColumnOrder (NSTableViewAssociation), − sortingSelector

sortingSelector

− (SEL)sortingSelector

Returns the method selector used to sort rows, or nil if the column isn’t sorted.

See also:	− sortsByColumnOrder (NSTableViewAssociation), − setSortingSelector:

Delegate and Data Source Methods

These methods are forwarded by the NSTableView’s EOTableViewAssociation to the appropriate EOColumnAssociation.

control:isValidObject:

− (BOOL)control:(NSControl *)aTableView isValidObject:(id)anObject

Saves the value of any cell being edited using setValue:forAspect:, and if successful sends an associationDidEndEditing: message to the receiver’s EODisplayGroup. Returns YES if successful (or if no changes need be saved), NO if unsuccessful.

control:didFailToFormatString:errorDescription:

− (BOOL)control:(NSControl *)aTableView

didFailToFormatString:(NSString *)aString

errorDescription:(NSString *)errorDescription

Invokes shouldEndEditingForAspect:invalidInput:errorDescription: (defined by EOAssociation) and returns the result.

control:textShouldBeginEditing:

− (BOOL)control:(NSControl *)aTableView textShouldBeginEditing:(NSText *)fieldEditor

Sends an associationDidBeginEditing: message to the receiver’s EODisplayGroup and returns YES.

tableView:objectValueForTableColumn:row:

− (id)tableView:(NSTableView *)aTableView

objectValueForTableColumn:(NSTableColumn *)aTableColumn

row:(int)rowIndex

Returns the value of the property of the object at rowIndex bound to the value aspect.

tableView:setObjectValue:forTableColumn:row:

− (void)tableView:(NSTableView *)aTableView

setObjectValue:(id)value

forTableColumn:(NSTableColumn *)aTableColumn

row:(int)rowIndex

Sets the property of the object at rowIndex bound to the value aspect to value.

tableView:shouldEditTableColumn:row:

− (BOOL)tableView:(NSTableView *)aTableView

shouldEditTableColumn:(NSTableColumn *)aTableColumn

row:(int)rowIndex

Returns NO if the enabled aspect is bound and its value for the object at rowIndex is NO. Otherwise returns YES. Note that because the enabled aspects of EOTableViewAssociation and EOColumnAssociation can be bound to different keys, you can limit editability to the whole row or to an individual cell (column) in that row.

tableView:willDisplayCell:forTableColumn:row:

− (void)tableView:(NSTableView *)aTableView

willDisplayCell:(id)aCell

forTableColumn:(NSTableColumn *)aTableColumn

row:(int)rowIndex

Alters the display characteristics for aCell according to the values for the enabled aspect of the object at rowIndex.

See also:	− tableView:willDisplayCell:forTableColumn:row:


EOControlAssociation

Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

Inherits From:	EOGenericControlAssociation : EOAssociation : EODelayedObserver : NSObject

Conforms To:	NSCoding (EOAssociation)

EOObserving (EODelayedObserver)

NSObject (NSObject)

Declared In:	EOInterface/EOControlAssociation.h

Purpose

An EOControlAssociation displays a single attribute value in its display object (an NSControl) and updates that value in the selected object when the NSControl changes.

Usable With

Any NSControl

Aspects

value	An attribute of the selected object, displayed in the NSControl.

enabled	A boolean attribute of the selected object, which determines whether the NSControl is enabled.

Object Keys Taken

target	On receiving an action message from the NSControl, an EOControlAssociation sends the NSControl’s value to the EODisplayGroup.

delegate	An EOControlAssociation accepts messages related to editing and validation of text, such as control:textShouldBeginEditing: and control:didFailToFormatString:errorDescription:.

Class Description

EOControlAssociation is the default EOAssociation subclass for use with NSControls. An EOControlAssociation displays the value of the selected object in its NSControl, and updates the object when the NSControl’s value changes. A sibling class, EOActionCellAssociation, can be used with individual cells in an NSMatrix or NSForm. Some other subclasses of EOAssociation, such as EOPopUpAssociation and EOColumnAssociation, supersede these classes for more specialized behavior.

EOControlAssociations access values using NSControl’s setObjectValue: method, which allows values with non-string representations to be displayed. An EOControlAssociation can be bound to an NSImageView, for example, with an attribute whose class is NSImage.

Examples

To display a movie’s budget in an NSTextField, create an EOControlAssociation to the Movie display group and bind the value aspect to the “budget” key. If the NSTextField is editable, then when the user types a new value and presses Enter or Tab, the selected movie’s budget attribute is changed.

Assuming that Movie objects implement an isBudgetNegotiable method, you can make the NSTextField uneditable depending on the selected movie. To do so, add an “isBudgetNegotiable” key to the Movie display group in Interface Builder and bind the the “enabled” key to it.

Instance Methods

control

− (NSControl *)control

Returns the receiver’s control object (for EOControlAssociation this method is equivalent to EOAssociation’s object method).

editingAssociation

− (EOGenericControlAssociation *)editingAssociation

Returns self.


EODetailSelectionAssociation

Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

Inherits From:	EOAssociation : EODelayedObserver : NSObject

Conforms To:	NSCoding (EOAssociation)

EOObserving (EODelayedObserver)

NSObject (NSObject)

Declared In:	EOInterface/EODetailSelectionAssociation.h

Purpose

An EODetailSelectionAssociation binds the selection in one EODisplayGroup (the destination) to a relationship in another (the source), so that the destination EODisplayGroup acts as an editor for that relationship. The selection in the destination EODisplayGroup reflects the value of the relationship for the object selected in the source EODisplayGroup. Changing the selection in the destination EODisplayGroup changes the value of the relationship in the source EODisplayGroup.

Usable With

EODisplayGroup

Aspects

selectedObjects	A relationship from objects in the source EODisplayGroup.

Object Keys Taken

None

Class Description

An EODetailSelectionAssociation binds two EODisplayGroups together by a relationship, where the destination EODisplayGroup shows all possible values for the relationship, but indicates the actual members of the relationship by selecting them. The user can change the objects included in the relationship of the source by selecting and deselecting them in the destination.

EODetailSelectionAssociation is a useful alternative to EOMasterDetailAssociation and EOMasterPeerAssociation when it’s more important to add and remove objects from a relationship than it is to edit the attributes of those objects.

Example

Suppose that in your business model, an employee can be assigned any number of projects. A custom application shows this by having all employees listed in one table view, and all projects in another. When an employee is selected in the first table view, his assigned projects are selected in the other. To set up this kind of display, you use an EODetailSelectionAssociation between the Employee and Project EODisplayGroups, binding the selectedObjects aspect to the “projects” key. This causes the Projects table view to display all available projects and to highlight the ones assigned to the selected employee. The user can then add and remove projects from the selected employee by highlighting and unhighlighting them.


EODisplayGroup

Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

Inherits From:	NSObject

Conforms To:	NSCoding

NSObject (NSObject)

Declared In:	EOInterface/EODisplayGroup.h

Purpose

An EODisplayGroup collects an array of objects from an EODataSource, and works with a group of EOAssociation objects to display and edit the properties of those objects.

Principal Attributes

•	Array of objects supplied by an EODataSource

•	EOQualifier and EOSortOrderings to filter the objects for display

•	Array of selection indexes

•	Delegate

Creation

Interface Builder

− init	Designated initializer.

Commonly Used Methods

− allObjects	Returns all objects in the EODisplayGroup.

− displayedObjects	Returns the subset of all objects made available for display.

− selectedObjects	Returns the selected objects.

− setQualifier:	Sets a filter that limits the objects displayed.

− setSortOrdering:	Sets the ordering used to sort the objects.

− updateDisplayedObjects	Filters, sorts, and redisplays the objects.

− insertObjectAtIndex:	Creates a new object and inserts it into the EODataSource.

Class Description

An EODisplayGroup is the basic user interface manager for an Enterprise Objects Framework application. It collects objects from an EODataSource, filters and sorts them, and maintains a selection in the filtered subset. It interacts with user interface objects and other display objects through EOAssociations, which bind the values of objects to various aspects of the display objects.

An EODisplayGroup manipulates its EODataSource by sending it fetchObjects, insertObject:, and other messages, and registers itself as an editor and message handler of the EODataSource’s EOEditingContext. The EOEditingContext then monitors the EODisplayGroup for changes to objects and allows it to intercede in certain operations, as described in the EOEditors and EOMessageHandlers informal protocol specifications. EODisplayGroup implements all the methods of these informal protocols; see the descriptions for editingContextWillSaveChanges:, editorHasChangesForEditingContext:, and editingContext:presentErrorMessage: for more information.

Most of an EODisplayGroup’s interactions are with its associations, its EODataSource, and its EOEditingContext. See the EOAssociation, EODataSource, and EOEditingContext class specifications for more information on these interactions.

Creating an EODisplayGroup

You create most EODisplayGroups in Interface Builder, by dragging an entity icon from the EOModeler application, which creates an EODisplayGroup with an EODataSource, or by dragging an EODisplayGroup with no EODataSource from the EOPalette. EODisplayGroups with EODataSources operate independent of other EODisplayGroups, while those without EODataSources must be set up in a master-detail association with another EODisplayGroup. See Chapter 4, “Creating an Enterprise Objects Framework Project” in the Enterprise Objects Framework Developer’s Guide for more information on setting up EODisplayGroups in Interface Builder.

To create an EODisplayGroup programmatically, simply initialize it and set its EODataSource:

EODataSource *myDataSource;    /* Assume this exists. */

EODisplayGroup *myDisplayGroup;

myDisplayGroup = [[EODisplayGroup alloc] init];

[myDisplayGroup setDataSource:myDataSource];

After creating the EODisplayGroup, you can add associations as described in the EOAssociation class specification under “Setting up an Association Programmatically.”

Getting Objects

Since an EODisplayGroup isn’t much use without objects to manage, the first thing you do with an EODisplayGroup is send it a fetch message. You can use the basic fetch method; the fetch: action method, which can be invoked by a control in the EODisplayGroup’s nib file; or, you can configure the EODisplayGroup in Interface Builder to fetch automatically when its nib file is loaded. These methods all ask the EODisplayGroup’s EODataSource to fetch from its persistent store with a fetchObjects message.

Filtering and Sorting

An EODisplayGroup’s fetched objects are available through its allObjects method. These objects are treated only as candidates for display, however. The array of objects actually displayed is filtered and sorted by the EODisplayGroup’s delegate, or by a qualifier and sort ordering array. You set the qualifier and sort orderings using the setQualifier: and setSortOrdering: methods. The displayedObjects method returns this filtered and sorted array; index arguments to other EODisplayGroup methods are defined in terms of this array.

If the EODisplayGroup has a delegate that responds to displayGroup:displayArrayForObjects:, it invokes this method rather than using its own qualifier and sort ordering array. The delegate is then responsible for filtering the objects and returning a sorted array. If the delegate only needs to perform one of these steps, it can get the qualifier or sort orderings from the EODisplayGroup and apply either itself using the NSArray methods filteredArrayUsingQualifier: and sortedArrayUsingKeyOrderArray:, which are added by the control layer.

If you change the qualifier or sort ordering, or alter the delegate in a way that changes how it filters and sorts the EODisplayGroup’s objects, you can send updateDisplayedObjects to the EODisplayGroup to get it to refilter and resort its objects. Note that this doesn’t cause the EODisplayGroup to refetch.

Changing and Examining the Selection

An EODisplayGroup keeps a selection in terms of indexes into the array of displayed objects. EOAssociations that display values for multiple objects are responsible for updating the selection in their EODisplayGroups according to user actions on their display objects. This is typically done with the setSelectionIndexes: method. Other methods available for indirect manipulation of the selection are the action methods selectNext: and selectPrevious:, as well as selectObjectsIdenticalTo: and selectObjectsIdenticalTo:selectFirstOnNoMatch:.

To get the selection, you can use the selectionIndexes method, which returns an array of NSNumbers, or selectedObjects, which returns an array containing the selected objects themselves. Another method, selectedObject, returns the first selected object if there is one.

The Delegate

EODisplayGroup offers a number of methods for its delegate to implement; if the delegate does, it invokes them as appropriate. Besides the aforementioned displayGroup:displayArrayForObjects:, there are methods that inform the delegate that the EODisplayGroup has fetched, created an object (or failed to create one), inserted or deleted an object, changed the selection, or set a value for a property. There are also methods that request permission from the delegate to perform most of these same actions. The delegate can return YES to permit the action or NO to deny it. See each method’s description, at the end of this class specification, for more information.

Methods for Use by EOAssociations

While most of your application code interacts with objects directly, EODisplayGroup also defines methods for its associations to access properties of individual objects without having to know anything about which methods they implement. Accessing properties through the EODisplayGroup offers associations the benefit of automatic validation, as well.

Associations access objects by index into the displayed objects array, or by id. valueForObjectAtIndex:key: returns the value of a named property for the object at a given index, and setValue:forObjectAtIndex:key: sets it. Similarly, valueForKey:object: and setValue:forObject:key:access the objects by id. EOAssociations can also get and set values for the first object in the selection using selectedObjectValueForKey: and setSelectedObjectValue:forKey:.

Adopted Protocols

NSCoding	− encodeWithCoder:

− initWithCoder:

Method Types

Creating instances	− init

Configuring behavior	− setFetchesOnLoad:

− fetchesOnLoad

− setSelectsFirstObjectAfterFetch:

− selectsFirstObjectAfterFetch

− setUsesOptimisticRefresh:

− usesOptimisticRefresh

− setValidatesChangesImmediately:

− validatesChangesImmediately

Setting the data source	− setDataSource:

− dataSource

Setting the qualifier and sort ordering

− setQualifier:

− qualifier

− setSortOrdering:

− sortOrdering

Fetching objects from the data source

− fetch

− fetch:

Getting the objects	− allObjects

− displayedObjects

Updating display of values	− redisplay

− updateDisplayedObjects

Setting the objects	− setObjectArray:

Changing the selection	− setSelectionIndexes:

− selectObjectsIdenticalTo:

− selectObjectsIdenticalTo:selectFirstOnNoMatch:

− clearSelection

− selectNext

− selectNext:

− selectPrevious

− selectPrevious:

Examining the selection	− selectionIndexes

− selectedObject

− selectedObjects

Inserting and deleting objects	− insertObject:atIndex:

− insertObjectAtIndex:

− insert:

− deleteObjectAtIndex:

− deleteSelection

− delete:

Adding keys	− setLocalKeys:

− localKeys

Getting the associations	− observingAssociations

Setting the delegate	− setDelegate:

− delegate

Changing values from associations	− setSelectedObjectValue:forKey:

− selectedObjectValueForKey:

− setValue:forObject:key:

− valueForKey:object:

− setValue:forObjectAtIndex:key:

− valueForObjectAtIndex:key:

Editing by associations	− associationDidBeginEditing:

− association:failedToValidateValue:forKey:object:errorDescription:

− associationDidEndEditing:

− editingAssociation

− endEditing

Querying changes for associations	− contentsChanged

− selectionChanged

− updatedObjectIndex

Interacting with the EOEditingContext

− editorHasChangesForEditingContext:

− editingContextWillSaveChanges:

− editingContext:presentErrorMessage:

Instance Methods

allObjects

− (NSArray *)allObjects

Returns all of the objects collected by the receiver.

See also:	− displayedObjects, − fetch

association:failedToValidateValue:forKey:object:errorDescription:

− (BOOL)association:(EOAssociation *)anAssociation

failedToValidateValue:(NSString *)value

forKey:(NSString *)key

object:(id)anObject

errorDescription:(NSString *)errorDescription

Invoked by anAssociation from its shouldEndEditingForAspect:invalidInput:errorDescription:... method to let the receiver handle a validation error. This method opens an attention panel with errorDescription as the message and returns NO.

See also:	− displayGroup:shouldDisplayAlertWithTitle:message: (Methods Implemented By the Delegate)

associationDidBeginEditing:

− (void)associationDidBeginEditing:(EOAssociation *)anAssociation

Invoked by anAssociation when its display object begins editing to record that EOAssociation as the editing association.

See also:	− editingAssociation, − associationDidEndEditing:, − endEditing, − association:failedToValidateValue:forKey:object:errorDescription:

associationDidEndEditing:

− (void)associationDidEndEditing:(EOAssociation *)anAssociation

Invoked by anAssociation to clear the editing association. If anAssociation is the receiver’s editing association, clears the editing association. Otherwise does nothing.

See also:	− editingAssociation, − associationDidBeginEditing:, − endEditing, − association:failedToValidateValue:forKey:object:errorDescription:

clearSelection

− (BOOL)clearSelection

Invokes setSelectionIndexes: to clear the selection, returning YES on success and NO on failure.

contentsChanged

− (BOOL)contentsChanged

Returns YES if the receiver’s array of objects has changed and not all observers have been notified, NO otherwise. EOAssociations use this in their subjectChanged methods to determine what they need to update.

See also:	− selectionChanged, − updatedObjectIndex

dataSource

− (EODataSource *)dataSource

Returns the receiver’s EODataSource.

See also:	− setDataSource:

delegate

− (id)delegate

Returns the receiver’s delegate.

See also:	− setDelegate:

delete:

− (void)delete:(id)sender

This action method invokes deleteSelection.

See also:	− deleteObjectAtIndex:

deleteObjectAtIndex:

− (BOOL)deleteObjectAtIndex:(unsigned int)index

Attempts to delete the object at index, returning YES if successful and NO if not. Checks with the delegate using displayGroup:shouldDeleteObject:. If the delegate returns NO, this method fails and returns NO. If successful, sends the delegate a displayGroup:didDeleteObject: message.

This method performs the delete by sending deleteObject: to the EODataSource. If that message raises an exception, this method fails and returns NO.

See also:	− deleteSelection, − delete:

deleteSelection

− (BOOL)deleteSelection

Attempts to delete the selected objects, returning YES if successful and NO if not.

See also:	− deleteObjectAtIndex:, − delete:

displayedObjects

− (NSArray *)displayedObjects

Returns the objects that should be displayed or otherwise made available to the user, as filtered by the receiver’s delegate or by its qualifier and sort ordering.

See also:	− allObjects, − updateDisplayedObjects, − displayGroup:displayArrayForObjects: (Methods Implemented By the Delegate), − qualifier, − sortOrdering

editingAssociation

− (EOAssociation *)editingAssociation

Returns the EOAssociation editing a value if there is one, NO if there isn’t.

See also:	− associationDidBeginEditing:, − associationDidEndEditing:

editingContext:presentErrorMessage:

− (void)editingContext:(EOEditingContext *)anEditingContext presentErrorMessage:(NSString *)errorMessage

Invoked by anEditingContext as part of the EOMessageHandlers informal protocol, this method calls NSRunAlertPanel() with no title, errorMessage as the message to display, and an OK button.

editingContextWillSaveChanges:

− (void)editingContextWillSaveChanges:(EOEditingContext *)anEditingContext

Invoked by anEditingContext in its saveChanges method as part of the EOEditors informal protocol, this method allows the EODisplayGroup to prohibit a save operation. EODisplayGroup’s implementation of this method invokes endEditing, and raises an NSInternalInconsistencyException if it returns NO. Thus, if there’s an association that refuses to end editing, anEditingContext doesn’t save changes.

editorHasChangesForEditingContext:

− (BOOL)editorHasChangesForEditingContext:(EOEditingContext *)anEditingContext

Invoked by anEditingContext as part of the EOEditors informal protocol, this method returns NO if any association is editing, YES otherwise.

See also:	− editingAssociation, − associationDidBeginEditing:, − associationDidEndEditing:

endEditing

− (BOOL)endEditing

Attempts to end any editing taking place. If there’s no editing association or if the editing association responds YES to an endEditing message, returns YES. Otherwise returns NO.

See also:	− editingAssociation

fetch

− (BOOL)fetch

Attempts to fetch objects from the EODataSource, returning YES on success and NO on failure.

Before fetching, invokes endEditing and sends displayGroupShouldFetch: to the delegate, returning NO if either of these methods does. If both return YES, sends a fetchObjects message to the receiver’s EODataSource to replace the object array, and if successful sends the delegate a displayGroup:didFetchObjects: message.

See also:	− fetch:

fetch:

− (void)fetch:(id)sender

This action method invokes fetch.

fetchesOnLoad

− (BOOL)fetchesOnLoad

Returns YES if the receiver fetches automatically after being loaded from a nib file, NO if it must be told explicitly to fetch. The default is NO. You can set this behavior in Interface Builder using the Inspector panel.

See also:	− fetch, − fetch:, − setFetchesOnLoad:

init

− (id)init

Initializes a newly allocated EODisplayGroup. The new EODisplayGroup then needs to have an EODataSource set with setDataSource:. This is the designated initializer for the EODisplayGroup class. Returns self.

See also:	− bindAspect:displayGroup:key: (EOAssociation)

insert:

− (void)insert:(id)sender

This action method invokes insertObjectAtIndex: with an index just past the first index in the selection, or 0 if there’s no selection.

See also:	− insertObject:atIndex:

insertObject:atIndex:

− (void)insertObject:(id)anObject atIndex:(unsigned int)index

Inserts anObject into the receiver’s EODataSource and displayed objects at index, if possible. This method checks with the delegate before actually inserting, using displayGroup:shouldInsertObject:atIndex:. If the delegate refuses, anObject isn’t inserted. After successfully inserting the object, this method informs the delegate with a displayGroup:didInsertObject: message, and selects the newly inserted object.

Raises an NSRangeException if index is out of bounds.

See also:	− insertObjectAtIndex:, − insert:

insertObjectAtIndex:

− (id)insertObjectAtIndex:(unsigned int)anIndex

Asks the receiver’s EODataSource to create a new object by sending it a createObject message, then inserts the new object using insertObject:atIndex:. If a new object can’t be created, this method sends the delegate a displayGroup:createObjectFailedForDataSource: message or, if the delegate doesn’t respond, opens an attention panel to inform the user of the error.

See also:	− insert:

localKeys

− (NSArray *)localKeys

Returns the additional keys that EOAssociations can be bound to. An EODisplayGroup’s basic keys are typically those of the attributes and relationships of its objects, as defined by their EOClassDescription through an EOEntity in the model. Local keys are typically used to form associations with key paths, with arbitrary methods of objects, or with properties of objects not associated with an EOEntity. Interface Builder allows the user to add and remove local keys in the EODisplayGroup Attributes Inspector panel.

See also:	− setLocalKeys:

observingAssociations

− (NSArray *)observingAssociations

Returns all EOAssociations that observe the receiver’s objects.

See also:	+ observersForObject: (EOObserverCenter)

qualifier

− (EOQualifier *)qualifier

Returns the receiver’s qualifier, which it uses to filter its array of objects for display when the delegate doesn’t do so itself.

See also:	− updateDisplayedObjects, − displayedObjects, − setQualifier:

redisplay

− (void)redisplay

Notifies all observing associations to redisplay their values.

See also:	− observingAssociations

selectedObject

− (id)selectedObject

Returns the first selected object in the displayed objects array, or nil if there’s no such object.

See also:	− displayedObjects, − selectionIndexes, − selectedObjects

selectedObjects

− (NSArray *)selectedObjects

Returns the objects selected in the receiver’s displayed objects array.

See also:	− displayedObjects, − selectionIndexes, − selectedObject

selectedObjectValueForKey:

− (id)selectedObjectValueForKey:(NSString *)key

Returns the value corresponding to key for the first selected object in the receiver’s displayed objects array, or nil if exactly one object isn’t selected.

See also:	− valueForKey:object:

selectionChanged

− (BOOL)selectionChanged

Returns YES if the selection has changed and not all observers have been notified, NO otherwise. EOAssociations use this in their subjectChanged methods to determine what they need to update.

See also:	− contentsChanged

selectionIndexes

− (NSArray *)selectionIndexes

Returns the indexes of the receiver’s selected objects as NSNumbers, in terms of its displayed objects array.

See also:	− displayedObjects, − selectedObjects, − selectedObject, − setSelectionIndexes:

selectNext

− (BOOL)selectNext

Attempts to select the object just after the currently selected one, returning YES if successful and NO if not. The selection is altered in this way:

•	If there are no objects, does nothing and returns NO.

•	If there’s no selection, selects the object at index zero and returns YES.

•	If the first selected object is the last object in the displayed objects array, selects the first object and returns YES.

•	Otherwise selects the object after the first selected object.

See also:	− selectPrevious, − selectNext:, − setSelectionIndexes:

selectNext:

− (void)selectNext:(id)sender

This action method invokes selectNext.

See also:	− selectPrevious:, − setSelectionIndexes:

selectObjectsIdenticalTo:

− (BOOL)selectObjectsIdenticalTo:(NSArray *)objects

Attempts to select the objects in the receiver’s displayed objects array whose ids are equal to those of objects, returning YES if successful and NO otherwise.

See also:	− setSelectionIndexes:, − selectObjectsIdenticalTo:selectFirstOnNoMatch:

selectObjectsIdenticalTo:selectFirstOnNoMatch:

− (BOOL)selectObjectsIdenticalTo:(NSArray *)objects selectFirstOnNoMatch:(BOOL)flag

Selects the objects in the receiver’s displayed objects array whose ids are equal to those of objects, returning YES if successful and NO otherwise. If no objects in the displayed objects array match objects and flag is YES, attempts to select the first object in the displayed objects array.

See also:	− setSelectionIndexes:, − selectObjectsIdenticalTo:

selectPrevious

− (BOOL)selectPrevious

Attempts to select the object just before the presently selected one, returning YES if successful and NO if not. The selection is altered in this way:

•	If there are no objects, does nothing and returns NO.

•	If there’s no selection, selects the object at index zero and returns YES.

•	If the first selected object is at index zero, selects the last object and returns YES.

•	Otherwise selects the object before the first selected object.

See also:	− selectNext, − selectPrevious:, − redisplay

selectPrevious:

− (void)selectPrevious:(id)sender

This action method invokes selectPrevious.

See also:	− selectNext:, − redisplay

selectsFirstObjectAfterFetch

− (BOOL)selectsFirstObjectAfterFetch

Returns YES if the receiver automatically selects its first displayed object after a fetch if there was no selection, NO if it leaves an empty selection as-is.

EODisplayGroups by default do select the first object after a fetch when there was no previous selection.

See also:	− displayedObjects, − fetch, − selectsFirstObjectAfterFetch

setDataSource:

− (void)setDataSource:(EODataSource *)aDataSource

Sets the receiver’s EODataSource to aDataSource. In the process, it performs these actions:

•	Unregisters self as an editor and message handler for the previous EODataSource’s EOEditingContext, if necessary, and registers self with aDataSource’s EOEditingContext. If the new EOEditingContext already has a message handler, however, the receiver doesn’t assume that role.

•	Registers self for EOObjectsChangedInEditingContextNotification and EOInvalidatedAllObjectsInStoreNotification from the new EOEditingContext.

•	Clears the receiver’s array of objects.

•	Sends displayGroupDidChangeDataSource: to the delegate if there is one.

See also:	− dataSource

setDelegate:

− (void)setDelegate:(id)anObject

Sets the receiver’s delegate to anObject, without retaining it.

See also:	− delegate

setFetchesOnLoad:

− (void)setFetchesOnLoad:(BOOL)flag

Controls whether the receiver automatically fetches its objects after being loaded from a nib file. If flag is YES it does; if flag is NO the receiver must be told explicitly to fetch. The default is NO. You can also set this behavior in Interface Builder using the Inspector panel.

See also:	− fetch, − fetch:, − fetchesOnLoad

setLocalKeys:

− (void)setLocalKeys:(NSArray *)keys

Sets the additional keys to which EOAssociations can be bound to keys. Interface Builder allows the user to add and remove local keys in the EODisplayGroup Attributes Inspector panel. See localKeys for more information.

setObjectArray:

− (void)setObjectArray:(NSArray *)objects

Sets the receiver’s objects to objects, regardless of what its EODataSource provides. This method doesn’t affect the EODataSource’s objects at all; specifically, it results in neither inserts or deletes of objects in the EODataSource. objects should contain objects with the same property names or methods as those accessed by the receiver. This method is used by fetch to set the array of fetched objects; you should rarely need to invoke it directly.

After setting the object array, this method restores as much of the original selection as possible by invoking selectObjectsIdenticalTo:selectFirstOnNoMatch:. If there’s no match and the receiver selects after fetching, then the first object is selected.

See also:	− allObjects, − displayedObjects, − selectsFirstObjectAfterFetch

setQualifier:

− (void)setQualifier:(EOQualifier *)aQualifier

Sets the receiver’s qualifier to aQualifier. This qualifier is used to filter the receiver’s array of objects for display when the delegate doesn’t do so itself. Use updateDisplayedObjects to apply the qualifier.

If the receiver’s delegate responds to displayGroup:displayArrayForObjects:, that method is used instead of the qualifier to filter the objects.

See also:	+ qualifierWithQualifierFormat: (EOQualifier class of the control layer), − updateDisplayedObjects, − displayedObjects, − qualifier

setSelectedObjectValue:forKey:

− (BOOL)setSelectedObjectValue:(id)value forKey:(NSString *)key

Invokes setValue:forObject:key: with the first selected object, returning YES if successful and NO otherwise. This method should be invoked only by EOAssociation objects to propagate changes from display objects.

See also:	− setValue:forObjectAtIndex:key:, − valueForKey:object:

setSelectionIndexes:

− (BOOL)setSelectionIndexes:(NSArray *)indexes

Selects the objects at indexes in the receiver’s array if possible, returning YES if successful and NO if not (in which case the selection remains unaltered). indexes is an array of NSNumbers. This method is the primitive method for altering the selection; all other such methods invoke this one to make the change.

This method invokes endEditing to wrap up any changes being made by the user. If endEditing returns NO, this method fails and returns NO. This method then checks the delegate with a displayGroup:shouldChangeSelectionToIndexes: message. If the delegate returns NO, this method also fails and returns NO. If the receiver successfully changes the selection, its observers each receive a subjectChanged message.

See also:	− allObjects

setSelectsFirstObjectAfterFetch:

− (void)setSelectsFirstObjectAfterFetch:(BOOL)flag

Controls whether the receiver automatically selects its first displayed object after a fetch when there were no selected objects before the fetch. If flag is YES it does; if flag is NO then no objects are selected.

EODisplayGroups by default do select the first object after a fetch when there was no previous selection.

See also:	− displayedObjects, − fetch, − selectsFirstObjectAfterFetch

setSortOrdering:

− (void)setSortOrdering:(NSArray *)orderings

Sets the EOSortOrdering objects that updateDisplayedObjects uses to sort the displayed objects to orderings. Use updateDisplayedObjects to apply the sort orderings.

If the receiver’s delegate responds to displayGroup:displayArrayForObjects:, that method is used instead of the sort orderings to order the objects.

See also:	+ sortOrderingWithKey:selector: (EOSortOrdering class of the control layer), − displayedObjects, − sortOrdering

setUsesOptimisticRefresh:

− (void)setUsesOptimisticRefresh:(BOOL)flag

Controls how the receiver redisplays on changes to objects. If flag is YES it redisplays only when elements of its displayed objects array change; if flag is NO it redisplays on any change in its EOEditingContext. Because changes to other objects can affect the displayed objects (through flattened attributes or custom methods, for example), EODisplayGroups by default use the more pessimistic refresh technique of redisplaying on any change in the EOEditingContext. If you know that none of the EOAssociations for a particular EODisplayGroup display derived values, you can turn on optimistic refresh to reduce redisplay time.

The default is NO. You can also change this setting in Interface Builder’s Inspector panel using the Refresh All check box.

See also:	− usesOptimisticRefresh

setValidatesChangesImmediately:

− (void)setValidatesChangesImmediately:(BOOL)flag

Controls the receiver’s behavior on encountering a validation error. Whenever an EODisplayGroup sets a value in an object, it sends the object a validateValue:forKey: message, allowing the object to coerce the value’s type to a more appropriate one or to return an exception indicating that the value isn’t valid. If this method is invoked with a flag of YES, the receiver immediately presents an attention panel indicating the validation error. If this method is invoked with a flag of NO, the receiver leaves validation errors to be handled when changes are saved.

EODisplayGroups by default don’t validate changes immediately.

See also:	− saveChanges (EOEditingContext), − validatesChangesImmediately

setValue:forObject:key:

− (BOOL)setValue:(id)value

forObject:(id)anObject

key:(NSString *)key

Sets a property of anObject, identified by key, to value. Returns YES if successful and NO otherwise. If a new value is set, sends the delegate a displayGroup:didSetValue:forObject:key: message.

This method should be invoked only by EOAssociation objects to propagate changes from display objects. Other application code should interact with the objects directly.

If the receiver validates changes immediately, it sends anObject a validateValue:forKey: message, returning NO if the object refuses to validate value. Otherwise, validation errors are checked by the EOEditingContext when it attempts to save changes.

See also:	− setValue:forObjectAtIndex:key:, − setSelectedObjectValue:forKey:, − valueForKey:object:, − validatesChangesImmediately

setValue:forObjectAtIndex:key:

− (BOOL)setValue:(id)value

forObjectAtIndex:(unsigned int)index

key:(NSString *)key

Invokes setValue:forObject:key: with the object at index, returning YES if successful and NO otherwise. This method should be invoked only by EOAssociation objects to propagate changes from display objects.

See also:	− setSelectedObjectValue:forKey:,− valueForObjectAtIndex:key:

sortOrdering

− (NSArray *)sortOrdering

Returns an array of EOSortOrdering objects that updateDisplayedObjects uses to sort the displayed objects, as returned by the displayedObjects method.

See also:	− setSortOrdering:

updateDisplayedObjects

− (void)updateDisplayedObjects

Recalculates the receiver’s displayed objects array and redisplays. If the delegate responds to displayGroup:displayArrayForObjects:, it’s sent this message and the returned array is set as the EODisplayGroup’s displayed object. Otherwise, the receiver applies its qualifier and sort ordering to its array of objects. In either case, any objects that were selected before remain selected in the new displayed objects array.

See also:	− redisplay, − allObjects, − displayedObjects, − selectedObjects, − qualifier, − sortOrdering

updatedObjectIndex

− (int)updatedObjectIndex

Returns the index in the displayed objects array of the most recently updated object, or −1 if more than one object has changed. The return value is meaningful only when contentsChanged returns YES. Associations can use this method to optimize redisplay of their user interface objects.

usesOptimisticRefresh

− (BOOL)usesOptimisticRefresh

Returns YES if the receiver redisplays only when elements of its displayed objects array change, NO if it redisplays on any change in its EOEditingContext. Because changes to other objects can affect the displayed objects (through flattened attributes or custom methods, for example), EODisplayGroups by default use the more pessimistic refresh technique of redisplaying on any change in the EOEditingContext. If you know that none of the EOAssociations for a particular EODisplayGroup display derived values, you can turn on optimistic refresh to reduce redisplay time.

The default is NO. You can change this setting in Interface Builder’s Inspector panel using the Refresh All check box.

See also:	− setUsesOptimisticRefresh:

validatesChangesImmediately

− (BOOL)validatesChangesImmediately

Returns YES if the receiver immediately handles validation errors, or leaves them for the EOEditingContext to handle when saving changes. See setValidatesChangesImmediately: for more information.

EODisplayGroups by default don’t validate changes immediately.

valueForKey:object:

− (id)valueForKey:(NSString *)key object:(id)anObject

Returns anObject’s value for the property identified by key.

See also:	− valueForObjectAtIndex:key:

valueForObjectAtIndex:key:

− (id)valueForObjectAtIndex:(unsigned int)index key:(NSString *)key

Returns the value of the object at index for the property identified by key.

See also:	− valueForKey:object:

Methods Implemented By the Delegate

displayGroup:createObjectFailedForDataSource:

− (void)displayGroup:(EODisplayGroup *)aDisplayGroup createObjectFailedForDataSource:(id)aDataSource

Invoked from insertObjectAtIndex: to inform the delegate that aDisplayGroup has failed to create a new object for aDataSource. If the delegate doesn’t implement this method, the EODisplayGroup instead runs an alert panel to inform the user of the failure.

displayGroupDidChangeDataSource:

− (void)displayGroupDidChangeDataSource:(EODisplayGroup *)aDisplayGroup

Informs the delegate that aDisplayGroup’s EODataSource has changed.

displayGroup:didDeleteObject:

− (void)displayGroup:(EODisplayGroup *)aDisplayGroup didDeleteObject:(id)anObject

Informs the delegate that aDisplayGroup has deleted anObject.

displayGroup:didFetchObjects:

− (void)displayGroup:(EODisplayGroup *)aDisplayGroup didFetchObjects:(NSArray *)objects

Informs the delegate that aDisplayGroup has fetched objects.

displayGroup:didInsertObject:

− (void)displayGroup:(EODisplayGroup *)aDisplayGroup didInsertObject:(id)anObject

Informs the delegate that aDisplayGroup has inserted anObject.

displayGroup:didSetValue:forObject:key:

− (void)displayGroup:(EODisplayGroup *)aDisplayGroup

didSetValue:(id)value

forObject:(id)anObject

key:(NSString *)key

Informs the delegate that aDisplayGroup has altered a property value of anObject. key identifies the property, and value is its new value.

displayGroup:displayArrayForObjects:

− (NSArray *)displayGroup:(EODisplayGroup *)aDisplayGroup displayArrayForObjects:(NSArray *)objects

Invoked from updateDisplayedObjects, this method allows the delegate to filter and sort aDisplayGroup’s array of objects to limit which ones get displayed. objects contains all of aDisplayGroup’s objects. The delegate should filter any objects that shouldn’t be shown and sort the remainder, returning a new array containing this group of objects. You can use the added NSArray methods filteredArrayUsingQualifier: and sortedArrayUsingKeyOrderArray: to create the new array.

If the delegate doesn’t implement this method, the EODisplayGroup uses its own qualifier and sort ordering to update its displayed objects array.

See also:	− sortOrdering, − qualifier, − displayedObjects

displayGroup:shouldChangeSelectionToIndexes:

− (BOOL)displayGroup:(EODisplayGroup *)aDisplayGroup shouldChangeSelectionToIndexes:(NSArray *)newIndexes

Allows the delegate to prevent a change in selection by aDisplayGroup. newIndexes is the proposed new selection, an array of NSNumbers. If the delegate returns YES, the selection changes; if the delegate returns NO, the selection remains as it is.

displayGroup:shouldDeleteObject:

− (BOOL)displayGroup:(EODisplayGroup *)aDisplayGroup shouldDeleteObject:(id)anObject

Allows the delegate to prevent aDisplayGroup from deleting anObject. If the delegate returns YES, anObject is deleted; if the delegate returns NO, the deletion is abandoned.

displayGroup:shouldDisplayAlertWithTitle:message:

− (BOOL)displayGroup:(EODisplayGroup *)aDisplayGroup

shouldDisplayAlertWithTitle:(NSString *)title

message:(NSString *)message

Allows the delegate to prevent aDisplayGroup from displaying an attention panel with title and message. The delegate can return YES to allow aDisplayGroup to display the panel, or NO to prevent it from doing so (perhaps displaying a different attention panel).

displayGroup:shouldInsertObject:atIndex:

− (BOOL)displayGroup:(EODisplayGroup *)aDisplayGroup

shouldInsertObject:(id)anObject

atIndex:(unsigned int)anIndex

Allows the delegate to prevent aDisplayGroup from inserting anObject at anIndex. If the delegate returns YES, anObject is inserted; if the delegate returns NO, the insertion is abandoned.

displayGroup:shouldRedisplayForChangesInEditingContext:

− (BOOL)displayGroup:(EODisplayGroup *)aDisplayGroup shouldRedisplayForEditingContextChangeNotification:(NSNotification *)aNotification

Invoked whenever aDisplayGroup receives an EOObjectsChangedInEditingContextNotification, this method allows the delegate to suppress redisplay based on the nature of the change that has occurred. If the delegate returns YES, aDisplayGroup redisplays; if it returns NO, aDisplayGroup doesn’t. aNotification indicates the EOEditingContext that has changed, as well as which objects have changed and how. See the EOEditingContext class specification for information on EOObjectsChangedInEditingContextNotification.

See also:	− redisplay

displayGroup:shouldRefetchForInvalidatedAllObjectsNotification:

− (BOOL)displayGroup:(EODisplayGroup *)aDisplayGroup shouldRefetchForInvalidatedAllObjectsNotification:(NSNotification *)aNotification

Invoked whenever aDisplayGroup receives an EOInvalidatedAllObjectsInStoreNotification, this method allows the delegate to suppress refetching of the invalidated objects. If the delegate returns YES, aDisplayGroup immediately refetches its objects. If the delegate returns NO, aDisplayGroup doesn’t immediately fetch, instead delaying until absolutely necessary. aNotification is an NSNotification. See the EOObjectStore and EOEditingContext class specifications for information on this notification.

displayGroupDidChangeSelection:

− (void)displayGroupDidChangeSelection:(EODisplayGroup *)aDisplayGroup

Informs the delegate that aDisplayGroup’s selection has changed.

displayGroupShouldFetch:

− (BOOL)displayGroupShouldFetch:(EODisplayGroup *)aDisplayGroup

Allows the delegate to prevent aDisplayGroup from fetching. If the delegate returns YES, aDisplayGroup performs the fetch; if the delegate returns NO, aDisplayGroup abandons the fetch.


EOGenericControlAssociation

Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

Inherits From:	EOAssociation : EODelayedObserver : NSObject

Conforms To:	NSCoding (EOAssociation)

EOObserving (EODelayedObserver)

NSObject (NSObject)

Declared In:	EOInterface/EOControlAssociation.h

Purpose

EOGenericControlAssociation is the abstract superclass of EOControlAssociation and EOActionCellAssociation. You never use instances of this class directly; its isUsableWithObject: method always returns NO. See the subclass specifications for more information.

Usable With

None

Aspects

value	See EOControlAssociation and EOActionCellAssociation.

enabled

Object Keys Taken

target	See EOControlAssociation and EOActionCellAssociation.

delegate


EOInterface
Contents

Classes

EOActionAssociation

EOActionCellAssociation

EOActionInsertionAssociation

EOAssociation

EOColumnAssociation

EOControlAssociation

EODetailSelectionAssociation

EODisplayGroup

EOGenericControlAssociation

EOMasterDetailAssociation

EOMasterPeerAssociation

EOPickTextAssociation

EOPopUpAssociation

EOTableViewAssociation

EOTextAssociation

NSImageAdditions


EOMasterDetailAssociation

Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

Inherits From:	EOAssociation : EODelayedObserver : NSObject

Conforms To:	NSCoding (EOAssociation)

EOObserving (EODelayedObserver)

NSObject (NSObject)

Declared In:	EOInterface/EOMasterDetailAssociation.h

Purpose

An EOMasterDetailAssociation binds one EODisplayGroup (the detail) to a relationship in another (the master), so that the detail EODisplayGroup contains the destination objects for the object selected in the master. The EODisplayGroups’ data sources also operate in a master-detail arrangement, meaning changes to one are immediately reflected in the other.

Usable With

EODisplayGroups whose data sources are EODetailDataSources

Aspects

parent	A relationship from the master EODisplayGroup.

Object Keys Taken

None

Class Description

An EOMasterDetailAssociation binds two EODisplayGroups together in a master-detail relationship, where the detail EODisplayGroup shows the destination objects for the relationship of the master EODisplayGroup. In this arrangement, the detail EODisplayGroup’s data source must be an EODetailDataSource. The detail objects are taken directly from the selected object in the master EODisplayGroup, so that changes to the objects in one EODisplayGroup are instantly reflected in the other.

By contrast, with an EOMasterPeerAssociation, the two EODisplayGroups are independent of each other. In a master-peer setup, insertions and deletions in the detail EODisplayGroup don’t affect the corresponding relationship property of the selected object in the master EODisplayGroup. Master-peer setups are more appropriate when no insertions or deletions will be made in the detail EODisplayGroup. See the EOMasterPeerAssociation class specification for more information.

Example

Suppose you have a master EODisplayGroup that presents Movie objects and a detail EODisplayGroup that presents Talent objects. An EOMasterDetailAssociation between the two, bound to the “directors” key, causes the Talent EODisplayGroup to contain the directors for the first Movie object selected in the Movie EODisplayGroup. Inserting a new director into the detail EODisplayGroup also adds it to the relationship property of the selected Movie object.

Instance Methods

priority

− (EOObserverPriority)priority

Returns EOObserverPrioritySecond (one notch above the default priority). This guarantees that changes in the master are propagated to the detail before any other updates are made.


EOMasterPeerAssociation

Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

Inherits From:	EOMasterDetailAssociation : EOAssociation : EODelayedObserver : NSObject

Conforms To:	NSCoding (EOAssociation)

EOObserving (EODelayedObserver)

NSObject (NSObject)

Declared In:	EOInterface/EOMasterDetailAssociation.h

Purpose

An EOMasterPeerAssociation binds one EODisplayGroup (the detail) to a relationship in another (the master), so that the detail EODisplayGroup contains objects corresponding to a relationship of the object selected in the master. The EODisplayGroups’ data sources operate independently of each other, meaning insertions and deletions in the detail EODisplayGroup don’t affect the corresponding relationship property of the selected object in the master EODisplayGroup.

Usable With

EODisplayGroups whose data sources are not EODetailDataSources

Aspects

parent	A relationship from the master EODisplayGroup.

Object Keys Taken

None

Class Description

An EOMasterPeerAssociation binds two EODisplayGroups together in a master-detail relationship, where the detail EODisplayGroup shows the destination objects for the relationship of the master EODisplayGroup. In this arrangement, the detail EODisplayGroup’s data source is an independent EODataSource. Detail objects are fetched independently from the detail’s data source, which means that changes to one EODisplayGroup aren’t automatically reflected in the other. To update the other EODisplayGroup, it’s necessary to save the changes made and then have the other EODisplayGroup fetch its objects anew.

Master-peer setups display these advantages over master-detail setups:

•	You can use them to display the destination objects for relationships that are defined in the model but not declared as class properties. This is typically done for rarely accessed information—or information that’s costly to access. By not defining the relationship as a class property, the destination objects aren’t stored as instance variables in the source objects, which saves memory and the cost of constructing faults for the relationship.

•	Because the detail EODisplayGroup fetches objects with its own EODataSource, you can configure the detail EODataSource with an auxiliary EOQualifier to limit the objects fetched. This further reduces the cost of fetching data.

Generally, though, master-peer setups are only appropriate when no insertions or deletions will be made in the detail EODisplayGroup. For a master-detail relationship that reflects changes between two EODisplayGroups, including insertions and deletions, use an EOMasterDetailAssociation.

Example

Suppose you have a master EODisplayGroup that presents Movie objects and a detail EODisplayGroup that presents Talent objects. An EOMasterPeerAssociation between the two, bound to the “directors” key, causes the Talent EODisplayGroup to contain the directors for the first Movie object selected in the Movie EODisplayGroup. Inserting a new director into the detail EODisplayGroup, however, doesn’t change the relationship property of the selected Movie object.


EOPickTextAssociation

Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

Inherits From:	EOAssociation : EODelayedObserver : NSObject

Conforms To:	NSCoding (EOAssociation)

EOObserving (EODelayedObserver)

NSObject (NSObject)

Declared In:	EOInterface/EOPickTextAssociation.h

Purpose

An EOPickTextAssociation applies a LIKE qualifier to its EODisplayGroup, based on the value of the display object. This allows the user to perform a similarity search based on whole or partial values.

Usable With

Any NSControl

Aspects

matchKey1	An attribute to match using a LIKE qualifier.

matchKey2	An attribute to match using a LIKE qualifier.

matchKey3	An attribute to match using a LIKE qualifier.

Object Keys Taken

target	The EOPickTextAssociation applies its qualifier when sent an action message from the NSControl.

delegate	The EOPickTextAssociation applies its qualifier when sent a controlTextDidChange: message, causing dynamic update as the user types.

Class Description

An EOPickTextAssociation takes the value of its display object and uses it to form a qualifier with up to three LIKE operators, each compared to a different key of the EODisplayGroup.

Example

Make an EOPickTextAssociation between an NSTextField and an EODisplayGroup of People objects. Bind the matchKey1 and matchKey2 aspects to the “lastName” and “firstName” keys. If the user types “Bi” in the field, the EOPickTextAssociation applies the following qualifier to the EODisplayGroup:

(lastName LIKE "*Bi*") OR (firstName LIKE "*Bi*")

which matches names like “Bill Smith” and “Joe Biggs”.


EOPopUpAssociation

Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

Inherits From:	EOAssociation : EODelayedObserver : NSObject

Conforms To:	NSCoding (EOAssociation)

EOObserving (EODelayedObserver)

NSObject (NSObject)

Declared In:	EOInterface/EOPopUpAssociation.h

Purpose

An EOPopUpAssociation displays a single attribute or to-one relationship value from a list of possible values. The titles aspect is typically bound to an attribute of the destination entity’s EODisplayGroup, and one of the selectedTitle, selectedTag, or selectedObject aspects is bound to the source entity’s EODisplayGroup.

Usable With

NSPopUpButton

Aspects

titles	An attribute of the objects in an EODisplayGroup whose values can be represented as strings.

selectedTitle	An attribute of the selected object whose values can be represented as strings.

selectedTag	An integer attribute of the selected object.

selectedObject	A to-one relationship of the selected object; the value displayed is that for the attribute bound to the titles aspect.

enabled	A boolean attribute of the selected object, which determines whether the NSPopUpButton is enabled.

Object Keys Taken

target	When the user chooses an item in the pop-up list, the EOPopUpAssociation updates the selected object’s property with the item’s title, tag, or object.

Class Description

EOPopUpAssociation displays an attribute or to-one relationship value in an NSPopUpButton. The items in the NSPopUpButton can be entered manually, or for a relationship, constructed dynamically from values supplied by the destination entity’s EODisplayGroup. The value displayed by the NSPopUpButton can be bound by one of three aspects: selectedTitle, which is useful for values representable as strings; selectedTag, for integer values; and selectedObject, for the destination object of a relationship.

Examples

Selecting a string from a static list: Given an EODisplayGroup of Movies, the goal is to provide a pop-up list for setting the rating. Assume the rating is a string property of the Movie object rather than a relationship to a Rating object. In this case you type the list of ratings into the pop-up list in Interface Builder, and then bind the selectedTitle aspect to the “rating” property of the Movie EODisplayGroup. If an object’s string attribute value isn’t in the pop-up list, it’s temporarily added while the object is selected.

Selecting a string from a dynamic list: As above, but we want to fill the popup from the “ratingString” property of an EODisplayGroup containing an array of Rating objects fetched from an external source. In this case you bind the titles aspect to the “ratingString” property of the Ratings EODisplayGroup, and bind the selectedTitle aspect to the “rating” property of the Movie EODisplayGroup.

Selecting an integer tag from a static list: Given an EODisplayGroup of customers, whose credit card type is indicated by a tag, the goal is to provide the credit card name on the pop-up list (Visa, MasterCard, and so on). In this case you set the credit card names and tags for the pop-up list in Interface Builder, and then bind the selectedTag aspect to the “cardType” property of the Customer EODisplayGroup. You can also allow for a general “other” value by defining a special tag and setting it in the EOPopUpAssociation using setTagValueForOther:. Credit card tags from the database not matching any in the pop-up list are then displayed as the “other” value. (It would also make sense to disable the pop-up list in this case, to avoid writing the meaningless tag back to the database.)

Selecting an object to assign to a to-one relationship: Given a list of employees, the goal is to assign the department each employee belongs to. In terms of the object model, we want to assign a Department object to the “department” property of an Employee object. In this case you bind the titles aspect to the “name” property of a Department EODisplayGroup, and bind the selectedObject aspect to the “department” relationship property of the Employee EODisplayGroup. This fills the pop-up list with the names of departments, and causes the name of the selected Employee’s Department to be selected in the pop-up list.

Instance Methods

setTagValueForOther:

− (void)setTagValueForOther:(int)tag

Records tag as the “unknown” tag. When a property value doesn’t match any other tag in the pop-up list, the EOPopUpAssociation automatically selects the item for this tag. If there’s no item for this tag, the pop-up list’s selection isn’t changed. This tag value is by default −1.

tagValueForOther

− (int)tagValueForOther

Returns the “unknown” tag. When a property value doesn’t match any other tag in the pop-up list, the EOPopUpAssociation automatically selects the item for this tag. If there’s no item for this tag, the pop-up list’s selection isn’t changed. This tag value is by default −1.


EOTableViewAssociation

Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

Inherits From:	EOAssociation : EODelayedObserver : NSObject

Conforms To:	NSCoding (EOAssociation)

EOObserving (EODelayedObserver)

NSObject (NSObject)

Declared In:	EOInterface/EOColumnAssociation.h

Purpose

An EOTableViewAssociation coordinates the individual EOColumnAssociations bound to an NSTableView. The first EOColumnAssociation to be bound to an NSTableView automatically creates the EOTableViewAssociation; you should rarely need to do so yourself.

Usable With

NSTableView

Aspects

source	Bound to the EODisplayGroup providing objects. This aspect doesn’t use a key.

enabled	A boolean attribute of the objects, which determines whether each object’s row is editable. Note that because EOColumnAssociation also uses this aspect, you can use it with different keys to limit editability to the whole row or to an individual cell (column) in that row.

textColor	An NSColor attribute of the objects, which determines the color of text for each object’s row in the NSTableView.

bold	A boolean attribute of the objects, which determines whether each objects row is displayed in bold or regular weight text.

italic	A boolean attribute of the objects, which determines whether each objects row is displayed in italic or normal angle text.

Object Keys Taken

dataSource	An EOTableViewAssociation responds to some data source messages and forwards others to the appropriate EOColumnAssociation.

delegate	An EOTableViewAssociation forwards delegate messages to the appropriate EOColumnAssociations.

target	Reserved, but not used.

Class Description

An EOTableViewAssociation manages the individual EOColumnAssociations between an NSTableView and an EODisplayGroup. It receives data source and delegate messages from the NSTableView, some of which it handles itself, and some of which it forwards to the appropriate EOColumnAssociations. In addition to this, an EOTableViewAssociation can sort the objects in the EODisplayGroup by the left-to-right order of the table columns.

Class Methods

bindToTableView:displayGroup:

+ (void)bindToTableView:(NSTableView *)aTableView displayGroup:(EODisplayGroup *)aDisplayGroup

Creates an EOTableViewAssociation binding aTableView to aDisplayGroup, if there isn’t already one. EOColumnAssociation’s establishConnection invokes this method to guarantee the presence of a coordinating EOTableViewAssociation.

Instance Methods

editingAssociation

− (EOColumnAssociation *)editingAssociation

Returns the EOColumnAssociation for the NSTableView cell being edited, or nil if no cell is being edited.

setSortsByColumnOrder:

− (void)setSortsByColumnOrder:(BOOL)flag

Controls whether the receiver applies a sort ordering to its EODisplayGroup. If flag is YES, it builds EOSortOrderings for each of the EOColumnAssociations, collects them into an NSArray based on the left-to-right order of the columns, and assigns them to the EODisplayGroup with setSortOrdering:. If flag is NO, it doesn’t alter the sort ordering of the EODisplayGroup.

An EOTableViewAssociation assigns sort orderings based on the left to right order of the table columns, and reassigns them whenever the user moves a column.

See also:	− sortingSelector (EOColumnAssociation), − sortsByColumnOrder

sortsByColumnOrder

− (BOOL)sortsByColumnOrder

Returns YES if the receiver assigns EOSortOrderings to its EODisplayGroup based on the sorting selectors of its EOColumnAssociations, NO if it doesn’t alter the EODisplayGroup’s sort ordering.

An EOTableViewAssociation assigns sort orderings based on the left to right order of the table columns, and reassigns them whenever the user moves a column.

See also:	− sortingSelector (EOColumnAssociation), − setSortsByColumnOrder:

NSTableView Delegate and Data Source Methods

control:isValidObject:

− (BOOL)control:(NSControl *)aTableView isValidObject:(id)anObject

Forwards the message to the receiver’s editing association.

See also:	− editingAssociation

control:didFailToFormatString:errorDescription:

− (BOOL)control:(NSControl *)aTableView

didFailToFormatString:(NSString *)aString

errorDescription:(NSString *)errorDescription

Forwards the message to the receiver’s editing association.

See also:	− editingAssociation

control:textShouldBeginEditing:

− (BOOL)control:(NSControl *)aTableView textShouldBeginEditing:(NSText *)fieldEditor

Forwards the message to the receiver’s editing association.

See also:	− editingAssociation

numberOfRowsInTableView:

− (int)numberOfRowsInTableView:(NSTableView *)aTableView

Returns the number of displayed objects in the receiver’s EODisplayGroup.

See also:	− displayedObjects (EODisplayGroup)

tableView:objectValueForTableColumn:row:

− (id)tableView:(NSTableView *)aTableView

objectValueForTableColumn:(NSTableColumn *)aTableColumn

row:(int)rowIndex

Forwards the message to aTableColumn’s identifier—assumed to be the EOColumnAssociation bound to that column—so that it can provide the value.

tableView:setObjectValue:forTableColumn:row:

− (void)tableView:(NSTableView *)aTableView

setObjectValue:(id)value

forTableColumn:(NSTableColumn *)aTableColumn

row:(int)rowIndex

Forwards the message to aTableColumn’s identifier—assumed to be the EOColumnAssociation bound to that column—so that it can set the value.

tableView:shouldEditTableColumn:row:

− (BOOL)tableView:(NSTableView *)aTableView

shouldEditTableColumn:(NSTableColumn *)aTableColumn

row:(int)rowIndex

Returns NO if the “enabled” aspect is bound and its value for the object at rowIndex is NO. Otherwise forwards the message to aTableColumn’s identifier—assumed to be the EOColumnAssociation bound to that column—and returns its response. Note that because the two associations’ “enabled” aspects can be bound to different keys, you can limit editability to the whole row or to an individual cell (column) in that row.

tableView:willDisplayCell:forTableColumn:row:

− (void)tableView:(NSTableView *)aTableView

willDisplayCell:(id)aCell

forTableColumn:(NSTableColumn *)aTableColumn

row:(int)rowIndex

Alters the display characteristics for aCell according to the values for the “enabled”, “textColor”, “bold”, and “italic” aspects of the object at rowIndex. Then forwards the message to aTableColumn’s identifier—assumed to be the EOColumnAssociation bound to that column—allowing it to adjust aCell based on its own “enabled” aspect.

tableViewSelectionDidChange:

− (void)tableViewSelectionDidChange:(NSNotification *)aNotification

Updates the receiver’s EODisplayGroup based on the new selection in the table view.

See also:	− setSelectionIndexes: (EODisplayGroup)


EOTextAssociation

Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

Inherits From:	EOAssociation : EODelayedObserver : NSObject

Conforms To:	NSCoding (EOAssociation)

EOObserving (EODelayedObserver)

NSObject (NSObject)

Declared In:	EOInterface/EOTextAssociation.h

Purpose

An EOTextAssociation binds an NSText object to a string or NSData attribute, and can handle plain text, RTF, or RTFD (RTF with attachments).

Usable With

NSText, NSTextView, NSCStringText

Aspects

value	A text attribute of the selected object.

editable	A boolean attribute of the selected object, which determines whether the NSText object is editable.

Object Keys Taken

delegate	An EOTextAssociation accepts delegate messages related to the editing and validation of text; see the NSText, NSTextView, and NSCStringText class specifications for more information.

Class Description

An EOTextAssociation displays a plain or rich text attribute in an NSText object. It determines the kind of text received from an object by examining the beginning for signature codes specific to RTF and RTFD. When writing text back to the object, the association examines the configuration of the NSText object to determine the type to use:

Multiple Fonts	Allows Graphics	Type Written to Object

NO	NO	NSString text

YES	NO	NSData containing RTF

YES	YES	NSData containing RTFD


NSImage Additions

Copyright ©1996 by NeXT Software, Inc.  All Rights Reserved.

Inherits From:	NSObject

Declared In:	EOInterface/EOControlAssociation.h

Class Description

Enterprise Objects Framework adds one method to NSImage to aid in conversion of image data from databases. This method is used as a factory method for custom value archiving, as described in the EOCustomClassArchiving informal protocol specification. See the NSImage class specification in the Application Kit documentation for a list supported image file formats.

Class Methods

imageWithData:

+ imageWithData:(NSData *)imageData

Creates an NSImage from imageData and returns it.

See also:	− initWithData: (NSImage class of the Application Kit), − TIFFRepresentation (NSImage class of the Application Kit)