001 /*
002 * Copyright 1997-2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.swing.undo;
027
028 import javax.swing.event.*;
029
030 /**
031 * An <code>UndoableEdit</code> represents an edit. The edit may
032 * be undone, or if already undone the edit may be redone.
033 * <p>
034 * <code>UndoableEdit</code> is designed to be used with the
035 * <code>UndoManager</code>. As <code>UndoableEdit</code>s are generated
036 * by an <code>UndoableEditListener</code> they are typically added to
037 * the <code>UndoManager</code>. When an <code>UndoableEdit</code>
038 * is added to an <code>UndoManager</code> the following occurs (assuming
039 * <code>end</code> has not been called on the <code>UndoManager</code>):
040 * <ol>
041 * <li>If the <code>UndoManager</code> contains edits it will call
042 * <code>addEdit</code> on the current edit passing in the new edit
043 * as the argument. If <code>addEdit</code> returns true the
044 * new edit is assumed to have been incorporated into the current edit and
045 * the new edit will not be added to the list of current edits.
046 * Edits can use <code>addEdit</code> as a way for smaller edits to
047 * be incorporated into a larger edit and treated as a single edit.
048 * <li>If <code>addEdit</code> returns false <code>replaceEdit</code>
049 * is called on the new edit with the current edit passed in as the
050 * argument. This is the inverse of <code>addEdit</code> —
051 * if the new edit returns true from <code>replaceEdit</code>, the new
052 * edit replaces the current edit.
053 * </ol>
054 * The <code>UndoManager</code> makes use of
055 * <code>isSignificant</code> to determine how many edits should be
056 * undone or redone. The <code>UndoManager</code> will undo or redo
057 * all insignificant edits (<code>isSignificant</code> returns false)
058 * between the current edit and the last or
059 * next significant edit. <code>addEdit</code> and
060 * <code>replaceEdit</code> can be used to treat multiple edits as
061 * a single edit, returning false from <code>isSignificant</code>
062 * allows for treating can be used to
063 * have many smaller edits undone or redone at once. Similar functionality
064 * can also be done using the <code>addEdit</code> method.
065 *
066 * @version 1.27, 05/05/07
067 * @author Ray Ryan
068 */
069 public interface UndoableEdit {
070 /**
071 * Undo the edit.
072 *
073 * @throws CannotUndoException if this edit can not be undone
074 */
075 public void undo() throws CannotUndoException;
076
077 /**
078 * Returns true if this edit may be undone.
079 *
080 * @return true if this edit may be undone
081 */
082 public boolean canUndo();
083
084 /**
085 * Re-applies the edit.
086 *
087 * @throws CannotRedoException if this edit can not be redone
088 */
089 public void redo() throws CannotRedoException;
090
091 /**
092 * Returns true if this edit may be redone.
093 *
094 * @return true if this edit may be redone
095 */
096 public boolean canRedo();
097
098 /**
099 * Informs the edit that it should no longer be used. Once an
100 * <code>UndoableEdit</code> has been marked as dead it can no longer
101 * be undone or redone.
102 * <p>
103 * This is a useful hook for cleaning up state no longer
104 * needed once undoing or redoing is impossible--for example,
105 * deleting file resources used by objects that can no longer be
106 * undeleted. <code>UndoManager</code> calls this before it dequeues edits.
107 * <p>
108 * Note that this is a one-way operation. There is no "un-die"
109 * method.
110 *
111 * @see CompoundEdit#die
112 */
113 public void die();
114
115 /**
116 * Adds an <code>UndoableEdit</code> to this <code>UndoableEdit</code>.
117 * This method can be used to coalesce smaller edits into a larger
118 * compound edit. For example, text editors typically allow
119 * undo operations to apply to words or sentences. The text
120 * editor may choose to generate edits on each key event, but allow
121 * those edits to be coalesced into a more user-friendly unit, such as
122 * a word. In this case, the <code>UndoableEdit</code> would
123 * override <code>addEdit</code> to return true when the edits may
124 * be coalesced.
125 * <p>
126 * A return value of true indicates <code>anEdit</code> was incorporated
127 * into this edit. A return value of false indicates <code>anEdit</code>
128 * may not be incorporated into this edit.
129 * <p>Typically the receiver is already in the queue of a
130 * <code>UndoManager</code> (or other <code>UndoableEditListener</code>),
131 * and is being given a chance to incorporate <code>anEdit</code>
132 * rather than letting it be added to the queue in turn.</p>
133 *
134 * <p>If true is returned, from now on <code>anEdit</code> must return
135 * false from <code>canUndo</code> and <code>canRedo</code>,
136 * and must throw the appropriate exception on <code>undo</code> or
137 * <code>redo</code>.</p>
138 *
139 * @param anEdit the edit to be added
140 * @return true if <code>anEdit</code> may be incorporated into this
141 * edit
142 */
143 public boolean addEdit(UndoableEdit anEdit);
144
145 /**
146 * Returns true if this <code>UndoableEdit</code> should replace
147 * <code>anEdit</code>. This method is used by <code>CompoundEdit</code>
148 * and the <code>UndoManager</code>; it is called if
149 * <code>anEdit</code> could not be added to the current edit
150 * (<code>addEdit</code> returns false).
151 * <p>
152 * This method provides a way for an edit to replace an existing edit.
153 * <p>This message is the opposite of addEdit--anEdit has typically
154 * already been queued in an <code>UndoManager</code> (or other
155 * UndoableEditListener), and the receiver is being given a chance
156 * to take its place.</p>
157 *
158 * <p>If true is returned, from now on anEdit must return false from
159 * canUndo() and canRedo(), and must throw the appropriate
160 * exception on undo() or redo().</p>
161 *
162 * @param anEdit the edit that replaces the current edit
163 * @return true if this edit should replace <code>anEdit</code>
164 */
165 public boolean replaceEdit(UndoableEdit anEdit);
166
167 /**
168 * Returns true if this edit is considered significant. A significant
169 * edit is typically an edit that should be presented to the user, perhaps
170 * on a menu item or tooltip. The <code>UndoManager</code> will undo,
171 * or redo, all insignificant edits to the next significant edit.
172 *
173 * @return true if this edit is significant
174 */
175 public boolean isSignificant();
176
177 /**
178 * Returns a localized, human-readable description of this edit, suitable
179 * for use in a change log, for example.
180 *
181 * @return description of this edit
182 */
183 public String getPresentationName();
184
185 /**
186 * Returns a localized, human-readable description of the undoable form of
187 * this edit, suitable for use as an Undo menu item, for example.
188 * This is typically derived from <code>getPresentationName</code>.
189 *
190 * @return a description of the undoable form of this edit
191 */
192 public String getUndoPresentationName();
193
194 /**
195 * Returns a localized, human-readable description of the redoable form of
196 * this edit, suitable for use as a Redo menu item, for example. This is
197 * typically derived from <code>getPresentationName</code>.
198 *
199 * @return a description of the redoable form of this edit
200 */
201 public String getRedoPresentationName();
202 }
|