com.vaadin.flow.component.combobox

Class ComboBox<T>

java.lang.Object

com.vaadin.flow.component.Component

com.vaadin.flow.component.AbstractField<C,T>

com.vaadin.flow.component.AbstractSinglePropertyField<R,T>

com.vaadin.flow.component.combobox.GeneratedVaadinComboBox<ComboBox<T>,T>

com.vaadin.flow.component.combobox.ComboBox<T>

Type Parameters:

T - the type of the items to be inserted in the combo box

All Implemented Interfaces:

AttachNotifier, BlurNotifier<ComboBox<T>>, DetachNotifier, Focusable<ComboBox<T>>, FocusNotifier<ComboBox<T>>, HasElement, HasEnabled, HasHelper, HasSize, HasStyle, HasValidation, HasValue<AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>,T>, HasValueAndElement<AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>,T>, HasDataView<T,String,ComboBoxDataView<T>>, HasLazyDataView<T,String,ComboBoxLazyDataView<T>>, HasListDataView<T,ComboBoxListDataView<T>>, Serializable

@JsModule(value="./flow-component-renderer.js") @JsModule(value="./comboBoxConnector.js")
public class ComboBox<T>
extends GeneratedVaadinComboBox<ComboBox<T>,T>
implements HasSize, HasValidation, HasDataView<T,String,ComboBoxDataView<T>>, HasListDataView<T,ComboBoxListDataView<T>>, HasLazyDataView<T,String,ComboBoxLazyDataView<T>>, HasHelper

Server-side component for the vaadin-combo-box webcomponent. It contains the same features of the webcomponent, such as item filtering, object selection and item templating.

ComboBox supports lazy loading. This means that when using large data sets, items are requested from the server one "page" at a time when the user scrolls down the overlay. The number of items in one page is by default 50, and can be changed with setPageSize(int).

ComboBox can do filtering either in the browser or in the server. When ComboBox has only a relatively small set of items, the filtering will happen in the browser, allowing smooth user-experience. When the size of the data set is larger than the pageSize, the webcomponent doesn't necessarily have all the data available and it will make requests to the server to handle the filtering. Also, if you have defined custom filtering logic, with eg. setItems(ItemFilter, Collection), filtering will happen in the server. To enable client-side filtering with larger data sets, you can override the pageSize to be bigger than the size of your data set. However, then the full data set will be sent to the client immediately and you will lose the benefits of lazy loading.

Author:

Vaadin Ltd

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	ComboBox.FetchItemsCallback<T> A callback method for fetching items.
static interface	ComboBox.ItemFilter<T> Predicate to check ComboBox items against user typed strings.

Nested classes/interfaces inherited from class com.vaadin.flow.component.combobox.GeneratedVaadinComboBox

GeneratedVaadinComboBox.CustomValueSetEvent<R extends GeneratedVaadinComboBox<R,?>>, GeneratedVaadinComboBox.FilterChangeEvent<R extends GeneratedVaadinComboBox<R,?>>, GeneratedVaadinComboBox.InvalidChangeEvent<R extends GeneratedVaadinComboBox<R,?>>, GeneratedVaadinComboBox.OpenedChangeEvent<R extends GeneratedVaadinComboBox<R,?>>, GeneratedVaadinComboBox.SelectedItemChangeEvent<R extends GeneratedVaadinComboBox<R,?>>

Nested classes/interfaces inherited from class com.vaadin.flow.component.AbstractField

AbstractField.ComponentValueChangeEvent<C extends Component,V>

Nested classes/interfaces inherited from interface com.vaadin.flow.component.BlurNotifier

BlurNotifier.BlurEvent<C extends Component>

Nested classes/interfaces inherited from interface com.vaadin.flow.component.FocusNotifier

FocusNotifier.FocusEvent<C extends Component>

Nested classes/interfaces inherited from interface com.vaadin.flow.component.HasValue

HasValue.ValueChangeEvent<V>, HasValue.ValueChangeListener<E extends HasValue.ValueChangeEvent<?>>

Constructor Summary

Constructors

Constructor and Description
ComboBox() Default constructor.
ComboBox(int pageSize) Creates an empty combo box with the defined page size for lazy loading.
ComboBox(String label) Creates an empty combo box with the defined label.
ComboBox(String label, Collection<T> items) Creates a combo box with the defined label and populated with the items in the collection.
ComboBox(String label, T... items) Creates a combo box with the defined label and populated with the items in the array.

Method Summary

