Adding more JavaDoc to Cell explaining how a singleton instance of Cell will behave if used in multiple Columns or Cell Widgets. The text comes from a rather brilliant email I recently authored. Also removing some stale JavaDoc about Cell view data from the Column class. Columns were originally responsible for ViewData, but that was changed before the first release of Cell Widgets.
Review at http://gwt-code-reviews.appspot.com/1515804
Review by: rjrjr@google.com
git-svn-id: https://google-web-toolkit.googlecode.com/svn/trunk@10507 8db76d5a-ed1c-0410-87a9-c151d255dfc7
diff --git a/user/src/com/google/gwt/cell/client/Cell.java b/user/src/com/google/gwt/cell/client/Cell.java
index f5ea607..66e02ca 100644
--- a/user/src/com/google/gwt/cell/client/Cell.java
+++ b/user/src/com/google/gwt/cell/client/Cell.java
@@ -22,7 +22,41 @@
import java.util.Set;
/**
- * A light weight representation of a renderable object.
+ * A lightweight representation of a renderable object.
+ *
+ * <p>
+ * Multiple cell widgets or Columns can share a single Cell instance, but there
+ * may be implications for certain stateful Cells. Generally, Cells are
+ * stateless flyweights that see the world as row values/keys. If a Column
+ * contains duplicate row values/keys, the Cell will not differentiate the value
+ * in one row versus another. Similarly, if you use a single Cell instance in
+ * multiple Columns, the Cells will not differentiate the values coming from one
+ * Column versus another.
+ * </p>
+ *
+ * <p>
+ * However, some interactive Cells ({@link EditTextCell}, {@link CheckboxCell},
+ * {@link TextInputCell}, etc...) have a stateful "pending" state, which is a
+ * map of row values/keys to the end user entered pending value. For example, if
+ * an end user types a new value in a {@link TextInputCell}, the
+ * {@link TextInputCell} maps the "pending value" and associates it with the
+ * original row value/key. The next time the Cell Widget renders that row
+ * value/key, the Cell renders the pending value instead. This allows
+ * applications to refresh the Cell Widget without clearing out all of the end
+ * user's pending changes. In subclass of {@link AbstractEditableCell}, the
+ * pending state remains until either the original value is updated (a
+ * successful commit), or until
+ * {@link AbstractEditableCell#clearViewData(Object)} is called (a failed
+ * commit).
+ * </p>
+ *
+ * <p>
+ * If you share an interactive Cell between two cell widgets (or Columns within
+ * the same CellTable), then when the end user updates the pending value in one
+ * widget, it will be reflected in the other widget <i>when the other widget is
+ * redrawn</i>. You should base your decision on whether or not to share Cell
+ * instances on this behavior.
+ * </p>
*
* <p>
* <h3>Example</h3>
diff --git a/user/src/com/google/gwt/user/cellview/client/Column.java b/user/src/com/google/gwt/user/cellview/client/Column.java
index 8fe3a8b..51c75b7 100644
--- a/user/src/com/google/gwt/user/cellview/client/Column.java
+++ b/user/src/com/google/gwt/user/cellview/client/Column.java
@@ -26,10 +26,7 @@
import com.google.gwt.user.client.ui.HasAlignment;
/**
- * A representation of a column in a table. The column may maintain view data
- * for each cell on demand. New view data, if needed, is created by the cell's
- * onBrowserEvent method, stored in the Column, and passed to future calls to
- * Cell's {@link Cell#onBrowserEvent} and {@link Cell#render} methods.
+ * A representation of a column in a table.
*
* @param <T> the row type
* @param <C> the column type
