NSUndoManager Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in iOS 3.0 and later. |
| Companion guide | |
| Declared in | NSUndoManager.h |
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. 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. UIKit implements undo and redo in its text view object and makes it easy to implement it in objects along the responder chain (see UIResponder).
Tasks
Registering Undo Operations
Checking Undo Ability
Performing Undo and Redo
Limiting the Undo Stack
Creating Undo Groups
Enabling and Disabling Undo
Checking Whether Undo or Redo Is Being Performed
Clearing Undo Operations
Managing the Action Name
Getting and Localizing the Menu Item Title
-
– redoMenuItemTitle -
– undoMenuItemTitle -
– redoMenuTitleForUndoActionName: -
– undoMenuTitleForUndoActionName:
Working with Run Loops
Discardable Undo and Redo Actions
Instance Methods
beginUndoGrouping
Marks the beginning of an undo group.
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 NSUndoManagerCheckpointNotification unless a top-level undo is in progress. It posts an NSUndoManagerDidOpenUndoGroupNotification if a new group was successfully created.
Availability
- Available in iOS 3.0 and later.
Declared In
NSUndoManager.hcanRedo
Returns a Boolean value that indicates whether the receiver has any actions to redo.
Discussion
Because any undo operation registered clears the redo stack, this method posts an NSUndoManagerCheckpointNotification to allow clients to apply their pending operations before testing the redo stack.
Availability
- Available in iOS 3.0 and later.
Declared In
NSUndoManager.hcanUndo
Returns a Boolean value that indicates whether the receiver has any actions to undo.
Discussion
The return value does not mean you can safely invoke undo or undoNestedGroup—you may have to close open undo groups first.
Availability
- Available in iOS 3.0 and later.
Declared In
NSUndoManager.hdisableUndoRegistration
Disables the recording of undo operations, whether by registerUndoWithTarget:selector:object: or by invocation-based undo.
Discussion
This method can be invoked multiple times by multiple clients. The enableUndoRegistration method must be invoked an equal number of times to re-enable undo registration.
Availability
- Available in iOS 3.0 and later.
Declared In
NSUndoManager.henableUndoRegistration
Enables the recording of undo operations.
Discussion
Because undo registration is enabled by default, it is often used to balance a prior disableUndoRegistration message. Undo registration isn’t actually re-enabled until an enable message balances the last disable message in effect. Raises an NSInternalInconsistencyException if invoked while no disableUndoRegistration message is in effect.
Availability
- Available in iOS 3.0 and later.
Declared In
NSUndoManager.hendUndoGrouping
Marks the end of an undo group.
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. Raises an NSInternalInconsistencyException if there’s no beginUndoGrouping message in effect.
This method posts an NSUndoManagerCheckpointNotification and an NSUndoManagerDidCloseUndoGroupNotification just before the group is closed.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hgroupingLevel
Returns the number of nested undo groups (or redo groups, if Redo was invoked last) in the current event loop.
Return Value
An integer indicating the number of nested groups. If 0 is returned, there is no open undo or redo group.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hgroupsByEvent
Returns a Boolean value that indicates whether the receiver automatically creates undo groups around each pass of the run loop.
Return Value
YES if the receiver automatically creates undo groups around each pass of the run loop, otherwise NO.
Discussion
The default is YES.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hisRedoing
Returns a Boolean value that indicates whether the receiver is in the process of performing its redo method.
Return Value
YES if the method is being performed, otherwise NO.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hisUndoing
Returns a Boolean value that indicates whether the receiver is in the process of performing its undo or undoNestedGroup method.
Return Value
YES if the method is being performed, otherwise NO.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hisUndoRegistrationEnabled
Returns a Boolean value that indicates whether the recording of undo operations is enabled.
Return Value
YES if registration is enabled; otherwise, NO.
Discussion
Undo registration is enabled by default.
Availability
- Available in iOS 3.0 and later.
Declared In
NSUndoManager.hlevelsOfUndo
Returns the maximum number of top-level undo groups the receiver holds.
Return Value
An integer specifying the number of undo groups. A limit of 0 indicates no limit, so old undo groups are never dropped.
Discussion
When ending an undo group results in the number of groups exceeding this limit, the oldest groups are dropped from the stack. The default is 0.
Availability
- Available in iOS 3.0 and later.
Declared In
NSUndoManager.hprepareWithInvocationTarget:
Prepares the receiver for invocation-based undo with the given target as the subject of the next undo operation and returns self.
Parameters
- target
The target of the undo operation.
Return Value
self.
Discussion
See “Registering Undo Operations” for more information.
Availability
- Available in iOS 3.0 and later.
Declared In
NSUndoManager.hredo
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.
Discussion
Raises an NSInternalInconsistencyException if the method is invoked during an undo operation.
This method posts an NSUndoManagerCheckpointNotification and NSUndoManagerWillRedoChangeNotification before it performs the redo operation, and it posts the NSUndoManagerDidRedoChangeNotification after it performs the redo operation.
Availability
- Available in iOS 3.0 and later.
Declared In
NSUndoManager.hredoActionIsDiscardable
Returns whether the next redo action is discardable.
Return Value
YES if the action is discardable; NO otherwise.
Discussion
Specifies that the latest redo action may be safely discarded when a document can not be saved for any reason. These are typically actions that don’t effect persistent state.
An example might be an redo action that changes the viewable area of a document.
Availability
- Available in iOS 5.0 and later.
Declared In
NSUndoManager.hredoActionName
Returns the name identifying the redo action.
Return Value
The redo action name. Returns an empty string (@"") if no action name has been assigned or if there is nothing to redo.
Discussion
For example, if the menu title is “Redo Delete,” the string returned is “Delete.”
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hredoMenuItemTitle
Returns the complete title of the Redo menu command, for example, “Redo Paste.”
Return Value
The menu item title.
Discussion
Returns “Redo” if no action name has been assigned or nil if there is nothing to redo.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hredoMenuTitleForUndoActionName:
Returns the complete, localized title of the Redo menu command for the action identified by the given name.
Parameters
- actionName
The name of the undo action.
Return Value
The localized title of the redo menu item.
Discussion
Override this method if you want to customize the localization behavior. This method is invoked by redoMenuItemTitle.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hregisterUndoWithTarget:selector:object:
Records a single undo operation for a given target, so that when an undo is performed it is sent a specified selector with a given object as the sole argument.
Parameters
- target
The target of the undo operation.
- aSelector
The selector for the undo operation.
- anObject
The argument sent with the selector.
Discussion
Also clears the redo stack. Does not retain target, but does retain anObject. See “Registering Undo Operations” for more information.
Raises an NSInternalInconsistencyException 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.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hremoveAllActions
Clears the undo and redo stacks and re-enables the receiver.
Availability
- Available in iOS 3.0 and later.
Declared In
NSUndoManager.hremoveAllActionsWithTarget:
Clears the undo and redo stacks of all operations involving the specified target as the recipient of the undo message.
Parameters
- target
The recipient of the undo messages to be removed.
Discussion
Doesn’t re-enable the receiver if it’s disabled. An object that shares an NSUndoManager with other clients should invoke this message in its implementation of dealloc.
Availability
- Available in iOS 3.0 and later.
Declared In
NSUndoManager.hrunLoopModes
Returns the modes governing the types of input handled during a cycle of the run loop.
Return Value
An array of string constants specifying the current run-loop modes.
Discussion
By default, the sole run-loop mode is NSDefaultRunLoopMode (which excludes data from NSConnection objects).
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hsetActionIsDiscardable:
Sets whether the next undo or redo action is discardable.
Parameters
- discardable
Specifies if the action is discardable.
YESif the next undo or redo action can be discarded;NOotherwise.
Discussion
Specifies that the latest undo action may be safely discarded when a document can not be saved for any reason.
An example might be an undo action that changes the viewable area of a document.
To find out if an undo group contains only discardable actions, look for the NSUndoManagerGroupIsDiscardableKey in the userInfo dictionary of the NSUndoManagerWillCloseUndoGroupNotification.
Availability
- Available in iOS 5.0 and later.
Declared In
NSUndoManager.hsetActionName:
Sets the name of the action associated with the Undo or Redo command.
Parameters
- actionName
The name of the action.
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 nil.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hsetGroupsByEvent:
Sets a Boolean value that specifies whether the receiver automatically groups undo operations during the run loop.
Parameters
Discussion
The default is YES. If you turn automatic grouping off, you must close groups explicitly before invoking either undo or undoNestedGroup.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hsetLevelsOfUndo:
Sets the maximum number of top-level undo groups the receiver holds.
Parameters
- anInt
The maximum number of undo groups. A limit of
0indicates no limit, so that old undo groups are never dropped.
Discussion
When ending an undo group results in the number of groups exceeding this limit, the oldest groups are dropped from the stack. The default is 0.
If invoked with a limit below the prior limit, old undo groups are immediately dropped.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hsetRunLoopModes:
Sets the modes that determine the types of input handled during a cycle of the run loop.
Parameters
- modes
An array of string constants specifying the run-loop modes to set.
Discussion
By default, the sole run-loop mode is NSDefaultRunLoopMode (which excludes data from NSConnection objects). With this method, you could limit the input to data received during a mouse-tracking session by setting the mode to NSEventTrackingRunLoopMode, or you could limit it to data received from a modal panel with NSModalPanelRunLoopMode.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hundo
Closes the top-level undo group if necessary and invokes undoNestedGroup.
Discussion
This method also invokes endUndoGrouping if the nesting level is 1. Raises an NSInternalInconsistencyException if more than one undo group is open (that is, if the last group isn’t at the top level).
This method posts an NSUndoManagerCheckpointNotification.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hundoActionIsDiscardable
Returns whether the next undo action is discardable.
Return Value
YES if the action is discardable; NO otherwise.
Discussion
Specifies that the latest undo action may be safely discarded when a document can not be saved for any reason. These are typically actions that don’t effect persistent state.
An example might be an undo action that changes the viewable area of a document.
Availability
- Available in iOS 5.0 and later.
Declared In
NSUndoManager.hundoActionName
Returns the name identifying the undo action.
Return Value
The undo action name. Returns an empty string (@"") if no action name has been assigned or if there is nothing to undo.
Discussion
For example, if the menu title is “Undo Delete,” the string returned is “Delete.”
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hundoMenuItemTitle
Returns the complete title of the Undo menu command, for example, “Undo Paste.”
Return Value
The menu item title.
Discussion
Returns “Undo” if no action name has been assigned or nil if there is nothing to undo.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hundoMenuTitleForUndoActionName:
Returns the complete, localized title of the Undo menu command for the action identified by the given name.
Parameters
- actionName
The name of the undo action.
Return Value
The localized title of the undo menu item.
Discussion
Override this method if you want to customize the localization behavior. This method is invoked by undoMenuItemTitle.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hundoNestedGroup
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.
Discussion
Raises an NSInternalInconsistencyException if any undo operations have been registered since the last enableUndoRegistration message.
This method posts an NSUndoManagerCheckpointNotification and NSUndoManagerWillUndoChangeNotification before it performs the undo operation, and it posts an NSUndoManagerDidUndoChangeNotification after it performs the undo operation.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSUndoManager.hConstants
NSUndoCloseGroupingRunLoopOrdering
NSUndoManager provides this constant as a convenience; you can use it to compare to values returned by some NSUndoManager methods.
enum {
NSUndoCloseGroupingRunLoopOrdering = 350000
};
Constants
NSUndoCloseGroupingRunLoopOrderingUsed with
NSRunLoop'sperformSelector:target:argument:order:modes:.Available in iOS 3.0 and later.
Declared in
NSUndoManager.h.
Declared In
NSUndoManager.hUndo Group is Discardable Key
This constant is used in the userInfo dictionary of the NSUndoManagerWillCloseUndoGroupNotification it the undo group as a whole is discardable.
NSString * const NSUndoManagerGroupIsDiscardableKey;
Constants
Notifications
NSUndoManagerCheckpointNotification
NSUndoManager object 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 object. This notification does not contain a userInfo dictionary.Availability
- Available in iOS 3.0 and later.
Declared In
NSUndoManager.hNSUndoManagerDidOpenUndoGroupNotification
NSUndoManager object opens an undo group, which occurs in the implementation of the beginUndoGrouping method. The notification object is the NSUndoManager object. This notification does not contain a userInfo dictionary.Availability
- Available in iOS 3.0 and later.
Declared In
NSUndoManager.hNSUndoManagerDidRedoChangeNotification
NSUndoManager object performs a redo operation (redo). The notification object is the NSUndoManager object. This notification does not contain a userInfo dictionary.Availability
- Available in iOS 3.0 and later.
Declared In
NSUndoManager.hNSUndoManagerDidUndoChangeNotification
NSUndoManager object performs an undo operation. If you invoke undo or undoNestedGroup, this notification is posted. The notification object is the NSUndoManager object. This notification does not contain a userInfo dictionary.Availability
- Available in iOS 3.0 and later.
Declared In
NSUndoManager.hNSUndoManagerWillCloseUndoGroupNotification
NSUndoManager object closes an undo group, which occurs in the implementation of the endUndoGrouping method. The notification object is the NSUndoManager object. Prior to OS X v10.7 this notification did not contain a userInfo dictionary. In OS X v10.7 and later the userInfo dictionary may contain the NSUndoManagerWillCloseUndoGroupNotification key, with a NSNumber boolean value of YES, if the undo group as a whole is discardable.
Availability
- Available in iOS 3.0 and later.
Declared In
NSUndoManager.hNSUndoManagerDidCloseUndoGroupNotification
NSUndoManager object closes an undo group, which occurs in the implementation of the endUndoGrouping method. The notification object is the NSUndoManager object. This notification does not contain a userInfo dictionary.Availability
- Available in iOS 5.0 and later.
Declared In
NSUndoManager.hNSUndoManagerWillRedoChangeNotification
NSUndoManager object performs a redo operation (redo). The notification object is the NSUndoManager object. This notification does not contain a userInfo dictionary.Availability
- Available in iOS 3.0 and later.
Declared In
NSUndoManager.hNSUndoManagerWillUndoChangeNotification
NSUndoManager object performs an undo operation. If you invoke undo or undoNestedGroup, this notification is posted. The notification object is the NSUndoManager object. This notification does not contain a userInfo dictionary.Availability
- Available in iOS 3.0 and later.
Declared In
NSUndoManager.h© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-06-11)