EODocumentController
- Inherits from:
- EOEntityController : EOComponentController : EOController
- Implements:
- EODocument
- EOEditable
- EOAssociationConnector (Inherited from EOEntityController)
- EOComponentController.EndEditing (Inherited from EOEntityController)
- EOObserving (Inherited from EOEntityController)
- EOObjectDisplay (Inherited from EOEntityController)
- NSInlineObservable (Inherited from EOController)
- NSDisposable (Inherited from EOController)
- EOKeyValueCodingAdditions (Inherited from EOController)
- EOAction.Enabling (Inherited from EOController)
- EOKeyValueCoding (Inherited from EOKeyValueCodingAdditions)
- NSKeyValueCoding (Inherited from EOKeyValueCoding)
- Package:
- com.apple.client.eoapplication
Class Description
The EODocumentController class provides behavior for displaying and editing enterprise objects in a user interface. EODocumentController's API is mostly specified by the interfaces EODocument and EOEditable. Additionally, much of the way that EODocumentController works is set up by its superclass, EOEntityController. Since EOEntityControllers use EOEditingContexts and EODisplayGroups to manage and display a set of enterprise objects; EODocumentControllers use them as well. However, in addition to displaying enterprise objects, document controllers can also edit their objects. You can insert, update, and delete enterprise objects; undo and redo unsaved changes; and save and revert.
EODocumentController provides several methods that interact with a user. For example, the methods revert and saveIfUserConfirms open dialogs to confirm that a user wants to revert or save before performing the action. Also, many of the methods open dialogs when an error occurs, telling the user what happened.
Root Document Controller Responsibilities
EODocumentController defines the concept of a root document controller. A document controller is the root if none of its ancestors are EODocuments. A root document controller usually provides the editing context for all its descendent document controllers-they typically don't have their own. Consequently, the root document controller has responsibilities that non-root document controllers don't have. For example, only the root document controller provides save and revert behavior.
Rule System and XML Description
The following tables identify the controllerType,
XML tag, and XML attributes used by the rule system and EOXMLUnarchiver
to generate a controller hierarchy. For more information, see the
section "Rule System and XML Description" in the package introduction.
| Default Rule System Controller Type |
entityController |
| XML Tag |
DOCUMENTCONTROLLER |
| XML Attribute | Value | Description |
editability |
string | One of "Never", "Always", or "IfSupercontroller". See the EOEditable interface specification for more information on these settings. |
Interfaces Implemented
EODocument
- isDocumentForGlobalID
- isEdited
- save
- saveIfUserConfirms
- setEdited
EOEditable
- editability
- isEditable
- setEditability
- supercontrollerEditabilityDidChange
- takeResposibilityForEditabilityOfAssociation
EOAssociationConnector (Inherited from EOEntityController)
EOComponentController.EndEditing (Inherited from EOEntityController)
EOObserving (Inherited from EOEntityController)
EOObjectDisplay (Inherited from EOEntityController)
NSInlineObservable (Inherited from EOController)
NSDisposable (Inherited from EOController)
- dispose
EOKeyValueCodingAdditions (Inherited from EOController)
EOAction.Enabling (Inherited from EOController)
- canPerformActionNamed
EOKeyValueCoding (Inherited from EOKeyValueCodingAdditions)
NSKeyValueCoding (Inherited from EOKeyValueCoding)
Method Types
- Constructors
- EODocumentController
- Inserting, updating, and deleting
- insertObject
- deleteSelectedObjects
- wasEdited
- Saving
- canSave
- saveChanges
- saveAndMakeInvisible
- saveIfUserConfirms
- saveIfUserConfirmsAndMakeInvisible
- saveIfUserConfirmsAndMakeInvisible
- saveFailed
- Reverting
- canRevert
- revert
- revertAndMakeInvisible
- revertChanges
- revertFailed
- Undoing and Redoing
- canUndo
- undo
- canRedo
- redo
- Determining the root document controller
- isRootDocumentController
- Methods inherited from EOEntityController
- handleEditingContextNotification
- Methods inherited from EOController
- connectionWasEstablished
- defaultActions
- prepareForNewTask
- Methods inherited from Object
- toString
Constructors
EODocumentController
public EODocumentController()
public EODocumentController(EOXMLUnarchiver unarchiver)
Creates a new document controller. For information on how these constructors are used and on what they do, see the method description for the EOController constructors in the EOController class specification.
Instance Methods
canPerformActionNamed
public boolean canPerformActionNamed(String actionName)
Conformance to EOAction.Enabling. EODocumentController's implementation uses the methods canRedo, canRevert, canSave, and canUndo to determine the enabling state of the corresponding actions.
See Also: canPerformActionNamed (EOAction.Enabling)
canRedo
protected boolean canRedo()
Returns true if
the receiver can redo, false otherwise. A
document controller can redo as long as its editing context's
undo manager can redo and as long as it (or one of its subcontrollers)
is editable.
canRevert
protected boolean canRevert()
Returns true if
the receiver can revert, false otherwise. A
document controller can revert only if it's been edited and only
if it's the root document controller.
canSave
protected boolean canSave()
Returns true if
the receiver can save, false otherwise. A
document controller can save only if it's been edited and only
if it's the root document controller.
canUndo
protected boolean canUndo()
Returns true if
the receiver can undo, false otherwise. A
document controller can undo as long as its editing context's
undo manager can undo and as long as it (or one of its subcontrollers)
is editable.
connectionWasEstablished
protected void connectionWasEstablished()
See the method description for connectionWasEstablished in the EOController class specification. EODocumentController's implementation additionally updates its editability.
defaultActions
protected NSArray defaultActions()
Adds actions for handling editing to the default actions defined by the superclass, EOEntityController. More specifically, it adds save and revert actions. However, note that defaultActions only adds save and revert if the receiver is the root document controller, if it's editable, and if it's not modal.
deleteSelectedObjects
public void deleteSelectedObjects()
Deletes the
objects selected in the receiver's display group and then sets
the receiver's edited state to true.
dispose
public void dispose()
Conformance to NSDisposable. See the method description of dispose in the interface specification for NSDisposable.
editability
public int editability()
Conformance to EOEditable. See the method description of editability in the interface specification for EOEditable.
handleEditingContextNotification
public void handleEditingContextNotification(NSNotification notification)
See the method description for handleEditingContextNotification in the EOEntityController class specification. EODocumentController's implementation additionally updates its edited state if the receiver is a root document controller.
insertObject
public void insertObject()
Creates a new enterprise object,
inserts it into the receiver's display group, and sets the receiver's
edited status to true.
isDocumentForGlobalID
public boolean isDocumentForGlobalID(
com.apple.client.eocontrol.EOGlobalID globalID,
String entityName)
Conformance to EODocument. See the method description of isDocumentForGlobalID in the interface specification for EODocument.
isEditable
public boolean isEditable()
Conformance to EOEditable. See the method description of isEditable in the interface specification for EOEditable.
isEdited
public boolean isEdited()
Conformance to EODocument. See the method description of isEdited in the interface specification for EODocument.
isRootDocumentController
protected boolean isRootDocumentController()
Returns true if
none of the supercontrollers are EODocuments, false otherwise.
prepareForNewTask
public void prepareForNewTask(boolean flag)
See the method description
for prepareForNewTask in
the EOController class specification. EODocumentController's
implementation additionally sets its edited state to false.
redo
public void redo()
Tells the receiver's editing context to redo.
revert
public boolean revert()
Reverts the receiver's unsaved
changes upon user confirmation. If the receiver
has been edited, opens a dialog to verify that the user wants to
revert. Upon confirmation, invokes revertChanges requesting an error
dialog upon failure. Returns true on
success, false upon failure
or if the user cancels the revert.
revertAndMakeInvisible
public boolean revertAndMakeInvisible()
Reverts the receiver's unsaved
changes and makes the receiver invisible. Reverts
by invoking revertChanges, requesting an error
dialog upon failure Returns true if
changes are successfully reverted, false if
the receiver can't be reverted or if the revert fails.
revertChanges
public boolean revertChanges(boolean showErrorDialog)
Tells the receiver's editing
context to revert, refetches if necessary, and sets the receiver's
editing state to false. If
the revert fails, catches the exception and, if showErrorDialog is
true, invokes revertFailed to show the
reason for failure. Returns true if
the revert succeeds, false otherwise.
revertFailed
protected void revertFailed(
Exception exception,
boolean showErrorDialog)
If showErrorDialog is true,
brings the receiver's user interface to the front and opens a
dialog displaying exception's class
name and exception message. Invoked from revertChanges.
save
public boolean save()
Saves the receiver's changes. Saves
by invoking saveChanges, requesting an
error dialog upon failure Returns true if
changes are successfully saved, false if
the receiver can't save or if the save fails.
saveAndMakeInvisible
public boolean saveAndMakeInvisible()
Saves the receiver's changes
and makes the receiver invisible. Saves by invoking saveChanges, requesting an error
dialog upon failure Returns true if
changes are successfully reverted, false if
the receiver can't be reverted or if the revert fails.
saveChanges
public boolean saveChanges(
boolean showErrorDialog,
String saveOperationTitle)
Tells the receiver's editing
context to save changes and sets the receiver's editing state
to false. If
the save fails, catches the exception and, if showErrorDialog is
true, invokes saveFailed to show the reason for
failure. Returns true if
the save succeeds, false otherwise.
saveFailed
protected void saveFailed(
Exception showErrorDialog,
boolean showErrorDialog,
String saveOperationTitle)
If showErrorDialog is true,
brings the receiver's user interface to the front and opens a
dialog displaying exception's class
name and exception message. Invoked from saveChanges.
saveIfUserConfirms
public boolean saveIfUserConfirms(
String operationTitle,
String message)
public boolean saveIfUserConfirms()
Saves the receiver's unsaved
changes upon user confirmation. If the receiver
has been edited, opens a dialog to verify that the user wants to
save. If operationTitle and message are
provided, they are used as the dialog title and message; otherwise,
"Save" and "Save Changes?" are used. Upon confirmation, invokes saveChanges requesting
an error dialog upon failure. Returns true on
success, false upon failure
or if the user cancels the save.
saveIfUserConfirmsAndMakeInvisible
public boolean saveIfUserConfirmsAndMakeInvisible(
String operationTitle,
String message)
public boolean saveIfUserConfirmsAndMakeInvisible()
Saves the receiver's unsaved
changes upon user confirmation and makes the receiver invisible. Saves by
invoking saveIfUserConfirms, requesting
an error dialog upon failure. The arguments operationTitle and message are
used as the title and message of the confirmation panel. "Save"
and "Save changes?" are substituted for null.
If the no-argument form of this method is invoked, then the title
of the confirmation dialog is "Close" and the dialog has no
message. Returns true if
changes are successfully saved, false if
the receiver can't be saved or if the save fails.
setEditability
public void setEditability(int editability)
Conformance to EOEditable. See the method description of setEditability in the interface specification for EOEditable.
setEdited
public void setEdited(boolean flag)
Conformance to EODocument. See the method description of setEdited in the interface specification for EODocument.
supercontrollerEditabilityDidChange
public void supercontrollerEditabilityDidChange()
Conformance to EOEditable. See the method description of supercontrollerEditabilityDidChange in the interface specification for EOEditable. EODocumentController's implementation updates the receiver's editability and resets its actions.
takeResposibilityForEditabilityOfAssociation
public void takeResposibilityForEditabilityOfAssociation(com.apple.client.eointerface.EOAssociation association)
Conformance to EOEditable. See the method description of takeResposibilityForEditabilityOfAssociation in the interface specification for EOEditable.
toString
public String toString()
Returns the receiver as a string, including the receiver's editability and whether or not it has unsaved edits.
undo
public void undo()
Tells the receiver's editing context to redo.
wasEdited
protected void wasEdited()
Invoked from setEdited to notify the receiver that edited status has changed, giving the receiver the opportunity to respond.
DRAFT