EODisplayGroup (WebObjects 5.2.3 Reference Documentation)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

WebObjects 5.2.3

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.webobjects.eointerface
Class EODisplayGroup

java.lang.Object
  com.webobjects.eointerface.EODisplayGroup

All Implemented Interfaces:: NSDisposable

public class EODisplayGroup
extends Object
implements NSDisposable

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 Numbers, 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 setValueForObject access the objects by object identifier. EOAssociations can also get and set values for the first object in the selection using selectedObjectValueForKey and setSelectedObjectValue.

See Also:: EOAssociation, EODataSource, EOEditingContext

Nested Class Summary
`static interface`	`EODisplayGroup.Delegate` The EODisplayGroup.Delegate interface defines methods that an EODisplayGroup can invoke in its delegate.

Field Summary
`static String`	`DisplayGroupWillFetchNotification` An NSNotification with this name is posted whenever an EODisplayGroup receives a fetch message.

Constructor Summary
`EODisplayGroup()` Creates a new EODisplayGroup.

Method Summary
`NSArray`	`allObjects()`
`void`	`associationDidBeginEditing(EOAssociation association)` Invoked by `association` when its display object begins editing to record that EOAssociation as the editing association.
`void`	`associationDidEndEditing(EOAssociation association)` Invoked by `association` to clear the editing association.
`boolean`	`associationFailedToValidateValue(EOAssociation association, String value, String key, Object eo, String errorDescription)` Invoked by `association` from its `shouldEndEditingAtIndex` method to let the receiver handle a validation error.
`void`	`awakeFromNib()` Invoked when the receiver is unarchived from a nib file to prepare it for use in an application.
`boolean`	`clearSelection()` Invokes `setSelectionIndexes` to clear the selection.
`boolean`	`contentsChanged()` Returns whether or not there are changes in any of this EODisplayGroup's objects and not all observers have been notified.
`EODataSource`	`dataSource()`
`String`	`defaultStringMatchFormat()`
`String`	`defaultStringMatchOperator()`
`Object`	`delegate()`
`void`	`delete()` Deprecated. Deprecated. Use `deleteSelection` instead.
`boolean`	`deleteObjectAtIndex(int index)` Attempts to delete the object at index.
`boolean`	`deleteSelection()` Attempts to delete the selected objects
`NSArray`	`displayedObjects()`
`void`	`dispose()` Clears all references this association has to other objects especially its display object and EODisplayGroup.
`EOAssociation`	`editingAssociation()` Returns the editing association
`void`	`editingContextPresentErrorMessage(EOEditingContext editingContext, String message)` Invoked by `editingContext` as part of the EOEditingContext.MessageHandlers interface, this method presents an attention panel with `message` as the message to display.
`boolean`	`editingContextShouldContinueFetching(EOEditingContext editingContext, int count, int limit, EOObjectStore objectStore)` Invoked by `editingContext` as part of the EOEditingContext.MessageHandlers interface, this method presents an attention panel prompting the user about whether or not to continue fetching the current result set.
`void`	`editingContextWillSaveChanges(EOEditingContext editingContext)` Invoked by `editingContext` in its `saveChanges` method as part of the EOEditors informal protocol, this method allows the EODisplayGroup to prohibit a save operation.
`boolean`	`editorHasChangesForEditingContext(EOEditingContext editingContext)` Invoked by anEditingContext as part of the EOEditors interface, this method returns `false` if any association is editing, `true` otherwise.
`boolean`	`enabledToSetSelectedObjectValueForKey(String key)` Returns `true` to indicate that a single value association (such as an EOTextFieldAssociation for a JTextField) should be enabled for setting key, `false` otherwise.
`boolean`	`endEditing()` Attempts to end any editing taking place.
`void`	`enterQueryMode()` This action method invokes `setInQueryMode` with an argument of `true`.
`NSDictionary`	`equalToQueryValues()` Returns the receiver's dictionary of `equalTo` query values.
`boolean`	`fetch()` Attempts to fetch objects from the EODataSource.
`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.
`static boolean`	`globalDefaultForValidatesChangesImmediately()` Returns whether or not new instances should handle validation errors.
`static String`	`globalDefaultStringMatchFormat()` Returns the default string match format string used by display group instances.
`static String`	`globalDefaultStringMatchOperator()` Returns the default string match operator used by display group instances.
`NSDictionary`	`greaterThanQueryValues()` Returns the receiver's dictionary of `greaterThan` query values.
`boolean`	`inQueryMode()` Returns whether or not this display group is in query mode.
`void`	`insert()` Invokes `insertNewObjectAtIndex` with an index just past the first index in the selection, or 0 if there is no selection.
`NSDictionary`	`insertedObjectDefaultValues()` Returns the default values to be used for newly inserted objects.
`Object`	`insertNewObjectAtIndex(int newIndex)` Asks the receiver's EODataSource to create a new object by sending it a `createObject` message, then inserts the new object using `insertObjectAtIndex`.
`boolean`	`insertObjectAtIndex(Object createObject, int newIndex)` Inserts `createObject` into the receiver's EODataSource and `displayedObjects` array at `newIndex`, if possible.
`NSDictionary`	`lessThanQueryValues()` Returns the receiver's dictionary of `lessThan` query values.
`NSArray`	`localKeys()` Returns the additional keys that EOAssociations can be bound to.
`void`	`objectsChangedInEditingContext(NSNotification notification)` Notification sent by the notification center when the data source (usually an EOEditingContext) that this display group observes has its objects changed.
`void`	`objectsInvalidatedInEditingContext(NSNotification notification)` Notification sent by the notification center when the data source (usually an EOEditingContext) that this display group observes has its objects invalidated.
`NSArray`	`observingAssociations()` Returns all EOAssociations that observe the receiver's objects.
`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.
`EOQualifier`	`qualifierFromQueryValues()` Builds a qualifier constructed from entries in the three query dictionaries: `equalTo`, `greaterThan`, and `lessThan`.
`void`	`qualifyDataSource()` Takes the result of `qualifierFromQueryValues` and applies to the receiver's data source.
`void`	`qualifyDisplayGroup()` Takes the result of `qualifierFromQueryValues` and applies it to the receiver using `setQualifier`.
`NSDictionary`	`queryBindingValues()` Returns a dictionary containing the actual values that the user wants to query upon.
`NSDictionary`	`queryOperatorValues()` Returns a dictionary of operators to use on items in the query dictionaries (`equalToQueryValues`, `greaterThanQueryValues`, and `lessThanQueryValues`).
`void`	`redisplay()` Notifies all observing associations to redisplay their values.
`Object`	`selectedObject()` Returns the first selected object in the displayed objects array, or `null` if there is no such object.
`NSArray`	`selectedObjects()` Returns the objects selected in the receiver's displayed objects array.
`Object`	`selectedObjectValueForKey(String key)` Returns the value corresponding to `key` for the first selected object in the receiver's displayed objects array, or `null` if no objects are selected.
`boolean`	`selectionChanged()` Returns `true` if the selection has changed and not all observers have been notified, `false` otherwise.
`NSArray`	`selectionIndexes()` Returns the indexes of the receiver's selected objects as Numbers, in terms of its displayed objects array.
`boolean`	`selectNext()` Attempts to select the object just after the currently selected one, returning `true` if successful and `false` if not.
`boolean`	`selectObject(Object object)` Attempts to find and select `object`.
`boolean`	`selectObjectsIdenticalTo(NSArray objectSelection)` Attempts to select the objects in the receiver's displayed objects array which are equal to those of `objectSelection`.
`boolean`	`selectObjectsIdenticalToSelectFirstOnNoMatch(NSArray objectSelection, boolean selectFirstOnNoMatch)` Selects the objects in the receiver's displayed objects array that are equal to those of `objectSelection`.
`boolean`	`selectPrevious()` Attempts to select the object just before the presently selected one, returning `true` if successful and `false` if not.
`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.
`void`	`setDataSource(EODataSource ds)` Sets the receiver's EODataSource to `ds`.
`void`	`setDefaultStringMatchFormat(String format)` Sets how pattern matching will be performed on String values in the query dictionaries ( `equalToQueryValues`, `greaterThanQueryValues`, and `lessThanQueryValues`).
`void`	`setDefaultStringMatchOperator(String op)` Sets the operator used to perform pattern matching for String values in the `queryMatch` dictionary.
`void`	`setDelegate(Object anObject)` Sets the receiver's delegate to `anObject`.
`void`	`setEqualToQueryValues(NSDictionary values)` Sets to values the receiver's dictionary of `equalTo` query values.
`void`	`setFetchesOnLoad(boolean yn)` Controls whether the receiver automatically fetches its objects after being loaded from a nib file.
`static void`	`setGlobalDefaultForValidatesChangesImmediately(boolean yn)` Sets the default behavior display group instances use when they encounter a validation error.
`static void`	`setGlobalDefaultStringMatchFormat(String format)` Sets the default string match format to be used by display group instances.
`static void`	`setGlobalDefaultStringMatchOperator(String op)` Sets the default string match operator to be used by display group instances.
`void`	`setGreaterThanQueryValues(NSDictionary values)` Sets to values the receiver's dictionary of `greaterThan` query values.
`void`	`setInQueryMode(boolean yn)` Sets according to `yn` whether the receiver is in query mode.
`void`	`setInsertedObjectDefaultValues(NSDictionary defaultValues)` Sets default values to be used for newly inserted objects.
`void`	`setLessThanQueryValues(NSDictionary values)` Sets to values the receiver's dictionary of `lessThan` query values.
`void`	`setLocalKeys(NSArray newKeySet)` Sets the additional keys to which EOAssociations can be bound to the strings in `newKeySet`.
`void`	`setObjectArray(NSArray array)` Sets the receiver's objects to `array`, regardless of what its EODataSource provides.
`void`	`setQualifier(EOQualifier qualifier)` Sets the receiver's qualifier to `qualifier`.
`void`	`setQueryBindingValues(NSDictionary values)` Sets the dictionary of values that a user wants to query on.
`void`	`setQueryOperatorValues(NSDictionary values)` Sets the dictionary of operators to use on items in the query dictionaries ( `equalToQueryValues`, `greaterThanQueryValues`, and `lessThanQueryValues`).
`void`	`setSelectedObject(Object anObject)` Sets the selected objects to `anObject`.
`void`	`setSelectedObjects(NSArray objects)` Sets the selected objects to objects.
`boolean`	`setSelectedObjectValue(Object value, String key)` Invokes `setValueForObject` with the first selected object, returning `true` if successful and `false` otherwise.
`boolean`	`setSelectionIndexes(NSArray s)` Selects the objects at indexe of `s` in the receiver's array if possible, returning `true` if successful and `false` if not (in which case the selection remains unaltered).
`void`	`setSelectsFirstObjectAfterFetch(boolean yn)` Controls whether the receiver automatically selects its first displayed object after a fetch when there were no selected objects before the fetch.
`void`	`setSortOrderings(NSArray keySortOrderArray)` Sets the EOSortOrdering objects that `updateDisplayedObjects` uses to sort the displayed objects to orderings.
`void`	`setUsesOptimisticRefresh(boolean yn)` Controls how the receiver redisplays on changes to objects.
`void`	`setValidatesChangesImmediately(boolean yn)` Controls the receiver's behavior on encountering a validation error.
`boolean`	`setValueForObject(Object value, Object eo, String key)` Sets a property of `eo`, identified by `key`, to `value`.
`boolean`	`setValueForObjectAtIndex(Object value, int index, String key)` Invokes `setValueForObject` with the object at `index`.
`NSArray`	`sortOrderings()` Returns an array of EOSortOrdering objects that `updateDisplayedObjects` uses to sort the displayed objects, as returned by the `displayedObjects` method.
`NSUndoManager`	`undoManager()` Returns the receiver's undo manager.
`void`	`updateDisplayedObjects()` Recalculates the receiver's displayed objects array and redisplays.
`int`	`updatedObjectIndex()` Returns the index in the displayed objects array of the most recently updated object, or if more than one object has changed.
`boolean`	`usesOptimisticRefresh()` Returns `true` if the receiver redisplays only when its displayed objects change, `false` if it redisplays on any change in its EOEditingContext.
`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.
`Object`	`valueForObject(Object object, String key)` Returns `object`'s value for the property identified by `key`.
`Object`	`valueForObjectAtIndex(int index, String key)` Returns the value of the object at index for the property identified by `key`.
`void`	`willChange()` Notifies observers that the receiver will change.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DisplayGroupWillFetchNotification

