2.4/user/src/com/google/gwt/user/cellview/client/DataGrid.java

/*
 * Copyright 2011 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.user.cellview.client;

import com.google.gwt.core.client.GWT;
import com.google.gwt.dom.client.Document;
import com.google.gwt.dom.client.Element;
import com.google.gwt.dom.client.Style.Display;
import com.google.gwt.dom.client.Style.Overflow;
import com.google.gwt.dom.client.Style.TableLayout;
import com.google.gwt.dom.client.Style.Unit;
import com.google.gwt.dom.client.TableColElement;
import com.google.gwt.dom.client.TableElement;
import com.google.gwt.dom.client.TableSectionElement;
import com.google.gwt.event.dom.client.ScrollEvent;
import com.google.gwt.event.dom.client.ScrollHandler;
import com.google.gwt.resources.client.ClientBundle;
import com.google.gwt.resources.client.CssResource;
import com.google.gwt.resources.client.CssResource.ImportedWithPrefix;
import com.google.gwt.resources.client.ImageResource;
import com.google.gwt.resources.client.ImageResource.ImageOptions;
import com.google.gwt.user.cellview.client.LoadingStateChangeEvent.LoadingState;
import com.google.gwt.user.client.ui.CustomScrollPanel;
import com.google.gwt.user.client.ui.FlexTable;
import com.google.gwt.user.client.ui.HeaderPanel;
import com.google.gwt.user.client.ui.Image;
import com.google.gwt.user.client.ui.RequiresResize;
import com.google.gwt.user.client.ui.ScrollPanel;
import com.google.gwt.user.client.ui.SimplePanel;
import com.google.gwt.user.client.ui.Widget;
import com.google.gwt.view.client.ProvidesKey;

/**
 * A tabular view with a fixed header and footer section and a scrollable data
 * section in the middle. This widget supports paging and columns.
 * 
 * <p>
 * <h3>Columns</h3> The {@link Column} class defines the
 * {@link com.google.gwt.cell.client.Cell} used to render a column. Implement
 * {@link Column#getValue(Object)} to retrieve the field value from the row
 * object that will be rendered in the {@link com.google.gwt.cell.client.Cell}.
 * </p>
 * 
 * <p>
 * <h3>Headers and Footers</h3> A {@link Header} can be placed at the top
 * (header) or bottom (footer) of the {@link DataGrid}. You can specify a header
 * as text using {@link #addColumn(Column, String)}, or you can create a custom
 * {@link Header} that can change with the value of the cells, such as a column
 * total. The {@link 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.
 * </p>
 * 
 * <p>
 * <h3>Examples</h3>
 * <dl>
 * <dt>Trivial example</dt>
 * <dd>{@example com.google.gwt.examples.cellview.CellTableExample}</dd>
 * <dt>FieldUpdater example</dt>
 * <dd>{@example com.google.gwt.examples.cellview.CellTableFieldUpdaterExample}</dd>
 * <dt>Key provider example</dt>
 * <dd>{@example com.google.gwt.examples.view.KeyProviderExample}</dd>
 * </dl>
 * </p>
 * 
 * @param <T> the data type of each row
 */
public class DataGrid<T> extends AbstractCellTable<T> implements RequiresResize {

  /**
   * A ClientBundle that provides images for this widget.
   */
  public interface Resources extends ClientBundle {
    /**
     * The loading indicator used while the table is waiting for data.
     */
    @Source("cellTableLoading.gif")
    @ImageOptions(flipRtl = true)
    ImageResource dataGridLoading();

    /**
     * Icon used when a column is sorted in ascending order.
     */
    @Source("sortAscending.png")
    @ImageOptions(flipRtl = true)
    ImageResource dataGridSortAscending();

    /**
     * Icon used when a column is sorted in descending order.
     */
    @Source("sortDescending.png")
    @ImageOptions(flipRtl = true)
    ImageResource dataGridSortDescending();

    /**
     * The styles used in this widget.
     */
    @Source(Style.DEFAULT_CSS)
    Style dataGridStyle();
  }

