/*
* 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.dom.builder.shared.TableSectionBuilder;
import com.google.gwt.dom.client.Element;
import com.google.gwt.dom.client.TableRowElement;
/**
* Builds the DOM elements for the header section of a CellTable. It also
* provides queries on elements in the last DOM subtree that it created.
*
* <p>
* {@link HeaderBuilder} provides two optional ways to handle events, via a
* {@link Column}, a {@link Header}, or both. If {@link #getColumn(Element)}
* returns a {@link Column} given the target {@link Element} of an event, cell
* table will use it to enable features such as sorting. If
* {@link #getHeader(Element)} returns a {@link Header}, cell table will forward
* the event to the {@link Header}. You can specify both a {@link Column} and
* {@link Header}.
* </p>
*
* <p>
* The default implementation used by cell widgets is
* {@link DefaultHeaderOrFooterBuilder}.
* </p>
*
* @param <T> the row data type
*/
public interface HeaderBuilder<T> {
/**
* Builds the DOM subtree for this header. The root of the subtree must be a
* THEAD element, as appropriate. This method may be called multiple times and
* should return a new DOM subtree each time.
*
* <p>
* If the header is empty, return null.
* </p>
*
* @return a {@link TableSectionBuilder} representing the new header, or null
* if the header is empty
*/
TableSectionBuilder buildHeader();
/**
* Given an element in the DOM subtree returned by the most recent call to
* {@link #buildHeader()}, returns the Column that should be the target of any
* button clicks or other events on that element, or null if the events should
* be discarded. The column is used to support features such as column
* sorting.
*
* @param elem the element that the contains column
* @return the immediate column contained by the element
*/
Column<T, ?> getColumn(Element elem);
/**
* If you want to handle browser events using a subclass of {@link Header},
* implement this method to return the appropriate instance and cell table
* will forward events originating in the element to the {@link Header}.
* Return null if events from the element should be discarded.
*
* @param elem the element that the contains header
* @return the immediate {@link Header} contained by the element
*/
Header<?> getHeader(Element elem);
/**
* Get the row index from the associated
* {@link TableRowElement} (an TR element).
*
* @param row the row element
* @return the row value index
*/
int getRowIndex(TableRowElement row);
/**
* Check if an element contains a {@link Column}. This method should return
* false if and only if {@link #getColumn(Element)} would return null.
*
* @param elem the element of interest
*/
boolean isColumn(Element elem);
/**
* Check if an element contains a {@link Header}. This method should return
* false if and only if {@link #getHeader(Element)} would return null.
*
* @param elem the element of interest
*/
boolean isHeader(Element elem);
}