WODisplayGroup

Inherits from:
Object

Implements:
NSKeyValueCoding
NSKeyValueCoding.ErrorHandling
NSInlineObservable
NSDisposable
EOKeyValueArchiving
EOKeyValueArchiving.Awaking

Package:
com.webobjects.appserver

Class Description

A WODisplayGroup is the basic user interface manager for a WebObjects application that accesses a database. It collects objects from an EODataSource (defined in EOControl), filters and sorts them, and maintains a selection in the filtered subset. You bind WebObjects dynamic elements to WODisplayGroup attributes and methods to display information from the database on your web page.

A WODisplayGroup 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 (also defined in EOControl). The EOEditingContext then monitors the WODisplayGroup for changes to objects.

Most of a WODisplayGroup's interactions are with its EODataSource and its EOEditingContext. See the EODataSource, and EOEditingContext class specifications in the Enterprise Objects Framework Reference for more information on these interactions.

The Delegate

The WODisplayGroup delegate offers a number of methods, and WODisplayGroup invokes them as appropriate. Besides displayGroupDisplayArrayForObjects, there are methods that inform the delegate that the WODisplayGroup 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. See each method's description in the WODisplayGroup.Delegates interface specification for more information.

Constants

Class Variable	Description
`DisplayGroupWillFetchNotification`	This class variable contains a String that names the notification posted at the beginning of WODisplayGroup's fetch() method.

Interfaces Implemented

NSDisposable
dispose

NSKeyValueCoding
takeValueForKey
valueForKey

NSKeyValueCoding.ErrorHandling
handleQueryWithUnboundKey
handleTakeValueForUnboundKey
unableToSetNullForKey

EOKeyValueArchiving
decodeWithKeyValueUnarchiver
encodeWithKeyValueArchiver

EOKeyValueArchiving.Awaking
awakeFromKeyValueUnarchiver

Method Types

Constructor
WODisplayGroup
Configuring behavior
setFetchesOnLoad
fetchesOnLoad
setSelectsFirstObjectAfterFetch
selectsFirstObjectAfterFetch
setGlobalDefaultForValidatesChangesImmediately
globalDefaultForValidatesChangesImmediately
setValidatesChangesImmediately
validatesChangesImmediately
Setting the data source
setDataSource
dataSource
Setting the qualifier and sort ordering
setQualifier
qualifier
setSortOrderings
sortOrderings
Managing queries
qualifierFromQueryValues
queryMatch
queryMax
queryMin
queryOperator
allQualifierOperators
relationalQualifierOperators
stringQualifierOperators
setGlobalDefaultStringMatchFormat
globalDefaultStringMatchFormat
setDefaultStringMatchFormat
defaultStringMatchFormat
setGlobalDefaultStringMatchOperator
globalDefaultStringMatchOperator
setDefaultStringMatchOperator
defaultStringMatchOperator
qualifyDisplayGroup
qualifyDataSource
inQueryMode
setInQueryMode
Fetching objects from the data source
fetch
Getting the objects
allObjects
displayedObjects
Batching the results
setNumberOfObjectsPerBatch
numberOfObjectsPerBatch
hasMultipleBatches
displayNextBatch
displayPreviousBatch
batchCount
setCurrentBatchIndex
currentBatchIndex
indexOfFirstDisplayedObject
indexOfLastDisplayedObject
displayBatchContainingSelectedObject
Updating display of values
redisplay
updateDisplayedObjects
Setting the objects
setObjectArray
Changing the selection
clearSelection
selectNext
selectObjectsIdenticalTo
selectObjectsIdenticalToSelectFirstOnNoMatch
selectObject
selectPrevious
setSelectedObject
setSelectedObjects
setSelectionIndexes
Examining the selection
selectionIndexes
selectedObject
selectedObjects
Inserting and deleting objects
insertObjectAtIndex
insertNewObjectAtIndex
insert
setInsertedObjectDefaultValues
insertedObjectDefaultValues
deleteObjectAtIndex
deleteSelection
delete
Setting up a detail display group
hasDetailDataSource
setMasterObject
masterObject
setDetailKey
detailKey
Working with named fetch specifications
queryBindings
Setting the delegate
setDelegate
delegate

