OpenJDK 1.23 · javax.swing.undo.UndoManager · APIdia, the JavaDoc alternative

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

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

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

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

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 java.beans.XMLEncoder.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static enum	UndoManager.Action

Field Summary

Modifier and Type	Field and Description
pack-priv int	indexOfNextAdd
pack-priv int	limit

Inherited from javax.swing.undo.CompoundEdit:: edits inProgress

Constructor Summary

Access	Constructor and Description
public	UndoManager() Creates a new `UndoManager`.

Method Summary

Modifier and Type	Method and Description
public synchronized boolean	Returns: true if `anEdit` can be incorporated into this edit addEdit(UndoableEdit the edit to be added anEdit) Overrides javax.swing.undo.CompoundEdit.addEdit. Implements javax.swing.undo.UndoableEdit.addEdit. Adds an `UndoableEdit` to this `UndoManager`, if it's possible.
public synchronized boolean	Returns: true if there are edits to be redone canRedo() Overrides javax.swing.undo.CompoundEdit.canRedo. Implements javax.swing.undo.UndoableEdit.canRedo. Returns true if edits may be redone.
public synchronized boolean	Returns: true if there are edits to be undone canUndo() Overrides javax.swing.undo.CompoundEdit.canUndo. Implements javax.swing.undo.UndoableEdit.canUndo. Returns true if edits may be undone.
public synchronized boolean	Returns: true if invoking `canUndoOrRedo` is valid canUndoOrRedo() Returns true if it is possible to invoke `undo` or `redo`.
public synchronized void	discardAllEdits() Empties the undo manager sending each edit a `die` message in the process.
protected UndoableEdit	Returns: the next significant edit to be redone editToBeRedone() Returns the next significant edit to be redone if `redo` is invoked.
protected UndoableEdit	Returns: the next significant edit to be undone editToBeUndone() Returns the next significant edit to be undone if `undo` is invoked.
public synchronized void	end() Overrides javax.swing.undo.CompoundEdit.end. Turns this `UndoManager` into a normal `CompoundEdit`.
private UndoableEditLockSupport	getEditLockSupport(UndoableEdit anEdit)
public synchronized int	Returns: the maximum number of edits this `UndoManager` holds getLimit() Returns the maximum number of edits this `UndoManager` holds.
public synchronized String	Returns: a description of the redoable form of this edit getRedoPresentationName() Overrides javax.swing.undo.CompoundEdit.getRedoPresentationName. Implements javax.swing.undo.UndoableEdit.getRedoPresentationName. Returns a description of the redoable form of this edit.
public synchronized String	Returns: undo or redo name getUndoOrRedoPresentationName() Convenience method that returns either `getUndoPresentationName` or `getRedoPresentationName`.
public synchronized String	Returns: a description of the undoable form of this edit getUndoPresentationName() Overrides javax.swing.undo.CompoundEdit.getUndoPresentationName. Implements javax.swing.undo.UndoableEdit.getUndoPresentationName. Returns a description of the undoable form of this edit.
public void	redo() Overrides javax.swing.undo.CompoundEdit.redo. Implements javax.swing.undo.UndoableEdit.redo. Redoes the appropriate edits.
protected void	redoTo(UndoableEdit the edit to be redo to edit) Redoes all changes from the index of the next edit to `edit`, updating the index of the next edit appropriately.
public synchronized void	setLimit(int the new limit l) Sets the maximum number of edits this `UndoManager` holds.
public String	Returns: a String representation of this object toString() Overrides javax.swing.undo.CompoundEdit.toString. Returns a string that displays and identifies this object's properties.
protected void	trimEdits(int the minimum index to remove from, int the maximum index to remove 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.
private void	tryUndoOrRedo(UndoManager.Action action)
public void	undo() Overrides javax.swing.undo.CompoundEdit.undo. Implements javax.swing.undo.UndoableEdit.undo. Undoes the appropriate edits.
public void	undoableEditHappened(UndoableEditEvent the `UndoableEditEvent` the `UndoableEditEvent` will be added from e) Implements javax.swing.event.UndoableEditListener.undoableEditHappened. An `UndoableEditListener` method.
public void	undoOrRedo() Convenience method that invokes one of `undo` or `redo`.
protected void	undoTo(UndoableEdit the edit to be undo to edit) Undoes all changes from the index of the next edit to `edit`, updating the index of the next edit appropriately.

Inherited from javax.swing.undo.CompoundEdit:: die getPresentationName isInProgress isSignificant lastEdit

Field Detail

indexOfNextAdd	back to summary
pack-priv int indexOfNextAdd

limit	back to summary
pack-priv int limit

Constructor Detail

UndoManager	back to summary
public UndoManager() Creates a new `UndoManager`.

Method Detail

addEdit back to summary

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

public synchronized boolean addEdit(UndoableEdit anEdit)

Overrides javax.swing.undo.CompoundEdit.addEdit.

Implements javax.swing.undo.UndoableEdit.addEdit.

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.

Parameters

anEdit:UndoableEdit: the edit to be added

Returns:boolean

true if anEdit can be incorporated into this edit

canRedo back to summary

canRedo	back to summary
public synchronized boolean canRedo() Overrides javax.swing.undo.CompoundEdit.canRedo. Implements javax.swing.undo.UndoableEdit.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`). Returns:boolean true if there are edits to be redone See Also `CompoundEdit#canRedo`, `editToBeRedone`

public synchronized boolean canRedo()

Overrides javax.swing.undo.CompoundEdit.canRedo.

Implements javax.swing.undo.UndoableEdit.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).

