javax.swing.undo
Class UndoManager

java.lang.Object
  extended by javax.swing.undo.AbstractUndoableEdit
      extended by javax.swing.undo.CompoundEdit
          extended by javax.swing.undo.UndoManager
All Implemented Interfaces:
Serializable, EventListener, UndoableEditListener, UndoableEdit

public class UndoManager
extends CompoundEdit
implements UndoableEditListener

A manager for providing an application’s undo/redo functionality.

Tyipcally, an application will create only one single instance of UndoManager. When the user performs an undoable action, for instance changing the color of an object from green to blue, the application registers an UndoableEdit object with the UndoManager. To implement the “undo” and “redo” menu commands, the application invokes the UndoManager’s undo() and redo() methods. The human-readable text of these menu commands is provided by getUndoPresentationName() and getRedoPresentationName(), respectively. To determine whether the menu item should be selectable or greyed out, use canUndo() and canRedo().

The UndoManager will only keep a specified number of editing actions, the limit. The value of this parameter can be retrieved by calling getLimit() and set with setLimit(int). If more UndoableEdits are added to the UndoManager, the oldest actions will be discarded.

Some applications do not provide separate menu commands for “undo” and “redo.” Instead, they have just a single command whose text switches between the two. Such applications would use an UndoManager with a limit of 1. The text of this combined menu item is available via getUndoOrRedoPresentationName(), and it is implemented by calling undoOrRedo().

Thread Safety: In constrast to the other classes of the javax.swing.undo package, the public methods of an UndoManager are safe to call from concurrent threads. The caller does not need to perform external synchronization, and UndoableEditEvent sources do not need to broadcast their events from inside the Swing worker thread.

See Also:
Serialized Form

Field Summary
 
Fields inherited from class javax.swing.undo.CompoundEdit
edits
 
Fields inherited from class javax.swing.undo.AbstractUndoableEdit
RedoName, UndoName
 
Constructor Summary
UndoManager()
          Constructs an UndoManager.
 
Method Summary
 boolean addEdit(UndoableEdit edit)
          Registers an undoable editing action with this UndoManager.
 boolean canRedo()
          Determines whether it would be possible to redo this editing action.
 boolean canUndo()
          Determines whether it would be possible to undo this editing action.
 boolean canUndoOrRedo()
          Determines whether it would be possible to either undo or redo this editing action.
 void discardAllEdits()
          Discards all editing actions that are currently registered with this UndoManager.
protected  UndoableEdit editToBeRedone()
          Determines which significant edit would be redone if redo() was called.
protected  UndoableEdit editToBeUndone()
          Determines which significant edit would be undone if undo() was called.
 void end()
          Puts this UndoManager into a state where it acts as a normal CompoundEdit.
 int getLimit()
          Returns how many edits this UndoManager can maximally hold.
 String getRedoPresentationName()
          Calculates a localized text for presenting the redo action to the user, for example in the form of a menu command.
 String getUndoOrRedoPresentationName()
          Calculates a localized text for presenting the undo or redo action to the user, for example in the form of a menu command.
 String getUndoPresentationName()
          Calculates a localized text for presenting the undo action to the user, for example in the form of a menu command.
 void redo()
          Redoes one significant edit action.
protected  void redoTo(UndoableEdit edit)
          Redoes all editing actions in the same order as they were added to this UndoManager, up to the specified action.
 void setLimit(int limit)
          Changes the maximal number of edits that this UndoManager can process.
 String toString()
          Returns a string representation for this UndoManager.
protected  void trimEdits(int from, int to)
          Discards a range of edits.
protected  void trimForLimit()
          Called by various internal methods in order to enforce the limit value.
 void undo()
          Undoes one significant edit action.
 void undoableEditHappened(UndoableEditEvent event)
          Registers the edit action of an UndoableEditEvent with this UndoManager.
 void undoOrRedo()
          Undoes or redoes the last action.
protected  void undoTo(UndoableEdit edit)
          Undoes all editing actions in reverse order of addition, up to the specified action,
 
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()
Constructs an UndoManager.

The limit of the freshly constructed UndoManager is 100.

Method Detail

toString

public String toString()
Returns a string representation for this UndoManager. This may be useful for debugging purposes. For the text of menu items, please refer to getUndoPresentationName(), getRedoPresentationName(), and getUndoOrRedoPresentationName().

Overrides:
toString in class CompoundEdit
Returns:
the String representing this Object, which may be null
See Also:
Object.getClass(), Object.hashCode(), Class.getName(), Integer.toHexString(int)

end

public void end()
Puts this UndoManager into a state where it acts as a normal CompoundEdit. It is unlikely that an application would want to do this.

Overrides:
end in class CompoundEdit

getLimit

public int getLimit()
Returns how many edits this UndoManager can maximally hold.

See Also:
setLimit(int)

setLimit

public void setLimit(int limit)
Changes the maximal number of edits that this UndoManager can process. If there are currently more edits than the new limit allows, they will receive a die message in reverse order of addition.

Parameters:
limit - the new limit.
Throws:
IllegalStateException - if end() has already been called on this UndoManager.

discardAllEdits

public void discardAllEdits()
Discards all editing actions that are currently registered with this UndoManager. Each UndoableEdit will receive a die message.


trimForLimit

protected void trimForLimit()
Called by various internal methods in order to enforce the limit value.


trimEdits

protected void trimEdits(int from,
                         int to)
Discards a range of edits. All edits in the range [from .. to] will receive a die message before being removed from the edits array. If from is greater than to, nothing happens.

Parameters:
from - the lower bound of the range of edits to be discarded.
to - the upper bound of the range of edits to be discarded.