public static final String DisplayGroupWillFetchNotification

An NSNotification with this name is posted whenever an EODisplayGroup receives a fetch message. The notification contains: Notification Object - The EODisplayGroup that received the fetch message. Userinfo - None

Constructor Detail

EODisplayGroup

public EODisplayGroup()

Creates a new EODisplayGroup. The new display group needs to have an EODataSource set with setDataSource.
See Also:: EOAssociation.bindAspect(java.lang.String, com.webobjects.eointerface.EODisplayGroup, java.lang.String)

Method Detail

allObjects

public NSArray allObjects()

Returns:: all of the objects collected by this EODisplaygroup
See Also:: displayedObjects(), fetch()

associationDidBeginEditing

public void associationDidBeginEditing(EOAssociation association)

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

Parameters:: association - the editing association.
See Also:: editingAssociation(), endEditing(), associationFailedToValidateValue(com.webobjects.eointerface.EOAssociation, java.lang.String, java.lang.String, java.lang.Object, java.lang.String)

associationDidEndEditing

public void associationDidEndEditing(EOAssociation association)

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

Parameters:: association - the association that wants to clear the editing association.
See Also:: editingAssociation(), endEditing(), associationFailedToValidateValue(com.webobjects.eointerface.EOAssociation, java.lang.String, java.lang.String, java.lang.Object, java.lang.String)

