Package com.google.gwt.user.cellview.client

Class DataGrid<T>

java.lang.Object
com.google.gwt.user.client.ui.UIObject
com.google.gwt.user.client.ui.Widget
com.google.gwt.user.client.ui.Composite
com.google.gwt.user.cellview.client.AbstractHasData<T>
com.google.gwt.user.cellview.client.AbstractCellTable<T>
com.google.gwt.user.cellview.client.DataGrid<T>
Type Parameters:
T - the data type of each row
All Implemented Interfaces:
HasAttachHandlers, HasHandlers, HasKeyboardPagingPolicy, HasKeyboardSelectionPolicy, EventListener, Focusable, HasVisibility, IsRenderable, IsWidget, RequiresResize, HasCellPreviewHandlers<T>, HasData<T>, HasKeyProvider<T>, HasRows
public class DataGrid<T> extends AbstractCellTable<T> implements RequiresResize
A tabular view with a fixed header and footer section and a scrollable data section in the middle. This widget supports paging and columns.

Columns

The Column class defines the Cell used to render a column. Implement Column.getValue(Object) to retrieve the field value from the row object that will be rendered in the Cell.

Headers and Footers

A Header can be placed at the top (header) or bottom (footer) of the DataGrid. You can specify a header as text using AbstractCellTable.addColumn(Column, String), or you can create a custom Header that can change with the value of the cells, such as a column total. The Header will be rendered every time the row data changes or the table is redrawn. If you pass the same header instance (==) into adjacent columns, the header will span the columns.

Examples

Trivial example
public class CellTableExample implements EntryPoint {

  /**
   * A simple data type that represents a contact.
   */
  private static class Contact {
    private final String address;
    private final Date birthday;
    private final String name;

    public Contact(String name, Date birthday, String address) {
      this.name = name;
      this.birthday = birthday;
      this.address = address;
    }
  }

  /**
   * The list of data to display.
   */
  private static final List<Contact> CONTACTS = Arrays.asList(
      new Contact("John", new Date(80, 4, 12), "123 Fourth Avenue"),
      new Contact("Joe", new Date(85, 2, 22), "22 Lance Ln"),
      new Contact("George", new Date(46, 6, 6), "1600 Pennsylvania Avenue"));

  public void onModuleLoad() {
    // Create a CellTable.
    CellTable<Contact> table = new CellTable<Contact>();
    table.setKeyboardSelectionPolicy(KeyboardSelectionPolicy.ENABLED);

    // Add a text column to show the name.
    TextColumn<Contact> nameColumn = new TextColumn<Contact>() {
      @Override
      public String getValue(Contact object) {
        return object.name;
      }
    };
    table.addColumn(nameColumn, "Name");

    // Add a date column to show the birthday.
    DateCell dateCell = new DateCell();
    Column<Contact, Date> dateColumn = new Column<Contact, Date>(dateCell) {
      @Override
      public Date getValue(Contact object) {
        return object.birthday;
      }
    };
    table.addColumn(dateColumn, "Birthday");

    // Add a text column to show the address.
    TextColumn<Contact> addressColumn = new TextColumn<Contact>() {
      @Override
      public String getValue(Contact object) {
        return object.address;
      }
    };
    table.addColumn(addressColumn, "Address");

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

    // 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.
    table.setRowCount(CONTACTS.size(), true);

    // Push the data into the widget.
    table.setRowData(0, CONTACTS);

    // Add it to the root panel.
    RootPanel.get().add(table);
  }
}
FieldUpdater example
public class CellTableFieldUpdaterExample implements EntryPoint {