Modifier and Type	Method and Description
Registration	addCustomValueSetListener(ComponentEventListener<GeneratedVaadinComboBox.CustomValueSetEvent<ComboBox<T>>> listener) Adds a listener for the event which is fired when user inputs a string value that does not match any existing items and commits it eg.
DataProvider<T,?>	getDataProvider() Gets the data provider used by this ComboBox.
T	getEmptyValue() Returns the value that represents an empty value.
String	getErrorMessage() Gets the current error message from the combobox.
ComboBoxDataView<T>	getGenericDataView() Gets the generic data view for the ComboBox.
ItemLabelGenerator<T>	getItemLabelGenerator() Gets the item label generator that is used to produce the strings shown in the combo box for each item.
String	getLabel() Gets the label of the combobox.
ComboBoxLazyDataView<T>	getLazyDataView() Gets the lazy data view for the ComboBox.
ComboBoxListDataView<T>	getListDataView() Gets the list data view for the ComboBox.
int	getPageSize() Gets the page size, which is the number of items fetched at a time from the data provider.
String	getPattern() Gets the valid input pattern
String	getPlaceholder() Gets the placeholder of the combobox.
boolean	isAllowCustomValue() If true, the user can input string values that do not match to any existing item labels, which will fire a CustomValueSetEvent.
boolean	isAutofocus() Get the state for the auto-focus property of the combobox.
boolean	isAutoOpen() Gets whether dropdown will open automatically or not.
boolean	isClearButtonVisible() Gets whether this combo box displays a clear button when a value is selected.
boolean	isInvalid() Gets the validity of the combobox output.
boolean	isOpened() Gets the states of the drop-down.
boolean	isPreventInvalidInput() Determines whether preventing the user from inputing invalid value.
boolean	isRequired() Determines whether the combobox is marked as input required.
protected void	onAttach(AttachEvent attachEvent) Called when the component is attached to a UI.
protected void	onDetach(DetachEvent detachEvent) Called when the component is detached from a UI.
void	setAllowCustomValue(boolean allowCustomValue) Enables or disables the component firing events for custom string input.
void	setAutofocus(boolean autofocus) Set the combobox to be input focused when the page loads.
void	setAutoOpen(boolean autoOpen) Enables or disables the dropdown opening automatically.
void	setClearButtonVisible(boolean clearButtonVisible) Allows displaying a clear button in the combo box when a value is selected.
void	setDataProvider(ComboBox.FetchItemsCallback<T> fetchItems, SerializableFunction<String,Integer> sizeCallback) Deprecated. use instead setItems(CallbackDataProvider.FetchCallback, CallbackDataProvider.CountCallback) which provide access to ComboBoxLazyDataView
void	setDataProvider(ComboBox.ItemFilter<T> itemFilter, ListDataProvider<T> listDataProvider) Deprecated. use instead setItems(ItemFilter, ListDataProvider) which provide access to ComboBoxListDataView
<C> void	setDataProvider(DataProvider<T,C> dataProvider, SerializableFunction<String,C> filterConverter) Deprecated. use instead one of the setItems methods which provide access to either ComboBoxListDataView or ComboBoxLazyDataView
void	setDataProvider(DataProvider<T,String> dataProvider) Deprecated. use instead one of the setItems methods which provide access to either ComboBoxListDataView or ComboBoxLazyDataView
void	setDataProvider(ListDataProvider<T> listDataProvider) Deprecated. use instead one of the setItems methods which provide access to ComboBoxListDataView
void	setErrorMessage(String errorMessage) Description copied from corresponding location in WebComponent:
void	setInvalid(boolean invalid) Description copied from corresponding location in WebComponent:
void	setItemLabelGenerator(ItemLabelGenerator<T> itemLabelGenerator) Sets the item label generator that is used to produce the strings shown in the combo box for each item.
ComboBoxLazyDataView<T>	setItems(BackEndDataProvider<T,String> dataProvider) Supply items with a BackEndDataProvider that lazy loads items from a backend.
ComboBoxLazyDataView<T>	setItems(CallbackDataProvider.FetchCallback<T,String> fetchCallback) Supply items lazily with a callback from a backend.
ComboBoxLazyDataView<T>	setItems(CallbackDataProvider.FetchCallback<T,String> fetchCallback, CallbackDataProvider.CountCallback<T,String> countCallback) Supply items lazily with callbacks: the first one fetches the items based on offset, limit and an optional filter, the second provides the exact count of items in the backend.
ComboBoxListDataView<T>	setItems(Collection<T> items) Sets the items from the given Collection and returns a ListDataView that provides information and allows operations on the items.
ComboBoxListDataView<T>	setItems(ComboBox.ItemFilter<T> itemFilter, Collection<T> items) Sets the data items of this combo box and a filtering function for defining which items are displayed when user types into the combo box.
ComboBoxListDataView<T>	setItems(ComboBox.ItemFilter<T> itemFilter, ListDataProvider<T> listDataProvider) Sets a ListDataProvider for this combo box and a filtering function for defining which items are displayed when user types into the combo box.
ComboBoxListDataView<T>	setItems(ComboBox.ItemFilter<T> itemFilter, T... items) Sets the data items of this combo box and a filtering function for defining which items are displayed when user types into the combo box.
ComboBoxDataView<T>	setItems(DataProvider<T,String> dataProvider) Set a generic data provider for the component to use and returns the base DataView that provides API to get information on the items.
ComboBoxDataView<T>	setItems(InMemoryDataProvider<T> dataProvider) Deprecated. does not work so don't use
ComboBoxDataView<T>	setItems(InMemoryDataProvider<T> inMemoryDataProvider, SerializableFunction<String,SerializablePredicate<T>> filterConverter) Sets an in-memory data provider for the combo box to use, taking into account both in-memory filtering from data provider and combo box's text filter.
ComboBoxListDataView<T>	setItems(ListDataProvider<T> dataProvider) Sets a ListDataProvider for the component to use and returns a ListDataView that provides information and allows operations on the items.
void	setItems(Stream<T> streamOfItems) Deprecated. Because the stream is collected to a list anyway, use setItems(Collection) or setItems(CallbackDataProvider.FetchCallback) instead.
<C> ComboBoxLazyDataView<T>	setItemsWithFilterConverter(CallbackDataProvider.FetchCallback<T,C> fetchCallback, CallbackDataProvider.CountCallback<T,C> countCallback, SerializableFunction<String,C> filterConverter) Supply items lazily with callbacks: the first one fetches the items based on offset, limit and an optional filter, the second provides the exact count of items in the backend.
<C> ComboBoxLazyDataView<T>	setItemsWithFilterConverter(CallbackDataProvider.FetchCallback<T,C> fetchCallback, SerializableFunction<String,C> filterConverter) Supply items lazily with a callback from a backend, using custom filter type.
void	setLabel(String label) Description copied from corresponding location in WebComponent:
void	setOpened(boolean opened) Description copied from corresponding location in WebComponent:
void	setPageSize(int pageSize) Sets the page size, which is the number of items requested at a time from the data provider.
void	setPattern(String pattern) Description copied from corresponding location in WebComponent:
void	setPlaceholder(String placeholder) Description copied from corresponding location in WebComponent:
void	setPreventInvalidInput(boolean preventInvalidInput) Description copied from corresponding location in WebComponent:
void	setRenderer(Renderer<T> renderer) Sets the TemplateRenderer responsible to render the individual items in the list of possible choices of the ComboBox.
void	setRequired(boolean required) Description copied from corresponding location in WebComponent:
void	setRequiredIndicatorVisible(boolean requiredIndicatorVisible) Sets the required indicator visible or not.
void	setValue(T value) Sets the value of this object.