Constructors

WODisplayGroup

public WODisplayGroup()

Creates and returns a new WODisplayGroup. The WODisplayGroup then needs to have an EODataSource (defined in EOControl) set with setDataSource.

Static Methods

decodeWithKeyValueUnarchiver

public static Object decodeWithKeyValueUnarchiver( com.webobjects.eocontrol.EOKeyValueUnarchiver unarchiver)

Conformance to EOKeyValueArchiving.

globalDefaultForValidatesChangesImmediately

public static boolean globalDefaultForValidatesChangesImmediately()

Returns the class default controlling whether changes are immediately validated.

See Also: validatesChangesImmediately

globalDefaultStringMatchFormat

public static String globalDefaultStringMatchFormat()

Returns the default string match format for the class.

See Also: defaultStringMatchFormat

globalDefaultStringMatchOperator

public static String globalDefaultStringMatchOperator()

Returns the default string match operator for the class.

See Also: defaultStringMatchOperator

setGlobalDefaultForValidatesChangesImmediately

public static void setGlobalDefaultForValidatesChangesImmediately(boolean flag)

Sets according to flag the class default controlling whether changes are immediately validated.

See Also: setValidatesChangesImmediately

setGlobalDefaultStringMatchFormat

public static void setGlobalDefaultStringMatchFormat(String format)

Sets the default string match format for the class.

See Also: setDefaultStringMatchFormat

setGlobalDefaultStringMatchOperator

public static void setGlobalDefaultStringMatchOperator(String operator)

Sets the default string match operator for the class.

See Also: setDefaultStringMatchOperator

Instance Methods

allObjects

public NSArray allObjects()

Returns all of the objects collected by the receiver.

See Also: displayedObjects, fetch

allQualifierOperators

public NSArray allQualifierOperators()

Returns an array containing all of the relational operators supported by EOControl's EOQualifier, including: =, !=, <, <=, >, >=, "like" and "contains".

awakeFromKeyValueUnarchiver

public void awakeFromKeyValueUnarchiver( com.webobjects.eocontrol.EOKeyValueUnarchiver unarchiver)

Conformance to EOKeyValueArchiving.Awaking.

batchCount

public int batchCount()

The number of batches to display. For example, if the displayed objects array contains two hundred records and the batch size is ten, batchCount returns twenty (twenty batches of ten records each).

clearSelection

public boolean clearSelection()

Invokes setSelectionIndexes to clear the selection, returning true on success and false on failure.

currentBatchIndex

public int currentBatchIndex()

Returns the index of the batch currently being displayed. The total batch count equals the number of displayed objects divided by the batch size. For example, if the WODisplayGroup has one hundred objects to display and the batch size is twenty, there are five batches. The first batch has a batch index of 1.

dataSource

public com.webobjects.eocontrol.EODataSource dataSource()

Returns the receiver's EODataSource (defined in the EOControl framework).

See Also: hasDetailDataSource, setDataSource

defaultStringMatchFormat

public String defaultStringMatchFormat()

Returns the format string that specifies how pattern matching will be performed on string values in the queryMatch dictionary. If a key in the queryMatch dictionary does not have an associated operator in the queryOperator dictionary, then its value is matched using pattern matching, and the format string returned by this method specifies how it will be matched.

defaultStringMatchOperator

public String defaultStringMatchOperator()

Returns the operator used to perform pattern matching for string values in the queryMatch dictionary. If a key in the queryMatch dictionary does not have an associated operator in the queryOperator dictionary, then the operator returned by this method is used to perform pattern matching. Unless the default is changed, this method returns caseInsensitiveLike.

delegate

public Object delegate()

Returns the receiver's delegate.

See Also: setDelegate

delete

public Object delete()

Uses deleteSelection to attempt to delete the selected objects and then causes the page to reload. Returns null to force reloading of the web page.

See Also: deleteObjectAtIndex

deleteObjectAtIndex

public boolean deleteObjectAtIndex(int index)

