com.google.gwt.cell.client

## Interface Cell<C>

- Type Parameters:
    `C` - the type that this Cell represents
  All Known Implementing Classes:
    AbstractCell, AbstractEditableCell, AbstractInputCell, AbstractSafeHtmlCell, ActionCell, ButtonCell, ButtonCellBase, CheckboxCell, ClickableTextCell, CompositeCell, DateCell, DatePickerCell, EditTextCell, IconCellDecorator, ImageCell, ImageLoadingCell, ImageResourceCell, NumberCell, SafeHtmlCell, SafeImageCell, SelectionCell, TextButtonCell, TextCell, TextInputCell

      public interface Cell<C>

  A lightweight representation of a renderable object.

  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.

  However, some interactive Cells (`EditTextCell`, `CheckboxCell`, `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 `TextInputCell`, the `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 `AbstractEditableCell`, the pending state remains until either the original value is updated (a successful commit), or until `AbstractEditableCell.clearViewData(Object)` is called (a failed commit).

  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 when the other widget is redrawn. You should base your decision on whether or not to share Cell instances on this behavior.

  ### Example

  >     public class CellExample implements EntryPoint {

  >       /**
  >        * A custom {@link Cell} used to render a string that contains the name of a
  >        * color.
  >        */
  >       static class ColorCell extends AbstractCell<String> {

  >         /**
  >          * The HTML templates used to render the cell.
  >          */
  >         interface Templates extends SafeHtmlTemplates {
  >           /**
  >            * The template for this Cell, which includes styles and a value.
  >            *
  >            * @param styles the styles to include in the style attribute of the div
  >            * @param value the safe value. Since the value type is {@link SafeHtml},
  >            *          it will not be escaped before including it in the template.
  >            *          Alternatively, you could make the value type String, in which
  >            *          case the value would be escaped.
  >            * @return a {@link SafeHtml} instance
  >            */
  >           @SafeHtmlTemplates.Template("<div style=\"{0}\">{1}</div>")
  >           SafeHtml cell(SafeStyles styles, SafeHtml value);
  >         }

  >         /**
  >          * Create a singleton instance of the templates used to render the cell.
  >          */
  >         private static Templates templates = GWT.create(Templates.class);

  >         @Override
  >         public void render(Context context, String value, SafeHtmlBuilder sb) {
  >           /*
  >            * Always do a null check on the value. Cell widgets can pass null to
  >            * cells if the underlying data contains a null, or if the data arrives
  >            * out of order.
  >            */
  >           if (value == null) {
  >             return;
  >           }

  >           // If the value comes from the user, we escape it to avoid XSS attacks.
  >           SafeHtml safeValue = SafeHtmlUtils.fromString(value);

  >           // Use the template to create the Cell's html.
  >           SafeStyles styles = SafeStylesUtils.forTrustedColor(safeValue.asString());
  >           SafeHtml rendered = templates.cell(styles, safeValue);
  >           sb.append(rendered);
  >         }
  >       }

  >       /**
  >        * The list of data to display.
  >        */
  >       private static final List<String> COLORS = Arrays.asList("red", "green", "blue", "violet",
  >           "black", "gray");

  >       @Override
  >       public void onModuleLoad() {
  >         // Create a cell to render each value.
  >         ColorCell cell = new ColorCell();

  >         // Use the cell in a CellList.
  >         CellList<String> cellList = new CellList<String>(cell);

  >         // Push the data into the widget.
  >         cellList.setRowData(0, COLORS);

  >         // Add it to the root panel.
  >         RootPanel.get().add(cellList);
  >       }
  >     }

  Warning: The Cell interface may change in subtle but breaking ways as we continuously seek to improve performance. You should always subclass `AbstractCell` instead of implementing `Cell` directly.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `Cell.Context` Contains information about the context of the Cell.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `dependsOnSelection()` Check if this cell depends on the selection state.
    `java.util.Set<java.lang.String>` | `getConsumedEvents()` Get the set of events that this cell consumes (see `BrowserEvents` for useful constants).
    `boolean` | `handlesSelection()` Check if this cell handles selection.
    `boolean` | `isEditing(Cell.Context context, Element parent, C value)` Returns true if the cell is currently editing the data identified by the given element and key.
    `void` | `onBrowserEvent(Cell.Context context, Element parent, C value, NativeEvent event, ValueUpdater<C> valueUpdater)` Handle a browser event that took place within the cell.
    `void` | `render(Cell.Context context, C value, SafeHtmlBuilder sb)` Render a cell as HTML into a `SafeHtmlBuilder`, suitable for passing to `Element.setInnerHTML(String)` on a container element.
    `boolean` | `resetFocus(Cell.Context context, Element parent, C value)` Reset focus on the Cell.
    `void` | `setValue(Cell.Context context, Element parent, C value)` This method may be used by cell containers to set the value on a single cell directly, rather than using `Element.setInnerHTML(String)`.

- - ### Method Detail

    - #### dependsOnSelection

          boolean dependsOnSelection()

      Check if this cell depends on the selection state.
      Returns:
        true if dependent on selection, false if not

    - #### getConsumedEvents

          java.util.Set<java.lang.String> getConsumedEvents()

      Get the set of events that this cell consumes (see `BrowserEvents` for useful constants). The container that uses this cell should only pass these events to `onBrowserEvent(Context, Element, Object, NativeEvent, ValueUpdater)` when the event occurs.

      The returned value should not be modified, and may be an unmodifiable set. Changes to the return value may not be reflected in the cell.

      Returns:
        the consumed events, or null if no events are consumed
      See Also:
        `BrowserEvents`

    - #### handlesSelection

          boolean handlesSelection()

      Check if this cell handles selection. If the cell handles selection, then its container should not automatically handle selection.
      Returns:
        true if the cell handles selection, false if not

    - #### isEditing

          boolean isEditing(Cell.Context context,
                          Element parent,
                          C value)

      Returns true if the cell is currently editing the data identified by the given element and key. While a cell is editing, widgets containing the cell may choose to pass keystrokes directly to the cell rather than using them for navigation purposes.
      Parameters:
        `context` - the `Cell.Context` of the cell
        `parent` - the parent Element
        `value` - the value associated with the cell
      Returns:
        true if the cell is in edit mode

    - #### onBrowserEvent

          void onBrowserEvent(Cell.Context context,
                            Element parent,
                            C value,
                            NativeEvent event,
                            ValueUpdater<C> valueUpdater)

      Handle a browser event that took place within the cell. The default implementation returns null.
      Parameters:
        `context` - the `Cell.Context` of the cell
        `parent` - the parent Element
        `value` - the value associated with the cell
        `event` - the native browser event
        `valueUpdater` - a `ValueUpdater`, or null if not specified

    - #### render

          void render(Cell.Context context,
                    C value,
                    SafeHtmlBuilder sb)

      Render a cell as HTML into a `SafeHtmlBuilder`, suitable for passing to `Element.setInnerHTML(String)` on a container element.

      Note: If your cell contains natively focusable elements, such as buttons or input elements, be sure to set the tabIndex to -1 so that they do not steal focus away from the containing widget.

      Parameters:
        `context` - the `Cell.Context` of the cell
        `value` - the cell value to be rendered
        `sb` - the `SafeHtmlBuilder` to be written to

    - #### resetFocus

          boolean resetFocus(Cell.Context context,
                           Element parent,
                           C value)

      Reset focus on the Cell. This method is called if the cell has focus when it is refreshed.
      Parameters:
        `context` - the `Cell.Context` of the cell
        `parent` - the parent Element
        `value` - the value associated with the cell
      Returns:
        true if focus is taken, false if not

    - #### setValue

          void setValue(Cell.Context context,
                      Element parent,
                      C value)

      This method may be used by cell containers to set the value on a single cell directly, rather than using `Element.setInnerHTML(String)`. See `setValue(Context, Element, Object)` for a default implementation that uses `render(Context, Object, SafeHtmlBuilder)`.
      Parameters:
        `context` - the `Cell.Context` of the cell
        `parent` - the parent Element
        `value` - the value associated with the cell