associationFailedToValidateValue

public boolean associationFailedToValidateValue(EOAssociation association,
                                                String value,
                                                String key,
                                                Object eo,
                                                String errorDescription)

Invoked by association 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.

Parameters:: association - the EOAssociation for which validation failed.; value - display value for which validation failed.; key - key for the EO.; eo - EnterpriseObject in which the value had attempted to be set.; errorDescription - description of why the validation failed.
Returns:: false.
See Also:: EODisplayGroup.Delegate.displayGroupShouldDisplayAlert(EODisplayGroup, String, String)

awakeFromNib

public void awakeFromNib()

Invoked when the receiver is unarchived from a nib file to prepare it for use in an application. You should never invoke this method directly. Finishes initializing the receiver and updates the display.

See Also:: redisplay()

clearSelection

public boolean clearSelection()

Invokes setSelectionIndexes to clear the selection.

Returns:: true on success and false on failure

contentsChanged

public boolean contentsChanged()

Returns whether or not there are changes in any of this EODisplayGroup's objects and not all observers have been notified. EOAssociations use this in their subjectChanged methods to determine what they need to update.

Returns:: true if the receiver's array of objects has changed and not all observers have been notified, false otherwise.
See Also:: selectionChanged(), updatedObjectIndex()

dataSource

public EODataSource dataSource()

