Package com.vaadin.flow.component.combobox

Class ComboBoxBase<TComponent extends ComboBoxBase<TComponent,​TItem,​TValue>,​TItem,​TValue>

    • Constructor Detail

      • ComboBoxBase

        public ComboBoxBase​(String valuePropertyName,
                    TValue defaultValue,
                    Class<TValueProperty> valuePropertyType,
                    SerializableBiFunction<TComponent,​TValueProperty,​TValue> presentationToModel,
                    SerializableBiFunction<TComponent,​TValue,​TValueProperty> modelToPresentation)
        Constructs a new ComboBoxBase instance
        Type Parameters:
        TValueProperty - the type of the raw value of the Flow element property
        Parameters:
        valuePropertyName - name of the value property of the web component that should be used to set values, or listen to value changes
        defaultValue - the default value of the component
        valuePropertyType - the class that represents the type of the raw value of the Flow element property
        presentationToModel - a function to convert a raw property value into a value using the user-specified model type
        modelToPresentation - a function to convert a value using the user-specified model type into a raw property value

    • Method Detail

      • isAutofocus

        public boolean isAutofocus()
        Whether the component should automatically receive focus when the page loads.
        Returns:
        true if the component should automatically receive focus

      • setAutofocus

        public void setAutofocus​(boolean autofocus)
        Sets the whether the component should automatically receive focus when the page loads. Defaults to false.
        Parameters:
        autofocus - true component should automatically receive focus

      • 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)

      • 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

      • isOpened

        @Synchronize(property="opened",
             value="opened-changed")
public boolean isOpened()
        Whether the dropdown is opened or not.
        Returns:
        true if the drop-down is opened, false otherwise

      • setOpened

        public void setOpened​(boolean opened)
        Sets whether the dropdown should be opened or not.
        Parameters:
        opened - true to open the drop-down, false to close it

      • setAllowCustomValue

        public void setAllowCustomValue​(boolean allowCustomValue)
        Enables or disables the component firing events for custom string input.

        When enabled, a ComboBoxBase.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.

        Parameters:
        allowCustomValue - true to enable custom value set events, false to disable them
        See Also:
        addCustomValueSetListener(ComponentEventListener)

      • getFilter

        @Synchronize(property="filter",
             value="filter-changed")
