Class CPUndoManager

CPObject
    extended byCPUndoManager

@implementation CPUndoManager : CPObject

CPUndoManager 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 [[CPUndoManager alloc] init] message.


Method Summary
-(id)init
          Initializes the undo manager.
-(id)initWithCoder:(CPCoder)aCoder
-(void)beginUndoGrouping
          Starts a new grouping of undo tasks, and makes it the current grouping.
-(BOOL)canRedo
          Returns YES if the user can perform a redo operation.
-(BOOL)canUndo
          Returns YES if the user can perform an undo operation.
-(void)disableUndoRegistration
          Disables undo registrations.
-(void)enableUndoRegistration
          Enables undo registrations.
-(void)encodeWithCoder:(CPCoder)aCoder
-(void)endUndoGrouping
          Closes the current undo grouping.
-(void)forwardInvocation:(CPInvocation)anInvocation
          Records the specified invocation as an undo operation.
-(unsigned)groupingLevel
          Returns the number of undo/redo groups.
-(BOOL)groupsByEvent
          Returns YES if the manager groups undo operations at every iteration of the run loop.
-(BOOL)isRedoing
          Returns YES if the manager is currently performing a redo.
-(BOOL)isUndoRegistrationEnabled
          Returns YES if undo registration is enabled.
-(BOOL)isUndoing
          Returns YES if the manager is currently performing an undo.
-(id)prepareWithInvocationTarget:(id)aTarget
          Prepares the specified target for the undo action.
-(void)redo
          Performs the redo operation using the last grouping on the redo stack.
-(CPString)redoActionName
          If the receiver can perform a redo, this method returns the action name previously associated with the top grouping with -setActionName:.
-(void)registerUndoWithTarget:(id)aTarget selector:(SEL)aSelector object:(id)anObject
          Registers an undo operation.
-(void)removeAllActions
          Clears all redo and undo operations and enables undo registrations.
-(void)removeAllActionsWithTarget:(id)aTarget
          Removes any redo and undo operations that use the specified target.
-(CPArray)runLoopModes
          Returns the CPRunLoopModes in which the receiver registers the -endUndoGrouping processing when it -groupsByEvent.
-(void)setActionName:(CPString)anActionName
          Sets the name associated with the actions of the current group.
-(void)setGroupsByEvent:(BOOL)aFlag
          Sets whether the manager should group undo operations at every iteration of the run loop.
-(void)setRunLoopModes:(CPArray)modes
          Sets the modes in which the receiver registers the calls with the current run loop to invoke -endUndoGrouping when it -groupsByEvent.
-(void)undo
          Ends the current grouping, and performs an 'undo' operation.
-(CPString)undoActionName
          If the receiver can perform an undo, this method returns the action name previously associated with the top grouping with -setActionName:.
-(void)undoNestedGroup
          Performs an undo on the last undo group.

Methods inherited from class CPObject
initialize, alloc, class, instanceMethodForSelector, instancesRespondToSelector, isSubclassOfClass, load, new, setVersion, superclass, version, init, autorelease, awakeAfterUsingCoder, class, classForCoder, classForKeyedArchiver, className, copy, dealloc, description, doesNotRecognizeSelector, forwardInvocation, hash, isEqual, isKindOfClass, isMemberOfClass, isProxy, methodForSelector, methodSignatureForSelector, mutableCopy, performSelector, performSelector, performSelector, release, replacementObjectForArchiver, replacementObjectForCoder, replacementObjectForKeyedArchiver, respondsToSelector, retain, self, superclass


Method Detail

init

-(id)init
Initializes the undo manager
Returns:
the initialized undo manager

initWithCoder

-(id)initWithCoder:(CPCoder)aCoder
Parameters:
aCoder

beginUndoGrouping

-(void)beginUndoGrouping
Starts a new grouping of undo tasks, and makes it the current grouping.

canRedo

-(BOOL)canRedo
Returns YES if the user can perform a redo operation.

canUndo

-(BOOL)canUndo
Returns YES if the user can perform an undo operation.

disableUndoRegistration

-(void)disableUndoRegistration
Disables undo registrations.

enableUndoRegistration

-(void)enableUndoRegistration
Enables undo registrations. Calls to this method must be balanced with calls to disableUndoRegistration. So, if two disable calls were made, two enable calls are required to actually enable undo registration again.

encodeWithCoder

-(void)encodeWithCoder:(CPCoder)aCoder
Parameters:
aCoder

endUndoGrouping

-(void)endUndoGrouping
Closes the current undo grouping.
Throws:
CPInternalInconsistencyException - if no undo group is open

forwardInvocation

-(void)forwardInvocation:(CPInvocation)anInvocation
Records the specified invocation as an undo operation. Sets the target on the invocation, and adds it to the current grouping.
Parameters:
anInvocation - the message to record

groupingLevel

-(unsigned)groupingLevel
Returns the number of undo/redo groups.

groupsByEvent

-(BOOL)groupsByEvent
Returns YES if the manager groups undo operations at every iteration of the run loop.

isRedoing

-(BOOL)isRedoing
Returns YES if the manager is currently performing a redo.

isUndoRegistrationEnabled

-(BOOL)isUndoRegistrationEnabled
Returns YES if undo registration is enabled.

isUndoing

-(BOOL)isUndoing
Returns YES if the manager is currently performing an undo.

prepareWithInvocationTarget

-(id)prepareWithInvocationTarget:(id)aTarget
Prepares the specified target for the undo action.
Parameters:
aTarget - the target to receive the action
Returns:
the undo manager

redo

-(void)redo
Performs the redo operation using the last grouping on the redo stack.

redoActionName

-(CPString)redoActionName
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.
Returns:
the redo action's name, or nil if no there's no redo on the stack.

registerUndoWithTarget

-(void)registerUndoWithTarget:(id)aTarget selector:(SEL)aSelector object:(id)anObject
Registers an undo operation. 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 invocation will be added to the current grouping. If the registrations have been disabled through -disableUndoRegistration, this method does nothing.
Parameters:
aTarget - the target for the undo invocation
aSelector - the selector for the action message
anObject - the argument for the action message
Throws:
CPInternalInconsistencyException - if no undo group is currently open

removeAllActions

-(void)removeAllActions
Clears all redo and undo operations and enables undo registrations.

removeAllActionsWithTarget

-(void)removeAllActionsWithTarget:(id)aTarget
Removes any redo and undo operations that use the specified target.
Parameters:
aTarget - the target for which operations should be removed.

runLoopModes

-(CPArray)runLoopModes
Returns the CPRunLoopModes in which the receiver registers the -endUndoGrouping processing when it -groupsByEvent.

setActionName

-(void)setActionName:(CPString)anActionName
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.
Parameters:
anActionName - the new name for the current group

setGroupsByEvent

-(void)setGroupsByEvent:(BOOL)aFlag
Sets whether the manager should group undo operations at every iteration of the run loop.
Parameters:
aFlag - YES groups undo operations

setRunLoopModes

-(void)setRunLoopModes:(CPArray)modes
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.
Parameters:
modes - the modes in which calls are registered

undo

-(void)undo
Ends the current grouping, and performs an 'undo' operation.

undoActionName

-(CPString)undoActionName
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.
Returns:
the undo action name or nil if no if there's no undo on the stack.

undoNestedGroup

-(void)undoNestedGroup
Performs an undo on the last undo group.

Created on Sat Sep 13 14:15:43 PDT 2008