  /**
   * Styles used by this widget.
   */
  @ImportedWithPrefix("gwt-CellTable")
  public interface Style extends CssResource {
    /**
     * The path to the default CSS styles used by this resource.
     */
    String DEFAULT_CSS = "com/google/gwt/user/cellview/client/DataGrid.css";

    /**
     * Applied to every cell.
     */
    String dataGridCell();

    /**
     * Applied to even rows.
     */
    String dataGridEvenRow();

    /**
     * Applied to cells in even rows.
     */
    String dataGridEvenRowCell();

    /**
     * Applied to the first column.
     */
    String dataGridFirstColumn();

    /**
     * Applied to the first column footers.
     */
    String dataGridFirstColumnFooter();

    /**
     * Applied to the first column headers.
     */
    String dataGridFirstColumnHeader();

    /**
     * Applied to footers cells.
     */
    String dataGridFooter();

    /**
     * Applied to headers cells.
     */
    String dataGridHeader();

    /**
     * Applied to the hovered row.
     */
    String dataGridHoveredRow();

    /**
     * Applied to the cells in the hovered row.
     */
    String dataGridHoveredRowCell();

    /**
     * Applied to the keyboard selected cell.
     */
    String dataGridKeyboardSelectedCell();

    /**
     * Applied to the keyboard selected row.
     */
    String dataGridKeyboardSelectedRow();

    /**
     * Applied to the cells in the keyboard selected row.
     */
    String dataGridKeyboardSelectedRowCell();

    /**
     * Applied to the last column.
     */
    String dataGridLastColumn();

    /**
     * Applied to the last column footers.
     */
    String dataGridLastColumnFooter();

    /**
     * Applied to the last column headers.
     */
    String dataGridLastColumnHeader();

    /**
     * Applied to odd rows.
     */
    String dataGridOddRow();

    /**
     * Applied to cells in odd rows.
     */
    String dataGridOddRowCell();

    /**
     * Applied to selected rows.
     */
    String dataGridSelectedRow();

    /**
     * Applied to cells in selected rows.
     */
    String dataGridSelectedRowCell();

    /**
     * Applied to header cells that are sortable.
     */
    String dataGridSortableHeader();

    /**
     * Applied to header cells that are sorted in ascending order.
     */
    String dataGridSortedHeaderAscending();

    /**
     * Applied to header cells that are sorted in descending order.
     */
    String dataGridSortedHeaderDescending();

    /**
     * Applied to the table.
     */
    String dataGridWidget();
  }

  /**
   * A simple widget wrapper around a table element.
   */
  static class TableWidget extends Widget {
    private final TableColElement colgroup;
    private TableSectionElement section;
    private final TableElement tableElem;

    public TableWidget() {
      // Setup the table.
      tableElem = Document.get().createTableElement();
      tableElem.setCellSpacing(0);
      tableElem.getStyle().setTableLayout(TableLayout.FIXED);
      tableElem.getStyle().setWidth(100.0, Unit.PCT);
      setElement(tableElem);

      // Add the colgroup.
      colgroup = Document.get().createColGroupElement();
      tableElem.appendChild(colgroup);
    }

    public void addColumnStyleName(int index, String styleName) {
      ensureTableColElement(index).addClassName(styleName);
    }

    /**
     * Get the {@link TableColElement} at the specified index, creating it if
     * necessary.
     * 
     * @param index the column index
     * @return the {@link TableColElement}
     */
    public TableColElement ensureTableColElement(int index) {
      // Ensure that we have enough columns.
      for (int i = colgroup.getChildCount(); i <= index; i++) {
        colgroup.appendChild(Document.get().createColElement());
      }
      return colgroup.getChild(index).cast();
    }

    public void removeColumnStyleName(int index, String styleName) {
      if (index >= colgroup.getChildCount()) {
        return;
      }
      ensureTableColElement(index).removeClassName(styleName);
    }

