Update layout chapter of the documentation for version 8 (#8154)

The SplitPanel chapter still uses a Tree in its example.

13 files changed, 48 insertions, 115 deletions

diff --git a/documentation/layout/img/tabsheet-example2.png b/documentation/layout/img/tabsheet-example2.png
deleted file mode 100644
index 9819a637ae..0000000000
--- a/documentation/layout/img/tabsheet-example2.png
+++ /dev/null
diff --git a/documentation/layout/layout-accordion.asciidoc b/documentation/layout/layout-accordion.asciidoc
index 001c1f677e..b84ccf4100 100644
--- a/documentation/layout/layout-accordion.asciidoc
+++ b/documentation/layout/layout-accordion.asciidoc
@@ -48,7 +48,7 @@ String[] tabs = {"Earth", "Mars", "Jupiter", "Saturn"};
 for (String caption: tabs) {
     String basename = "img/planets/" + caption;
     VerticalLayout tab = new VerticalLayout();
-    tab.addComponent(new Embedded(null,
+    tab.addComponent(new Image(null,
             new ThemeResource(basename + ".jpg")));
     accordion.addTab(tab, caption,
             new ThemeResource(basename + "_symbol.png"));
diff --git a/documentation/layout/layout-csslayout.asciidoc b/documentation/layout/layout-csslayout.asciidoc
index d77f93b19d..8be6fbeea3 100644
--- a/documentation/layout/layout-csslayout.asciidoc
+++ b/documentation/layout/layout-csslayout.asciidoc
@@ -115,12 +115,11 @@ image::img/csslayout-getcss.png[width=60%, scaledwidth=100%]
 [[layout.csslayout.compatibility]]
 == Browser Compatibility
 
-The stregth of the [classname]#CssLayout# is also its weakness. Much of the
-logic behind the other layout components is there to give nice default behaviour
-and to handle the differences in different browsers. Some browsers, no need to
-say which, are notoriously incompatible with the CSS standards, so they require
-a lot of custom CSS. You may need to make use of the browser-specific style
-classes in the root element of the application.
+The strength of the [classname]#CssLayout# is also its weakness. Much of the
+logic behind the other layout components is there to give nice default behavior
+and to handle the differences in different browsers. With [classname]#CssLayout#,
+you may need to make use of the browser-specific style classes in the root
+element of the application to write browser specific CSS rules.
 // TODO: ... described in <<advanced.browserinfo>>
 Some features in the other layouts are not even solvable in pure CSS, at least
 in all browsers.
diff --git a/documentation/layout/layout-customlayout.asciidoc b/documentation/layout/layout-customlayout.asciidoc
index f94d3be3ae..d10d6309fc 100644
--- a/documentation/layout/layout-customlayout.asciidoc
+++ b/documentation/layout/layout-customlayout.asciidoc
@@ -21,9 +21,9 @@ designed separately from code, for example using WYSIWYG web designer tools such
 as Adobe Dreamweaver.
 
 A template is a HTML file located under [filename]#layouts# folder under a theme
-folder under the [filename]#WebContent/VAADIN/themes/# folder, for example,
-[filename]#WebContent/VAADIN/themes/__themename/layouts/mylayout.html__#.
-(Notice that the root path [filename]#WebContent/VAADIN/themes/# for themes is
+folder under the [filename]#/VAADIN/themes/# folder, for example,
+[filename]#/VAADIN/themes/__themename/layouts/mylayout.html__#.
+(Notice that the root path [filename]#/VAADIN/themes/# for themes is
 fixed.) A template can also be provided dynamically from an
 [classname]#InputStream#, as explained below. A template includes
 [literal]#++<div>++# elements with a [parameter]#location# attribute that
diff --git a/documentation/layout/layout-formlayout.asciidoc b/documentation/layout/layout-formlayout.asciidoc
index c5e7360224..a74e69e64b 100644
--- a/documentation/layout/layout-formlayout.asciidoc
+++ b/documentation/layout/layout-formlayout.asciidoc
@@ -28,8 +28,7 @@ The following example shows typical use of [classname]#FormLayout# in a form:
 FormLayout form = new FormLayout();
 TextField tf1 = new TextField("Name");
 tf1.setIcon(FontAwesome.USER);
-tf1.setRequired(true);
-tf1.addValidator(new NullValidator("Must be given", false));
+tf1.setRequiredIndicatorVisible(true);
 form.addComponent(tf1);
 
 TextField tf2 = new TextField("Street address");
@@ -38,11 +37,12 @@ form.addComponent(tf2);
 
 TextField tf3 = new TextField("Postal code");
 tf3.setIcon(FontAwesome.ENVELOPE);
-tf3.addValidator(new IntegerRangeValidator("Doh!", 1, 99999));
 form.addComponent(tf3);
+// normally comes from validation by Binder
+tf3.setComponentError(new UserError("Doh!"));
 ----
 
-The resulting layout will look as follows. The error message shows in a tooptip
+The resulting layout will look as follows. The error message shows in a tooltip
 when you hover the mouse pointer over the error indicator.
 
 [[figure.layout.formlayout]]
diff --git a/documentation/layout/layout-gridlayout.asciidoc b/documentation/layout/layout-gridlayout.asciidoc
index c2db30c6c7..fbd45fad98 100644
--- a/documentation/layout/layout-gridlayout.asciidoc
+++ b/documentation/layout/layout-gridlayout.asciidoc
@@ -107,7 +107,6 @@ expanding rows/columns.
 [source, java]
 ----
 GridLayout grid = new GridLayout(3,2);
-ifdef::web[]
 // Layout containing relatively sized components must have
 // a defined size, here is fixed size.
 grid.setWidth("600px");
@@ -127,7 +126,6 @@ for (int i=0; i<labels.length; i++) {
     label.setWidth(null); // Set width as undefined
     grid.addComponent(label);
 }
-endif::web[]
 // Set different expansion ratios for the two columns
 grid.setColumnExpandRatio(1, 1);
 grid.setColumnExpandRatio(2, 5);
@@ -135,7 +133,6 @@ grid.setColumnExpandRatio(2, 5);
 // Set the bottom row to expand
 grid.setRowExpandRatio(1, 1);
 
-ifdef::web[]
 // Align and size the labels.
 for (int col=0; col<grid.getColumns(); col++) {
     for (int row=0; row<grid.getRows(); row++) {
@@ -148,7 +145,6 @@ for (int col=0; col<grid.getColumns(); col++) {
             c.setHeight("100%");
     }
 }
-endif::web[]
 ----
 
 [[figure.ui.gridlayout.sizing.expanding]]
diff --git a/documentation/layout/layout-orderedlayout.asciidoc b/documentation/layout/layout-orderedlayout.asciidoc
index 5fd70aeded..593bb5ef45 100644
--- a/documentation/layout/layout-orderedlayout.asciidoc
+++ b/documentation/layout/layout-orderedlayout.asciidoc
@@ -28,7 +28,6 @@ vertical.addComponent(new TextField("Street address"));
 vertical.addComponent(new TextField("Postal code"));
 layout.addComponent(vertical);
 ----
-See the http://demo.vaadin.com/book-examples-vaadin7/book#layout.orderedlayout.basic[on-line example, window="_blank"].
 
 In [classname]#VerticalLayout#, the captions of child components are placed above each component, so the layout would look as follows:
 
@@ -38,7 +37,6 @@ image::img/orderedlayout_vertical.png[width=30%, scaledwidth=65%]
 
 image::img/orderedlayout_horizontal.png[width=80%, scaledwidth=100%]
 
-ifdef::web[]
 [[layout.orderedlayout.declarative]]
 == Declarative Format
 
@@ -46,9 +44,9 @@ Ordered layouts have the following declarative elements:
 
 |===============
 |Component|Element Name
-|[classname]#VerticalLayout#|[elementname]#v-verticallayout#
-|[classname]#HorizontalLayout#|[elementname]#v-horizontallayout#
-|[classname]#FormLayout#|[elementname]#v-formlayout#
+|[classname]#VerticalLayout#|[elementname]#v-vertical-layout#
+|[classname]#HorizontalLayout#|[elementname]#v-horizontal-layout#
+|[classname]#FormLayout#|[elementname]#v-form-layout#
 |===============
 
 The have the following declarative attributes:
@@ -92,16 +90,15 @@ For example:
   </v-horizontal-layout>
 </v-vertical-layout>
 ----
-endif::web[]
 
 [[layout.orderedlayout.spacing]]
 == Spacing in Ordered Layouts
 
 The ordered layouts can have spacing between the horizontal or vertical cells.
-The spacing can be enabled with [methodname]#setSpacing(true)# or declaratively
-with the [literal]#++spacing++# attribute.
+Spacing is enabled by default, and can be disabled with [methodname]#setSpacing(false)# or declaratively
+with the [literal]#++spacing="false"++# attribute.
 
-The spacing as a default height or width, which can be customized in CSS. You
+The spacing has a default height or width, which can be customized in CSS. You
 need to set the height or width for spacing elements with
 [literal]#++v-spacing++# style. You also need to specify an enclosing rule
 element in a CSS selector, such as [literal]#++v-verticallayout++# for a
@@ -140,21 +137,23 @@ direction of the layout component.
 image::img/horizontallayout_sizing.png[width=75%, scaledwidth=100%]
 
 <<figure.layout.orderedlayout.size.summary>> gives a summary of the sizing
-options for a [classname]#HorizontalLayout#. The figure is broken down in the
-following subsections.
+options for a [classname]#HorizontalLayout# with spacing disabled.
+The figure is broken down in the following subsections.
 
 [[layout.orderedlayout.sizing.undefined]]
 === Layout with Undefined Size
 
 If a [classname]#VerticalLayout# has undefined height or
 [classname]#HorizontalLayout# undefined width, the layout will shrink to fit the
-contained components so that there is no extra space between them.
+contained components so that there is no extra space between them (apart from
+optional spacing).
 
 
 [source, java]
 ----
 HorizontalLayout fittingLayout = new HorizontalLayout();
 fittingLayout.setWidth(Sizeable.SIZE_UNDEFINED, 0); // Default
+fittingLayout.setSpacing(false); // Compact layout
 fittingLayout.addComponent(new Button("Small"));
 fittingLayout.addComponent(new Button("Medium-sized"));
 fittingLayout.addComponent(new Button("Quite a big component"));
@@ -191,7 +190,6 @@ with fixed (or undefined) size in a sense defines the size of the containing
 layout, removing the paradox. That size is then used for the relatively sized
 components.
 
-ifdef::web[]
 The technique can be used to define the width of a [classname]#VerticalLayout#
 or the height of a [classname]#HorizontalLayout#.
 
@@ -218,13 +216,11 @@ Button butt = new Button("\u2190 This Button takes 100% "+
 butt.setWidth("100%");
 vertical.addComponent(butt);
 ----
-See the http://demo.vaadin.com/book-examples-vaadin7/book#layout.orderedlayout.sizing.sizing-undefined-defining[on-line example, window="_blank"].
 
 [[figure.layout.orderedlayout.sizing.undefined.defining]]
 .Defining the Size with a Component
 image::img/orderedlayout-sizing-undefined.png[width=50%, scaledwidth=75%]
 
-endif::web[]
 
 [[layout.orderedlayout.defined-size]]
 === Layout with Defined Size
@@ -241,11 +237,6 @@ their alignment setting, top left by default, as in the example below.
 fixedLayout.setWidth("400px");
 ----
 
-Using percentual sizes for components contained in a layout requires answering
-the question, "Percentage of what?" There is no sensible default answer for this
-question in the current implementation of the layouts, so in practice, you may
-not define "100%" size alone.
-
 [[layout.orderedlayout.expanding]]
 === Expanding Components
 
diff --git a/documentation/layout/layout-overview.asciidoc b/documentation/layout/layout-overview.asciidoc
index 7a57e2a518..a88d9ad443 100644
--- a/documentation/layout/layout-overview.asciidoc
+++ b/documentation/layout/layout-overview.asciidoc
@@ -56,7 +56,7 @@ Or in the declarative format (roughly):
   <vaadin-label>The Ultimate Cat Finder</vaadin-label>
 
   <vaadin-horizontal-layout>
-    <vaadin-tree caption="Possible Places"/>
+    <vaadin-radio-button-group caption="Possible Places"/>
     <vaadin-panel/>
     ...
   </vaadin-horizontal-layout>
diff --git a/documentation/layout/layout-panel.asciidoc b/documentation/layout/layout-panel.asciidoc
index 6ee283099a..72621a578c 100644
--- a/documentation/layout/layout-panel.asciidoc
+++ b/documentation/layout/layout-panel.asciidoc
@@ -110,7 +110,6 @@ not update the scroll position to the server-side.
 (((range="endofrange", startref="term.layout.panel.scrolling.scrollbars")))
 
 
-ifdef::web[]
 [[layout.panel.css]]
 == CSS Style Rules
 
@@ -130,10 +129,7 @@ styled with [literal]#++v-panel-caption++#, [literal]#++v-panel-content++#, and
 [literal]#++v-panel-deco++#, respectively. If the panel has no caption, the
 caption element will have the style [literal]#++v-panel-nocaption++#.
 
-The built-in [literal]#++light++# style in the Reindeer and Runo themes has no
+The built-in [literal]#++borderless++# style in the Valo theme has no
 borders or border decorations for the [classname]#Panel#. You can use the
-[parameter]#Reindeer.PANEL_LIGHT# and [parameter]#Runo.PANEL_LIGHT# constants to
-add the style to a panel. Other themes may also provide the light and other
-styles for [classname]#Panel# as well.
-
-endif::web[]
+[parameter]#ValoTheme.PANEL_BORDERLESS# constant to
+add the style to a panel.
\ No newline at end of file
diff --git a/documentation/layout/layout-settings.asciidoc b/documentation/layout/layout-settings.asciidoc
index 682cf93563..da18da92fb 100644
--- a/documentation/layout/layout-settings.asciidoc
+++ b/documentation/layout/layout-settings.asciidoc
@@ -118,7 +118,7 @@ example below, the buttons have 1:2:3 ratio for the expansion.
 [classname]#GridLayout# has corresponding method for both of its directions,
 [methodname]#setRowExpandRatio()# and [methodname]#setColumnExpandRatio()#.
 
-Expansion is dealt in detail in the documentation of the layout components that
+Expansion is covered in detail in the documentation of the layout components that
 support it. See
 <<dummy/../../../framework/layout/layout-orderedlayout#layout.orderedlayout,"VerticalLayout
 and HorizontalLayout">> and
@@ -251,36 +251,19 @@ alignment, which you can also get as a bitmask value.
 === Size of Aligned Components
 
 You can only align a component that is smaller than its containing cell in the
-direction of alignment. If a component has 100% width, as many components have
+direction of alignment. If a component has 100% width, as some components have
 by default, horizontal alignment does not have any effect. For example,
-[classname]#Label# is 100% wide by default and can not therefore be horizontally
-aligned as such. The problem can be hard to notice, as the text inside a
-[classname]#Label# is left-aligned.
+[classname]#VerticalLayout# is 100% wide by default and can not therefore be horizontally
+aligned as such. The problem can sometimes be hard to notice, as the content inside a
+[classname]#VerticalLayout# is left-aligned by default.
 
 You usually need to set either a fixed size, undefined size, or less than a 100%
 relative size for the component to be aligned - a size that is smaller than the
 containing layout has.
 
-For example, assuming that a [classname]#Label# has short content that is less
-wide than the containing [classname]#VerticalLayout#, you could center it as
-follows:
-
-
-[source, java]
-----
-VerticalLayout layout = new VerticalLayout(); // 100% default width
-Label label = new Label("Hello"); // 100% default width
-label.setSizeUndefined();
-layout.addComponent(label);
-layout.setComponentAlignment(label, Alignment.MIDDLE_CENTER);
-----
-
 If you set the size as undefined and the component itself contains components,
 make sure that the contained components also have either undefined or fixed
-size. For example, if you set the size of a [classname]#Form# as undefined, its
-containing layout [classname]#FormLayout# has 100% default width, which you also
-need to set as undefined. But then, any components inside the
-[classname]#FormLayout# must have either undefined or fixed size.
+size.
 
 
 (((range="endofrange", startref="term.alignment")))
@@ -291,7 +274,7 @@ need to set as undefined. But then, any components inside the
 
 The [classname]#VerticalLayout#, [classname]#HorizontalLayout#, and
 [classname]#GridLayout# layouts offer a [methodname]#setSpacing()# method to
-enable spacing between the cells of the layout.
+enable or disable spacing between the cells of the layout.
 
 For example:
 
@@ -299,7 +282,7 @@ For example:
 [source, java]
 ----
 VerticalLayout layout = new VerticalLayout();
-layout.setSpacing(true);
+layout.setSpacing(false);
 layout.addComponent(new Button("Component 1"));
 layout.addComponent(new Button("Component 2"));
 layout.addComponent(new Button("Component 3"));
@@ -330,9 +313,10 @@ handling. Please see the sections on the individual components for more details.
 [[layout.settings.margins]]
 == Layout Margins
 
-Most layout components do not have any margin around them by default. The
-ordered layouts, as well as [classname]#GridLayout#, support enabling a margin
-with [methodname]#setMargin()#. This enables CSS classes for each margin in the
+Most layout components (with the exception of [classname]#VerticalLayout#) do
+not have any margin around them by default. The ordered layouts, as well as
+[classname]#GridLayout#, support enabling or disabling a margin with
+[methodname]#setMargin()#. This enables CSS classes for each margin in the
 HTML element of the layout component.
 
 In the Valo theme, the margin sizes default to $v-unit-size. You can customize
diff --git a/documentation/layout/layout-splitpanel.asciidoc b/documentation/layout/layout-splitpanel.asciidoc
index b8b225b8ac..9d16392e82 100644
--- a/documentation/layout/layout-splitpanel.asciidoc
+++ b/documentation/layout/layout-splitpanel.asciidoc
@@ -27,6 +27,7 @@ You can set the two components with the [methodname]#setFirstComponent()# and
 [methodname]#setSecondComponent()# methods, or with the regular
 [methodname]#addComponent()# method.
 
+// TODO replace Tree with something else in the example code and screenshot
 
 [source, java]
 ----
@@ -49,7 +50,6 @@ hsplit.setSecondComponent(vsplit);
 vsplit.addComponent(new Label("Here's the upper panel"));
 vsplit.addComponent(new Label("Here's the lower panel"));
 ----
-See the http://demo.vaadin.com/book-examples-vaadin7/book#layout.splitpanel.basic[on-line example, window="_blank"].
 
 The result is shown in <<figure.splitpanel.basic>>. Observe that the tree is cut
 horizontally as it can not fit in the layout. If its height exceeds the height
@@ -76,7 +76,6 @@ hsplit.setSecondComponent(new Label("25% wide panel"));
 // Set the position of the splitter as percentage
 hsplit.setSplitPosition(75, Sizeable.UNITS_PERCENTAGE);
 ----
-See the http://demo.vaadin.com/book-examples-vaadin7/book#layout.splitpanel.splitposition[on-line example, window="_blank"].
 
 Another version of the [methodname]#setSplitPosition()# method allows leaving
 out the unit, using the same unit as previously. The method also has versions
@@ -93,7 +92,6 @@ locked, the move handle in the middle of the bar is disabled.
 // Lock the splitter
 hsplit.setLocked(true);
 ----
-See the http://demo.vaadin.com/book-examples-vaadin7/book#layout.splitpanel.splitposition[on-line example, window="_blank"].
 
 Setting the split position programmatically and locking the split bar is
 illustrated in <<figure.component.splitpanel.splitposition>>.
diff --git a/documentation/layout/layout-sub-window.asciidoc b/documentation/layout/layout-sub-window.asciidoc
index ed75b800aa..9d10876efc 100644
--- a/documentation/layout/layout-sub-window.asciidoc
+++ b/documentation/layout/layout-sub-window.asciidoc
@@ -46,7 +46,6 @@ public static class SubWindowUI extends UI {
         // Create a sub-window and set the content
         Window subWindow = new Window("Sub-window");
         VerticalLayout subContent = new VerticalLayout();
-        subContent.setMargin(true);
         subWindow.setContent(subContent);
 
         // Put some components in it
@@ -78,7 +77,6 @@ You close a sub-window also programmatically by calling the
 [guibutton]#OK# or [guibutton]#Cancel# button. You can also call
 [methodname]#removeWindow()# for the current [classname]#UI#.
 
-ifdef::web[]
 [[layout.sub-window.openclose.example]]
 === Sub-Window Management
 
@@ -94,23 +92,10 @@ class MySub extends Window {
         super("Subs on Sale"); // Set window caption
         center();
 
-        // Some basic content for the window
-        VerticalLayout content = new VerticalLayout();
-        content.addComponent(new Label("Just say it's OK!"));
-        content.setMargin(true);
-        setContent(content);
-
         // Disable the close button
         setClosable(false);
 
-        // Trivial logic for closing the sub-window
-        Button ok = new Button("OK");
-        ok.addClickListener(new ClickListener() {
-            public void buttonClick(ClickEvent event) {
-                close(); // Close the sub-window
-            }
-        });
-        content.addComponent(ok);
+        setContent(new Button("Close me", event -> close()));
     }
 }
 ----
@@ -122,18 +107,14 @@ You could open the window as follows:
 ----
 // Some UI logic to open the sub-window
 final Button open = new Button("Open Sub-Window");
-open.addClickListener(new ClickListener() {
-    public void buttonClick(ClickEvent event) {
-        MySub sub = new MySub();
+open.addClickListener(event -> {
+    MySub sub = new MySub();
 
-        // Add it to the root component
-        UI.getCurrent().addWindow(sub);
-    }
+    // Add it to the root component
+    UI.getCurrent().addWindow(sub);
 });
 ----
 
-endif::web[]
-
 
 [[layout.sub-window.position]]
 == Window Positioning
diff --git a/documentation/layout/layout-tabsheet.asciidoc b/documentation/layout/layout-tabsheet.asciidoc
index 301d2ed28b..30d12d6172 100644
--- a/documentation/layout/layout-tabsheet.asciidoc
+++ b/documentation/layout/layout-tabsheet.asciidoc
@@ -45,14 +45,14 @@ layout.addComponent(tabsheet);
 
 // Create the first tab
 VerticalLayout tab1 = new VerticalLayout();
-tab1.addComponent(new Embedded(null,
+tab1.addComponent(new Image(null,
         new ThemeResource("img/planets/Mercury.jpg")));
 tabsheet.addTab(tab1, "Mercury",
         new ThemeResource("img/planets/Mercury_symbol.png"));
 
 // This tab gets its caption from the component caption
 VerticalLayout tab2 = new VerticalLayout();
-tab2.addComponent(new Embedded(null,
+tab2.addComponent(new Image(null,
         new ThemeResource("img/planets/Venus.jpg")));
 tab2.setCaption("Venus");
 tabsheet.addTab(tab2).setIcon(
@@ -92,12 +92,6 @@ A tab can be made invisible by setting [methodname]#setVisible(false)# for the
 tab bar entirely. This can be useful in tabbed document interfaces (TDI) when
 there is only one tab.
 
-ifdef::web[]
-[[figure.tabsheet.example2]]
-.A TabSheet with Hidden and Disabled Tabs
-image::img/tabsheet-example2.png[width=50%, scaledwidth=70%]
-endif::web[]
-
 
 [[layout.tabsheet.events]]
 == Tab Change Events
@@ -116,7 +110,6 @@ Notice that when the first tab is added, it is selected and the change event is
 fired, so if you want to catch that, you need to add your listener before adding
 any tabs.
 
-ifdef::web[]
 [[layout.tabsheet.events.dynamic]]
 === Creating Tab Content Dynamically
 
@@ -155,8 +148,6 @@ for (String caption: tabs)
         new ThemeResource("img/planets/"+caption+"_symbol.png"));
 ----
 
-endif::web[]
-
 
 [[layout.tabsheet.closing]]
 == Enabling and Handling Closing Tabs
@@ -202,7 +193,6 @@ tabsheet.setCloseHandler(new CloseHandler() {
 
 
 
-ifdef::web[]
 [[layout.tabsheet.css]]
 == CSS Style Rules
 
@@ -247,5 +237,3 @@ buttons enable browsing the full tab list. These use the styles
 The content area where the tab contents are shown can be styled with
 [literal]#++v-tabsheet-content++#, and the surrounding decoration with
 [literal]#++v-tabsheet-deco++#.
-
-endif::web[]