Returns:: the receiver's EODataSource.
See Also:: setDataSource(com.webobjects.eocontrol.EODataSource)

defaultStringMatchFormat

public String defaultStringMatchFormat()

Returns:: the format string that specifies how pattern matching will be performed on string values in the query dictionaries ( equalToQueryValues, greaterThanQueryValues, and lessThanQueryValues). 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(String matchOperator)

defaultStringMatchOperator

public String defaultStringMatchOperator()

Returns:: the operator used to perform pattern matching for string values in the query dictionaries (equalToQueryValues, greaterThanQueryValues, and lessThanQueryValues). If a key in one of the query dictionaries 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(java.lang.String)

delegate

public Object delegate()

Returns:: this display groups delegate
See Also:: setDelegate(java.lang.Object)

delete

public void delete()

Deprecated. Deprecated. Use deleteSelection instead.

deleteObjectAtIndex

public boolean deleteObjectAtIndex(int index)

Attempts to delete the object at index. 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.

Parameters:: index - index of object to delete from this display group's object array.
Returns:: true if the delete operation was successful and false if not.

deleteSelection

public boolean deleteSelection()

Attempts to delete the selected objects

Returns:: true if delete selection succeeds and false otherwise

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(), EODisplayGroup.Delegate.displayGroupDisplayArrayForObjects(EODisplayGroup, NSArray), qualifier(), sortOrderings()

dispose

public void dispose()

Clears all references this association has to other objects especially its display object and EODisplayGroup. Call this method before nulling out a reference to this association to ensure it gets garbage collected properly. Subclasses should override this method to do any additional cleanup that may be needed and invoke super's implementation at the end.

Specified by:: dispose in interface NSDisposable

See Also:: NSDisposable

editingAssociation

public EOAssociation editingAssociation()

Returns the editing association

Returns:: the EOAssociation editing a value if there is one, null if there isn't.
See Also:: associationDidBeginEditing(com.webobjects.eointerface.EOAssociation), associationDidEndEditing(com.webobjects.eointerface.EOAssociation)

editingContextPresentErrorMessage

public void editingContextPresentErrorMessage(EOEditingContext editingContext,
                                              String message)

Invoked by editingContext as part of the EOEditingContext.MessageHandlers interface, this method presents an attention panel with message as the message to display.

Parameters:: editingContext - EOEditingContext.; message - string displayed in the attention panel.

editingContextShouldContinueFetching

public boolean editingContextShouldContinueFetching(EOEditingContext editingContext,
                                                    int count,
                                                    int limit,
                                                    EOObjectStore objectStore)

Invoked by editingContext as part of the EOEditingContext.MessageHandlers interface, this method presents an attention panel prompting the user about whether or not to continue fetching the current result set.

Parameters:: editingContext - the EOEditingContext that invoked the method.; count - number of objects per batch.; limit - maximum number of objects to fetch before notifying the user.; objectStore - an EOObjectStore.
Returns:: true if the user chooses to continue fetching the next batch of objects or all objects, false otherwise.

editingContextWillSaveChanges

public void editingContextWillSaveChanges(EOEditingContext editingContext)

Invoked by editingContext 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 endEditing returns false. Thus, if there's an association that refuses to end editing, editingContext doesn't save changes.

Parameters:: editingContext - The EOEditingContext that invoked the method.

editorHasChangesForEditingContext

public boolean editorHasChangesForEditingContext(EOEditingContext editingContext)

Invoked by anEditingContext as part of the EOEditors interface, this method returns false if any association is editing, true otherwise.

Parameters:: editingContext - EOEditingContext that invoked this method
Returns:: false if any association is editing, true otherwise
See Also:: editingAssociation(), associationDidBeginEditing(com.webobjects.eointerface.EOAssociation), associationDidEndEditing(com.webobjects.eointerface.EOAssociation)

enabledToSetSelectedObjectValueForKey

public boolean enabledToSetSelectedObjectValueForKey(String key)

Returns true to indicate that a single value association (such as an EOTextFieldAssociation for a JTextField) 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.

Parameters:: key - a String representing an EO key.
Returns:: true to indicate that a single value association should be enabled for setting key, false otherwise.

endEditing

public boolean endEditing()

Attempts to end any editing taking place.

Returns:: true if there's no editing assocation or if the editing association responds true to an endEditing message. false otherwise.
See Also:: editingAssociation()

enterQueryMode

public void enterQueryMode()

This action method invokes setInQueryMode with an argument of true.

equalToQueryValues

public NSDictionary equalToQueryValues()

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.

