- 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
edits
Fields declared in class javax.swing.undo.AbstractUndoableEdit
RedoName, UndoName
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionboolean
addEdit
(UndoableEdit anEdit) Adds anUndoableEdit
to thisUndoManager
, if it's possible.boolean
canRedo()
Returns true if edits may be redone.boolean
canUndo()
Returns true if edits may be undone.boolean
Returns true if it is possible to invokeundo
orredo
.void
Empties the undo manager sending each edit adie
message in the process.protected UndoableEdit
Returns the next significant edit to be redone ifredo
is invoked.protected UndoableEdit
Returns the next significant edit to be undone ifundo
is invoked.void
end()
Turns thisUndoManager
into a normalCompoundEdit
.int
getLimit()
Returns the maximum number of edits thisUndoManager
holds.Returns a description of the redoable form of this edit.Convenience method that returns eithergetUndoPresentationName
orgetRedoPresentationName
.Returns a description of the undoable form of this edit.void
redo()
Redoes the appropriate edits.protected void
redoTo
(UndoableEdit edit) Redoes all changes from the index of the next edit toedit
, updating the index of the next edit appropriately.void
setLimit
(int l) Sets the maximum number of edits thisUndoManager
holds.toString()
Returns a string that displays and identifies this object's properties.protected void
trimEdits
(int from, int to) Removes edits in the specified range.protected void
Reduces the number of queued edits to a range of size limit, centered on the index of the next edit.void
undo()
Undoes the appropriate edits.void
AnUndoableEditListener
method.void
Convenience method that invokes one ofundo
orredo
.protected void
undoTo
(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, lastEdit
Methods 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 thisUndoManager
holds. A value less than 0 indicates the number of edits is not limited.- Returns:
- the maximum number of edits this
UndoManager
holds - See Also:
-
discardAllEdits
public void discardAllEdits()Empties the undo manager sending each edit adie
message 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 havedie
invoked 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 thisUndoManager
holds. A value less than 0 indicates the number of edits is not limited. If edits need to be discarded to shrink the limit,die
will be invoked on them in the reverse order they were added. The default is 100.- Parameters:
l
- the new limit- Throws:
RuntimeException
- if thisUndoManager
is not in progress (end
has been invoked)- See Also:
-
editToBeUndone
Returns the next significant edit to be undone ifundo
is invoked. This returnsnull
if there are no edits to be undone.- Returns:
- the next significant edit to be undone
-
editToBeRedone
Returns the next significant edit to be redone ifredo
is invoked. This returnsnull
if 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 ofundo
orredo
. 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 throwsCannotUndoException
CannotRedoException
- if one of the edits throwsCannotRedoException
- See Also:
-
canUndoOrRedo
public boolean canUndoOrRedo()Returns true if it is possible to invokeundo
orredo
.- Returns:
- true if invoking
canUndoOrRedo
is valid - See Also:
-
undo
Undoes the appropriate edits. Ifend
has been invoked this calls through to the superclass, otherwise this invokesundo
on all edits between the index of the next edit and the last significant edit, updating the index of the next edit appropriately.- Specified by:
undo
in interfaceUndoableEdit
- Overrides:
undo
in classCompoundEdit
- Throws:
CannotUndoException
- if one of the edits throwsCannotUndoException
or there are no edits to be undone- See Also:
-
canUndo
public boolean canUndo()Returns true if edits may be undone. Ifend
has been invoked, this returns the value from super. Otherwise this returns true if there are any edits to be undone (editToBeUndone
returns non-null
).- Specified by:
canUndo
in interfaceUndoableEdit
- Overrides:
canUndo
in classCompoundEdit
- Returns:
- true if there are edits to be undone
- See Also:
-
redo
Redoes the appropriate edits. Ifend
has been invoked this calls through to the superclass. Otherwise this invokesredo
on all edits between the index of the next edit and the next significant edit, updating the index of the next edit appropriately.- Specified by:
redo
in interfaceUndoableEdit
- Overrides:
redo
in classCompoundEdit
- Throws:
CannotRedoException
- if one of the edits throwsCannotRedoException
or there are no edits to be redone- See Also:
-
canRedo
public boolean canRedo()Returns true if edits may be redone. Ifend
has been invoked, this returns the value from super. Otherwise, this returns true if there are any edits to be redone (editToBeRedone
returns non-null
).- Specified by:
canRedo
in interfaceUndoableEdit
- Overrides:
canRedo
in classCompoundEdit
- Returns:
- true if there are edits to be redone
- See Also:
-
addEdit
Adds anUndoableEdit
to thisUndoManager
, if it's possible. This removes all edits from the index of the next edit to the end of the edits list. Ifend
has been invoked the edit is not added andfalse
is returned. Ifend
hasn't been invoked this returnstrue
.- Specified by:
addEdit
in interfaceUndoableEdit
- Overrides:
addEdit
in classCompoundEdit
- Parameters:
anEdit
- the edit to be added- Returns:
- true if
anEdit
can be incorporated into this edit - See Also:
-
end
public void end()Turns thisUndoManager
into a normalCompoundEdit
. This removes all edits that have been undone.- Overrides:
end
in classCompoundEdit
- See Also:
-
getUndoOrRedoPresentationName
Convenience method that returns eithergetUndoPresentationName
orgetRedoPresentationName
. If the index of the next edit equals the size of the edits list,getUndoPresentationName
is returned, otherwisegetRedoPresentationName
is returned.- Returns:
- undo or redo name
-
getUndoPresentationName
Returns a description of the undoable form of this edit. Ifend
has 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 andend
has not been invoked this returns the value from theUIManager
property "AbstractUndoableEdit.undoText".- Specified by:
getUndoPresentationName
in interfaceUndoableEdit
- Overrides:
getUndoPresentationName
in classCompoundEdit
- Returns:
- a description of the undoable form of this edit
- See Also:
-
getRedoPresentationName
Returns a description of the redoable form of this edit. Ifend
has 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 andend
has not been invoked this returns the value from theUIManager
property "AbstractUndoableEdit.redoText".- Specified by:
getRedoPresentationName
in interfaceUndoableEdit
- Overrides:
getRedoPresentationName
in classCompoundEdit
- Returns:
- a description of the redoable form of this edit
- See Also:
-
undoableEditHappened
AnUndoableEditListener
method. This invokesaddEdit
withe.getEdit()
.- Specified by:
undoableEditHappened
in interfaceUndoableEditListener
- Parameters:
e
- theUndoableEditEvent
theUndoableEditEvent
will be added from- See Also:
-
toString
Returns a string that displays and identifies this object's properties.- Overrides:
toString
in classCompoundEdit
- Returns:
- a String representation of this object
-