com.vaadin.ui.components.grid
Class Grid

java.lang.Object
  com.vaadin.server.AbstractClientConnector
      com.vaadin.ui.AbstractComponent
          com.vaadin.ui.components.grid.Grid

All Implemented Interfaces:

MethodEventSource, ClientConnector, Sizeable, com.vaadin.shared.Connector, Component, SelectionChangeNotifier, java.io.Serializable

public class Grid
extends AbstractComponent
implements SelectionChangeNotifier

Data grid component

Lazy loading

TODO To be revised when the data data source implementation has been don.

Columns

The grid columns are based on the property ids of the underlying data source. Each property id represents one column in the grid. To retrive a column in the grid you can use getColumn(Object) with the property id of the column. A grid column contains properties like the width, the footer and header captions of the column.

Auxiliary headers and footers

TODO To be revised when column grouping is implemented.

Since:

Author:

Vaadin Ltd

See Also:

Serialized Form

Nested Class Summary

static class

Grid.SelectionMode Selection modes representing built-in SelectionModels that come bundled with Grid.

Nested classes/interfaces inherited from interface com.vaadin.ui.Component

Component.ErrorEvent, Component.Event, Component.Focusable, Component.Listener

Nested classes/interfaces inherited from interface com.vaadin.server.ClientConnector

ClientConnector.AttachEvent, ClientConnector.AttachListener, ClientConnector.ConnectorErrorEvent, ClientConnector.DetachEvent, ClientConnector.DetachListener

Nested classes/interfaces inherited from interface com.vaadin.server.Sizeable

Sizeable.Unit

Field Summary

Fields inherited from interface com.vaadin.server.Sizeable

SIZE_UNDEFINED, UNITS_CM, UNITS_EM, UNITS_EX, UNITS_INCH, UNITS_MM, UNITS_PERCENTAGE, UNITS_PICAS, UNITS_PIXELS, UNITS_POINTS

Constructor Summary

Grid(Container.Indexed datasource)
Creates a new Grid using the given datasource.

Method Summary

ColumnGroupRow	addColumnGroupRow() Adds a new column group to the grid.
ColumnGroupRow	addColumnGroupRow(int rowIndex) Adds a new column group to the grid at a specific index
void	addSelectionChangeListener(SelectionChangeListener listener) Registers a new selection change listener
void	addSortOrderChangeListener(SortOrderChangeListener listener) Adds a sort order change listener that gets notified when the sort order changes.
void	clearSortOrder() Clear the current sort order, and re-sort the grid.
boolean	deselect(java.lang.Object itemId) Marks an item as deselected.
void	fireSelectionChangeEvent(java.util.Collection<java.lang.Object> oldSelection, java.util.Collection<java.lang.Object> newSelection) Fires a selection change event.
GridColumn	getColumn(java.lang.Object propertyId) Returns a column based on the property id
java.util.List<ColumnGroupRow>	getColumnGroupRows() Gets the column group rows.
Container.Indexed	getContainerDatasource() Returns the grid data source.
double	getHeightByRows() Gets the amount of rows in Grid's body that are shown, while getHeightMode() is HeightMode.ROW.
com.vaadin.shared.ui.grid.HeightMode	getHeightMode() Returns the current HeightMode the Grid is in.
java.lang.Object	getLastFrozenPropertyId() Gets the rightmost frozen column in the grid.
java.lang.Object	getSelectedRow() Gets the item id of the currently selected item.
java.util.Collection<java.lang.Object>	getSelectedRows() Returns a collection of all the currently selected itemIds.
SelectionModel	getSelectionModel() Returns the currently used SelectionModel.
java.util.List<SortOrder>	getSortOrder() Get the current sort order list.
protected com.vaadin.shared.ui.grid.GridState	getState() Returns the shared state bean with information to be sent from the server to the client.
protected com.vaadin.shared.ui.grid.GridState	getState(boolean markAsDirty) Returns the shared state for this connector.
boolean	isColumnFootersVisible() Are the footer rows visible.
boolean	isColumnHeadersVisible() Are the header rows visible?
boolean	isSelected(java.lang.Object itemId) Checks whether an item is selected or not.
void	removeColumnGroupRow(ColumnGroupRow row) Removes a column group.
void	removeSelectionChangeListener(SelectionChangeListener listener) Removes a previously registered selection change listener
void	removeSortOrderChangeListener(SortOrderChangeListener listener) Removes a sort order change listener previously added using addSortOrderChangeListener(SortOrderChangeListener).
void	scrollTo(java.lang.Object itemId) Scrolls to a certain item, using ScrollDestination.ANY.
void	scrollTo(java.lang.Object itemId, com.vaadin.shared.ui.grid.ScrollDestination destination) Scrolls to a certain item, using user-specified scroll destination.
void	scrollToEnd() Scrolls to the end of the last data row.
void	scrollToStart() Scrolls to the beginning of the first data row.
boolean	select(java.lang.Object itemId) Marks an item as selected.
void	setColumnFootersVisible(boolean visible) Sets the footer rows visible.
void	setColumnHeadersVisible(boolean visible) Sets the header rows visible.
void	setContainerDataSource(Container.Indexed container) Sets the grid data source.
void	setHeight(float height, Sizeable.Unit unit) Sets the height of the object.
void	setHeightByRows(double rows) Sets the number of rows that should be visible in Grid's body, while getHeightMode() is HeightMode.ROW.
void	setHeightMode(com.vaadin.shared.ui.grid.HeightMode heightMode) Defines the mode in which the Grid widget's height is calculated.
void	setLastFrozenPropertyId(java.lang.Object propertyId) Sets (or unsets) the rightmost frozen column in the grid.
SelectionModel	setSelectionMode(Grid.SelectionMode selectionMode) Changes the Grid's selection mode.
void	setSelectionModel(SelectionModel selectionModel) Takes a new SelectionModel into use.
void	setSortOrder(java.util.List<SortOrder> order) Sets the sort order to use.
void	sort(java.lang.Object propertyId) Sort this Grid in ascending order by a specified property.
void	sort(java.lang.Object propertyId, com.vaadin.shared.ui.grid.SortDirection direction) Sort this Grid in user-specified SortOrder by a property.
void	sort(Sort s) Sets the current sort order using the fluid Sort API.

