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