Attempts to delete the object at index, returning true if successful and false if not. Checks with the delegate using the method displayGroupShouldDeleteObject. If the delegate returns false, this method fails and returns false. If successful, it sends the delegate a displayGroupDidDeleteObject message.

This method performs the delete by sending the private method deleteObject to the EODataSource (defined in the EOControl framework). If that message raises an exception, this method fails and returns false.

See Also: delete, deleteSelection

deleteSelection

public boolean deleteSelection()

Attempts to delete the selected objects, returning true if successful and false if not.

See Also: delete, deleteObjectAtIndex

detailKey

public String detailKey()

For detail display groups, returns the key to the master object that specifies what this detail display group represents. That is, if you send the object returned by the masterObject method a valueForKey message with this key, you obtain the objects controlled by this display group.

This method returns null if the receiver is not a detail display group or if the detail key has not yet been set. You typically create a detail display group by dragging a to-many relationship from EOModeler to an open component in WebObjects Builder.

displayBatchContainingSelectedObject

public Object displayBatchContainingSelectedObject()

Displays the batch containing the selection and sets the current batch index to that batch's index. Returns null to force the page to reload.

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, by the receiver's qualifier and sort ordering.

If batching is in effect, displayedObjects returns the current batch of objects.

See Also: allObjects, updateDisplayedObjects, qualifier, setSortOrderings, displayGroupDisplayArrayForObjects (delegate method)

displayNextBatch

public Object displayNextBatch()

Increments the current batch index, displays that batch of objects, and clears the selection. If the batch currently being displayed is the last batch, this method displays the first batch of objects. Returns null to force the page to reload.

displayPreviousBatch

public Object displayPreviousBatch()

Decrements the current batch index, displays that batch of objects, and clears the selection. If the batch currently being displayed is the first batch, this method displays the last batch of objects. Returns null to force the page to reload.

dispose

public void dispose()

Conformance to NSDisposable.

editingContextPresentErrorMessage

public void editingContextPresentErrorMessage( com.webobjects.eocontrol.EOEditingContext editingContext, String message)

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

encodeWithCoder

public void encodeWithCoder(NSCoder coder)

Encodes the receiver using the supplied NSCoder.

encodeWithKeyValueArchiver

public void encodeWithKeyValueArchiver( com.webobjects.eocontrol.EOKeyValueArchiver archiver)

Conformance to EOKeyValueArchiving.

endEditing

public boolean endEditing()

Attempts to end any editing taking place. If there's no editing association or if the editing association responds true to an endEditing message, returns true. Otherwise returns false.

fetch

public Object fetch()

Attempts to fetch objects from the EODataSource (defined in the EOControl framework).

Before fetching, this method sends displayGroupShouldFetch to the delegate. If this method was successful, it then sends a fetchObjects message to the receiver's EODataSource to replace the object array, and if successful sends the delegate a displayGroupDidFetchObjects message.

This method returns null to force the page to reload.

See Also: allObjects, updateDisplayedObjects

fetchesOnLoad

public boolean fetchesOnLoad()

Returns true if the receiver fetches automatically after the component that contains it is loaded, false if it must be told explicitly to fetch. The default is true. You can set this behavior in WebObjects Builder using the Display Group Options panel. Note that if the display group fetches on load, it performs the fetch each time the component is loaded into the web browser.

See Also: fetch, setFetchesOnLoad

finishInitialization

protected void finishInitialization()

Invoked from the WODisplayGroup constructor and from awakeFromNib to finish initializing a newly created display group. You should never invoke this method directly. Sets the receiver's editing context to it's data source's editing context (if available), registers the receiver for ObjectsChangedInEditingContextNotifications and InvalidatedAllObjectsInStoreNotifications, establishes the receiver as an editor for the editing context, and establishes the receiver as the editing context's message handler (unless the editing context already has a message handler).

hasDetailDataSource

public boolean hasDetailDataSource()

Returns true if the display group's data source is an EODetailDataSource (defined in the EOControl framework), and false otherwise. If you drag a to-many relationship from EOModeler to an open component in WebObjects Builder, you create a display group that has an EODetailDataSource. You can also set this up using the Display Group Options panel in WebObjects Builder.

