javax.swing.undo

Class UndoManager

Implemented Interfaces:
EventListener, Serializable, UndoableEdit, UndoableEditListener

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
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,
void
undoableEditHappened(UndoableEditEvent event)
Registers the edit action of an UndoableEditEvent with this UndoManager.

Methods inherited from class javax.swing.undo.CompoundEdit

addEdit, canRedo, canUndo, die, end, getPresentationName, getRedoPresentationName, getUndoPresentationName, isInProgress, isSignificant, lastEdit, redo, toString, undo

Methods inherited from class javax.swing.undo.AbstractUndoableEdit

addEdit, canRedo, canUndo, die, getPresentationName, getRedoPresentationName, getUndoPresentationName, isSignificant, redo, replaceEdit, toString, undo

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

UndoManager

public UndoManager()
Constructs an UndoManager.

The limit of the freshly constructed UndoManager is 100.

Method Details

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 interface 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.

canRedo

public boolean canRedo()
Determines whether it would be possible to redo this editing action.
Specified by:
canRedo in interface UndoableEdit
Overrides:
canRedo in interface CompoundEdit
Returns:
true to indicate that this action can be redone; false otherwise.

canUndo

public boolean canUndo()
Determines whether it would be possible to undo this editing action.
Specified by:
canUndo in interface UndoableEdit
Overrides:
canUndo in interface CompoundEdit
Returns:
true to indicate that this action can be undone; false otherwise.

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.

discardAllEdits

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

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().

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().

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 interface CompoundEdit

getLimit

public int getLimit()
Returns how many edits this UndoManager can maximally hold.
See Also:
setLimit(int)

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 interface CompoundEdit

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.

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 interface CompoundEdit

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 interface CompoundEdit
Throws:
CannotRedoException - if no action can be redone.

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.

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.

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 interface CompoundEdit

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.

trimForLimit

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

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 interface CompoundEdit
Throws:
CannotUndoException - if no action can be undone.

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.


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.

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(UndoableEdit).

UndoManager.java -- Copyright (C) 2002, 2004, 2005, 2006, Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.