iOS Developer Library — Prerelease

Developer

Foundation Framework Reference NSUndoManager Class Reference

Options
Deployment Target:

On This Page
Language:

NSUndoManager

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

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

    Declaration

    Swift

    func registerUndoWithTarget(_ target: AnyObject, selector selector: Selector, object anObject: AnyObject?)

    Objective-C

    - (void)registerUndoWithTarget:(id _Nonnull)target selector:(SEL _Nonnull)aSelector object:(id _Nullable)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.

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

    Declaration

    Swift

    func prepareWithInvocationTarget(_ target: AnyObject) -> AnyObject

    Objective-C

    - (id _Nonnull)prepareWithInvocationTarget:(id _Nonnull)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.

  • A Boolean value that indicates whether the receiver has any actions to undo. (read-only)

    Declaration

    Swift

    var canUndo: Bool { get }

    Objective-C

    @property(readonly) BOOL canUndo

    Discussion

    YEStrue if the receiver has any actions to undo, otherwise NOfalse.

    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.

  • A Boolean value that indicates whether the receiver has any actions to redo. (read-only)

    Declaration

    Swift

    var canRedo: Bool { get }

    Objective-C

    @property(readonly) BOOL canRedo

    Discussion

    YEStrue if the receiver has any actions to redo, otherwise NOfalse.

    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.

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

    Declaration

    Swift

    var levelsOfUndo: Int

    Objective-C

    @property NSUInteger levelsOfUndo

    Discussion

    An integer specifying the number of undo groups. A limit of 0 indicates no limit, so old undo groups are never dropped.

    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 you change the limit to a level below the prior limit, old undo groups are immediately dropped.

    Availability

    Available in iOS 3.0 and later.

  • Marks the beginning of an undo group.

    Declaration

    Swift

    func beginUndoGrouping()

    Objective-C

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

  • Marks the end of an undo group.

    Declaration

    Swift

    func endUndoGrouping()

    Objective-C

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

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

    Declaration

    Swift

    var groupsByEvent: Bool

    Objective-C

    @property BOOL groupsByEvent

    Discussion

    YEStrue if the receiver automatically creates undo groups around each pass of the run loop, otherwise NOfalse.

    The default is YEStrue. 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.

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

    Declaration

    Swift

    var groupingLevel: Int { get }

    Objective-C

    @property(readonly) NSInteger groupingLevel

    Discussion

    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.

  • Returns a Boolean value that indicates whether the receiver is in the process of performing its undo or undoNestedGroup method. (read-only)

    Declaration

    Swift

    var undoing: Bool { get }

    Objective-C

    @property(readonly, getter=isUndoing) BOOL undoing

    Discussion

    YEStrue if the method is being performed, otherwise NOfalse.

    Availability

    Available in iOS 8.0 and later.

    See Also

    – isRedoing

  • Returns a Boolean value that indicates whether the receiver is in the process of performing its redo method. (read-only)

    Declaration

    Swift

    var redoing: Bool { get }

    Objective-C

    @property(readonly, getter=isRedoing) BOOL redoing

    Discussion

    YEStrue if the method is being performed, otherwise NOfalse.

    Availability

    Available in iOS 8.0 and later.

    See Also

    – isUndoing

  • The name identifying the undo action. (read-only)

    Declaration

    Swift

    var undoActionName: String { get }

    Objective-C

    @property(readonly, copy, nonnull) NSString *undoActionName

    Discussion

    The undo action name. Returns an empty string (@"") if no action name has been assigned or if there is nothing to undo.

    For example, if the menu title is “Undo Delete,” the string returned is “Delete.”

    Availability

    Available in iOS 3.0 and later.

  • The name identifying the redo action. (read-only)

    Declaration

    Swift

    var redoActionName: String { get }

    Objective-C

    @property(readonly, copy, nonnull) NSString *redoActionName

    Discussion

    The redo action name. Returns an empty string (@"") if no action name has been assigned or if there is nothing to redo.

    For example, if the menu title is “Redo Delete,” the string returned is “Delete.”

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    func setActionName(_ actionName: String)

    Objective-C

    - (void)setActionName:(NSString * _Nonnull)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.

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

    Declaration

    Swift

    var runLoopModes: [String]

    Objective-C

    @property(copy, nonnull) NSArray <NSString *> *runLoopModes

    Discussion

    An array of string constants specifying the current run-loop modes.

    By default, the sole run-loop mode is NSDefaultRunLoopMode (which excludes data from NSConnection objects). Some examples of other uses are to limit the input to data received during a mouse-tracking session by setting the mode to NSEventTrackingRunLoopMode, or limit it to data received from a modal panel with NSModalPanelRunLoopMode.

    Availability

    Available in iOS 3.0 and later.

  • Sets whether the next undo or redo action is discardable.

    Declaration

    Swift

    func setActionIsDiscardable(_ discardable: Bool)

    Objective-C

    - (void)setActionIsDiscardable:(BOOL)discardable

    Parameters

    discardable

    Specifies if the action is discardable. YEStrue if the next undo or redo action can be discarded; NOfalse 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.

  • Boolean value that indicates whether the next undo action is discardable. (read-only)

    Declaration

    Swift

    var undoActionIsDiscardable: Bool { get }

    Objective-C

    @property(readonly) BOOL undoActionIsDiscardable

    Discussion

    YEStrue if the action is discardable; NOfalse otherwise.

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

  • Boolean value that indicates whether the next redo action is discardable. (read-only)

    Declaration

    Swift

    var redoActionIsDiscardable: Bool { get }

    Objective-C

    @property(readonly) BOOL redoActionIsDiscardable

    Discussion

    YEStrue if the action is discardable; NOfalse otherwise.

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

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

    Declaration

    Swift

    var NSUndoCloseGroupingRunLoopOrdering: Int { get }

    Objective-C

    enum { NSUndoCloseGroupingRunLoopOrdering = 350000 };

    Constants

  • This constant is used in the userInfo dictionary of the NSUndoManagerWillCloseUndoGroupNotification it the undo group as a whole is discardable.

    Declaration

    Objective-C

    NSString * const NSUndoManagerGroupIsDiscardableKey;

    Constants

    • NSUndoManagerGroupIsDiscardableKey

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

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

    Declaration

    Swift

    let NSUndoManagerCheckpointNotification: String

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    let NSUndoManagerDidOpenUndoGroupNotification: String

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    let NSUndoManagerDidRedoChangeNotification: String

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    let NSUndoManagerDidUndoChangeNotification: String

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    let NSUndoManagerWillCloseUndoGroupNotification: String

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    let NSUndoManagerDidCloseUndoGroupNotification: String

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    let NSUndoManagerWillRedoChangeNotification: String

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    let NSUndoManagerWillUndoChangeNotification: String

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.