See Also: detailKey, masterObject

handleQueryWithUnboundKey

public Object handleQueryWithUnboundKey(String key)

Conformance to NSKeyValueCoding.ErrorHandling.

handleTakeValueForUnboundKey

public void handleTakeValueForUnboundKey(Object value, String key)

Conformance to NSKeyValueCoding.ErrorHandling.

hasMultipleBatches

public boolean hasMultipleBatches()

Returns true if the batch count is greater than 1. A display group displays its objects in batches if the numberOfObjectsPerBatch method returns a number that is less than the number of objects in the displayedObjects array.

See Also: batchCount, setNumberOfObjectsPerBatch

indexOfFirstDisplayedObject

public int indexOfFirstDisplayedObject()

Returns the index of the first object displayed by the current batch. For example, if the current batch is displaying items 11 through 20, this method returns 11.

See Also: indexOfLastDisplayedObject

indexOfLastDisplayedObject

public int indexOfLastDisplayedObject()

Returns the index of the last object display by the current batch. For example, if the current batch is displaying items 11 through 20, this method returns 20.

See Also: indexOfFirstDisplayedObject

initWithCoder

public Object initWithCoder(NSCoder coder)

Initializes a newly allocated instance from the supplied NSCoder. Returns this.

inQueryMode

public boolean inQueryMode()

Returns true to indicate that the receiver is in query mode, false otherwise. In query mode, controls in the user interface 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 queryMatch dictionary. When qualifyDisplayGroup or qualifyDataSource is subsequently invoked, the query is performed and the display reverts to displaying values-this time, the objects returned by the query.

See Also: setInQueryMode

insert

public Object insert()

Invokes insertNewObjectAtIndex with an index just past the first index in the selection, or at the end if there's no selection.

This method returns null to force the page to reload.

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. Because the object is empty, the display group has no value to display on the HTML page for that object, meaning that there is nothing for the user to select and modify. Use the setInsertedObjectDefaultValues method to set up a default value so that there is something to display on the page.

insertNewObjectAtIndex

public Object insertNewObjectAtIndex(int index)

Asks the receiver's EODataSource (defined in the EOControl framework) to create a new object by sending it a createObject message, then inserts the new object using insertObjectAtIndex. If a new object can't be created, this method sends the delegate a displayGroupCreateObjectFailedForDataSource message.

If the object is successfully created, this method then sets the default values specified by insertedObjectDefaultValues.

See Also: insert

insertObjectAtIndex

public void insertObjectAtIndex( Object anObject, int index)

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

Raises an exception if index is out of bounds.

See Also: insertNewObjectAtIndex, insert

localKeys

public NSArray localKeys()

Returns the additional keys that EOAssociations can be bound to. A WODisplayGroup'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.

masterObject

public Object masterObject()

Returns the master object for a detail display group (a display group that represents a detail in a master-detail relationship). A detail display group is one that uses an EODetailDataSource (defined in the EOControl framework). You create a detail display group by dragging a to-many relationship from EOModeler to an open component in WebObjects Builder. If the display group is not a detail display group or does not have a master object set, this method returns null.

numberOfObjectsPerBatch

public int numberOfObjectsPerBatch()

Returns the batch size. You can set the batch size using setNumberOfObjectsPerBatch or using WebObjects Builder's Display Group Options panel.

objectsChangedInEditingContext

public void objectsChangedInEditingContext(NSNotification notification)

Redisplays the changed objects in the display group unless the display group's delegate method displayGroupShouldRedisplay indicates that a redisplay should not take place.

objectsInvalidatedInEditingContext

public void objectsInvalidatedInEditingContext(NSNotification notification)

Refetches all objects in the receiving display group unless the display group's delegate method displayGroupShouldRefetch indicates that a refetch should not take place.

qualifier

public com.webobjects.eocontrol.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.

qualifierFromQueryValues

public com.webobjects.eocontrol.EOQualifier qualifierFromQueryValues()

Builds a qualifier constructed from entries in these query dictionaries: queryMatch, queryMax, queryMin, and queryOperator.

See Also: qualifyDataSource, qualifyDisplayGroup

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.

