2003-11-26 Sascha Brawer <brawer@dandelis.ch>

	* javax/swing/undo/StateEdit.java (getPresentationName): Docfix.
	* javax/swing/undo/AbstractUndoableEdit.java (canUndo, canRedo,
	isSignificant): Likewise.

2003-11-26  Sascha Brawer  <brawer@dandelis.ch>

	* javax/swing/undo/CompoundEdit.java: Re-format, document.
	(inProgress): Set initial value to true.
	(undo, redo, die, canUndo, canRedo): Also call inherited
	implementation; simplify code structure.
	(getPresentationName, getUndoPresentationName,
	getRedoPresentationName): Make behavior dependent on lastEdit.
	(addEdit, isSignificant): Completely re-written.

2003-11-26  Sascha Brawer  <brawer@dandelis.ch>

	* javax/swing/undo/StateEdit.java: Re-format, document.
	(undo, redo): Also call inherited implementation.

2003-11-26  Sascha Brawer  <brawer@dandelis.ch>

	* javax/swing/undo/StateEditable.java: Re-format, document.

2003-11-26  Sascha Brawer  <brawer@dandelis.ch>

	* javax/swing/undo/AbstractUndoableEdit.java: Re-format, document.
	(AbstractUndoableEdit): Initialize hasBeenDone to true.
	(canUndo, canRedo): Simplify.
	(getUndoPresentationName, getRedoPresentationName): Support
	localized message; call getPresentationName() only once.


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@73967 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 122 insertions, 38 deletions

diff --git a/libjava/javax/swing/undo/StateEdit.java b/libjava/javax/swing/undo/StateEdit.java
index 6a32fbdb48d..00f1e2d830c 100644
--- a/libjava/javax/swing/undo/StateEdit.java
+++ b/libjava/javax/swing/undo/StateEdit.java
@@ -1,4 +1,4 @@
-/* StateEdit.java --
+/* StateEdit.java -- UndoableEdit for StateEditable implementations.
    Copyright (C) 2002, 2003 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
@@ -42,59 +42,118 @@ import java.util.Hashtable;
 import java.util.Iterator;
 
 /**
- * StateEdit
- * @author	Andrew Selkirk
+ * A helper class, making it easy to support undo and redo.
+ *
+ * <p>The following example shows how to use this class.
+ *
+ * <pre>  Foo foo; // class Foo implements {@link StateEditable}
+ *  StateEdit edit;
+ *
+ *  edit = new StateEdit(foo, "Name Change");
+ *  foo.setName("Jane Doe");
+ *  edit.end();
+ *  undoManager.addEdit(edit);</pre>
+ *
+ * <p>If <code>Foo</code>&#x2019;s implementation of {@link
+ * StateEditable} considers the name as part of the editable state,
+ * the user can now choose &#x201c;Undo Name Change&#x201d; or
+ * &#x201c;Redo Name Change&#x201d; from the respective menu. No
+ * further undo support is needed from the application.
+ *
+ * <p>The following explains what happens in the example.
+ *
+ * <p><ol><li>When a <code>StateEdit</code> is created, the associated
+ * {@link StateEditable} gets asked to store its state into a hash
+ * table, {@link #preState}.</li>
+ *
+ * <li>The application will now perform some changes to the edited
+ * object.  This typically happens by invoking methods on the edited
+ * object.</li>
+ *
+ * <li>The editing phase is terminated by invoking the {@link #end()}
+ * method of the <code>StateEdit</code>. The <code>end()</code> method
+ * does two things.
+ *
+ *   <ul><li>The edited object receives a second request for storing
+ *   its state.  This time, it will use a different hash table, {@link
+ *   #postState}.</li>
+ *
+ *   <li>To increase efficiency, the <code>StateEdit</code> now removes
+ *   any entries from {@link #preState} and {@link #postState} that have
+ *   the same key, and whose values are equal. Equality is determined
+ *   by invoking the <code>equals</code> method inherited from
+ *   {@link java.lang.Object}.</li></ul></li>
+ *
+ * <li>When the user later chooses to undo the <code>StateEdit</code>,
+ * the edited object is asked to {@linkplain StateEditable#restoreState
+ * restore its state} from the {@link #preState} table.  Similarly,
+ * when the user chooses to <i>redo</i> the <code>StateEdit</code>,
+ * the edited object gets asked to restore its state from the {@link
+ * #postState}.</li></ol>
+ *
+ * @author Andrew Selkirk (aselkirk@sympatico.ca)
+ * @author Sascha Brawer (brawer@dandelis.ch)
  */
