Source code: javax/swing/undo/StateEdit.java
1 /* StateEdit.java -- UndoableEdit for StateEditable implementations.
2 Copyright (C) 2002, 2003 Free Software Foundation, Inc.
3
4 This file is part of GNU Classpath.
5
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
9 any later version.
10
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 General Public License for more details.
15
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING. If not, write to the
18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
19 02110-1301 USA.
20
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library. Thus, the terms and
23 conditions of the GNU General Public License cover the whole
24 combination.
25
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module. An independent module is a module which is not derived from
33 or based on this library. If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so. If you do not wish to do so, delete this
36 exception statement from your version. */
37
38
39 package javax.swing.undo;
40
41 import java.util.Hashtable;
42 import java.util.Iterator;
43
44 /**
45 * A helper class, making it easy to support undo and redo.
46 *
47 * <p>The following example shows how to use this class.</p>
48 *
49 * <pre>
50 * Foo foo; // class Foo implements {@link StateEditable}
51 * StateEdit edit;
52 *
53 * edit = new StateEdit(foo, "Name Change");
54 * foo.setName("Jane Doe");
55 * edit.end();
56 * undoManager.addEdit(edit);
57 * </pre>
58 *
59 * <p>If <code>Foo</code>’s implementation of {@link
60 * StateEditable} considers the name as part of the editable state,
61 * the user can now choose “Undo Name Change” or
62 * “Redo Name Change” from the respective menu. No
63 * further undo support is needed from the application.</p>
64 *
65 * <p>The following explains what happens in the example.</p>
66 *
67 * <ol>
68 * <li>When a <code>StateEdit</code> is created, the associated
69 * {@link StateEditable} gets asked to store its state into a hash
70 * table, {@link #preState}.</li>
71 * <li>The application will now perform some changes to the edited
72 * object. This typically happens by invoking methods on the edited
73 * object.</li>
74 * <li>The editing phase is terminated by invoking the {@link #end()}
75 * method of the <code>StateEdit</code>. The <code>end()</code> method
76 * does two things.
77 *
78 * <ul>
79 * <li>The edited object receives a second request for storing
80 * its state. This time, it will use a different hash table, {@link
81 * #postState}.</li>
82 * <li>To increase efficiency, the <code>StateEdit</code> now removes
83 * any entries from {@link #preState} and {@link #postState} that have
84 * the same key, and whose values are equal. Equality is determined
85 * by invoking the <code>equals</code> method inherited from
86 * {@link java.lang.Object}.</li>
87 * </ul></li>
88 * <li>When the user later chooses to undo the <code>StateEdit</code>,
89 * the edited object is asked to {@linkplain StateEditable#restoreState
90 * restore its state} from the {@link #preState} table. Similarly,
91 * when the user chooses to <i>redo</i> the <code>StateEdit</code>,
92 * the edited object gets asked to restore its state from the {@link
93 * #postState}.</li>
94 * </ol>
95 *
96 * @author Andrew Selkirk (aselkirk@sympatico.ca)
97 * @author Sascha Brawer (brawer@dandelis.ch)
98 */
99 public class StateEdit
100 extends AbstractUndoableEdit
101 {
102 /**
103 * The ID of the Java source file in Sun’s Revision Control
104 * System (RCS). This certainly should not be part of the API
105 * specification. But in order to be API-compatible with
106 * Sun’s reference implementation, GNU Classpath also has to
107 * provide this field. However, we do not try to match its value.
108 */
109 protected static final String RCSID = "";
110
111
112 /**
113 * The object which is being edited by this <code>StateEdit</code>.
114 */
115 protected StateEditable object;
116
117
118 /**
119 * The state of <code>object</code> at the time of constructing
120 * this <code>StateEdit</code>.
121 */
122 protected Hashtable preState;
123
124
125 /**
126 * The state of <code>object</code> at the time when {@link #end()}
127 * was called.
128 */
129 protected Hashtable postState;
130
131
132 /**
133 * A human-readable name for this edit action.
134 */
135 protected String undoRedoName;
136
137
138 /**
139 * Constructs a <code>StateEdit</code>, specifying the object whose
140 * state is being edited.
141 *
142 * @param obj the object whose state is being edited by this
143 * <code>StateEdit</code>.
144 */
145 public StateEdit(StateEditable obj)
146 {
147 init(obj, null);
148 }
149
150
151 /**
152 * Constructs a <code>StateEdit</code>, specifying the object whose
153 * state is being edited.
154 *
155 * @param obj the object whose state is being edited by this
156 * <code>StateEdit</code>.
157 *
158 * @param name the human-readable name of the editing action.
159 */
160 public StateEdit(StateEditable obj, String name)
161 {
162 init(obj, name);
163 }
164
165
166 /**
167 * Initializes this <code>StateEdit</code>. The edited object will
168 * be asked to store its current state into {@link #preState}.
169 *
170 * @param obj the object being edited.
171 *
172 * @param name the human-readable name of the editing action.
173 */
174 protected void init(StateEditable obj, String name)
175 {
176 object = obj;
177 undoRedoName = name;
178 preState = new Hashtable();
179 postState = new Hashtable();
180 obj.storeState(preState);
181 }
182
183
184 /**
185 * Informs this <code>StateEdit</code> that all edits are finished.
186 * The edited object will be asked to store its state into {@link
187 * #postState}, and any redundant entries will get removed from
188 * {@link #preState} and {@link #postState}.
189 */
190 public void end()
191 {
192 object.storeState(postState);
193 removeRedundantState();
194 }
195
196
197 /**
198 * Undoes this edit operation. The edited object will be asked to
199 * {@linkplain StateEditable#restoreState restore its state} from
200 * {@link #preState}.
201 *
202 * @throws CannotUndoException if {@link #canUndo()} returns
203 * <code>false</code>, for example because this action has already
204 * been undone.
205 */
206 public void undo()
207 {
208 super.undo();
209 object.restoreState(preState);
210 }
211
212
213 /**
214 * Redoes this edit operation. The edited object will be asked to
215 * {@linkplain StateEditable#restoreState restore its state} from
216 * {@link #postState}.
217 *
218 * @throws CannotRedoException if {@link #canRedo()} returns
219 * <code>false</code>, for example because this action has not yet
220 * been undone.
221 */
222 public void redo()
223 {
224 super.redo();
225 object.restoreState(postState);
226 }
227
228
229 /**
230 * Returns a human-readable, localized name that describes this
231 * editing action and can be displayed to the user.
232 *
233 * @return the name, or <code>null</code> if no presentation
234 * name is available.
235 */
236 public String getPresentationName()
237 {
238 return undoRedoName;
239 }
240
241
242 /**
243 * Removes all redundant entries from the pre- and post-edit state
244 * hash tables. An entry is considered redundant if it is present
245 * both before and after the edit, and if the two values are equal.
246 */
247 protected void removeRedundantState()
248 {
249 Iterator i = preState.keySet().iterator();
250 while (i.hasNext())
251 {
252 Object key = i.next();
253 if (postState.containsKey(key))
254 {
255 if (preState.get(key).equals(postState.get(key)))
256 {
257 i.remove();
258 postState.remove(key);
259 }
260 }
261 }
262 }
263 }