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
Related sample code

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

Working with Run Loops

Discardable Undo and Redo Actions

Instance Methods

beginUndoGrouping

Marks the beginning of an undo group.

- (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 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.h

canRedo

Returns a Boolean value that indicates whether the receiver has any actions to redo.

- (BOOL)canRedo
Return Value

YES if the receiver has any actions to redo, otherwise NO.

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.h

canUndo

Returns a Boolean value that indicates whether the receiver has any actions to undo.

- (BOOL)canUndo
Return Value

YES if the receiver has any actions to undo, otherwise NO.

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.h

disableUndoRegistration

Disables the recording of undo operations, whether by registerUndoWithTarget:selector:object: or by invocation-based undo.

- (void)disableUndoRegistration
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.h

enableUndoRegistration

Enables the recording of undo operations.

- (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 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.h

endUndoGrouping

Marks the end of an undo group.

- (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. 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.
Declared In
NSUndoManager.h

groupingLevel

Returns the number of nested undo groups (or redo groups, if Redo was invoked last) in the current event loop.

- (NSInteger)groupingLevel
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.
Declared In
NSUndoManager.h

groupsByEvent

Returns a Boolean value that indicates whether the receiver automatically creates undo groups around each pass of the run loop.

- (BOOL)groupsByEvent
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.
Declared In
NSUndoManager.h

isRedoing

Returns a Boolean value that indicates whether the receiver is in the process of performing its redo method.

- (BOOL)isRedoing
Return Value

YES if the method is being performed, otherwise NO.

Availability
  • Available in iOS 3.0 and later.
Declared In
NSUndoManager.h

isUndoing

Returns a Boolean value that indicates whether the receiver is in the process of performing its undo or undoNestedGroup method.

- (BOOL)isUndoing
Return Value

YES if the method is being performed, otherwise NO.

Availability
  • Available in iOS 3.0 and later.
Declared In
NSUndoManager.h

isUndoRegistrationEnabled

Returns a Boolean value that indicates whether the recording of undo operations is enabled.

- (BOOL)isUndoRegistrationEnabled
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.h

levelsOfUndo

Returns the maximum number of top-level undo groups the receiver holds.

- (NSUInteger)levelsOfUndo
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.h

prepareWithInvocationTarget:

Prepares the receiver for invocation-based undo with the given target as the subject of the next undo operation and returns self.

- (id)prepareWithInvocationTarget:(id)target
Parameters
target

The target of the undo operation. The undo manager maintains a weak reference to the target.

Return Value

self.

Discussion

See “Registering Undo Operations” for more information.

Availability
  • Available in iOS 3.0 and later.
Declared In
NSUndoManager.h

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.

- (void)redo
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.h

redoActionIsDiscardable

Returns whether the next redo action is discardable.

- (BOOL)redoActionIsDiscardable
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.h

redoActionName

Returns the name identifying the redo action.

- (NSString *)redoActionName
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.
Declared In
NSUndoManager.h

redoMenuItemTitle

Returns the complete title of the Redo menu command, for example, “Redo Paste.”

- (NSString *)redoMenuItemTitle
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.
Declared In
NSUndoManager.h

redoMenuTitleForUndoActionName:

Returns the complete, localized title of the Redo menu command for the action identified by the given name.

- (NSString *)redoMenuTitleForUndoActionName:(NSString *)actionName
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.
Declared In
NSUndoManager.h

registerUndoWithTarget: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.

- (void)registerUndoWithTarget:(id)target selector:(SEL)aSelector object:(id)anObject
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.
Declared In
NSUndoManager.h

removeAllActions

Clears the undo and redo stacks and re-enables the receiver.

- (void)removeAllActions
Availability
  • Available in iOS 3.0 and later.
Declared In
NSUndoManager.h

removeAllActionsWithTarget:

Clears the undo and redo stacks of all operations involving the specified target as the recipient of the undo message.

- (void)removeAllActionsWithTarget:(id)target
Parameters
target

The recipient of the undo messages to be removed.

Discussion

Doesn’t re-enable the receiver if it’s disabled.

Availability
  • Available in iOS 3.0 and later.
Declared In
NSUndoManager.h

runLoopModes

Returns the modes governing the types of input handled during a cycle of the run loop.

- (NSArray *)runLoopModes
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.
Declared In
NSUndoManager.h

setActionIsDiscardable:

Sets whether the next undo or redo action is discardable.

- (void)setActionIsDiscardable:(BOOL)discardable
Parameters
discardable

Specifies if the action is discardable. YES if the next undo or redo action can be discarded; NO otherwise.

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.h

setActionName:

Sets the name of the action associated with the Undo or Redo command.

- (void)setActionName:(NSString *)actionName
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.
Related Sample Code
Declared In
NSUndoManager.h

setGroupsByEvent:

Sets a Boolean value that specifies whether the receiver automatically groups undo operations during the run loop.

- (void)setGroupsByEvent:(BOOL)flag
Parameters
flag

If YES, the receiver creates undo groups around each pass through the run loop; if NO it doesn’t.

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.
Declared In
NSUndoManager.h

setLevelsOfUndo:

Sets the maximum number of top-level undo groups the receiver holds.

- (void)setLevelsOfUndo:(NSUInteger)anInt
Parameters
anInt

The maximum number of undo groups. A limit of 0 indicates 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.
Related Sample Code
Declared In
NSUndoManager.h

setRunLoopModes:

Sets the modes that determine the types of input handled during a cycle of the run loop.

- (void)setRunLoopModes:(NSArray *)modes
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.
Declared In
NSUndoManager.h

undo

Closes the top-level undo group if necessary and invokes undoNestedGroup.

- (void)undo
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.
Declared In
NSUndoManager.h

undoActionIsDiscardable

Returns whether the next undo action is discardable.

- (BOOL)undoActionIsDiscardable
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.h

undoActionName

Returns the name identifying the undo action.

- (NSString *)undoActionName
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.
Declared In
NSUndoManager.h

undoMenuItemTitle

Returns the complete title of the Undo menu command, for example, “Undo Paste.”

- (NSString *)undoMenuItemTitle
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.
Declared In
NSUndoManager.h

undoMenuTitleForUndoActionName:

Returns the complete, localized title of the Undo menu command for the action identified by the given name.

- (NSString *)undoMenuTitleForUndoActionName:(NSString *)actionName
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.
Declared In
NSUndoManager.h

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.

- (void)undoNestedGroup
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.h

Constants

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
NSUndoCloseGroupingRunLoopOrdering

Used with NSRunLoop's performSelector:target:argument:order:modes:.

Available in iOS 3.0 and later.

Declared in NSUndoManager.h.

Declared In
NSUndoManager.h

Undo 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
NSUndoManagerGroupIsDiscardableKey

The key has a corresponding value of YES, wrapped as a Boolean NSNumber object, if the undo group as a whole is discardable.

Notifications

NSUndoManagerCheckpointNotification

Posted whenever an 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
Declared In
NSUndoManager.h

NSUndoManagerDidOpenUndoGroupNotification

Posted whenever an 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
Declared In
NSUndoManager.h

NSUndoManagerDidRedoChangeNotification

Posted just after an NSUndoManager object performs a redo operation (redo). The notification object is the NSUndoManager object. This notification does not contain a userInfo dictionary.
Availability
Declared In
NSUndoManager.h

NSUndoManagerDidUndoChangeNotification

Posted just after an 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
Declared In
NSUndoManager.h

NSUndoManagerWillCloseUndoGroupNotification

Posted before an 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
Declared In
NSUndoManager.h

NSUndoManagerDidCloseUndoGroupNotification

Posted after an 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
Declared In
NSUndoManager.h

NSUndoManagerWillRedoChangeNotification

Posted just before an NSUndoManager object performs a redo operation (redo). The notification object is the NSUndoManager object. This notification does not contain a userInfo dictionary.
Availability
Declared In
NSUndoManager.h

NSUndoManagerWillUndoChangeNotification

Posted just before an 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
Declared In
NSUndoManager.h