Returns:boolean: true if there are edits to be redone
See Also: CompoundEdit#canRedo, editToBeRedone

canUndo back to summary

canUndo	back to summary
public synchronized boolean canUndo() Overrides javax.swing.undo.CompoundEdit.canUndo. Implements javax.swing.undo.UndoableEdit.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`). Returns:boolean true if there are edits to be undone See Also `CompoundEdit#canUndo`, `editToBeUndone`

public synchronized boolean canUndo()

Overrides javax.swing.undo.CompoundEdit.canUndo.

Implements javax.swing.undo.UndoableEdit.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).

Returns:boolean: true if there are edits to be undone
See Also: CompoundEdit#canUndo, editToBeUndone

canUndoOrRedo back to summary

canUndoOrRedo	back to summary
public synchronized boolean canUndoOrRedo() Returns true if it is possible to invoke `undo` or `redo`. Returns:boolean true if invoking `canUndoOrRedo` is valid See Also `undoOrRedo`

public synchronized boolean canUndoOrRedo()

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

Returns:boolean: true if invoking canUndoOrRedo is valid
See Also: undoOrRedo

discardAllEdits back to summary

discardAllEdits	back to summary
public synchronized void discardAllEdits() Empties the undo manager sending each edit a `die` message in the process. See Also `AbstractUndoableEdit#die`

public synchronized void discardAllEdits()

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

See Also: AbstractUndoableEdit#die

editToBeRedone back to summary

editToBeRedone	back to summary
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:UndoableEdit the next significant edit to be redone

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:UndoableEdit: the next significant edit to be redone

editToBeUndone back to summary

editToBeUndone	back to summary
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:UndoableEdit the next significant edit to be undone

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:UndoableEdit: the next significant edit to be undone

end back to summary

end	back to summary
public synchronized void end() Overrides javax.swing.undo.CompoundEdit.end. Turns this `UndoManager` into a normal `CompoundEdit`. This removes all edits that have been undone. See Also `CompoundEdit#end`

public synchronized void end()

Overrides javax.swing.undo.CompoundEdit.end.

Turns this UndoManager into a normal CompoundEdit. This removes all edits that have been undone.

See Also: CompoundEdit#end

getEditLockSupport	back to summary
private UndoableEditLockSupport getEditLockSupport(UndoableEdit anEdit)

getLimit back to summary

getLimit	back to summary
public synchronized 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:int the maximum number of edits this `UndoManager` holds See Also `addEdit`, `setLimit`

public synchronized 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:int: the maximum number of edits this UndoManager holds
See Also: addEdit, setLimit

getRedoPresentationName back to summary

getRedoPresentationName	back to summary
public synchronized String getRedoPresentationName() Overrides javax.swing.undo.CompoundEdit.getRedoPresentationName. Implements javax.swing.undo.UndoableEdit.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". Returns:String a description of the redoable form of this edit See Also `redo`, `CompoundEdit#getRedoPresentationName`

public synchronized String getRedoPresentationName()

Overrides javax.swing.undo.CompoundEdit.getRedoPresentationName.

Implements javax.swing.undo.UndoableEdit.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".

Returns:String: a description of the redoable form of this edit
See Also: redo, CompoundEdit#getRedoPresentationName

getUndoOrRedoPresentationName back to summary

getUndoOrRedoPresentationName	back to summary
public synchronized 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:String undo or redo name

public synchronized 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:String: undo or redo name

getUndoPresentationName back to summary

getUndoPresentationName	back to summary
public synchronized String getUndoPresentationName() Overrides javax.swing.undo.CompoundEdit.getUndoPresentationName. Implements javax.swing.undo.UndoableEdit.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". Returns:String a description of the undoable form of this edit See Also `undo`, `CompoundEdit#getUndoPresentationName`

public synchronized String getUndoPresentationName()

Overrides javax.swing.undo.CompoundEdit.getUndoPresentationName.

