com.vaadin.ui
Class Grid

java.lang.Object
  extended by com.vaadin.server.AbstractClientConnector
      extended by com.vaadin.ui.AbstractComponent
          extended by com.vaadin.ui.Grid
All Implemented Interfaces:
ItemClickEvent.ItemClickNotifier, MethodEventSource, SelectionEvent.SelectionNotifier, SortEvent.SortNotifier, ClientConnector, Sizeable, com.vaadin.shared.Connector, Component, HasComponents, SelectiveRenderer, java.io.Serializable, java.lang.Iterable<Component>

public class Grid
extends AbstractComponent
implements SelectionEvent.SelectionNotifier, SortEvent.SortNotifier, SelectiveRenderer, ItemClickEvent.ItemClickNotifier

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);
 Column 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:
7.4
Author:
Vaadin Ltd
See Also:
Serialized Form

Nested Class Summary
static class Grid.AbstractRenderer<T>
          An abstract base class for server-side Grid renderers.
static class Grid.AbstractSelectionModel
          A base class for SelectionModels that contains some of the logic that is reusable.
static class Grid.CellReference
          A data class which contains information which identifies a cell in a Grid.
static interface Grid.CellStyleGenerator
          Callback interface for generating custom style names for cells
static class Grid.Column
          A column in the grid.
static class Grid.CommitErrorEvent
          An event which is fired when saving the editor fails
 class Grid.DefaultEditorErrorHandler
          Default error handler for the editor
static interface Grid.EditorErrorHandler
          Error handler for the editor
static class Grid.EditorFieldFactory
          Field factory used by default in the editor.
protected static class Grid.Footer
          Represents the footer section of a Grid.
static class Grid.FooterCell
          Represents a footer cell in Grid.
static class Grid.FooterRow
          Represents a footer row in Grid.
protected static class Grid.Header
          Represents the header section of a Grid.
static class Grid.HeaderCell
          Represents a header cell in Grid.
static class Grid.HeaderRow
          Represents a header row in Grid.
static class Grid.MultiSelectionModel
          A default implementation of a Grid.SelectionModel.Multi
static class Grid.NoSelectionModel
          A default implementation for a Grid.SelectionModel.None
static class Grid.RowReference
          A data class which contains information which identifies a row in a Grid.
static interface Grid.RowStyleGenerator
          Callback interface for generating custom style names for data rows
static class Grid.SelectionMode
          Selection modes representing built-in SelectionModels that come bundled with Grid.
static interface Grid.SelectionModel
          The server-side interface that controls Grid's selection state.
static class Grid.SingleSelectionModel
          A default implementation of a Grid.SelectionModel.Single
protected static class Grid.StaticSection<ROWTYPE extends com.vaadin.ui.Grid.StaticSection.StaticRow<?>>
          Abstract base class for Grid header and footer sections.
 
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 class com.vaadin.ui.AbstractComponent
DESIGN_ATTR_PLAIN_TEXT
 
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()
          Creates a new Grid with a new IndexedContainer as the data source.
Grid(Container.Indexed dataSource)
          Creates a new Grid using the given data source.
Grid(java.lang.String caption)
          Creates a new Grid with the given caption and a new IndexedContainer data source.
Grid(java.lang.String caption, Container.Indexed dataSource)
          Creates a new Grid with the given caption and data source.
 
Method Summary
 Grid.Column addColumn(java.lang.Object propertyId)
          Adds a new Column to Grid.
 Grid.Column addColumn(java.lang.Object propertyId, java.lang.Class<?> type)
          Adds a new Column to Grid.
protected  void addColumnProperty(java.lang.Object propertyId, java.lang.Class<?> type, java.lang.Object defaultValue)
           
 Grid.FooterRow addFooterRowAt(int index)
          Inserts a new row at the given position to the footer section.
 Grid.HeaderRow addHeaderRowAt(int index)
          Inserts a new row at the given position to the header section.
 void addItemClickListener(ItemClickEvent.ItemClickListener listener)
          Register a listener to handle ItemClickEvents.
 void addListener(ItemClickEvent.ItemClickListener listener)
          Deprecated. 
 java.lang.Object addRow(java.lang.Object... values)
          Adds a row to the underlying container.
 void addSelectionListener(SelectionEvent.SelectionListener listener)
          Registers a new selection listener
 void addSortListener(SortEvent.SortListener listener)
          Adds a sort order change listener that gets notified when the sort order changes.
 Grid.FooterRow appendFooterRow()
          Adds a new row at the bottom of the footer section.
 Grid.HeaderRow appendHeaderRow()
          Adds a new row at the bottom of the header section.
 void beforeClientResponse(boolean initial)
          Called before the shared state and RPC invocations are sent to the client.
 void cancelEditor()
          Cancels the currently active edit if any.
 void clearSortOrder()
          Clear the current sort order, and re-sort the grid.
 boolean deselect(java.lang.Object itemId)
          Marks an item as unselected.