-public class StateEdit extends AbstractUndoableEdit
+public class StateEdit
+  extends AbstractUndoableEdit
 {
-
-  //-------------------------------------------------------------
-  // Variables --------------------------------------------------
-  //-------------------------------------------------------------
-
   /**
-   * RCSID
+   * The ID of the Java source file in Sun&#x2019;s Revision Control
+   * System (RCS).  This certainly should not be part of the API
+   * specification. But in order to be API-compatible with
+   * Sun&#x2019;s reference implementation, GNU Classpath also has to
+   * provide this field. However, we do not try to match its value.
    */
-  protected static final String RCSID = ""; // TODO
+  protected static final String RCSID = "";
+
 
   /**
-   * object
+   * The object which is being edited by this <code>StateEdit</code>.
    */
   protected StateEditable object;
 
+
   /**
-   * preState
+   * The state of <code>object</code> at the time of constructing
+   * this <code>StateEdit</code>.
    */
   protected Hashtable preState;
 
+
   /**
-   * postState
+   * The state of <code>object</code> at the time when {@link #end()}
+   * was called.
    */
   protected Hashtable postState;
 
+
   /**
-   * undoRedoName
+   * A human-readable name for this edit action.
    */
   protected String undoRedoName;
 
 
-  //-------------------------------------------------------------
-  // Initialization ---------------------------------------------
-  //-------------------------------------------------------------
-
   /**
-   * Constructor StateEdit
-   * @param obj Object to edit
+   * Constructs a <code>StateEdit</code>, specifying the object whose
+   * state is being edited.
+   *
+   * @param obj the object whose state is being edited by this
+   * <code>StateEdit</code>.
    */
   public StateEdit(StateEditable obj)
   {
     init(obj, null);
   }
 
+
   /**
-   * Constructor StateEdit
-   * @param obj Object to edit
-   * @param name Presentation name
+   * Constructs a <code>StateEdit</code>, specifying the object whose
+   * state is being edited.
+   *
+   * @param obj the object whose state is being edited by this
+   * <code>StateEdit</code>.
+   *
+   * @param name the human-readable name of the editing action.
    */
   public StateEdit(StateEditable obj, String name)
   {
@@ -102,14 +161,13 @@ public class StateEdit extends AbstractUndoableEdit
   }
 
 
-  //-------------------------------------------------------------
-  // Methods ----------------------------------------------------
-  //-------------------------------------------------------------
-
   /**
-   * Initialize this object.
-   * @param obj Object to edit
-   * @param name Presentation name
+   * Initializes this <code>StateEdit</code>. The edited object will
+   * be asked to store its current state into {@link #preState}.
+   *
+   * @param obj the object being edited.
+   *
+   * @param name the human-readable name of the editing action.
    */
   protected void init(StateEditable obj, String name)
   {
@@ -120,9 +178,12 @@ public class StateEdit extends AbstractUndoableEdit
     obj.storeState(preState);
   }
 
+
   /**
-   * Indicate that all edits are finished, and update this object
-   * with final state.
+   * Informs this <code>StateEdit</code> that all edits are finished.
+   * The edited object will be asked to store its state into {@link
+   * #postState}, and any redundant entries will get removed from
+   * {@link #preState} and {@link #postState}.
    */
   public void end()
   {
@@ -130,33 +191,56 @@ public class StateEdit extends AbstractUndoableEdit
     removeRedundantState();
   }
 
+
   /**
-   * Undo this edit by applying the initial state to the edited object.
+   * Undoes this edit operation. The edited object will be asked to
+   * {@linkplain StateEditable#restoreState restore its state} from
+   * {@link #preState}.
+   *
+   * @throws CannotUndoException if {@link #canUndo()} returns
+   * <code>false</code>, for example because this action has already
+   * been undone.
    */
   public void undo()
   {
+    super.undo();
     object.restoreState(preState);
   }
 
+
   /**
-   * Undo this edit by applying the final state to the edited object.
+   * Redoes this edit operation. The edited object will be asked to
+   * {@linkplain StateEditable#restoreState restore its state} from
+   * {@link #postState}.
+   *
+   * @throws CannotRedoException if {@link #canRedo()} returns
+   * <code>false</code>, for example because this action has not yet
+   * been undone.
    */
   public void redo()
   {
+    super.redo();
     object.restoreState(postState);
   }
 
+
   /**
-   * Return the presentation name of this object.
-   * @returns The name, or null if not set
+   * Returns a human-readable, localized name that describes this
+   * editing action and can be displayed to the user.
+   *
+   * @return the name, or <code>null</code> if no presentation
+   * name is available.
    */
   public String getPresentationName()
   {
     return undoRedoName;
   }
 
+
   /**
-   * removeRedundantState
+   * Removes all redundant entries from the pre- and post-edit state
+   * hash tables. An entry is considered redundant if it is present
+   * both before and after the edit, and if the two values are equal.
    */
   protected void removeRedundantState()
   {