Package com.vaadin.ui

Class ComboBox<T>

    • Constructor Detail

      • ComboBox

        public ComboBox​(String caption,
                Collection<T> options)
        Constructs a combo box with a static in-memory data provider with the given options.
        Parameters:
        caption - the caption to show in the containing layout, null for no caption
        options - collection of options, not null

      • ComboBox

        protected ComboBox​(DataCommunicator<T> dataCommunicator)
        Constructs and initializes an empty combo box.
        Parameters:
        dataCommunicator - the data comnunicator to use with this ComboBox
        Since:
        8.5

    • Method Detail

      • setItems

        public void setItems​(Collection<T> items)
        Sets the data items of this component provided as a collection.

        The provided items are wrapped into a ListDataProvider and this instance is used as a data provider for the HasDataProvider.setDataProvider(DataProvider) method. It means that the items collection can be accessed later on via ListDataProvider.getItems(): 

         
 HasDataProvider<String> listing = new CheckBoxGroup<>();
 listing.setItems(Arrays.asList("a","b"));
 ...

 Collection<String> collection = ((ListDataProvider<String>)listing.getDataProvider()).getItems();

        The provided collection instance may be used as-is. Subsequent modification of the collection might cause inconsistent data to be shown in the component unless it is explicitly instructed to read the data again.

        Filtering will use a case insensitive match to show all items where the filter text is a substring of the caption displayed for that item.

        Specified by:
        setItems in interface HasItems<T>
        Parameters:
        items - the data items to display, not null

      • setItems

        public void setItems​(Stream<T> streamOfItems)
        Sets the data items of this listing provided as a stream.

        This is just a shorthand for HasItems.setItems(Collection), that collects objects in the stream to a list. Thus, using this method, instead of its array and Collection variations, doesn't save any memory. If you have a large data set to bind, using a lazy data provider is recommended. See BackEndDataProvider for more info.

        The provided items are wrapped into a ListDataProvider and this instance is used as a data provider for the HasDataProvider.setDataProvider(DataProvider) method. It means that the items collection can be accessed later on via ListDataProvider.getItems(): 

         
 HasDataProvider<String> listing = new CheckBoxGroup<>();
 listing.setItems(Stream.of("a","b"));
 ...

 Collection<String> collection = ((ListDataProvider<String>)listing.getDataProvider()).getItems();

        Filtering will use a case insensitive match to show all items where the filter text is a substring of the caption displayed for that item.

        Specified by:
        setItems in interface HasItems<T>
        Parameters:
        streamOfItems - the stream of data items to display, not null
        See Also:
        HasItems.setItems(Collection)

      • setItems

        public void setItems​(T... items)
        Sets the data items of this listing.

        The provided items are wrapped into a ListDataProvider and this instance is used as a data provider for the HasDataProvider.setDataProvider(DataProvider) method. It means that the items collection can be accessed later on via ListDataProvider.getItems(): 

         
 HasDataProvider<String> listing = new CheckBoxGroup<>();
 listing.setItems("a","b");
 ...

 Collection<String> collection = ((ListDataProvider<String>)listing.getDataProvider()).getItems();

        Filtering will use a case insensitive match to show all items where the filter text is a substring of the caption displayed for that item.

        Specified by:
        setItems in interface HasItems<T>
        Parameters:
        items - the data items to display
        See Also:
        HasItems.setItems(Collection)

      • setDataProvider

        public void setDataProvider​(ListDataProvider<T> listDataProvider)
        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 caption displayed for that item.

        Note that this is a shorthand that calls HasFilterableDataProvider.setDataProvider(DataProvider) with a wrapper of the provided list data provider. This means that getDataProvider() will return the wrapper instead of the original list data provider.

        Parameters:
        listDataProvider - the list data provider to use, not null
        Since:
        8.0

      • setItems

        public void setItems​(ComboBox.CaptionFilter captionFilter,
                     Collection<T> items)
        Sets the data items of this listing and a simple string filter with which the item string and the text the user has input are compared.

        Note that unlike setItems(Collection), no automatic case conversion is performed before the comparison.

        Parameters:
        captionFilter - filter to check if an item is shown when user typed some text into the ComboBox
        items - the data items to display
        Since:
        8.0

      • setDataProvider

        public void setDataProvider​(ComboBox.CaptionFilter captionFilter,
                            ListDataProvider<T> listDataProvider)
        Sets a list data provider with an item caption filter as the data provider of this combo box. The caption filter is used to compare the displayed caption of each item to the filter text entered by the user.
        Parameters:
        captionFilter - 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
        Since:
        8.0

      • setItems

        public void setItems​(ComboBox.CaptionFilter captionFilter,
                     T... items)
        Sets the data items of this listing and a simple string filter with which the item string and the text the user has input are compared.

        Note that unlike setItems(Collection), no automatic case conversion is performed before the comparison.

        Parameters:
        captionFilter - filter to check if an item is shown when user typed some text into the ComboBox
        items - the data items to display
        Since:
        8.0

      • getPlaceholder

        public String getPlaceholder()
        Gets the current placeholder text shown when the combo box would be empty.
        Returns:
        the current placeholder string, or null if not enabled
        Since:
        8.0
        See Also:
        setPlaceholder(String)

      • setPlaceholder

        public void setPlaceholder​(String placeholder)
        Sets the placeholder string - a textual prompt that is displayed when the select would otherwise be empty, to prompt the user for input.
        Parameters:
        placeholder - the desired placeholder, or null to disable
        Since:
        8.0

      • setTextInputAllowed

        public void setTextInputAllowed​(boolean textInputAllowed)
        Sets whether it is possible to input text into the field or whether the field area of the component is just used to show what is selected. By disabling text input, the comboBox will work in the same way as a NativeSelect
        Parameters:
        textInputAllowed - true to allow entering text, false to just show the current selection
        See Also:
        isTextInputAllowed()

      • isTextInputAllowed

        public boolean isTextInputAllowed()
        Returns true if the user can enter text into the field to either filter the selections or enter a new value if new item provider or handler is set (see setNewItemProvider(NewItemProvider) (recommended) and setNewItemHandler(NewItemHandler) (deprecated)). If text input is disabled, the comboBox will work in the same way as a NativeSelect
        Returns:
        true if text input is allowed

      • getPageLength

        public int getPageLength()
        Returns the page length of the suggestion popup.
        Returns:
        the pageLength

      • getPopupWidth

        public String getPopupWidth()
        Returns the suggestion pop-up's width as a CSS string. By default this width is set to "100%".
        Returns:
        explicitly set popup width as CSS size string or null if not set
        Since:
        7.7
        See Also:
        setPopupWidth(java.lang.String)

      • setPageLength

        public void setPageLength​(int pageLength)
        Sets the page length for the suggestion popup. Setting the page length to 0 will disable suggestion popup paging (all items visible).
        Parameters:
        pageLength - the pageLength to set

      • isEmptySelectionAllowed

        public boolean isEmptySelectionAllowed()
        Returns whether the user is allowed to select nothing in the combo box.
        Returns:
        true if empty selection is allowed, false otherwise
        Since:
        8.0

      • setEmptySelectionAllowed

        public void setEmptySelectionAllowed​(boolean emptySelectionAllowed)
        Sets whether the user is allowed to select nothing in the combo box. When true, a special empty item is shown to the user.
        Parameters:
        emptySelectionAllowed - true to allow not selecting anything, false to require selection
        Since:
        8.0

      • setEmptySelectionCaption

        public void setEmptySelectionCaption​(String caption)
        Sets the empty selection caption.

        The empty string "" is the default empty selection caption.

        If empty selection is allowed via the setEmptySelectionAllowed(boolean) method (it is by default) then the empty item will be shown with the given caption.

        Parameters:
        caption - the caption to set, not null
        Since:
        8.0
        See Also:
        AbstractSingleSelect.isSelected(Object)

      • setPopupWidth

        public void setPopupWidth​(String width)
        Sets the suggestion pop-up's width as a CSS string. By using relative units (e.g. "50%") it's possible to set the popup's width relative to the ComboBox itself.

        By default this width is set to "100%" so that the pop-up's width is equal to the width of the combobox. By setting width to null the pop-up's width will automatically expand beyond 100% relative width to fit the content of all displayed items.

        Parameters:
        width - the width
        Since:
        7.7
        See Also:
        getPopupWidth()

      • setScrollToSelectedItem

        public void setScrollToSelectedItem​(boolean scrollToSelectedItem)
        Sets whether to scroll the selected item visible (directly open the page on which it is) when opening the combo box popup or not.

        This requires finding the index of the item, which can be expensive in many large lazy loading containers.

        Parameters:
        scrollToSelectedItem - true to find the page with the selected item when opening the selection popup

      • isScrollToSelectedItem

        public boolean isScrollToSelectedItem()
        Returns true if the select should find the page with the selected item when opening the popup.
        Returns:
        true if the page with the selected item will be shown when opening the popup
        See Also:
        setScrollToSelectedItem(boolean)

      • setStyleGenerator

        public void setStyleGenerator​(StyleGenerator<T> itemStyleGenerator)
        Sets the style generator that is used to produce custom class names for items visible in the popup. The CSS class name that will be added to the item is v-filterselect-item-[style name]. Returning null from the generator results in no custom style name being set.
        Parameters:
        itemStyleGenerator - the item style generator to set, not null
        Throws:
        NullPointerException - if itemStyleGenerator is null
        Since:
        8.0
        See Also:
        StyleGenerator

      • getStyleGenerator

        public StyleGenerator<T> getStyleGenerator()
        Gets the currently used style generator that is used to generate CSS class names for items. The default item style provider returns null for all items, resulting in no custom item class names being set.
        Returns:
        the currently used item style generator, not null
        Since:
        8.0
        See Also:
        StyleGenerator, setStyleGenerator(StyleGenerator)

      • setItemIconGenerator

        public void setItemIconGenerator​(IconGenerator<T> itemIconGenerator)
        Description copied from class: AbstractListing
        Sets the item icon generator that is used to produce custom icons for shown items. The generator can return null for items with no icon.

        Implementations that support item icons make this method public.

        Overrides:
        setItemIconGenerator in class AbstractListing<T>
        Parameters:
        itemIconGenerator - the item icon generator to set, not null
        See Also:
        IconGenerator

      • setNewItemHandler

        @Deprecated