Returns:: this EODisplayGroup's dictionary of equalTo query values.
See Also:: setEqualToQueryValues(com.webobjects.foundation.NSDictionary), greaterThanQueryValues(), lessThanQueryValues()

fetch

public boolean fetch()

Attempts to fetch objects from the EODataSource. 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.

Returns:: true if the fetch succeeds and false otherwise.

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.

Returns:: true if this EODisplayGroup fetches automatically after being loaded from a nib file, false if it must be told explicitly to fetch.
See Also:: fetch(), fetchesOnLoad()

globalDefaultForValidatesChangesImmediately

public static boolean globalDefaultForValidatesChangesImmediately()

Returns whether or not new instances should handle validation errors.

Returns:: 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()

Returns the default string match format string used by display group instances.

Returns:: format string used for matching by default in display group instances
See Also:: defaultStringMatchFormat()

globalDefaultStringMatchOperator

public static String globalDefaultStringMatchOperator()

Returns the default string match operator used by display group instances.

Returns:: operator string used for matching by default in display group instances
See Also:: defaultStringMatchOperator()

greaterThanQueryValues

public NSDictionary greaterThanQueryValues()

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.

Returns:: this display group's dictionary of "greaterThan" query values.
See Also:: setGreaterThanQueryValues(com.webobjects.foundation.NSDictionary), equalToQueryValues()

inQueryMode

public boolean inQueryMode()

Returns whether or not this display group is in query mode. 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.

Returns:: true to indicate that the receiver is in query mode, false otherwise
See Also:: setInQueryMode(boolean), enterQueryMode()

insert

public void insert()

Invokes insertNewObjectAtIndex with an index just past the first index in the selection, or 0 if there is no selection.

insertNewObjectAtIndex

public Object insertNewObjectAtIndex(int newIndex)

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.

Parameters:: newIndex - index at which to insert the new object in this display group's object array.
Returns:: the newly created object that was inserted, or null if object creation failed.
See Also:: insert()

insertObjectAtIndex

public boolean insertObjectAtIndex(Object createObject,
                                   int newIndex)

Inserts createObject into the receiver's EODataSource and displayedObjects array at newIndex, if possible. This method checks with the delegate before actually inserting, using displayGroupShouldInsertObject. If the delegate refuses, createObject 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 newIndex is out of bounds. Unlike the insertNewObjectAtIndex method, this method does not insert the object into the EOEditingContext. If you use this method, you are responsible for inserting the object into the EOEditingContext yourself.

Parameters:: createObject - object to insert into this display group's object array.; newIndex - index of this display group's object array at which to insert the object.
Returns:: true if the insertion succeeded, false if endEditing() fails, if the delegate returns false for shouldInsertObject, or if the inserting the object into the datasource failed for any reason.

insertedObjectDefaultValues

public NSDictionary insertedObjectDefaultValues()

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. Use the setInsertedObjectDefaultValues method to set up a default value for newly inserted objects

Returns:: immutable dicationary of default values to be used for newly inserted objects.
See Also:: setInsertedObjectDefaultValues(com.webobjects.foundation.NSDictionary)

lessThanQueryValues

public NSDictionary lessThanQueryValues()

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.

Returns:: this display groups dictionary of lessThan query values.
See Also:: setLessThanQueryValues(com.webobjects.foundation.NSDictionary), 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.

Returns:: immutable array of additional keys that EOAssociations can be bound to.
See Also:: setLocalKeys(com.webobjects.foundation.NSArray)

objectsChangedInEditingContext

public void objectsChangedInEditingContext(NSNotification notification)

Notification sent by the notification center when the data source (usually an EOEditingContext) that this display group observes has its objects changed. If objects were deleted from the data source, they will be in the userInfo dictionary of notification with the key "deleted". If the deleted array is not null and not empty, or if the delegate is not set, or if the delegate is set and responds true to shouldRedisplay, redisplay is called.

Parameters:: notification - containing, in its userInfo dictionary an array of the objects deleted from the editing context if any.
See Also:: redisplay()

objectsInvalidatedInEditingContext

public void objectsInvalidatedInEditingContext(NSNotification notification)

Notification sent by the notification center when the data source (usually an EOEditingContext) that this display group observes has its objects invalidated. If the delegate is not set, or if it is set and responds true to shouldRefetch, fetch is called.

Parameters:: notification -
See Also:: fetch()

observingAssociations

public NSArray observingAssociations()

Returns all EOAssociations that observe the receiver's objects.

Returns:: immutable array of 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.

Returns:: EOQualifier this display group uses to filter its objects when the delegate doesn't do it itself.
See Also:: updateDisplayedObjects(), displayedObjects(), setQualifier(com.webobjects.eocontrol.EOQualifier)

qualifierFromQueryValues

public EOQualifier qualifierFromQueryValues()

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.

Returns:: EOQualifier constructed from this display group's three query dictionaries
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 it 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.

queryBindingValues

public NSDictionary queryBindingValues()

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.

Returns:: immutable dictionary of query binding values

queryOperatorValues

