javax.swing.undo
Interface UndoableEdit

All Known Implementing Classes:

AbstractDocument.DefaultDocumentEvent , AbstractDocument.ElementEdit , AbstractUndoableEdit , CompoundEdit , DefaultStyledDocument.AttributeUndoableEdit , StateEdit , UndoManager

public interface UndoableEdit

An UndoableEdit represents an edit. The edit may be undone, or if already undone the edit may be redone. An object representing an edit that has been done, and that can be undone and 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):

1. If the UndoManager contains edits it will call addEdit on the current edit passing in the new edit as the argument. If addEdit returns 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 use addEdit as a way for smaller edits to be incorporated into a larger edit and treated as a single edit.
2. If addEdit returns false replaceEdit is called on the new edit with the current edit passed in as the argument. This is the inverse of addEdit — if the new edit returns true from replaceEdit, the new edit replaces the current edit.

Method Summary
boolean	addEdit ( UndoableEdit           Adds an           This UndoableEdit to this UndoableEdit. should absorb anEdit if it can.
boolean	canRedo ()           Returns true           True if it is still possible to redo this edit may be redone. operation.
boolean	canUndo ()           Returns true           True if it is still possible to undo this edit may be undone. operation.
void	die ()           Informs the           May be sent to inform an edit that it should no longer be used.
String	getPresentationName ()           Returns           Provides a localized, human-readable human readable description of this edit, edit suitable for use in in, say, a change log, for example. log.
String	getRedoPresentationName ()           Returns           Provides a localized, human-readable human readable description of the redoable form of this edit, suitable for use as a Redo menu item, for example. e.g.
String	getUndoPresentationName ()           Returns           Provides a localized, human-readable human readable description of the undoable form of this edit, suitable for use as an Undo menu item, for example. e.g.
boolean	isSignificant ()           Returns true false if this edit is considered significant. insignificant--for example one that maintains the user's selection, but does not change any model state.
void	redo ()           Re-applies           Re-apply the edit. edit, assuming that it has been undone.
boolean	replaceEdit ( UndoableEdit  anEdit)           Returns true if this UndoableEdit should replace anEdit.
void	undo ()           Undo the edit. edit that was made.

 

Method Detail

undo

void undo()
          throws CannotUndoException

Undo the edit. Undo the edit that was made.

Throws:

CannotUndoException - if this edit can not be undone

canUndo

boolean canUndo()

Returns true if this edit may be undone. True if it is still possible to undo this operation.

Returns:

true if this edit may be undone

redo

void redo()
          throws CannotRedoException

Re-applies the edit. Re-apply the edit, assuming that it has been undone.

Throws:

CannotRedoException - if this edit can not be redone

canRedo

boolean canRedo()

Returns true if this edit may be redone. True if it is still possible to redo this operation.

Returns:

true if this edit may be redone

die

void die()

Informs the edit that it should no longer be used. Once an UndoableEdit has been marked as dead it can no longer be undone or redone.

May be sent to inform an edit that it should no longer be used. 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. UndoManager calls this before it dequeues edits.

Note that this is a one-way operation. There is no "un-die" method.

See Also:

CompoundEdit.die()

addEdit

boolean addEdit(UndoableEdit anEdit)

Adds an UndoableEdit to this UndoableEdit. 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, the UndoableEdit would override addEdit to return true when the edits may be coalesced. This UndoableEdit should absorb anEdit if it can. Returns true if has been incorporated, false if it has not.

A return value of true indicates anEdit was incorporated into this edit. A return value of false indicates anEdit may not be incorporated into this edit.

Typically the receiver is already in the queue of a UndoManager (or other UndoableEditListener), and is being given a chance to incorporate anEdit rather than letting it be added to the queue in turn.

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 to be added

Returns:

true if anEdit may be incorporated into this edit

replaceEdit

boolean replaceEdit(UndoableEdit anEdit)

Returns true if this UndoableEdit should replace anEdit. This method is used by CompoundEdit and the UndoManager; it is called if anEdit could not be added to the current edit (addEdit returns false). The receiver should incorporate anEdit's state before returning true.

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 a 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. The UndoManager will undo, or redo, all insignificant edits to the next significant edit.

Returns:

true if this edit is significant

getPresentationName

 StringgetPresentationName () 

Returns a localized, human-readable description of this edit, suitable for use in a change log, for example.

Returns:

description of this edit

getUndoPresentationName

 StringgetUndoPresentationName () 

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 from getPresentationName.

Returns:

a description of the undoable form of this edit

getRedoPresentationName

 StringgetRedoPresentationName () 

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 from getPresentationName.

Returns:

a description of the redoable form of this edit

isSignificant

 
boolean isSignificant () 

Returns false if this edit is insignificant--for example one that maintains the user's selection, but does not change any model state. This status can be used by an UndoableEditListener (like UndoManager) when deciding which UndoableEdits to present to the user as Undo/Redo options, and which to perform as side effects of undoing or redoing other events.

getPresentationName

 
 StringgetPresentationName () 

Provides a localized, human readable description of this edit suitable for use in, say, a change log.

getUndoPresentationName

 
 StringgetUndoPresentationName () 

Provides a localized, human readable description of the undoable form of this edit, e.g. for use as an Undo menu item. Typically derived from getDescription.

getRedoPresentationName

 
 StringgetRedoPresentationName () 

Provides a localized, human readable description of the redoable form of this edit, e.g. for use as a Redo menu item. Typically derived from getPresentationName.