Methods inherited from class com.vaadin.flow.component.combobox.GeneratedVaadinComboBox

addFilterChangeListener, addInvalidChangeListener, addOpenedChangeListener, addSelectedItemChangeListener, addToPrefix, cancel, checkValidity, clearCache, close, getErrorMessageString, getFilteredItemsJsonArray, getFilterString, getItemIdPathString, getItemLabelPathString, getItemsJsonArray, getItemValuePathString, getLabelString, getNameString, getPageSizeDouble, getPatternString, getPlaceholderString, getSelectedItemJsonObject, getSizeDouble, isAllowCustomValueBoolean, isAutofocusBoolean, isClearButtonVisibleBoolean, isDisabledBoolean, isInvalidBoolean, isLoadingBoolean, isOpenedBoolean, isPreventInvalidInputBoolean, isReadonlyBoolean, isRequiredBoolean, open, remove, removeAll, render, setDisabled, setFilter, setFilteredItems, setItemIdPath, setItemLabelPath, setItems, setItemValuePath, setLoading, setName, setPageSize, setReadonly, setSelectedItem, setSize, validate

Methods inherited from class com.vaadin.flow.component.AbstractSinglePropertyField

getSynchronizationRegistration, hasValidValue, setPresentationValue, setSynchronizedEvent

Methods inherited from class com.vaadin.flow.component.AbstractField

addValueChangeListener, getValue, isEmpty, setModelValue, valueEquals

Methods inherited from class com.vaadin.flow.component.Component

addListener, fireEvent, from, get, getChildren, getElement, getEventBus, getId, getLocale, getParent, getTranslation, getTranslation, getUI, hasListener, isAttached, isTemplateMapped, isVisible, onEnabledStateChanged, set, setElement, setId, setVisible

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.vaadin.flow.component.HasSize

getCssSize, getHeight, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getWidth, setHeight, setHeight, setHeightFull, setMaxHeight, setMaxHeight, setMaxWidth, setMaxWidth, setMinHeight, setMinHeight, setMinWidth, setMinWidth, setSizeFull, setSizeUndefined, setWidth, setWidth, setWidthFull

Methods inherited from interface com.vaadin.flow.data.provider.HasListDataView

setItems

Methods inherited from interface com.vaadin.flow.component.HasHelper

getHelperComponent, getHelperText, setHelperComponent, setHelperText

Methods inherited from interface com.vaadin.flow.component.HasElement

getElement

Methods inherited from interface com.vaadin.flow.component.HasStyle

addClassName, addClassNames, getClassName, getClassNames, getStyle, hasClassName, removeClassName, removeClassNames, setClassName, setClassName

Methods inherited from interface com.vaadin.flow.component.Focusable

addFocusShortcut, blur, focus, getTabIndex, setTabIndex

Methods inherited from interface com.vaadin.flow.component.BlurNotifier

addBlurListener

Methods inherited from interface com.vaadin.flow.component.FocusNotifier

addFocusListener

Methods inherited from interface com.vaadin.flow.component.HasEnabled

isEnabled, setEnabled

Methods inherited from interface com.vaadin.flow.component.HasValueAndElement

isReadOnly, isRequiredIndicatorVisible, setReadOnly

Methods inherited from interface com.vaadin.flow.component.HasValue

clear, getOptionalValue

Methods inherited from interface com.vaadin.flow.component.AttachNotifier

addAttachListener

Methods inherited from interface com.vaadin.flow.component.DetachNotifier

addDetachListener

Constructor Detail

ComboBox

public ComboBox(int pageSize)

Creates an empty combo box with the defined page size for lazy loading.

The default page size is 50.

The page size is also the largest number of items that can support client-side filtering. If you provide more items than the page size, the component has to fall back to server-side filtering.

Parameters:

pageSize - the amount of items to request at a time for lazy loading

See Also:

#setPageSize(int)}

ComboBox

public ComboBox()

Default constructor. Creates an empty combo box.

ComboBox

public ComboBox(String label)

Creates an empty combo box with the defined label.

Parameters:

label - the label describing the combo box

ComboBox

public ComboBox(String label,
                Collection<T> items)

Creates a combo box with the defined label and populated with the items in the collection.

Parameters:

label - the label describing the combo box

items - the items to be shown in the list of the combo box

See Also:

setItems(Collection)

ComboBox

@SafeVarargs
public ComboBox(String label,
                             T... items)

Creates a combo box with the defined label and populated with the items in the array.

Parameters:

label - the label describing the combo box

items - the items to be shown in the list of the combo box

See Also:

HasListDataView.setItems(Object...)

Method Detail

setValue

public void setValue(T value)

Description copied from interface: HasValue

Sets the value of this object. If the new value is not equal to getValue(), fires a value change event. May throw IllegalArgumentException if the value is not acceptable.

Implementation note: the implementing class should document whether null values are accepted or not, and override HasValue.getEmptyValue() if the empty value is not null.

Specified by:

setValue in interface HasValue<AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>,T>

Overrides:

setValue in class AbstractField<ComboBox<T>,T>

Parameters:

value - the new value

setRenderer

public void setRenderer(Renderer<T> renderer)

Sets the TemplateRenderer responsible to render the individual items in the list of possible choices of the ComboBox. It doesn't affect how the selected item is rendered - that can be configured by using setItemLabelGenerator(ItemLabelGenerator).

Parameters:

