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: [[components.selection.newitems]]
  == Allowing Adding New Items
  
  Some selection components can allow the user to add new items. Currently, only
  [classname]#ComboBox# allows it, when the user types in a value and presses
  kbd:[Enter]. You need to enable the mode with [methodname]#setNewItemsAllowed(true)#.
  Setting the component also in immediate mode may be necessary, as otherwise the
  item would not be added immediately when the user interacts with the component,
  but after some other component causes a server
  request.
  // TODO This could be a bug
  
  
  [source, java]
  ----
  myselect.setNewItemsAllowed(true);
  myselect.setImmediate(true);
  ----
  
  The user interface for adding new items depends on the selection component. The
  regular [classname]#ComboBox# component allows you to simply type the new item
  in the combo box and hit kbd:[Enter] to add it.
  
  Adding new items is not possible if the selection component is read-only or is
  bound to a [classname]#Container# that does not allow adding new items. 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. The
  default implementation, [classname]#DefaultNewItemHandler#, checks for read-only
  state, adds the item using the entered caption as the item ID, and if the
  selection component gets the captions from a property, copies the caption to
  that property. It also selects the item. The default implementation may not be
  suitable for all container types, in which case you need to define a custom
  handler. For example, a [classname]#BeanItemContainer# expects the items to have
  the bean object itself as the ID, not a string.
  
  ifdef::web[]
  
  [source, java]
  ----
  // Have a bean container to put the beans in
  final 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"));
  
  final ComboBox select =
      new ComboBox("Select or Add a Planet", container);
  select.setNullSelectionAllowed(false);
  
  // Use the name property for item captions
  select.setItemCaptionPropertyId("name");
  
  // Allow adding new items
  select.setNewItemsAllowed(true);
  select.setImmediate(true);
  
  // Custom handling for new items
  select.setNewItemHandler(new NewItemHandler() {
      @Override
      public void addNewItem(String newItemCaption) {
          // Create a new bean - can't set all properties
          Planet newPlanet = new Planet(0, newItemCaption);
          container.addBean(newPlanet);
  
          // Remember to set the selection to the new item
          select.select(newPlanet);
  
          Notification.show("Added new planet called " +
                            newItemCaption);
      }
  });
  ----
  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]#setMultiSelect()#. For [classname]#TwinColSelect#, which is
  especially intended for multiple selection, it is enabled by default.
  
  
  [source, java]
  ----
  myselect.setMultiSelect(true);
  ----
  
  As in single selection mode, the property value of the component indicates the
  selection. In multiple selection mode, however, the property value is a
  [classname]#Collection# of the item IDs of the currently selected items. You can
  get and set the property with the [methodname]#getValue()# and
  [methodname]#setValue()# methods as usual.
  
  A change in the selection will trigger a [classname]#ValueChangeEvent#, which
  you can handle with a [classname]#Propery.ValueChangeListener#. As usual, you
  should use [methodname]#setImmediate(true)# to trigger the event immediately
  when the user changes the selection. The following example shows how to handle
  selection changes with a listener.
  
  
  [source, java]
  ----
  // A selection component with some items
  ListSelect select = new ListSelect("My Selection");
  select.addItems("Mercury", "Venus", "Earth",
      "Mars", "Jupiter", "Saturn", "Uranus", "Neptune");
  
  // Multiple selection mode
  select.setMultiSelect(true);
  
  // Feedback on value changes
  select.addValueChangeListener(
      new Property.ValueChangeListener() {
      public void valueChange(ValueChangeEvent event) {
          // Some feedback
          layout.addComponent(new Label("Selected: " +
              event.getProperty().getValue().toString()));
      }
  });
  select.setImmediate(true);
  ----
  
  
  [[components.selection.item-icons]]
  == Item Icons
  
  You can set an icon for each item with [methodname]#setItemIcon()#, or define an
  item property that provides the icon resource with
  [methodname]#setItemIconPropertyId()#, 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.
  
negative.code: +
  [source, java]
  ----
  // A class that implements toString()
  class Planet implements Serializable {
      Integer id;
      String planetName;
  
      Planet(Integer id, String name) {
          this.id = id
          this.planetName = name;
      }
  
      public String toString () {
          return "The Planet " + planetName;
      }
  
      public Integer getId () {
          return id;
      }
  
  
      public String getName () {
          return planetName;
      }
  
  }
  
  // Put some example data
  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"));
  
  // Create a selection component
  ComboBox<Planet> select = new ComboBox<>("Planets");
  
  // Set the caption provider to read the
  // caption directly from the 'name'
  // property of the bean
  select.setItemCaptionProvider(Planet::getName);
  ----
  
  [[components.selection.getset]]
  == Getting and Setting Selection
  
  You can get the item with [methodname]#getSelected()# of the
  [classname]#Select# interface that returns collection of selected items.
  You can select an item with the corresponding [methodname]#select()# method.
  
  In multiselect mode, the [methodname]#getSelected()# returns an unmodifiable
  set of items. If no item is selected, the select will be an empty collection.
  
  The [classname]#ComboBox# and [classname]#NativeSelect# will show empty
  selection when no actual item is selected.
  
  
  [[components.selection.valuechange]]
  == Handling Selection Changes
  
  You can access currently selected item with the [methodname]#getSelected()# or
  [methodname]#getFirstSelected()# method of the component. Also, when
  handling selection changes with a
  [classname]#SelectionChangeListener#, the
  [classname]#SelectionChange# will have the selected items of the event.
  
  
  [source, java]
  ----
  // Create a selection component with some items
  ComboBox<String> select = new ComboBox<>("My Select");
  select.setItems("Io", "Europa", "Ganymedes", "Callisto");
  
  // Handle selection change
  select.addSelectionChangeListener(event ->
      layout.addComponent(new Label("Selected " +
          event.getSelected())));
  ----
  
  The result of user interaction is shown in
  