1 /*
2 * Copyright (c) 1997, 2005, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
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 }