PATH |
EODisplayGroup
- Inherits from:
- Object
- Implements:
- NSDisposable
- Package:
- com.webobjects.eointerface
Class at a Glance
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
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. |
setSortOrderings | Sets the ordering used to sort the objects. |
updateDisplayedObjects | Filters, sorts, and redisplays the objects. |
insertNewObjectAtIndex | 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 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 EOEditingContext.Editor and EOEditingContext.MessageHandler interface specifications (both interfaces are defined in EOControl). EODisplayGroup implements all the methods of these informal protocols; see their specifications 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 EOQualifier's filteredArrayUsingQualifier and EOSortOrdering's sortedArrayUsingKeyOrderArray methods, 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 selectObjectsIdenticalToSelectFirstOnNoMatch.
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 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 setValueForObjectaccess the objects by object identifier. EOAssociations can also get and set values for the first object in the selection using selectedObjectValueForKey and setSelectedObjectValue.
Interfaces Implemented
- NSDisposable
- dispose
Method Types
- Configuring behavior
- defaultStringMatchFormat
- defaultStringMatchOperator
- fetchesOnLoad
- queryBindingValues
- queryOperatorValues
- selectsFirstObjectAfterFetch
- setDefaultStringMatchFormat
- setDefaultStringMatchOperator
- setFetchesOnLoad
- setQueryBindingValues
- setQueryOperatorValues
- setSelectedObject
- setSelectedObjects
- setSelectsFirstObjectAfterFetch
- setUsesOptimisticRefresh
- setValidatesChangesImmediately
- usesOptimisticRefresh
- validatesChangesImmediately
- Setting the data source
- setDataSource
- dataSource
- Setting the qualifier and sort ordering
- setQualifier
- qualifier
- setSortOrderings
- sortOrderings
- Managing queries
- qualifierFromQueryValues
- setEqualToQueryValues
- equalToQueryValues
- setGreaterThanQueryValues
- greaterThanQueryValues
- setLessThanQueryValues
- lessThanQueryValues
- qualifyDataSource
- qualifyDisplayGroup
- enterQueryMode
- inQueryMode
- setInQueryMode
- enabledToSetSelectedObjectValueForKey
- Fetching objects from the data source
- fetch
- Getting the objects
- allObjects
- displayedObjects
- Updating display of values
- redisplay
- updateDisplayedObjects
- Setting the objects
- setObjectArray
- Changing the selection
- setSelectionIndexes
- selectObjectsIdenticalTo
- selectObject
- clearSelection
- selectNext
- selectPrevious
- Examining the selection
- selectionIndexes
- selectedObject
- selectedObjects
- Adding keys
- setLocalKeys
- localKeys
- Getting the associations
- observingAssociations
- Setting the delegate
- setDelegate
- delegate
- Changing values from associations
- setSelectedObjectValue
- selectedObjectValueForKey
- setValueForObject
- valueForObject
- setValueForObjectAtIndex
- valueForObjectAtIndex
- Editing by associations
- associationDidBeginEditing
- associationDidEndEditing
- associationFailedToValidateValue
- editingAssociation
- endEditing
- Querying changes for associations
- contentsChanged
- selectionChanged
- updatedObjectIndex
- Interacting withthe EOEditingContext
- editorHasChangesForEditingContext
- editingContextWillSaveChanges
- editingContextPresentErrorMessage
- Other methods
- EODisplayGroup
- globalDefaultForValidatesChangesImmediately
- globalDefaultStringMatchFormat
- globalDefaultStringMatchOperator
- setGlobalDefaultForValidatesChangesImmediately
- setGlobalDefaultStringMatchFormat
- setGlobalDefaultStringMatchOperator
- awakeFromNib
- delete
- deleteObjectAtIndex
- deleteSelection
- editingContextShouldContinueFetching
- insert
- insertNewObjectAtIndex
- insertObjectAtIndex
- insertedObjectDefaultValues
- objectsChangedInEditingContext
- objectsInvalidatedInEditingContext
- selectObjectsIdenticalToSelectFirstOnNoMatch
- setInsertedObjectDefaultValues
- undoManager
- willChange
Constructors
EODisplayGroup
public EODisplayGroup()
See Also: bindAspect (EOAssociation)
Static Methods
globalDefaultForValidatesChangesImmediately
public static boolean globalDefaultForValidatesChangesImmediately()
true
if the default behavior for new display group instances is to immediately handle validation errors, or false
if the default behavior leaves errors for the EOEditingContext to handle when saving changes.
See Also: validatesChangesImmediately
globalDefaultStringMatchFormat
public static String globalDefaultStringMatchFormat()
See Also: defaultStringMatchFormat
globalDefaultStringMatchOperator
public static String globalDefaultStringMatchOperator()
See Also: defaultStringMatchOperator
setGlobalDefaultForValidatesChangesImmediately
public static void setGlobalDefaultForValidatesChangesImmediately(boolean flag)
true
, the default behavior is for display groups to immediately present an attention panel indicating a validation error. If flag is false
, the default behavior if for display groups to leave validation errors to be handled when changes are saved. By default, display groups don't validate changes immediately.
See Also: setValidatesChangesImmediately
setGlobalDefaultStringMatchFormat
public static void setGlobalDefaultStringMatchFormat(String format)
See Also: setDefaultStringMatchFormat
setGlobalDefaultStringMatchOperator
public static void setGlobalDefaultStringMatchOperator(String op)
See Also: setDefaultStringMatchOperator
Instance Methods
allObjects
public NSArray allObjects()
See Also: displayedObjects, fetch
associationDidBeginEditing
public void associationDidBeginEditing(EOAssociation anEOAssociation)
See Also: editingAssociation, endEditing, associationFailedToValidateValue
associationDidEndEditing
public void associationDidEndEditing(EOAssociation anEOAssociation)
See Also: editingAssociation, endEditing, associationFailedToValidateValue
associationFailedToValidateValue
public boolean associationFailedToValidateValue( EOAssociation anEOAssociation, String value, String key, Object anObject, String errorDescription)
See Also: displayGroupShouldDisplayAlert (EODisplayGroup.Delegate)
awakeFromNib
public void awakeFromNib()
See Also: redisplay
clearSelection
public boolean clearSelection()
contentsChanged
public boolean contentsChanged()
See Also: selectionChanged, updatedObjectIndex
dataSource
public com.webobjects.eocontrol.EODataSource dataSource()
See Also: setDataSource
defaultStringMatchFormat
public String defaultStringMatchFormat()
See Also: defaultStringMatchOperator, setDefaultStringMatchFormat
defaultStringMatchOperator
public String defaultStringMatchOperator()
See Also: defaultStringMatchFormat, setDefaultStringMatchOperator
delegate
public Object delegate()
See Also: setDelegate
delete
public void delete()
deleteObjectAtIndex
public boolean deleteObjectAtIndex(int index)
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()
displayedObjects
public NSArray displayedObjects()
See Also: allObjects, updateDisplayedObjects, displayGroupDisplayArrayForObjects (EODisplayGroup.Delegate), qualifier, sortOrderings
dispose
public void dispose()
editingAssociation
public EOAssociation editingAssociation()
See Also: associationDidBeginEditing, associationDidEndEditing
editingContextPresentErrorMessage
public void editingContextPresentErrorMessage( com.webobjects.eocontrol.EOEditingContext anEOEditingContext, String errorMessage)
editingContextShouldContinueFetching
public boolean editingContextShouldContinueFetching( com.webobjects.eocontrol.EOEditingContext anEOEditingContext, int count, int limit, com.webobjects.eocontrol.EOObjectStore anEOObjectStore)
editingContextWillSaveChanges
public void editingContextWillSaveChanges( com.webobjects.eocontrol.EOEditingContext anEOEditingContext)
editorHasChangesForEditingContext
public boolean editorHasChangesForEditingContext( com.webobjects.eocontrol.EOEditingContext anEOEditingContext)
See Also: editingAssociation, associationDidBeginEditing, associationDidEndEditing
enabledToSetSelectedObjectValueForKey
public boolean enabledToSetSelectedObjectValueForKey(String key)
endEditing
public boolean endEditing()
See Also: editingAssociation
enterQueryMode
public void enterQueryMode()
equalToQueryValues
public NSDictionary equalToQueryValues()
See Also: setEqualToQueryValues, greaterThanQueryValues, lessThanQueryValues
fetch
public boolean fetch()
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()
See Also: fetch, fetchesOnLoad
greaterThanQueryValues
public NSDictionary greaterThanQueryValues()
See Also: setGreaterThanQueryValues,, equalToQueryValues
inQueryMode
public boolean inQueryMode()
See Also: setInQueryMode, enterQueryMode
insert
public void insert()
This action method invokes insertObjectAtIndex with an index just past the first index in the selection, or 0 if there's no selection.
insertNewObjectAtIndex
public 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.
See Also: insert
insertObjectAtIndex
public boolean insertObjectAtIndex( Object anObject, int index)
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.
insertedObjectDefaultValues
public NSDictionary insertedObjectDefaultValues()
lessThanQueryValues
public NSDictionary lessThanQueryValues()
See Also: setLessThanQueryValues, greaterThanQueryValues, equalToQueryValues
localKeys
public NSArray localKeys()
See Also: setLocalKeys
objectsChangedInEditingContext
public void objectsChangedInEditingContext(NSNotification aNSNotification)
objectsInvalidatedInEditingContext
public void objectsInvalidatedInEditingContext(NSNotification aNSNotification)
observingAssociations
public NSArray observingAssociations()
qualifier
public com.webobjects.eocontrol.EOQualifier qualifier()
See Also: updateDisplayedObjects, displayedObjects, setQualifier
qualifierFromQueryValues
public com.webobjects.eocontrol.EOQualifier qualifierFromQueryValues()
See Also: qualifyDisplayGroup, qualifyDataSource
qualifyDataSource
public void qualifyDataSource()
qualifyDisplayGroup
public void qualifyDisplayGroup()
queryBindingValues
public NSDictionary queryBindingValues()
queryOperatorValues
public NSDictionary queryOperatorValues()
See Also: qualifierFromQueryValues
redisplay
public void redisplay()
See Also: observingAssociations
selectNext
public boolean selectNext()
- If there are no objects, does nothing and returns false.
- If there's no selection, selects the object at index zero and returns true.
- If the first selected object is the last object in the displayed objects array, selects the first object and returns true.
- Otherwise selects the object after the first selected object.
selectObject
public boolean selectObject(Object anObject)
selectObjectsIdenticalTo
public boolean selectObjectsIdenticalTo(NSArray objectSelection)
selectObjectsIdenticalToSelectFirstOnNoMatch
public boolean selectObjectsIdenticalToSelectFirstOnNoMatch( NSArray objectSelection, boolean flag)
See Also: setSelectionIndexes
selectPrevious
public boolean selectPrevious()
- If there are no objects, does nothing and returns false.
- If there's no selection, selects the object at index zero and returns true.
- If the first selected object is at index zero, selects the last object and returns true.
- Otherwise selects the object before the first selected object.
selectedObject
public Object selectedObject()
See Also: displayedObjects, selectionIndexes
selectedObjectValueForKey
public Object selectedObjectValueForKey(String key)
See Also: valueForObjectAtIndex
selectedObjects
public NSArray selectedObjects()
See Also: displayedObjects, selectionIndexes
selectionChanged
public boolean selectionChanged()
See Also: contentsChanged
selectionIndexes
public NSArray selectionIndexes()
See Also: displayedObjects, selectedObjects, selectedObject, setSelectionIndexes
selectsFirstObjectAfterFetch
public boolean selectsFirstObjectAfterFetch()
See Also: displayedObjects, fetch, setSelectsFirstObjectAfterFetch
setDataSource
public void setDataSource(com.webobjects.eocontrol.EODataSource anEODataSource)
- Unregisters 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.
- Registers self for
ObjectsChangedInEditingContextNotification
andInvalidatedAllObjectsInStoreNotification
from the new editing context. - Clears the receiver's array of objects.
- Sends displayGroupDidChangeDataSource to the delegate if there is one.
See Also: dataSource
setDefaultStringMatchFormat
public void setDefaultStringMatchFormat(String format)
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 query 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(String matchOperator)
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(Object anObject)
See Also: delegate
setEqualToQueryValues
public void setEqualToQueryValues(NSDictionary values)
See Also: equalToQueryValues, setLessThanQueryValues, setGreaterThanQueryValues
setFetchesOnLoad
public void setFetchesOnLoad(boolean flag)
See Also: fetch, fetchesOnLoad
setGreaterThanQueryValues
public void setGreaterThanQueryValues(NSDictionary values)
See Also: greaterThanQueryValues, setLessThanQueryValues, setEqualToQueryValues
setInQueryMode
public void setInQueryMode(boolean flag)
See Also: inQueryMode, enterQueryMode
setInsertedObjectDefaultValues
public void setInsertedObjectDefaultValues(NSDictionary defaultValues)
See Also: insertedObjectDefaultValues
setLessThanQueryValues
public void setLessThanQueryValues(NSDictionary values)
See Also: lessThanQueryValues, setGreaterThanQueryValues, setEqualToQueryValues
setLocalKeys
public void setLocalKeys(NSArray keys)
See Also: localKeys
setObjectArray
public void setObjectArray(NSArray objects)
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(com.webobjects.eocontrol.EOQualifier anEOQualifier)
Note: To set the qualifier used to fetch objects from the database, set the qualifier of the display group's dataSource (assuming that the data source is an EODatabaseDataSource). |
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)
setQueryOperatorValues
public void setQueryOperatorValues(NSDictionary values)
setSelectedObject
public void setSelectedObject(Object anObject)
setSelectedObjectValue
public boolean setSelectedObjectValue( Object value , String key)
See Also: setValueForObjectAtIndex, valueForObject
setSelectedObjects
public void setSelectedObjects(NSArray objects)
setSelectionIndexes
public boolean setSelectionIndexes(NSArray indexes)
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)
See Also: displayedObjects, fetch, selectsFirstObjectAfterFetch
setSortOrderings
public void setSortOrderings(NSArray 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)
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 flag)
See Also: - saveChanges (EOEditingContext), validatesChangesImmediately
setValueForObject
public boolean setValueForObject( Object value, Object anObject, String key)
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( Object value, int index, String key)
See Also: setSelectedObjectValue, valueForObjectAtIndex
sortOrderings
public NSArray sortOrderings()
See Also: setSortOrderings
undoManager
public NSUndoManager undoManager()
updateDisplayedObjects
public void updateDisplayedObjects()
See Also: redisplay, displayedObjects, selectedObjects, qualifier, sortOrderings
updatedObjectIndex
public int updatedObjectIndex()
usesOptimisticRefresh
public boolean usesOptimisticRefresh()
See Also: setUsesOptimisticRefresh
validatesChangesImmediately
public boolean validatesChangesImmediately()
See Also: setValidatesChangesImmediately
valueForObject
public Object valueForObject( NSKeyValueCodingAdditions anObject, String key)
valueForObjectAtIndex
public Object valueForObjectAtIndex( int index, String key)
willChange
public void willChange()
Notifications
DisplayGroupWillFetchNotification
public static final String DisplayGroupWillFetchNotification
Notification Object | The EODisplayGroup that received the fetch message. |
Userinfo | None |
© 2001 Apple Computer, Inc. (Last Published April 21, 2001)