diff options
Diffstat (limited to 'documentation/components/components-grid.asciidoc')
| -rw-r--r-- | documentation/components/components-grid.asciidoc | 97 |
1 files changed, 27 insertions, 70 deletions
diff --git a/documentation/components/components-grid.asciidoc b/documentation/components/components-grid.asciidoc index c5510a3f80..a323dc28bb 100644 --- a/documentation/components/components-grid.asciidoc +++ b/documentation/components/components-grid.asciidoc @@ -60,7 +60,9 @@ API-level and functional differences to Table: * Grid has no generated columns. Instead, the container data source can be wrapped around a [classname]#GeneratedPropertyContainer#. * No column icons; you can implement them in a column with an [classname]#ImageRenderer#. * Components can not be shown in Grid cells; instead the much more efficient renderers can be used for the most common cases, and row editor for editing values. -* Limited support for drag and drop: the user can drag columns to reorder them. +* No support for drag and drop currently. +* No support for column resizing by dragging from column header boundaries. +* Focusing with [methodname]#focus()# is currently not supported. In addition, Grid has the following visual changes: @@ -84,7 +86,7 @@ You can set the container in the constructor or with [methodname]#setContainerDataSource()#. For example, if you have a collection of beans, you could wrap them in a Vaadin -[classname]#BeanContainer# or [classname]#BeanItemContainer#, and bind to a [classname]#Grid# as follows +[classname]#BeanItemContainer#, and bind to a [classname]#Grid# as follows [source, java] @@ -105,9 +107,6 @@ grid.setColumnOrder("name", "born"); layout.addComponent(grid); ---- -Note that you need to define [methodname]#equals()# and [methodname]#hashcode()# for -bean ([classname]#Person#) class to make the [classname]#BeanItemContainer# work properly. - [[components.grid.basic.manual]] === Default Data Source and Shorthands @@ -178,8 +177,8 @@ A [classname]#Grid# can be set to be in [literal]#++SINGLE++# (default), grid.setSelectionMode(SelectionMode.SINGLE); ---- -Empty (null) selection is allowed by default, but can be disabled -with [methodname]#setDeselectAllowed# in single-selection mode. +Empty (null) selection is allowed in multi-selection mode, but not in single +selection. The selection is handled with a different selection model object in each respective selection mode: [classname]#SingleSelectionModel#, @@ -253,8 +252,7 @@ should synchronize or reset the selection with the container, such as by calling === Multiple Selection In the multiple selection mode, a user can select multiple items by clicking on -the checkboxes in the leftmost column, or by using the spacebar to select/deselect the currently focused row. -(space key is a customizable default). +the checkboxes in the leftmost column. [[figure.components.grid.selection.multi]] .Multiple Selection in [classname]#Grid# @@ -303,8 +301,9 @@ delSelected.setEnabled(grid.getSelectedRows().size() > 0); Changes in the selection can be handled with a [interfacename]#SelectionListener#. The selection event object provides -[methodname]#getAdded()# and [methodname]#getRemoved()# to allow determining the -differences in the selection change. +[methodname]#getAdded()# and [methodname]#getRemove()# to allow determining the +differences in the selection change. When [classname]#Grid# is in immediate +mode, the difference is one item, but in non-immediate mode can be more. [source, java] @@ -328,13 +327,7 @@ grid.addSelectionListener(selection -> { // Java 8 In addition to selecting rows, you can focus individual cells. The focus can be moved with arrow keys and, if editing is enabled, pressing Enter opens the -editor. Normally pressing Tab or ShiftTab moves the focus to another component, -as usual. - -In editing or unbuffered mode, Tab or ShiftTab moves the focus to -next or previous cell. From first or last last cell of the row focus is moved -to a previous or a next line respectively. Note you can make your own subclass of -[classname]#DefaultEditorEventHandler# and change this behavior. +editor. Pressing Tab or ShiftTab moves the focus to another component, as usual. With mouse, you can focus a cell by clicking on it. The clicks can be handled with an [interfacename]#ItemClickListener#. The [classname]#ItemClickEvent# @@ -401,7 +394,7 @@ the [methodname]#removeColumn()#, as described later, or by hiding them in a === Hiding Columns Columns can be hidden by removing them with [methodname]#removeColumn()#. You -can remove all columns with [methodname]#removeAllColumns()#. The removed columns +can remove all columns with [methodname]#removeAllColumn()#. The removed columns are only removed from the grid, not from the container data source. To restore a previously removed column, you can call [methodname]#addColumn()# @@ -449,9 +442,6 @@ You can specify minimum and maximum widths for the expanding columns with [methodname]#setMinimumWidth()# and [methodname]#setMaximumWidth()#, respectively. -The user can resize columns by mouse dragging. In this case all the columns widths -are explicitly set to pixel values. - [[components.grid.columns.frozen]] === Frozen Columns @@ -523,7 +513,7 @@ The converter is run on the server-side, before sending the values to the client-side to be rendered with the renderer. The following renderers are available, as defined in the server-side -[package]#com.vaadin.ui.renderers# package: +[package]#com.vaadin.ui.renderer# package: [classname]#ButtonRenderer#:: Renders the data value as the caption of a button. A [interfacename]#RendererClickListener# can be given to handle the button clicks. @@ -799,25 +789,10 @@ for information on implementing custom renderers. Optionally, you can give a [interfacename]#Converter# in the [methodname]#setRenderer()#, or define it for the column, to convert the data value to an intermediary representation that is rendered by the renderer. For -example, when using an [classname]#ImageRenderer#, you could store the image file name +example, when using an [classname]#ImageRenderer#, you could the image file name in the data column, which the converter would convert to a resource, which would then be rendered by the renderer. -In this example, we use a converter and [classname]#HTMLRenderer# to display boolean -values as FontAwesome icons -[source, java] - ----- -// Have a column for hyperlink paths to Wikipedia -grid.addColumn("truth", Boolean.class); -Grid.Column truth = grid.getColumn("truth"); -truth.setRenderer(new HtmlRenderer(), - new StringToBooleanConverter( - FontAwesome.CHECK_CIRCLE_O.getHtml(), - FontAwesome.CIRCLE_O.getHtml())); -... ----- - In the following example, we use a converter to format URL paths to complete HTML hyperlinks with [classname]#HTMLRenderer#: @@ -904,7 +879,7 @@ Similarly, you can add footer rows with [methodname]#appendFooterRow()#, You can join two or more header or footer cells with the [methodname]#join()# method. For header cells, the intention is usually to create column grouping, -while for footer cells, you typically calculate sums or averages. +while for footer cells, you typically calculate sums or averates. [source, java] @@ -913,13 +888,11 @@ while for footer cells, you typically calculate sums or averages. HeaderRow groupingHeader = grid.prependHeaderRow(); HeaderCell namesCell = groupingHeader.join( groupingHeader.getCell("firstname"), - groupingHeader.getCell("lastname")) - .setText("Person"); + groupingHeader.getCell("lastname")); HeaderCell yearsCell = groupingHeader.join( groupingHeader.getCell("born"), groupingHeader.getCell("died"), - groupingHeader.getCell("lived")) - .setText("Dates of Life"); + groupingHeader.getCell("lived")); ---- @@ -940,7 +913,7 @@ mainHeader.getCell("died").setText("Died In"); mainHeader.getCell("lived").setText("Lived For"); ---- -To use raw HTML in the captions, you can use [methodname]#setHtml()#. +To use raw HTML in the captions, you can use [methodname]#setHTML()#. [source, java] @@ -1068,8 +1041,10 @@ sorting. Grid supports line-based editing, where double-clicking a row opens the row editor. In the editor, the input fields can be edited, as well as navigated with -Tab and ShiftTab keys. If validation fails, an error is displayed and the user -can correct the inputs. +Tab and ShiftTab keys. The editor has a [guibutton]#Save# button that commits +the data item to the container data source and closes the editor. If validation +fails, an error is displayed and the user can correct the inputs. A +[guibutton]#Cancel# button discards the changes and exits the editor. To enable editing, you need to call [methodname]#setEditorEnabled(true)# for the grid. @@ -1081,32 +1056,12 @@ Grid grid = new Grid(GridExample.exampleDataSource()); grid.setEditorEnabled(true); ---- -Grid supports two row editor modes - buffered and unbuffered. Default mode is -buffered. The mode could be changed by [methodname]#setBuffered(false)# - -[[components.grid.editing.buffered]] -=== Buffered Mode - -The editor has a [guibutton]#Save# button that commits -the data item to the container data source and closes the editor. A -[guibutton]#Cancel# button discards the changes and exits the editor. - A row under editing is illustrated in <<figure.components.grid.editing>>. [[figure.components.grid.editing]] .Editing a Grid Row image::img/grid-editor-basic.png[] -[[components.grid.editing.unbuffered]] -=== Unbuffered Mode - -The editor has no buttons and all changed data is provided directly -to the container. If another row is clicked, row editor for current row is closed and -a row editor for the clicked row is opened. - -[[components.grid.editing.fields]] -=== Editor Fields - The editor fields are by default generated with a [interfacename]#FieldFactory# and bound to the container data source with a [classname]#FieldGroup#, which also handles tasks such as validation, as explained later. @@ -1118,7 +1073,7 @@ To disable editing in a particular column, you can call [[components.grid.editing.editorfields]] === Customizing Editor Fields -The editor fields are normally created by the field factory of the editor's field +Te editor fields are normally created by the field factory of the editor's field group, which creates the fields according to the data types of their respective columns. To customize the editor fields of specific properties, such as to style them or to set up validation, you can provide them with @@ -1151,7 +1106,7 @@ ifdef::web[] [[components.grid.editing.captions]] === Customizing Editor Buttons -In buffered mode, the editor has two buttons: [guibutton]#Save# and [guibutton]#Cancel#. You can +The editor has two buttons: [guibutton]#Save# and [guibutton]#Cancel#. You can set their captions with [methodname]#setEditorSaveCaption()# and [methodname]#setEditorCancelCaption()#, respectively. @@ -1232,7 +1187,7 @@ ifdef::web[] [[components.grid.editing.validation]] === Handling Validation Errors -The input fields are validated when the value is updated. The default +The input fields are validated when the save button is clicked. The default error handler displays error indicators in the invalid fields, as well as the first error in the editor. @@ -1253,6 +1208,8 @@ The fields are generated by the [classname]#FieldFactory# of the field group; you can also set it with [methodname]#setEditorFieldFactory()#. Alternatively, you can create the editor fields explicitly with [methodname]#setEditorField()#. + + [[components.grid.scrolling]] == Programmatic Scrolling |