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

java.lang.Object
  com.google.gwt.user.client.ui.UIObject
      com.google.gwt.user.client.ui.Widget
          com.google.gwt.user.cellview.client.AbstractHasData<T>
              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, IsWidget, HasData<T>, HasKeyProvider<T>, HasRows

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);
  }
}

ValueUpdater example

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);
  }
}

Key provider example

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(Contact value, Object key, 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);
  }
}

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

getEmptyListMessage

public SafeHtml getEmptyListMessage()

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

Returns:

the empty message

See Also:

setEmptyListMessage(SafeHtml)

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

public void setEmptyListMessage(SafeHtml html)

Set the message to display when there is no data.

Parameters:

html - the message to display when there are no results

See Also:

getEmptyListMessage()

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

doSelection

protected void doSelection(Event event,
                           T value,
                           int indexOnPage)

Called when a user action triggers selection.

Parameters:

event - the event that triggered selection

value - the value that was selected

indexOnPage - the index of the value on the page

fireEventToCell

protected void fireEventToCell(Event event,
                               Element parent,
                               T value)

Fire an event to the cell.

Parameters:

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

onBlur

protected void onBlur()

Description copied from class: AbstractHasData

Called when the widget is blurred.

Overrides:

onBlur in class AbstractHasData<T>

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

onFocus

protected void onFocus()

Description copied from class: AbstractHasData

Called when the widget is focused.

Overrides:

onFocus in class AbstractHasData<T>

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.

Specified by:

renderRowValues in class AbstractHasData<T>

Parameters:

sb - the SafeHtmlBuilder to render into

values - the row values

start - the 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

protected void setSelected(Element elem,
                           boolean selected)

Description copied from class: AbstractHasData

Update an element to reflect its selected state.

Specified by:

setSelected in class AbstractHasData<T>

Parameters:

elem - the element to update

selected - true if selected, false if not