public NSDictionary queryOperatorValues()

Returns a dictionary of operators to use on items in the query dictionaries (equalToQueryValues, greaterThanQueryValues, and lessThanQueryValues). If a key in a query dictionary also exists in queryOperatorValues, that operator for that key is used.

Returns:: immutable dictionary of operators for items in the query dictionaries
See Also:: qualifierFromQueryValues()

redisplay

public void redisplay()

Notifies all observing associations to redisplay their values.

See Also:: observingAssociations()

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:

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.

Returns:: true if selection was successful, false otherwise

selectObject

public boolean selectObject(Object object)

Attempts to find and select object. If object cannot be found, it clears the selection. The selection is performed on the receiver's displayedObjects, not on allObjects.

Parameters:: object - object to try to select
Returns:: true if the receiver has found and selected object, false if it can't find a match for object

selectObjectsIdenticalTo

public boolean selectObjectsIdenticalTo(NSArray objectSelection)

Attempts to select the objects in the receiver's displayed objects array which are equal to those of objectSelection.

Parameters:: objectSelection - NSArray of objects to attempt to select matches for in this display group's displayed objects.
Returns:: true if selection is successful, false otherwise.
See Also:: selectObjectsIdenticalToSelectFirstOnNoMatch(com.webobjects.foundation.NSArray, boolean)

selectObjectsIdenticalToSelectFirstOnNoMatch

public boolean selectObjectsIdenticalToSelectFirstOnNoMatch(NSArray objectSelection,
                                                            boolean selectFirstOnNoMatch)

Selects the objects in the receiver's displayed objects array that are equal to those of objectSelection. If no objects in the displayed objects array match objects in objectSelection and selectFirstOnNoMatch is true, attempts to select the first object in the displayed objects array.

Parameters:: objectSelection - NSArray of objects to attempt to select.; selectFirstOnNoMatch - if true, this method attempts to select the first object in the displayed objects array if no match is made between the displayed objects and objectSelection.
Returns:: true if selection is successful and false otherwise.
See Also:: setSelectionIndexes(com.webobjects.foundation.NSArray)

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:

If there are no objects, does nothing and returns false.
If there is 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.

Returns:: true if selection succeeded, false otherwise.

selectedObject

public Object selectedObject()

Returns the first selected object in the displayed objects array, or null if there is no such object.

Returns:: the first selected object in the displayed objects array, or null if there is no such object
See Also:: displayedObjects(), selectionIndexes()

selectedObjectValueForKey

public Object selectedObjectValueForKey(String key)

Returns the value corresponding to key for the first selected object in the receiver's displayed objects array, or null if no objects are selected.

Parameters:: key - string key for which to return value.
Returns:: value for the selected object's key, or null if no objects are selected.
See Also:: valueForObjectAtIndex(int, java.lang.String)

selectedObjects

public NSArray selectedObjects()

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

Returns:: immutable containing objects selected in the receiver's displayed Objects array.
See Also:: displayedObjects(), selectionIndexes()

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.

Returns:: true if the selection has changed and not all observers have been notified, false otherwise.
See Also:: contentsChanged()

selectionIndexes

public NSArray selectionIndexes()

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

Returns:: immutable array of Numbers corresponding to the indexes of the display group's selected objects in its displayed objects array.
See Also:: displayedObjects(), selectedObjects(), selectedObject(), setSelectionIndexes(com.webobjects.foundation.NSArray)

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.

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(boolean)

setDataSource

public void setDataSource(EODataSource ds)

Sets the receiver's EODataSource to ds. In the process, it performs these actions:

Unregisters the receiver as an editor and message handler for the previous EODataSource's EOEditingContext, if necessary, and registers the receiver with ds's editing context. If the new editing context already has a message handler, however, the receiver doesn't assume that role.
Registers this for ObjectsChangedInEditingContextNotification and InvalidatedAllObjectsInStoreNotification from the new editing context.
Clears the receiver's array of objects.
Sends displayGroupDidChangeDataSource to the delegate if there is one.

Parameters:: ds - the EODataSource object to set as the display group's data source.
See Also:: dataSource()

setDefaultStringMatchFormat

public void setDefaultStringMatchFormat(String format)

Sets how pattern matching will be performed on String values in the query dictionaries ( equalToQueryValues, greaterThanQueryValues, and lessThanQueryValues). This format is used for query dictionary properties 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 query dictionary contains a value "Jo" for the key "Name", the query returns all records whose name values begin with "Jo".

Parameters:: format - string specifying the pattern matching format.
See Also:: defaultStringMatchFormat(), setDefaultStringMatchOperator(java.lang.String)

setDefaultStringMatchOperator

public void setDefaultStringMatchOperator(String op)

Sets the operator used to perform pattern matching for String values in the queryMatch dictionary. This operator is used for properties listed in the query dictionaries ( equalToQueryValues, greaterThanQueryValues, and lessThanQueryValues) that have String values and that do not have an associated entry in the queryOperatorValues dictionary. In these cases, the operator matchOperator 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.

