Class UndoManager
- java.lang.Object
-
- javax.swing.undo.AbstractUndoableEdit
-
- javax.swing.undo.CompoundEdit
-
- javax.swing.undo.UndoManager
- All Implemented Interfaces:
-
Serializable
,EventListener
,UndoableEditListener
,UndoableEdit
public class UndoManager extends CompoundEdit implements UndoableEditListener
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
.
- See Also:
- Serialized Form
Field Summary
Fields declared in class javax.swing.undo.CompoundEdit
edits
Fields declared in class javax.swing.undo.AbstractUndoableEdit
RedoName, UndoName
Constructor Summary
Constructor | Description |
---|---|
UndoManager() | Creates a new |
Method Summary
Modifier and Type | Method | Description |
---|---|---|
boolean | addEdit(UndoableEdit anEdit) | Adds an |
boolean | canRedo() | Returns true if edits may be redone. |
boolean | canUndo() | Returns true if edits may be undone. |
boolean | canUndoOrRedo() | Returns true if it is possible to invoke |
void | discardAllEdits() | Empties the undo manager sending each edit a |
protected UndoableEdit | editToBeRedone() | Returns the next significant edit to be redone if |
protected UndoableEdit | editToBeUndone() | Returns the next significant edit to be undone if |
void | end() | Turns this |
int | getLimit() | Returns the maximum number of edits this |
String | getRedoPresentationName() | Returns a description of the redoable form of this edit. |
String | getUndoOrRedoPresentationName() | Convenience method that returns either |
String | getUndoPresentationName() | 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 to |
void | setLimit(int l) | Sets the maximum number of edits this |
String | 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 | trimForLimit() | 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 | undoableEditHappened(UndoableEditEvent e) | An |
void | undoOrRedo() | Convenience method that invokes one of |
protected void | undoTo(UndoableEdit edit) | Undoes all changes from the index of the next edit to |
Methods declared in class javax.swing.undo.CompoundEdit
die, getPresentationName, isInProgress, isSignificant, lastEdit
Methods declared in class javax.swing.undo.AbstractUndoableEdit
replaceEdit
Methods declared in class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Constructor Detail
UndoManager
public UndoManager()
Creates a new UndoManager
.
Method Detail
getLimit
public int getLimit()
Returns the maximum number of edits this UndoManager
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:
-
addEdit(javax.swing.undo.UndoableEdit)
,setLimit(int)
discardAllEdits
public void discardAllEdits()
Empties the undo manager sending each edit a die
message in the process.
- See Also:
AbstractUndoableEdit.die()
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 have die
invoked on them and are removed from the list of edits. This has no effect if from
> to
.
- Parameters:
-
from
- the minimum index to remove -
to
- the maximum index to remove
setLimit
public void setLimit(int l)
Sets the maximum number of edits this UndoManager
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:
-
CompoundEdit.isInProgress()
,end()
,addEdit(javax.swing.undo.UndoableEdit)
,getLimit()
editToBeUndone
protected UndoableEdit editToBeUndone()
Returns the next significant edit to be undone if undo
is invoked. This returns null
if there are no edits to be undone.
- Returns:
- the next significant edit to be undone
editToBeRedone
protected UndoableEdit editToBeRedone()
Returns the next significant edit to be redone if redo
is invoked. This returns null
if there are no edits to be redone.
- Returns:
- the next significant edit to be redone
undoTo
protected void undoTo(UndoableEdit edit) throws CannotUndoException
Undoes all changes from the index of the next edit to edit
, 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
protected void redoTo(UndoableEdit edit) throws CannotRedoException
Redoes all changes from the index of the next edit to edit
, 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
public void undoOrRedo() throws CannotRedoException, CannotUndoException
Convenience method that invokes one of undo
or redo
. If any edits have been undone (the index of the next edit is less than the length of the edits list) this invokes redo
, otherwise it invokes undo
.
- Throws:
-
CannotUndoException
- if one of the edits throwsCannotUndoException
-
CannotRedoException
- if one of the edits throwsCannotRedoException
- See Also:
-
canUndoOrRedo()
,getUndoOrRedoPresentationName()
canUndoOrRedo
public boolean canUndoOrRedo()
Returns true if it is possible to invoke undo
or redo
.
- Returns:
- true if invoking
canUndoOrRedo
is valid - See Also:
undoOrRedo()
undo
public void undo() throws CannotUndoException
Undoes the appropriate edits. If end
has been invoked this calls through to the superclass, otherwise this invokes undo
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:
-
CompoundEdit.end()
,canUndo()
,editToBeUndone()
canUndo
public boolean canUndo()
Returns true if edits may be undone. If end
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:
-
CompoundEdit.canUndo()
,editToBeUndone()
redo
public void redo() throws CannotRedoException
Redoes the appropriate edits. If end
has been invoked this calls through to the superclass. Otherwise this invokes redo
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:
-
CompoundEdit.end()
,canRedo()
,editToBeRedone()
canRedo
public boolean canRedo()
Returns true if edits may be redone. If end
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:
-
CompoundEdit.canRedo()
,editToBeRedone()
addEdit
public boolean addEdit(UndoableEdit anEdit)
Adds an UndoableEdit
to this UndoManager
, if it's possible. This removes all edits from the index of the next edit to the end of the edits list. If end
has been invoked the edit is not added and false
is returned. If end
hasn't been invoked this returns true
.
- 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:
-
CompoundEdit.end()
,CompoundEdit.addEdit(javax.swing.undo.UndoableEdit)
end
public void end()
Turns this UndoManager
into a normal CompoundEdit
. This removes all edits that have been undone.
- Overrides:
-
end
in classCompoundEdit
- See Also:
CompoundEdit.end()
getUndoOrRedoPresentationName
public String getUndoOrRedoPresentationName()
Convenience method that returns either getUndoPresentationName
or getRedoPresentationName
. If the index of the next edit equals the size of the edits list, getUndoPresentationName
is returned, otherwise getRedoPresentationName
is returned.
- Returns:
- undo or redo name
getUndoPresentationName
public String getUndoPresentationName()
Returns a description of the undoable form of this edit. If end
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 and end
has not been invoked this returns the value from the UIManager
property "AbstractUndoableEdit.undoText".
- Specified by:
-
getUndoPresentationName
in interfaceUndoableEdit
- Overrides:
-
getUndoPresentationName
in classCompoundEdit
- Returns:
- a description of the undoable form of this edit
- See Also:
-
undo()
,CompoundEdit.getUndoPresentationName()
getRedoPresentationName
public String getRedoPresentationName()
Returns a description of the redoable form of this edit. If end
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 and end
has not been invoked this returns the value from the UIManager
property "AbstractUndoableEdit.redoText".
- Specified by:
-
getRedoPresentationName
in interfaceUndoableEdit
- Overrides:
-
getRedoPresentationName
in classCompoundEdit
- Returns:
- a description of the redoable form of this edit
- See Also:
-
redo()
,CompoundEdit.getRedoPresentationName()
undoableEditHappened
public void undoableEditHappened(UndoableEditEvent e)
An UndoableEditListener
method. This invokes addEdit
with e.getEdit()
.
- Specified by:
-
undoableEditHappened
in interfaceUndoableEditListener
- Parameters:
-
e
- theUndoableEditEvent
theUndoableEditEvent
will be added from - See Also:
addEdit(javax.swing.undo.UndoableEdit)
toString
public String toString()
Returns a string that displays and identifies this object's properties.
- Overrides:
-
toString
in classCompoundEdit
- Returns:
- a String representation of this object