Class

NSUndoManager

A general-purpose recorder of operations that enables undo and redo.

Declaration

@interface NSUndoManager : NSObject

Overview

You register an undo operation by calling one of the methods described in Registering Undo Operations. You specify the name of the object that’s changing (or the owner of that object) and provide a closure, method, or invocation to revert its state.

After you register an undo operation, you can call undo on the undo manager to revert to the state of the last undo operation. When undoing an action, NSUndoManager saves the operations you reverted to so that you can call redo automatically.

NSUndoManager is typically used by apps with UI interactions. For example, UIKit implements undo and redo in its text view object, making it easy for you to undo and redo actions in objects along the responder chain. NSUndoManager also serves as a general-purpose state manager, which can be used to undo and redo many kinds of actions. For example, an interactive command-line utility could use this class to undo the last command run, or a networking library could undo a request by sending another request that invalidates the previous one.

Topics

Registering Undo Operations

registerUndoWithTarget:handler:

Records a single undo operation for a given target so that when an undo is performed, it executes the specified block.

registerUndoWithTarget:selector:object:

Registers the selector of the specified target to implement a single undo operation that the target receives.

prepareWithInvocationTarget:

Prepares the undo manager for invocation-based undo with the given target as the subject of the next undo operation.

Checking Undo Ability

canUndo

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

canRedo

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

Performing Undo and Redo

undo

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

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.

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.

Limiting the Undo Stack

levelsOfUndo

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

Creating Undo Groups

beginUndoGrouping

Marks the beginning of an undo group.

endUndoGrouping

Marks the end of an undo group.

groupsByEvent

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

groupingLevel

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

Enabling and Disabling Undo

disableUndoRegistration

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

enableUndoRegistration

Enables the recording of undo operations.

undoRegistrationEnabled

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

Checking Whether Undo or Redo Is Being Performed

undoing

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

redoing

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

Clearing Undo Operations

removeAllActions

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

removeAllActionsWithTarget:

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

Managing the Action Name

undoActionName

The name identifying the undo action.

redoActionName

The name identifying the redo action.

setActionName:

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

Getting and Localizing the Menu Item Title

undoMenuItemTitle

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

redoMenuItemTitle

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

undoMenuTitleForUndoActionName:

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

redoMenuTitleForUndoActionName:

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

Working with Run Loops

runLoopModes

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

Discardable Undo and Redo Actions

setActionIsDiscardable:

Sets whether the next undo or redo action is discardable.

undoActionIsDiscardable

Boolean value that indicates whether the next undo action is discardable.

redoActionIsDiscardable

Boolean value that indicates whether the next redo action is discardable.

Constants

NSUndoCloseGroupingRunLoopOrdering

NSUndoManager provides this constant as a convenience; you can use it to compare to values returned by some NSUndoManager methods.

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.

NSUndoManagerDidOpenUndoGroupNotification

Posted whenever an NSUndoManager object opens an undo group, which occurs in the implementation of the beginUndoGrouping method.

NSUndoManagerDidRedoChangeNotification

Posted just after an NSUndoManager object performs a redo operation (redo).

NSUndoManagerDidUndoChangeNotification

Posted just after an NSUndoManager object performs an undo operation.

NSUndoManagerWillCloseUndoGroupNotification

Posted before an NSUndoManager object closes an undo group, which occurs in the implementation of the endUndoGrouping method.

NSUndoManagerDidCloseUndoGroupNotification

Posted after an NSUndoManager object closes an undo group, which occurs in the implementation of the endUndoGrouping method.

NSUndoManagerWillRedoChangeNotification

Posted just before an NSUndoManager object performs a redo operation (redo).

NSUndoManagerWillUndoChangeNotification

Posted just before an NSUndoManager object performs an undo operation.

Relationships

Inherits From