Implements javax.swing.undo.UndoableEdit.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".

Returns:String: a description of the undoable form of this edit
See Also: undo, CompoundEdit#getUndoPresentationName

redo back to summary

redo	back to summary
public void redo() throws CannotRedoException Overrides javax.swing.undo.CompoundEdit.redo. Implements javax.swing.undo.UndoableEdit.redo. 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. Exceptions CannotRedoException: if one of the edits throws `CannotRedoException` or there are no edits to be redone See Also `CompoundEdit#end`, `canRedo`, `editToBeRedone`

public void redo() throws CannotRedoException

Overrides javax.swing.undo.CompoundEdit.redo.

Implements javax.swing.undo.UndoableEdit.redo.

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.

Exceptions

CannotRedoException:: if one of the edits throws CannotRedoException or there are no edits to be redone

redoTo back to summary

redoTo	back to summary
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:UndoableEdit the edit to be redo to Exceptions CannotRedoException: if one of the edits throws `CannotRedoException`

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:UndoableEdit: the edit to be redo to

Exceptions

CannotRedoException:: if one of the edits throws CannotRedoException

setLimit back to summary

setLimit	back to summary
public synchronized 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:int the new limit Exceptions RuntimeException: if this `UndoManager` is not in progress (`end` has been invoked) See Also `isInProgress`, `end`, `addEdit`, `getLimit`

public synchronized 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:int: the new limit

Exceptions

RuntimeException:: if this UndoManager is not in progress (end has been invoked)

See Also

isInProgress, end, addEdit, getLimit

toString	back to summary
public String toString() Overrides javax.swing.undo.CompoundEdit.toString. Returns a string that displays and identifies this object's properties. Returns:String a String representation of this object

toString

back to summary

public String toString()

Overrides javax.swing.undo.CompoundEdit.toString.

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

Returns:String: a String representation of this object

trimEdits back to summary

trimEdits	back to summary
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:int the minimum index to remove to:int the maximum index to remove

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:int: the minimum index to remove
to:int: the maximum index to remove

trimForLimit	back to summary
protected void trimForLimit() Reduces the number of queued edits to a range of size limit, centered on the index of the next edit.

tryUndoOrRedo	back to summary
private void tryUndoOrRedo(UndoManager.Action action)

undo back to summary

undo	back to summary
public void undo() throws CannotUndoException Overrides javax.swing.undo.CompoundEdit.undo. Implements javax.swing.undo.UndoableEdit.undo. 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. Exceptions CannotUndoException: if one of the edits throws `CannotUndoException` or there are no edits to be undone See Also `CompoundEdit#end`, `canUndo`, `editToBeUndone`

public void undo() throws CannotUndoException

Overrides javax.swing.undo.CompoundEdit.undo.

Implements javax.swing.undo.UndoableEdit.undo.

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.

Exceptions

CannotUndoException:: if one of the edits throws CannotUndoException or there are no edits to be undone

undoableEditHappened back to summary

undoableEditHappened	back to summary
public void undoableEditHappened(UndoableEditEvent e) Implements javax.swing.event.UndoableEditListener.undoableEditHappened. An `UndoableEditListener` method. This invokes `addEdit` with `e.getEdit()`. Parameters e:UndoableEditEvent the `UndoableEditEvent` the `UndoableEditEvent` will be added from See Also `addEdit`

public void undoableEditHappened(UndoableEditEvent e)

Implements javax.swing.event.UndoableEditListener.undoableEditHappened.

An UndoableEditListener method. This invokes addEdit with e.getEdit().

Parameters

e:UndoableEditEvent: the UndoableEditEvent the UndoableEditEvent will be added from

See Also

addEdit

undoOrRedo back to summary

undoOrRedo	back to summary
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`. Exceptions CannotRedoException: if one of the edits throws `CannotRedoException` CannotUndoException: if one of the edits throws `CannotUndoException` See Also `canUndoOrRedo`, `getUndoOrRedoPresentationName`

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.

Exceptions

CannotRedoException:: if one of the edits throws CannotRedoException
CannotUndoException:: if one of the edits throws CannotUndoException

undoTo back to summary

undoTo	back to summary
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:UndoableEdit the edit to be undo to Exceptions CannotUndoException: if one of the edits throws `CannotUndoException`

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:UndoableEdit: the edit to be undo to

Exceptions

CannotUndoException:: if one of the edits throws CannotUndoException

Modifier and Type	Field and Description
public static final UndoManager.Action	ANY
public static final UndoManager.Action	REDO
public static final UndoManager.Action	UNDO

Modifier and Type	Method and Description
public static UndoManager.Action	valueOf(String name)
public static UndoManager.Action[]	values()

public Class UndoManager

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Enum UndoManager.Action

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail