UndoManager (Java Platform SE 8 )
Keywords: javax.swing.undo.UndoManager class
Date: 2015-11-19

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

  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 inherited from class javax.swing.undo.CompoundEdit

      `edits`

    - ### Fields inherited from class javax.swing.undo.AbstractUndoableEdit

      `RedoName, UndoName`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `UndoManager()` Creates a new `UndoManager`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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 the next significant edit to be redone if `redo` is invoked.
    `protected UndoableEdit` | `editToBeUndone()` Returns the 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 inherited from class javax.swing.undo.CompoundEdit

      `die, getPresentationName, isInProgress, isSignificant, lastEdit`

    - ### Methods inherited from class javax.swing.undo.AbstractUndoableEdit

      `replaceEdit`

    - ### Methods inherited from 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 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 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 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.
      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.
      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

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2015, Oracle and/or its affiliates. All rights reserved.