    /**
     * Hide columns that aren't used in the table.
     * 
     * @param start the first unused column index
     */
    void hideUnusedColumns(int start) {
      /*
       * Set the width to zero for all col elements that appear after the last
       * column. Clearing the width would cause it to take up the remaining
       * width in a fixed layout table.
       */
      int colCount = colgroup.getChildCount();
      for (int i = start; i < colCount; i++) {
        setColumnWidth(i, "0px");
      }
    }

    void setColumnWidth(int column, String width) {
      if (width == null) {
        ensureTableColElement(column).getStyle().clearWidth();
      } else {
        ensureTableColElement(column).getStyle().setProperty("width", width);
      }
    }
  }

  /**
   * Adapter class to convert {@link Resources} to
   * {@link AbstractCellTable.Resources}.
   */
  private static class ResourcesAdapter implements AbstractCellTable.Resources {

    private final DataGrid.Resources resources;
    private final StyleAdapter style;

    public ResourcesAdapter(DataGrid.Resources resources) {
      this.resources = resources;
      this.style = new StyleAdapter(resources.dataGridStyle());
    }

    @Override
    public ImageResource sortAscending() {
      return resources.dataGridSortAscending();
    }

    @Override
    public ImageResource sortDescending() {
      return resources.dataGridSortDescending();
    }

    @Override
    public AbstractCellTable.Style style() {
      return style;
    }
  }

  /**
   * Adapter class to convert {@link Style} to {@link AbstractCellTable.Style}.
   */
  private static class StyleAdapter implements AbstractCellTable.Style {
    private final DataGrid.Style style;

    public StyleAdapter(DataGrid.Style style) {
      this.style = style;
    }

    @Override
    public String cell() {
      return style.dataGridCell();
    }

    @Override
    public String evenRow() {
      return style.dataGridEvenRow();
    }

    @Override
    public String evenRowCell() {
      return style.dataGridEvenRowCell();
    }

    @Override
    public String firstColumn() {
      return style.dataGridFirstColumn();
    }

    @Override
    public String firstColumnFooter() {
      return style.dataGridFirstColumnFooter();
    }

    @Override
    public String firstColumnHeader() {
      return style.dataGridFirstColumnHeader();
    }

    @Override
    public String footer() {
      return style.dataGridFooter();
    }

    @Override
    public String header() {
      return style.dataGridHeader();
    }

    @Override
    public String hoveredRow() {
      return style.dataGridHoveredRow();
    }

    @Override
    public String hoveredRowCell() {
      return style.dataGridHoveredRowCell();
    }

    @Override
    public String keyboardSelectedCell() {
      return style.dataGridKeyboardSelectedCell();
    }

    @Override
    public String keyboardSelectedRow() {
      return style.dataGridKeyboardSelectedRow();
    }

    @Override
    public String keyboardSelectedRowCell() {
      return style.dataGridKeyboardSelectedRowCell();
    }

    @Override
    public String lastColumn() {
      return style.dataGridLastColumn();
    }

    @Override
    public String lastColumnFooter() {
      return style.dataGridLastColumnFooter();
    }

    @Override
    public String lastColumnHeader() {
      return style.dataGridLastColumnHeader();
    }

    @Override
    public String oddRow() {
      return style.dataGridOddRow();
    }

    @Override
    public String oddRowCell() {
      return style.dataGridOddRowCell();
    }

    @Override
    public String selectedRow() {
      return style.dataGridSelectedRow();
    }

    @Override
    public String selectedRowCell() {
      return style.dataGridSelectedRowCell();
    }

    @Override
    public String sortableHeader() {
      return style.dataGridSortableHeader();
    }

    @Override
    public String sortedHeaderAscending() {
      return style.dataGridSortedHeaderAscending();
    }

    @Override
    public String sortedHeaderDescending() {
      return style.dataGridSortedHeaderDescending();
    }

    @Override
    public String widget() {
      return style.dataGridWidget();
    }
  }

  private static final int DEFAULT_PAGESIZE = 50;
  private static Resources DEFAULT_RESOURCES;

