Up

NSUndoManager class reference

Authors

Richard Frith-Macdonald (richard@brainstorm.co.uk)

Version: 32173

Date: 2011-02-15 06:25:54 +0000 (Tue, 15 Feb 2011)

Copyright: (C) 1998 Free Software Foundation, Inc.

Software documentation for the NSUndoManager class

NSUndoManager : NSObject

Declared in:
Foundation/NSUndoManager.h
Availability: MacOS-X 10.0.0

NSUndoManager provides a general mechanism supporting implementation of user action "undo" in applications. Essentially, it allows you to store sequences of messages and receivers that need to be invoked to undo or redo an action. The various methods in this class provide for grouping of sets of actions, execution of undo or redo actions, and tuning behavior parameters such as the size of the undo stack. Each application entity with its own editing history (e.g., a document) should have its own undo manager instance. Obtain an instance through a simple [[NSUndoManager alloc] init] message.
Method summary

beginUndoGrouping 

- (void) beginUndoGrouping;
Availability: MacOS-X 10.0.0

Starts a new grouping of undo actions which can be atomically undone by an [-undo] invocation.
This method posts an NSUndoManagerDidOpenUndoGroupNotification upon creating the grouping.
It first posts an NSUndoManagerCheckpointNotification unless an undo is currently in progress.
The order of these notifications is undefined, but the GNUstep implementation currently mimics the observed order in MacOS X 10.5

canRedo 

- (BOOL) canRedo;
Availability: MacOS-X 10.0.0

Returns whether the receiver can service redo requests and posts a NSUndoManagerCheckpointNotification.

canUndo 

- (BOOL) canUndo;
Availability: MacOS-X 10.0.0

Returns whether the receiver has any action groupings on the stack to undo. It does not imply, that the receiver is currently in a state to service an undo request. Make sure [-endUndoGrouping] is invoked before requesting either an [-undo] or an -undoNestedGroup .

disableUndoRegistration 

- (void) disableUndoRegistration;
Availability: MacOS-X 10.0.0

Disables the registration of operations with with either [-registerUndoWithTarget:selector:object:] or -forwardInvocation: . This method may be called multiple times. Each will need to be paired to a call of [-enableUndoRegistration] before registration is actually reenabled.

enableUndoRegistration 

- (void) enableUndoRegistration;
Availability: MacOS-X 10.0.0

Matches previous calls of to -disableUndoRegistration . Only call this method to that end. Once all are matched, the registration of [-registerUndoWithTarget:selector:object:] and [-forwardInvocation:] are reenabled. If this method is called without a matching -disableUndoRegistration , it will raise an NSInternalInconsistencyException.

endUndoGrouping 

- (void) endUndoGrouping;
Availability: MacOS-X 10.0.0

Matches previous calls of to [-beginUndoGrouping] and puts the group on the undo stack. This method posts an NSUndoManagerCheckpointNotification and a NSUndoManagerWillCloseUndoGroupNotification. If there was no matching call to -beginUndoGrouping , this method will raise an NSInternalInconsistencyException.

forwardInvocation: 

- (void) forwardInvocation: (NSInvocation*)anInvocation;
Availability: MacOS-X 10.0.0

Registers the invocation with the current undo grouping. This method is part of the NSInvocation-based undo registration as opposed to the simpler [-registerUndoWithTarget:selector:object:] technique.
You generally never invoke this method directly. Instead invoke [-prepareWithInvocationTarget:] with the target of the undo action and then invoke the targets method to undo the action on the return value of -prepareWithInvocationTarget: which actually is the undo manager. The runtime will then fallback to -forwardInvocation: to do the actual registration of the invocation. The invocation will added to the current grouping.
If the registrations have been disabled through -disableUndoRegistration , this method does nothing.
Unless the receiver implicitly groups operations by event, the this method must have been preceded with a [-beginUndoGrouping] message. Otherwise it will raise an NSInternalInconsistencyException.
Unless this method is invoked as part of a [-undo] or [-undoNestedGroup] processing, the redo stack is cleared.
If the receiver [-groupsByEvent] and this is the first call to this method since the last run loop processing, this method sets up the receiver to process the [-endUndoGrouping] at the end of the event loop.

