toolchain/gcc/libjava/javax/swing/undo/CompoundEdit.java

   1 /* CompoundEdit.java -- Combines multiple UndoableEdits.
   2    Copyright (C) 2002, 2003, 2004 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., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 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.Vector;
  42
  43 /**
  44  * An editing action that consists of multiple
  45  * <code>UndoableEdits</code>.
  46  *
  47  * <p>The use of a <code>CompoundEdit</code> is divided in two separate
  48  * phases.
  49  *
  50  * <ol><li>In the first phase, the <code>CompoundEdit</code> is
  51  * initialized.  After a new instance of <code>CompoundEdit</code> has
  52  * been created, {@link #addEdit(UndoableEdit)} is called for each
  53  * element of the compound.  To terminate the initialization phase,
  54  * call {@link #end()}.</li>
  55  *
  56  * <li>In the second phase, the the <code>CompoundEdit</code> can be
  57  * used, typically by invoking {@link #undo()} and {@link
  58  * #redo()}.</li></ol>
  59  *
  60  * @author Andrew Selkirk (aselkirk@sympatico.ca)
  61  * @author Sascha Brawer (brawer@dandelis.ch)
  62  */
  63 public class CompoundEdit
  64   extends AbstractUndoableEdit
  65 {
  66   /**
  67    * The identifier of this class in object serialization. Determined
  68    * using the serialver tool of Sun J2SE 1.4.1_01.
  69    */
  70   private static final long serialVersionUID = -6512679249930119683L;
  71
  72
  73   /**
  74    * The <code>UndoableEdit</code>s being combined into a compound
  75    * editing action.
  76    */
  77   protected Vector edits;
  78
  79
  80   /**
  81    * Indicates whether the creation of this CompoundEdit is still in
  82    * progress. Initially, the value of this flag is
  83    * <code>true</code>. The {@link #end()} method changes the flag to
  84    * <code>false</code>.
  85    */
  86   private boolean inProgress;
  87
  88
  89   /**
  90    * Constructs a new CompoundEdit.
  91    */
  92   public CompoundEdit()
  93   {
  94     edits = new Vector();
  95     inProgress = true;
  96   }
  97
  98
  99   /**
 100    * Undoes all edits that are part of of this
 101    * <code>CompoundEdit</code>. The compound elements will receive the
 102    * <code>undo</code> message in the reverse order of addition.
 103    *
 104    * @throws CannotUndoException if {@link #canUndo()} returns
 105    * <code>false</code>. This can happen if {@link #end()} has not
 106    * been called on this <code>CompoundEdit</code>, or if this edit
 107    * has already been undone.
 108    *
 109    * @see #canUndo()
 110    * @see #redo()
 111    */
 112   public void undo()
 113     throws CannotUndoException
 114   {
 115     // AbstractUndoableEdit.undo() will throw a CannotUndoException if
 116     // canUndo returns false.
 117     super.undo();
 118
 119     for (int i = edits.size() - 1; i >= 0; i--)
 120       ((UndoableEdit) edits.elementAt(i)).undo();
 121   }
 122
 123
 124   /**
 125    * Redoes all edits that are part of of this
 126    * <code>CompoundEdit</code>. The compound elements will receive the
 127    * <code>undo</code> message in the same order as they were added.
 128    *
 129    * @throws CannotRedoException if {@link #canRedo()} returns
 130    * <code>false</code>. This can happen if {@link #end()} has not
 131    * been called on this <code>CompoundEdit</code>, or if this edit
 132    * has already been redone.
 133    *
 134    * @see #canRedo()
 135    * @see #undo()
 136    */
 137   public void redo()
 138     throws CannotRedoException
 139   {
 140     // AbstractUndoableEdit.redo() will throw a CannotRedoException if
 141     // canRedo returns false.
 142     super.redo();
 143
 144     for (int i = 0; i < edits.size(); i++)
 145       ((UndoableEdit) edits.elementAt(i)).redo();
 146   }
 147
 148
 149   /**
 150    * Returns the the <code>UndoableEdit</code> that was last added to
 151    * this compound.
 152    */
 153   protected UndoableEdit lastEdit()
 154   {
 155     if (edits.size() == 0)
 156       return null;
 157     else
 158       return (UndoableEdit) edits.elementAt(edits.size() - 1);
 159   }
 160
 161
 162   /**
 163    * Informs this edit action, and all compound edits, that they will
 164    * no longer be used. Some actions might use this information to
 165    * release resources such as open files.  Called by {@link
 166    * UndoManager} before this action is removed from the edit queue.
 167    *
 168    * <p>The compound elements will receive the
 169    * <code>die</code> message in the reverse order of addition.
 170    */
 171   public void die()
 172   {
 173     for (int i = edits.size() - 1; i >= 0; i--)
 174       ((UndoableEdit) edits.elementAt(i)).die();
 175
 176     super.die();
 177   }
 178
 179
 180   /**
 181    * Incorporates another editing action into this one, thus forming a
 182    * combined edit.
 183    *
 184    * <p>If this edit&#x2019;s {@link #end()} method has been called
 185    * before, <code>false</code> is returned immediately. Otherwise,
 186    * the {@linkplain #lastEdit() last added edit} is given the
 187    * opportunity to {@linkplain UndoableEdit#addEdit(UndoableEdit)
 188    * incorporate} <code>edit</code>.  If this fails, <code>edit</code>
 189    * is given the opportunity to {@linkplain
 190    * UndoableEdit#replaceEdit(UndoableEdit) replace} the last added
 191    * edit.  If this fails as well, <code>edit</code> gets added as a
 192    * new compound to {@link #edits}.
 193    *
 194    * @param edit the editing action being added.
 195    *
 196    * @return <code>true</code> if <code>edit</code> could somehow be
 197    * incorporated; <code>false</code> if <code>edit</code> has not
 198    * been incorporated because {@link #end()} was called before.
 199    */
 200   public boolean addEdit(UndoableEdit edit)
 201   {
 202     UndoableEdit last;
 203
 204     // If end has been called before, do nothing.
 205     if (!inProgress)
 206       return false;
 207
 208     last = lastEdit();
 209
 210     // If edit is the very first edit, just add it to the list.
 211     if (last == null)
 212     {
 213       edits.add(edit);
 214       return true;
 215     }
 216
 217     // Try to incorporate edit into last.
 218     if (last.addEdit(edit))
 219       return true;
 220
 221     // Try to replace last by edit.
 222     if (edit.replaceEdit(last))
 223     {
 224       edits.set(edits.size() - 1, edit);
 225       return true;
 226     }
 227
 228     // If everything else has failed, add edit to the list of compound
 229     // edits.
 230     edits.add(edit);
 231     return true;
 232   }
 233
 234
 235   /**
 236    * Informs this <code>CompoundEdit</code> that its construction
 237    * phase has been completed. After this method has been called,
 238    * {@link #undo()} and {@link #redo()} may be called, {@link
 239    * #isInProgress()} will return <code>false</code>, and all attempts
 240    * to {@linkplain #addEdit(UndoableEdit) add further edits} will
 241    * fail.
 242    */
 243   public void end()
 244   {
 245     inProgress = false;
 246   }
 247
 248
 249   /**
 250    * Determines whether it would be possible to undo this editing
 251    * action. The result will be <code>true</code> if {@link #end()}
 252    * has been called on this <code>CompoundEdit</code>, {@link #die()}
 253    * has not yet been called, and the edit has not been undone
 254    * already.
 255    *
 256    * @return <code>true</code> to indicate that this action can be
 257    * undone; <code>false</code> otherwise.
 258    *
 259    * @see #undo()
 260    * @see #canRedo()
 261    */
 262   public boolean canUndo()
 263   {
 264     return !inProgress && super.canUndo();
 265   }
 266
 267
 268   /**
 269    * Determines whether it would be possible to redo this editing
 270    * action. The result will be <code>true</code> if {@link #end()}
 271    * has been called on this <code>CompoundEdit</code>, {@link #die()}
 272    * has not yet been called, and the edit has not been redone
 273    * already.
 274    *
 275    * @return <code>true</code> to indicate that this action can be
 276    * redone; <code>false</code> otherwise.
 277    *
 278    * @see #redo()
 279    * @see #canUndo()
 280    */
 281   public boolean canRedo()
 282   {
 283     return !inProgress && super.canRedo();
 284   }
 285
 286
 287   /**
 288    * Determines whether the initial construction phase of this
 289    * <code>CompoundEdit</code> is still in progress.  During this
 290    * phase, edits {@linkplain #addEdit(UndoableEdit) may be
 291    * added}. After initialization has been terminated by calling
 292    * {@link #end()}, {@link #undo()} and {@link #redo()} can be used.
 293    *
 294    * @return <code>true</code> if the initialization phase is still in
 295    * progress; <code>false</code> if {@link #end()} has been called.
 296    *
 297    * @see #end()
 298    */
 299   public boolean isInProgress()
 300   {
 301     return inProgress;
 302   }
 303
 304
 305   /**
 306    * Determines whether this editing action is significant enough for
 307    * being seperately undoable by the user. A typical significant
 308    * action would be the resizing of an object. However, changing the
 309    * selection in a text document would usually not be considered
 310    * significant.
 311    *
 312    * <p>A <code>CompoundEdit</code> is significant if any of its
 313    * elements are significant.
 314    */
 315   public boolean isSignificant()
 316   {
 317     for (int i = edits.size() - 1; i >= 0; i--)
 318       if (((UndoableEdit) edits.elementAt(i)).isSignificant())
 319         return true;
 320
 321     return false;
 322   }
 323
 324
 325   /**
 326    * Returns a human-readable, localized name that describes this
 327    * editing action and can be displayed to the user.
 328    *
 329    * <p>The implementation delegates the call to the {@linkplain
 330    * #lastEdit() last added edit action}. If no edit has been added
 331    * yet, the inherited implementation will be invoked, which always
 332    * returns an empty string.
 333    */
 334   public String getPresentationName()
 335   {
 336     UndoableEdit last;
 337
 338     last = lastEdit();
 339     if (last == null)
 340       return super.getPresentationName();
 341     else
 342       return last.getPresentationName();
 343   }
 344
 345
 346   /**
 347    * Calculates a localized message text for presenting the undo
 348    * action to the user.
 349    *
 350    * <p>The implementation delegates the call to the {@linkplain
 351    * #lastEdit() last added edit action}. If no edit has been added
 352    * yet, the {@linkplain
 353    * AbstractUndoableEdit#getUndoPresentationName() inherited
 354    * implementation} will be invoked.
 355    */
 356   public String getUndoPresentationName()
 357   {
 358     UndoableEdit last;
 359
 360     last = lastEdit();
 361     if (last == null)
 362       return super.getUndoPresentationName();
 363     else
 364       return last.getUndoPresentationName();
 365   }
 366
 367
 368   /**
 369    * Calculates a localized message text for presenting the redo
 370    * action to the user.
 371    *
 372    * <p>The implementation delegates the call to the {@linkplain
 373    * #lastEdit() last added edit action}. If no edit has been added
 374    * yet, the {@linkplain
 375    * AbstractUndoableEdit#getRedoPresentationName() inherited
 376    * implementation} will be invoked.
 377    */
 378   public String getRedoPresentationName()
 379   {
 380     UndoableEdit last;
 381
 382     last = lastEdit();
 383     if (last == null)
 384       return super.getRedoPresentationName();
 385     else
 386       return last.getRedoPresentationName();
 387   }
 388
 389
 390   /**
 391    * Calculates a string that may be useful for debugging.
 392    */
 393   public String toString()
 394   {
 395     return super.toString()
 396       + " inProgress: " + inProgress
 397       + " edits: " + edits;
 398   }
 399 }