From 93767cf76b2fb14c65b758066c67fc8b48cc2eeb Mon Sep 17 00:00:00 2001
From: Marko Gronroos <magi@vaadin.com>
Date: Fri, 20 May 2016 14:44:42 +0300
Subject: Scaled images for print edition and fixed errors up to the beginning
 of layouts chapter (#19835). Also major revision of Tree, CustomField, and
 layouts overview.

Change-Id: I19f5e9511b83f953ce4707f324d81c2821ebb69d
---
 .../components/components-selection.asciidoc       | 81 +++++++++++++---------
 1 file changed, 50 insertions(+), 31 deletions(-)

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

diff --git a/documentation/components/components-selection.asciidoc b/documentation/components/components-selection.asciidoc
index 4bf7528b9f..0dc65f4f19 100644
--- a/documentation/components/components-selection.asciidoc
+++ b/documentation/components/components-selection.asciidoc
@@ -11,16 +11,27 @@ Vaadin offers many alternative ways for selecting one or more items. The core
 library includes the following selection components, all based on the
 [classname]#AbstractSelect# class:
 
-[classname]#ComboBox# (Section <<dummy/../../../framework/components/components-combobox#components.combobox,"ComboBox">>):: A drop-down list with a text box, where the user can type text to find matching items. The component also provides an input prompt and the user can enter new items.
-[classname]#ListSelect# (Section <<dummy/../../../framework/components/components-listselect#components.listselect,"ListSelect">>):: A vertical list box for selecting items in either single or multiple selection mode.
-[classname]#NativeSelect# (Section<<dummy/../../../framework/components/components-nativeselect#components.nativeselect,"NativeSelect">>):: Provides selection using the native selection component of the browser, typically a drop-down list for single selection and a multi-line list in multiselect mode. This uses the [literal]#++<select>++# element in HTML.
-[classname]#OptionGroup# (Section <<dummy/../../../framework/components/components-optiongroup#components.optiongroup,"OptionGroup">>):: Shows the items as a vertically arranged group of radio buttons in the single selection mode and of check boxes in multiple selection mode.
-[classname]#TwinColSelect# (Section <<dummy/../../../framework/components/components-twincolselect#components.twincolselect,"TwinColSelect">>):: Shows two list boxes side by side where the user can select items from a list of available items and move them to a list of selected items using control buttons.
+// TODO Only use section numbers here, prefixed with "Section", not include section title
 
+[classname]#ComboBox# (<<components-combobox#components.combobox,"ComboBox">>)::
+A drop-down list with a text box, where the user can type text to find matching items.
+The component also provides an input prompt and the user can enter new items.
 
-In addition, the [classname]#Tree#, [classname]#Table#, and
-[classname]#TreeTable# components allow special forms of selection. They also
-inherit the [classname]#AbstractSelect#.
+[classname]#ListSelect# (<<components-listselect#components.listselect,"ListSelect">>)::
+A vertical list box for selecting items in either single or multiple selection mode.
+
+[classname]#NativeSelect# (<<components-nativeselect#components.nativeselect, "NativeSelect">>)::
+Provides selection using the native selection component of the browser, typically a drop-down list for single selection and a multi-line list in multiselect mode.
+This uses the [literal]#++<select>++# element in HTML.
+
+[classname]#OptionGroup# (<<components-optiongroup#components.optiongroup,"OptionGroup">>)::
+Shows the items as a vertically arranged group of radio buttons in the single selection mode and of check boxes in multiple selection mode.
+
+[classname]#TwinColSelect# (<<components-twincolselect#components.twincolselect, "TwinColSelect">>)::
+Shows two list boxes side by side where the user can select items from a list of available items and move them to a list of selected items using control buttons.
+
+In addition, the [classname]#Tree#, [classname]#Table#, and [classname]#TreeTable# components allow special forms of selection.
+They also inherit [classname]#AbstractSelect#.
 
 [[components.selection.databinding]]
 == Binding Selection Components to Data
@@ -153,9 +164,10 @@ identifier.
 ----
 // Create a selection component
 ComboBox select = new ComboBox("Moons of Mars");
-select.setItemCaptionMode(ItemCaptionMode.EXPLICIT_DEFAULTS_ID);
+select.setItemCaptionMode(
+    ItemCaptionMode.EXPLICIT_DEFAULTS_ID);
 
-// Use the item ID also as the caption of this item
+// The given item ID is also used as the caption
 select.addItem(new Integer(1));
 
 // Set item caption for this item explicitly
@@ -173,7 +185,6 @@ ID:: String representation of the item identifier object is used as caption. Thi
 useful when the identifier is a string, and also when the identifier is an
 complex object that has a string representation. For example:
 
-
 +
 [source, java]
 ----
@@ -181,7 +192,8 @@ ComboBox select = new ComboBox("Inner Planets");
 select.setItemCaptionMode(ItemCaptionMode.ID);
 
 // A class that implements toString()
-class PlanetId extends Object implements Serializable {
+class PlanetId extends Object
+               implements Serializable {
     String planetName;
 
     PlanetId (String name) {
@@ -193,16 +205,19 @@ class PlanetId extends Object implements Serializable {
 }
 
 // Use such objects as item identifiers
-String planets[] = {"Mercury", "Venus", "Earth", "Mars"};
+String planets[] = {"Mercury", "Venus",
+                    "Earth", "Mars"};
 for (int i=0; i<planets.length; i++)
     select.addItem(new PlanetId(planets[i]));
 ----
-INDEX:: Index number of item is used as caption. This caption mode is applicable only to
-data sources that implement the [classname]#Container.Indexed# interface. If the
-interface is not available, the component will throw a
-[classname]#ClassCastException#. The [classname]#AbstractSelect# itself does not
-implement this interface, so the mode is not usable without a separate data
-source. An [classname]#IndexedContainer#, for example, would work.
+
+INDEX::
+Index number of item is used as caption.
+This caption mode is applicable only to data sources that implement the [interfacename]#Container.Indexed# interface.
+If the interface is not available, the component will throw a
+[classname]#ClassCastException#.
+The [classname]#AbstractSelect# itself does not implement this interface, so the mode is not usable without a separate data source.
+An [classname]#IndexedContainer#, for example, would work.
 
 ITEM:: [classname]#String# representation of item, acquired with
 [methodname]#toString()#, is used as the caption. This is applicable mainly when
@@ -220,7 +235,6 @@ and you want to use a specific property for caption.
 In the example below, we bind a selection component to a bean container and use
 a property of the bean as the caption.
 
-
 +
 [source, java]
 ----
@@ -237,30 +251,35 @@ public class Planet implements Serializable {
     ... setters and getters ...
 }
 
-public void captionproperty(VerticalLayout layout) {
+public void captionproperty(
+        VerticalLayout layout) {
     // Have a bean container to put the beans in
     BeanItemContainer<Planet> container =
-        new BeanItemContainer<Planet>(Planet.class);
+        new BeanItemContainer<Planet>(
+            Planet.class);
 
     // Put some example data in it
-    container.addItem(new Planet(1, "Mercury"));
+    container.addItem(
+        new Planet(1, "Mercury"));
     container.addItem(new Planet(2, "Venus"));
     container.addItem(new Planet(3, "Earth"));
     container.addItem(new Planet(4, "Mars"));
 
-    // Create a selection component bound to the container
-    ComboBox select = new ComboBox("Planets", container);
+    // Create a selection component bound
+    // to the container
+    ComboBox select = new ComboBox("Planets",
+                                   container);
 
-    // Set the caption mode to read the caption directly
-    // from the 'name' property of the bean
-    select.setItemCaptionMode(ItemCaptionMode.PROPERTY);
+    // Set the caption mode to read the
+    // caption directly from the 'name'
+    // property of the bean
+    select.setItemCaptionMode(
+        ItemCaptionMode.PROPERTY);
     select.setItemCaptionPropertyId("name");
 
     ...
 ----
 
-
-
 [[components.selection.getset]]
 == Getting and Setting Selection
 
@@ -311,7 +330,7 @@ The result of user interaction is shown in
 
 [[figure.components.selection.valuechange]]
 .Selected Item
-image::img/select-selected1.png[]
+image::img/select-selected1.png[width=30%, scaledwidth=40%]
 
 
 [[components.selection.newitems]]
-- 
cgit v1.2.3

