| /* | |
| * Copyright (c) 1997, 2005, Oracle and/or its affiliates. All rights reserved. | |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | |
| * | |
| * This code is free software; you can redistribute it and/or modify it | |
| * under the terms of the GNU General Public License version 2 only, as | |
| * published by the Free Software Foundation. Oracle designates this | |
| * particular file as subject to the "Classpath" exception as provided | |
| * by Oracle in the LICENSE file that accompanied this code. | |
| * | |
| * This code 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 | |
| * version 2 for more details (a copy is included in the LICENSE file that | |
| * accompanied this code). | |
| * | |
| * You should have received a copy of the GNU General Public License version | |
| * 2 along with this work; if not, write to the Free Software Foundation, | |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | |
| * | |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA | |
| * or visit www.oracle.com if you need additional information or have any | |
| * questions. | |
| */ | |
| 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(); | |
| } |