Module java.desktop
Package javax.swing.undo

# 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
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 `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
Constructor
Description
`UndoManager()`
Creates a new `UndoManager`.

## Method Summary

Modifier and Type
Method
Description
`boolean`
`addEdit(UndoableEdit anEdit)`
Adds an `UndoableEdit` to this `UndoManager`, if it's possible.
`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 `undo` or `redo`.
`void`
`discardAllEdits()`
Empties the undo manager sending each edit a `die` message in the process.
`protected UndoableEdit`
`editToBeRedone()`
Returns the next significant edit to be redone if `redo` is invoked.
`protected UndoableEdit`
`editToBeUndone()`
Returns the next significant edit to be undone if `undo` is invoked.
`void`
`end()`
Turns this `UndoManager` into a normal `CompoundEdit`.
`int`
`getLimit()`
Returns the maximum number of edits this `UndoManager` holds.
`String`
`getRedoPresentationName()`
Returns a description of the redoable form of this edit.
`String`
`getUndoOrRedoPresentationName()`
Convenience method that returns either `getUndoPresentationName` or `getRedoPresentationName`.
`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 `edit`, updating the index of the next edit appropriately.
`void`
`setLimit(int l)`
Sets the maximum number of edits this `UndoManager` holds.
`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 `UndoableEditListener` method.
`void`
`undoOrRedo()`
Convenience method that invokes one of `undo` or `redo`.
`protected void`
`undoTo(UndoableEdit edit)`
Undoes all changes from the index of the next edit to `edit`, 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`

### Methods declared in class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

## Constructor Details

### UndoManager

public UndoManager()
Creates a new `UndoManager`.

## Method Details

### 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 this `UndoManager` 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 throws `CannotUndoException`

### 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 throws `CannotRedoException`

### 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 throws `CannotUndoException`
  `CannotRedoException` - if one of the edits throws `CannotRedoException`
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 interface `UndoableEdit`
Overrides:
  `undo` in class `CompoundEdit`
Throws:
  `CannotUndoException` - if one of the edits throws `CannotUndoException` 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 interface `UndoableEdit`
Overrides:
  `canUndo` in class `CompoundEdit`
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 interface `UndoableEdit`
Overrides:
  `redo` in class `CompoundEdit`
Throws:
  `CannotRedoException` - if one of the edits throws `CannotRedoException` 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 interface `UndoableEdit`
Overrides:
  `canRedo` in class `CompoundEdit`
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 interface `UndoableEdit`
Overrides:
  `addEdit` in class `CompoundEdit`
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 class `CompoundEdit`
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 interface `UndoableEdit`
Overrides:
  `getUndoPresentationName` in class `CompoundEdit`
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 interface `UndoableEdit`
Overrides:
  `getRedoPresentationName` in class `CompoundEdit`
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 interface `UndoableEditListener`
Parameters:
  `e` - the `UndoableEditEvent` the `UndoableEditEvent` 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 class `CompoundEdit`
Returns:
  a String representation of this object