protected String getFilter()
        Filtering string the user has typed into the input field.
        Returns:
        the filter string

      • setFilter

        protected void setFilter​(String filter)
        Sets the filter string for the filter input.

        Setter is only required to allow using @Synchronize

        Parameters:
        filter - the String value to set

      • isInvalid

        public boolean isInvalid()
        Whether the component has an invalid value or not.
        Specified by:
        isInvalid in interface HasValidation
        Returns:
        whether the component input is valid

      • setInvalid

        public void setInvalid​(boolean invalid)
        Sets whether the component has an invalid value or not.
        Specified by:
        setInvalid in interface HasValidation
        Parameters:
        invalid - new value for component input validity

      • isRequired

        public boolean isRequired()
        Sets whether the component requires a value to be considered in a valid state.
        Returns:
        true if the component requires a value to be valid

      • setRequired

        public void setRequired​(boolean required)
        Whether the component requires a value to be considered in a valid state.
        Parameters:
        required - true if the component requires a value to be valid

      • getErrorMessage

        public String getErrorMessage()
        The error message that should be displayed when the component becomes invalid
        Specified by:
        getErrorMessage in interface HasValidation
        Returns:
        current error message

      • setErrorMessage

        public void setErrorMessage​(String errorMessage)
        Sets the error message that should be displayed when the component becomes invalid
        Specified by:
        setErrorMessage in interface HasValidation
        Parameters:
        errorMessage - a new error message

      • getPlaceholder

        public String getPlaceholder()
        The placeholder text that should be displayed in the input element, when the user has not entered a value
        Returns:
        the placeholder text

      • setPlaceholder

        public void setPlaceholder​(String placeholder)
        Sets the placeholder text that should be displayed in the input element, when the user has not entered a value
        Parameters:
        placeholder - the placeholder text

      • isAutoOpen

        public boolean isAutoOpen()
        Gets whether dropdown will open automatically or not.
        Returns:
        true if enabled, false otherwise

      • 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

      • 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<TComponent extends ComboBoxBase<TComponent,​TItem,​TValue>,​TItem>
        Specified by:
        setRequiredIndicatorVisible in interface HasValueAndElement<TComponent extends ComboBoxBase<TComponent,​TItem,​TValue>,​TItem>
        Parameters:
        requiredIndicatorVisible - true to make the required indicator visible, false if not

      • setItemLabelGenerator

        public void setItemLabelGenerator​(ItemLabelGenerator<TItem> 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<TItem> 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

      • generateLabel

        protected String generateLabel​(TItem item)
        Generates a string label for a data item using the current item label generator
        Parameters:
        item - the data item
        Returns:
        string label for the data item

      • setRenderer

        public void setRenderer​(Renderer<TItem> renderer)
        Sets the Renderer 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).

      • 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

      • addCustomValueSetListener

        public Registration addCustomValueSetListener​(ComponentEventListener<ComboBoxBase.CustomValueSetEvent<TComponent>> 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.

        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)

      • setItems

        public ComboBoxListDataView<TItem> setItems​(Collection<TItem> 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<TComponent extends ComboBoxBase<TComponent,​TItem,​TValue>,​TItem>
        Parameters:
        items - the items to display, not null
        Returns:
        ListDataView providing access to the items

      • setItems

        public ComboBoxListDataView<TItem> setItems​(ComboBox.ItemFilter<TItem> itemFilter,
                                            Collection<TItem> 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<TItem> setItems​(ComboBox.ItemFilter<TItem> itemFilter,
                                            TItem... 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<TItem> setItems​(ComboBox.ItemFilter<TItem> itemFilter,
                                            ListDataProvider<TItem> 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

      • setItemsWithFilterConverter

        public <C> ComboBoxLazyDataView<TItem> setItemsWithFilterConverter​(CallbackDataProvider.FetchCallback<TItem,​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<TItem> setItemsWithFilterConverter​(CallbackDataProvider.FetchCallback<TItem,​C> fetchCallback,
                                                                   CallbackDataProvider.CountCallback<TItem,​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
        countCallback - function that return the number of items in the back end for a query
        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

      • setItems

        public ComboBoxLazyDataView<TItem> setItems​(CallbackDataProvider.FetchCallback<TItem,​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<TComponent extends ComboBoxBase<TComponent,​TItem,​TValue>,​TItem,​TValue>
        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 ComboBoxDataView<TItem> setItems​(InMemoryDataProvider<TItem> inMemoryDataProvider,
                                        SerializableFunction<String,​SerializablePredicate<TItem>> 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

      • getDataProvider

        public DataProvider<TItem,​?> getDataProvider()
        Gets the data provider used by this ComboBox.
        Returns:
        the data provider used by this ComboBox

      • setDataProvider

        @Deprecated
public <C> void setDataProvider​(DataProvider<TItem,​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.

      • setDataProvider

        @Deprecated
public void setDataProvider​(ListDataProvider<TItem> 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.ItemFilter<TItem> itemFilter,
                            ListDataProvider<TItem> listDataProvider)
        Deprecated.
        use instead setItems(ComboBox.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

      • isSelected

        protected abstract boolean isSelected​(TItem item)
        Whether the item is currently selected in the combo box.
        Parameters:
        item - the item to check
        Returns:
        true if the item is selected, false otherwise

      • refreshValue

        protected abstract void refreshValue()
        Refresh value / selection of the web component after changes that might affect the presentation / rendering of items

      • getRenderManager

        protected com.vaadin.flow.component.combobox.ComboBoxRenderManager<TItem> getRenderManager()
        Accesses the render manager that is managing the custom renderer
        Returns:
        the render manager

      • getDataController

        protected com.vaadin.flow.component.combobox.ComboBoxDataController<TItem> getDataController()
        Accesses the data controller that is managing data communication with the web component

        Can be null if the constructor has not run yet

        Returns:
        the data controller

      • getDataCommunicator

        protected ComboBoxDataCommunicator<TItem> getDataCommunicator()
        Accesses the data communicator that is managed by the data controller

        Can be null if the no data source has been set yet, or if the constructor has not run yet

        Returns:
        the data communicator

      • getDataGenerator

        protected CompositeDataGenerator<TItem> getDataGenerator()
        Accesses the data generator that is managed by the data controller

        Can be null if the constructor has not run yet

        Returns:
        the data generator

      • getKeyMapper

        protected DataKeyMapper<TItem> getKeyMapper()
        Accesses the key mapper that is managed by the data controller

        Can be null if the no data source has been set yet, or if the constructor has not run yet

        Returns:
        the key mapper

      • runBeforeClientResponse

        protected void runBeforeClientResponse​(SerializableConsumer<UI> command)
        Helper for running a command in the before client response hook
        Parameters:
        command - the command to execute

      • validate

        protected void validate()