protected  void doCancelEditor()
           
protected  void doEditItem()
           
 void editItem(java.lang.Object itemId)
          Opens the editor interface for the provided item.
 void fireSelectionEvent(java.util.Collection<java.lang.Object> oldSelection, java.util.Collection<java.lang.Object> newSelection)
          Fires a selection change event.
 Grid.CellStyleGenerator getCellStyleGenerator()
          Gets the style generator that is used for generating styles for cells
 Grid.Column getColumn(java.lang.Object propertyId)
          Returns a column based on the property id
 java.util.List<Grid.Column> getColumns()
          Returns a copy of currently configures columns in their current visual order in this Grid.
 Container.Indexed getContainerDataSource()
          Returns the grid data source.
 Grid.HeaderRow getDefaultHeaderRow()
          Returns the current default row of the header section.
 java.lang.Object getEditedItemId()
          Gets the id of the item that is currently being edited.
 java.lang.String getEditorCancelCaption()
          Gets the current caption of the cancel button in the Grid editor.
 Grid.EditorErrorHandler getEditorErrorHandler()
          Gets the error handler used for the editor
 FieldGroupFieldFactory getEditorFieldFactory()
          Gets the field factory for the FieldGroup.
 FieldGroup getEditorFieldGroup()
          Gets the field group that is backing the item editor of this grid.
 java.lang.String getEditorSaveCaption()
          Gets the current caption of the save button in the Grid editor.
protected  Grid.Footer getFooter()
          Returns the footer section of this grid.
 Grid.FooterRow getFooterRow(int rowIndex)
          Gets the footer row at given index.
 int getFooterRowCount()
          Gets the row count for the footer.
 int getFrozenColumnCount()
          Gets the number of frozen columns in this grid.