renderer - a renderer for the items in the selection list of the ComboBox, not null Note that filtering of the ComboBox is not affected by the renderer that is set here. Filtering is done on the original values and can be affected by setItemLabelGenerator(ItemLabelGenerator).

setItems

public ComboBoxListDataView<T> setItems(Collection<T> items)

Sets the items from the given Collection and returns a ListDataView that provides information and allows operations on the items.

Filtering will use a case insensitive match to show all items where the filter text is a substring of the label displayed for that item, which you can configure with setItemLabelGenerator(ItemLabelGenerator).

Filtering will be handled in the client-side if the size of the data set is less than the page size. To force client-side filtering with a larger data set (at the cost of increased network traffic), you can increase the page size with setPageSize(int).

Setting the items resets the combo box's value to null.

Specified by:

setItems in interface HasListDataView<T,ComboBoxListDataView<T>>

Parameters:

items - the items to display, not null

Returns:

ListDataView providing access to the items

setItems

public ComboBoxListDataView<T> setItems(ComboBox.ItemFilter<T> itemFilter,
                                        Collection<T> items)

Sets the data items of this combo box and a filtering function for defining which items are displayed when user types into the combo box.

Note that defining a custom filter will force the component to make server roundtrips to handle the filtering. Otherwise it can handle filtering in the client-side, if the size of the data set is less than the pageSize.

Setting the items resets the combo box's value to null.

The returned data view object can be used for further access to combo box items, or later on fetched with getListDataView(). For using lazy data loading, use one of the setItems methods which take a fetch callback parameter instead.

Parameters:

itemFilter - filter to check if an item is shown when user typed some text into the ComboBox

items - the data items to display

Returns:

the in-memory data view instance that provides access to the data bound to the combo box

setItems

public ComboBoxListDataView<T> setItems(ComboBox.ItemFilter<T> itemFilter,
                                        T... items)

Sets the data items of this combo box and a filtering function for defining which items are displayed when user types into the combo box.

Note that defining a custom filter will force the component to make server roundtrips to handle the filtering. Otherwise it can handle filtering in the client-side, if the size of the data set is less than the pageSize.

Setting the items resets the combo box's value to null.

The returned data view object can be used for further access to combo box items, or later on fetched with getListDataView(). For using lazy data loading, use one of the setItems methods which take a fetch callback parameter instead.

Parameters:

itemFilter - filter to check if an item is shown when user typed some text into the ComboBox

items - the data items to display

Returns:

the in-memory data view instance that provides access to the data bound to the combo box

setItems

@Deprecated
public void setItems(Stream<T> streamOfItems)

Deprecated. Because the stream is collected to a list anyway, use setItems(Collection) or setItems(CallbackDataProvider.FetchCallback) instead.

setItems

public ComboBoxDataView<T> setItems(DataProvider<T,String> dataProvider)

Description copied from interface: HasDataView

Set a generic data provider for the component to use and returns the base DataView that provides API to get information on the items.

This method should be used only when the data provider type is not either ListDataProvider or BackEndDataProvider.

Specified by:

setItems in interface HasDataView<T,String,ComboBoxDataView<T>>

Parameters:

dataProvider - DataProvider instance to use, not null

Returns:

DataView providing information on the data

setItems

@Deprecated
public ComboBoxDataView<T> setItems(InMemoryDataProvider<T> dataProvider)

Deprecated. does not work so don't use

The method is not supported for the ComboBox component, use another overloaded method with filter converter setItems(InMemoryDataProvider, SerializableFunction)

Always throws an UnsupportedOperationException.

Specified by:

setItems in interface HasDataView<T,String,ComboBoxDataView<T>>

Parameters:

dataProvider - InMemoryDataProvider to use, not null

Returns:

DataView providing information on the data

Throws:

UnsupportedOperationException

See Also:

setItems(InMemoryDataProvider, SerializableFunction)

setItems

public ComboBoxDataView<T> setItems(InMemoryDataProvider<T> inMemoryDataProvider,
                                    SerializableFunction<String,SerializablePredicate<T>> filterConverter)

Sets an in-memory data provider for the combo box to use, taking into account both in-memory filtering from data provider and combo box's text filter.

Text filter is transformed into a predicate filter through the given filter converter. Example of filter converter which produces the Person's name predicate: (String nameFilter) -> person -> person.getName().equalsIgnoreCase (nameFilter);

Filtering will be handled in the client-side if the size of the data set is less than the page size. To force client-side filtering with a larger data set (at the cost of increased network traffic), you can increase the page size with setPageSize(int).

Note! Using a ListDataProvider instead of a InMemoryDataProvider is recommended to get access to ListDataView API by using setItems(ListDataProvider).

Parameters:

inMemoryDataProvider - InMemoryDataProvider to use, not null

filterConverter - a function which converts a component's internal filter into a predicate applied to the data provider

Returns:

DataView providing information on the data

getGenericDataView

public ComboBoxDataView<T> getGenericDataView()

Gets the generic data view for the ComboBox. This data view can be used when getListDataView() or getLazyDataView() are not applicable for the underlying data provider, or you don't want to distinct between which type of data view to use.

Specified by:

getGenericDataView in interface HasDataView<T,String,ComboBoxDataView<T>>

Returns:

the generic DataView implementation for ComboBox

See Also:

getListDataView(), getLazyDataView()

setItems

public ComboBoxLazyDataView<T> setItems(BackEndDataProvider<T,String> dataProvider)

Description copied from interface: HasLazyDataView

Supply items with a BackEndDataProvider that lazy loads items from a backend. Note that component will query the data provider for the item count. In case that is not desired for performance reasons, use HasLazyDataView.setItems(CallbackDataProvider.FetchCallback) instead.

The returned data view object can be used for further configuration, or later on fetched with HasLazyDataView.getLazyDataView(). For using in-memory data, like Collection, use HasListDataView.setItems(Collection) instead.

