Class UndoManager
- All Implemented Interfaces:
Serializable,EventListener,UndoableEditListener,UndoableEdit
UndoManager manages a list of UndoableEdits,
providing a way to undo or redo the appropriate edits. There are
two ways to add edits to an UndoManager. Add the edit
directly using the addEdit method, or add the
UndoManager to a bean that supports
UndoableEditListener. The following examples creates
an UndoManager and adds it as an
UndoableEditListener to a JTextField:
UndoManager undoManager = new UndoManager(); JTextField tf = ...; tf.getDocument().addUndoableEditListener(undoManager);
UndoManager maintains an ordered list of edits and the
index of the next edit in that list. The index of the next edit is
either the size of the current list of edits, or if
undo has been invoked it corresponds to the index
of the last significant edit that was undone. When
undo is invoked all edits from the index of the next
edit to the last significant edit are undone, in reverse order.
For example, consider an UndoManager consisting of the
following edits: A b c D. Edits with a
upper-case letter in bold are significant, those in lower-case
and italicized are insignificant.
|
| Figure 1 |
As shown in figure 1, if D was just added, the
index of the next edit will be 4. Invoking undo
results in invoking undo on D and setting the
index of the next edit to 3 (edit c), as shown in the following
figure.
|
| Figure 2 |
The last significant edit is A, so that invoking
undo again invokes undo on c,
b, and A, in that order, setting the index of the
next edit to 0, as shown in the following figure.
|
| Figure 3 |
Invoking redo results in invoking redo on
all edits between the index of the next edit and the next
significant edit (or the end of the list). Continuing with the previous
example if redo were invoked, redo would in
turn be invoked on A, b and c. In addition
the index of the next edit is set to 3 (as shown in figure 2).
Adding an edit to an UndoManager results in
removing all edits from the index of the next edit to the end of
the list. Continuing with the previous example, if a new edit,
e, is added the edit D is removed from the list
(after having die invoked on it). If c is not
incorporated by the next edit
(c.addEdit(e) returns true), or replaced
by it (e.replaceEdit(c) returns true),
the new edit is added after c, as shown in the following
figure.
|
| Figure 4 |
Once end has been invoked on an UndoManager
the superclass behavior is used for all UndoableEdit
methods. Refer to CompoundEdit for more details on its
behavior.
Unlike the rest of Swing, this class is thread safe.
Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing. As of 1.4, support for long term storage
of all JavaBeans
has been added to the java.beans package.
Please see XMLEncoder.
-
Field Summary
Fields declared in class javax.swing.undo.CompoundEdit
editsFields declared in class javax.swing.undo.AbstractUndoableEdit
RedoName, UndoName -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionbooleanaddEdit(UndoableEdit anEdit) Adds anUndoableEditto thisUndoManager, if it's possible.booleancanRedo()Returns true if edits may be redone.booleancanUndo()Returns true if edits may be undone.booleanReturns true if it is possible to invokeundoorredo.voidEmpties the undo manager sending each edit adiemessage in the process.protected UndoableEditReturns the next significant edit to be redone ifredois invoked.protected UndoableEditReturns the next significant edit to be undone ifundois invoked.voidend()Turns thisUndoManagerinto a normalCompoundEdit.intgetLimit()Returns the maximum number of edits thisUndoManagerholds.Returns a description of the redoable form of this edit.Convenience method that returns eithergetUndoPresentationNameorgetRedoPresentationName.Returns a description of the undoable form of this edit.voidredo()Redoes the appropriate edits.protected voidredoTo(UndoableEdit edit) Redoes all changes from the index of the next edit toedit, updating the index of the next edit appropriately.voidsetLimit(int l) Sets the maximum number of edits thisUndoManagerholds.toString()Returns a string that displays and identifies this object's properties.protected voidtrimEdits(int from, int to) Removes edits in the specified range.protected voidReduces the number of queued edits to a range of size limit, centered on the index of the next edit.voidundo()Undoes the appropriate edits.voidAnUndoableEditListenermethod.voidConvenience method that invokes one ofundoorredo.protected voidundoTo(UndoableEdit edit) Undoes all changes from the index of the next edit toedit, updating the index of the next edit appropriately.Methods declared in class javax.swing.undo.CompoundEdit
die, getPresentationName, isInProgress, isSignificant, lastEditMethods declared in class javax.swing.undo.AbstractUndoableEdit
replaceEdit
-
Constructor Details
-
UndoManager
public UndoManager()Creates a newUndoManager.
-
-
Method Details
-
getLimit
public int getLimit()Returns the maximum number of edits thisUndoManagerholds. A value less than 0 indicates the number of edits is not limited.- Returns:
- the maximum number of edits this
UndoManagerholds - See Also:
-
discardAllEdits
public void discardAllEdits()Empties the undo manager sending each edit adiemessage in the process.- See Also:
-
trimForLimit
protected void trimForLimit()Reduces the number of queued edits to a range of size limit, centered on the index of the next edit. -
trimEdits
protected void trimEdits(int from, int to) Removes edits in the specified range. All edits in the given range (inclusive, and in reverse order) will havedieinvoked on them and are removed from the list of edits. This has no effect iffrom>to.- Parameters:
from- the minimum index to removeto- the maximum index to remove
-
setLimit
public void setLimit(int l) Sets the maximum number of edits thisUndoManagerholds. A value less than 0 indicates the number of edits is not limited. If edits need to be discarded to shrink the limit,diewill be invoked on them in the reverse order they were added. The default is 100.- Parameters:
l- the new limit- Throws:
RuntimeException- if thisUndoManageris not in progress (endhas been invoked)- See Also:
-
editToBeUndone
Returns the next significant edit to be undone ifundois invoked. This returnsnullif there are no edits to be undone.- Returns:
- the next significant edit to be undone
-
editToBeRedone
Returns the next significant edit to be redone ifredois invoked. This returnsnullif there are no edits to be redone.- Returns:
- the next significant edit to be redone
-
undoTo
Undoes all changes from the index of the next edit toedit, updating the index of the next edit appropriately.- Parameters:
edit- the edit to be undo to- Throws:
CannotUndoException- if one of the edits throwsCannotUndoException
-
redoTo
Redoes all changes from the index of the next edit toedit, updating the index of the next edit appropriately.- Parameters:
edit- the edit to be redo to- Throws:
CannotRedoException- if one of the edits throwsCannotRedoException
-
undoOrRedo
Convenience method that invokes one ofundoorredo. If any edits have been undone (the index of the next edit is less than the length of the edits list) this invokesredo, otherwise it invokesundo.- Throws:
CannotUndoException- if one of the edits throwsCannotUndoExceptionCannotRedoException- if one of the edits throwsCannotRedoException- See Also:
-
canUndoOrRedo
public boolean canUndoOrRedo()Returns true if it is possible to invokeundoorredo.- Returns:
- true if invoking
canUndoOrRedois valid - See Also:
-
undo
Undoes the appropriate edits. Ifendhas been invoked this calls through to the superclass, otherwise this invokesundoon all edits between the index of the next edit and the last significant edit, updating the index of the next edit appropriately.- Specified by:
undoin interfaceUndoableEdit- Overrides:
undoin classCompoundEdit- Throws:
CannotUndoException- if one of the edits throwsCannotUndoExceptionor there are no edits to be undone- See Also:
-
canUndo
public boolean canUndo()Returns true if edits may be undone. Ifendhas been invoked, this returns the value from super. Otherwise this returns true if there are any edits to be undone (editToBeUndonereturns non-null).- Specified by:
canUndoin interfaceUndoableEdit- Overrides:
canUndoin classCompoundEdit- Returns:
- true if there are edits to be undone
- See Also:
-
redo
Redoes the appropriate edits. Ifendhas been invoked this calls through to the superclass. Otherwise this invokesredoon all edits between the index of the next edit and the next significant edit, updating the index of the next edit appropriately.- Specified by:
redoin interfaceUndoableEdit- Overrides:
redoin classCompoundEdit- Throws:
CannotRedoException- if one of the edits throwsCannotRedoExceptionor there are no edits to be redone- See Also:
-
canRedo
public boolean canRedo()Returns true if edits may be redone. Ifendhas been invoked, this returns the value from super. Otherwise, this returns true if there are any edits to be redone (editToBeRedonereturns non-null).- Specified by:
canRedoin interfaceUndoableEdit- Overrides:
canRedoin classCompoundEdit- Returns:
- true if there are edits to be redone
- See Also:
-
addEdit
Adds anUndoableEditto thisUndoManager, if it's possible. This removes all edits from the index of the next edit to the end of the edits list. Ifendhas been invoked the edit is not added andfalseis returned. Ifendhasn't been invoked this returnstrue.- Specified by:
addEditin interfaceUndoableEdit- Overrides:
addEditin classCompoundEdit- Parameters:
anEdit- the edit to be added- Returns:
- true if
anEditcan be incorporated into this edit - See Also:
-
end
public void end()Turns thisUndoManagerinto a normalCompoundEdit. This removes all edits that have been undone.- Overrides:
endin classCompoundEdit- See Also:
-
getUndoOrRedoPresentationName
Convenience method that returns eithergetUndoPresentationNameorgetRedoPresentationName. If the index of the next edit equals the size of the edits list,getUndoPresentationNameis returned, otherwisegetRedoPresentationNameis returned.- Returns:
- undo or redo name
-
getUndoPresentationName
Returns a description of the undoable form of this edit. Ifendhas been invoked this calls into super. Otherwise if there are edits to be undone, this returns the value from the next significant edit that will be undone. If there are no edits to be undone andendhas not been invoked this returns the value from theUIManagerproperty "AbstractUndoableEdit.undoText".- Specified by:
getUndoPresentationNamein interfaceUndoableEdit- Overrides:
getUndoPresentationNamein classCompoundEdit- Returns:
- a description of the undoable form of this edit
- See Also:
-
getRedoPresentationName
Returns a description of the redoable form of this edit. Ifendhas been invoked this calls into super. Otherwise if there are edits to be redone, this returns the value from the next significant edit that will be redone. If there are no edits to be redone andendhas not been invoked this returns the value from theUIManagerproperty "AbstractUndoableEdit.redoText".- Specified by:
getRedoPresentationNamein interfaceUndoableEdit- Overrides:
getRedoPresentationNamein classCompoundEdit- Returns:
- a description of the redoable form of this edit
- See Also:
-
undoableEditHappened
AnUndoableEditListenermethod. This invokesaddEditwithe.getEdit().- Specified by:
undoableEditHappenedin interfaceUndoableEditListener- Parameters:
e- theUndoableEditEventtheUndoableEditEventwill be added from- See Also:
-
toString
Returns a string that displays and identifies this object's properties.- Overrides:
toStringin classCompoundEdit- Returns:
- a String representation of this object
-