protected  Grid.Header getHeader()
          Returns the header section of this grid.
 Grid.HeaderRow getHeaderRow(int rowIndex)
          Gets the header row at given index.
 int getHeaderRowCount()
          Gets the row count for the header section.
 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.
 Grid.RowStyleGenerator getRowStyleGenerator()
          Gets the style generator that is used for generating styles for rows
 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.
 Grid.SelectionModel getSelectionModel()
          Returns the currently used Grid.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 isEditorActive()
          Returns whether an item is currently being edited in the editor.
 boolean isEditorEnabled()
          Checks whether the item editor UI is enabled for this grid.
 boolean isFooterVisible()
          Returns the visibility of the footer section.
 boolean isHeaderVisible()
          Returns the visibility of the header section.
 boolean isRendered(Component childComponent)
          Checks if the child component should be rendered (sent to the client side).
 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.
 Grid.FooterRow prependFooterRow()
          Adds a new row at the top of the footer section.
 Grid.HeaderRow prependHeaderRow()
          Adds a new row at the top of the header section.
 void recalculateColumnWidths()
          Requests that the column widths should be recalculated.
 void removeAllColumns()
          Removes all columns from this Grid.
 void removeColumn(java.lang.Object propertyId)
          Removes a column from Grid based on a property id.
 void removeFooterRow(Grid.FooterRow row)
          Removes the given row from the footer section.
 void removeFooterRow(int rowIndex)
          Removes the row at the given position from the footer section.
 void removeHeaderRow(Grid.HeaderRow row)
          Removes the given row from the header section.
 void removeHeaderRow(int rowIndex)
          Removes the row at the given position from the header section.
 void removeItemClickListener(ItemClickEvent.ItemClickListener listener)
          Removes an ItemClickListener.
 void removeListener(ItemClickEvent.ItemClickListener listener)
          Deprecated. 
 void removeSelectionListener(SelectionEvent.SelectionListener listener)
          Removes a previously registered selection change listener
 void removeSortListener(SortEvent.SortListener listener)
          Removes a sort order change listener previously added using #addSortListener(SortListener).
 void saveEditor()
          Saves all changes done to the bound fields.
 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 setCellStyleGenerator(Grid.CellStyleGenerator cellStyleGenerator)
          Sets the style generator that is used for generating styles for cells
 void setColumnOrder(java.lang.Object... propertyIds)
          Sets a new column order for the grid.
 void setContainerDataSource(Container.Indexed container)
          Sets the grid data source.
 void setDefaultHeaderRow(Grid.HeaderRow row)
          Sets the default row of the header.
 void setEditorCancelCaption(java.lang.String cancelCaption)
          Sets the caption on the cancel button in the Grid editor.
 void setEditorEnabled(boolean isEnabled)
          Sets whether or not the item editor UI is enabled for this grid.
 void setEditorErrorHandler(Grid.EditorErrorHandler editorErrorHandler)
          Sets the error handler for the editor.
 void setEditorFieldFactory(FieldGroupFieldFactory fieldFactory)
          Sets the field factory for the FieldGroup.
 void setEditorFieldGroup(FieldGroup fieldGroup)
          Sets the field group that is backing the item editor of this grid.
 void setEditorSaveCaption(java.lang.String saveCaption)
          Sets the caption on the save button in the Grid editor.
 void setFooterVisible(boolean visible)
          Sets the visibility of the footer section.
 void setFrozenColumnCount(int numberOfColumns)
          Sets the number of frozen columns in this grid.
 void setHeaderVisible(boolean visible)
          Sets the visibility of the header section.
 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 setRowStyleGenerator(Grid.RowStyleGenerator rowStyleGenerator)
          Sets the style generator that is used for generating styles for rows
 Grid.SelectionModel setSelectionMode(Grid.SelectionMode selectionMode)
          Sets the Grid's selection mode.
 void setSelectionModel(Grid.SelectionModel selectionModel)
          Takes a new Grid.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.data.sort.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, detach, findAncestor, fireComponentErrorEvent, fireComponentEvent, focus, getActionManager, getCaption, getComponentError, getCustomAttributes, getData, getDebugId, getDescription, getErrorMessage, getHeight, getHeightUnits, getIcon, getId, getLocale, getParent, getPrimaryStyleName, getStyleName, getWidth, getWidthUnits, isCaptionAsHtml, isConnectorEnabled, isEnabled, isImmediate, isOrHasAncestor, isReadOnly, isVisible, readDesign, removeListener, removeShortcutListener, removeStyleName, setCaption, setCaptionAsHtml, setComponentError, setData, setDebugId, setDescription, setEnabled, setHeight, setHeightUndefined, setIcon, setId, setImmediate, setLocale, setParent, setPrimaryStyleName, setReadOnly, setSizeFull, setSizeUndefined, setStyleName, setVisible, setWidth, setWidth, setWidthUndefined, writeDesign
 
Methods inherited from class com.vaadin.server.AbstractClientConnector
addAttachListener, addDetachListener, addExtension, addListener, addListener, addListener, addMethodInvocationToQueue, createState, encodeState, equals, fireEvent, getAllChildrenIterable, getConnectorId, getErrorHandler, getExtensions, getListeners, getResource, getRpcManager, getRpcProxy, getSession, getStateType, getUI, handleConnectorRequest, hashCode, hasListeners, isAttached, isThis, markAsDirty, markAsDirtyRecursive, registerRpc, registerRpc, removeAttachListener, removeDetachListener, removeExtension, removeListener, removeListener, removeListener, removeListener, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler, setResource
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, 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, readDesign, removeListener, removeStyleName, setCaption, setEnabled, setIcon, setId, setParent, setPrimaryStyleName, setReadOnly, setStyleName, setVisible, writeDesign
 
Methods inherited from interface com.vaadin.server.ClientConnector
addAttachListener, addDetachListener, 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()
Creates a new Grid with a new IndexedContainer as the data source.


Grid

public Grid(Container.Indexed dataSource)
Creates a new Grid using the given data source.

Parameters:
dataSource - the indexed container to use as a data source

Grid

public Grid(java.lang.String caption)
Creates a new Grid with the given caption and a new IndexedContainer data source.

Parameters:
caption - the caption of the grid

Grid

public Grid(java.lang.String caption,
            Container.Indexed dataSource)
Creates a new Grid with the given caption and data source. If the data source is null, a new IndexedContainer will be used.

