Inherits From:
NSObject (Yellow Box)
Object (Java Client)
Inherits From:
com.apple.client.eointerface (Java Client)
com.apple.yellow.eointerface (Yellow Box)
Class Description
An EODisplayGroup is the basic user interface manager for an Enterprise Objects Framework or Java Client 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 allows the EODisplayGroup to intercede in certain operations, as described in the Editor and MessageHandler interface specifications. EODisplayGroup implements all the methods of these informal protocols; see the descriptions for editingContextWillSaveChanges
, editorHasChangesForEditingContext
, and editingContextPresentErrorMessage
(editingContextPresentException
for Java Client applications) 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 EODatabaseDataSource (EODistributedDataSource, for Java Client applications), 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.
To create an EODisplayGroup programmatically, simply initialize it and set its EODataSource:
EODistributedDataSource dataSource; /* Assume this exists. */
EODisplayGroup displayGroup;
displayGroup = new EODisplayGroup();
displayGroup.setDataSource(dataSource);
After creating the EODisplayGroup, you can add associations as described in the EOAssociation class specification.
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 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 setSortOrderings
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 displayGroupDisplayArrayForObjects
, 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
.
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 displayGroupDisplayArrayForObjects
, 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 true
to permit the action or false
to deny it. For more information, see each method's description in the EODisplayGroup.Delegate interface informal specification.
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 object identifier. valueForObjectAtIndex
returns the value of a named property for the object at a given index, and setValueForObjectAtIndex
sets it. Similarly, valueForObject
and setValueForObject
access the objects by object identifer. EOAssociations can also get and set values for the first object in the selection using selectedObjectValueForKey
and setSelectedObjectValue
.
EODisplayGroup
()
Creates a new EODisplayGroup. The new display group needs to have an EODataSource set with setDataSource
.
public EODisplayGroup
(EODataSource aDataSource)
(Java Client applications only) Creates a new EODisplayGroup and sets its data source set to aDataSource.
See also:
bindAspect
(EOAssociation)
Instance Methods
allObjects
public NSArray allObjects
()
Returns all of the objects collected by the receiver.
See also:
displayedObjects
, fetch
associationDidBeginEditing
public void associationDidBeginEditing
(EOAssociation anAssociation)
Invoked by anAssociation when its display object begins editing to record that EOAssociation as the editing association.
See also:
editingAssociation
, endEditing
, associationFailedToValidateValue
associationDidEndEditing
public 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
, endEditing
, associationFailedToValidateValue
associationFailedToValidateValue
public boolean associationFailedToValidateValue
(
EOAssociation anAssociation,
java.lang.String value,
java.lang.String key,
java.lang.Object anObject,
java.lang.String errorDescription)
Invoked by anAssociation from its shouldEndEditingAtIndex
method to let the receiver handle a validation error. This method opens an attention panel with errorDescription as the message and returns false
.
See also:
displayGroupShouldDisplayAlert
(EODisplayGroup.Delegate)
clearSelection
public boolean clearSelection
()
Invokes setSelectionIndexes
to clear the selection, returning true
on success and false
on failure.
contentsChanged
public boolean contentsChanged
()
Returns true
if the receiver's array of objects has changed and not all observers have been notified, false
otherwise. EOAssociations use this in their subjectChanged
methods to determine what they need to update.
See also:
selectionChanged
, updatedObjectIndex
dataSource
public EODataSource dataSource
()
Returns the receiver's EODataSource.
See also:
setDataSource
defaultStringMatchFormat
public java.lang.String defaultStringMatchFormat
()
(Yellow Box applications only) Returns the format string that specifies how pattern matching will be performed on string values in the queryMatch
dictionary. If a key in the queryMatch
dictionary does not have an associated operator in the queryOperatorValues
dictionary, then its value is matched using pattern matching, and the format string returned by this method specifies how it will be matched.
See also:
defaultStringMatchOperator
, setDefaultStringMatchFormat
defaultStringMatchOperator
public java.lang.String defaultStringMatchOperator
()
(Yellow Box applications only) Returns the operator used to perform pattern matching for string values in the queryMatch
dictionary. If a key in the queryMatch
dictionary does not have an associated operator in the queryOperatorValues
dictionary, then the operator returned by this method is used to perform pattern matching.
See also:
defaultStringMatchFormat
, setDefaultStringMatchOperator
delegate
public java.lang.Object delegate
()
Returns the receiver's delegate.
See also:
setDelegate
deleteObjectAtIndex
public boolean deleteObjectAtIndex
(int index)
Attempts to delete the object at index, returning true
if successful and false
if not. Checks with the delegate using displayGroupShouldDeleteObject
. If the delegate returns false
, this method fails and returns false
. If successful, sends the delegate a displayGroupDidDeleteObject
message.
This method performs the delete by sending deleteObject:
to the EODataSource. If that message throws an exception, this method fails and returns false
.
deleteSelection
public boolean deleteSelection
()
Attempts to delete the selected objects, returning true
if successful and false
if not.
displayedObjects
public 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
,
displayGroupDisplayArrayForObjects
(EODisplayGroup.Delegate), qualifier
, sortOrderings
editingAssociation
public EOAssociation editingAssociation
()
Returns the EOAssociation editing a value if there is one, false
if there isn't.
See also:
associationDidBeginEditing
, associationDidEndEditing
editingContextPresentErrorMessage
public void editingContextPresentErrorMessage
(
EOEditingContext anEditingContext,
java.lang.String errorMessage)
(For Java Client applications, this method is named editingContextPresentException
) Invoked by anEditingContext as part of the EOMessageHandlers interface (MessageHandler interface for Java Client applications), this method presents an attention panel with errorMessage as the message to display.
editingContextWillSaveChanges
public 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 throws an exception if it returns false
. Thus, if there's an association that refuses to end editing, anEditingContext doesn't save changes.
editorHasChangesForEditingContext
public boolean editorHasChangesForEditingContext
(
EOEditingContext anEditingContext)
Invoked by anEditingContext as part of the EOEditors interface, this method returns false
if any association is editing, true
otherwise.
See also:
editingAssociation
, associationDidBeginEditing
, associationDidEndEditing
enabledToSetSelectedObjectValueForKey
public boolean enabledToSetSelectedObjectValueForKey
(java.lang.String key)
Returns true
to indicate that a single value association (such as an EOControlAssociation for a NSTextField) should be enabled for setting key, false
otherwise. Normally this is the case if the receiver has a selected object. However, if key is a special query key (for example, "@query=.name"), then the control should be enabled even without a selected object.
endEditing
public boolean endEditing
()
Attempts to end any editing taking place. If there's no editing association or if the editing association responds true
to an endEditing
message, returns true
. Otherwise returns false
.
See also:
editingAssociation
enterQueryMode
public void enterQueryMode
(java.lang.Object sender)
(Yellow Box applications only) This action method invokes setInQueryMode
with an argument of true
.
equalToQueryValues
public NSDictionary equalToQueryValues
()
(Yellow Box applications only) Returns the receiver's dictionary of equalTo query values. This dictionary is typically manipulated by associations bound to keys of the form @query=.propertyName. The qualifierFromQueryValues
method uses this dictionary along with the lessThan and greaterThan dictionaries to construct qualifiers.
See also:
setEqualToQueryValues
, greaterThanQueryValues
, lessThanQueryValues
,
Attempts to fetch objects from the EODataSource, returning true
on success and false
on failure.
Before fetching, invokes endEditing
and sends displayGroupShouldFetch
to the delegate, returning false
if either of these methods does. If both return true
, sends a fetchObjects
message to the receiver's EODataSource to replace the object array, and if successful sends the delegate a displayGroupDidFetchObjects
message.
fetchesOnLoad
public boolean fetchesOnLoad
()
Returns true
if the receiver fetches automatically after being loaded from a nib file, false
if it must be told explicitly to fetch. The default is false
. You can set this behavior in Interface Builder using the Inspector panel.
See also:
fetch
, setFetchesOnLoad
greaterThanQueryValues
public NSDictionary greaterThanQueryValues
()
(Yellow Box applications only) Returns the receiver's dictionary of greaterThan query values. This dictionary is typically manipulated by associations bound to keys of the form @query>.propertyName. The qualifierFromQueryValues
method uses this dictionary along with the lessThan and equalTo dictionaries to construct qualifiers.
See also:
setGreaterThanQueryValues
, lessThanQueryValues
, equalToQueryValues
inQueryMode
public boolean inQueryMode
()
(Yellow Box applications only) Returns true
to indicate that the receiver is in query mode, false
otherwise. In query mode, user interface controls that normally display values become empty, allowing users to type queries directly into them (this is also known as a "Query By Example" interface). In effect, the receiver's "displayedObjects" are replaced with an empty equalTo query values dictionary. When qualifyDisplayGroup
or qualifyDataSource
is subsequently invoked, the query is performed and the display reverts to displaying values-this time, the objects returned by the query.
See also:
setInQueryMode
, enterQueryMode
(Java Client applications only) This action method invokes insertNewObjectAtIndex
with an index just past the first index in the selection, or 0 if there's no selection.
insertedObjectDefaultValues
public NSDictionary insertedObjectDefaultValues
()
(Yellow Box applications only) Returns the default values to be used for newly inserted objects. The keys into the dictionary are the properties of the entity that the display group manages. If the dictionary returned by this method is empty, the insert...
method adds an object that is initially empty. Because the object is empty, the display group has no value to display on the HTML page for that object, meaning that there is nothing for the user to select and modify. Use the setInsertedObjectDefaultValues
method to set up a default value so that there is something to display on the page.
insertNewObjectAtIndex
public java.lang.Object insertNewObjectAtIndex
(int anIndex)
Asks the receiver's EODataSource to create a new object by sending it a createObject
message, then inserts the new object using insertObjectAtIndex
. The EODataSource createObject method has the effect of inserting the object into the EOEditingContext.
If a new object can't be created, this method sends the delegate a displayGroupCreateObjectFailed
message or, if the delegate doesn't respond, opens an attention panel to inform the user of the error.
insertObjectAtIndex
public void insertObjectAtIndex
(
java.lang.Object anObject,
int index)
Inserts anObject into the receiver's EODataSource and displayedObjects
array at index, if possible. This method checks with the delegate before actually inserting, using displayGroupShouldInsertObject
. If the delegate refuses, anObject isn't inserted. After successfully inserting the object, this method informs the delegate with a displayGroupDidInsertObject
message, and selects the newly inserted object. Throws an exception if index is out of bounds.
Unlike the insertNewObjectAtIndex
method, this method does not insert the object into the EOEditingContext. If you use this method, you're responsible for inserting the object into the EOEditingContext yourself.
lessThanQueryValues
public NSDictionary lessThanQueryValues
()
(Yellow Box applications only) Returns the receiver's dictionary of lessThan query values. This dictionary is typically manipulated by associations bound to keys of the form @query<.propertyName. The qualifierFromQueryValues
method uses this dictionary along with the greaterThan and equalTo dictionaries to construct qualifiers.
See also:
setLessThanQueryValues
, greaterThanQueryValues
, equalToQueryValues
localKeys
public 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
public NSArray observingAssociations
()
Returns all EOAssociations that observe the receiver's objects.
qualifier
public 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
qualifierFromQueryValues
public EOQualifier qualifierFromQueryValues
()
(Yellow Box applications only) Builds a qualifier constructed from entries in the three query dictionaries: equalTo, greaterThan, and lessThan. These, in turn, are typically manipulated by associations bound to keys of the form @query=.firstName, @query>.budget, @query<.budget.
See also:
qualifyDisplayGroup
, qualifyDataSource
qualifyDataSource
public void qualifyDataSource
()
Takes the result of qualifierFromQueryValues
and applies to the receiver's data source. The receiver then sends itself a fetch
message. If the receiver is in query mode, query mode is exited. This method differs from qualifyDisplayGroup
as follows: whereas qualifyDisplayGroup
performs in-memory filtering of already fetched objects, qualifyDataSource
triggers a new qualified fetch against the database.
qualifyDisplayGroup
public void qualifyDisplayGroup
()
Takes the result of qualifierFromQueryValues
and applies to the receiver using setQualifier
. The method updateDisplayedObjects
is invoked to refresh the display. If the receiver is in query mode, query mode is exited.
See also:
qualifyDataSource
queryBindingValues
public NSDictionary queryBindingValues
()
(Yellow Box applications only) Returns a dictionary containing the actual values that the user wants to query upon. You use this method to perform a query stored in the model file. Bind keys in this dictionary to elements on your component that specify query values, then pass this dictionary to the fetch specification that performs the fetch.
queryOperatorValues
public NSDictionary queryOperatorValues
()
(Yellow Box applications only) Returns a dictionary of operators to use on items in the queryMatch
dictionary. If a key in the queryMatch
dictionary also exists in queryOperatorValues
, that operator for that key is used.
See also:
qualifierFromQueryValues
redisplay
public void redisplay
()
Notifies all observing associations to redisplay their values.
See also:
observingAssociations
selectedObject
public java.lang.Object selectedObject
()
Returns the first selected object in the displayed objects array, or null
if there's no such object.
See also:
displayedObjects
, selectionIndexes
selectedObjects
public NSArray selectedObjects
()
Returns the objects selected in the receiver's displayed objects array.
See also:
displayedObjects
, selectionIndexes
selectedObjectValueForKey
public java.lang.Object selectedObjectValueForKey
(java.lang.String key)
Returns the value corresponding to key for the first selected object in the receiver's displayed objects array, or null
if exactly one object isn't selected.
See also:
valueForObject
selectionChanged
public boolean selectionChanged
()
Returns true
if the selection has changed and not all observers have been notified, false
otherwise. EOAssociations use this in their subjectChanged
methods to determine what they need to update.
See also:
contentsChanged
selectionIndexes
public 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
public boolean selectNext
()
Attempts to select the object just after the currently selected one, returning true
if successful and false
if not. The selection is altered in this way:
false
.
true
.
true
.
selectPrevious
, setSelectionIndexes
selectObject
public boolean selectObject
(java.lang.Object anObject)
Returns true
to indicate that the receiver has found and selected anObject, false
if it can't find a match for anObject (in which case it clears the selection). The selection is performed on the receiver's displayedObjects
, not on allObjects
.
selectObjectsIdenticalTo
public boolean selectObjectsIdenticalTo
(NSArray objects)
Attempts to select the objects in the receiver's displayed objects array which are equal to those of objects, returning true
if successful and false
otherwise.
public boolean selectObjectsIdenticalTo
(NSArray objects,
boolean flag)
(Java Client applications only) Selects the objects in the receiver's displayed objects array that are equal to those of objects, returning true
if successful and false
otherwise. If no objects in the displayed objects array match objects and flag is true
, attempts to select the first object in the displayed objects array.
See also:
setSelectionIndexes
selectPrevious
public boolean selectPrevious
()
Attempts to select the object just before the presently selected one, returning true
if successful and false
if not. The selection is altered in this way:
false
.
true
.
true
.
selectNext
, redisplay
selectsFirstObjectAfterFetch
public boolean selectsFirstObjectAfterFetch
()
Returns true
if the receiver automatically selects its first displayed object after a fetch if there was no selection, false
if it leaves an empty selection as-is.
See also:
displayedObjects
, fetch
, setSelectsFirstObjectAfterFetch
setDataSource
public void setDataSource
(EODataSource aDataSource)
Sets the receiver's EODataSource to aDataSource. In the process, it performs these actions:
self
as an editor and message handler for the previous EODataSource's EOEditingContext, if necessary, and registers self
with aDataSource's editing context. If the new editing context already has a message handler, however, the receiver doesn't assume that role.
self
for EOObjectsChangedInEditingContextNotification and EOInvalidatedAllObjectsInStoreNotification from the new editing context.
displayGroupDidChangeDataSource
to the delegate if there is one.
dataSource
setDefaultStringMatchFormat
public void setDefaultStringMatchFormat
(java.lang.String format)
(Yellow Box applications only) Sets how pattern matching will be performed on String values in the queryMatch
dictionary. This format is used for properties listed in the queryMatch
dictionary that have String values and that do not have an associated entry in the queryOperatorValues
dictionary. In these cases, the value is matched using pattern matching and format specifies how it will be matched.
The default format string for pattern matching is "%@*
" which means that the string value in the queryMatch
dictionary is used as a prefix. For example, if the queryMatch
dictionary contains a value "Jo" for the key "Name", the query returns all records whose name values begin with "Jo".
See also:
defaultStringMatchFormat
, setDefaultStringMatchOperator
setDefaultStringMatchOperator
public void setDefaultStringMatchOperator
(java.lang.String operator)
(Yellow Box applications only) Sets the operator used to perform pattern matching for String values in the queryMatch
dictionary. This operator is used for properties listed in the queryMatch
dictionary that have String values and that do not have an associated entry in the queryOperatorValues
dictionary. In these cases, the operator operator is used to perform pattern matching.
The default value for the query match operator is caseInsensitiveLike
, which means that the query does not consider case when matching letters. The other possible value for this operator is like
, which matches the case of the letters exactly.
See also:
defaultStringMatchOperator
, setDefaultStringMatchFormat
setDelegate
public void setDelegate
(java.lang.Object anObject)
Sets the receiver's delegate to anObject.
See also:
delegate
setEqualToQueryValues
public void setEqualToQueryValues
(NSDictionary values)
(Yellow Box applications only) Sets to values the receiver's dictionary of equalTo query values. The qualifierFromQueryValues
method uses this dictionary along with the lessThan and greaterThan dictionaries to construct qualifiers.
See also:
equalToQueryValues
, setLessThanQueryValues
, setGreaterThanQueryValues
setFetchesOnLoad
public void setFetchesOnLoad
(boolean flag)
Controls whether the receiver automatically fetches its objects after being loaded from a nib file. If flag is true
it does; if flag is false
the receiver must be told explicitly to fetch. The default is false
. You can also set this behavior in Interface Builder using the Inspector panel.
See also:
fetch
, fetchesOnLoad
setGreaterThanQueryValues
public void setGreaterThanQueryValues
(NSDictionary values)
(Yellow Box applications only) Sets to values the receiver's dictionary of greaterThan query values. The qualifierFromQueryValues
method uses this dictionary along with the lessThan and equalTo dictionaries to construct qualifiers.
See also:
greaterThanQueryValues
, setLessThanQueryValues
, setEqualToQueryValues
setInQueryMode
public void setInQueryMode
(boolean flag)
(Yellow Box applications only) Sets according to flag whether the receiver is in query mode.
See also:
inQueryMode
, enterQueryMode
setInsertedObjectDefaultValues
public void setInsertedObjectDefaultValues
(
NSDictionary defaultValues)
(Yellow Box applications only) Sets default values to be used for newly inserted objects. When you use the insert...
method to add an object, that object is initially empty. Because the object is empty, there is no value to be displayed on the HTML page, meaning there is nothing for the user to select and modify. You use this method to provide at least one field that can be displayed for the newly inserted object. The possible keys into the dictionary are the properties of the entity managed by this display group.
See also:
insertedObjectDefaultValues
setLessThanQueryValues
public void setLessThanQueryValues
(NSDictionary values)
(Yellow Box applications only) Sets to values the receiver's dictionary of lessThan query values. The qualifierFromQueryValues
method uses this dictionary along with the greaterThan and equalTo dictionaries to construct qualifiers.
See also:
lessThanQueryValues
, setGreaterThanQueryValues
, setEqualToQueryValues
setLocalKeys
public void setLocalKeys
(NSArray keys)
Sets the additional keys to which EOAssociations can be bound to the strings in keys. Instead of invoking this method programmatically, you can use Interface Builder to add and remove local keys in the EODisplayGroup Attributes Inspector panel.
See also:
localKeys
setObjectArray
public 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
. If there's no match and the receiver selects after fetching, then the first object is selected.
See also:
allObjects
, displayedObjects
, selectsFirstObjectAfterFetch
setQualifier
public 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 displayGroupDisplayArrayForObjects
, that method is used instead of the qualifier to filter the objects.
See also:
displayedObjects
, qualifier
, qualifierFromQueryValues
setQueryBindingValues
public void setQueryBindingValues
(NSDictionary values)
(Yellow Box applications only)
setQueryOperatorValues
public void setQueryOperatorValues
(NSDictionary values)
(Yellow Box applications only)
setSelectedObject
public void setSelectedObject
(java.lang.Object anObject)
Sets the selected objects to anObject.
setSelectedObjects
public void setSelectedObjects
(NSArray objects)
Sets the selected objects to objects.
setSelectedObjectValue
public boolean setSelectedObjectValue
(
java.lang.Object value,
java.lang.String key)
Invokes setValueForObject
with the first selected object, returning true
if successful and false
otherwise. This method should be invoked only by EOAssociation objects to propagate changes from display objects.
See also:
setValueForObjectAtIndex
, valueForObject
setSelectionIndexes
public boolean setSelectionIndexes
(NSArray indexes)
Selects the objects at indexes in the receiver's array if possible, returning true
if successful and false
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 false
, this method fails and returns false
. This method then checks the delegate with a displayGroupShouldChangeSelection
message. If the delegate returns false
, this method also fails and returns false
. If the receiver successfully changes the selection, its observers (typically EOAssociations) each receive a subjectChanged
message.
setSelectsFirstObjectAfterFetch
public void setSelectsFirstObjectAfterFetch
(boolean 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 true
it does; if flag is false
then no objects are selected. By default, display groups select the first object after a fetch when there was no previous selection.
See also:
displayedObjects
, fetch
, selectsFirstObjectAfterFetch
setSortOrderings
public void setSortOrderings
(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 displayGroupDisplayArrayForObjects
, that method is used instead of the sort orderings to order the objects.
See also:
displayedObjects
, sortOrderings
setUsesOptimisticRefresh
public void setUsesOptimisticRefresh
(boolean flag)
Controls how the receiver redisplays on changes to objects. If flag is true
it redisplays only when elements of its displayed objects array change; if flag is false
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 false
. You can also change this setting in Interface Builder's Inspector panel using the Refresh All check box.
See also:
usesOptimisticRefresh
setValidatesChangesImmediately
public void setValidatesChangesImmediately
(boolean aBoolean)
Controls the receiver's behavior on encountering a validation error. Whenever an EODisplayGroup sets a value in an object, it sends the object a validateValueForKey
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 true
, the receiver immediately presents an attention panel indicating the validation error. If this method is invoked with a flag of false
, the receiver leaves validation errors to be handled when changes are saved. By default, display groups don't validate changes immediately.
See also:
- saveChanges
(EOEditingContext), validatesChangesImmediately
setValueForObject
public boolean setValueForObject
(
java.lang.Object value,
java.lang.Object anObject,
java.lang.String key)
Sets a property of anObject, identified by key, to value. Returns true
if successful and false
otherwise. If a new value is set, sends the delegate a displayGroupDidSetValueForObject
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 validateValueForKey
message, returning false
if the object refuses to validate value. Otherwise, validation errors are checked by the EOEditingContext when it attempts to save changes.
See also:
setValueForObjectAtIndex
, setSelectedObjectValue
, valueForObject
,
validatesChangesImmediately
setValueForObjectAtIndex
public boolean setValueForObjectAtIndex
(
java.lang.Object value,
int index,
java.lang.String key)
Invokes setValueForObject
with the object at index, returning true
if successful and false
otherwise. This method should be invoked only by EOAssociation objects to propagate changes from display objects.
See also:
setSelectedObjectValue
,valueForObjectAtIndex
sortOrderings
public NSArray sortOrderings
()
Returns an array of EOSortOrdering objects that updateDisplayedObjects
uses to sort the displayed objects, as returned by the displayedObjects
method.
See also:
setSortOrderings
updateDisplayedObjects
public void updateDisplayedObjects
()
Recalculates the receiver's displayed objects array and redisplays. If the receiver's delegate responds to displayGroupDisplayArrayForObjects
, it's sent this message and the returned array is set as the display group'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
, displayedObjects
, selectedObjects
, qualifier
, sortOrderings
updatedObjectIndex
public 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 true
. EOAssociations can use this method to optimize redisplay of their user interface objects.
usesOptimisticRefresh
public boolean usesOptimisticRefresh
()
Returns true
if the receiver redisplays only when its displayed objects change, false
if it redisplays on any change in its EOEditingContext.
See also:
setUsesOptimisticRefresh
validatesChangesImmediately
public boolean validatesChangesImmediately
()
Returns true
if the receiver immediately handles validation errors, or false
if it leaves errors for the EOEditingContext to handle when saving changes.
See also:
setValidatesChangesImmediately
valueForObject
public java.lang.Object valueForObject
(
java.lang.Object anObject,
java.lang.String key)
Returns anObject's value for the property identified by key.
valueForObjectAtIndex
public java.lang.Object valueForObjectAtIndex
(
int index,
java.lang.String key)
Returns the value of the object at index for the property identified by key.