Specified by:

setItems in interface HasLazyDataView<T,String,ComboBoxLazyDataView<T>>

Parameters:

dataProvider - BackEndDataProvider instance

Returns:

LazyDataView instance for further configuration

getLazyDataView

public ComboBoxLazyDataView<T> getLazyDataView()

Gets the lazy data view for the ComboBox. This data view should only be used when the items are provided lazily from the backend with:

• setItems(CallbackDataProvider.FetchCallback)
• setItemsWithFilterConverter(CallbackDataProvider.FetchCallback, SerializableFunction)
• setItems(CallbackDataProvider.FetchCallback, CallbackDataProvider.CountCallback)
• setItemsWithFilterConverter(CallbackDataProvider.FetchCallback, CallbackDataProvider.CountCallback, SerializableFunction)
• setItems(BackEndDataProvider)

If the items are not fetched lazily an exception is thrown. When the items are in-memory, use getListDataView() instead.

Specified by:

getLazyDataView in interface HasLazyDataView<T,String,ComboBoxLazyDataView<T>>

Returns:

the lazy data view that provides access to the data bound to the ComboBox

Throws:

IllegalStateException - if no items fetch callback(s) set

setItems

public ComboBoxListDataView<T> setItems(ListDataProvider<T> dataProvider)

Description copied from interface: HasListDataView

Sets a ListDataProvider for the component to use and returns a ListDataView that provides information and allows operations on the items.

Specified by:

setItems in interface HasListDataView<T,ComboBoxListDataView<T>>

Parameters:

dataProvider - ListDataProvider providing items to the component.

Returns:

ListDataView providing access to the items

getListDataView

public ComboBoxListDataView<T> getListDataView()

Gets the list data view for the ComboBox. This data view should only be used when the items are in-memory set with:

• setItems(Collection)
• HasListDataView.setItems(Object[])
• setItems(ListDataProvider)
• setItems(ItemFilter, ListDataProvider)
• setItems(ItemFilter, Object[])
• setItems(ItemFilter, Collection)

If the items are not in-memory an exception is thrown. When the items are fetched lazily, use getLazyDataView() instead.

Specified by:

getListDataView in interface HasListDataView<T,ComboBoxListDataView<T>>

Returns:

the list data view that provides access to the items in the ComboBox

setDataProvider

@Deprecated
public void setDataProvider(DataProvider<T,String> dataProvider)

Deprecated. use instead one of the setItems methods which provide access to either ComboBoxListDataView or ComboBoxLazyDataView

The filter-type of the given data provider must be String so that it can handle the filters typed into the ComboBox by users. If your data provider uses some other type of filter, you can provide a function which converts the ComboBox's filter-string into that type via setDataProvider(DataProvider, SerializableFunction). Another way to do the same thing is to use this method with your data provider converted with DataProvider.withConvertedFilter(SerializableFunction).

Changing the combo box's data provider resets its current value to null.

setItemsWithFilterConverter

public <C> ComboBoxLazyDataView<T> setItemsWithFilterConverter(CallbackDataProvider.FetchCallback<T,C> fetchCallback,
                                                               SerializableFunction<String,C> filterConverter)

Supply items lazily with a callback from a backend, using custom filter type. The combo box will automatically fetch more items and adjust its size until the backend runs out of items. Usage example:

comboBox.setItemsWithFilterConverter( query -> orderService.getOrdersByCount(query.getFilter(), query.getOffset, query.getLimit()), orderCountStr -> Integer.parseInt(orderCountStr)); Note: Validations for orderCountStr are omitted for briefness.

Combo box's client-side filter typed by the user is transformed into a callback's filter through the given filter converter.

The returned data view object can be used for further configuration, or later on fetched with getLazyDataView(). For using in-memory data, like Collection, use setItems(Collection) instead.

Type Parameters:

C - filter type used by a callback

Parameters:

fetchCallback - function that returns a stream of items from the backend based on the offset, limit and a object filter

filterConverter - a function which converts a combo box's filter-string typed by the user into a callback's object filter

Returns:

ComboBoxLazyDataView instance for further configuration

setItemsWithFilterConverter

public <C> ComboBoxLazyDataView<T> setItemsWithFilterConverter(CallbackDataProvider.FetchCallback<T,C> fetchCallback,
                                                               CallbackDataProvider.CountCallback<T,C> countCallback,
                                                               SerializableFunction<String,C> filterConverter)

Supply items lazily with callbacks: the first one fetches the items based on offset, limit and an optional filter, the second provides the exact count of items in the backend. Use this only in case getting the count is cheap and the user benefits from the component showing immediately the exact size. Usage example:

comboBox.setItemsWithFilterConverter( query -> orderService.getOrdersByCount(query.getFilter(), query.getOffset, query.getLimit()), query -> orderService.getSize(query.getFilter()), orderCountStr -> Integer.parseInt(orderCountStr)); Note: Validations for orderCountStr are omitted for briefness.

Combo box's client-side filter typed by the user is transformed into a custom filter type through the given filter converter.

The returned data view object can be used for further configuration, or later on fetched with getLazyDataView(). For using in-memory data, like Collection, use setItems(Collection) instead.

Type Parameters:

C - filter type used by a callbacks

Parameters:

fetchCallback - function that returns a stream of items from the backend based on the offset, limit and a object filter

filterConverter - a function which converts a combo box's filter-string typed by the user into a callback's object filter

Returns:

ComboBoxLazyDataView instance for further configuration

setDataProvider

@Deprecated
public <C> void setDataProvider(DataProvider<T,C> dataProvider,
                                            SerializableFunction<String,C> filterConverter)

Deprecated. use instead one of the setItems methods which provide access to either ComboBoxListDataView or ComboBoxLazyDataView