See Also: queryMatch, queryMax,, queryMin, queryOperator

qualifyDisplayGroup

public void qualifyDisplayGroup()

Takes the result of the qualifierFromQueryValues and applies to the receiver using setQualifier. The method updateDisplayedObjects is invoked to refresh the display. If the receiver is in query mode, query mode is exited.

queryBindings

public NSMutableDictionary queryBindings()

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.

queryMatch

public NSMutableDictionary queryMatch()

Returns a dictionary of query values to match. The qualifierFromQueryValues method uses this dictionary along with the queryMax and queryMin dictionaries to construct qualifiers.

Use the queryOperator dictionary to specify the type of matching (=, <, >, like, and so on) for each key in the queryMatch dictionary.

If the queryOperator dictionary does not contain a key contained in the queryMatch dictionary, the default is to match the value exactly (=) if the value is a number or a date and to perform pattern matching if the value is a String. In the case of string values, the defaultStringMatchFormat and defaultStringMatchOperator specify exactly how the pattern matching will be performed.

queryMax

public NSMutableDictionary queryMax()

Returns a dictionary of "less than" query values. The qualifierFromQueryValues method uses this dictionary along with the queryMatch and queryMin dictionaries to construct qualifiers.

queryMin

public NSMutableDictionary queryMin()

Returns a dictionary of "greater than" query values. The qualifierFromQueryValues method uses this dictionary along with the queryMatch and queryMin dictionaries to construct qualifiers.

queryOperator

public NSMutableDictionary queryOperator()

Returns a dictionary of operators to use on items in the queryMatch dictionary. If a key in the queryMatch dictionary also exists in queryOperator, that operator for that key is used. The allQualifierOperators method returns the operator strings you can use as values in this dictionary.

redisplay

public void redisplay()

Sends out a contents changed notification.

relationalQualifierOperators

public NSArray relationalQualifierOperators()

Returns an array containing all of the relational operators supported by EOControl's EOQualifier: =, !=, <, <=, >, and >=. In other words, returns all of the EOQualifier operators except for the ones that work exclusively on strings (such as "like" and "contains").

selectedObject

public Object selectedObject()

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

selectedObjects

public NSArray selectedObjects()

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

selectionIndexes

public NSArray selectionIndexes()

Returns the selection as an array of integers . The integers are indexes into the array returned by displayedObjects.

selectNext

public Object selectNext()

Attempts to select the object just after the currently selected one. The selection is altered in this way:

If there are no objects, does nothing.
If there's no selection, selects the object at index zero.
If the first selected object is the last object in the displayed objects array, selects the first object.
Otherwise selects the object after the first selected object.

This method returns null to force the page to reload.

See Also: selectPrevious, setSelectionIndexes

selectObject

public boolean selectObject(Object anObject)

Attempts to select the object equal to anObject in the receiver's displayed objects array, returning true if successful and false otherwise. anObject is equal to an object in the displayed objects array if its address is the same as the object in the array.

See Also: selectNext, selectPrevious

selectObjectsIdenticalTo

public boolean selectObjectsIdenticalTo(NSArray objectSelection)

Attempts to select the objects in the receiver's displayed objects array whose addresses are equal to those of objects, returning true if successful and false otherwise.

selectObjectsIdenticalToSelectFirstOnNoMatch

public boolean selectObjectsIdenticalToSelectFirstOnNoMatch( NSArray objects, boolean flag)

Selects the objects in the receiver's displayed objects array whose addresses are equal to those of objects, returning true if successful and false otherwise. If no objects in the displayed objects array match objects and flag is true, attempts to select the first object in the displayed objects array.

selectPrevious

public Object selectPrevious()

Attempts to select the object just before the presently selected one. The selection is altered in this way:

If there are no objects, does nothing.
If there's no selection, selects the object at index zero.
If the first selected object is at index zero, selects the last object.
Otherwise selects the object before the first selected object.

This method returns null to force the page to reload.

See Also: selectNext, redisplay

selectsFirstObjectAfterFetch

public boolean selectsFirstObjectAfterFetch()

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

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

setCurrentBatchIndex