Parameters:
caption - the caption of the grid
dataSource - the indexed container to use as a data source
Method Detail

beforeClientResponse

public void beforeClientResponse(boolean initial)
Description copied from interface: ClientConnector
Called before the shared state and RPC invocations are sent to the client. Gives the connector an opportunity to set computed/dynamic state values or to invoke last minute RPC methods depending on other component features.

This method must not alter the component hierarchy in any way. Calling ClientConnector.markAsDirty() from this method will have no effect.

Specified by:
beforeClientResponse in interface ClientConnector
Overrides:
beforeClientResponse in class AbstractComponent
Parameters:
initial - true if the client-side connector will be created and initialized after this method has been invoked. false if there is already an initialized client-side connector.

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 Grid.Column 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

getColumns

public java.util.List<Grid.Column> getColumns()
Returns a copy of currently configures columns in their current visual order in this Grid.

Returns:
unmodifiable copy of current columns in visual order

addColumn

public Grid.Column addColumn(java.lang.Object propertyId)
                      throws java.lang.IllegalStateException
Adds a new Column to Grid. Also adds the property to container with data type String, if property for column does not exist in it. Default value for the new property is an empty String.

Note that adding a new property is only done for the default container that Grid sets up with the default constructor.

Parameters:
propertyId - the property id of the new column
Returns:
the new column
Throws:
java.lang.IllegalStateException - if column for given property already exists in this grid

addColumn

public Grid.Column addColumn(java.lang.Object propertyId,
                             java.lang.Class<?> type)
Adds a new Column to Grid. This function makes sure that the property with the given id and data type exists in the container. If property does not exists, it will be created.

Default value for the new property is 0 if type is Integer, Double and Float. If type is String, default value is an empty string. For all other types the default value is null.

Note that adding a new property is only done for the default container that Grid sets up with the default constructor.

Parameters:
propertyId - the property id of the new column
type - the data type for the new property
Returns:
the new column
Throws:
java.lang.IllegalStateException - if column for given property already exists in this grid or property already exists in the container with wrong type

addColumnProperty

protected void addColumnProperty(java.lang.Object propertyId,
                                 java.lang.Class<?> type,
                                 java.lang.Object defaultValue)
                          throws java.lang.IllegalStateException
Throws:
java.lang.IllegalStateException

removeAllColumns

public void removeAllColumns()
Removes all columns from this Grid.


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()

removeColumn

public void removeColumn(java.lang.Object propertyId)
                  throws java.lang.IllegalArgumentException
Removes a column from Grid based on a property id.

Parameters:
propertyId - The property id of column to be removed
Throws:
java.lang.IllegalArgumentException - if there is no column for given property id in this grid

setColumnOrder

public void setColumnOrder(java.lang.Object... propertyIds)
Sets a new column order for the grid. All columns which are not ordered here will remain in the order they were before as the last columns of grid.

Parameters:
propertyIds - properties in the order columns should be

setFrozenColumnCount

public void setFrozenColumnCount(int numberOfColumns)
Sets the number of frozen columns in this grid. Setting the count to 0 means that no data columns will be frozen, but the built-in selection checkbox column will still be frozen if it's in use. Setting the count to -1 will also disable the selection column.

The default value is 0.

Parameters:
numberOfColumns - the number of columns that should be frozen
Throws:
java.lang.IllegalArgumentException - if the column count is < 0 or > the number of visible columns

getFrozenColumnCount

public int getFrozenColumnCount()
Gets the number of frozen columns in this grid. 0 means that no data columns will be frozen, but the built-in selection checkbox column will still be frozen if it's in use. -1 means that not even the selection column is frozen.

Returns:
the number of frozen columns
See Also:
setFrozenColumnCount(int)

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(Grid.SelectionModel selectionModel)
                       throws java.lang.IllegalArgumentException
Takes a new Grid.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 Grid.SelectionModel getSelectionModel()
Returns the currently used Grid.SelectionModel.

Returns:
the currently used SelectionModel

setSelectionMode

public Grid.SelectionModel setSelectionMode(Grid.SelectionMode selectionMode)
                                     throws java.lang.IllegalArgumentException
Sets the Grid's selection mode.

Grid supports three selection modes: multiselect, single select and no selection, and this is a convenience 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 Grid.SelectionModel instance that was taken into use
Throws:
java.lang.IllegalArgumentException - if selectionMode is null
See Also:
Grid.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 delegates to the selection model.

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 delegates to the selection model. Only Grid.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 selection model does not implement 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 delegates to the selection model. Only Grid.SelectionModel.Single and Grid.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 selection model does not implement SelectionModel.Single or SelectionModel.Multi

