From a20e5be94fc13058a61ff27c1398052828c00d7b Mon Sep 17 00:00:00 2001
From: elmot <elmot@vaadin.com>
Date: Fri, 27 Nov 2015 18:26:21 +0200
Subject: BoV 7.6 update - Grid (#19317)

Change-Id: I7bd41d656a5ed39e24beea4111d9a48de4ef37b5
---
 documentation/components/components-grid.asciidoc | 97 ++++++++++++++++-------
 1 file changed, 70 insertions(+), 27 deletions(-)

(limited to 'documentation/components/components-grid.asciidoc')

diff --git a/documentation/components/components-grid.asciidoc b/documentation/components/components-grid.asciidoc
index a323dc28bb..c5510a3f80 100644
--- a/documentation/components/components-grid.asciidoc
+++ b/documentation/components/components-grid.asciidoc
@@ -60,9 +60,7 @@ 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.
-* 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.
+* Limited support for drag and drop: the user can drag columns to reorder them.
 
 In addition, Grid has the following visual changes:
 
@@ -86,7 +84,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]#BeanItemContainer#, and bind to a [classname]#Grid# as follows
+[classname]#BeanContainer# or [classname]#BeanItemContainer#, and bind to a [classname]#Grid# as follows
 
 
 [source, java]
@@ -107,6 +105,9 @@ 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
 
@@ -177,8 +178,8 @@ A [classname]#Grid# can be set to be in [literal]#++SINGLE++# (default),
 grid.setSelectionMode(SelectionMode.SINGLE);
 ----
 
-Empty (null) selection is allowed in multi-selection mode, but not in single
-selection.
+Empty (null) selection is allowed by default, but can be disabled
+with [methodname]#setDeselectAllowed# in single-selection mode.
 
 The selection is handled with a different selection model object in each
 respective selection mode: [classname]#SingleSelectionModel#,
@@ -252,7 +253,8 @@ 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.
+the checkboxes in the leftmost column, or by using the spacebar to select/deselect the currently focused row.
+(space key is a customizable default).
 
 [[figure.components.grid.selection.multi]]
 .Multiple Selection in  [classname]#Grid#
@@ -301,9 +303,8 @@ 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]#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.
+[methodname]#getAdded()# and [methodname]#getRemoved()# to allow determining the
+differences in the selection change.
 
 
 [source, java]
@@ -327,7 +328,13 @@ 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. Pressing Tab or ShiftTab moves the focus to another component, as usual.
+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.
 
 With mouse, you can focus a cell by clicking on it. The clicks can be handled
 with an [interfacename]#ItemClickListener#. The [classname]#ItemClickEvent#
@@ -394,7 +401,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]#removeAllColumn()#. The removed columns
+can remove all columns with [methodname]#removeAllColumns()#. 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()#
@@ -442,6 +449,9 @@ 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
@@ -513,7 +523,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.renderer# package:
+[package]#com.vaadin.ui.renderers# package:
 
 [classname]#ButtonRenderer#:: Renders the data value as the caption of a button. A
 [interfacename]#RendererClickListener# can be given to handle the button clicks.
@@ -789,10 +799,25 @@ 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 the image file name
+example, when using an [classname]#ImageRenderer#, you could store 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#:
 
@@ -879,7 +904,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 averates.
+while for footer cells, you typically calculate sums or averages.
 
 
 [source, java]
@@ -888,11 +913,13 @@ while for footer cells, you typically calculate sums or averates.
 HeaderRow groupingHeader = grid.prependHeaderRow();
 HeaderCell namesCell = groupingHeader.join(
     groupingHeader.getCell("firstname"),
-    groupingHeader.getCell("lastname"));
+    groupingHeader.getCell("lastname"))
+        .setText("Person");
 HeaderCell yearsCell = groupingHeader.join(
     groupingHeader.getCell("born"),
     groupingHeader.getCell("died"),
-    groupingHeader.getCell("lived"));
+    groupingHeader.getCell("lived"))
+        .setText("Dates of Life");
 ----
 
 
@@ -913,7 +940,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]
@@ -1041,10 +1068,8 @@ 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. 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.
+Tab and ShiftTab keys. If validation fails, an error is displayed and the user
+can correct the inputs.
 
 To enable editing, you need to call [methodname]#setEditorEnabled(true)# for the
 grid.
@@ -1056,12 +1081,32 @@ 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.
@@ -1073,7 +1118,7 @@ To disable editing in a particular column, you can call
 [[components.grid.editing.editorfields]]
 === Customizing Editor Fields
 
-Te editor fields are normally created by the field factory of the editor's field
+The 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
@@ -1106,7 +1151,7 @@ ifdef::web[]
 [[components.grid.editing.captions]]
 === Customizing Editor Buttons
 
-The editor has two buttons: [guibutton]#Save# and [guibutton]#Cancel#. You can
+In buffered mode, the editor has two buttons: [guibutton]#Save# and [guibutton]#Cancel#. You can
 set their captions with [methodname]#setEditorSaveCaption()# and
 [methodname]#setEditorCancelCaption()#, respectively.
 
@@ -1187,7 +1232,7 @@ ifdef::web[]
 [[components.grid.editing.validation]]
 === Handling Validation Errors
 
-The input fields are validated when the save button is clicked. The default
+The input fields are validated when the value is updated. The default
 error handler displays error indicators in the invalid fields, as well as the
 first error in the editor.
 
@@ -1208,8 +1253,6 @@ 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
 
-- 
cgit v1.2.3

