toolchain/gcc/libjava/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., 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.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.
  48  *
  49  * <pre>  Foo foo; // class Foo implements {@link StateEditable}
  50  *  StateEdit edit;
  51  *
  52  *  edit = new StateEdit(foo, "Name Change");
  53  *  foo.setName("Jane Doe");
  54  *  edit.end();
  55  *  undoManager.addEdit(edit);</pre>
  56  *
  57  * <p>If <code>Foo</code>&#x2019;s implementation of {@link
  58  * StateEditable} considers the name as part of the editable state,
  59  * the user can now choose &#x201c;Undo Name Change&#x201d; or
  60  * &#x201c;Redo Name Change&#x201d; from the respective menu. No
  61  * further undo support is needed from the application.
  62  *
  63  * <p>The following explains what happens in the example.
  64  *
  65  * <p><ol><li>When a <code>StateEdit</code> is created, the associated
  66  * {@link StateEditable} gets asked to store its state into a hash
  67  * table, {@link #preState}.</li>
  68  *
  69  * <li>The application will now perform some changes to the edited
  70  * object.  This typically happens by invoking methods on the edited
  71  * object.</li>
  72  *
  73  * <li>The editing phase is terminated by invoking the {@link #end()}
  74  * method of the <code>StateEdit</code>. The <code>end()</code> method
  75  * does two things.
  76  *
  77  *   <ul><li>The edited object receives a second request for storing
  78  *   its state.  This time, it will use a different hash table, {@link
  79  *   #postState}.</li>
  80  *
  81  *   <li>To increase efficiency, the <code>StateEdit</code> now removes
  82  *   any entries from {@link #preState} and {@link #postState} that have
  83  *   the same key, and whose values are equal. Equality is determined
  84  *   by invoking the <code>equals</code> method inherited from
  85  *   {@link java.lang.Object}.</li></ul></li>
  86  *
  87  * <li>When the user later chooses to undo the <code>StateEdit</code>,
  88  * the edited object is asked to {@linkplain StateEditable#restoreState
  89  * restore its state} from the {@link #preState} table.  Similarly,
  90  * when the user chooses to <i>redo</i> the <code>StateEdit</code>,
  91  * the edited object gets asked to restore its state from the {@link
  92  * #postState}.</li></ol>
  93  *
  94  * @author Andrew Selkirk (aselkirk@sympatico.ca)
  95  * @author Sascha Brawer (brawer@dandelis.ch)
  96  */
  97 public class StateEdit
  98   extends AbstractUndoableEdit
  99 {
 100   /**
 101    * The ID of the Java source file in Sun&#x2019;s Revision Control
 102    * System (RCS).  This certainly should not be part of the API
 103    * specification. But in order to be API-compatible with
 104    * Sun&#x2019;s reference implementation, GNU Classpath also has to
 105    * provide this field. However, we do not try to match its value.
 106    */
 107   protected static final String RCSID = "";
 108
 109
 110   /**
 111    * The object which is being edited by this <code>StateEdit</code>.
 112    */
 113   protected StateEditable object;
 114
 115
 116   /**
 117    * The state of <code>object</code> at the time of constructing
 118    * this <code>StateEdit</code>.
 119    */
 120   protected Hashtable preState;
 121
 122
 123   /**
 124    * The state of <code>object</code> at the time when {@link #end()}
 125    * was called.
 126    */
 127   protected Hashtable postState;
 128
 129
 130   /**
 131    * A human-readable name for this edit action.
 132    */
 133   protected String undoRedoName;
 134
 135
 136   /**
 137    * Constructs a <code>StateEdit</code>, specifying the object whose
 138    * state is being edited.
 139    *
 140    * @param obj the object whose state is being edited by this
 141    * <code>StateEdit</code>.
 142    */
 143   public StateEdit(StateEditable obj)
 144   {
 145     init(obj, null);
 146   }
 147
 148
 149   /**
 150    * Constructs a <code>StateEdit</code>, specifying the object whose
 151    * state is being edited.
 152    *
 153    * @param obj the object whose state is being edited by this
 154    * <code>StateEdit</code>.
 155    *
 156    * @param name the human-readable name of the editing action.
 157    */
 158   public StateEdit(StateEditable obj, String name)
 159   {
 160     init(obj, name);
 161   }
 162
 163
 164   /**
 165    * Initializes this <code>StateEdit</code>. The edited object will
 166    * be asked to store its current state into {@link #preState}.
 167    *
 168    * @param obj the object being edited.
 169    *
 170    * @param name the human-readable name of the editing action.
 171    */
 172   protected void init(StateEditable obj, String name)
 173   {
 174     object = obj;
 175     undoRedoName = name;
 176     preState = new Hashtable();
 177     postState = new Hashtable();
 178     obj.storeState(preState);
 179   }
 180
 181
 182   /**
 183    * Informs this <code>StateEdit</code> that all edits are finished.
 184    * The edited object will be asked to store its state into {@link
 185    * #postState}, and any redundant entries will get removed from
 186    * {@link #preState} and {@link #postState}.
 187    */
 188   public void end()
 189   {
 190     object.storeState(postState);
 191     removeRedundantState();
 192   }
 193
 194
 195   /**
 196    * Undoes this edit operation. The edited object will be asked to
 197    * {@linkplain StateEditable#restoreState restore its state} from
 198    * {@link #preState}.
 199    *
 200    * @throws CannotUndoException if {@link #canUndo()} returns
 201    * <code>false</code>, for example because this action has already
 202    * been undone.
 203    */
 204   public void undo()
 205   {
 206     super.undo();
 207     object.restoreState(preState);
 208   }
 209
 210
 211   /**
 212    * Redoes this edit operation. The edited object will be asked to
 213    * {@linkplain StateEditable#restoreState restore its state} from
 214    * {@link #postState}.
 215    *
 216    * @throws CannotRedoException if {@link #canRedo()} returns
 217    * <code>false</code>, for example because this action has not yet
 218    * been undone.
 219    */
 220   public void redo()
 221   {
 222     super.redo();
 223     object.restoreState(postState);
 224   }
 225
 226
 227   /**
 228    * Returns a human-readable, localized name that describes this
 229    * editing action and can be displayed to the user.
 230    *
 231    * @return the name, or <code>null</code> if no presentation
 232    * name is available.
 233    */
 234   public String getPresentationName()
 235   {
 236     return undoRedoName;
 237   }
 238
 239
 240   /**
 241    * Removes all redundant entries from the pre- and post-edit state
 242    * hash tables. An entry is considered redundant if it is present
 243    * both before and after the edit, and if the two values are equal.
 244    */
 245   protected void removeRedundantState()
 246   {
 247     Iterator i = preState.keySet().iterator();
 248     while (i.hasNext())
 249       {
 250         Object key = i.next();
 251         if (postState.containsKey(key))
 252           {
 253             if (preState.get(key).equals(postState.get(key)))
 254               {
 255                 i.remove();
 256                 postState.remove(key);
 257               }
 258           }
 259       }
 260   }
 261 }