< prev index next >

src/java.desktop/share/classes/javax/swing/undo/UndoableEdit.java

Print this page




  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.swing.undo;
  27 
  28 import javax.swing.event.*;
  29 
  30 /**
  31  * An <code>UndoableEdit</code> represents an edit.  The edit may
  32  * be undone, or if already undone the edit may be redone.
  33  * <p>
  34  * <code>UndoableEdit</code> is designed to be used with the
  35  * <code>UndoManager</code>.  As <code>UndoableEdit</code>s are generated
  36  * by an <code>UndoableEditListener</code> they are typically added to
  37  * the <code>UndoManager</code>.  When an <code>UndoableEdit</code>
  38  * is added to an <code>UndoManager</code> the following occurs (assuming
  39  * <code>end</code> has not been called on the <code>UndoManager</code>):
  40  * <ol>
  41  * <li>If the <code>UndoManager</code> contains edits it will call
  42  *     <code>addEdit</code> on the current edit passing in the new edit
  43  *     as the argument.  If <code>addEdit</code> returns true the
  44  *     new edit is assumed to have been incorporated into the current edit and
  45  *     the new edit will not be added to the list of current edits.
  46  *     Edits can use <code>addEdit</code> as a way for smaller edits to
  47  *     be incorporated into a larger edit and treated as a single edit.
  48  * <li>If <code>addEdit</code> returns false <code>replaceEdit</code>
  49  *     is called on the new edit with the current edit passed in as the
  50  *     argument. This is the inverse of <code>addEdit</code> —
  51  *     if the new edit returns true from <code>replaceEdit</code>, the new
  52  *     edit replaces the current edit.
  53  * </ol>
  54  * The <code>UndoManager</code> makes use of
  55  * <code>isSignificant</code> to determine how many edits should be
  56  * undone or redone.  The <code>UndoManager</code> will undo or redo
  57  * all insignificant edits (<code>isSignificant</code> returns false)
  58  * between the current edit and the last or
  59  * next significant edit.   <code>addEdit</code> and
  60  * <code>replaceEdit</code> can be used to treat multiple edits as
  61  * a single edit, returning false from <code>isSignificant</code>
  62  * allows for treating can be used to
  63  * have many smaller edits undone or redone at once.  Similar functionality
  64  * can also be done using the <code>addEdit</code> method.
  65  *
  66  * @author Ray Ryan
  67  */
  68 public interface UndoableEdit {
  69     /**
  70      * Undo the edit.
  71      *
  72      * @throws CannotUndoException if this edit can not be undone
  73      */
  74     public void undo() throws CannotUndoException;
  75 
  76     /**
  77      * Returns true if this edit may be undone.
  78      *
  79      * @return true if this edit may be undone
  80      */
  81     public boolean canUndo();
  82 
  83     /**
  84      * Re-applies the edit.
  85      *
  86      * @throws CannotRedoException if this edit can not be redone
  87      */
  88     public void redo() throws CannotRedoException;
  89 
  90     /**
  91      * Returns true if this edit may be redone.
  92      *
  93      * @return true if this edit may be redone
  94      */
  95     public boolean canRedo();
  96 
  97     /**
  98      * Informs the edit that it should no longer be used. Once an
  99      * <code>UndoableEdit</code> has been marked as dead it can no longer
 100      * be undone or redone.
 101      * <p>
 102      * This is a useful hook for cleaning up state no longer
 103      * needed once undoing or redoing is impossible--for example,
 104      * deleting file resources used by objects that can no longer be
 105      * undeleted. <code>UndoManager</code> calls this before it dequeues edits.
 106      * <p>
 107      * Note that this is a one-way operation. There is no "un-die"
 108      * method.
 109      *
 110      * @see CompoundEdit#die
 111      */
 112     public void die();
 113 
 114     /**
 115      * Adds an <code>UndoableEdit</code> to this <code>UndoableEdit</code>.
 116      * This method can be used to coalesce smaller edits into a larger
 117      * compound edit.  For example, text editors typically allow
 118      * undo operations to apply to words or sentences.  The text
 119      * editor may choose to generate edits on each key event, but allow
 120      * those edits to be coalesced into a more user-friendly unit, such as
 121      * a word. In this case, the <code>UndoableEdit</code> would
 122      * override <code>addEdit</code> to return true when the edits may
 123      * be coalesced.
 124      * <p>
 125      * A return value of true indicates <code>anEdit</code> was incorporated
 126      * into this edit.  A return value of false indicates <code>anEdit</code>
 127      * may not be incorporated into this edit.
 128      * <p>Typically the receiver is already in the queue of a
 129      * <code>UndoManager</code> (or other <code>UndoableEditListener</code>),
 130      * and is being given a chance to incorporate <code>anEdit</code>
 131      * rather than letting it be added to the queue in turn.</p>
 132      *
 133      * <p>If true is returned, from now on <code>anEdit</code> must return
 134      * false from <code>canUndo</code> and <code>canRedo</code>,
 135      * and must throw the appropriate exception on <code>undo</code> or
 136      * <code>redo</code>.</p>
 137      *
 138      * @param anEdit the edit to be added
 139      * @return true if <code>anEdit</code> may be incorporated into this
 140      *              edit
 141      */
 142     public boolean addEdit(UndoableEdit anEdit);
 143 
 144     /**
 145      * Returns true if this <code>UndoableEdit</code> should replace
 146      * <code>anEdit</code>. This method is used by <code>CompoundEdit</code>
 147      * and the <code>UndoManager</code>; it is called if
 148      * <code>anEdit</code> could not be added to the current edit
 149      * (<code>addEdit</code> returns false).
 150      * <p>
 151      * This method provides a way for an edit to replace an existing edit.
 152      * <p>This message is the opposite of addEdit--anEdit has typically
 153      * already been queued in an <code>UndoManager</code> (or other
 154      * UndoableEditListener), and the receiver is being given a chance
 155      * to take its place.</p>
 156      *
 157      * <p>If true is returned, from now on anEdit must return false from
 158      * canUndo() and canRedo(), and must throw the appropriate
 159      * exception on undo() or redo().</p>
 160      *
 161      * @param anEdit the edit that replaces the current edit
 162      * @return true if this edit should replace <code>anEdit</code>
 163      */
 164     public boolean replaceEdit(UndoableEdit anEdit);
 165 
 166     /**
 167      * Returns true if this edit is considered significant.  A significant
 168      * edit is typically an edit that should be presented to the user, perhaps
 169      * on a menu item or tooltip.  The <code>UndoManager</code> will undo,
 170      * or redo, all insignificant edits to the next significant edit.
 171      *
 172      * @return true if this edit is significant
 173      */
 174     public boolean isSignificant();
 175 
 176     /**
 177      * Returns a localized, human-readable description of this edit, suitable
 178      * for use in a change log, for example.
 179      *
 180      * @return description of this edit
 181      */
 182     public String getPresentationName();
 183 
 184     /**
 185      * Returns a localized, human-readable description of the undoable form of
 186      * this edit, suitable for use as an Undo menu item, for example.
 187      * This is typically derived from <code>getPresentationName</code>.
 188      *
 189      * @return a description of the undoable form of this edit
 190      */
 191     public String getUndoPresentationName();
 192 
 193     /**
 194      * Returns a localized, human-readable description of the redoable form of
 195      * this edit, suitable for use as a Redo menu item, for example. This is
 196      * typically derived from <code>getPresentationName</code>.
 197      *
 198      * @return a description of the redoable form of this edit
 199      */
 200     public String getRedoPresentationName();
 201 }


  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.swing.undo;
  27 
  28 import javax.swing.event.*;
  29 
  30 /**
  31  * An {@code UndoableEdit} represents an edit.  The edit may
  32  * be undone, or if already undone the edit may be redone.
  33  * <p>
  34  * {@code UndoableEdit} is designed to be used with the
  35  * {@code UndoManager}.  As {@code UndoableEdit}s are generated
  36  * by an {@code UndoableEditListener} they are typically added to
  37  * the {@code UndoManager}.  When an {@code UndoableEdit}
  38  * is added to an {@code UndoManager} the following occurs (assuming
  39  * {@code end} has not been called on the {@code UndoManager}):
  40  * <ol>
  41  * <li>If the {@code UndoManager} contains edits it will call
  42  *     {@code addEdit} on the current edit passing in the new edit
  43  *     as the argument.  If {@code addEdit} returns true the
  44  *     new edit is assumed to have been incorporated into the current edit and
  45  *     the new edit will not be added to the list of current edits.
  46  *     Edits can use {@code addEdit} as a way for smaller edits to
  47  *     be incorporated into a larger edit and treated as a single edit.
  48  * <li>If {@code addEdit} returns false {@code replaceEdit}
  49  *     is called on the new edit with the current edit passed in as the
  50  *     argument. This is the inverse of {@code addEdit} —
  51  *     if the new edit returns true from {@code replaceEdit}, the new
  52  *     edit replaces the current edit.
  53  * </ol>
  54  * The {@code UndoManager} makes use of
  55  * {@code isSignificant} to determine how many edits should be
  56  * undone or redone.  The {@code UndoManager} will undo or redo
  57  * all insignificant edits ({@code isSignificant} returns false)
  58  * between the current edit and the last or
  59  * next significant edit.   {@code addEdit} and
  60  * {@code replaceEdit} can be used to treat multiple edits as
  61  * a single edit, returning false from {@code isSignificant}
  62  * allows for treating can be used to
  63  * have many smaller edits undone or redone at once.  Similar functionality
  64  * can also be done using the {@code addEdit} method.
  65  *
  66  * @author Ray Ryan
  67  */
  68 public interface UndoableEdit {
  69     /**
  70      * Undo the edit.
  71      *
  72      * @throws CannotUndoException if this edit can not be undone
  73      */
  74     public void undo() throws CannotUndoException;
  75 
  76     /**
  77      * Returns true if this edit may be undone.
  78      *
  79      * @return true if this edit may be undone
  80      */
  81     public boolean canUndo();
  82 
  83     /**
  84      * Re-applies the edit.
  85      *
  86      * @throws CannotRedoException if this edit can not be redone
  87      */
  88     public void redo() throws CannotRedoException;
  89 
  90     /**
  91      * Returns true if this edit may be redone.
  92      *
  93      * @return true if this edit may be redone
  94      */
  95     public boolean canRedo();
  96 
  97     /**
  98      * Informs the edit that it should no longer be used. Once an
  99      * {@code UndoableEdit} has been marked as dead it can no longer
 100      * be undone or redone.
 101      * <p>
 102      * This is a useful hook for cleaning up state no longer
 103      * needed once undoing or redoing is impossible--for example,
 104      * deleting file resources used by objects that can no longer be
 105      * undeleted. {@code UndoManager} calls this before it dequeues edits.
 106      * <p>
 107      * Note that this is a one-way operation. There is no "un-die"
 108      * method.
 109      *
 110      * @see CompoundEdit#die
 111      */
 112     public void die();
 113 
 114     /**
 115      * Adds an {@code UndoableEdit} to this {@code UndoableEdit}.
 116      * This method can be used to coalesce smaller edits into a larger
 117      * compound edit.  For example, text editors typically allow
 118      * undo operations to apply to words or sentences.  The text
 119      * editor may choose to generate edits on each key event, but allow
 120      * those edits to be coalesced into a more user-friendly unit, such as
 121      * a word. In this case, the {@code UndoableEdit} would
 122      * override {@code addEdit} to return true when the edits may
 123      * be coalesced.
 124      * <p>
 125      * A return value of true indicates {@code anEdit} was incorporated
 126      * into this edit.  A return value of false indicates {@code anEdit}
 127      * may not be incorporated into this edit.
 128      * <p>Typically the receiver is already in the queue of a
 129      * {@code UndoManager} (or other {@code UndoableEditListener}),
 130      * and is being given a chance to incorporate {@code anEdit}
 131      * rather than letting it be added to the queue in turn.</p>
 132      *
 133      * <p>If true is returned, from now on {@code anEdit} must return
 134      * false from {@code canUndo} and {@code canRedo},
 135      * and must throw the appropriate exception on {@code undo} or
 136      * {@code redo}.</p>
 137      *
 138      * @param anEdit the edit to be added
 139      * @return true if {@code anEdit} may be incorporated into this
 140      *              edit
 141      */
 142     public boolean addEdit(UndoableEdit anEdit);
 143 
 144     /**
 145      * Returns true if this {@code UndoableEdit} should replace
 146      * {@code anEdit}. This method is used by {@code CompoundEdit}
 147      * and the {@code UndoManager}; it is called if
 148      * {@code anEdit} could not be added to the current edit
 149      * ({@code addEdit} returns false).
 150      * <p>
 151      * This method provides a way for an edit to replace an existing edit.
 152      * <p>This message is the opposite of addEdit--anEdit has typically
 153      * already been queued in an {@code UndoManager} (or other
 154      * UndoableEditListener), and the receiver is being given a chance
 155      * to take its place.</p>
 156      *
 157      * <p>If true is returned, from now on anEdit must return false from
 158      * canUndo() and canRedo(), and must throw the appropriate
 159      * exception on undo() or redo().</p>
 160      *
 161      * @param anEdit the edit that replaces the current edit
 162      * @return true if this edit should replace {@code anEdit}
 163      */
 164     public boolean replaceEdit(UndoableEdit anEdit);
 165 
 166     /**
 167      * Returns true if this edit is considered significant.  A significant
 168      * edit is typically an edit that should be presented to the user, perhaps
 169      * on a menu item or tooltip.  The {@code UndoManager} will undo,
 170      * or redo, all insignificant edits to the next significant edit.
 171      *
 172      * @return true if this edit is significant
 173      */
 174     public boolean isSignificant();
 175 
 176     /**
 177      * Returns a localized, human-readable description of this edit, suitable
 178      * for use in a change log, for example.
 179      *
 180      * @return description of this edit
 181      */
 182     public String getPresentationName();
 183 
 184     /**
 185      * Returns a localized, human-readable description of the undoable form of
 186      * this edit, suitable for use as an Undo menu item, for example.
 187      * This is typically derived from {@code getPresentationName}.
 188      *
 189      * @return a description of the undoable form of this edit
 190      */
 191     public String getUndoPresentationName();
 192 
 193     /**
 194      * Returns a localized, human-readable description of the redoable form of
 195      * this edit, suitable for use as a Redo menu item, for example. This is
 196      * typically derived from {@code getPresentationName}.
 197      *
 198      * @return a description of the redoable form of this edit
 199      */
 200     public String getRedoPresentationName();
 201 }
< prev index next >