groupingLevel 

- (NSInteger) groupingLevel;
Availability: MacOS-X 10.0.0

Returns the current number of groupings. These are the current groupings which can be nested, not the number of of groups on either the undo or redo stack.

groupsByEvent 

- (BOOL) groupsByEvent;
Availability: MacOS-X 10.0.0

Returns whether the receiver currently groups undo operations by events. When it does, so it implicitly invokes [-beginUndoGrouping] upon registration of undo operations and registers an internal call to insure the invocation of [-endUndoGrouping] at the end of the run loop.

isRedoing 

- (BOOL) isRedoing;
Availability: MacOS-X 10.0.0

Returns whether the receiver is currently processing a redo.

isUndoRegistrationEnabled 

- (BOOL) isUndoRegistrationEnabled;
Availability: MacOS-X 10.0.0

Returns whether the receiver will currently register undo operations.

isUndoing 

- (BOOL) isUndoing;
Availability: MacOS-X 10.0.0

Returns whether the receiver is currently processing an undo.

levelsOfUndo 

- (NSUInteger) levelsOfUndo;
Availability: MacOS-X 10.0.0

Returns the maximum number of undo groupings the receiver will maintain. The default value is 0 meaning the number is only limited by memory availability.

prepareWithInvocationTarget: 

- (id) prepareWithInvocationTarget: (id)target;
Availability: MacOS-X 10.0.0

Prepares the receiver to registers an invocation-based undo operation. This method is part of the NSInvocation-based undo registration as opposed to the simpler [-registerUndoWithTarget:selector:object:] technique.
You invoke this method with the target of the undo action and then invoke the targets method to undo the action on the return value of this invocation which actually is the undo manager. The runtime will then fallback to [-forwardInvocation:] to do the actual registration of the invocation.

redo 

- (void) redo;
Availability: MacOS-X 10.0.0

Performs a redo of previous undo request by taking the top grouping from the redo stack and invoking them. This method posts an NSUndoManagerCheckpointNotification notification to allow the client to process any pending changes before proceeding. If there are groupings on the redo stack, the top object is popped off the stack and invoked within a nested -beginUndoGrouping /[-endUndoGrouping]. During this processing, the operations registered for undo are recorded on the undo stack again.

redoActionName 

- (NSString*) redoActionName;
Availability: MacOS-X 10.0.0

If the receiver can perform a redo, this method returns the action name previously associated with the top grouping with -setActionName: . This name should identify the action to be redone. If there are no items on the redo stack this method returns nil. If no action name has been set, this method returns an empty string.

redoMenuItemTitle 

- (NSString*) redoMenuItemTitle;
Availability: MacOS-X 10.0.0

Returns the full localized title of the actions to be displayed as a menu item. This method first invokes [-redoActionName] and passes it to [-redoMenuTitleForUndoActionName:] and returns the result.

redoMenuTitleForUndoActionName: 

- (NSString*) redoMenuTitleForUndoActionName: (NSString*)actionName;
Availability: MacOS-X 10.0.0

Returns the localized title of the actions to be displayed as a menu item identified by actionName, by appending a localized command string like @"Redo <localized( actionName)>".

registerUndoWithTarget: selector: object: 

- (void) registerUndoWithTarget: (id)target selector: (SEL)aSelector object: (id)anObject;
Availability: MacOS-X 10.0.0

Registers an undo operation. This method is the simple target-action-based undo registration as opposed to the sophisticated [-forwardInvocation:] mechanism.
You invoke this method with the target of the undo action providing the selector which can perform the undo with the provided object. The object is often a dictionary of the identifying the attribute and their values before the change. The object will be retained. The invocation will added to the current grouping.
If the registrations have been disabled through -disableUndoRegistration , this method does nothing.
Unless the receiver implicitly groups operations by event, the this method must have been preceded with a [-beginUndoGrouping] message. Otherwise it will raise an NSInternalInconsistencyException.
Unless this method is invoked as part of a [-undo] or [-undoNestedGroup] processing, the redo stack is cleared.
If the receiver [-groupsByEvent] and this is the first call to this method since the last run loop processing, this method sets up the receiver to process the [-endUndoGrouping] at the end of the event loop.

