| /* |
| * 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(); |
| } |