Parameters:: op - operator used to perform pattern matching.
See Also:: defaultStringMatchOperator(), setDefaultStringMatchFormat(java.lang.String)

setDelegate

public void setDelegate(Object anObject)

Sets the receiver's delegate to anObject.

Parameters:: anObject - the object to send delegate messages to for this display group.
See Also:: delegate()

setEqualToQueryValues

public void setEqualToQueryValues(NSDictionary values)

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.

Parameters:: values - dictionary of query values to be used for equalTo queries.
See Also:: equalToQueryValues(), setLessThanQueryValues(com.webobjects.foundation.NSDictionary), setGreaterThanQueryValues(com.webobjects.foundation.NSDictionary)

setFetchesOnLoad

public void setFetchesOnLoad(boolean yn)

Controls whether the receiver automatically fetches its objects after being loaded from a nib file. If yn is true it does; if yn 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.

Parameters:: yn - if true this display group fetches its objects automatically after being loaded from a nib file; if false the receiver must be told explicitly to fetch. The default is false.
See Also:: fetch(), fetchesOnLoad()

setGlobalDefaultForValidatesChangesImmediately

public static void setGlobalDefaultForValidatesChangesImmediately(boolean yn)

Sets the default behavior display group instances use when they encounter a validation error.

Parameters:: yn - if yn is true, the default behavior is for display groups to immediately present an attention panel indicating a validation error. If false, the default behavior is 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(boolean)

setGlobalDefaultStringMatchFormat

public static void setGlobalDefaultStringMatchFormat(String format)

Sets the default string match format to be used by display group instances. The default format string for pattern matching is "%@*".

Parameters:: format - string match format to be used by display group instances.
See Also:: setDefaultStringMatchFormat(java.lang.String)

setGlobalDefaultStringMatchOperator

public static void setGlobalDefaultStringMatchOperator(String op)

Sets the default string match operator to be used by display group instances. The default operator is "caseInsensitiveLike".

Parameters:: op - string match operator to be used by display group instances.
See Also:: setDefaultStringMatchOperator(java.lang.String)

setGreaterThanQueryValues

public void setGreaterThanQueryValues(NSDictionary values)

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.

Parameters:: values - dictionary of query values to be used for greaterThan queries.
See Also:: greaterThanQueryValues(), setLessThanQueryValues(com.webobjects.foundation.NSDictionary), setEqualToQueryValues(com.webobjects.foundation.NSDictionary)

setInQueryMode

public void setInQueryMode(boolean yn)

Sets according to yn whether the receiver is in query mode.

Parameters:: yn - if true, puts this display group into query mode, if false, makes the display group exit query mode.
See Also:: inQueryMode(), enterQueryMode()

setInsertedObjectDefaultValues

public void setInsertedObjectDefaultValues(NSDictionary defaultValues)

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. 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.

Parameters:: defaultValues - default values to be used for newly inserted objects.
See Also:: insertedObjectDefaultValues()

setLessThanQueryValues

public void setLessThanQueryValues(NSDictionary values)

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.

Parameters:: values - dictionary of query values to be used for lessThan queries.
See Also:: lessThanQueryValues(), setGreaterThanQueryValues(com.webobjects.foundation.NSDictionary), setEqualToQueryValues(com.webobjects.foundation.NSDictionary)

setLocalKeys

public void setLocalKeys(NSArray newKeySet)

Sets the additional keys to which EOAssociations can be bound to the strings in newKeySet. Instead of invoking this method programmatically, you can use Interface Builder to add and remove local keys in the EODisplayGroup Attributes Inspector panel.

Parameters:: newKeySet - array of additional keys to which EOAssociations can be bound to.
See Also:: localKeys()

setObjectArray

public void setObjectArray(NSArray array)

Sets the receiver's objects to array, 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. array 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.

Parameters:: array - array of objects for this display group to manage
See Also:: allObjects(), displayedObjects(), selectsFirstObjectAfterFetch()

setQualifier

public void setQualifier(EOQualifier qualifier)

Sets the receiver's qualifier to qualifier. This qualifier is used to filter (in memory) the receiver's array of objects for display when the delegate doesn't do so itself. Use updateDisplayedObjects to apply the qualifier. 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.

Parameters:: qualifier - EOQualifier to be used to filter (in memory) the receiver's array of objects for display when the delegate doesn't do so itself.
See Also:: displayedObjects(), qualifier(), qualifierFromQueryValues()

setQueryBindingValues

public void setQueryBindingValues(NSDictionary values)

Sets the dictionary of values that a user wants to query on. You use this method to perform a query stored in the model file. Bind keys in the queryBindingValues dictionary to elements of your component that specify query values.

Parameters:: values - dictionary of values that a user wants to query on.

setQueryOperatorValues

public void setQueryOperatorValues(NSDictionary values)

Sets the dictionary of operators to use on items in the query dictionaries ( equalToQueryValues, greaterThanQueryValues, and lessThanQueryValues). If a key in a query dictionary also exists in queryOperatorValues, that operator for that key is used.