public void setCurrentBatchIndex(int anInt)

Displays the anInt batch of objects. The total batch count equals the number of displayed objects divided by the batch size. For example, if the WODisplayGroup has one hundred objects to display and the batch size is twenty, there are five batches. The first batch has a batch index of 1. setCurrentBatchIndex(3) would display the third batch of objects (objects 41 to 60 in this example).

If anInt is greater than the number of batches, this method displays the first batch.

setDataSource

public void setDataSource( com.webobjects.eocontrol.EODataSource aDataSource)

Sets the receiver's EODataSource (defined in the EOControl framework) to aDataSource. In the process, it performs these actions:

Unregisters itself as an editor and message handler for the previous EODataSource's EOEditingContext (also defined in EOControl), if necessary, and registers itself with aDataSource's EOEditingContext. If the new EOEditingContext already has a message handler, however, the receiver doesn't assume that role.
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)

Sets how pattern matching will be performed on String values in the queryMatch dictionary. This format is used for properties listed in the queryMatch dictionary that have String values and that do not have an associated entry in the queryOperator 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 (this default can be overridden on a class basis using setGlobalDefaultStringMatchFormat). For example, if the queryMatch dictionary contains a value "Jo" for the key "Name", the query returns all records whose name values begin with "Jo".

setDefaultStringMatchOperator

public void setDefaultStringMatchOperator(String operator)

Sets the operator used to perform pattern matching for String values in the queryMatch dictionary. This operator is used for properties listed in the queryMatch dictionary that have String values and that do not have an associated entry in the queryOperator dictionary. In these cases, the operator operator is used to perform pattern matching.

The default value for the query match operator is caseInsensitiveLike, which means that the query does not consider case when matching letters (this default can be overridden on a class basis using setGlobalDefaultStringMatchOperator). The other possible value for this operator is like, which matches the case of the letters exactly.

setDelegate

public void setDelegate(Object anObject)

Sets the receiver's delegate to anObject.

See Also: delegate, WODisplayGroup.Delegate

setDetailKey

public void setDetailKey(String detailKey)

Sets the detail key to detailKey for a detail display group. The detail key is the key that retrieves from the master object the objects that this display group manages. You must set a detail key before you set a master object.

If the receiver is not a detail display group, this method has no effect. A display group is a detail display group if its data source is an EODetailDataSource (defined in the EOControl framework). You typically create a detail display group by dragging a to-many relationship from EOModeler to an open component in WebObjects Builder. Doing so sets the detail key and master object, so you rarely need to use this method.

setFetchesOnLoad

public void setFetchesOnLoad(boolean flag)

Controls whether the receiver automatically fetches its objects after being loaded. If flag is true it does; if flag is false the receiver must be told explicitly to fetch. The default is false. You can also set this behavior in WebObjects Builder in the Display Group Options panel.

See Also: fetch, fetchesOnLoad

setInQueryMode

public void setInQueryMode(boolean flag)

Sets according to flag whether the receiver is in query mode. In query mode, controls in the user interface 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 queryMatch dictionary. When qualifyDisplayGroup or qualifyDataSource is subsequently invoked, the query is performed and the display reverts to displaying values-this time, the objects returned by the query.

See Also: inQueryMode

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. Because the object is empty, there is no value to be displayed on the HTML page, meaning there is nothing for the user to select and modify. You use this method to provide at least one field that can be displayed for the newly inserted object. The possible keys into the dictionary are the properties of the entity managed by this display group.

See Also: insertedObjectDefaultValues

setLocalKeys

public void setLocalKeys(NSArray newKeySet)

Sets the additional keys to which EOAssociations can be bound to the strings in supplied NSArray.

setMasterObject

public void setMasterObject(Object masterObject)

Sets the master object to masterObject for detail display groups and then performs a fetch if the display group is set to fetch on load. The master object owns the objects controlled by this display group.

Before you use this method, you should use the setDetailKey to set the key to this relationship. You typically create a detail display group by dragging a to-Many relationship from EOModeler to an open component in WebObjects Builder. Doing so sets the master object and detail key, so you typically do not have to use this method.