Methods inherited from class com.vaadin.ui.AbstractComponent

addListener, addShortcutListener, addStyleName, attach, beforeClientResponse, detach, findAncestor, fireComponentErrorEvent, fireComponentEvent, focus, getActionManager, getCaption, getComponentError, getData, getDebugId, getDescription, getErrorMessage, getHeight, getHeightUnits, getIcon, getId, getLocale, getParent, getPrimaryStyleName, getStyleName, getWidth, getWidthUnits, isConnectorEnabled, isEnabled, isImmediate, isOrHasAncestor, isReadOnly, isVisible, removeListener, removeShortcutListener, removeStyleName, setCaption, setComponentError, setData, setDebugId, setDescription, setEnabled, setHeight, setHeightUndefined, setIcon, setId, setImmediate, setLocale, setParent, setPrimaryStyleName, setReadOnly, setSizeFull, setSizeUndefined, setStyleName, setVisible, setWidth, setWidth, setWidthUndefined

Methods inherited from class com.vaadin.server.AbstractClientConnector

addAttachListener, addDetachListener, addExtension, addListener, addListener, addListener, addMethodInvocationToQueue, createState, encodeState, fireEvent, getAllChildrenIterable, getConnectorId, getErrorHandler, getExtensions, getListeners, getResource, getRpcManager, getRpcProxy, getSession, getStateType, getUI, handleConnectorRequest, hasListeners, isAttached, markAsDirty, markAsDirtyRecursive, registerRpc, registerRpc, removeAttachListener, removeDetachListener, removeExtension, removeListener, removeListener, removeListener, removeListener, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler, setResource

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.vaadin.ui.Component

getUI

Methods inherited from interface com.vaadin.server.ClientConnector

addAttachListener, addDetachListener, encodeState, getErrorHandler, getExtensions, getRpcManager, getStateType, handleConnectorRequest, isAttached, markAsDirty, markAsDirtyRecursive, removeAttachListener, removeDetachListener, removeExtension, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler

Methods inherited from interface com.vaadin.shared.Connector

getConnectorId

Constructor Detail

Grid

public Grid(Container.Indexed datasource)

Creates a new Grid using the given datasource.

Parameters:

datasource - the data source for the grid

Method Detail

setContainerDataSource

public void setContainerDataSource(Container.Indexed container)

Sets the grid data source.

Parameters:

container - The container data source. Cannot be null.

Throws:

java.lang.IllegalArgumentException - if the data source is null

getContainerDatasource

public Container.Indexed getContainerDatasource()

