123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112 |
- ---
- title: ComboBox
- order: 16
- layout: page
- ---
-
- [[components.combobox]]
- = [classname]#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%]
-
- [classname]#ComboBox# supports adding new items when the user presses
- kbd:[Enter].
- ifdef::web[]
- See <<dummy/../../../framework/components/components-selection#components.selection.newitems,"Allowing Adding New Items">>.
- endif::web[]
-
- [[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.
-
- [[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.
-
- Filtering is enabled by setting a __filtering mode__ with
- [methodname]#setFilteringMode()#.
-
-
- [source, java]
- ----
- cb.setFilteringMode(FilteringMode.CONTAINS);
- ----
- See the http://demo.vaadin.com/book-examples-vaadin7/book#component.select.combobox.filtering[on-line example, window="_blank"].
-
- The modes defined in the [classname]#FilteringMode# enum are as follows:
-
- [parameter]#CONTAINS#:: Matches any item that contains the string given in the text field part of the
- component.
-
- [parameter]#STARTSWITH#:: Matches only items that begin with the given string.
-
- [parameter]#OFF# (default):: Filtering is by default off and all items are shown all the time.
-
-
-
- The above example uses the containment filter that matches to all items
- containing the input string. As shown in <<figure.components.combobox.filter>>
- below, when we type some text in the input area, the drop-down list will show
- all the matching items.
-
-
- [[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.
|