  /**
   * A simple data type that represents a contact with a unique ID.
   */
  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;
    }
  }

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

  /**
   * The key provider that allows us to identify Contacts even if a field
   * changes. We identify contacts by their unique ID.
   */
  private static final ProvidesKey<Contact> KEY_PROVIDER =
      new ProvidesKey<CellTableFieldUpdaterExample.Contact>() {
        @Override
        public Object getKey(Contact item) {
          return item.id;
        }
      };

  @Override
  public void onModuleLoad() {
    // Create a CellTable with a key provider.
    final CellTable<Contact> table = new CellTable<Contact>(KEY_PROVIDER);

    // Add a text input column to edit the name.
    final TextInputCell nameCell = new TextInputCell();
    Column<Contact, String> nameColumn = new Column<Contact, String>(nameCell) {
      @Override
      public String getValue(Contact object) {
        // Return the name as the value of this column.
        return object.name;
      }
    };
    table.addColumn(nameColumn, "Name");

    // Add a field updater to be notified when the user enters a new name.
    nameColumn.setFieldUpdater(new FieldUpdater<Contact, String>() {
      @Override
      public void update(int index, Contact object, String value) {
        // Inform the user of the change.
        Window.alert("You changed the name of " + object.name + " to " + value);

        // Push the changes into the Contact. At this point, you could send an
        // asynchronous request to the server to update the database.
        object.name = value;

        // Redraw the table with the new data.
        table.redraw();
      }
    });

    // Push the data into the widget.
    table.setRowData(CONTACTS);

    // Add it to the root panel.
    RootPanel.get().add(table);
  }
}
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(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);
  }
}

  • Field Details

  • Constructor Details

    • DataGrid

      public DataGrid()
      Constructs a table with a default page size of 50.

    • DataGrid

      public DataGrid(int pageSize)
      Constructs a table with the given page size.
      Parameters:
      pageSize - the page size

    • DataGrid

      public DataGrid(int pageSize, ProvidesKey<T> keyProvider)
      Constructs a table with the given page size and the given key provider.
      Parameters:
      pageSize - the page size
      keyProvider - an instance of ProvidesKey, or null if the record object should act as its own key

    • DataGrid

      public DataGrid(int pageSize, DataGrid.Resources resources)
      Constructs a table with the given page size with the specified DataGrid.Resources.
      Parameters:
      pageSize - the page size
      resources - the resources to use for this widget

    • DataGrid

      public DataGrid(int pageSize, DataGrid.Resources resources, ProvidesKey<T> keyProvider)
      Constructs a table with the given page size, the specified DataGrid.Resources, and the given key provider.
      Parameters:
      pageSize - the page size
      resources - the resources to use for this widget
      keyProvider - an instance of ProvidesKey, or null if the record object should act as its own key

    • DataGrid

      public DataGrid(int pageSize, DataGrid.Resources resources, ProvidesKey<T> keyProvider, Widget loadingIndicator)
      Constructs a table with the given page size, the specified DataGrid.Resources, and the given key provider.
      Parameters:
      pageSize - the page size
      resources - the resources to use for this widget
      keyProvider - an instance of ProvidesKey, or null if the record object should act as its own key
      loadingIndicator - the widget to use as a loading indicator, or null to disable

    • DataGrid

      public DataGrid(ProvidesKey<T> keyProvider)
      Constructs a table with a default page size of 50, and the given key provider.
      Parameters:
      keyProvider - an instance of ProvidesKey, or null if the record object should act as its own key

  • Method Details

    • addColumnStyleName

      public void addColumnStyleName(int index, String styleName)
      Description copied from class: AbstractCellTable
      Add a style name to the col element at the specified index, creating it if necessary.
      Specified by:
      addColumnStyleName in class AbstractCellTable<T>
      Parameters:
      index - the column index
      styleName - the style name to add

    • clearTableWidth

      public void clearTableWidth()
      Clear the width of the tables in this widget, which causes them to fill the available width.

      The table width is not the same as the width of this widget. If the tables are narrower than this widget, there will be a gap between the table and the edge of the widget. If the tables are wider than this widget, a horizontal scrollbar will appear so the user can scroll horizontally.

      See Also:

    • onResize

      public void onResize()
      Description copied from interface: RequiresResize
      This method must be called whenever the implementor's size has been modified.
      Specified by:
      onResize in interface RequiresResize

    • removeColumnStyleName

      public void removeColumnStyleName(int index, String styleName)
      Description copied from class: AbstractCellTable
      Remove a style from the col element at the specified index.
      Specified by:
      removeColumnStyleName in class AbstractCellTable<T>
      Parameters:
      index - the column index
      styleName - the style name to remove

    • setAlwaysShowScrollBars

      public void setAlwaysShowScrollBars(boolean alwaysShowScrollBars)
      Sets whether this grid always shows its scroll bars, or only when necessary.
      Parameters:
      alwaysShowScrollBars - true to show scroll bars at all times

    • setEmptyTableWidget

      public void setEmptyTableWidget(Widget widget)
      Description copied from class: AbstractCellTable
      Set the widget to display when the table has no rows.
      Overrides:
      setEmptyTableWidget in class AbstractCellTable<T>
      Parameters:
      widget - the empty table widget, or null to disable

    • setLoadingIndicator

      public void setLoadingIndicator(Widget widget)
      Description copied from class: AbstractCellTable
      Set the widget to display when the data is loading.
      Overrides:
      setLoadingIndicator in class AbstractCellTable<T>
      Parameters:
      widget - the loading indicator, or null to disable

    • setMinimumTableWidth

      public void setMinimumTableWidth(double value, Style.Unit unit)
      Set the minimum width of the tables in this widget. If the widget become narrower than the minimum width, a horizontal scrollbar will appear so the user can scroll horizontally.

      Note that this method is not supported in IE6 and earlier versions of IE.

      Parameters:
      value - the width
      unit - the unit of the width
      See Also:

    • setTableWidth

      public void setTableWidth(double value, Style.Unit unit)
      Set the width of the tables in this widget. By default, the width is not set and the tables take the available width.

      The table width is not the same as the width of this widget. If the tables are narrower than this widget, there will be a gap between the table and the edge of the widget. If the tables are wider than this widget, a horizontal scrollbar will appear so the user can scroll horizontally.

      If your table has many columns and you want to ensure that the columns are not truncated, you probably want to use setMinimumTableWidth(double, Unit) instead. That will ensure that the table is wide enough, but it will still allow the table to expand to 100% if the user has a wide screen.

      Note that setting the width in percentages will not work on older versions of IE because it does not account for scrollbars when calculating the width.

      Parameters:
      value - the width
      unit - the unit of the width
      See Also:

    • doSetColumnWidth

      protected void doSetColumnWidth(int column, String width)
      Description copied from class: AbstractCellTable
      Set the width of a column.
      Specified by:
      doSetColumnWidth in class AbstractCellTable<T>
      Parameters:
      column - the column index
      width - the width, or null to clear the width

    • doSetHeaderVisible

      protected void doSetHeaderVisible(boolean isFooter, boolean isVisible)
      Description copied from class: AbstractCellTable
      Show or hide a header section.
      Specified by:
      doSetHeaderVisible in class AbstractCellTable<T>
      Parameters:
      isFooter - true for the footer, false for the header
      isVisible - true to show, false to hide

    • getTableBodyElement

      protected TableSectionElement getTableBodyElement()
      Description copied from class: AbstractCellTable
      Get the tbody element that contains the render row values.
      Specified by:
      getTableBodyElement in class AbstractCellTable<T>

    • getTableFootElement

      protected TableSectionElement getTableFootElement()
      Description copied from class: AbstractCellTable
      Get the tfoot element that contains the footers.
      Specified by:
      getTableFootElement in class AbstractCellTable<T>

    • getTableHeadElement

      protected TableSectionElement getTableHeadElement()
      Description copied from class: AbstractCellTable
      Get the thead element that contains the headers.
      Specified by:
      getTableHeadElement in class AbstractCellTable<T>

    • 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

    • refreshColumnWidths

      protected void refreshColumnWidths()
      Overrides:
      refreshColumnWidths in class AbstractCellTable<T>