Returns the grid data source.

Returns:

the container data source of the grid

getColumn

public GridColumn getColumn(java.lang.Object propertyId)

Returns a column based on the property id

Parameters:

propertyId - the property id of the column

Returns:

the column or null if not found

setColumnHeadersVisible

public void setColumnHeadersVisible(boolean visible)

Sets the header rows visible.

Parameters:

visible - true if the header rows should be visible

isColumnHeadersVisible

public boolean isColumnHeadersVisible()

Are the header rows visible?

Returns:

true if the headers of the columns are visible

setColumnFootersVisible

public void setColumnFootersVisible(boolean visible)

Sets the footer rows visible.

Parameters:

visible - true if the footer rows should be visible

isColumnFootersVisible

public boolean isColumnFootersVisible()

Are the footer rows visible.

Returns:

true if the footer rows should be visible

addColumnGroupRow

public ColumnGroupRow addColumnGroupRow()

Adds a new column group to the grid.

Column group rows are rendered in the header and footer of the grid. Column group rows are made up of column groups which groups together columns for adding a common auxiliary header or footer for the columns.

Example usage:

 // Add a new column group row to the grid
 ColumnGroupRow row = grid.addColumnGroupRow();
 
 // Group "Column1" and "Column2" together to form a header in the row
 ColumnGroup column12 = row.addGroup("Column1", "Column2");
 
 // Set a common header for "Column1" and "Column2"
 column12.setHeader("Column 1&2");
 

Returns:

a column group instance you can use to add column groups

addColumnGroupRow

public ColumnGroupRow addColumnGroupRow(int rowIndex)

Adds a new column group to the grid at a specific index

Parameters:

rowIndex - the index of the row

Returns:

a column group instance you can use to add column groups

removeColumnGroupRow

public void removeColumnGroupRow(ColumnGroupRow row)

Removes a column group.

Parameters:

row - the row to remove

getColumnGroupRows

public java.util.List<ColumnGroupRow> getColumnGroupRows()

Gets the column group rows.

Returns:

an unmodifiable list of column group rows

getState

protected com.vaadin.shared.ui.grid.GridState getState()

Description copied from class: AbstractComponent

Returns the shared state bean with information to be sent from the server to the client. Subclasses should override this method and set any relevant fields of the state returned by super.getState().

Overrides:

getState in class AbstractComponent

Returns:

updated component shared state

getState

protected com.vaadin.shared.ui.grid.GridState getState(boolean markAsDirty)

Description copied from class: AbstractClientConnector

Returns the shared state for this connector.

Overrides:

getState in class AbstractComponent

Parameters:

markAsDirty - true if the connector should automatically be marked dirty, false otherwise

Returns:

The shared state for this connector. Never null.

See Also:

AbstractClientConnector.getState()

setLastFrozenPropertyId

public void setLastFrozenPropertyId(java.lang.Object propertyId)

Sets (or unsets) the rightmost frozen column in the grid.

All columns up to and including the indicated property will be frozen in place when the grid is scrolled sideways.

Note: If the container used by this grid supports a propertyId null, it can never be defined as the last frozen column, as a null parameter will always reset the frozen columns in Grid.

Parameters:

propertyId - the property id corresponding to the column that should be the last frozen column, or null to not have any columns frozen.

Throws:

java.lang.IllegalArgumentException - if lastFrozenColumn is not a column from this grid

getLastFrozenPropertyId

public java.lang.Object getLastFrozenPropertyId()

Gets the rightmost frozen column in the grid.

Note: Most often, this method returns the very value set with setLastFrozenPropertyId(Object). This value, however, can be reset to null if the column is detached from this grid.

Returns:

the rightmost frozen column in the grid, or null if no columns are frozen.

scrollTo

public void scrollTo(java.lang.Object itemId)
              throws java.lang.IllegalArgumentException

Scrolls to a certain item, using ScrollDestination.ANY.

Parameters:

itemId - id of item to scroll to.

Throws:

java.lang.IllegalArgumentException - if the provided id is not recognized by the data source.

scrollTo

public void scrollTo(java.lang.Object itemId,
                     com.vaadin.shared.ui.grid.ScrollDestination destination)
              throws java.lang.IllegalArgumentException

Scrolls to a certain item, using user-specified scroll destination.

Parameters:

itemId - id of item to scroll to.

destination - value specifying desired position of scrolled-to row.

Throws:

