- All Known Implementing Classes:
AbstractDocument.DefaultDocumentEvent,AbstractDocument.ElementEdit,AbstractUndoableEdit,CompoundEdit,DefaultStyledDocument.AttributeUndoableEdit,StateEdit,UndoManager
UndoableEdit represents an edit. The edit may
be undone, or if already undone the edit may be redone.
UndoableEdit is designed to be used with the
UndoManager. As UndoableEdits are generated
by an UndoableEditListener they are typically added to
the UndoManager. When an UndoableEdit
is added to an UndoManager the following occurs (assuming
end has not been called on the UndoManager):
- If the
UndoManagercontains edits it will calladdEditon the current edit passing in the new edit as the argument. IfaddEditreturns true the new edit is assumed to have been incorporated into the current edit and the new edit will not be added to the list of current edits. Edits can useaddEditas a way for smaller edits to be incorporated into a larger edit and treated as a single edit. - If
addEditreturns falsereplaceEditis called on the new edit with the current edit passed in as the argument. This is the inverse ofaddEdit— if the new edit returns true fromreplaceEdit, the new edit replaces the current edit.
UndoManager makes use of
isSignificant to determine how many edits should be
undone or redone. The UndoManager will undo or redo
all insignificant edits (isSignificant returns false)
between the current edit and the last or
next significant edit. addEdit and
replaceEdit can be used to treat multiple edits as
a single edit, returning false from isSignificant
allows for treating can be used to
have many smaller edits undone or redone at once. Similar functionality
can also be done using the addEdit method.-
Method Summary
Modifier and TypeMethodDescriptionbooleanaddEdit(UndoableEdit anEdit) Adds anUndoableEditto thisUndoableEdit.booleancanRedo()Returns true if this edit may be redone.booleancanUndo()Returns true if this edit may be undone.voiddie()Informs the edit that it should no longer be used.Returns a localized, human-readable description of this edit, suitable for use in a change log, for example.Returns a localized, human-readable description of the redoable form of this edit, suitable for use as a Redo menu item, for example.Returns a localized, human-readable description of the undoable form of this edit, suitable for use as an Undo menu item, for example.booleanReturns true if this edit is considered significant.voidredo()Re-applies the edit.booleanreplaceEdit(UndoableEdit anEdit) Returns true if thisUndoableEditshould replaceanEdit.voidundo()Undo the edit.
-
Method Details
-
undo
Undo the edit.- Throws:
CannotUndoException- if this edit can not be undone
-
canUndo
boolean canUndo()Returns true if this edit may be undone.- Returns:
- true if this edit may be undone
-
redo
Re-applies the edit.- Throws:
CannotRedoException- if this edit can not be redone
-
canRedo
boolean canRedo()Returns true if this edit may be redone.- Returns:
- true if this edit may be redone
-
die
void die()Informs the edit that it should no longer be used. Once anUndoableEdithas been marked as dead it can no longer be undone or redone.This is a useful hook for cleaning up state no longer needed once undoing or redoing is impossible--for example, deleting file resources used by objects that can no longer be undeleted.
UndoManagercalls this before it dequeues edits.Note that this is a one-way operation. There is no "un-die" method.
- See Also:
-
addEdit
Adds anUndoableEditto thisUndoableEdit. This method can be used to coalesce smaller edits into a larger compound edit. For example, text editors typically allow undo operations to apply to words or sentences. The text editor may choose to generate edits on each key event, but allow those edits to be coalesced into a more user-friendly unit, such as a word. In this case, theUndoableEditwould overrideaddEditto return true when the edits may be coalesced.A return value of true indicates
anEditwas incorporated into this edit. A return value of false indicatesanEditmay not be incorporated into this edit.Typically the receiver is already in the queue of a
UndoManager(or otherUndoableEditListener), and is being given a chance to incorporateanEditrather than letting it be added to the queue in turn.If true is returned, from now on
anEditmust return false fromcanUndoandcanRedo, and must throw the appropriate exception onundoorredo.- Parameters:
anEdit- the edit to be added- Returns:
- true if
anEditmay be incorporated into this edit
-
replaceEdit
Returns true if thisUndoableEditshould replaceanEdit. This method is used byCompoundEditand theUndoManager; it is called ifanEditcould not be added to the current edit (addEditreturns false).This method provides a way for an edit to replace an existing edit.
This message is the opposite of addEdit--anEdit has typically already been queued in an
UndoManager(or other UndoableEditListener), and the receiver is being given a chance to take its place.If true is returned, from now on anEdit must return false from canUndo() and canRedo(), and must throw the appropriate exception on undo() or redo().
- Parameters:
anEdit- the edit that replaces the current edit- Returns:
- true if this edit should replace
anEdit
-
isSignificant
boolean isSignificant()Returns true if this edit is considered significant. A significant edit is typically an edit that should be presented to the user, perhaps on a menu item or tooltip. TheUndoManagerwill undo, or redo, all insignificant edits to the next significant edit.- Returns:
- true if this edit is significant
-
getPresentationName
String getPresentationName()Returns a localized, human-readable description of this edit, suitable for use in a change log, for example.- Returns:
- description of this edit
-
getUndoPresentationName
String getUndoPresentationName()Returns a localized, human-readable description of the undoable form of this edit, suitable for use as an Undo menu item, for example. This is typically derived fromgetPresentationName.- Returns:
- a description of the undoable form of this edit
-
getRedoPresentationName
String getRedoPresentationName()Returns a localized, human-readable description of the redoable form of this edit, suitable for use as a Redo menu item, for example. This is typically derived fromgetPresentationName.- Returns:
- a description of the redoable form of this edit
-