Overview  Package   Class  Use  Deprecated  Help 
GWT 2.7.0
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.google.gwt.user.cellview.client
Class CellList<T>

java.lang.Object
  extended by com.google.gwt.user.client.ui.UIObject
      extended by com.google.gwt.user.client.ui.Widget
          extended by com.google.gwt.user.client.ui.Composite
              extended by com.google.gwt.user.cellview.client.AbstractHasData<T>
                  extended by com.google.gwt.user.cellview.client.CellList<T>
Type Parameters:
T - the data type of list items
All Implemented Interfaces:
HasAttachHandlers, HasHandlers, HasKeyboardPagingPolicy, HasKeyboardSelectionPolicy, EventListener, Focusable, HasVisibility, IsRenderable, IsWidget, HasCellPreviewHandlers<T>, HasData<T>, HasKeyProvider<T>, HasRows
Direct Known Subclasses:
CellBrowser.BrowserCellList
public class CellList<T>
extends AbstractHasData<T>

A single column list of cells.

Examples

Trivial example
public class CellListExample implements EntryPoint {

  /**
   * The list of data to display.
   */
  private static final List<String> DAYS = Arrays.asList("Sunday", "Monday",
      "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday");

  public void onModuleLoad() {
    // Create a cell to render each value.
    TextCell textCell = new TextCell();

    // Create a CellList that uses the cell.
    CellList<String> cellList = new CellList<String>(textCell);
    cellList.setKeyboardSelectionPolicy(KeyboardSelectionPolicy.ENABLED);

    // Add a selection model to handle user selection.
    final SingleSelectionModel<String> selectionModel = new SingleSelectionModel<String>();
    cellList.setSelectionModel(selectionModel);
    selectionModel.addSelectionChangeHandler(new SelectionChangeEvent.Handler() {
      public void onSelectionChange(SelectionChangeEvent event) {
        String selected = selectionModel.getSelectedObject();
        if (selected != null) {
          Window.alert("You selected: " + selected);
        }
      }
    });

    // Set the total row count. This isn't strictly necessary, but it affects
    // paging calculations, so its good habit to keep the row count up to date.
    cellList.setRowCount(DAYS.size(), true);

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

    // Add it to the root panel.
    RootPanel.get().add(cellList);
  }
}
Handling user input with ValueUpdater
public class CellListValueUpdaterExample implements EntryPoint {

  /**
   * The list of data to display.
   */
  private static final List<String> DAYS = Arrays.asList("Sunday", "Monday",
      "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday");

  public void onModuleLoad() {
    // Create a cell that will interact with a value updater.
    TextInputCell inputCell = new TextInputCell();

    // Create a CellList that uses the cell.
    CellList<String> cellList = new CellList<String>(inputCell);

    // Create a value updater that will be called when the value in a cell
    // changes.
    ValueUpdater<String> valueUpdater = new ValueUpdater<String>() {
      public void update(String newValue) {
        Window.alert("You typed: " + newValue);
      }
    };

    // Add the value updater to the cellList.
    cellList.setValueUpdater(valueUpdater);

    // Set the total row count. This isn't strictly necessary, but it affects
    // paging calculations, so its good habit to keep the row count up to date.
    cellList.setRowCount(DAYS.size(), true);

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

    // Add it to the root panel.
    RootPanel.get().add(cellList);
  }
}
Pushing data with List Data Provider (backed by List)
public class ListDataProviderExample implements EntryPoint {

