UndoManager JDK 1.6)

Description

public class UndoManager

UndoManager manages a list of UndoableEdits, providing a way to undo or redo the appropriate edits.

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^TM has been added to the java.beans package. Please see XMLEncoder.

See also:

Methods

Hide/Show inherited methods

publicsynchronized boolean addEdit (UndoableEdit anEdit) [Overrides CompoundEdit]

Adds an UndoableEdit to this UndoManager, if it's possible.

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.
Returns: true if anEdit can be incorporated into this edit
Parameters:
- anEdit - the edit to be added
See Also: CompoundEdit.end(), CompoundEdit.addEdit(javax.swing.undo.UndoableEdit),

publicsynchronized boolean canRedo () [Overrides CompoundEdit]

Returns true if edits may be redone.

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).
Returns: true if there are edits to be redone
See Also: CompoundEdit.canRedo(), UndoManager.editToBeRedone(),

publicsynchronized boolean canUndo () [Overrides CompoundEdit]

Returns true if edits may be undone.

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).
Returns: true if there are edits to be undone
See Also: CompoundEdit.canUndo(), UndoManager.editToBeUndone(),

publicsynchronized boolean canUndoOrRedo ()

Returns true if it is possible to invoke undo or redo.

Returns true if it is possible to invoke undo or
redo.
Returns: true if invoking canUndoOrRedo is valid
See Also: UndoManager.undoOrRedo(),

public void die () [Inherited From CompoundEdit]

Sends die to each subedit, in the reverse of the order that they were added.

publicsynchronized void discardAllEdits ()

Empties the undo manager sending each edit a die message in the process.

Empties the undo manager sending each edit a die message
in the process.
See Also: AbstractUndoableEdit.die(),

protected UndoableEdit editToBeRedone ()

Returns the the next significant edit to be redone if redo is invoked.

Returns the 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

protected UndoableEdit editToBeUndone ()

Returns the the next significant edit to be undone if undo is invoked.

Returns the 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

publicsynchronized void end () [Overrides CompoundEdit]

Turns this UndoManager into a normal CompoundEdit.

Turns this UndoManager into a normal
CompoundEdit. This removes all edits that have
been undone.
See Also: CompoundEdit.end(),

publicsynchronized int getLimit ()

Returns the maximum number of edits this UndoManager holds.

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 {@code UndoManager} holds
See Also: UndoManager.addEdit(javax.swing.undo.UndoableEdit), UndoManager.setLimit(int),

public String getPresentationName () [Inherited From CompoundEdit]

Returns getPresentationName from the last UndoableEdit added to edits.

Returns getPresentationName from the
last UndoableEdit added to
edits. If edits is empty,
calls super.

publicsynchronized String getRedoPresentationName () [Overrides CompoundEdit]

Returns a description of the redoable form of this edit.

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".
Returns: a description of the redoable form of this edit
See Also: UndoManager.redo(), CompoundEdit.getRedoPresentationName(),

publicsynchronized String getUndoOrRedoPresentationName ()

Convenience method that returns either getUndoPresentationName or getRedoPresentationName.

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

publicsynchronized String getUndoPresentationName () [Overrides CompoundEdit]

Returns a description of the undoable form of this edit.

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".
Returns: a description of the undoable form of this edit
See Also: UndoManager.undo(), CompoundEdit.getUndoPresentationName(),

public boolean isInProgress () [Inherited From CompoundEdit]

Returns true if this edit is in progress--that is, it has not received end.

public boolean isSignificant () [Inherited From CompoundEdit]

Returns true if any of the UndoableEdits in edits do.

Returns true if any of the UndoableEdits
in edits do.
Returns false if they all return false.

protected UndoableEdit lastEdit () [Inherited From CompoundEdit]

Returns the last UndoableEdit in edits, or null if edits is empty.

publicsynchronized void redo () throws CannotRedoException [Overrides CompoundEdit]

Redoes the appropriate edits.

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.
Throws:
- CannotRedoException - if one of the edits throws CannotRedoException or there are no edits to be redone
See Also: CompoundEdit.end(), UndoManager.canRedo(), UndoManager.editToBeRedone(),

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.

Redoes all changes from the index of the next edit to
edit, updating the index of the next edit appropriately.
Throws:
- CannotRedoException - if one of the edits throws CannotRedoException

public boolean replaceEdit (UndoableEdit anEdit) [Inherited From AbstractUndoableEdit]

This default implementation returns false.

publicsynchronized void setLimit (int l)

Sets the maximum number of edits this UndoManager holds.

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 this {@code UndoManager} is not in progress ({@code end} has been invoked)
See Also: CompoundEdit.isInProgress(), UndoManager.end(), UndoManager.addEdit(javax.swing.undo.UndoableEdit), UndoManager.getLimit(),

public String toString () [Overrides CompoundEdit]

Returns a string that displays and identifies this object's properties.

protected void trimEdits (int from, int to)

Removes edits in the specified range.

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

protected void trimForLimit ()

Reduces the number of queued edits to a range of size limit, centered on the index of the next edit.

publicsynchronized void undo () throws CannotUndoException [Overrides CompoundEdit]

Undoes the appropriate edits.

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.
Throws:
- CannotUndoException - if one of the edits throws CannotUndoException or there are no edits to be undone
See Also: CompoundEdit.end(), UndoManager.canUndo(), UndoManager.editToBeUndone(),

public void undoableEditHappened (UndoableEditEvent e) [Specified in UndoableEditListener]

An UndoableEditListener method.

An UndoableEditListener method. This invokes
addEdit with e.getEdit().
Parameters:
- e - the UndoableEditEvent the UndoableEditEvent will be added from
See Also: UndoManager.addEdit(javax.swing.undo.UndoableEdit),

publicsynchronized void undoOrRedo () throws CannotRedoException CannotUndoException

Convenience method that invokes one of undo or redo.

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 throws CannotUndoException
- CannotRedoException - if one of the edits throws CannotRedoException
See Also: UndoManager.canUndoOrRedo(), UndoManager.getUndoOrRedoPresentationName(),

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.

Undoes all changes from the index of the next edit to
edit, updating the index of the next edit appropriately.
Throws:
- CannotUndoException - if one of the edits throws CannotUndoException