ComboBox triggers filtering queries based on the strings users type into the field. For this reason you need to provide the second parameter, a function which converts the filter-string typed by the user into filter-type used by your data provider. If your data provider already supports String as the filter-type, it can be used without a converter function via setDataProvider(DataProvider).

Using this method provides the same result as using a data provider wrapped with DataProvider.withConvertedFilter(SerializableFunction).

Changing the combo box's data provider resets its current value to null.

onAttach

protected void onAttach(AttachEvent attachEvent)

Description copied from class: Component

Called when the component is attached to a UI.

The default implementation does nothing.

This method is invoked before the AttachEvent is fired for the component.

Overrides:

onAttach in class Component

Parameters:

attachEvent - the attach event

onDetach

protected void onDetach(DetachEvent detachEvent)

Description copied from class: Component

Called when the component is detached from a UI.

The default implementation does nothing.

This method is invoked before the DetachEvent is fired for the component.

Overrides:

onDetach in class Component

Parameters:

detachEvent - the detach event

setDataProvider

@Deprecated
public void setDataProvider(ListDataProvider<T> listDataProvider)

Deprecated. use instead one of the setItems methods which provide access to ComboBoxListDataView

Sets a list data provider as the data provider of this combo box.

Filtering will use a case insensitive match to show all items where the filter text is a substring of the label displayed for that item, which you can configure with setItemLabelGenerator(ItemLabelGenerator).

Filtering will be handled in the client-side if the size of the data set is less than the page size. To force client-side filtering with a larger data set (at the cost of increased network traffic), you can increase the page size with setPageSize(int).

Changing the combo box's data provider resets its current value to null.

Parameters:

listDataProvider - the list data provider to use, not null

setDataProvider

@Deprecated
public void setDataProvider(ComboBox.FetchItemsCallback<T> fetchItems,
                                        SerializableFunction<String,Integer> sizeCallback)

Deprecated. use instead setItems(CallbackDataProvider.FetchCallback, CallbackDataProvider.CountCallback) which provide access to ComboBoxLazyDataView

Sets a CallbackDataProvider using the given fetch items callback and a size callback.

This method is a shorthand for making a CallbackDataProvider that handles a partial Query object.

Changing the combo box's data provider resets its current value to null.

Parameters:

fetchItems - a callback for fetching items, not null

sizeCallback - a callback for getting the count of items, not null

See Also:

CallbackDataProvider, setDataProvider(DataProvider)

setDataProvider

@Deprecated
public void setDataProvider(ComboBox.ItemFilter<T> itemFilter,
                                        ListDataProvider<T> listDataProvider)

Deprecated. use instead setItems(ItemFilter, ListDataProvider) which provide access to ComboBoxListDataView

Sets a list data provider with an item filter as the data provider of this combo box. The item filter is used to compare each item to the filter text entered by the user.

Note that defining a custom filter will force the component to make server roundtrips to handle the filtering. Otherwise it can handle filtering in the client-side, if the size of the data set is less than the pageSize.

Changing the combo box's data provider resets its current value to null.

Parameters:

itemFilter - filter to check if an item is shown when user typed some text into the ComboBox

listDataProvider - the list data provider to use, not null

setItems

public ComboBoxListDataView<T> setItems(ComboBox.ItemFilter<T> itemFilter,
                                        ListDataProvider<T> listDataProvider)

Sets a ListDataProvider for this combo box and a filtering function for defining which items are displayed when user types into the combo box.

Note that defining a custom filter will force the component to make server roundtrips to handle the filtering. Otherwise it can handle filtering in the client-side, if the size of the data set is less than the pageSize.

Setting the items resets the combo box's value to null.

The returned data view object can be used for further access to combo box items, or later on fetched with getListDataView(). For using lazy data loading, use one of the setItems methods which take a fetch callback parameter instead.

Parameters:

itemFilter - filter to check if an item is shown when user typed some text into the ComboBox.

listDataProvider - ListDataProvider providing items to the component.

Returns:

the in-memory data view instance that provides access to the data bound to the combo box

getDataProvider

public DataProvider<T,?> getDataProvider()

Gets the data provider used by this ComboBox.

Returns:

the data provider used by this ComboBox

setItemLabelGenerator

public void setItemLabelGenerator(ItemLabelGenerator<T> itemLabelGenerator)

Sets the item label generator that is used to produce the strings shown in the combo box for each item. By default, String.valueOf(Object) is used.

When the setRenderer(Renderer) is used, the ItemLabelGenerator is only used to show the selected item label.

Parameters:

itemLabelGenerator - the item label provider to use, not null

getItemLabelGenerator

public ItemLabelGenerator<T> getItemLabelGenerator()

Gets the item label generator that is used to produce the strings shown in the combo box for each item.

Returns:

the item label generator used, not null

setPageSize

public void setPageSize(int pageSize)

Sets the page size, which is the number of items requested at a time from the data provider. This does not guarantee a maximum query size to the backend; when the overlay has room to render more new items than the page size, multiple "pages" will be requested at once.

The page size is also the largest number of items that can support client-side filtering. If you provide more items than the page size, the component has to fall back to server-side filtering.

Setting the page size after the ComboBox has been rendered effectively resets the component, and the current page(s) and sent over again.

The default page size is 50.

Parameters:

pageSize - the maximum number of items sent per request, should be greater than zero

getPageSize

public int getPageSize()

Gets the page size, which is the number of items fetched at a time from the data provider.

The page size is also the largest number of items that can support client-side filtering. If you provide more items than the page size, the component has to fall back to server-side filtering.

The default page size is 50.

Returns:

the maximum number of items sent per request

See Also:

#setPageSize(int)}

setOpened

public void setOpened(boolean opened)

Description copied from class: GeneratedVaadinComboBox

Description copied from corresponding location in WebComponent:

True if the dropdown is open, false otherwise.

Overrides:

setOpened in class GeneratedVaadinComboBox<ComboBox<T>,T>

