Interface UndoManager
- All Known Implementing Classes:
DefaultUndoManager
,NoopUndoManager
public interface UndoManager
An UndoManager is responsible for the management of actions a user takes in some kind of UI and
providing means of undoing and redoing those actions.
Actions are represented by UndoableEdit
s. Undoable edits encapsulate those actions at a
granularity that is up to the implementor. In general, it is desirable to neither make them too
fine-grained (don't undo every single key-press for some typed text) nor too coarse, so that an
undo loses a large amount of work. UndoableEdit.tryMergeInto(UndoableEdit)
can be used to
manage the granularity.
The undo manager will usually maintain two stacks of actions: the undo stack and the redo stack. The sizes of those stacks may be limited, so that the undo history doesn't become too large. The general undo algorithm is as follows:
- Edits are added to the undo stack using
addEdit(UndoableEdit)
. - Calling
undo()
will instruct the action at the top of the stack to undo its effect, then add the edit to the redo stack. - Calling
undo()
will instruct the action at the top of the stack to redo its effect, then add the edit back to the undo stack. - Adding an edit while the redo strack is non-empty will clear the redo stack making that path of action no longer accessible.
-
Method Summary
Modifier and TypeMethodDescriptionboolean
addEdit
(UndoableEdit anEdit) Add an undoable edit to the undo stack.void
Adds a handler that is called whenever the undo/redo item lists are updated.boolean
canRedo()
Determine whether there is currently something to redo.boolean
canUndo()
Determine whether there is currently something to undo.void
clear()
Clear the undo and redo stacks.void
Removes all handlers that are called whenever the undo/redo item lists are updated.Get the human-readable description of the edit at the top of the redo stack.Get the human-readable description of the edit at the top of the undo stack.void
redo()
Redo the edit at the top of the redo stack.void
Removes a handler that is called whenever the undo/redo item lists are updated.void
undo()
Undo the edit at the top of the undo stack.
-
Method Details
-
clear
void clear()Clear the undo and redo stacks. -
undo
Undo the edit at the top of the undo stack.- Throws:
CannotUndoException
- if the stack is empty or the edit cannot be undone for some other reason.
-
canUndo
boolean canUndo()Determine whether there is currently something to undo.- Returns:
true
if there is
-
redo
Redo the edit at the top of the redo stack.- Throws:
CannotRedoException
- if the stack is empty or the edit cannot be re-done for some other reason.
-
canRedo
boolean canRedo()Determine whether there is currently something to redo.- Returns:
true
if there is
-
addEdit
Add an undoable edit to the undo stack. This can happen in one of two ways:- The edit could not be merged into the element currently at the top of the stack either
because the stack was empty or because the
UndoableEdit.tryMergeInto(UndoableEdit)
returnedfalse
. In this case the new edit is simply added to the stack. - The edit could me berged.
- Parameters:
anEdit
- the edit- Returns:
true
if the edit was merged into the edit at the top of the stack,false
otherwise.
- The edit could not be merged into the element currently at the top of the stack either
because the stack was empty or because the
-
getUndoDescription
String getUndoDescription()Get the human-readable description of the edit at the top of the undo stack. It is provided by delegating toUndoableEdit.getUndoDescription()
.- Returns:
- the description or
null
if the undo stack is empty.
-
getRedoDescription
String getRedoDescription()Get the human-readable description of the edit at the top of the redo stack. It is provided by delegating toUndoableEdit.getRedoDescription()
.- Returns:
- the description or
null
if the redo stack is empty.
-
addOnUndoStackUpdatedHandler
Adds a handler that is called whenever the undo/redo item lists are updated.- Parameters:
handler
- The handler to add.
-
removeOnUndoStackUpdatedHandler
Removes a handler that is called whenever the undo/redo item lists are updated.- Parameters:
handler
- The handler to remove.
-
clearOnUndoStackUpdateHandlers
void clearOnUndoStackUpdateHandlers()Removes all handlers that are called whenever the undo/redo item lists are updated.
-