deselect

public boolean deselect(java.lang.Object itemId)
                 throws java.lang.IllegalStateException
Marks an item as unselected.

This method is a shorthand that delegates to the selection model. Only Grid.SelectionModel.Single and Grid.SelectionModel.Multi are supported.

Parameters:
itemId - the itemId to remove from being selected
Returns:
true if the selection state changed, false if the itemId was already 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 requires one or more items to be selected at all times.
java.lang.IllegalStateException - if the selection model does not implement SelectionModel.Single or {code SelectionModel.Multi}

fireSelectionEvent

public void fireSelectionEvent(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

addSelectionListener

public void addSelectionListener(SelectionEvent.SelectionListener listener)
Description copied from interface: SelectionEvent.SelectionNotifier
Registers a new selection listener

Specified by:
addSelectionListener in interface SelectionEvent.SelectionNotifier
Parameters:
listener - the listener to register

removeSelectionListener

public void removeSelectionListener(SelectionEvent.SelectionListener listener)
Description copied from interface: SelectionEvent.SelectionNotifier
Removes a previously registered selection change listener

Specified by:
removeSelectionListener in interface SelectionEvent.SelectionNotifier
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.

Note: Sorting by a property that has no column in Grid will hide all possible sorting indicators.

Parameters:
s - a sort instance
Throws:
java.lang.IllegalStateException - if container is not sortable (does not implement Container.Sortable)
java.lang.IllegalArgumentException - if trying to sort by non-existing property

sort

public void sort(java.lang.Object propertyId)
Sort this Grid in ascending order by a specified property.

Note: Sorting by a property that has no column in Grid will hide all possible sorting indicators.

Parameters:
propertyId - a property ID
Throws:
java.lang.IllegalStateException - if container is not sortable (does not implement Container.Sortable)
java.lang.IllegalArgumentException - if trying to sort by non-existing property

sort

public void sort(java.lang.Object propertyId,
                 com.vaadin.shared.data.sort.SortDirection direction)
Sort this Grid in user-specified SortOrder by a property.

Note: Sorting by a property that has no column in Grid will hide all possible sorting indicators.

Parameters:
propertyId - a property ID
direction - a sort order value (ascending/descending)
Throws:
java.lang.IllegalStateException - if container is not sortable (does not implement Container.Sortable)
java.lang.IllegalArgumentException - if trying to sort by non-existing property

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.

Note: Sorting by a property that has no column in Grid will hide all possible sorting indicators.

Parameters:
order - a sort order list.
Throws:
java.lang.IllegalStateException - if container is not sortable (does not implement Container.Sortable)
java.lang.IllegalArgumentException - if order is null or trying to sort by non-existing property

getSortOrder

public java.util.List<SortOrder> getSortOrder()
Get the current sort order list.

Returns:
a sort order list

addSortListener

public void addSortListener(SortEvent.SortListener listener)
Adds a sort order change listener that gets notified when the sort order changes.

Specified by:
addSortListener in interface SortEvent.SortNotifier
Parameters:
listener - the sort order change listener to add

removeSortListener

public void removeSortListener(SortEvent.SortListener listener)
Removes a sort order change listener previously added using #addSortListener(SortListener).

Specified by:
removeSortListener in interface SortEvent.SortNotifier
Parameters:
listener - the sort order change listener to remove

getHeader

protected Grid.Header getHeader()
Returns the header section of this grid. The default header contains a single row displaying the column captions.

Returns:
the header

getHeaderRow

public Grid.HeaderRow getHeaderRow(int rowIndex)
Gets the header row at given index.

Parameters:
rowIndex - 0 based index for row. Counted from top to bottom
Returns:
header row at given index
Throws:
java.lang.IllegalArgumentException - if no row exists at given index

addHeaderRowAt

public Grid.HeaderRow addHeaderRowAt(int index)
Inserts a new row at the given position to the header section. Shifts the row currently at that position and any subsequent rows down (adds one to their indices).

Parameters:
index - the position at which to insert the row
Returns:
the new row
Throws:
java.lang.IllegalArgumentException - if the index is less than 0 or greater than row count
See Also:
appendHeaderRow(), prependHeaderRow(), removeHeaderRow(HeaderRow), removeHeaderRow(int)

appendHeaderRow

public Grid.HeaderRow appendHeaderRow()
Adds a new row at the bottom of the header section.

Returns:
the new row
See Also:
prependHeaderRow(), addHeaderRowAt(int), removeHeaderRow(HeaderRow), removeHeaderRow(int)

getDefaultHeaderRow

public Grid.HeaderRow getDefaultHeaderRow()
Returns the current default row of the header section. The default row is a special header row providing a user interface for sorting columns. Setting a header text for column updates cells in the default header.

Returns:
the default row or null if no default row set

getHeaderRowCount

public int getHeaderRowCount()
Gets the row count for the header section.

Returns:
row count

prependHeaderRow

public Grid.HeaderRow prependHeaderRow()
Adds a new row at the top of the header section.

Returns:
the new row
See Also:
appendHeaderRow(), addHeaderRowAt(int), removeHeaderRow(HeaderRow), removeHeaderRow(int)

removeHeaderRow

public void removeHeaderRow(Grid.HeaderRow row)
Removes the given row from the header section.

Parameters:
row - the row to be removed
Throws:
java.lang.IllegalArgumentException - if the row does not exist in this section
See Also:
removeHeaderRow(int), addHeaderRowAt(int), appendHeaderRow(), prependHeaderRow()

removeHeaderRow

public void removeHeaderRow(int rowIndex)
Removes the row at the given position from the header section.

Parameters:
index - the position of the row
Throws:
java.lang.IllegalArgumentException - if no row exists at given index
See Also:
removeHeaderRow(HeaderRow), addHeaderRowAt(int), appendHeaderRow(), prependHeaderRow()

setDefaultHeaderRow

public void setDefaultHeaderRow(Grid.HeaderRow row)
Sets the default row of the header. The default row is a special header row providing a user interface for sorting columns.

Parameters:
row - the new default row, or null for no default row
Throws:
java.lang.IllegalArgumentException - header does not contain the row

setHeaderVisible

public void setHeaderVisible(boolean visible)
Sets the visibility of the header section.

Parameters:
visible - true to show header section, false to hide

isHeaderVisible

public boolean isHeaderVisible()
Returns the visibility of the header section.

Returns:
true if visible, false otherwise.

getFooter

protected Grid.Footer getFooter()
Returns the footer section of this grid. The default header contains a single row displaying the column captions.

Returns:
the footer

getFooterRow

public Grid.FooterRow getFooterRow(int rowIndex)
Gets the footer row at given index.

Parameters:
rowIndex - 0 based index for row. Counted from top to bottom
Returns:
footer row at given index
Throws:
java.lang.IllegalArgumentException - if no row exists at given index

addFooterRowAt

public Grid.FooterRow addFooterRowAt(int index)
Inserts a new row at the given position to the footer section. Shifts the row currently at that position and any subsequent rows down (adds one to their indices).

Parameters:
index - the position at which to insert the row
Returns:
the new row
Throws:
java.lang.IllegalArgumentException - if the index is less than 0 or greater than row count
See Also:
appendFooterRow(), prependFooterRow(), removeFooterRow(FooterRow), removeFooterRow(int)

appendFooterRow

public Grid.FooterRow appendFooterRow()
Adds a new row at the bottom of the footer section.

Returns:
the new row
See Also:
prependFooterRow(), addFooterRowAt(int), removeFooterRow(FooterRow), removeFooterRow(int)

getFooterRowCount

public int getFooterRowCount()
Gets the row count for the footer.

Returns:
row count

prependFooterRow

public Grid.FooterRow prependFooterRow()
Adds a new row at the top of the footer section.

Returns:
the new row
See Also:
appendFooterRow(), addFooterRowAt(int), removeFooterRow(FooterRow), removeFooterRow(int)

removeFooterRow

public void removeFooterRow(Grid.FooterRow row)
Removes the given row from the footer section.

Parameters:
row - the row to be removed
Throws:
java.lang.IllegalArgumentException - if the row does not exist in this section
See Also:
removeFooterRow(int), addFooterRowAt(int), appendFooterRow(), prependFooterRow()

removeFooterRow

public void removeFooterRow(int rowIndex)
Removes the row at the given position from the footer section.

Parameters:
index - the position of the row
Throws:
java.lang.IllegalArgumentException - if no row exists at given index
See Also:
removeFooterRow(FooterRow), addFooterRowAt(int), appendFooterRow(), prependFooterRow()

setFooterVisible

public void setFooterVisible(boolean visible)
Sets the visibility of the footer section.

Parameters:
visible - true to show footer section, false to hide

isFooterVisible

public boolean isFooterVisible()
Returns the visibility of the footer section.

Returns:
true if visible, false otherwise.

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.

isRendered

public boolean isRendered(Component childComponent)
Description copied from interface: SelectiveRenderer
Checks if the child component should be rendered (sent to the client side). This method allows hiding a child component from updates and communication to and from the client. It is mostly useful for parents which show only a limited number of their children at any given time and want to allow updates only for the visible children (e.g. TabSheet has one tab open at a time).

This method can only prevent updates from reaching the client, not force child components to reach the client. If the child is set to visible, returning false will prevent the child from being sent to the client. If a child is set to invisible, this method has no effect.

Specified by:
isRendered in interface SelectiveRenderer
Parameters:
childComponent - The child component to check
Returns:
true if the child component may be sent to the client, false otherwise

setCellStyleGenerator

public void setCellStyleGenerator(Grid.CellStyleGenerator cellStyleGenerator)
Sets the style generator that is used for generating styles for cells

Parameters:
cellStyleGenerator - the cell style generator to set, or null to remove a previously set generator

getCellStyleGenerator

public Grid.CellStyleGenerator getCellStyleGenerator()
Gets the style generator that is used for generating styles for cells

Returns:
the cell style generator, or null if no generator is set

setRowStyleGenerator

public void setRowStyleGenerator(Grid.RowStyleGenerator rowStyleGenerator)
Sets the style generator that is used for generating styles for rows

Parameters:
rowStyleGenerator - the row style generator to set, or null to remove a previously set generator

getRowStyleGenerator

public Grid.RowStyleGenerator getRowStyleGenerator()
Gets the style generator that is used for generating styles for rows

Returns:
the row style generator, or null if no generator is set

addRow

public java.lang.Object addRow(java.lang.Object... values)
Adds a row to the underlying container. The order of the parameters should match the current visible column order.

Please note that it's generally only safe to use this method during initialization. After Grid has been initialized and the visible column order might have been changed, it's better to instead add items directly to the underlying container and use Item.getItemProperty(Object) to make sure each value is assigned to the intended property.

Parameters:
values - the cell values of the new row, in the same order as the visible column order, not null.
Returns:
the item id of the new row
Throws:
java.lang.IllegalArgumentException - if values is null
java.lang.IllegalArgumentException - if its length does not match the number of visible columns
java.lang.IllegalArgumentException - if a parameter value is not an instance of the corresponding property type
java.lang.UnsupportedOperationException - if the container does not support adding new items

setEditorEnabled

public void setEditorEnabled(boolean isEnabled)
                      throws java.lang.IllegalStateException
Sets whether or not the item editor UI is enabled for this grid. When the editor is enabled, the user can open it by double-clicking a row or hitting enter when a row is focused. The editor can also be opened programmatically using the editItem(Object) method.

Parameters:
isEnabled - true to enable the feature, false otherwise
Throws:
java.lang.IllegalStateException - if an item is currently being edited
See Also:
getEditedItemId()

isEditorEnabled

public boolean isEditorEnabled()
Checks whether the item editor UI is enabled for this grid.

Returns:
true iff the editor is enabled for this grid
See Also:
setEditorEnabled(boolean), getEditedItemId()

getEditedItemId

public java.lang.Object getEditedItemId()
Gets the id of the item that is currently being edited.

Returns:
the id of the item that is currently being edited, or null if no item is being edited at the moment

getEditorFieldGroup

public FieldGroup getEditorFieldGroup()
Gets the field group that is backing the item editor of this grid.

Returns:
the backing field group

setEditorFieldGroup

public void setEditorFieldGroup(FieldGroup fieldGroup)
Sets the field group that is backing the item editor of this grid.

Parameters:
fieldGroup - the backing field group
Throws:
java.lang.IllegalStateException - if the editor is currently active

isEditorActive

public boolean isEditorActive()
Returns whether an item is currently being edited in the editor.

Returns:
true iff the editor is open

editItem

public void editItem(java.lang.Object itemId)
              throws java.lang.IllegalStateException,
                     java.lang.IllegalArgumentException
Opens the editor interface for the provided item. Scrolls the Grid to bring the item to view if it is not already visible.

Parameters:
itemId - the id of the item to edit
Throws:
java.lang.IllegalStateException - if the editor is not enabled or already editing an item
java.lang.IllegalArgumentException - if the itemId is not in the backing container
See Also:
setEditorEnabled(boolean)

doEditItem

protected void doEditItem()

saveEditor

public void saveEditor()
                throws FieldGroup.CommitException
Saves all changes done to the bound fields.

Note: This is a pass-through call to the backing field group.

Throws:
FieldGroup.CommitException - If the commit was aborted
See Also:
FieldGroup.commit()

cancelEditor

public void cancelEditor()
Cancels the currently active edit if any. Hides the editor and discards possible unsaved changes in the editor fields.


doCancelEditor

protected void doCancelEditor()

setEditorFieldFactory

public void setEditorFieldFactory(FieldGroupFieldFactory fieldFactory)
Sets the field factory for the FieldGroup. The field factory is only used when FieldGroup creates a new field.

Note: This is a pass-through call to the backing field group.

Parameters:
fieldFactory - The field factory to use

setEditorErrorHandler

public void setEditorErrorHandler(Grid.EditorErrorHandler editorErrorHandler)
                           throws java.lang.IllegalArgumentException
Sets the error handler for the editor. The error handler is called whenever there is an exception in the editor.

Parameters:
editorErrorHandler - The editor error handler to use
Throws:
java.lang.IllegalArgumentException - if the error handler is null

getEditorErrorHandler

public Grid.EditorErrorHandler getEditorErrorHandler()
Gets the error handler used for the editor

Returns:
the editor error handler, never null
See Also:
AbstractClientConnector.setErrorHandler(com.vaadin.server.ErrorHandler)

getEditorFieldFactory

public FieldGroupFieldFactory getEditorFieldFactory()
Gets the field factory for the FieldGroup. The field factory is only used when FieldGroup creates a new field.

Note: This is a pass-through call to the backing field group.

Returns:
The field factory in use

setEditorSaveCaption

public void setEditorSaveCaption(java.lang.String saveCaption)
                          throws java.lang.IllegalArgumentException
Sets the caption on the save button in the Grid editor.

Parameters:
saveCaption - the caption to set
Throws:
java.lang.IllegalArgumentException - if saveCaption is null

getEditorSaveCaption

public java.lang.String getEditorSaveCaption()
Gets the current caption of the save button in the Grid editor.

Returns:
the current caption of the save button

setEditorCancelCaption

public void setEditorCancelCaption(java.lang.String cancelCaption)
                            throws java.lang.IllegalArgumentException
Sets the caption on the cancel button in the Grid editor.

Parameters:
cancelCaption - the caption to set
Throws:
java.lang.IllegalArgumentException - if cancelCaption is null

getEditorCancelCaption

public java.lang.String getEditorCancelCaption()
Gets the current caption of the cancel button in the Grid editor.

Returns:
the current caption of the cancel button

addItemClickListener

public void addItemClickListener(ItemClickEvent.ItemClickListener listener)
Description copied from interface: ItemClickEvent.ItemClickNotifier
Register a listener to handle ItemClickEvents.

Specified by:
addItemClickListener in interface ItemClickEvent.ItemClickNotifier
Parameters:
listener - ItemClickListener to be registered

addListener

@Deprecated
public void addListener(ItemClickEvent.ItemClickListener listener)
Deprecated. 

Specified by:
addListener in interface ItemClickEvent.ItemClickNotifier

removeItemClickListener

public void removeItemClickListener(ItemClickEvent.ItemClickListener listener)
Description copied from interface: ItemClickEvent.ItemClickNotifier
Removes an ItemClickListener.

Specified by:
removeItemClickListener in interface ItemClickEvent.ItemClickNotifier
Parameters:
listener - ItemClickListener to be removed

removeListener

@Deprecated
public void removeListener(ItemClickEvent.ItemClickListener listener)
Deprecated. 

Specified by:
removeListener in interface ItemClickEvent.ItemClickNotifier

recalculateColumnWidths

public void recalculateColumnWidths()
Requests that the column widths should be recalculated.

In most cases Grid will know when column widths need to be recalculated but this method can be used to force recalculation in situations when grid does not recalculate automatically.

Since:
7.4.1


Copyright © 2000-2014 Vaadin Ltd. All Rights Reserved.