123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126 |
- ---
- title: ComboBox
- order: 16
- layout: page
- ---
-
- [[components.combobox]]
- = ComboBox
-
- ifdef::web[]
- [.sampler]
- image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/multiple-value/combo-box"]
- endif::web[]
-
- [classname]#ComboBox# is a selection component allows selecting an item from a
- drop-down list. The component also has a text field area, which allows entering
- search text by which the items shown in the drop-down list are filtered. Common
- selection component features are described in
- <<dummy/../../../framework/components/components-selection#components.selection,"Selection
- Components">>.
-
- .The [classname]#ComboBox# Component
- image::img/combobox-basic.png[width=35%, scaledwidth=50%]
-
- [[components.combobox.filtering]]
- == Filtered Selection
-
- [classname]#ComboBox# allows filtering the items available for selection in the
- drop-down list by the text entered in the input box. To apply custom filtering, the [methodname]#setItems(CaptionFilter, Collection)# can be used. When using a [classname]#DataProvider#, the filtering is delegated to it.
-
- [[figure.components.combobox.filter]]
- .Filtered Selection in [classname]#ComboBox#
- image::img/combobox-filtering.png[width=35%, scaledwidth=50%]
-
- Pressing kbd:[Enter] will complete the item in the input box. Pressing kbd:[Up] and kbd:[Down] arrow keys can be used for selecting an item from the drop-down list. The
- drop-down list is paged and clicking on the scroll buttons will change to the
- next or previous page. The list selection can also be done with the arrow keys
- on the keyboard. The shown items are loaded from the server as needed, so the
- number of items held in the component can be quite large. The number of matching
- items is displayed by the drop-down list.
-
- [[components.combobox.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.
-
-
- === Handling New Items
-
- Adding new items is handled by a [interfacename]#NewItemHandler#, which gets the
- item caption string as parameter for the [methodname]#accept(String)# method.
-
-
- [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"));
-
- ComboBox<Planet> select =
- new ComboBox<>("Select or Add a Planet");
- select.setItems(planets);
-
- // Use the name property for item captions
- select.setItemCaptionGenerator(Planet::getName);
-
- // Allow adding new items and add
- // handling for new items
- select.setNewItemHandler(inputString -> {
-
- Planet newPlanet = new Planet(planets.size(), inputString);
- planets.add(newPlanet);
-
- // Update combobox content
- select.setItems(planets);
-
- // Remember to set the selection to the new item
- select.select(newPlanet);
- });
- ----
-
- [[components.combobox.css]]
- == CSS Style Rules
-
-
- [source, css]
- ----
- .v-filterselect { }
- .v-filterselect-input { }
- .v-filterselect-button { }
-
- // Under v-overlay-container
- .v-filterselect-suggestpopup { }
- .popupContent { }
- .v-filterselect-prevpage,
- .v-filterselect-prevpage-off { }
- .v-filterselect-suggestmenu { }
- .gwt-MenuItem { }
- .v-filterselect-nextpage,
- .v-filterselect-nextpage-off { }
- .v-filterselect-status { }
- ----
-
- In its default state, only the input field of the [classname]#ComboBox#
- component is visible. The entire component is enclosed in
- [literal]#++v-filterselect++# style (a legacy remnant), the input field has
- [literal]#++v-filterselect-input++# style and the button in the right end that
- opens and closes the drop-down result list has
- [literal]#++v-filterselect-button++# style.
-
- The drop-down result list has an overall
- [literal]#++v-filterselect-suggestpopup++# style. It contains the list of
- suggestions with [literal]#++v-filterselect-suggestmenu++# style. When there are
- more items that fit in the menu, navigation buttons with
- [literal]#++v-filterselect-prevpage++# and
- [literal]#++v-filterselect-nextpage++# styles are shown. When they are not
- shown, the elements have [literal]#++-off++# suffix. The status bar in the
- bottom that shows the paging status has [literal]#++v-filterselect-status++#
- style.
|