If the receiver is not a detail display group, this method has no effect.

See Also: hasDetailDataSource, masterObject

setNumberOfObjectsPerBatch

public void setNumberOfObjectsPerBatch(int count)

Sets the number of objects the receiver displays at a time. For example, suppose you are displaying one hundred records. Instead of displaying all of these at once, you can set the batch size so that the page displays a more manageable number (for example, 10). WebObjects Builder allows you to set the number of objects per batch on the Display Group Options panel.

setObjectArray

public void setObjectArray(NSArray objects)

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

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

setQualifier

public void setQualifier(com.webobjects.eocontrol.EOQualifier aQualifier)

Sets the receiver's qualifier to aQualifier. This qualifier is used to filter the receiver's array of objects for display. Use updateDisplayedObjects to apply the qualifier.

If the receiver's delegate responds to displayGroupDisplayArrayForObjects, that method is used instead of the qualifier to filter the objects.

See Also: displayedObjects, qualifier

setSelectedObject

public void setSelectedObject(Object anObject)

Sets the first selected object in the displayed objects array to anObject.

setSelectedObjects

public void setSelectedObjects(NSArray objects)

Sets the objects selected in the receiver's displayed objects array to objects.

setSelectionIndexes

public boolean setSelectionIndexes(NSArray selection)

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

This method checks the delegate with a displayGroupShouldChangeSelectionToIndexes message. If the delegate returns false, this method also fails and returns false. If the receiver successfully changes the selection, its observers each receive a subjectChanged message and, if necessary, a displayGroupDidChangeSelectedObjects message.

Note: The selection set here is only a programmatic selection; the objects on the screen are not highlighted in any way.

See Also: allObjects

setSelectsFirstObjectAfterFetch

public void setSelectsFirstObjectAfterFetch(boolean flag)

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

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

setSortOrderings

public void setSortOrderings(NSArray keySortOrderArray)

Sets the EOSortOrdering objects (defined in the EOControl framework) that updateDisplayedObjects uses to sort the displayed objects to orderings. Use updateDisplayedObjects to apply the sort orderings.You can also set this value using the WebObjects Builder Display Group Options panel.

If the receiver's delegate responds to displayGroupDisplayArrayForObjects, that method is used instead of the sort orderings to order the objects.

setValidatesChangesImmediately

public void setValidatesChangesImmediately(boolean flag)

Controls the receiver's behavior on encountering a validation error. In the Web context, this method has no effect.

WODisplayGroups by default don't validate changes immediately (although this default can be overridden on a class basis; see setGlobalDefaultForValidatesChangesImmediately).

See Also: - saveChanges (in EOControl's EOEditingContext), - tryToSaveChanges (EOEditingContext Additions), validatesChangesImmediately, setGlobalDefaultForValidatesChangesImmediately

sortOrderings

public NSArray sortOrderings()

Returns an array of EOSortOrdering objects (defined in the EOControl framework) that updateDisplayedObjects uses to sort the displayed objects, as returned by the displayedObjects method.

See Also: setSortOrderings

stringQualifierOperators

public NSArray stringQualifierOperators()

Returns an array containing all of the relational operators supported by EOControl's EOQualifier that work exclusively on strings: "starts with", "contains", "ends with", "is", and "like".

takeValueForKey

public void takeValueForKey(Object value, String key)

Conformance to NSKeyValueCoding.

toString

public String toString()

Returns a String containing a string representation of the receiver.

unableToSetNullForKey

public void unableToSetNullForKey(String key)

Conformance to NSKeyValueCoding.ErrorHandling.

undoManager

public NSUndoManager undoManager()

Returns the receiver's undo manager.

updateDisplayedObjects

public void updateDisplayedObjects()

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

validatesChangesImmediately

public boolean validatesChangesImmediately()

Returns true if the receiver immediately handles validation errors, or leaves them for the EOEditingContext (defined in the EOControl framework) to handle when saving changes.

By default, WODisplayGroups don't validate changes immediately.

valueForKey

public Object valueForKey(String key)

Conformance to NSKeyValueCoding.

willChange

public void willChange()

Notifies observers that the receiver will change.