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, HasComponents, java.io.Serializable, java.lang.Iterable<Component>

public class Grid
extends AbstractComponent
implements SelectionChangeNotifier, HasComponents

A grid component for displaying tabular data.

Grid is always bound to a Container.Indexed, but is not a Container of any kind in of itself. The contents of the given Container is displayed with the help of Renderers.

Headers and Footers

Converters and Renderers

Each column has its own Renderer that displays data into something that can be displayed in the browser. That data is first converted with a Converter into something that the Renderer can process. This can also be an implicit step - if a column has a simple data type, like a String, no explicit assignment is needed.

Usually a renderer takes some kind of object, and converts it into a HTML-formatted string.

 Grid grid = new Grid(myContainer);
 GridColumn column = grid.getColumn(STRING_DATE_PROPERTY);
 column.setConverter(new StringToDateConverter());
 column.setRenderer(new MyColorfulDateRenderer());
 

Lazy Loading

The data is accessed as it is needed by Grid and not any sooner. In other words, if the given Container is huge, but only the first few rows are displayed to the user, only those (and a few more, for caching purposes) are accessed.

Selection Modes and Models

Grid supports three selection modes (single, multi, none), and comes bundled with one model for each of the modes. The distinction between a selection mode and selection model is as follows: a mode essentially says whether you can have one, many or no rows selected. The model, however, has the behavioral details of each. A single selection model may require that the user deselects one row before selecting another one. A variant of a multiselect might have a configurable maximum of rows that may be selected. And so on.

 Grid grid = new Grid(myContainer);
 
 // uses the bundled SingleSelectionModel class
 grid.setSelectionMode(SelectionMode.SINGLE);
 
 // changes the behavior to a custom selection model
 grid.setSelectionModel(new MyTwoSelectionModel());
 

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.HasComponents

HasComponents.ComponentAttachDetachNotifier, HasComponents.ComponentAttachEvent, HasComponents.ComponentAttachListener, HasComponents.ComponentDetachEvent, HasComponents.ComponentDetachListener

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

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
Container.Indexed	getContainerDatasource() Returns the grid data source.
EditorRow	getEditorRow() Gets the editor row configuration object.
GridFooter	getFooter() Returns the footer section of this grid.
GridHeader	getHeader() Returns the header section of this grid.
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	isSelected(java.lang.Object itemId) Checks whether an item is selected or not.
java.util.Iterator<Component>	iterator() Gets an iterator to the collection of contained components.
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	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

addListener, addStyleName, attach, getCaption, getDescription, getIcon, getId, getLocale, getParent, getPrimaryStyleName, getStyleName, getUI, isEnabled, isReadOnly, isVisible, removeListener, removeStyleName, setCaption, setEnabled, setIcon, setId, setParent, setPrimaryStyleName, setReadOnly, setStyleName, setVisible

Methods inherited from interface com.vaadin.server.ClientConnector

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

Methods inherited from interface com.vaadin.shared.Connector

getConnectorId

Methods inherited from interface com.vaadin.server.Sizeable

getHeight, getHeightUnits, getWidth, getWidthUnits, setHeight, setHeightUndefined, setSizeFull, setSizeUndefined, setWidth, setWidth, setWidthUndefined

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

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

getHeader

public GridHeader getHeader()

Returns the header section of this grid. The default header contains a single row displaying the column captions.

Returns:

the header

getFooter

public GridFooter getFooter()

Returns the footer section of this grid. The default header contains a single row displaying the column captions.

Returns:

the footer

iterator

public java.util.Iterator<Component> iterator()

Description copied from interface: HasComponents

Gets an iterator to the collection of contained components. Using this iterator it is possible to step through all components contained in this container.

Specified by:

iterator in interface HasComponents

Specified by:

iterator in interface java.lang.Iterable<Component>

Returns:

the component iterator.

getEditorRow

public EditorRow getEditorRow()

Gets the editor row configuration object.

Returns:

the editor row configuration object