PATH |
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()
Static Methods
decodeWithKeyValueUnarchiver
public static Object decodeWithKeyValueUnarchiver( com.webobjects.eocontrol.EOKeyValueUnarchiver unarchiver)
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()
See Also: displayedObjects, fetch
allQualifierOperators
public NSArray allQualifierOperators()
See Also: queryOperator, relationalQualifierOperators, stringQualifierOperators
awakeFromKeyValueUnarchiver
public void awakeFromKeyValueUnarchiver( com.webobjects.eocontrol.EOKeyValueUnarchiver unarchiver)
batchCount
public int batchCount()
See Also: currentBatchIndex, displayNextBatch, displayPreviousBatch, hasMultipleBatches, numberOfObjectsPerBatch
clearSelection
public boolean clearSelection()
true
on success and false
on failure.
currentBatchIndex
public int currentBatchIndex()
See Also: batchCount, numberOfObjectsPerBatch, setCurrentBatchIndex
dataSource
public com.webobjects.eocontrol.EODataSource dataSource()
See Also: hasDetailDataSource, setDataSource
defaultStringMatchFormat
public String defaultStringMatchFormat()
See Also: defaultStringMatchOperator, setDefaultStringMatchFormat, globalDefaultStringMatchFormat
defaultStringMatchOperator
public String defaultStringMatchOperator()
See Also: defaultStringMatchFormat, setDefaultStringMatchOperator, globalDefaultStringMatchOperator
delegate
public Object delegate()
See Also: setDelegate
delete
public Object delete()
null
to force reloading of the web page.
See Also: deleteObjectAtIndex
deleteObjectAtIndex
public boolean deleteObjectAtIndex(int index)
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()
true
if successful and false
if not.
See Also: delete, deleteObjectAtIndex
detailKey
public String detailKey()
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.
See Also: hasDetailDataSource, masterObject, setDetailKey
displayBatchContainingSelectedObject
public Object displayBatchContainingSelectedObject()
null
to force the page to reload.
See Also: displayNextBatch, displayPreviousBatch, setCurrentBatchIndex
displayedObjects
public NSArray displayedObjects()
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()
null
to force the page to reload.
See Also: batchCount, currentBatchIndex, displayBatchContainingSelectedObject, displayPreviousBatch
displayPreviousBatch
public Object displayPreviousBatch()
null
to force the page to reload.
See Also: batchCount, currentBatchIndex, displayBatchContainingSelectedObject, displayNextBatch
dispose
public void dispose()
editingContextPresentErrorMessage
public void editingContextPresentErrorMessage( com.webobjects.eocontrol.EOEditingContext editingContext, String message)
encodeWithCoder
public void encodeWithCoder(NSCoder coder)
encodeWithKeyValueArchiver
public void encodeWithKeyValueArchiver( com.webobjects.eocontrol.EOKeyValueArchiver archiver)
endEditing
public boolean endEditing()
true
to an endEditing message, returns true
. Otherwise returns false
.
fetch
public Object fetch()
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()
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()
hasDetailDataSource
public boolean hasDetailDataSource()
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)
handleTakeValueForUnboundKey
public void handleTakeValueForUnboundKey(Object value, String key)
hasMultipleBatches
public boolean hasMultipleBatches()
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()
See Also: indexOfLastDisplayedObject
indexOfLastDisplayedObject
public int indexOfLastDisplayedObject()
See Also: indexOfFirstDisplayedObject
initWithCoder
public Object initWithCoder(NSCoder coder)
this
.
inQueryMode
public boolean inQueryMode()
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()
This method returns null
to force the page to reload.
insertedObjectDefaultValues
public NSDictionary insertedObjectDefaultValues()
insertNewObjectAtIndex
public Object insertNewObjectAtIndex(int index)
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)
Raises an exception if index is out of bounds.
See Also: insertNewObjectAtIndex, insert
localKeys
public NSArray localKeys()
masterObject
public Object masterObject()
See Also: detailKey, hasDetailDataSource, setMasterObject
numberOfObjectsPerBatch
public int numberOfObjectsPerBatch()
objectsChangedInEditingContext
public void objectsChangedInEditingContext(NSNotification notification)
objectsInvalidatedInEditingContext
public void objectsInvalidatedInEditingContext(NSNotification notification)
qualifier
public com.webobjects.eocontrol.EOQualifier qualifier()
See Also: displayedObjects, setQualifier, updateDisplayedObjects
qualifierFromQueryValues
public com.webobjects.eocontrol.EOQualifier qualifierFromQueryValues()
See Also: qualifyDataSource, qualifyDisplayGroup
qualifyDataSource
public void qualifyDataSource()
See Also: queryMatch, queryMax,, queryMin, queryOperator
qualifyDisplayGroup
public void qualifyDisplayGroup()
See Also: qualifyDataSource, queryMatch, queryMax, - queryMin, queryOperator
queryBindings
public NSMutableDictionary queryBindings()
queryMatch
public NSMutableDictionary queryMatch()
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.
See Also: allQualifierOperators, qualifyDataSource, qualifyDisplayGroup, relationalQualifierOperators
queryMax
public NSMutableDictionary queryMax()
See Also: qualifyDataSource, qualifyDisplayGroup, queryOperator
queryMin
public NSMutableDictionary queryMin()
See Also: qualifyDataSource, qualifyDisplayGroup, queryOperator
queryOperator
public NSMutableDictionary queryOperator()
See Also: qualifierFromQueryValues, queryMax, queryMin, relationalQualifierOperators
redisplay
public void redisplay()
relationalQualifierOperators
public NSArray relationalQualifierOperators()
See Also: allQualifierOperators, queryOperator, stringQualifierOperators
selectedObject
public Object selectedObject()
null
if there's no such object.
See Also: displayedObjects, selectionIndexes, selectedObjects
selectedObjects
public NSArray selectedObjects()
See Also: displayedObjects, selectionIndexes, selectedObject
selectionIndexes
public NSArray selectionIndexes()
See Also: selectedObject, selectedObjects, setSelectionIndexes
selectNext
public Object selectNext()
- 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)
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)
true
if successful and false
otherwise.
See Also: setSelectionIndexes, selectObjectsIdenticalToSelectFirstOnNoMatch
selectObjectsIdenticalToSelectFirstOnNoMatch
public boolean selectObjectsIdenticalToSelectFirstOnNoMatch( NSArray objects, boolean flag)
true
if successful and false
otherwise. If no objects in the displayed objects array match objects and flag is true
, attempts to select the first object in the displayed objects array.
See Also: setSelectionIndexes, selectObjectsIdenticalTo
selectPrevious
public Object selectPrevious()
- 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()
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.
See Also: displayedObjects, fetch, setSelectsFirstObjectAfterFetch
setCurrentBatchIndex
public void setCurrentBatchIndex(int anInt)
If anInt is greater than the number of batches, this method displays the first batch.
See Also: batchCount, currentBatchIndex, displayBatchContainingSelectedObject, displayNextBatch, displayPreviousBatch, numberOfObjectsPerBatch
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)
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".
See Also: defaultStringMatchFormat, setDefaultStringMatchOperator, setGlobalDefaultStringMatchFormat
setDefaultStringMatchOperator
public void setDefaultStringMatchOperator(String operator)
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.
See Also: allQualifierOperators, defaultStringMatchOperator, relationalQualifierOperators, setDefaultStringMatchFormat, setGlobalDefaultStringMatchOperator
setDelegate
public void setDelegate(Object anObject)
See Also: delegate, WODisplayGroup.Delegate
setDetailKey
public void setDetailKey(String detailKey)
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.
See Also: hasDetailDataSource, detailKey, setMasterObject
setFetchesOnLoad
public void setFetchesOnLoad(boolean flag)
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)
See Also: inQueryMode
setInsertedObjectDefaultValues
public void setInsertedObjectDefaultValues(NSDictionary defaultValues)
See Also: insertedObjectDefaultValues
setLocalKeys
public void setLocalKeys(NSArray newKeySet)
setMasterObject
public void setMasterObject(Object masterObject)
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)
See Also: batchCount, displayNextBatch, displayPreviousBatch, numberOfObjectsPerBatch
setObjectArray
public void setObjectArray(NSArray objects)
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.
See Also: allObjects, displayedObjects, fetch, selectsFirstObjectAfterFetch
setQualifier
public void setQualifier(com.webobjects.eocontrol.EOQualifier aQualifier)
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)
See Also: displayedObjects, selectionIndexes, selectedObjects
setSelectedObjects
public void setSelectedObjects(NSArray objects)
See Also: displayedObjects, selectionIndexes, selectedObject
setSelectionIndexes
public boolean setSelectionIndexes(NSArray selection)
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)
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.
See Also: displayedObjects, fetch, selectsFirstObjectAfterFetch
setSortOrderings
public void setSortOrderings(NSArray keySortOrderArray)
If the receiver's delegate responds to displayGroupDisplayArrayForObjects, that method is used instead of the sort orderings to order the objects.
See Also: displayedObjects, sortOrderings, updateDisplayedObjects
setValidatesChangesImmediately
public void setValidatesChangesImmediately(boolean flag)
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()
See Also: setSortOrderings
stringQualifierOperators
public NSArray stringQualifierOperators()
See Also: allQualifierOperators, relationalQualifierOperators
takeValueForKey
public void takeValueForKey(Object value, String key)
toString
public String toString()
unableToSetNullForKey
public void unableToSetNullForKey(String key)
undoManager
public NSUndoManager undoManager()
updateDisplayedObjects
public void updateDisplayedObjects()
See Also: redisplay, allObjects, displayedObjects, qualifier, selectedObjects, sortOrderings
validatesChangesImmediately
public boolean validatesChangesImmediately()
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.
See Also: setValidatesChangesImmediately, globalDefaultForValidatesChangesImmediately
valueForKey
public Object valueForKey(String key)
willChange
public void willChange()
© 2001 Apple Computer, Inc. (Last Published April 15, 2001)