  public void onModuleLoad() {
    // Create a CellList.
    CellList<String> cellList = new CellList<String>(new TextCell());

    // Create a list data provider.
    final ListDataProvider<String> dataProvider = new ListDataProvider<String>();

    // Add the cellList to the dataProvider.
    dataProvider.addDataDisplay(cellList);

    // Create a form to add values to the data provider.
    final TextBox valueBox = new TextBox();
    valueBox.setText("Enter new value");
    Button addButton = new Button("Add value", new ClickHandler() {
      public void onClick(ClickEvent event) {
        // Get the value from the text box.
        String newValue = valueBox.getText();

        // Get the underlying list from data dataProvider.
        List<String> list = dataProvider.getList();

        // Add the value to the list. The dataProvider will update the cellList.
        list.add(newValue);
      }
    });

    // Add the widgets to the root panel.
    VerticalPanel vPanel = new VerticalPanel();
    vPanel.add(valueBox);
    vPanel.add(addButton);
    vPanel.add(cellList);
    RootPanel.get().add(vPanel);
  }
}
Pushing data asynchronously with Async Data Provider
public class AsyncDataProviderExample implements EntryPoint {

  /**
   * A custom {@link AsyncDataProvider}.
   */
  private static class MyDataProvider extends AsyncDataProvider<String> {
    /**
     * {@link #onRangeChanged(HasData)} is called when the table requests a new
     * range of data. You can push data back to the displays using
     * {@link #updateRowData(int, List)}.
     */
    @Override
    protected void onRangeChanged(HasData<String> display) {
      // Get the new range.
      final Range range = display.getVisibleRange();

      /*
       * Query the data asynchronously. If you are using a database, you can
       * make an RPC call here. We'll use a Timer to simulate a delay.
       */
      new Timer() {
        @Override
        public void run() {
          // We are creating fake data. Normally, the data will come from a
          // server.
          int start = range.getStart();
          int length = range.getLength();
          List<String> newData = new ArrayList<String>();
          for (int i = start; i < start + length; i++) {
            newData.add("Item " + i);
          }

          // Push the data to the displays. AsyncDataProvider will only update
          // displays that are within range of the data.
          updateRowData(start, newData);
        }
      }.schedule(3000);
    }
  }

  public void onModuleLoad() {
    // Create a CellList.
    CellList<String> cellList = new CellList<String>(new TextCell());

    // Create a data provider.
    MyDataProvider dataProvider = new MyDataProvider();

    // Add the cellList to the dataProvider.
    dataProvider.addDataDisplay(cellList);

    // Create paging controls.
    SimplePager pager = new SimplePager();
    pager.setDisplay(cellList);

    // Add the widgets to the root panel.
    VerticalPanel vPanel = new VerticalPanel();
    vPanel.add(pager);
    vPanel.add(cellList);
    RootPanel.get().add(vPanel);
  }
}
Writing a custom data provider
public class RangeChangeHandlerExample implements EntryPoint {

  @Override
  public void onModuleLoad() {
    // Create a CellList.
    final CellList<String> cellList = new CellList<String>(new TextCell());

    // Add a range change handler.
    cellList.addRangeChangeHandler(new RangeChangeEvent.Handler() {
      @Override
      public void onRangeChange(RangeChangeEvent event) {
        Range range = event.getNewRange();
        int start = range.getStart();
        int length = range.getLength();

        // Create the data to push into the view. At this point, you could send
        // an asynchronous RPC request to a server.
        List<String> data = new ArrayList<String>();
        for (int i = start; i < start + length; i++) {
          data.add("Item " + i);
        }

        // Push the data into the list.
        cellList.setRowData(start, data);
      }
    });

    // Force the cellList to fire an initial range change event.
    cellList.setVisibleRangeAndClearData(new Range(0, 25), true);

    // Create paging controls.
    SimplePager pager = new SimplePager();
    pager.setDisplay(cellList);

    // Add the widgets to the root panel.
    VerticalPanel vPanel = new VerticalPanel();
    vPanel.add(pager);
    vPanel.add(cellList);
    RootPanel.get().add(vPanel);
  }
}
Using a key provider to track objects as they change
public class KeyProviderExample implements EntryPoint {

  /**
   * A simple data type that represents a contact.
   */
  private static class Contact {
    private static int nextId = 0;

    private final int id;
    private String name;

    public Contact(String name) {
      nextId++;
      this.id = nextId;
      this.name = name;
    }
  }

