001    /* AbstractUndoableEdit.java --
002       Copyright (C) 2002, 2003, 2004  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package javax.swing.undo;
040    
041    import java.io.Serializable;
042    
043    import javax.swing.UIManager;
044    
045    /**
046     * A default implementation of <code>UndoableEdit</code> that can be
047     * used as a base for implementing editing operations.
048     *
049     * @author Andrew Selkirk (aselkirk@sympatico.ca)
050     * @author Sascha Brawer (brawer@dandelis.ch)
051     */
052    public class AbstractUndoableEdit
053      implements UndoableEdit, Serializable
054    {
055      /**
056       * The serialization ID.  Verified using the <code>serialver</code>
057       * tool of Apple/Sun JDK 1.3.1 on MacOS X 10.1.5, and Sun JDK
058       * 1.4.1_01 on GNU/Linux.
059       */
060      static final long serialVersionUID = 580150227676302096L;
061    
062    
063      /**
064       * The constant string &#x201c;Undo&#x201d;, which was returned by
065       * {@link #getUndoPresentationName()} on early versions of the
066       * platform. However, this field has become obsolete with version
067       * 1.3.1.  That method now retrieves a localized string from the
068       * {@link javax.swing.UIManager}, using the key
069       * <code>&#x201c;AbstractUndoableEdit.undoText&#x201d;</code>.
070       */
071      protected static final String UndoName = "Undo";
072    
073    
074      /**
075       * The constant string &#x201c;Redo&#x201d;, which was returned by
076       * {@link #getRedoPresentationName()} on early versions of the
077       * platform. However, this field has become obsolete with version
078       * 1.3.1.  That method now retrieves a localized string from the
079       * {@link javax.swing.UIManager}, using the key
080       * <code>&#x201c;AbstractUndoableEdit.redoText&#x201d;</code>.
081       */
082      protected static final String RedoName = "Redo";
083    
084    
085      /**
086       * Indicates whether this editing action has been executed.  A value
087       * of <code>true</code> means that the action was performed, or that
088       * a redo operation was successful. A value of <code>false</code>
089       * means that the action has not yet performed, or that an undo
090       * operation was successful.
091       */
092      private boolean hasBeenDone;
093    
094    
095      /**
096       * Indicates whether this editing action is still alive. The value
097       * is set to <code>true</code> by the constructor, and to
098       * <code>false</code> by the {@link #die()} method.
099       */
100      private boolean alive;
101    
102    
103      /**
104       * Constructs a new <code>AbstractUndoableEdit</code>. The initial
105       * state is that the editing action is alive, and
106       * <code>hasBeenDone</code> is <code>true</code>.
107       */
108      public AbstractUndoableEdit()
109      {
110        // The API specification is not clear, but Mauve test code has
111        // determined that hasBeenDone is initially set to true.
112        alive = hasBeenDone = true;
113      }
114    
115    
116      /**
117       * Undoes this editing action.
118       *
119       * @throws CannotUndoException if {@link #canUndo()} returns
120       * <code>false</code>, for example because this action has already
121       * been undone.
122       *
123       * @see #canUndo()
124       * @see #redo()
125       */
126      public void undo()
127        throws CannotUndoException
128      {
129        if (!canUndo())
130          throw new CannotUndoException();
131        hasBeenDone = false;
132      }
133      
134      
135      /**
136       * Determines whether it would be possible to undo this editing
137       * action.
138       *
139       * @return <code>true</code> to indicate that this action can be
140       * undone, <code>false</code> otherwise.
141       *
142       * @see #undo()
143       * @see #canRedo()
144       */
145      public boolean canUndo()
146      {
147        return alive && hasBeenDone;
148      }
149      
150      
151      /**
152       * Redoes this editing action.
153       *
154       * @throws CannotRedoException if {@link #canRedo()} returns
155       * <code>false</code>, for example because this action has not
156       * yet been undone.
157       *
158       * @see #canRedo()
159       * @see #undo()
160       */
161      public void redo()
162        throws CannotRedoException
163      {
164        if (!canRedo())
165          throw new CannotRedoException();
166        hasBeenDone = true;
167      }
168      
169      
170      /**
171       * Determines whether it would be possible to redo this editing
172       * action.
173       *
174       * @return <code>true</code> to indicate that this action can be
175       * redone, <code>false</code> otherwise.
176       *
177       * @see #redo()
178       * @see #canUndo()
179       */
180      public boolean canRedo()
181      {
182        return alive && !hasBeenDone;
183      }
184    
185    
186      /**
187       * Informs this edit action that it will no longer be used. Some
188       * actions might use this information to release resources, for
189       * example open files.  Called by {@link UndoManager} before this
190       * action is removed from the edit queue.
191       */
192      public void die()
193      {
194        alive = false;
195      }
196    
197    
198      /**
199       * Incorporates another editing action into this one, thus forming a
200       * combined action.
201       *
202       * <p>The default implementation always returns <code>false</code>,
203       * indicating that the editing action could not be incorporated.
204       *
205       * @param edit the editing action to be incorporated.
206       */
207      public boolean addEdit(UndoableEdit edit)
208      {
209        return false;
210      }
211      
212      
213      /**
214       * Incorporates another editing action into this one, thus forming a
215       * combined action that replaces the argument action.
216       *
217       * <p>The default implementation always returns <code>false</code>,
218       * indicating that the argument action should not be replaced.
219       *
220       * @param edit the editing action to be replaced.
221       */
222      public boolean replaceEdit(UndoableEdit edit)
223      {
224        return false;
225      }
226      
227      
228      /**
229       * Determines whether this editing action is significant enough for
230       * being seperately undoable by the user. A typical significant
231       * action would be the resizing of an object. However, changing the
232       * selection in a text document would usually not be considered
233       * significant.
234       *
235       * <p>The default implementation returns <code>true</code>.
236       *
237       * @return <code>true</code> to indicate that the action is
238       * significant enough for being separately undoable, or
239       * <code>false</code> otherwise.
240       */
241      public boolean isSignificant()
242      {
243        return true;
244      }
245      
246      
247      /**
248       * Returns a human-readable, localized name that describes this
249       * editing action and can be displayed to the user.
250       *
251       * <p>The default implementation returns an empty string.
252       */
253      public String getPresentationName()
254      {
255        return "";
256      }
257    
258    
259      /**
260       * Calculates a localized name for presenting the undo action to the
261       * user.
262       *
263       * <p>The default implementation returns the concatenation of the
264       * string &#x201c;Undo&#x201d; and the action name, which is
265       * determined by calling {@link #getPresentationName()}.
266       *
267       * <p>The string &#x201c;Undo&#x201d; is retrieved from the {@link
268       * javax.swing.UIManager}, using the key
269       * <code>&#x201c;AbstractUndoableEdit.undoText&#x201d;</code>.  This
270       * allows the text to be localized.
271       */
272      public String getUndoPresentationName()
273      {
274        String msg, pres;
275    
276        msg = UIManager.getString("AbstractUndoableEdit.undoText");
277        if (msg == null)
278          msg = UndoName;
279    
280        pres = getPresentationName();
281        if ((pres == null) || (pres.length() == 0))
282          return msg;
283        else
284          return msg + ' ' + pres;
285      }
286    
287    
288      /**
289       * Calculates a localized name for presenting the redo action to the
290       * user.
291       *
292       * <p>The default implementation returns the concatenation of the
293       * string &#x201c;Redo&#x201d; and the action name, which is
294       * determined by calling {@link #getPresentationName()}.
295       *
296       * <p>The string &#x201c;Redo&#x201d; is retrieved from the {@link
297       * javax.swing.UIManager}, using the key
298       * <code>&#x201c;AbstractUndoableEdit.redoText&#x201d;</code>.  This
299       * allows the text to be localized.
300       */
301      public String getRedoPresentationName()
302      {
303        String msg, pres;
304    
305        msg = UIManager.getString("AbstractUndoableEdit.redoText");
306        if (msg == null)
307          msg = RedoName;
308    
309        pres = getPresentationName();
310        if ((pres == null) || (pres.length() == 0))
311          return msg;
312        else
313          return msg + ' ' + pres;
314      }
315    
316    
317      public String toString()
318      {
319        return super.toString()
320          + " hasBeenDone: " + hasBeenDone
321          + " alive: " + alive;
322      }
323    }