https://openjdk.java.net/ 
/*
 * 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 UndoableEdit represents an edit.  The edit may
be undone, or if already undone the edit may be redone.


UndoableEdit is designed to be used with the
UndoManager.  As UndoableEdits are generated
by an UndoableEditListener they are typically added to
the UndoManager.  When an UndoableEdit
is added to an UndoManager the following occurs (assuming
end has not been called on the UndoManager):

    

  1. If the UndoManager contains edits it will call
    addEdit on the current edit passing in the new edit
    as the argument.  If addEdit 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 addEdit as a way for smaller edits to
    be incorporated into a larger edit and treated as a single edit.

  2. If addEdit returns false replaceEdit
    is called on the new edit with the current edit passed in as the
    argument. This is the inverse of addEdit —
    if the new edit returns true from replaceEdit, the new
    edit replaces the current edit.


The UndoManager makes use of
isSignificant to determine how many edits should be
undone or redone.  The UndoManager will undo or redo
all insignificant edits (isSignificant returns false)
between the current edit and the last or
next significant edit.   addEdit and
replaceEdit can be used to treat multiple edits as
a single edit, returning false from isSignificant
allows for treating can be used to
have many smaller edits undone or redone at once.  Similar functionality
can also be done using the addEdit method.

Author:Ray Ryan
/**
 * 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
/**
     * 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.

Returns:true if this edit may be undone
/**
     * 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
/**
     * 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.

Returns:true if this edit may be redone
/**
     * 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
UndoableEdit has been marked as dead it can no longer
be undone or redone.


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. UndoManager calls this before it dequeues edits.


Note that this is a one-way operation. There is no "un-die"
method.

See Also:
  • die.die
/**
     * 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 UndoableEdit to this UndoableEdit.
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 UndoableEdit would
override addEdit to return true when the edits may
be coalesced.


A return value of true indicates anEdit was incorporated
into this edit.  A return value of false indicates anEdit
may not be incorporated into this edit.

Typically the receiver is already in the queue of a
UndoManager (or other UndoableEditListener),
and is being given a chance to incorporate anEdit
rather than letting it be added to the queue in turn.


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.


Params:
  • anEdit – the edit to be added
Returns:true if anEdit may be incorporated into this
             edit
/**
     * 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 UndoableEdit should replace
anEdit. This method is used by CompoundEdit
and the UndoManager; it is called if
anEdit could not be added to the current edit
(addEdit returns false).


This method provides a way for an edit to replace an existing edit.

This message is the opposite of addEdit--anEdit has typically
already been queued in an UndoManager (or other
UndoableEditListener), and the receiver is being given a chance
to take its place.


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().


Params:
  • anEdit – the edit that replaces the current edit
Returns:true if this edit should replace 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 UndoManager will undo,
or redo, all insignificant edits to the next significant edit.

Returns:true if this edit is significant
/**
     * 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.

Returns:description of this edit
/**
     * 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 getPresentationName.

Returns:a description of the undoable form of this edit
/**
     * 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 getPresentationName.

Returns:a description of the redoable form of this edit
/**
     * 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();
}