  /**
   * A custom {@link Cell} used to render a {@link Contact}.
   */
  private static class ContactCell extends AbstractCell<Contact> {
    @Override
    public void render(Context context, Contact value, SafeHtmlBuilder sb) {
      if (value != null) {
        sb.appendEscaped(value.name);
      }
    }
  }

  /**
   * The list of data to display.
   */
  private static final List<Contact> CONTACTS = Arrays.asList(new Contact(
      "John"), new Contact("Joe"), new Contact("Michael"),
      new Contact("Sarah"), new Contact("George"));

  public void onModuleLoad() {
    /*
     * Define a key provider for a Contact. We use the unique ID as the key,
     * which allows to maintain selection even if the name changes.
     */
    ProvidesKey<Contact> keyProvider = new ProvidesKey<Contact>() {
      public Object getKey(Contact item) {
        // Always do a null check.
        return (item == null) ? null : item.id;
      }
    };

    // Create a CellList using the keyProvider.
    CellList<Contact> cellList = new CellList<Contact>(new ContactCell(),
        keyProvider);

    // Push data into the CellList.
    cellList.setRowCount(CONTACTS.size(), true);
    cellList.setRowData(0, CONTACTS);

    // Add a selection model using the same keyProvider.
    SelectionModel<Contact> selectionModel = new SingleSelectionModel<Contact>(
        keyProvider);
    cellList.setSelectionModel(selectionModel);

    /*
     * Select a contact. The selectionModel will select based on the ID because
     * we used a keyProvider.
     */
    Contact sarah = CONTACTS.get(3);
    selectionModel.setSelected(sarah, true);

    // Modify the name of the contact.
    sarah.name = "Sara";

    /*
     * Redraw the CellList. Sarah/Sara will still be selected because we
     * identify her by ID. If we did not use a keyProvider, Sara would not be
     * selected.
     */
    cellList.redraw();

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

Nested Class Summary
static interface CellList.Resources
          A ClientBundle that provides images for this widget.
static interface CellList.Style
          Styles used by this widget.
(package private) static interface CellList.Template
           
 
Nested classes/interfaces inherited from class com.google.gwt.user.cellview.client.AbstractHasData
AbstractHasData.DefaultKeyboardSelectionHandler<T>
 
Nested classes/interfaces inherited from class com.google.gwt.user.client.ui.UIObject
UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled
 
Nested classes/interfaces inherited from interface com.google.gwt.user.cellview.client.HasKeyboardPagingPolicy
HasKeyboardPagingPolicy.KeyboardPagingPolicy
 
Nested classes/interfaces inherited from interface com.google.gwt.user.cellview.client.HasKeyboardSelectionPolicy
HasKeyboardSelectionPolicy.KeyboardSelectionPolicy
 
Field Summary
 
Fields inherited from class com.google.gwt.user.cellview.client.AbstractHasData
isFocused
 
Fields inherited from class com.google.gwt.user.client.ui.UIObject
DEBUG_ID_PREFIX
 
Constructor Summary
CellList(Cell<T> cell)
          Construct a new CellList.
CellList(Cell<T> cell, CellList.Resources resources)
          Construct a new CellList with the specified CellList.Resources.
CellList(Cell<T> cell, CellList.Resources resources, ProvidesKey<T> keyProvider)
          Construct a new CellList with the specified CellList.Resources and key provider.
CellList(Cell<T> cell, ProvidesKey<T> keyProvider)
          Construct a new CellList with the specified key provider.
 
Method Summary
protected  boolean dependsOnSelection()
          Check whether or not the cells in the view depend on the selection state.
protected  void doAttachChildren()
          If a widget contains one or more child widgets that are not in the logical widget hierarchy (the child is physically connected only on the DOM level), it must override this method and call Widget.onAttach() for each of its child widgets.
protected  void doDetachChildren()
          If a widget contains one or more child widgets that are not in the logical widget hierarchy (the child is physically connected only on the DOM level), it must override this method and call Widget.onDetach() for each of its child widgets.
protected  void fireEventToCell(Cell.Context context, Event event, Element parent, T value)
          Fire an event to the cell.
protected  Cell<T> getCell()
          Return the cell used to render each item.
protected  Element getCellParent(Element item)
          Get the parent element that wraps the cell from the list item.
protected  Element getChildContainer()
          Return the element that holds the rendered cells.
 SafeHtml getEmptyListMessage()
          Deprecated. as of GWT 2.3, use getEmptyListWidget() instead
 Widget getEmptyListWidget()
          Get the widget displayed when the list has no rows.
protected  Element getKeyboardSelectedElement()
          Get the element that has keyboard selection.
 Widget getLoadingIndicator()
          Get the widget displayed when the data is loading.
 Element getRowElement(int indexOnPage)
          Get the Element for the specified index.
protected  boolean isKeyboardNavigationSuppressed()
          Check if keyboard navigation is being suppressed, such as when the user is editing a cell.
protected  void onBrowserEvent2(Event event)
          Called after AbstractHasData.onBrowserEvent(Event) completes.
protected  void onLoadingStateChanged(LoadingStateChangeEvent.LoadingState state)
          Called when the loading state changes.
protected  void renderRowValues(SafeHtmlBuilder sb, java.util.List<T> values, int start, SelectionModel<? super T> selectionModel)
          Render all row values into the specified SafeHtmlBuilder.
protected  boolean resetFocusOnCell()
          Reset focus on the currently focused cell.
 void setEmptyListMessage(SafeHtml html)
          Deprecated. as of GWT 2.3, use setEmptyListWidget(com.google.gwt.user.client.ui.Widget) instead
 void setEmptyListWidget(Widget widget)
          Set the widget to display when the list has no rows.
protected  void setKeyboardSelected(int index, boolean selected, boolean stealFocus)
          Update an element to reflect its keyboard selected state.
 void setLoadingIndicator(Widget widget)
          Set the widget to display when the data is loading.
protected  void setSelected(Element elem, boolean selected)
          Deprecated. this method is never called by AbstractHasData, render the selected styles in renderRowValues(SafeHtmlBuilder, List, int, SelectionModel)
 void setValueUpdater(ValueUpdater<T> valueUpdater)
          Set the value updater to use when cells modify items.
 
Methods inherited from class com.google.gwt.user.cellview.client.AbstractHasData
addCellPreviewHandler, addLoadingStateChangeHandler, addRangeChangeHandler, addRowCountChangeHandler, addValueChangeHandler, adopt, cellConsumesEventType, checkRowBounds, convertToElements, convertToElements, doAttach, doDetach, getAccessKey, getChildElement, getDisplayedItem, getDisplayedItems, getKeyboardPagingPolicy, getKeyboardSelectedRow, getKeyboardSelectionPolicy, getKeyProvider, getPageSize, getPageStart, getPresenter, getRowContainer, getRowCount, getSelectionModel, getTabIndex, getValueKey, getVisibleItem, getVisibleItemCount, getVisibleItems, getVisibleRange, isRowCountExact, isRowWithinBounds, onBlur, onBrowserEvent, onFocus, onUnload, redraw, redrawRow, replaceAllChildren, replaceAllChildren, replaceChildren, replaceChildren, setAccessKey, setFocus, setFocusable, setKeyboardPagingPolicy, setKeyboardSelectedRow, setKeyboardSelectedRow, setKeyboardSelectionHandler, setKeyboardSelectionPolicy, setPageSize, setPageStart, setRowCount, setRowCount, setRowData, setRowData, setSelectionModel, setSelectionModel, setTabIndex, setVisibleRange, setVisibleRange, setVisibleRangeAndClearData, showOrHide
 
Methods inherited from class com.google.gwt.user.client.ui.Composite
claimElement, getWidget, initializeClaimedElement, initWidget, isAttached, onAttach, onDetach, render, render, resolvePotentialElement, setWidget
 
Methods inherited from class com.google.gwt.user.client.ui.Widget
addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, createHandlerManager, delegateEvent, fireEvent, getHandlerCount, getLayoutData, getParent, isOrWasAttached, onLoad, removeFromParent, setLayoutData, sinkEvents, unsinkEvents
 
Methods inherited from class com.google.gwt.user.client.ui.UIObject
addStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getElement, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, onEnsureDebugId, removeStyleDependentName, removeStyleName, setElement, setElement, setHeight, setPixelSize, setSize, setStyleDependentName, setStyleName, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, sinkBitlessEvent, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
 

Constructor Detail

CellList

public CellList(Cell<T> cell)
Construct a new CellList.

Parameters:
cell - the cell used to render each item

CellList

public CellList(Cell<T> cell,
                CellList.Resources resources)
Construct a new CellList with the specified CellList.Resources.

Parameters:
cell - the cell used to render each item
resources - the resources used for this widget

CellList

public CellList(Cell<T> cell,
                ProvidesKey<T> keyProvider)
Construct a new CellList with the specified key provider.

Parameters:
cell - the cell used to render each item
keyProvider - an instance of ProvidesKey, or null if the record object should act as its own key

CellList

public CellList(Cell<T> cell,
                CellList.Resources resources,
                ProvidesKey<T> keyProvider)
Construct a new CellList with the specified CellList.Resources and key provider.

Parameters:
cell - the cell used to render each item
resources - the resources used for this widget
keyProvider - an instance of ProvidesKey, or null if the record object should act as its own key
Method Detail

getEmptyListMessage

@Deprecated
public SafeHtml getEmptyListMessage()
Deprecated. as of GWT 2.3, use getEmptyListWidget() instead

Get the message that is displayed when there is no data.

Returns:
the empty message
See Also:
setEmptyListMessage(SafeHtml)

getEmptyListWidget

public Widget getEmptyListWidget()
Get the widget displayed when the list has no rows.

Returns:
the empty list widget

getLoadingIndicator

public Widget getLoadingIndicator()
Get the widget displayed when the data is loading.

Returns:
the loading indicator

getRowElement

public Element getRowElement(int indexOnPage)
Get the Element for the specified index. If the element has not been created, null is returned.

Parameters:
indexOnPage - the index on the page
Returns:
the element, or null if it doesn't exists
Throws:
java.lang.IndexOutOfBoundsException - if the index is outside of the current page

setEmptyListMessage

@Deprecated
public void setEmptyListMessage(SafeHtml html)
Deprecated. as of GWT 2.3, use setEmptyListWidget(com.google.gwt.user.client.ui.Widget) instead

Set the message to display when there is no data.

Parameters:
html - the message to display when there are no results
See Also:
getEmptyListMessage()

setEmptyListWidget

public void setEmptyListWidget(Widget widget)
Set the widget to display when the list has no rows.

Parameters:
widget - the empty data widget

setLoadingIndicator

public void setLoadingIndicator(Widget widget)
Set the widget to display when the data is loading.

Parameters:
widget - the loading indicator

setValueUpdater

public void setValueUpdater(ValueUpdater<T> valueUpdater)
Set the value updater to use when cells modify items.

Parameters:
valueUpdater - the ValueUpdater

dependsOnSelection

protected boolean dependsOnSelection()
Description copied from class: AbstractHasData
Check whether or not the cells in the view depend on the selection state.

Specified by:
dependsOnSelection in class AbstractHasData<T>
Returns:
true if cells depend on selection, false if not

doAttachChildren

protected void doAttachChildren()
Description copied from class: Widget
If a widget contains one or more child widgets that are not in the logical widget hierarchy (the child is physically connected only on the DOM level), it must override this method and call Widget.onAttach() for each of its child widgets.

Overrides:
doAttachChildren in class Widget
See Also:
Widget.onAttach()

doDetachChildren

protected void doDetachChildren()
Description copied from class: Widget
If a widget contains one or more child widgets that are not in the logical widget hierarchy (the child is physically connected only on the DOM level), it must override this method and call Widget.onDetach() for each of its child widgets.

Overrides:
doDetachChildren in class Widget
See Also:
Widget.onDetach()

fireEventToCell

protected void fireEventToCell(Cell.Context context,
                               Event event,
                               Element parent,
                               T value)
Fire an event to the cell.

Parameters:
context - the Cell.Context of the cell
event - the event that was fired
parent - the parent of the cell
value - the value of the cell

getCell

protected Cell<T> getCell()
Return the cell used to render each item.

getCellParent

protected Element getCellParent(Element item)
Get the parent element that wraps the cell from the list item. Override this method if you add structure to the element.

Parameters:
item - the row element that wraps the list item
Returns:
the parent element of the cell

getChildContainer

protected Element getChildContainer()
Description copied from class: AbstractHasData
Return the element that holds the rendered cells.

Specified by:
getChildContainer in class AbstractHasData<T>
Returns:
the container Element

getKeyboardSelectedElement

protected Element getKeyboardSelectedElement()
Description copied from class: AbstractHasData
Get the element that has keyboard selection.

Specified by:
getKeyboardSelectedElement in class AbstractHasData<T>
Returns:
the keyboard selected element

isKeyboardNavigationSuppressed

protected boolean isKeyboardNavigationSuppressed()
Description copied from class: AbstractHasData
Check if keyboard navigation is being suppressed, such as when the user is editing a cell.

Specified by:
isKeyboardNavigationSuppressed in class AbstractHasData<T>
Returns:
true if suppressed, false if not

onBrowserEvent2

protected void onBrowserEvent2(Event event)
Description copied from class: AbstractHasData
Called after AbstractHasData.onBrowserEvent(Event) completes.

Overrides:
onBrowserEvent2 in class AbstractHasData<T>
Parameters:
event - the event that was fired

onLoadingStateChanged

protected void onLoadingStateChanged(LoadingStateChangeEvent.LoadingState state)
Called when the loading state changes.

Overrides:
onLoadingStateChanged in class AbstractHasData<T>
Parameters:
state - the new loading state

renderRowValues

protected void renderRowValues(SafeHtmlBuilder sb,
                               java.util.List<T> values,
                               int start,
                               SelectionModel<? super T> selectionModel)
Description copied from class: AbstractHasData
Render all row values into the specified SafeHtmlBuilder.

Subclasses can optionally throw an UnsupportedOperationException if they prefer to render the rows in AbstractHasData.replaceAllChildren(List, SafeHtml) and AbstractHasData.replaceChildren(List, int, SafeHtml). In this case, the SafeHtml argument will be null. Though a bit hacky, this is designed to supported legacy widgets that use SafeHtmlBuilder, and newer widgets that use other builders, such as the ElementBuilder API.

Specified by:
renderRowValues in class AbstractHasData<T>
Parameters:
sb - the SafeHtmlBuilder to render into
values - the row values
start - the absolute start index of the values
selectionModel - the SelectionModel

resetFocusOnCell

protected boolean resetFocusOnCell()
Description copied from class: AbstractHasData
Reset focus on the currently focused cell.

Specified by:
resetFocusOnCell in class AbstractHasData<T>
Returns:
true if focus is taken, false if not

setKeyboardSelected

protected void setKeyboardSelected(int index,
                                   boolean selected,
                                   boolean stealFocus)
Description copied from class: AbstractHasData
Update an element to reflect its keyboard selected state.

Specified by:
setKeyboardSelected in class AbstractHasData<T>
Parameters:
index - the index of the element
selected - true if selected, false if not
stealFocus - true if the row should steal focus, false if not

setSelected

@Deprecated
protected void setSelected(Element elem,
                                      boolean selected)
Deprecated. this method is never called by AbstractHasData, render the selected styles in renderRowValues(SafeHtmlBuilder, List, int, SelectionModel)

Description copied from class: AbstractHasData
Update an element to reflect its selected state.

Overrides:
setSelected in class AbstractHasData<T>
Parameters:
elem - the element to update
selected - true if selected, false if not
Overview  Package   Class  Use  Deprecated  Help 
GWT 2.7.0
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD