anchor.diff:  [[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
  +
  +[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. 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.
  +item caption string as parameter for the [methodname]#addNewItem()# method.
   
   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);
  +// 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.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);
  -    }
  +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]#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.
  +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 select = new ListSelect("My Selection");
  -select.addItems("Mercury", "Venus", "Earth",
  +ListSelect<String> select = new ListSelect<>("My Selection");
  +select.setItems("Mercury", "Venus", "Earth",
       "Mars", "Jupiter", "Saturn", "Uranus", "Neptune");
   
   // Multiple selection mode
  -select.setMultiSelect(true);
  +select.setSelectionMode(SelectionMode.MULTI);
   
   // Feedback on value changes
  -select.addValueChangeListener(
  -    new Property.ValueChangeListener() {
  -    public void valueChange(ValueChangeEvent event) {
  +select.addSelectionChangeListener(event -> {
           // Some feedback
           layout.addComponent(new Label("Selected: " +
  -            event.getProperty().getValue().toString()));
  +            event.getSelected()));
       }
   });
  -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++#
  +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.
  
positive.code: [[components.selection.databinding]]
  == Binding Selection Components to Data
  
  The selection components are strongly coupled with the Vaadin Data Model,
  described 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.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">>.
  
  
  [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.
  
  
  [[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.
  
  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.
  
  
  +
  [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);
  
  // A class that implements toString()
  class PlanetId extends Object
                 implements Serializable {
      String planetName;
  
      PlanetId (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]));
  ----
  
  INDEX::
  Index number of item is used as caption.
  
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
  