Package com.vaadin.client.ui

Class VComboBox

  • All Implemented Interfaces:
    com.google.gwt.event.dom.client.BlurHandler, com.google.gwt.event.dom.client.ClickHandler, com.google.gwt.event.dom.client.FocusHandler, com.google.gwt.event.dom.client.KeyDownHandler, com.google.gwt.event.dom.client.KeyUpHandler, com.google.gwt.event.dom.client.MouseDownHandler, com.google.gwt.event.logical.shared.HasAttachHandlers, com.google.gwt.event.shared.EventHandler, com.google.gwt.event.shared.HasHandlers, com.google.gwt.user.client.EventListener, com.google.gwt.user.client.ui.HasVisibility, com.google.gwt.user.client.ui.IsRenderable, com.google.gwt.user.client.ui.IsWidget, DeferredWorker, Focusable, HandlesAriaCaption, HandlesAriaInvalid, HandlesAriaRequired, Field, SubPartAware
    public class VComboBox
extends com.google.gwt.user.client.ui.Composite
implements Field, com.google.gwt.event.dom.client.KeyDownHandler, com.google.gwt.event.dom.client.KeyUpHandler, com.google.gwt.event.dom.client.ClickHandler, com.google.gwt.event.dom.client.FocusHandler, com.google.gwt.event.dom.client.BlurHandler, Focusable, SubPartAware, HandlesAriaCaption, HandlesAriaInvalid, HandlesAriaRequired, DeferredWorker, com.google.gwt.event.dom.client.MouseDownHandler
    Client side implementation of the ComboBox component. TODO needs major refactoring (to be extensible etc)
    Since:
    8.0

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      class  VComboBox.ComboBoxSuggestion
      Represents a suggestion in the suggestion popup box.
      class  VComboBox.DataReceivedHandler
      Handler receiving notifications from the connector and updating the widget state accordingly.
      class  VComboBox.FilterSelectTextBox
      TextBox variant used as input element for filter selects, which prevents selecting text when disabled.
      class  VComboBox.SuggestionMenu
      The menu where the suggestions are rendered.
      class  VComboBox.SuggestionPopup
      Represents the popup box with the selection options.

      • Nested classes/interfaces inherited from class com.google.gwt.user.client.ui.UIObject

        com.google.gwt.user.client.ui.UIObject.DebugIdImpl, com.google.gwt.user.client.ui.UIObject.DebugIdImplEnabled

    • Constructor Summary

      Constructors 
      Constructor Description
      VComboBox()
      Default constructor.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void bindAriaCaption​(com.google.gwt.user.client.Element captionElement)
      Called to bind the provided caption (label in HTML speak) element to the main input element of the Widget.
      protected VComboBox.SuggestionPopup createSuggestionPopup()
      This method will create the SuggestionPopup used by the VComboBox instance.
      protected com.google.gwt.user.client.ui.TextBox createTextBox()
      This method will create the TextBox used by the VComboBox instance.
      void filterOptions​(int page)
      Filters the options at a certain page.
      void filterOptions​(int page, String filter)
      Filters the options at certain page using the given filter.
      void focus()
      Sets focus to this widget.
      VComboBox.DataReceivedHandler getDataReceivedHandler()
      Returns a handler receiving notifications from the connector about communications.
      String getEmptySelectionCaption()
      Gets the empty selection caption.
      boolean getNullSelectionItemShouldBeVisible()
      Returns null selection item should be visible or not.
      String getSelectedCaption()
      This method is meant for internal use and may change in future versions.
      com.google.gwt.user.client.Element getSubPartElement​(String subPart)
      Locates an element inside a component using the identifier provided in subPart.
      String getSubPartName​(com.google.gwt.user.client.Element subElement)
      Provides an identifier that identifies the element within the component.
      int getTotalSuggestions()
      Gets the total number of suggestions, excluding the null selection item.
      boolean hasNextPage()
      Does the Select have more pages?
      boolean isWorkPending()
      Checks whether there are operations pending for this widget or connector that must be executed before reaching a steady state.
      int minWidth​(String captions)
      Calculate minimum width for FilterSelect textarea.
      void onBlur​(com.google.gwt.event.dom.client.BlurEvent event)  
      void onBrowserEvent​(com.google.gwt.user.client.Event event)  
      void onClick​(com.google.gwt.event.dom.client.ClickEvent event)
      Listener for popupopener.
      protected void onDetach()  
      void onFocus​(com.google.gwt.event.dom.client.FocusEvent event)  
      void onKeyDown​(com.google.gwt.event.dom.client.KeyDownEvent event)  
      void onKeyUp​(com.google.gwt.event.dom.client.KeyUpEvent event)
      Triggered when a key was depressed.
      void onMouseDown​(com.google.gwt.event.dom.client.MouseDownEvent event)  
      void onNullSelected()
      Triggered when an empty value is selected and null selection is allowed.
      void onSuggestionSelected​(VComboBox.ComboBoxSuggestion suggestion)
      Triggered when a suggestion is selected.
      void resetLastNewItemString()
      This method will reset the saved item string which is added last time.
      void setAllowNewItems​(boolean allowNewItems)
      Sets whether creation of new items when there is no match is allowed or not.
      void setAriaInvalid​(boolean invalid)
      Called to set the element, typically an input element, as invalid.
      void setAriaRequired​(boolean required)
      Called to set the element, typically an input element, as required.
      void setEmptySelectionCaption​(String emptySelectionCaption)
      Sets the empty selection caption for this VComboBox.
      void setPageLength​(int pageLength)
      Sets the number of items to show per page, or 0 for showing all items.
      void setPlaceholder​(String placeholder)
      Set or reset the placeholder attribute for the text field.
      void setSelectedCaption​(String selectedCaption)
      Sets the caption of selected item, if "scroll to page" is disabled.
      void setSelectedItemIcon​(String iconUri)
      Sets the icon URI of the selected item.
      void setStyleName​(String style)  
      void setStylePrimaryName​(String style)  
      void setSuggestionPopupWidth​(String suggestionPopupWidth)
      Sets the suggestion pop-up's width as a CSS string.
      void setText​(String text)
      Sets the text in the text box.
      void setTextInputAllowed​(boolean textInputAllowed)  
      void setTotalSuggestions​(int totalSuggestions)
      Sets the total number of suggestions.
      void setWidth​(String width)  
      void updatePlaceholder()
      Update placeholder visibility (hidden when read-only or disabled).
      void updateReadOnly()
      For internal use only.
      void updateRootWidth()
      Calculates the width of the select if the select has undefined width.
      protected void updateStyleNames()  
      void updateSuggestionPopupMinWidth()
      Update minimum width for combo box textarea based on input prompt and suggestions.

      • Methods inherited from class com.google.gwt.user.client.ui.Composite

        claimElement, getWidget, initializeClaimedElement, initWidget, isAttached, onAttach, render, render, resolvePotentialElement, setWidget

      • Methods inherited from class com.google.gwt.user.client.ui.Widget

        addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, createHandlerManager, delegateEvent, doAttachChildren, doDetachChildren, fireEvent, getHandlerCount, getLayoutData, getParent, isOrWasAttached, onLoad, onUnload, removeFromParent, setLayoutData, sinkEvents, unsinkEvents

      • Methods inherited from class com.google.gwt.user.client.ui.UIObject

        addStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getElement, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, onEnsureDebugId, removeStyleDependentName, removeStyleName, setElement, setElement, setHeight, setPixelSize, setSize, setStyleDependentName, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setTitle, setVisible, setVisible, sinkBitlessEvent, toString

    • Field Detail

      • pageLength

        public int pageLength
        For internal use only. May be removed or replaced in the future.

      • tb

        public final com.google.gwt.user.client.ui.TextBox tb
        The text box where the filter is written

        For internal use only. May be removed or replaced in the future.

      • suggestionPopup

        public final VComboBox.SuggestionPopup suggestionPopup
        For internal use only. May be removed or replaced in the future.

      • connector

        public ComboBoxConnector connector
        For internal use only. May be removed or replaced in the future.

      • currentPage

        public int currentPage
        For internal use only. May be removed or replaced in the future.

      • currentSuggestions

        public final List<VComboBox.ComboBoxSuggestion> currentSuggestions
        A collection of available suggestions (options) as received from the server.

        For internal use only. May be removed or replaced in the future.

      • serverSelectedKey

        public String serverSelectedKey
        For internal use only. May be removed or replaced in the future.

      • selectedOptionKey

        public String selectedOptionKey
        For internal use only. May be removed or replaced in the future.

      • initDone

        public boolean initDone
        For internal use only. May be removed or replaced in the future.

      • lastFilter

        public String lastFilter
        For internal use only. May be removed or replaced in the future.

      • currentSuggestion

        public VComboBox.ComboBoxSuggestion currentSuggestion
        The current suggestion selected from the dropdown. This is one of the values in currentSuggestions except when filtering, in this case currentSuggestion might not be in currentSuggestions.

        For internal use only. May be removed or replaced in the future.

      • allowNewItems

        public boolean allowNewItems
        For internal use only. May be removed or replaced in the future.

      • nullSelectionAllowed

        public boolean nullSelectionAllowed
        For internal use only. May be removed or replaced in the future.

      • nullSelectItem

        public boolean nullSelectItem
        For internal use only. May be removed or replaced in the future.

      • enabled

        public boolean enabled
        For internal use only. May be removed or replaced in the future.

      • readonly

        public boolean readonly
        For internal use only. May be removed or replaced in the future.

      • inputPrompt

        public String inputPrompt
        For internal use only. May be removed or replaced in the future.

      • suggestionPopupMinWidth

        public int suggestionPopupMinWidth
        For internal use only. May be removed or replaced in the future.

      • suggestionPopupWidth

        public String suggestionPopupWidth

      • lastNewItemString

        public String lastNewItemString
        Stores the last new item string to avoid double submissions. Cleared on uidl updates.

        For internal use only. May be removed or replaced in the future.

      • focused

        public boolean focused
        For internal use only. May be removed or replaced in the future.

      • noKeyDownEvents

        public boolean noKeyDownEvents
        For internal use only. May be removed or replaced in the future.

    • Constructor Detail

      • VComboBox

        public VComboBox()
        Default constructor.

    • Method Detail

      • resetLastNewItemString

        public void resetLastNewItemString()
        This method will reset the saved item string which is added last time.

      • onBrowserEvent

        public void onBrowserEvent​(com.google.gwt.user.client.Event event)
        Specified by:
        onBrowserEvent in interface com.google.gwt.user.client.EventListener
        Overrides:
        onBrowserEvent in class com.google.gwt.user.client.ui.Composite

      • createTextBox

        protected com.google.gwt.user.client.ui.TextBox createTextBox()
        This method will create the TextBox used by the VComboBox instance. It is invoked during the Constructor and should only be overridden if a custom TextBox shall be used. The overriding method cannot use any instance variables.
        Returns:
        TextBox instance used by this VComboBox
        Since:
        7.1.5

      • createSuggestionPopup

        protected VComboBox.SuggestionPopup createSuggestionPopup()
        This method will create the SuggestionPopup used by the VComboBox instance. It is invoked during the Constructor and should only be overridden if a custom SuggestionPopup shall be used. The overriding method cannot use any instance variables.
        Returns:
        SuggestionPopup instance used by this VComboBox
        Since:
        7.1.5

      • setStyleName

        public void setStyleName​(String style)
        Overrides:
        setStyleName in class com.google.gwt.user.client.ui.UIObject

      • setStylePrimaryName

        public void setStylePrimaryName​(String style)
        Overrides:
        setStylePrimaryName in class com.google.gwt.user.client.ui.UIObject

      • updateStyleNames

        protected void updateStyleNames()

      • hasNextPage

        public boolean hasNextPage()
        Does the Select have more pages?
        Returns:
        true if a next page exists, else false if the current page is the last page

      • filterOptions

        public void filterOptions​(int page)
        Filters the options at a certain page. Uses the text box input as a filter and ensures the popup is opened when filtering results are available.
        Parameters:
        page - The page which items are to be filtered

      • filterOptions

        public void filterOptions​(int page,
                          String filter)
        Filters the options at certain page using the given filter.
        Parameters:
        page - The page to filter
        filter - The filter to apply to the components

      • updateReadOnly

        public void updateReadOnly()
        For internal use only. May be removed or replaced in the future.

      • setTextInputAllowed

        public void setTextInputAllowed​(boolean textInputAllowed)

      • setText

        public void setText​(String text)
        Sets the text in the text box.
        Parameters:
        text - the text to set in the text box

      • setPlaceholder

        public void setPlaceholder​(String placeholder)
        Set or reset the placeholder attribute for the text field.
        Parameters:
        placeholder - new placeholder string or null for none

      • updatePlaceholder

        public void updatePlaceholder()
        Update placeholder visibility (hidden when read-only or disabled).

      • onSuggestionSelected

        public void onSuggestionSelected​(VComboBox.ComboBoxSuggestion suggestion)
        Triggered when a suggestion is selected.
        Parameters:
        suggestion - The suggestion that just got selected.

      • onNullSelected

        public void onNullSelected()
        Triggered when an empty value is selected and null selection is allowed.

      • setSelectedItemIcon

        public void setSelectedItemIcon​(String iconUri)
        Sets the icon URI of the selected item. The icon is shown on the left side of the item caption text. Set the URI to null to remove the icon.
        Parameters:
        iconUri - The URI of the icon, or null to remove icon

      • onKeyDown

        public void onKeyDown​(com.google.gwt.event.dom.client.KeyDownEvent event)
        Specified by:
        onKeyDown in interface com.google.gwt.event.dom.client.KeyDownHandler

      • onKeyUp

        public void onKeyUp​(com.google.gwt.event.dom.client.KeyUpEvent event)
        Triggered when a key was depressed.
        Specified by:
        onKeyUp in interface com.google.gwt.event.dom.client.KeyUpHandler
        Parameters:
        event - The KeyUpEvent of the key depressed

      • onClick

        public void onClick​(com.google.gwt.event.dom.client.ClickEvent event)
        Listener for popupopener.
        Specified by:
        onClick in interface com.google.gwt.event.dom.client.ClickHandler

      • updateSuggestionPopupMinWidth

        public void updateSuggestionPopupMinWidth()
        Update minimum width for combo box textarea based on input prompt and suggestions.

        For internal use only. May be removed or replaced in the future.

      • minWidth

        public int minWidth​(String captions)
        Calculate minimum width for FilterSelect textarea.

        For internal use only. May be removed or replaced in the future.

        Parameters:
        captions - pipe separated string listing all the captions to measure
        Returns:
        minimum width in pixels

      • onFocus

        public void onFocus​(com.google.gwt.event.dom.client.FocusEvent event)
        Specified by:
        onFocus in interface com.google.gwt.event.dom.client.FocusHandler

      • onBlur

        public void onBlur​(com.google.gwt.event.dom.client.BlurEvent event)
        Specified by:
        onBlur in interface com.google.gwt.event.dom.client.BlurHandler

      • focus

        public void focus()
        Description copied from interface: Focusable
        Sets focus to this widget.
        Specified by:
        focus in interface Focusable

      • updateRootWidth

        public void updateRootWidth()
        Calculates the width of the select if the select has undefined width. Should be called when the width changes or when the icon changes.

        For internal use only. May be removed or replaced in the future.

      • setWidth

        public void setWidth​(String width)
        Overrides:
        setWidth in class com.google.gwt.user.client.ui.UIObject

      • onMouseDown

        public void onMouseDown​(com.google.gwt.event.dom.client.MouseDownEvent event)
        Specified by:
        onMouseDown in interface com.google.gwt.event.dom.client.MouseDownHandler

      • onDetach

        protected void onDetach()
        Overrides:
        onDetach in class com.google.gwt.user.client.ui.Composite

      • getSubPartElement

        public com.google.gwt.user.client.Element getSubPartElement​(String subPart)
        Description copied from interface: SubPartAware
        Locates an element inside a component using the identifier provided in subPart. The subPart identifier is component specific and may be any string of characters, numbers, space characters and brackets.
        Specified by:
        getSubPartElement in interface SubPartAware
        Parameters:
        subPart - The identifier for the element inside the component
        Returns:
        The element identified by subPart or null if the element could not be found.

      • getSubPartName

        public String getSubPartName​(com.google.gwt.user.client.Element subElement)
        Description copied from interface: SubPartAware
        Provides an identifier that identifies the element within the component. The subElement is a part of the component and must never be null.

        Note! getSubPartElement(getSubPartName(element)) == element is not always true. A component can choose to provide a more generic identifier for any given element if the results of all interactions with subElement are the same as interactions with the element identified by the return value. For example a button can return an identifier for the root element even though a DIV inside the button was passed as subElement because interactions with the DIV and the root button element produce the same result.

        Specified by:
        getSubPartName in interface SubPartAware
        Parameters:
        subElement - The element the identifier string should uniquely identify
        Returns:
        An identifier that uniquely identifies subElement or null if no identifier could be provided.

      • setAriaRequired

        public void setAriaRequired​(boolean required)
        Description copied from interface: HandlesAriaRequired
        Called to set the element, typically an input element, as required.
        Specified by:
        setAriaRequired in interface HandlesAriaRequired
        Parameters:
        required - boolean true when the element needs to be set as required

      • setAriaInvalid

        public void setAriaInvalid​(boolean invalid)
        Description copied from interface: HandlesAriaInvalid
        Called to set the element, typically an input element, as invalid.
        Specified by:
        setAriaInvalid in interface HandlesAriaInvalid
        Parameters:
        invalid - boolean, true when the element should be marked invalid, false otherwise

      • bindAriaCaption

        public void bindAriaCaption​(com.google.gwt.user.client.Element captionElement)
        Description copied from interface: HandlesAriaCaption
        Called to bind the provided caption (label in HTML speak) element to the main input element of the Widget. Binding should be removed from the main input field when captionElement is null.
        Specified by:
        bindAriaCaption in interface HandlesAriaCaption
        Parameters:
        captionElement - Element of the caption

      • isWorkPending

        public boolean isWorkPending()
        Description copied from interface: DeferredWorker
        Checks whether there are operations pending for this widget or connector that must be executed before reaching a steady state.
        Specified by:
        isWorkPending in interface DeferredWorker

      • setSelectedCaption

        public void setSelectedCaption​(String selectedCaption)
        Sets the caption of selected item, if "scroll to page" is disabled. This method is meant for internal use and may change in future versions.
        Parameters:
        selectedCaption - the caption of selected item
        Since:
        7.7

      • getSelectedCaption

        public String getSelectedCaption()
        This method is meant for internal use and may change in future versions.
        Returns:
        the caption of selected item, if "scroll to page" is disabled
        Since:
        7.7

      • getDataReceivedHandler

        public VComboBox.DataReceivedHandler getDataReceivedHandler()
        Returns a handler receiving notifications from the connector about communications.
        Returns:
        the dataReceivedHandler

      • setPageLength

        public void setPageLength​(int pageLength)
        Sets the number of items to show per page, or 0 for showing all items.
        Parameters:
        pageLength - new page length or 0 for all items

      • setSuggestionPopupWidth

        public void setSuggestionPopupWidth​(String suggestionPopupWidth)
        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.
        Parameters:
        suggestionPopupWidth - new popup width as CSS string, null for old default width calculation based on items

      • setAllowNewItems

        public void setAllowNewItems​(boolean allowNewItems)
        Sets whether creation of new items when there is no match is allowed or not.
        Parameters:
        allowNewItems - true to allow creation of new items, false to only allow selection of existing items

      • setTotalSuggestions

        public void setTotalSuggestions​(int totalSuggestions)
        Sets the total number of suggestions.

        NOTE: this excluded the possible null selection item!

        NOTE: this just updates the state, but doesn't update any UI.

        Parameters:
        totalSuggestions - total number of suggestions
        Since:
        8.0

      • getTotalSuggestions

        public int getTotalSuggestions()
        Gets the total number of suggestions, excluding the null selection item.
        Returns:
        total number of suggestions
        Since:
        8.0

      • getNullSelectionItemShouldBeVisible

        public boolean getNullSelectionItemShouldBeVisible()
        Returns null selection item should be visible or not.

        NOTE: this checks for any entered filter value, and whether the feature is enabled

        Returns:
        true if it should be visible,
        Since:
        8.0

      • getEmptySelectionCaption

        public String getEmptySelectionCaption()
        Gets the empty selection caption.
        Returns:
        the empty selection caption
        Since:
        8.0.7

      • setEmptySelectionCaption

        public void setEmptySelectionCaption​(String emptySelectionCaption)
        Sets the empty selection caption for this VComboBox. The text is displayed in the text input when nothing is selected.
        Parameters:
        emptySelectionCaption - the empty selection caption
        Since:
        8.0.7