Parameters:

opened - the boolean value to set

isOpened

public boolean isOpened()

Gets the states of the drop-down.

Returns:

true if the drop-down is opened, false otherwise

setInvalid

public void setInvalid(boolean invalid)

Description copied from class: GeneratedVaadinComboBox

Description copied from corresponding location in WebComponent:

Set to true if the value is invalid.

Specified by:

setInvalid in interface HasValidation

Overrides:

setInvalid in class GeneratedVaadinComboBox<ComboBox<T>,T>

Parameters:

invalid - the boolean value to set

isInvalid

public boolean isInvalid()

Gets the validity of the combobox output.

return true, if the value is invalid.

Specified by:

isInvalid in interface HasValidation

Returns:

the validity property from the component

setErrorMessage

public void setErrorMessage(String errorMessage)

Description copied from class: GeneratedVaadinComboBox

Description copied from corresponding location in WebComponent:

The error message to display when the input is invalid.

Specified by:

setErrorMessage in interface HasValidation

Overrides:

setErrorMessage in class GeneratedVaadinComboBox<ComboBox<T>,T>

Parameters:

errorMessage - the String value to set

getErrorMessage

public String getErrorMessage()

Gets the current error message from the combobox.

Specified by:

getErrorMessage in interface HasValidation

Returns:

the current error message

setAllowCustomValue

public void setAllowCustomValue(boolean allowCustomValue)

Enables or disables the component firing events for custom string input.

When enabled, a CustomValueSetEvent will be fired when the user inputs a string value that does not match any existing items and commits it eg. by blurring or pressing the enter-key.

Note that ComboBox doesn't do anything with the custom value string automatically. Use the addCustomValueSetListener(ComponentEventListener) method to determine how the custom value should be handled. For example, when the ComboBox has String as the value type, you can add a listener which sets the custom string as the value of the ComboBox with setValue(Object).

Setting to true also allows an unfocused ComboBox to display a string that doesn't match any of its items nor its current value, unless this is explicitly handled with addCustomValueSetListener(ComponentEventListener). When set to false, an unfocused ComboBox will always display the label of the currently selected item.

Overrides:

setAllowCustomValue in class GeneratedVaadinComboBox<ComboBox<T>,T>

Parameters:

allowCustomValue - true to enable custom value set events, false to disable them

See Also:

addCustomValueSetListener(ComponentEventListener)

isAllowCustomValue

public boolean isAllowCustomValue()

If true, the user can input string values that do not match to any existing item labels, which will fire a CustomValueSetEvent.

Returns:

true if the component fires custom value set events, false otherwise

See Also:

setAllowCustomValue(boolean), addCustomValueSetListener(ComponentEventListener)

setAutoOpen

public void setAutoOpen(boolean autoOpen)

Enables or disables the dropdown opening automatically. If false the dropdown is only opened when clicking the toggle button or pressing Up or Down arrow keys.

Parameters:

autoOpen - false to prevent the dropdown from opening automatically

isAutoOpen

public boolean isAutoOpen()

Gets whether dropdown will open automatically or not.

Returns:

@{code true} if enabled, false otherwise

setAutofocus

public void setAutofocus(boolean autofocus)

Set the combobox to be input focused when the page loads.

Overrides:

setAutofocus in class GeneratedVaadinComboBox<ComboBox<T>,T>

Parameters:

autofocus - the boolean value to set

isAutofocus

public boolean isAutofocus()

Get the state for the auto-focus property of the combobox.

This property is not synchronized automatically from the client side, so the returned value may not be the same as in client side.

Returns:

the autofocus property from the combobox

setPreventInvalidInput

public void setPreventInvalidInput(boolean preventInvalidInput)

Description copied from class: GeneratedVaadinComboBox

Description copied from corresponding location in WebComponent:

Set to true to prevent the user from entering invalid input.

Overrides:

setPreventInvalidInput in class GeneratedVaadinComboBox<ComboBox<T>,T>

Parameters:

preventInvalidInput - the boolean value to set

isPreventInvalidInput

public boolean isPreventInvalidInput()

Determines whether preventing the user from inputing invalid value.

This property is not synchronized automatically from the client side, so the returned value may not be the same as in client side.

Returns:

the preventInvalidInput property of the combobox

setRequired

public void setRequired(boolean required)

Description copied from class: GeneratedVaadinComboBox

Description copied from corresponding location in WebComponent:

Set to true to mark the input as required.

Overrides:

setRequired in class GeneratedVaadinComboBox<ComboBox<T>,T>

Parameters:

required - the boolean value to set

isRequired

public boolean isRequired()

Determines whether the combobox is marked as input required.

This property is not synchronized automatically from the client side, so the returned value may not be the same as in client side.

Returns:

true if the input is required, false otherwise

setLabel

public void setLabel(String label)

Description copied from class: GeneratedVaadinComboBox

Description copied from corresponding location in WebComponent:

The label for this element.

Overrides:

setLabel in class GeneratedVaadinComboBox<ComboBox<T>,T>

Parameters:

label - the String value to set

getLabel

public String getLabel()

Gets the label of the combobox.

Returns:

the label property of the combobox

setPlaceholder

public void setPlaceholder(String placeholder)

Description copied from class: GeneratedVaadinComboBox

Description copied from corresponding location in WebComponent:

A placeholder string in addition to the label.

Overrides:

setPlaceholder in class GeneratedVaadinComboBox<ComboBox<T>,T>

Parameters:

placeholder - the String value to set

getPlaceholder

public String getPlaceholder()

Gets the placeholder of the combobox.

Returns:

the placeholder property of the combobox

setPattern

public void setPattern(String pattern)

Description copied from class: GeneratedVaadinComboBox

Description copied from corresponding location in WebComponent:

A pattern to validate the input with.

Overrides:

setPattern in class GeneratedVaadinComboBox<ComboBox<T>,T>

Parameters:

pattern - the String value to set

getPattern

public String getPattern()

Gets the valid input pattern

Returns:

the pattern property of the combobox

getEmptyValue

public T getEmptyValue()

Description copied from interface: HasValue

Returns the value that represents an empty value.

By default HasValue is expected to support null as empty values. Specific implementations might not support this.

Specified by:

getEmptyValue in interface HasValue<AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>,T>

Overrides:

getEmptyValue in class AbstractField<ComboBox<T>,T>

Returns:

empty value

addCustomValueSetListener

public Registration addCustomValueSetListener(ComponentEventListener<GeneratedVaadinComboBox.CustomValueSetEvent<ComboBox<T>>> listener)

Adds a listener for the event which is fired when user inputs a string value that does not match any existing items and commits it eg. by blurring or pressing the enter-key.

Note that ComboBox doesn't do anything with the custom value string automatically. Use this method to determine how the custom value should be handled. For example, when the ComboBox has String as the value type, you can add a listener which sets the custom string as the value of the ComboBox with setValue(Object).

As a side effect, this makes the ComboBox allow custom values. If you want to disable the firing of custom value set events once the listener is added, please disable it explicitly via the setAllowCustomValue(boolean) method.

The custom value becomes disallowed automatically once the last custom value set listener is removed.

Overrides:

addCustomValueSetListener in class GeneratedVaadinComboBox<ComboBox<T>,T>

Parameters:

listener - the listener to be notified when a new value is filled

Returns:

a Registration for removing the event listener

See Also:

setAllowCustomValue(boolean)

setRequiredIndicatorVisible

public void setRequiredIndicatorVisible(boolean requiredIndicatorVisible)

Description copied from interface: HasValue

Sets the required indicator visible or not.

If set visible, it is visually indicated in the user interface.

The method is intended to be used with Binder which does server-side validation. In case HTML element has its own (client-side) validation it should be disabled when setRequiredIndicatorVisible(true) is called and re-enabled back on setRequiredIndicatorVisible(false). It's responsibility of each component implementation to follow the contract so that the method call doesn't do anything else than show/hide the "required" indication. Usually components provide their own setRequired method which should be called in case the client-side validation is required.

Specified by:

setRequiredIndicatorVisible in interface HasValue<AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>,T>

Specified by:

setRequiredIndicatorVisible in interface HasValueAndElement<AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>,T>

Parameters:

requiredIndicatorVisible - true to make the required indicator visible, false if not

setClearButtonVisible

public void setClearButtonVisible(boolean clearButtonVisible)

Allows displaying a clear button in the combo box when a value is selected.

The clear button is an icon, which can be clicked to set the combo box value to null.

Overrides:

setClearButtonVisible in class GeneratedVaadinComboBox<ComboBox<T>,T>

Parameters:

clearButtonVisible - true to display the clear button, false to hide it

isClearButtonVisible

public boolean isClearButtonVisible()

Gets whether this combo box displays a clear button when a value is selected.

Returns:

true if this combo box displays a clear button, false otherwise

See Also:

setClearButtonVisible(boolean)

setItems

public ComboBoxLazyDataView<T> setItems(CallbackDataProvider.FetchCallback<T,String> fetchCallback)

Supply items lazily with a callback from a backend. The ComboBox will automatically fetch more items and adjust its size until the backend runs out of items. Usage example without component provided filter:

comboBox.setItems(query -> orderService.getOrders(query.getOffset(), query.getLimit());

Since ComboBox supports filtering, it can be fetched via query.getFilter():

comboBox.setItems(query -> orderService.getOrders(query.getFilter(), query.getOffset(), query.getLimit());

The returned data view object can be used for further configuration, or later on fetched with getLazyDataView(). For using in-memory data, like Collection, use HasListDataView.setItems(Collection) instead.

If item filtering by some value type other than String is preferred and backend service is able to fetch and filter items by such type, converter for client side's filter string can be set along with fetch callback. See: setItemsWithFilterConverter(CallbackDataProvider.FetchCallback, SerializableFunction)

Specified by:

setItems in interface HasLazyDataView<T,String,ComboBoxLazyDataView<T>>

Parameters:

fetchCallback - function that returns a stream of items from the backend based on the offset, limit and an optional filter provided by the query object

Returns:

ComboBoxLazyDataView instance for further configuration

setItems

public ComboBoxLazyDataView<T> setItems(CallbackDataProvider.FetchCallback<T,String> fetchCallback,
                                        CallbackDataProvider.CountCallback<T,String> countCallback)

Supply items lazily with callbacks: the first one fetches the items based on offset, limit and an optional filter, the second provides the exact count of items in the backend. Use this only in case getting the count is cheap and the user benefits from the ComboBox showing immediately the exact size. Usage example without component provided filter:

comboBox.setItems( query -> orderService.getOrders(query.getOffset, query.getLimit()), query -> orderService.getSize());

Since ComboBox supports filtering, it can be fetched via query.getFilter():

comboBox.setItems( query -> orderService.getOrders(query.getFilter(), query.getOffset, query.getLimit()), query -> orderService.getSize(query.getFilter()));

The returned data view object can be used for further configuration, or later on fetched with getLazyDataView(). For using in-memory data, like Collection, use HasListDataView.setItems(Collection) instead.

If item filtering by some value type other than String is preferred and backend service is able to fetch and filter items by such type, converter for client side's filter string can be set along with fetch callback. See: setItemsWithFilterConverter(CallbackDataProvider.FetchCallback, CallbackDataProvider.CountCallback, SerializableFunction)

Specified by:

setItems in interface HasLazyDataView<T,String,ComboBoxLazyDataView<T>>

Parameters:

fetchCallback - function that returns a stream of items from the back end for a query

countCallback - function that return the number of items in the back end for a query

Returns:

ComboBoxLazyDataView instance for further configuration