  /**
   * Create the default loading indicator using the loading image in the
   * specified {@link Resources}.
   * 
   * @param resources the resources containing the loading image
   * @return a widget loading indicator
   */
  private static Widget createDefaultLoadingIndicator(Resources resources) {
    ImageResource loadingImg = resources.dataGridLoading();
    if (loadingImg == null) {
      return null;
    }
    Image image = new Image(loadingImg);
    image.getElement().getStyle().setMarginTop(30.0, Unit.PX);
    return image;
  }

  private static Resources getDefaultResources() {
    if (DEFAULT_RESOURCES == null) {
      DEFAULT_RESOURCES = GWT.create(Resources.class);
    }
    return DEFAULT_RESOURCES;
  }

  final TableWidget tableData;
  final TableWidget tableFooter;
  final TableWidget tableHeader;
  private final FlexTable emptyTableWidgetContainer;
  private final HeaderPanel headerPanel;
  private final FlexTable loadingIndicatorContainer;
  private final Style style;
  private final Element tableDataContainer;
  private final ScrollPanel tableDataScroller;
  private final SimplePanel tableFooterContainer;
  private final Element tableFooterScroller;
  private final SimplePanel tableHeaderContainer;
  private final Element tableHeaderScroller;

  /**
   * Constructs a table with a default page size of 50.
   */
  public DataGrid() {
    this(DEFAULT_PAGESIZE);
  }

  /**
   * Constructs a table with the given page size.
   * 
   * @param pageSize the page size
   */
  public DataGrid(final int pageSize) {
    this(pageSize, getDefaultResources());
  }

  /**
   * Constructs a table with the given page size and the given
   * {@link ProvidesKey key provider}.
   * 
   * @param pageSize the page size
   * @param keyProvider an instance of ProvidesKey<T>, or null if the record
   *          object should act as its own key
   */
  public DataGrid(int pageSize, ProvidesKey<T> keyProvider) {
    this(pageSize, getDefaultResources(), keyProvider);
  }

  /**
   * Constructs a table with the given page size with the specified
   * {@link Resources}.
   * 
   * @param pageSize the page size
   * @param resources the resources to use for this widget
   */
  public DataGrid(int pageSize, Resources resources) {
    this(pageSize, resources, null);
  }

  /**
   * Constructs a table with the given page size, the specified
   * {@link Resources}, and the given key provider.
   * 
   * @param pageSize the page size
   * @param resources the resources to use for this widget
   * @param keyProvider an instance of ProvidesKey<T>, or null if the record
   *          object should act as its own key
   */
  public DataGrid(int pageSize, Resources resources, ProvidesKey<T> keyProvider) {
    this(pageSize, resources, keyProvider, createDefaultLoadingIndicator(resources));
  }