removeAllActions 

- (void) removeAllActions;
Availability: MacOS-X 10.0.0

Removes all grouping stored in the receiver. This clears the both the undo and the redo stacks. This method is if the sole client of the undo manager will be unable to service any undo or redo events. The client can call this method in its -dealloc method, unless the undo manager has several clients, in which case [-removeAllActionsWithTarget:] is more appropriate.

removeAllActionsWithTarget: 

- (void) removeAllActionsWithTarget: (id)target;
Availability: MacOS-X 10.0.0

Removes all actions recorded for the given target. This method is is useful when a client of the undo manager will be unable to service any undo or redo events. Clients should call this method in their dealloc method, unless they are the sole client of the undo manager in which case [-removeAllActions] is more appropriate.

runLoopModes 

- (NSArray*) runLoopModes;
Availability: MacOS-X 10.0.0

Returns the run loop modes in which the receiver registers the [-endUndoGrouping] processing when it -groupsByEvent .

setActionName: 

- (void) setActionName: (NSString*)name;
Availability: MacOS-X 10.0.0

Sets the name associated with the actions of the current group. Typically you can call this method while registering the actions for the current group. This name will be used to determine the name in the [-undoMenuTitleForUndoActionName:] and [-redoMenuTitleForUndoActionName:] names typically displayed in the menu.

setGroupsByEvent: 

- (void) setGroupsByEvent: (BOOL)flag;
Availability: MacOS-X 10.0.0

Sets whether the receiver should implicitly call [-beginUndoGrouping] when necessary and register a call to invoke [-endUndoGrouping] at the end of the current event loop. The grouping is turned on by default.

setLevelsOfUndo: 

- (void) setLevelsOfUndo: (NSUInteger)num;
Availability: MacOS-X 10.0.0

Sets the maximum number of groups in either the undo or redo stack. Use this method to limit memory usage if you either expect very many actions to be recorded or the recorded objects require a lot of memory. When set to 0 the stack size is limited by the range of a unsigned int, available memory.

setRunLoopModes: 

- (void) setRunLoopModes: (NSArray*)newModes;
Availability: MacOS-X 10.0.0

Sets the modes in which the receiver registers the calls with the current run loop to invoke [-endUndoGrouping] when it -groupsByEvent . This method first cancels any pending registrations in the old modes and registers the invocation in the new modes.

undo 

- (void) undo;
Availability: MacOS-X 10.0.0

This method performs an undo by invoking -undoNestedGroup . If current group of the receiver is the top group this method first calls -endUndoGrouping . This method may only be called on the top level group, otherwise it will raise an NSInternalInconsistencyException.

undoActionName 

- (NSString*) undoActionName;
Availability: MacOS-X 10.0.0

If the receiver can perform an undo, this method returns the action name previously associated with the top grouping with -setActionName: . This name should identify the action to be undone. If there are no items on the undo stack this method returns nil. If no action name has been set, this method returns an empty string.

undoMenuItemTitle 

- (NSString*) undoMenuItemTitle;
Availability: MacOS-X 10.0.0

Returns the full localized title of the actions to be displayed as a menu item. This method first invokes [-undoActionName] and passes it to [-undoMenuTitleForUndoActionName:] and returns the result.

undoMenuTitleForUndoActionName: 

- (NSString*) undoMenuTitleForUndoActionName: (NSString*)actionName;
Availability: MacOS-X 10.0.0

Returns the localized title of the actions to be displayed as a menu item identified by actionName, by appending a localized command string like @"Undo <localized( actionName)>".

undoNestedGroup 

- (void) undoNestedGroup;
Availability: MacOS-X 10.0.0

Performs an undo by taking the top grouping from the undo stack and invoking them. This method posts an NSUndoManagerCheckpointNotification notification to allow the client to process any pending changes before proceeding. If there are groupings on the undo stack, the top object is popped off the stack and invoked within a nested beginUndoGrouping/endUndoGrouping. During this processing, the undo operations registered for undo are recorded on the redo stack.


Up