Parameters:: values - dictionary of operators to use on items in the query dictionaries.

setSelectedObject

public void setSelectedObject(Object anObject)

Sets the selected objects to anObject.

Parameters:: anObject - the object to attempt to select. If null, the selection is cleared.

setSelectedObjectValue

public boolean setSelectedObjectValue(Object value,
                                      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.

Parameters:: value - value to set for key on the selected object.; key - key string for which to value on the selected object.
Returns:: true if successful and false otherwise.
See Also:: setValueForObjectAtIndex(java.lang.Object, int, java.lang.String), valueForObject(java.lang.Object, java.lang.String)

setSelectedObjects

public void setSelectedObjects(NSArray objects)

Sets the selected objects to objects.

Parameters:: objects - array of objects to attempt to select.

setSelectionIndexes

public boolean setSelectionIndexes(NSArray s)

Selects the objects at indexe of s in the receiver's array if possible, returning true if successful and false if not (in which case the selection remains unaltered). 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.

Parameters:: s - an array of Numbers.
Returns:: true if successful and false if not (in which case the selection remains unaltered).

setSelectsFirstObjectAfterFetch

public void setSelectsFirstObjectAfterFetch(boolean yn)

Controls whether the receiver automatically selects its first displayed object after a fetch when there were no selected objects before the fetch.

Parameters:: yn - if true it automatically selects its first displayed object after a fetch; if yn 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 keySortOrderArray)

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.

Parameters:: keySortOrderArray - array of EOSortOrdering objects that updateDisplayedObjects will use to sort the displayed objects.
See Also:: displayedObjects(), sortOrderings()

setUsesOptimisticRefresh

public void setUsesOptimisticRefresh(boolean yn)

Controls how the receiver redisplays on changes to objects. 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. You can also change this setting in Interface Builder's Inspector panel using the Refresh All check box.

Parameters:: yn - if true the display group redisplays only when elements of its displayed objects array change; if false it redisplays on any change in its EOEditingContext. The default is false.
See Also:: usesOptimisticRefresh()

setValidatesChangesImmediately

public void setValidatesChangesImmediately(boolean yn)

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.

Parameters:: yn - if true, the receiver immediately presents an attention panel indicating the validation error. If false, the receiver leaves validation errors to be handled when changes are saved. By default, display groups don't validate changes immediately.
See Also:: EOEditingContext.saveChanges(), validatesChangesImmediately()

setValueForObject

public boolean setValueForObject(Object value,
                                 Object eo,
                                 String key)

Sets a property of eo, identified by key, to value. 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 eo 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.

Parameters:: value - object value to set property to.; eo - Enterprise Object on which to set the property value.; key - string identifier of the property to set the value of.
Returns:: true if setting value was successful and false otherwise.
See Also:: setValueForObjectAtIndex(java.lang.Object, int, java.lang.String), setSelectedObjectValue(java.lang.Object, java.lang.String), valueForObject(java.lang.Object, java.lang.String), validatesChangesImmediately()

setValueForObjectAtIndex

public boolean setValueForObjectAtIndex(Object value,
                                        int index,
                                        String key)

Invokes setValueForObject with the object at index. This method should be invoked only by EOAssociation objects to propagate changes from display objects.

Parameters:: value - value to set the property identified by key to.; index - index of the object in the displayed objects array to set value in.; key - string identifier for the property of the object to set the value of.
Returns:: true if setValueForObject is successful and false otherwise.
See Also:: setSelectedObjectValue(java.lang.Object, java.lang.String), valueForObjectAtIndex(int, java.lang.String)

sortOrderings

public NSArray sortOrderings()

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

Returns:: immutable array of EOSortOrdering objects that updateDisplayedObjects uses to sort the displayed objects as returned by the displayedObjects method.
See Also:: setSortOrderings(com.webobjects.foundation.NSArray)

undoManager

public NSUndoManager undoManager()

Returns the receiver's undo manager.

Returns:: the display group's undo manager

updateDisplayedObjects

public void updateDisplayedObjects()

Recalculates the receiver's displayed objects array and redisplays. If the receiver's delegate responds to displayGroupDisplayArrayForObjects, it is sent this message and the returned array is set as the display group's displayed objects. 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 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.

Returns:: the index in the displayed objects array of the most recently updated object, or if more than one object has changed. The return value is meaningful only when contentsChanged returns true.

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.

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(boolean)

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.

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(boolean)

valueForObject

public Object valueForObject(Object object,
                             String key)

Returns object's value for the property identified by key.

Parameters:: object - Enterprise Object from which this method should get the value.; key - string identifier for anObject's property.
Returns:: object's value for the property identified by key or null if object is null.

valueForObjectAtIndex

public Object valueForObjectAtIndex(int index,
                                    String key)

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

Parameters:: index - index of the object from which this method will get value.; key - string identifier of the property for which to get value.
Returns:: value of the object at index for the property identified by key.

willChange

public void willChange()

Notifies observers that the receiver will change.