You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
202 lines
7.4 KiB
202 lines
7.4 KiB
/*
|
|
* Copyright (c) 1997, 2005, Oracle and/or its affiliates. All rights reserved.
|
|
* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*/
|
|
|
|
package javax.swing.undo;
|
|
|
|
import javax.swing.event.*;
|
|
|
|
/**
|
|
* An <code>UndoableEdit</code> represents an edit. The edit may
|
|
* be undone, or if already undone the edit may be redone.
|
|
* <p>
|
|
* <code>UndoableEdit</code> is designed to be used with the
|
|
* <code>UndoManager</code>. As <code>UndoableEdit</code>s are generated
|
|
* by an <code>UndoableEditListener</code> they are typically added to
|
|
* the <code>UndoManager</code>. When an <code>UndoableEdit</code>
|
|
* is added to an <code>UndoManager</code> the following occurs (assuming
|
|
* <code>end</code> has not been called on the <code>UndoManager</code>):
|
|
* <ol>
|
|
* <li>If the <code>UndoManager</code> contains edits it will call
|
|
* <code>addEdit</code> on the current edit passing in the new edit
|
|
* as the argument. If <code>addEdit</code> 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 <code>addEdit</code> as a way for smaller edits to
|
|
* be incorporated into a larger edit and treated as a single edit.
|
|
* <li>If <code>addEdit</code> returns false <code>replaceEdit</code>
|
|
* is called on the new edit with the current edit passed in as the
|
|
* argument. This is the inverse of <code>addEdit</code> —
|
|
* if the new edit returns true from <code>replaceEdit</code>, the new
|
|
* edit replaces the current edit.
|
|
* </ol>
|
|
* The <code>UndoManager</code> makes use of
|
|
* <code>isSignificant</code> to determine how many edits should be
|
|
* undone or redone. The <code>UndoManager</code> will undo or redo
|
|
* all insignificant edits (<code>isSignificant</code> returns false)
|
|
* between the current edit and the last or
|
|
* next significant edit. <code>addEdit</code> and
|
|
* <code>replaceEdit</code> can be used to treat multiple edits as
|
|
* a single edit, returning false from <code>isSignificant</code>
|
|
* allows for treating can be used to
|
|
* have many smaller edits undone or redone at once. Similar functionality
|
|
* can also be done using the <code>addEdit</code> method.
|
|
*
|
|
* @author Ray Ryan
|
|
*/
|
|
public interface UndoableEdit {
|
|
/**
|
|
* Undo the edit.
|
|
*
|
|
* @throws CannotUndoException if this edit can not be undone
|
|
*/
|
|
public void undo() throws CannotUndoException;
|
|
|
|
/**
|
|
* Returns true if this edit may be undone.
|
|
*
|
|
* @return true if this edit may be undone
|
|
*/
|
|
public boolean canUndo();
|
|
|
|
/**
|
|
* Re-applies the edit.
|
|
*
|
|
* @throws CannotRedoException if this edit can not be redone
|
|
*/
|
|
public void redo() throws CannotRedoException;
|
|
|
|
/**
|
|
* Returns true if this edit may be redone.
|
|
*
|
|
* @return true if this edit may be redone
|
|
*/
|
|
public boolean canRedo();
|
|
|
|
/**
|
|
* Informs the edit that it should no longer be used. Once an
|
|
* <code>UndoableEdit</code> has been marked as dead it can no longer
|
|
* be undone or redone.
|
|
* <p>
|
|
* 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. <code>UndoManager</code> calls this before it dequeues edits.
|
|
* <p>
|
|
* Note that this is a one-way operation. There is no "un-die"
|
|
* method.
|
|
*
|
|
* @see CompoundEdit#die
|
|
*/
|
|
public void die();
|
|
|
|
/**
|
|
* Adds an <code>UndoableEdit</code> to this <code>UndoableEdit</code>.
|
|
* 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 <code>UndoableEdit</code> would
|
|
* override <code>addEdit</code> to return true when the edits may
|
|
* be coalesced.
|
|
* <p>
|
|
* A return value of true indicates <code>anEdit</code> was incorporated
|
|
* into this edit. A return value of false indicates <code>anEdit</code>
|
|
* may not be incorporated into this edit.
|
|
* <p>Typically the receiver is already in the queue of a
|
|
* <code>UndoManager</code> (or other <code>UndoableEditListener</code>),
|
|
* and is being given a chance to incorporate <code>anEdit</code>
|
|
* rather than letting it be added to the queue in turn.</p>
|
|
*
|
|
* <p>If true is returned, from now on <code>anEdit</code> must return
|
|
* false from <code>canUndo</code> and <code>canRedo</code>,
|
|
* and must throw the appropriate exception on <code>undo</code> or
|
|
* <code>redo</code>.</p>
|
|
*
|
|
* @param anEdit the edit to be added
|
|
* @return true if <code>anEdit</code> may be incorporated into this
|
|
* edit
|
|
*/
|
|
public boolean addEdit(UndoableEdit anEdit);
|
|
|
|
/**
|
|
* Returns true if this <code>UndoableEdit</code> should replace
|
|
* <code>anEdit</code>. This method is used by <code>CompoundEdit</code>
|
|
* and the <code>UndoManager</code>; it is called if
|
|
* <code>anEdit</code> could not be added to the current edit
|
|
* (<code>addEdit</code> returns false).
|
|
* <p>
|
|
* This method provides a way for an edit to replace an existing edit.
|
|
* <p>This message is the opposite of addEdit--anEdit has typically
|
|
* already been queued in an <code>UndoManager</code> (or other
|
|
* UndoableEditListener), and the receiver is being given a chance
|
|
* to take its place.</p>
|
|
*
|
|
* <p>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().</p>
|
|
*
|
|
* @param anEdit the edit that replaces the current edit
|
|
* @return true if this edit should replace <code>anEdit</code>
|
|
*/
|
|
public boolean replaceEdit(UndoableEdit anEdit);
|
|
|
|
/**
|
|
* 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 <code>UndoManager</code> will undo,
|
|
* or redo, all insignificant edits to the next significant edit.
|
|
*
|
|
* @return true if this edit is significant
|
|
*/
|
|
public boolean isSignificant();
|
|
|
|
/**
|
|
* Returns a localized, human-readable description of this edit, suitable
|
|
* for use in a change log, for example.
|
|
*
|
|
* @return description of this edit
|
|
*/
|
|
public String getPresentationName();
|
|
|
|
/**
|
|
* 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 <code>getPresentationName</code>.
|
|
*
|
|
* @return a description of the undoable form of this edit
|
|
*/
|
|
public String getUndoPresentationName();
|
|
|
|
/**
|
|
* 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 <code>getPresentationName</code>.
|
|
*
|
|
* @return a description of the redoable form of this edit
|
|
*/
|
|
public String getRedoPresentationName();
|
|
}
|