  /**
   * Constructs a table with the given page size, the specified
   * {@link Resources}, and the given key provider.
   * 
   * @param pageSize the page size
   * @param resources the resources to use for this widget
   * @param keyProvider an instance of ProvidesKey<T>, or null if the record
   *          object should act as its own key
   * @param loadingIndicator the widget to use as a loading indicator, or null
   *          to disable
   */
  public DataGrid(int pageSize, Resources resources, ProvidesKey<T> keyProvider,
      Widget loadingIndicator) {
    super(new HeaderPanel(), pageSize, new ResourcesAdapter(resources), keyProvider);
    headerPanel = (HeaderPanel) getWidget();

    // Inject the stylesheet.
    this.style = resources.dataGridStyle();
    this.style.ensureInjected();

    // Create the header and footer widgets..
    tableHeader = new TableWidget();
    tableHeader.section = tableHeader.tableElem.createTHead();
    tableFooter = new TableWidget();
    tableFooter.section = tableFooter.tableElem.createTFoot();

    /*
     * Wrap the header and footer widgets in a div because we cannot set the
     * min-width of a table element. We set the width/min-width of the div
     * container instead.
     */
    tableHeaderContainer = new SimplePanel(tableHeader);
    tableFooterContainer = new SimplePanel(tableFooter);

    /*
     * Get the element that wraps the container so we can adjust its scroll
     * position.
     */
    headerPanel.setHeaderWidget(tableHeaderContainer);
    tableHeaderScroller = tableHeaderContainer.getElement().getParentElement();
    headerPanel.setFooterWidget(tableFooterContainer);
    tableFooterScroller = tableFooterContainer.getElement().getParentElement();

    /*
     * Set overflow to hidden on the scrollable elements so we can change the
     * scrollLeft position.
     */
    tableHeaderScroller.getStyle().setOverflow(Overflow.HIDDEN);
    tableFooterScroller.getStyle().setOverflow(Overflow.HIDDEN);

    // Create the body.
    tableData = new TableWidget();
    if (tableData.tableElem.getTBodies().getLength() > 0) {
      tableData.section = tableData.tableElem.getTBodies().getItem(0);
    } else {
      tableData.section = Document.get().createTBodyElement();
      tableData.tableElem.appendChild(tableData.section);
    }
    tableDataScroller = new CustomScrollPanel(tableData);
    tableDataScroller.setHeight("100%");
    headerPanel.setContentWidget(tableDataScroller);
    tableDataContainer = tableData.getElement().getParentElement();

    /*
     * CustomScrollPanel applies the inline block style to the container
     * element, but we want the container to fill the available width.
     */
    tableDataContainer.getStyle().setDisplay(Display.BLOCK);

    /*
     * Create the containers for the empty table message and loading indicator.
     * The containers are centered tables that contain one cell, which aligns
     * the widget in the center of the panel.
     */
    emptyTableWidgetContainer = new FlexTable();
    emptyTableWidgetContainer.getElement().setAttribute("align", "center");
    loadingIndicatorContainer = new FlexTable();
    loadingIndicatorContainer.getElement().setAttribute("align", "center");

    // Set the loading indicator.
    setLoadingIndicator(loadingIndicator); // Can be null.

    // Synchronize the scroll positions of the three tables.
    tableDataScroller.addScrollHandler(new ScrollHandler() {
      @Override
      public void onScroll(ScrollEvent event) {
        int scrollLeft = tableDataScroller.getHorizontalScrollPosition();
        tableHeaderScroller.setScrollLeft(scrollLeft);
        tableFooterScroller.setScrollLeft(scrollLeft);
      }
    });
  }

  /**
   * Constructs a table with a default page size of 50, and the given
   * {@link ProvidesKey key provider}.
   * 
   * @param keyProvider an instance of ProvidesKey<T>, or null if the record
   *          object should act as its own key
   */
  public DataGrid(ProvidesKey<T> keyProvider) {
    this(DEFAULT_PAGESIZE, keyProvider);
  }

  @Override
  public void addColumnStyleName(int index, String styleName) {
    tableHeader.addColumnStyleName(index, styleName);
    tableFooter.addColumnStyleName(index, styleName);
    tableData.addColumnStyleName(index, styleName);
  }

  /**
   * Clear the width of the tables in this widget, which causes them to fill the
   * available width.
   * 
   * <p>
   * 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.
   * </p>
   * 
   * @see #setMinimumTableWidth(double, Unit)
   * @see #setTableWidth(double, Unit)
   */
  public void clearTableWidth() {
    tableHeaderContainer.getElement().getStyle().clearWidth();
    tableFooterContainer.getElement().getStyle().clearWidth();
    tableDataContainer.getStyle().clearWidth();
  }

  @Override
  public void onResize() {
    headerPanel.onResize();
  }

  @Override
  public void removeColumnStyleName(int index, String styleName) {
    tableHeader.removeColumnStyleName(index, styleName);
    tableFooter.removeColumnStyleName(index, styleName);
    tableData.removeColumnStyleName(index, styleName);
  }

  @Override
  public void setEmptyTableWidget(Widget widget) {
    emptyTableWidgetContainer.setWidget(0, 0, widget);
    super.setEmptyTableWidget(widget);
  }

