Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
NSUndoManager
| Inherits from | |
| Package | com.apple.cocoa.foundation |
| Companion guide |
Overview
NSUndoManager is a general-purpose recorder of operations for undo and redo. You register an undo operation by specifying the object that’s changing (or the owner of that object), along with a method to invoke to revert its state, and the arguments for that method. NSUndoManager groups all operations within a single cycle of the run loop, so that performing an undo reverts all changes that occurred during the loop. Also, when performing undo an NSUndoManager saves the operations reverted so that you can redo the undos.
NSUndoManager is implemented as a class of the Foundation framework because executables other than applications might want to revert changes to their states. For example, you might have an interactive command-line tool with undo and redo commands, or there could be distributed object implementations that can revert operations “over the wire.” However, users typically see undo and redo as application features. The Application Kit implements undo and redo in its NSTextView object and makes it easy to implement it in objects along the responder chain.
Tasks
Constructors
Registering Undo Operations
Checking Undo Ability
Performing Undo and Redo
Limiting the Undo Stack
Creating Undo Groups
-
beginUndoGrouping
-
endUndoGrouping
-
enableUndoRegistration
-
groupsByEvent
-
setGroupsByEvent
-
groupingLevel
Disabling Undo
Checking Whether Undo or Redo Is Being Performed
Clearing Undo Operations
Setting and Getting the Action Name
Getting and Localizing Menu Item Title
Working with Run Loops
Instance Methods
beginUndoGrouping
Marks the beginning of an undo group.
public void beginUndoGrouping()
Discussion
All individual undo operations before a subsequent endUndoGrouping message are grouped together and reversed by a later undo message. By default undo groups are begun automatically at the start of the event loop, but you can begin your own undo groups with this method, and nest them within other groups.
This method posts an CheckpointNotification unless a top-level undo is in progress. It posts an DidOpenUndoGroupNotification if a new group was successfully created.
canRedo
Returns true if the receiver has any actions to redo, false if it doesn’t.
public boolean canRedo()
Discussion
Because any undo operation registered clears the redo stack, this method posts an CheckpointNotification to allow clients to apply their pending operations before testing the redo stack.
See Also
canUndo
Returns true if the receiver has any actions to undo, false if it doesn’t.
public boolean canUndo()
Discussion
This fact does not mean you can safely invoke undo or undoNestedGroup—you may have to close open undo groups first.
See Also
disableUndoRegistration
Disables the recording of undo operations by registerUndoWithTarget.
public void disableUndoRegistration()
Discussion
This method can be invoked multiple times by multiple clients. enableUndoRegistration must be invoked an equal number of times to reenable undo registration.
enableUndoRegistration
Enables the recording of undo operations.
public void enableUndoRegistration()
Discussion
Because undo registration is enabled by default, it is often used to balance a prior disableUndoRegistration message. Undo registration isn’t actually reenabled until an enable message balances the last disable message in effect. Throws an InternalInconsistencyException if invoked while no disableUndoRegistration message is in effect.
endUndoGrouping
Marks the end of an undo group.
public void endUndoGrouping()
Discussion
All individual undo operations back to the matching beginUndoGrouping message are grouped together and reversed by a later undo or undoNestedGroup message. Undo groups can be nested, thus providing functionality similar to nested transactions. Throws an InternalInconsistencyException if there’s no beginUndoGrouping message in effect.
This method posts an CheckpointNotification and an WillCloseUndoGroupNotification just before the group is closed.
See Also
groupingLevel
Returns the number of nested undo groups (or redo groups, if Redo was last invoked) in the current event loop.
public int groupingLevel()
Discussion
If 0 is returned, there is no open undo or redo group.
See Also
groupsByEvent
Returns true if the receiver automatically creates undo groups around each pass of the run loop, false if it doesn’t.
public boolean groupsByEvent()
Discussion
The default is true.
See Also
isRedoing
Returns true if the receiver is in the process of performing its redo method, false otherwise.
public boolean isRedoing()
See Also
isUndoing
Returns true if the receiver is in the process of performing its undo or undoNestedGroup method, false otherwise.
public boolean isUndoing()
See Also
isUndoRegistrationEnabled
Returns a Boolean value that indicates whether the recording of undo operations is enabled.
public boolean isUndoRegistrationEnabled()
Discussion
Undo registration is enabled by default.
See Also
levelsOfUndo
Returns the maximum number of top-level undo groups the receiver holds.
public int levelsOfUndo()
Discussion
When ending an undo group results in the number of groups exceeding this limit, the oldest groups are dropped from the stack. A limit of 0 indicates no limit, so old undo groups are never dropped. The default is 0.
See Also
redo
Performs the operations in the last group on the redo stack, if there are any, recording them on the undo stack as a single group.
public void redo()
Discussion
Throws an InternalInconsistencyException if the method is invoked during an undo operation.
This method posts an CheckpointNotification and WillRedoChangeNotification before it performs the redo operation, and it posts the DidRedoChangeNotification after it performs the redo operation.
See Also
redoActionName
Returns the name identifying the redo action.
public String redoActionName()
Discussion
For example, if the menu title is “Redo Delete,” the string returned is “Delete.” Returns an empty string if no action name has been assigned or null if there is nothing to redo.
See Also
redoMenuItemTitle
Returns the complete title of the Redo menu command, for example, “Redo Paste.”
public String redoMenuItemTitle()
Discussion
Returns “Redo” if no action name has been assigned or null if there is nothing to redo.
See Also
redoMenuTitleForUndoActionName
Returns the complete, localized title of the Redo menu command for the action identified by actionName.
public String redoMenuTitleForUndoActionName(String actionName)
Discussion
Override this method if you want to customize the localization behavior. This method is invoked by redoMenuItemTitle.
See Also
registerUndoWithTarget
Records a single undo operation for target, so that when an undo is performed it is sent aSelector with anObject as the sole argument.
public void registerUndoWithTarget(Object target, NSSelector aSelector, Object anObject)
Discussion
Also clears the redo stack. See “Registering Undo Operations” for more information.
Throws an InternalInconsistencyException if invoked when no undo group has been established using beginUndoGrouping. Undo groups are normally set by default, so you should rarely need to begin a top-level undo group explicitly.
See Also
registerUndoWithTargetAndArguments
Records a single undo operation for target, so that when an undo is performed it is sent aSelector with multiple arguments specified in objects.
public void registerUndoWithTargetAndArguments(Object target, NSSelector aSelector, Object[] objects)
See Also
removeAllActions
Clears the undo and redo stacks and reenables the receiver.
public void removeAllActions()
See Also
removeAllActionsWithTarget
Clears the undo and redo stacks of all operations involving target as the recipient of the undo message.
public void removeAllActionsWithTarget(Object target)
Discussion
Doesn’t reenable the receiver if it’s disabled. An object that shares an NSUndoManager with other clients should invoke this message in its implementation of dealloc.
See Also
runLoopModes
Returns the modes governing the types of input handled during a cycle of the run loop.
public NSArray runLoopModes()
Discussion
By default, the sole run-loop mode is NSRunLoop.DefaultRunLoopMode (which excludes data from NSConnections).
See Also
setActionName
Sets the name of the action associated with the Undo or Redo command to actionName.
public void setActionName(String actionName)
Discussion
If actionName is an empty string, the action name currently associated with the menu command is removed. There is no effect if actionName is null.
See Also
setGroupsByEvent
Sets a Boolean value that specifies whether the receiver automatically groups undo operations during the run loop.
public void setGroupsByEvent(boolean flag)
Discussion
If flag is true, the receiver creates undo groups around each pass through the run loop; if flag is false it doesn’t. The default is true.
If you turn automatic grouping off, you must close groups explicitly before invoking either undo or undoNestedGroup.
See Also
setLevelsOfUndo
Sets the maximum number of top-level undo groups the receiver holds to anInt.
public void setLevelsOfUndo(int anInt)
Discussion
When ending an undo group results in the number of groups exceeding this limit, the oldest groups are dropped from the stack. A limit of 0 indicates no limit, so that old undo groups are never dropped. The default is 0.
If invoked with a limit below the prior limit, old undo groups are immediately dropped.
See Also
setRunLoopModes
Sets the modes that determine the types of input handled during a cycle of the run loop.
public void setRunLoopModes(NSArray modes)
Discussion
By default, the sole run-loop mode is NSRunLoop.DefaultRunLoopMode (which excludes data from NSConnections). With this method, you could limit the input to data received during a mouse-tracking session by setting the mode to NSApplication.EventTrackingRunLoopMode, or you could limit it to data received from a modal panel with NSApplication.ModalPanelRunLoopMode.
See Also
undo
Closes the top-level undo group if necessary and invokes undoNestedGroup.
public void undo()
Discussion
It also invokes endUndoGrouping if the nesting level is 1. Throws an InternalInconsistencyException if more than one undo group is open (that is, if the last group isn’t at the top level).
This method posts an CheckpointNotification.
See Also
undoActionName
Returns the name identifying the undo action.
public String undoActionName()
Discussion
For example, if the menu title is “Undo Delete,” the string returned is “Delete.” Returns an empty string if no action name has been assigned or null if there is nothing to undo.
See Also
undoMenuItemTitle
Returns the complete title of the Undo menu command, for example, “Undo Paste.”
public String undoMenuItemTitle()
Discussion
Returns “Undo” if no action name has been assigned or null if there is nothing to undo.
See Also
undoMenuTitleForUndoActionName
Returns the complete, localized title of the Undo menu command for the action identified by actionName.
public String undoMenuTitleForUndoActionName(String actionName)
Discussion
Override this method if you want to customize the localization behavior. This method is invoked by undoMenuItemTitle.
See Also
undoNestedGroup
Performs the undo operations in the last undo group (whether top-level or nested), recording the operations on the redo stack as a single group.
public void undoNestedGroup()
Discussion
Throws an InternalInconsistencyException if any undo operations have been registered since the last enableUndoRegistration message.
This method posts an CheckpointNotification and WillUndoChangeNotification before it performs the undo operation, and it posts an DidUndoChangeNotification after it performs the undo operation.
See Also
Constants
NSUndoManager provides the following constant as a convenience; you can use it to compare to values returned by some NSUndoManager methods:
Constant | Description |
|---|---|
UndoCloseGroupingRunLoopOrdering | Used with NSRunLoop’s |
Notifications
CheckpointNotification
Posted whenever an NSUndoManager opens or closes an undo group (except when it opens a top-level group) and when checking the redo stack in canRedo. The notification object is the NSUndoManager. This notification does not contain a userInfo dictionary.
DidOpenUndoGroupNotification
Posted whenever an NSUndoManager opens an undo group, which occurs in the implementation of the beginUndoGrouping method. The notification object is the NSUndoManager. This notification does not contain a userInfo dictionary.
DidRedoChangeNotification
Posted just after an NSUndoManager performs a redo operation (redo). The notification object is the NSUndoManager. This notification does not contain a userInfo dictionary.
DidUndoChangeNotification
Posted just after an NSUndoManager performs an undo operation. If you invoke undo or undoNestedGroup, this notification is posted. The notification object is the NSUndoManager. This notification does not contain a userInfo dictionary.
WillCloseUndoGroupNotification
Posted before an NSUndoManager closes an undo group, which occurs in the implementation of the endUndoGrouping method. The notification object is the NSUndoManager. This notification does not contain a userInfo dictionary.
WillRedoChangeNotification
Posted just before an NSUndoManager performs a redo operation (redo). The notification object is the NSUndoManager. This notification does not contain a userInfo dictionary.
WillUndoChangeNotification
Posted just before an NSUndoManager performs an undo operation. If you invoke undo or undoNestedGroup, this notification is posted. The notification object is the NSUndoManager. This notification does not contain a userInfo dictionary.
© 1997, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-07-24)