LGTM On Mon, Aug 8, 2011 at 11:24 AM, <[email protected]> wrote:
> Reviewers: rjrjr, > > Description: > 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. > > > Please review this at > http://gwt-code-reviews.**appspot.com/1515804/<http://gwt-code-reviews.appspot.com/1515804/> > > Affected files: > M user/src/com/google/gwt/cell/**client/Cell.java > M user/src/com/google/gwt/user/**cellview/client/Column.java > > > Index: user/src/com/google/gwt/cell/**client/Cell.java > ==============================**==============================**======= > --- user/src/com/google/gwt/cell/**client/Cell.java (revision 10506) > +++ user/src/com/google/gwt/cell/**client/Cell.java (working copy) > @@ -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> > Index: user/src/com/google/gwt/user/**cellview/client/Column.java > ==============================**==============================**======= > --- user/src/com/google/gwt/user/**cellview/client/Column.java > (revision 10506) > +++ user/src/com/google/gwt/user/**cellview/client/Column.java (working > copy) > @@ -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
