Revision: 10507
Author: [email protected]
Date: Mon Aug 8 09:10:15 2011
Log: 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: [email protected]
http://code.google.com/p/google-web-toolkit/source/detail?r=10507
Modified:
/trunk/user/src/com/google/gwt/cell/client/Cell.java
/trunk/user/src/com/google/gwt/user/cellview/client/Column.java
=======================================
--- /trunk/user/src/com/google/gwt/cell/client/Cell.java Thu Jul 28
04:03:54 2011
+++ /trunk/user/src/com/google/gwt/cell/client/Cell.java Mon Aug 8
09:10:15 2011
@@ -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>
=======================================
--- /trunk/user/src/com/google/gwt/user/cellview/client/Column.java Tue
Aug 2 07:46:31 2011
+++ /trunk/user/src/com/google/gwt/user/cellview/client/Column.java Mon
Aug 8 09:10:15 2011
@@ -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
--
http://groups.google.com/group/Google-Web-Toolkit-Contributors
