com.google.gwt.cell.client.Cell Maven / Gradle / Ivy
/*
* Copyright 2010 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.google.gwt.cell.client;
import com.google.gwt.dom.client.Element;
import com.google.gwt.dom.client.NativeEvent;
import com.google.gwt.safehtml.shared.SafeHtmlBuilder;
import java.util.Set;
/**
* 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 ({@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).
*
*
*
* 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
* {@example com.google.gwt.examples.cell.CellExample}
*
*
*
* Warning: The Cell interface may change in subtle but breaking ways as we
* continuously seek to improve performance. You should always subclass {@link AbstractCell} instead
* of implementing {@link Cell} directly.
*
*
* @param the type that this Cell represents
*/
public interface Cell {
/**
* Contains information about the context of the Cell.
*/
public static class Context {
private final int column;
private final int index;
private final Object key;
private final int subindex;
/**
* Create a new {@link Context}.
*
* @param index the absolute index of the value
* @param column the column index of the cell, or 0
* @param key the unique key that represents the row value
*/
public Context(int index, int column, Object key) {
this(index, column, key, 0);
}
/**
* Create a new {@link Context}.
*
* @param index the absolute index of the value
* @param column the column index of the cell, or 0
* @param key the unique key that represents the row value
* @param subindex the child index
*/
public Context(int index, int column, Object key, int subindex) {
this.index = index;
this.column = column;
this.key = key;
this.subindex = subindex;
}
/**
* Get the column index of the cell. If the view only contains a single
* column, this method returns 0.
*
* @return the column index of the cell
*/
public int getColumn() {
return column;
}
/**
* Get the absolute index of the value.
*
* @return the index
*/
public int getIndex() {
return index;
}
/**
* Get the key that uniquely identifies the row object.
*
* @return the unique key
*/
public Object getKey() {
return key;
}
/**
* Get the sub index of the rendered row value. If the row value renders to
* a single row element, the sub index is 0. If the row value renders to
* more than one row element, the sub index may be greater than zero.
*/
public int getSubIndex() {
return subindex;
}
}
/**
* Check if this cell depends on the selection state.
*
* @return true if dependent on selection, false if not
*/
boolean dependsOnSelection();
/**
* Get the set of events that this cell consumes (see
* {@link com.google.gwt.dom.client.BrowserEvents BrowserEvents} for useful
* constants). The container that uses this cell should only pass these events
* to
* {@link #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.
*
*
* @return the consumed events, or null if no events are consumed
*
* @see com.google.gwt.dom.client.BrowserEvents
*/
Set getConsumedEvents();
/**
* Check if this cell handles selection. If the cell handles selection, then
* its container should not automatically handle selection.
*
* @return true if the cell handles selection, false if not
*/
boolean handlesSelection();
/**
* 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.
*
* @param context the {@link Context} of the cell
* @param parent the parent Element
* @param value the value associated with the cell
* @return true if the cell is in edit mode
*/
boolean isEditing(Context context, Element parent, C value);
/**
* Handle a browser event that took place within the cell. The default
* implementation returns null.
*
* @param context the {@link Context} of the cell
* @param parent the parent Element
* @param value the value associated with the cell
* @param event the native browser event
* @param valueUpdater a {@link ValueUpdater}, or null if not specified
*/
void onBrowserEvent(Context context, Element parent, C value, NativeEvent event,
ValueUpdater valueUpdater);
/**
* Render a cell as HTML into a {@link SafeHtmlBuilder}, suitable for passing
* to {@link 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.
*
*
* @param context the {@link Context} of the cell
* @param value the cell value to be rendered
* @param sb the {@link SafeHtmlBuilder} to be written to
*/
void render(Context context, C value, SafeHtmlBuilder sb);
/**
* Reset focus on the Cell. This method is called if the cell has focus when
* it is refreshed.
*
* @param context the {@link Context} of the cell
* @param parent the parent Element
* @param value the value associated with the cell
* @return true if focus is taken, false if not
*/
boolean resetFocus(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 {@link Element#setInnerHTML(String)}. See
* {@link AbstractCell#setValue(Context, Element, Object)} for a default
* implementation that uses {@link #render(Context, Object, SafeHtmlBuilder)}.
*
* @param context the {@link Context} of the cell
* @param parent the parent Element
* @param value the value associated with the cell
*/
void setValue(Context context, Element parent, C value);
}