java.lang.IllegalArgumentException - if the provided id is not recognized by the data source.

scrollToStart

public void scrollToStart()

Scrolls to the beginning of the first data row.

scrollToEnd

public void scrollToEnd()

Scrolls to the end of the last data row.

setHeightByRows

public void setHeightByRows(double rows)

Sets the number of rows that should be visible in Grid's body, while getHeightMode() is HeightMode.ROW.

If Grid is currently not in HeightMode.ROW, the given value is remembered, and applied once the mode is applied.

Parameters:

rows - The height in terms of number of rows displayed in Grid's body. If Grid doesn't contain enough rows, white space is displayed instead. If null is given, then Grid's height is undefined

Throws:

java.lang.IllegalArgumentException - if rows is zero or less

java.lang.IllegalArgumentException - if rows is infinite

java.lang.IllegalArgumentException - if rows is NaN

getHeightByRows

public double getHeightByRows()

Gets the amount of rows in Grid's body that are shown, while getHeightMode() is HeightMode.ROW.

Returns:

the amount of rows that are being shown in Grid's body

See Also:

setHeightByRows(double)

setHeight

public void setHeight(float height,
                      Sizeable.Unit unit)

Sets the height of the object. Negative number implies unspecified size (terminal is free to set the size).

Note: This method will change the widget's size in the browser only if getHeightMode() returns HeightMode.CSS.

Specified by:

setHeight in interface Sizeable

Overrides:

setHeight in class AbstractComponent

Parameters:

height - the height of the object.

unit - the unit used for the width.

See Also:

setHeightMode(HeightMode)

setHeightMode

public void setHeightMode(com.vaadin.shared.ui.grid.HeightMode heightMode)

Defines the mode in which the Grid widget's height is calculated.

If HeightMode.CSS is given, Grid will respect the values given via a setHeight-method, and behave as a traditional Component.

If HeightMode.ROW is given, Grid will make sure that the body will display as many rows as getHeightByRows() defines. Note: If headers/footers are inserted or removed, the widget will resize itself to still display the required amount of rows in its body. It also takes the horizontal scrollbar into account.

Parameters:

heightMode - the mode in to which Grid should be set

getHeightMode

public com.vaadin.shared.ui.grid.HeightMode getHeightMode()

Returns the current HeightMode the Grid is in.

Defaults to HeightMode.CSS.

Returns:

the current HeightMode

setSelectionModel

public void setSelectionModel(SelectionModel selectionModel)
                       throws java.lang.IllegalArgumentException

Takes a new SelectionModel into use.

The SelectionModel that is previously in use will have all its items deselected.

If the given SelectionModel is already in use, this method does nothing.

Parameters:

selectionModel - the new SelectionModel to use

Throws:

java.lang.IllegalArgumentException - if selectionModel is null

getSelectionModel

public SelectionModel getSelectionModel()

Returns the currently used SelectionModel.

Returns:

the currently used SelectionModel

setSelectionMode

public SelectionModel setSelectionMode(Grid.SelectionMode selectionMode)
                                throws java.lang.IllegalArgumentException

Changes the Grid's selection mode.

Grid supports three selection modes: multiselect, single select and no selection, and this is a conveniency method for choosing between one of them.

Technically, this method is a shortcut that can be used instead of calling setSelectionModel with a specific SelectionModel instance. Grid comes with three built-in SelectionModel classes, and the Grid.SelectionMode enum represents each of them.

Essentially, the two following method calls are equivalent:

 grid.setSelectionMode(SelectionMode.MULTI);
 grid.setSelectionModel(new MultiSelectionMode());
 

Parameters:

selectionMode - the selection mode to switch to

Returns:

The SelectionModel instance that was taken into use

Throws:

java.lang.IllegalArgumentException - if selectionMode is null

See Also:

SelectionModel

isSelected

public boolean isSelected(java.lang.Object itemId)

Checks whether an item is selected or not.

Parameters:

itemId - the item id to check for

Returns:

true iff the item is selected

getSelectedRows

public java.util.Collection<java.lang.Object> getSelectedRows()

Returns a collection of all the currently selected itemIds.

This method is a shorthand that is forwarded to the object that is returned by getSelectionModel().

Returns:

a collection of all the currently selected itemIds

getSelectedRow

public java.lang.Object getSelectedRow()
                                throws java.lang.IllegalStateException

Gets the item id of the currently selected item.

This method is a shorthand that is forwarded to the object that is returned by getSelectionModel(). Only SelectionModel.Single is supported.

