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.
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
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
.
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.
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.
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.
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.
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.
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.
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.
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.
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)>".
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.
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.
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.
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.
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.
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
unsignedint,
available memory.
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.
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.
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.
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)>".
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.