123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188 |
- ---
- title: Selection Components
- order: 5
- layout: page
- ---
-
- [[components.selection]]
- = Selection Components
-
- For a better overview on how selection works, see link:<<../datamodel/datamodel-selection.asciidoc#datamodel.selection,"Selecting Items">>.
-
- Vaadin offers many alternative ways for selecting one or more items. The core
- library includes the following selection components, all based on either
- [classname]#AbstractSingleSelect# or [classname]#AbstractMultiSelect# class:
-
- [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 and
- select one item.
- The component also provides a placeholder and the user can enter new items.
-
- [classname]#ListSelect# (<<components-listselect#components.listselect,"ListSelect">>)::
- A vertical list box for selecting items in 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]#RadioButtonGroup# (<<components-optiongroups#components.optiongroups,"CheckBoxGroup and RadioButtonGroup">>)::
- Shows the items as a vertically arranged group of radio buttons in single selection mode.
-
- [classname]#CheckBoxGroup# (<<components-optiongroups#components.optiongroups,"CheckBoxGroup and RadioButtonGroup">>)::
- Shows the items as a vertically arranged group 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]#Grid# component allows user selection.
-
- [[components.selection.databinding]]
- == Binding Selection Components to Data
-
- The selection components are typically bound to list of items obtained from backend system.
- You can give the list of items in the constructor or set it with
- [methodname]#setItems()#. Read more in
- <<../datamodel/datamodel-overview.asciidoc#datamodel.overview,"Binding
- Components to Data">>.
-
- You can get the current selection as the
- value of the selection component using [methodname]#getValue# defined in
- [interfacename]#HasValue# interface. Selection changes are handled as value change or
- selection events, as is described later.
-
-
- [[components.selection.captions]]
- == Item Captions
-
- 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]#setItemCaptionGenerator()# 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.setItemCaptionGenerator(Planet::getName);
-
- // Select the first
- select.setSelectedItem(planets.get(0));
- // or
- // select.setValue(planets.get(0));
- ----
-
- In addition to a caption, an item can have an icon. The icon is set with
- [methodname]#setItemIconGenerator()#.
-
- 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()# .
-
- Using a field of a item as caption: the caption is retrieved using the
- [interfacename]#ItemCaptionGenerator# typically given as a lambda or a method reference.
-
-
- [[components.selection.item-icons]]
- == Item Icons
-
- You can set an icon for each item with [methodname]#setItemIconGenerator()#,
- 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.
-
-
- [[components.selection.getset]]
- == Getting and Setting Selection
-
- For a better overview on how selection works, see link:<<../datamodel/datamodel-selection.asciidoc#datamodel.selection,"Selecting Items">>.
-
- You can get selected the item with [methodname]#getValue()# of the
- [interfacename]#HasValue# interface that returns either a single selected item
- (case of [interfacename]#SingleSelect#) or a collection of selected items (case of [interfacename]#MultiSelect#).
- You can select an item with the corresponding [methodname]#setValue()# method.
-
- The [classname]#ComboBox# and [classname]#NativeSelect# will show empty
- selection when no actual item is selected.
-
-
- [[components.selection.valuechange]]
- == Handling Selection Events
-
- You can access the currently selected item with the [methodname]#getValue()# ([interfacename]#SingleSelect#) or
- [methodname]#getSelectedItems()# ([interfacename]#MultiSelect#) method of the component. Also, when
- handling selection events with a
- [classname]#SelectionListener#, the
- [classname]#SelectionEvent# will have the selected items of the event. Single- and Multiselect
- components have their own more specific listener and event types, [interfacename]#SingleSelectionListener# for [classname]#SingleSelectionEvent# and [interfacename]#MultiSelectionListener# for [classname]#MultiSelectionEvent# respectively. Both can be added with the [methodname]#addSelectionListener# method.
-
-
- [source, java]
- ----
- // Create a selection component with some items
- ComboBox<String> select = new ComboBox<>("My Select");
- select.setItems("Io", "Europa", "Ganymedes", "Callisto");
-
- // Handle selection event
- select.addSelectionListener(event ->
- layout.addComponent(new Label("Selected " +
- event.getSelectedItem().orElse("none")));
- ----
-
- The result of user interaction is shown in
- <<figure.components.selection.valuechange>>.
-
- [[figure.components.selection.valuechange]]
- .Selected Item
- image::img/select-selected1.png[width=30%, scaledwidth=40%]
-
-
- [[components.selection.multiple]]
- == Multiple Selection
-
- For a better overview on how selection works, see link:<<../datamodel/datamodel-selection.asciidoc#datamodel.selection,"Selecting Items">>.
-
- Some selection components, such as [classname]#CheckBoxGroup#,
- [classname]#ListSelect# and [classname]#TwinColSelect# are multiselect components,
- they extend [classname]#AbstractMultiSelect# class.
-
-
- Multiselect components use the [interfacename]#MultiSelect# interface which extends [interfacename]#HasValue#.
- This provides more fine grained API for selection. You can get and set the selection with the [methodname]#getSelectedItems()# and
- [methodname]#select()# methods.
-
- A change in the selection will trigger a [classname]#SelectionEvent#, which
- you can handle with a [classname]#SelectionListener#. 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");
-
- // Feedback on value changes
- select.addSelectionListener(event -> {
- // Some feedback
- layout.addComponent(new Label("Selected: " +
- event.getNewSelection()));
- }
- });
-
- ----
|