/*

 * 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> &#8212;

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

}