anchor.diff:  [[components.selection.databinding]]
   == Binding Selection Components to Data
   
  -The selection components are strongly coupled with the Vaadin Data Model,
  -described in
  +The selection components typically bound to list of items obtained from backend system.
  +You can give the the list of items in the constructor or set it set
  +[methodname]#setItems()#. Read more in
   <<dummy/../../../framework/datamodel/datamodel-overview.asciidoc#datamodel.overview,"Binding
  -Components to Data">>. The selectable items in all selection components are
  -objects that implement the [classname]#Item# interface. The items are contained
  -in a [classname]#Container#.
  -
  -All selection components are containers themselves and simply forward all
  -container operations to the underlying container data source. You can give the
  -container in the constructor or set it set
  -[methodname]#setContainerDataSource()#. This is further described in
  -<<dummy/../../../framework/datamodel/datamodel-container#datamodel.container.intro,"Basic
  -Use of Containers">>.
  -
  -
  -[source, java]
  -----
  -// Have a container data source of some kind
  -IndexedContainer container = new IndexedContainer();
  -container.addContainerProperty("name", String.class, null);
  -...
  -
  -// Create a selection component bound to the container
  -OptionGroup group = new OptionGroup("My Select", container);
  -----
  -
  -If you do not bind a selection component to a container data source, a default
  -container is used. It is usually either an [classname]#IndexedContainer# or a
  -[classname]#HierarchicalContainer#.
  -
  -The current selection of a selection component is bound to the
  -[classname]#Property# interface, so you can get the current selection as the
  -value of the selection component. Also selection changes are handled as value
  -change events, as is described later.
  -
  +Components to Data">>.
  +
  +You can get the current selection as the
  +value of the selection component using [methodname]#getSelected# defined in
  +[interfacename]#Select# interface. Also selection changes are handled as
  +selection change events, as is described later.
   
   [[components.selection.adding]]
   == Adding New Items
   
  -New items are added with the [methodname]#addItem()# method defined in the
  -[classname]#Container# interface, described in
  -<<dummy/../../../framework/datamodel/datamodel-container#datamodel.container.intro,"Basic
  -Use of Containers">>.
  -
  +New items are added with the [methodname]#addItems()# method.
   
   [source, java]
   ----
   // Create a selection component
  -ComboBox select = new ComboBox("My ComboBox");
  -
  -// Add items with given item IDs
  -select.addItem("Mercury");
  -select.addItem("Venus");
  -select.addItem("Earth");
  -----
  -
  -The [methodname]#addItem()# method creates an empty [classname]#Item#, which is
  -identified by its __item identifier__ (IID) object, given as the parameter. This
  -item ID is by default used also as the caption of the item, as described in more
  -detail later.
  -
  -We emphasize that [methodname]#addItem()# is a factory method that __takes an
  -item ID, not the actual item__ as the parameter - the item is returned by the
  -method. The item is of a type that is specific to the container and has itself
  -little relevance for most selection components, as the properties of an item may
  -not be used in any way (except in [classname]#Table#), only the item ID.
  -
  -The item identifier is typically a string, in which case it can be used as the
  -caption, but can be any object type. We could as well have given integers for
  -the item identifiers and set the captions explicitly with
  -[methodname]#setItemCaption()#. You could also add an item with the
  -parameterless [methodname]#addItem()#, which returns an automatically generated
  -item ID.
  -
  -
  -[source, java]
  -----
  -// Create a selection component
  -ComboBox select = new ComboBox("My Select");
  -
  -// Add an item with a generated ID
  -Object itemId = select.addItem();
  -select.setItemCaption(itemId, "The Sun");
  -
  -// Select the item
  -select.setValue(itemId);
  -----
  -
  -Some container types may support passing the actual data object to the add
  -method. For example, you can add items to a [classname]#BeanItemContainer# with
  -[methodname]#addBean()#. Such implementations can use a separate item ID object,
  -or the data object itself as the item ID, as is done in [methodname]#addBean()#.
  -In the latter case you can not depend on the default way of acquiring the item
  -caption; see the description of the different caption modes later.
  -
  -The next section describes the different options for determining the item
  -captions.
  -
  +ComboBox<String> select = new ComboBox<>("Select a planet");
  +
  +// Add items to select
  +select.setItems("Mercury","Venus","Earth");
  +----
   
   [[components.selection.captions]]
   == Item Captions
   
  -The displayed captions of items in a selection component can be set explicitly
  -with [methodname]#setItemCaption()# or determined from the item IDs or item
  -properties. The caption determination is defined with the __caption mode__, any
  -of the modes in the [classname]#AbstractSelect.ItemCaptionMode# enum, which you
  -can set with [methodname]#setItemCaptionMode()#. The default mode is
  -[parameter]#EXPLICIT_DEFAULTS_ID#, which uses the item identifiers for the
  -captions, unless given explicitly.
  +The items are typically a strings, in which case they can be used as the
  +caption, but can be any object type. We could as well have given Planet instances
  +for the items and use captions generated based on them
  +[methodname]#setItemCaptionProvider()# method.
  +
  +
  +[source, java]
  +----
  +// List of Planet objects
  +List<Planet> planets = new ArrayList<>();
  +planets.add(new Planet("Mercury"));
  +planets.add(new Planet("Venus"));
  +planets.add(new Planet("Earth"));
  +
  +// Create a selection component
  +ComboBox<Planet> select = new ComboBox<>("My Select");
  +
  +// Add an items to the ComboBox
  +select.setItems(planets);
  +
  +select.setItemCaptionProvider(planet -> planet.getName());
  +// or even select.setItemCaptionProvider(Planet::getName);
  +
  +// Select the first
  +select.select(planets.get(0));
  +----
   
   In addition to a caption, an item can have an icon. The icon is set with
  -[methodname]#setItemIcon()#.
  -
  -The caption modes defined in [classname]#ItemCaptionMode# are the following:
  -
  -EXPLICIT_DEFAULTS_ID:: This is the default caption mode and its flexibility allows using it in most
  -cases. By default, the item identifier will be used as the caption. The
  -identifier object does not necessarily have to be a string; the caption is
  -retrieved with [methodname]#toString()# method. If the caption is specified
  -explicitly with [methodname]#setItemCaption()#, it overrides the item
  -identifier.
  -
  +[methodname]#setItemIconProvider()#.
  +
  +Typical use cases for captions are:
  +
  +Using the items as the caption: the caption is
  +retrieved with [methodname]#toString()# method from the item. This is useful
  +for simple objects like String or Integers, but also for objects that have
  +human readable output for [methodname]#toString()# .
   
   +
   [source, java]
   ----
  -// Create a selection component
  -ComboBox select = new ComboBox("Moons of Mars");
  -select.setItemCaptionMode(
  -    ItemCaptionMode.EXPLICIT_DEFAULTS_ID);
  -
  -// The given item ID is also used as the caption
  -select.addItem(new Integer(1));
  -
  -// Set item caption for this item explicitly
  -select.addItem(2); // same as "new Integer(2)"
  -select.setItemCaption(2, "Deimos");
  -----
  -EXPLICIT:: Captions must be explicitly specified with [methodname]#setItemCaption()#. If
  -they are not, the caption will be empty. Such items with empty captions will
  -nevertheless be displayed in the selection component as empty items. If they
  -have an icon, they will be visible.
  -
  -ICON_ONLY:: Only icons are shown, captions are hidden.
  -
  -ID:: String representation of the item identifier object is used as caption. This is
  -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]
  -----
  -ComboBox select = new ComboBox("Inner Planets");
  -select.setItemCaptionMode(ItemCaptionMode.ID);
  +ComboBox<Planet> select = new ComboBox<>("Inner Planets");
   
   // A class that implements toString()
  -class PlanetId extends Object
  -               implements Serializable {
  +class Planet implements Serializable {
       String planetName;
   
  -    PlanetId (String name) {
  +    Planet(String name) {
           planetName = name;
       }
  +
       public String toString () {
           return "The Planet " + planetName;
       }
   }
   
  -// Use such objects as item identifiers
  -String planets[] = {"Mercury", "Venus",
  -                    "Earth", "Mars"};
  -for (int i=0; i<planets.length; i++)
  -    select.addItem(new PlanetId(planets[i]));
  -----
  +// Use such objects as items
  +List<Planet> planets = new ArrayList<>();
  +planets.add(new Planet("Mercury"));
  +planets.add(new Planet("Venus"));
  +planets.add(new Planet("Earth"));
  +
  +select.addItems(planets);
  +----
  +
  +Using a field of a item as caption: the caption is retrieved using the
  +[interfacename]#ItemCaptionProvider# typically given as Java 8 lambda:
  +
  +
   
   INDEX::
   Index number of item is used as caption.
  
positive.code: +
  [source, java]
  ----
  /** A bean with a "name" property. */
  public class Planet implements Serializable {
      int    id;
      String name;
  
      public Planet(int id, String name) {
          this.id   = id;
          this.name = name;
      }
  
      ... setters and getters ...
  }
  
  public void captionproperty(
          VerticalLayout layout) {
      // Have a bean container to put the beans in
      BeanItemContainer<Planet> container =
          new BeanItemContainer<Planet>(
              Planet.class);
  
      // Put some example data in it
      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);
  
      // 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
  
  A selection component provides the current selection as the property of the
  component (with the [classname]#Property# interface). The property value is an
  item identifier object that identifies the selected item. You can get the
  identifier with [methodname]#getValue()# of the [classname]#Property# interface.
  
  You can select an item with the corresponding [methodname]#setValue()# method.
  In multiselect mode, the property will be an unmodifiable set of item
  identifiers. If no item is selected, the property will be [parameter]#null# in
  single selection mode or an empty collection in multiselect mode.
  
  The [classname]#ComboBox# and [classname]#NativeSelect# will show empty
  selection when no actual item is selected. This is the __null selection item
  identifier__. You can set an alternative ID with
  [methodname]#setNullSelectionItemId()#. Setting the alternative null ID is
  merely a visual text; the [methodname]#getValue()# will still return
  [parameter]#null# value if no item is selected, or an empty set in multiselect
  mode.
  
  
  [[components.selection.valuechange]]
  == Handling Selection Changes
  
  The item identifier of the currently selected item will be set as the property
  of the selection component. You can access it with the [methodname]#getValue()#
  method of the [classname]#Property# interface of the component. Also, when
  handling selection changes with a [classname]#Property.ValueChangeListener#, the
  [classname]#ValueChangeEvent# will have the selected item as the property of the
  event, accessible with the [methodname]#getProperty()# method.
  
  
  [source, java]
  ----
  // Create a selection component with some items
  ComboBox select = new ComboBox("My Select");
  select.addItems("Io", "Europa", "Ganymedes", "Callisto");
  
  // Handle selection change
  select.addValueChangeListener(event -> // Java 8
      layout.addComponent(new Label("Selected " +
          event.getProperty().getValue())));
  ----
  
  The result of user interaction is shown in
  
negative.code: [[components.selection.newitems]]
  == Allowing Adding New Items
  
  
  [classname]#ComboBox# allows the user to add new items, when the user types
  in a value and presses kbd:[Enter]. You need to enable this with
  [methodname]#setNewItemHandler()#.
  
  Adding new items is not possible if the selection component is read-only. An
  attempt to do so may result in an exception.
  
  [[components.selection.newitems.handling]]
  === Handling New Items
  
  Adding new items is handled by a [interfacename]#NewItemHandler#, which gets the
  item caption string as parameter for the [methodname]#addNewItem()# method.
  
  ifdef::web[]
  
  [source, java]
  ----
  // List of planets
  List<Planet> planets = new ArrayList<>();
  planets.add(new Planet(1, "Mercury"));
  planets.add(new Planet(2, "Venus"));
  planets.add(new Planet(3, "Earth"));
  planets.add(new Planet(4, "Mars"));
  
  ComboBox<Planet> select =
      new ComboBox<>("Select or Add a Planet");
  select.setItems(planets);
  
  // Use the name property for item captions
  select.setItemCaptionProvider(Planet::getName);
  
  // Allow adding new items and add
  // handling for new items
  select.setNewItemHandler(inputString -> {
  
      // Create a new bean - can't set all properties
      Planet newPlanet = new Planet(0, inputString);
      planets.add(newPlanet);
  
      // Update combobox content
      select.setItems(planets);
  
      // Remember to set the selection to the new item
      select.select(newPlanet);
  
      Notification.show("Added new planet called " +
                        inputString);
  });
  ----
  See the http://demo.vaadin.com/book-examples-vaadin7/book#component.select.combobox.newitemhandler[on-line example, window="_blank"].
  endif::web[]
  
  
  [[components.selection.multiple]]
  == Multiple Selection
  
  Some selection components, such as [classname]#OptionGroup# and
  [classname]#ListSelect# support a multiple selection mode, which you can enable
  with [methodname]#setSelectionMode(SelectionMode.MULTI)#.
  For [classname]#TwinColSelect#, which is especially intended for
  multiple selection, it is enabled by default.
  
  
  [source, java]
  ----
  myselect.setSelectionMode(SelectionMode.MULTI);
  ----
  
  In multiple selection mode the [interfacename]#Select# value is a
  [classname]#Collection# of the items of the currently selected items.
  You can get and set the selection with the [methodname]#getSelected()# and
  [methodname]#setSelected()# methods as usual.
  
  A change in the selection will trigger a [classname]#SelectionChange#, which
  you can handle with a [classname]#SelectionChangeListener#. The
  following example shows how to handle selection changes with a listener.
  
  
  [source, java]
  ----
  // A selection component with some items
  ListSelect<String> select = new ListSelect<>("My Selection");
  select.setItems("Mercury", "Venus", "Earth",
      "Mars", "Jupiter", "Saturn", "Uranus", "Neptune");
  
  // Multiple selection mode
  select.setSelectionMode(SelectionMode.MULTI);
  
  // Feedback on value changes
  select.addSelectionChangeListener(event -> {
          // Some feedback
          layout.addComponent(new Label("Selected: " +
              event.getSelected()));
      }
  });
  
  ----
  
  
  [[components.selection.item-icons]]
  == Item Icons
  
  You can set an icon for each item with [methodname]#setItemIconProvider()#,
  in a fashion similar to captions. Notice, however, that icons are not
  supported in [classname]#NativeSelect#, [classname]#TwinColSelect#, and
  some other selection components and modes. This is because HTML does not
  support images inside the native [literal]#++select++#
  elements. Icons are also not really visually applicable.
  