Returns:

the item id of the currently selected item, or null if nothing is selected

Throws:

java.lang.IllegalStateException - if the object that is returned by getSelectionModel() is not an instance of SelectionModel.Single

select

public boolean select(java.lang.Object itemId)
               throws java.lang.IllegalArgumentException,
                      java.lang.IllegalStateException

Marks an item as selected.

This method is a shorthand that is forwarded to the object that is returned by getSelectionModel(). Only SelectionModel.Single or SelectionModel.Multi are supported.

Parameters:

itemIds - the itemId to mark as selected

Returns:

true if the selection state changed. false if the itemId already was selected

Throws:

java.lang.IllegalArgumentException - if the itemId doesn't exist in the currently active Container

java.lang.IllegalStateException - if the selection was illegal. One such reason might be that the implementation already had an item selected, and that needs to be explicitly deselected before re-selecting something

java.lang.IllegalStateException - if the object that is returned by getSelectionModel() does not implement SelectionModel.Single or SelectionModel.Multi

deselect

public boolean deselect(java.lang.Object itemId)
                 throws java.lang.IllegalStateException

Marks an item as deselected.

This method is a shorthand that is forwarded to the object that is returned by getSelectionModel(). Only SelectionModel.Single and SelectionModel.Multi are supported.

Parameters:

itemId - the itemId to remove from being selected

Returns:

true if the selection state changed. false if the itemId already was selected

Throws:

java.lang.IllegalArgumentException - if the itemId doesn't exist in the currently active Container

java.lang.IllegalStateException - if the deselection was illegal. One such reason might be that the implementation already had an item selected, and that needs to be explicitly deselected before re-selecting something

java.lang.IllegalStateException - if the object that is returned by getSelectionModel() does not implement SelectionModel.Single or SelectionModel.Multi

fireSelectionChangeEvent

public void fireSelectionChangeEvent(java.util.Collection<java.lang.Object> oldSelection,
                                     java.util.Collection<java.lang.Object> newSelection)

Fires a selection change event.

Note: This is not a method that should be called by application logic. This method is publicly accessible only so that SelectionModels would be able to inform Grid of these events.

Parameters:

addedSelections - the selections that were added by this event

removedSelections - the selections that were removed by this event

addSelectionChangeListener

public void addSelectionChangeListener(SelectionChangeListener listener)

Description copied from interface: SelectionChangeNotifier

Registers a new selection change listener

Specified by:

addSelectionChangeListener in interface SelectionChangeNotifier

Parameters:

listener - the listener to register

removeSelectionChangeListener

public void removeSelectionChangeListener(SelectionChangeListener listener)

Description copied from interface: SelectionChangeNotifier

Removes a previously registered selection change listener

Specified by:

removeSelectionChangeListener in interface SelectionChangeNotifier

Parameters:

listener - the listener to remove

sort

public void sort(Sort s)

Sets the current sort order using the fluid Sort API. Read the documentation for Sort for more information.

Parameters:

s - a sort instance

sort

public void sort(java.lang.Object propertyId)

Sort this Grid in ascending order by a specified property.

Parameters:

propertyId - a property ID

sort

public void sort(java.lang.Object propertyId,
                 com.vaadin.shared.ui.grid.SortDirection direction)

Sort this Grid in user-specified SortOrder by a property.

Parameters:

propertyId - a property ID

direction - a sort order value (ascending/descending)

clearSortOrder

public void clearSortOrder()

Clear the current sort order, and re-sort the grid.

setSortOrder

public void setSortOrder(java.util.List<SortOrder> order)

Sets the sort order to use. This method throws IllegalStateException if the attached container is not a Container.Sortable, and IllegalArgumentException if a property in the list is not recognized by the container, or if the 'order' parameter is null.

Parameters:

order - a sort order list.

getSortOrder

public java.util.List<SortOrder> getSortOrder()

Get the current sort order list.

Returns:

a sort order list

addSortOrderChangeListener

public void addSortOrderChangeListener(SortOrderChangeListener listener)

Adds a sort order change listener that gets notified when the sort order changes.

Parameters:

listener - the sort order change listener to add

removeSortOrderChangeListener

public void removeSortOrderChangeListener(SortOrderChangeListener listener)

Removes a sort order change listener previously added using addSortOrderChangeListener(SortOrderChangeListener).

Parameters:

listener - the sort order change listener to remove