public void setNewItemHandler​(ComboBox.NewItemHandler newItemHandler)
        Deprecated.
        Since 8.4 use setNewItemProvider(NewItemProvider) instead.
        Sets the handler that is called when user types a new item. The creation of new items is allowed when a new item handler has been set. If new item provider is also set, the new item handler is ignored.
        Parameters:
        newItemHandler - handler called for new items, null to only permit the selection of existing items, all options ignored if new item provider is set
        Since:
        8.0

      • setNewItemProvider

        public void setNewItemProvider​(ComboBox.NewItemProvider<T> newItemProvider)
        Sets the provider function that is called when user types a new item. The creation of new items is allowed when a new item provider has been set. If a deprecated new item handler is also set it is ignored in favor of new item provider.
        Parameters:
        newItemProvider - provider function that is called for new items, null to only permit the selection of existing items or to use a deprecated new item handler if set
        Since:
        8.4

      • getNewItemHandler

        @Deprecated
public ComboBox.NewItemHandler getNewItemHandler()
        Deprecated.
        Since 8.4 use getNewItemProvider() instead.
        Returns the handler called when the user enters a new item (not present in the data provider).
        Returns:
        new item handler or null if none specified

      • getNewItemProvider

        public ComboBox.NewItemProvider<T> getNewItemProvider()
        Returns the provider function that is called when the user enters a new item (not present in the data provider).
        Returns:
        new item provider or null if none specified
        Since:
        8.4

      • getState

        protected ComboBoxState getState()
        Description copied from class: AbstractComponent
        Returns the shared state bean with information to be sent from the server to the client. Subclasses should override this method and set any relevant fields of the state returned by super.getState().
        Overrides:
        getState in class AbstractSingleSelect<T>
        Returns:
        updated component shared state

      • updateSelectedItemState

        protected void updateSelectedItemState​(T value)
        Description copied from class: AbstractSingleSelect
        This method updates the shared selection state of the AbstractSingleSelect.
        Overrides:
        updateSelectedItemState in class AbstractSingleSelect<T>
        Parameters:
        value - the value that is selected; may be null

      • writeItem

        protected org.jsoup.nodes.Element writeItem​(org.jsoup.nodes.Element design,
                                            T item,
                                            DesignContext context)
        Description copied from class: AbstractListing
        Writes a data source Item to a design. Hierarchical select components should override this method to recursively write any child items as well.
        Overrides:
        writeItem in class AbstractSingleSelect<T>
        Parameters:
        design - the element into which to insert the item
        item - the item to write
        context - the DesignContext instance used in writing
        Returns:
        a JSOUP element representing the item

      • readItems

        protected void readItems​(org.jsoup.nodes.Element design,
                         DesignContext context)
        Description copied from class: AbstractListing
        Reads the data source items from the design.
        Overrides:
        readItems in class AbstractSingleSelect<T>
        Parameters:
        design - The element to obtain the state from
        context - The DesignContext instance used for parsing the design

      • readItem

        protected T readItem​(org.jsoup.nodes.Element child,
                     Set<T> selected,
                     DesignContext context)
        Description copied from class: AbstractSingleSelect
        Reads an Item from a design and inserts it into the data source. Hierarchical select components should override this method to recursively recursively read any child items as well.
        Overrides:
        readItem in class AbstractSingleSelect<T>
        Parameters:
        child - a child element representing the item
        selected - A set accumulating selected items. If the item that is read is marked as selected, its item id should be added to this set.
        context - the DesignContext instance used in parsing
        Returns:
        the item id of the new item

      • getDataProvider

        public DataProvider<T,​?> getDataProvider()
        Description copied from interface: HasItems
        Returns the source of data items used by this listing.
        Specified by:
        getDataProvider in interface HasItems<T>
        Returns:
        the data provider, not null

      • setDataProvider

        public <C> void setDataProvider​(DataProvider<T,​C> dataProvider,
                                SerializableFunction<String,​C> filterConverter)
        Description copied from interface: HasFilterableDataProvider
        Sets the data provider and filter converter for this listing. The data provider is queried for displayed items as needed.
        Specified by:
        setDataProvider in interface HasFilterableDataProvider<T,​String>
        Type Parameters:
        C - filter type
        Parameters:
        dataProvider - the data provider, not null
        filterConverter - a function that converts filter values produced by this listing into filter values expected by the provided data provider, not null