  @Override
  public void setLoadingIndicator(Widget widget) {
    loadingIndicatorContainer.setWidget(0, 0, widget);
    super.setLoadingIndicator(widget);
  }

  /**
   * 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.
   * 
   * <p>
   * Note that this method is not supported in IE6 and earlier versions of IE.
   * </p>
   * 
   * @param value the width
   * @param unit the unit of the width
   * @see #setTableWidth(double, Unit)
   */
  public void setMinimumTableWidth(double value, Unit unit) {
    /*
     * The min-width style attribute doesn't apply to tables, so we set the
     * min-width of the element that contains the table instead. The table width
     * is fixed at 100%.
     */
    tableHeaderContainer.getElement().getStyle().setProperty("minWidth", value, unit);
    tableFooterContainer.getElement().getStyle().setProperty("minWidth", value, unit);
    tableDataContainer.getStyle().setProperty("minWidth", value, unit);
  }

  /**
   * Set the width of the tables in this widget. By default, the width is not
   * set and the tables take the available width.
   * 
   * <p>
   * 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.
   * </p>
   * 
   * <p>
   * If your table has many columns and you want to ensure that the columns are
   * not truncated, you probably want to use
   * {@link #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.
   * </p>
   * 
   * <p>
   * 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.
   * </p>
   * 
   * @param value the width
   * @param unit the unit of the width
   * @see #setMinimumTableWidth(double, Unit)
   */
  public void setTableWidth(double value, Unit unit) {
    /*
     * The min-width style attribute doesn't apply to tables, so we set the
     * min-width of the element that contains the table instead. For
     * consistency, we set the width of the container as well.
     */
    tableHeaderContainer.getElement().getStyle().setWidth(value, unit);
    tableFooterContainer.getElement().getStyle().setWidth(value, unit);
    tableDataContainer.getStyle().setWidth(value, unit);
  }

  @Override
  protected void doSetColumnWidth(int column, String width) {
    if (width == null) {
      tableData.ensureTableColElement(column).getStyle().clearWidth();
      tableHeader.ensureTableColElement(column).getStyle().clearWidth();
      tableFooter.ensureTableColElement(column).getStyle().clearWidth();
    } else {
      tableData.ensureTableColElement(column).getStyle().setProperty("width", width);
      tableHeader.ensureTableColElement(column).getStyle().setProperty("width", width);
      tableFooter.ensureTableColElement(column).getStyle().setProperty("width", width);
    }
  }

  @Override
  protected void doSetHeaderVisible(boolean isFooter, boolean isVisible) {
    if (isFooter) {
      headerPanel.setFooterWidget(isVisible ? tableFooterContainer : null);
    } else {
      headerPanel.setHeaderWidget(isVisible ? tableHeaderContainer : null);
    }
  }

  @Override
  protected TableSectionElement getTableBodyElement() {
    return tableData.section;
  }

  @Override
  protected TableSectionElement getTableFootElement() {
    return tableFooter.section;
  }

  @Override
  protected TableSectionElement getTableHeadElement() {
    return tableHeader.section;
  }

  /**
   * Called when the loading state changes.
   * 
   * @param state the new loading state
   */
  @Override
  protected void onLoadingStateChanged(LoadingState state) {
    Widget message = tableData;
    if (state == LoadingState.LOADING) {
      // Loading indicator.
      message = loadingIndicatorContainer;
    } else if (state == LoadingState.LOADED && getPresenter().isEmpty()) {
      // Empty table.
      message = emptyTableWidgetContainer;
    }

    // Switch out the message to display.
    tableDataScroller.setWidget(message);

    // Fire an event.
    super.onLoadingStateChanged(state);
  }

  @Override
  protected void refreshColumnWidths() {
    super.refreshColumnWidths();

    // Hide unused col elements in the colgroup.
    int columnCount = getColumnCount();
    tableHeader.hideUnusedColumns(columnCount);
    tableData.hideUnusedColumns(columnCount);
    tableFooter.hideUnusedColumns(columnCount);
  }
}