editToBeUndone

protected UndoableEdit editToBeUndone()
Determines which significant edit would be undone if undo() was called.

Returns:
the significant edit that would be undone, or null if no significant edit would be affected by calling undo().

editToBeRedone

protected UndoableEdit editToBeRedone()
Determines which significant edit would be redone if redo() was called.

Returns:
the significant edit that would be redone, or null if no significant edit would be affected by calling redo().

undoTo

protected void undoTo(UndoableEdit edit)
               throws CannotUndoException
Undoes all editing actions in reverse order of addition, up to the specified action,

Parameters:
edit - the last editing action to be undone.
Throws:
CannotUndoException

redoTo

protected void redoTo(UndoableEdit edit)
               throws CannotRedoException
Redoes all editing actions in the same order as they were added to this UndoManager, up to the specified action.

Parameters:
edit - the last editing action to be redone.
Throws:
CannotRedoException

undoOrRedo

public void undoOrRedo()
                throws CannotRedoException,
                       CannotUndoException
Undoes or redoes the last action. If the last action has already been undone, it will be re-done, and vice versa.

This is useful for applications that do not present a separate undo and redo facility, but just have a single menu item for undoing and redoing the very last action. Such applications will use an UndoManager whose limit is 1.

Throws:
CannotRedoException
CannotUndoException

canUndoOrRedo

public boolean canUndoOrRedo()
Determines whether it would be possible to either undo or redo this editing action.

This is useful for applications that do not present a separate undo and redo facility, but just have a single menu item for undoing and redoing the very last action. Such applications will use an UndoManager whose limit is 1.

Returns:
true to indicate that this action can be undone or redone; false if neither is possible at the current time.

undo

public void undo()
          throws CannotUndoException
Undoes one significant edit action. If insignificant actions have been posted after the last signficant action, the insignificant ones will be undone first.

However, if end() has been called on this UndoManager, it will behave like a normal CompoundEdit. In this case, all actions will be undone in reverse order of addition. Typical applications will never call end() on their UndoManager.

Specified by:
undo in interface UndoableEdit
Overrides:
undo in class CompoundEdit
Throws:
CannotUndoException - if no action can be undone.
See Also:
canUndo(), redo(), undoOrRedo()

canUndo

public boolean canUndo()
Determines whether it would be possible to undo this editing action.

Specified by:
canUndo in interface UndoableEdit
Overrides:
canUndo in class CompoundEdit
Returns:
true to indicate that this action can be undone; false otherwise.
See Also:
undo(), canRedo(), canUndoOrRedo()

redo

public void redo()
          throws CannotRedoException
Redoes one significant edit action. If insignificant actions have been posted in between, the insignificant ones will be redone first.

However, if end() has been called on this UndoManager, it will behave like a normal CompoundEdit. In this case, all actions will be redone in order of addition. Typical applications will never call end() on their UndoManager.

Specified by:
redo in interface UndoableEdit
Overrides:
redo in class CompoundEdit
Throws:
CannotRedoException - if no action can be redone.
See Also:
canRedo(), redo(), undoOrRedo()

canRedo

public boolean canRedo()
Determines whether it would be possible to redo this editing action.

Specified by:
canRedo in interface UndoableEdit
Overrides:
canRedo in class CompoundEdit
Returns:
true to indicate that this action can be redone; false otherwise.
See Also:
redo(), canUndo(), canUndoOrRedo()

addEdit

public boolean addEdit(UndoableEdit edit)
Registers an undoable editing action with this UndoManager. If the capacity limit is reached, the oldest action will be discarded (and receives a die message. Equally, any actions that were undone (but not re-done) will be discarded, too.

Specified by:
addEdit in interface UndoableEdit
Overrides:
addEdit in class CompoundEdit
Parameters:
edit - the editing action that is added to this UndoManager.
Returns:
true if edit could be incorporated; false if edit has not been incorporated because end() has already been called on this UndoManager.

getUndoOrRedoPresentationName

public String getUndoOrRedoPresentationName()
Calculates a localized text for presenting the undo or redo action to the user, for example in the form of a menu command.

This is useful for applications that do not present a separate undo and redo facility, but just have a single menu item for undoing and redoing the very last action. Such applications will use an UndoManager whose limit is 1.

Returns:
the redo presentation name if the last action has already been undone, or the undo presentation name otherwise.
See Also:
getUndoPresentationName(), getRedoPresentationName()

getUndoPresentationName

public String getUndoPresentationName()
Calculates a localized text for presenting the undo action to the user, for example in the form of a menu command.

Specified by:
getUndoPresentationName in interface UndoableEdit
Overrides:
getUndoPresentationName in class CompoundEdit
Returns:
The undo presentation name.

getRedoPresentationName

public String getRedoPresentationName()
Calculates a localized text for presenting the redo action to the user, for example in the form of a menu command.

Specified by:
getRedoPresentationName in interface UndoableEdit
Overrides:
getRedoPresentationName in class CompoundEdit
Returns:
The redo presentation name.

undoableEditHappened

public void undoableEditHappened(UndoableEditEvent event)
Registers the edit action of an UndoableEditEvent with this UndoManager.

Thread Safety: This method may safely be invoked from concurrent threads. The caller does not need to perform external synchronization. This means that UndoableEditEvent sources do not need to broadcast their events from inside the Swing worker thread.

Specified by:
undoableEditHappened in interface UndoableEditListener
Parameters:
event - the event whose edit will be passed to addEdit(javax.swing.undo.UndoableEdit).
See Also:
UndoableEditEvent.getEdit(), addEdit(javax.swing.undo.UndoableEdit)