Package com.vaadin.ui

Class ComboBox

java.lang.Object

com.vaadin.server.AbstractClientConnector

com.vaadin.ui.AbstractComponent

com.vaadin.ui.AbstractField<Object>

com.vaadin.ui.AbstractSelect

com.vaadin.ui.ComboBox

All Implemented Interfaces:

Buffered, BufferedValidatable, Container, Container.ItemSetChangeListener, Container.ItemSetChangeNotifier, Container.PropertySetChangeListener, Container.PropertySetChangeNotifier, Container.Viewer, Property<Object>, Property.Editor, Property.ReadOnlyStatusChangeListener, Property.ReadOnlyStatusChangeNotifier, Property.ValueChangeListener, Property.ValueChangeNotifier, Property.Viewer, Validatable, Action.ShortcutNotifier, ConnectorEventListener, ContextClickEvent.ContextClickNotifier, FieldEvents.BlurNotifier, FieldEvents.FocusNotifier, MethodEventSource, ClientConnector, Sizeable, VariableOwner, Connector, AbstractSelect.Filtering, Component, Component.Focusable, Field<Object>, LegacyComponent, Serializable, EventListener

Direct Known Subclasses:

Select

public class ComboBox
extends AbstractSelect
implements AbstractSelect.Filtering, FieldEvents.BlurNotifier, FieldEvents.FocusNotifier

A filtering dropdown single-select. Suitable for newItemsAllowed, but it's turned of by default to avoid mistakes. Items are filtered based on user input, and loaded dynamically ("lazy-loading") from the server. You can turn on newItemsAllowed and change filtering mode (and also turn it off), but you can not turn on multi-select mode.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	ComboBox.ItemStyleGenerator	ItemStyleGenerator can be used to add custom styles to combo box items shown in the popup.

Nested classes/interfaces inherited from class com.vaadin.ui.AbstractSelect

AbstractSelect.AbstractSelectTargetDetails, AbstractSelect.AcceptItem, AbstractSelect.CaptionChangeListener, AbstractSelect.DefaultNewItemHandler, AbstractSelect.Filtering, AbstractSelect.ItemCaptionMode, AbstractSelect.ItemDescriptionGenerator, AbstractSelect.NewItemHandler, AbstractSelect.TargetItemIs, AbstractSelect.VerticalLocationIs

Nested classes/interfaces inherited from class com.vaadin.ui.AbstractField

AbstractField.FocusShortcut, AbstractField.ReadOnlyStatusChangeEvent

Nested classes/interfaces inherited from interface com.vaadin.data.Buffered

Buffered.SourceException

Nested classes/interfaces inherited from interface com.vaadin.server.ClientConnector

ClientConnector.AttachEvent, ClientConnector.AttachListener, ClientConnector.ConnectorErrorEvent, ClientConnector.DetachEvent, ClientConnector.DetachListener

Nested classes/interfaces inherited from interface com.vaadin.ui.Component

Component.ErrorEvent, Component.Event, Component.Focusable, Component.Listener

Nested classes/interfaces inherited from interface com.vaadin.data.Container

Container.Editor, Container.Filter, Container.Filterable, Container.Hierarchical, Container.Indexed, Container.ItemSetChangeListener, Container.ItemSetChangeNotifier, Container.Ordered, Container.PropertySetChangeListener, Container.PropertySetChangeNotifier, Container.SimpleFilterable, Container.Sortable, Container.Viewer

Nested classes/interfaces inherited from interface com.vaadin.ui.Field

Field.ValueChangeEvent

Nested classes/interfaces inherited from interface com.vaadin.data.Property

Property.Editor, Property.ReadOnlyException, Property.ReadOnlyStatusChangeListener, Property.ReadOnlyStatusChangeNotifier, Property.Transactional<T>, Property.ValueChangeListener, Property.ValueChangeNotifier, Property.Viewer

Nested classes/interfaces inherited from interface com.vaadin.server.Sizeable

Sizeable.Unit

Field Summary

Fields

Modifier and Type	Field	Description
protected int	pageLength	Holds value of property pageLength.

Fields inherited from class com.vaadin.ui.AbstractSelect

ITEM_CAPTION_MODE_EXPLICIT, ITEM_CAPTION_MODE_EXPLICIT_DEFAULTS_ID, ITEM_CAPTION_MODE_ICON_ONLY, ITEM_CAPTION_MODE_ID, ITEM_CAPTION_MODE_INDEX, ITEM_CAPTION_MODE_ITEM, ITEM_CAPTION_MODE_PROPERTY, itemIdMapper, items

Fields inherited from class com.vaadin.ui.AbstractComponent

DESIGN_ATTR_PLAIN_TEXT

Fields inherited from interface com.vaadin.ui.AbstractSelect.Filtering

FILTERINGMODE_CONTAINS, FILTERINGMODE_OFF, FILTERINGMODE_STARTSWITH

Fields inherited from interface com.vaadin.server.Sizeable

SIZE_UNDEFINED, UNITS_CM, UNITS_EM, UNITS_EX, UNITS_INCH, UNITS_MM, UNITS_PERCENTAGE, UNITS_PICAS, UNITS_PIXELS, UNITS_POINTS

Constructor Summary

Constructors

Constructor	Description
ComboBox()
ComboBox(String caption)
ComboBox(String caption, Container dataSource)
ComboBox(String caption, Collection<?> options)

Method Summary

Modifier and Type	Method	Description
void	addBlurListener(FieldEvents.BlurListener listener)	Adds a BlurListener to the Component which gets fired when a Field loses keyboard focus.
void	addFocusListener(FieldEvents.FocusListener listener)	Adds a FocusListener to the Component which gets fired when a Field receives keyboard focus.
void	addListener(FieldEvents.BlurListener listener)	Deprecated. As of 7.0, replaced by addBlurListener(BlurListener)
void	addListener(FieldEvents.FocusListener listener)	Deprecated. As of 7.0, replaced by addFocusListener(FocusListener)
protected Container.Filter	buildFilter(String filterString, FilteringMode filteringMode)	Constructs a filter instance to use when using a Filterable container in the ITEM_CAPTION_MODE_PROPERTY mode.
void	changeVariables(Object source, Map<String,Object> variables)	Invoked when the value of a variable has changed.
void	containerItemSetChange(Container.ItemSetChangeEvent event)	Lets the listener know a Containers Item set has changed.
protected List<?>	getFilteredOptions()	Filters the options in memory and returns the full filtered list.
FilteringMode	getFilteringMode()	Gets the current filtering mode.
String	getInputPrompt()	Gets the current input prompt.
ComboBox.ItemStyleGenerator	getItemStyleGenerator()	Gets the currently used item style generator.
protected List<?>	getOptionsWithFilter(boolean needNullSelectOption)	Returns the filtered options for the current page using a container filter.
int	getPageLength()	Returns the page length of the suggestion popup.
String	getPopupWidth()	Returns the suggestion pop-up's width as a CSS string.
protected ComboBoxState	getState()	Returns the shared state bean with information to be sent from the server to the client.
boolean	isMultiSelect()	Deprecated. As of 7.0, use ListSelect, OptionGroup or TwinColSelect instead
boolean	isScrollToSelectedItem()	Returns true if the select should find the page with the selected item when opening the popup (single select combo box only).
boolean	isTextInputAllowed()	Returns true if the user can enter text into the field to either filter the selections or enter a new value if AbstractSelect.isNewItemsAllowed() returns true.
void	paintContent(PaintTarget target)	Paints the content of this component.
void	removeBlurListener(FieldEvents.BlurListener listener)	Removes a BlurListener from the Component.
void	removeFocusListener(FieldEvents.FocusListener listener)	Removes a FocusListener from the Component.
void	removeListener(FieldEvents.BlurListener listener)	Deprecated. As of 7.0, replaced by removeBlurListener(BlurListener)
void	removeListener(FieldEvents.FocusListener listener)	Deprecated. As of 7.0, replaced by removeFocusListener(FocusListener)
void	setFilteringMode(FilteringMode filteringMode)	Sets the option filtering mode.
void	setInputPrompt(String inputPrompt)	Sets the input prompt - a textual prompt that is displayed when the select would otherwise be empty, to prompt the user for input.
void	setItemStyleGenerator(ComboBox.ItemStyleGenerator itemStyleGenerator)	Sets the item style generator that is used to produce custom styles for showing items in the popup.
void	setMultiSelect(boolean multiSelect)	Deprecated. As of 7.0, use ListSelect, OptionGroup or TwinColSelect instead
void	setPageLength(int pageLength)	Sets the page length for the suggestion popup.
void	setPopupWidth(String width)	Sets the suggestion pop-up's width as a CSS string.
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.
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.

Methods inherited from class com.vaadin.ui.AbstractSelect

addContainerProperty, addItem, addItem, addItems, addItems, addItemSetChangeListener, addListener, addListener, addPropertySetChangeListener, attach, containerPropertySetChange, containsId, detach, fireItemSetChange, firePropertySetChange, getCaptionChangeListener, getContainerDataSource, getContainerProperty, getContainerPropertyIds, getItem, getItemCaption, getItemCaptionMode, getItemCaptionPropertyId, getItemIcon, getItemIconPropertyId, getItemIds, getListeners, getNewItemHandler, getNullSelectionItemId, getType, getType, getValue, getVisibleItemIds, isEmpty, isNewItemsAllowed, isNullSelectionAllowed, isSelected, paintItem, readDesign, readItem, readItems, removeAllItems, removeContainerProperty, removeItem, removeItemSetChangeListener, removeListener, removeListener, removePropertySetChangeListener, sanitizeSelection, select, setContainerDataSource, setItemCaption, setItemCaptionMode, setItemCaptionPropertyId, setItemIcon, setItemIconPropertyId, setNewItemHandler, setNewItemsAllowed, setNullSelectionAllowed, setNullSelectionItemId, setValue, setValue, size, unselect, writeDesign, writeItem, writeItems

Methods inherited from class com.vaadin.ui.AbstractField

addListener, addListener, addReadOnlyStatusChangeListener, addValidator, addValueChangeListener, beforeClientResponse, clear, commit, discard, fireReadOnlyStatusChange, fireValueChange, focus, getConversionError, getConversionError, getConvertedValue, getConverter, getCurrentBufferedSourceException, getCustomAttributes, getErrorMessage, getInternalValue, getModelType, getPropertyDataSource, getRequiredError, getState, getTabIndex, getValidators, isBuffered, isImmediate, isInvalidAllowed, isInvalidCommitted, isModified, isReadOnly, isRequired, isValid, isValidationVisible, readOnlyStatusChange, removeAllValidators, removeListener, removeListener, removeReadOnlyStatusChangeListener, removeValidator, removeValueChangeListener, setBuffered, setConversionError, setConvertedValue, setConverter, setConverter, setCurrentBufferedSourceException, setInternalValue, setInvalidAllowed, setInvalidCommitted, setLocale, setPropertyDataSource, setReadOnly, setRequired, setRequiredError, setTabIndex, setValidationVisible, setValue, shouldHideErrors, toString, validate, validate, valueChange

Methods inherited from class com.vaadin.ui.AbstractComponent

addContextClickListener, addListener, addShortcutListener, addStyleName, findAncestor, fireComponentErrorEvent, fireComponentEvent, getActionManager, getCaption, getComponentError, getData, getDebugId, getDescription, getExplicitImmediateValue, getHeight, getHeightUnits, getIcon, getId, getLocale, getParent, getPrimaryStyleName, getStyleName, getWidth, getWidthUnits, isCaptionAsHtml, isConnectorEnabled, isEnabled, isOrHasAncestor, isResponsive, isVisible, removeContextClickListener, removeListener, removeShortcutListener, removeStyleName, setCaption, setCaptionAsHtml, setComponentError, setData, setDebugId, setDescription, setEnabled, setHeight, setHeight, setHeightUndefined, setIcon, setId, setImmediate, setParent, setPrimaryStyleName, setResponsive, setSizeFull, setSizeUndefined, setStyleName, setStyleName, setVisible, setWidth, setWidth, setWidthUndefined

Methods inherited from class com.vaadin.server.AbstractClientConnector

addAttachListener, addDetachListener, addExtension, addListener, addListener, addListener, addMethodInvocationToQueue, createState, encodeState, equals, fireEvent, getAllChildrenIterable, getConnectorId, getErrorHandler, getExtensions, getResource, getRpcManager, getRpcProxy, getSession, getStateType, getUI, handleConnectorRequest, hashCode, hasListeners, isAttached, isThis, markAsDirty, markAsDirtyRecursive, registerRpc, registerRpc, removeAttachListener, removeDetachListener, removeExtension, removeListener, removeListener, removeListener, removeListener, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler, setResource

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.vaadin.event.Action.ShortcutNotifier

addShortcutListener, removeShortcutListener

Methods inherited from interface com.vaadin.server.ClientConnector

addAttachListener, addDetachListener, beforeClientResponse, encodeState, getErrorHandler, getExtensions, getRpcManager, getStateType, handleConnectorRequest, isAttached, isConnectorEnabled, markAsDirtyRecursive, removeAttachListener, removeDetachListener, removeExtension, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler

Methods inherited from interface com.vaadin.ui.Component

addListener, addStyleName, getCaption, getDescription, getIcon, getId, getLocale, getParent, getPrimaryStyleName, getStyleName, getUI, isEnabled, isReadOnly, isVisible, removeListener, removeStyleName, setCaption, setEnabled, setIcon, setId, setParent, setPrimaryStyleName, setReadOnly, setStyleName, setVisible

Methods inherited from interface com.vaadin.shared.Connector

getConnectorId

Methods inherited from interface com.vaadin.ui.LegacyComponent

markAsDirty

Methods inherited from interface com.vaadin.server.Sizeable

getHeight, getHeightUnits, getWidth, getWidthUnits, setHeight, setHeight, setHeightUndefined, setSizeFull, setSizeUndefined, setWidth, setWidth, setWidthUndefined

Methods inherited from interface com.vaadin.server.VariableOwner

isEnabled, isImmediate

Field Detail

pageLength

protected int pageLength

Holds value of property pageLength. 0 disables paging.

Constructor Detail

ComboBox

public ComboBox()

ComboBox

public ComboBox(String caption,
                Collection<?> options)

ComboBox

public ComboBox(String caption,
                Container dataSource)

ComboBox

public ComboBox(String caption)

Method Detail

getInputPrompt

public String getInputPrompt()

Gets the current input prompt.

Returns:

the current input prompt, or null if not enabled

See Also:

setInputPrompt(String)

setInputPrompt

public void setInputPrompt(String inputPrompt)

Sets the input prompt - a textual prompt that is displayed when the select would otherwise be empty, to prompt the user for input.

Parameters:

inputPrompt - the desired input prompt, or null to disable

paintContent

public void paintContent(PaintTarget target)
                  throws PaintException

Description copied from class: AbstractSelect

Paints the content of this component.

Specified by:

paintContent in interface LegacyComponent

Overrides:

paintContent in class AbstractSelect

Parameters:

target - the Paint Event.

Throws:

PaintException - if the paint operation failed.

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 AbstractSelect.isNewItemsAllowed() returns true. If text input is disabled, the comboBox will work in the same way as a NativeSelect

Returns:

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 AbstractSelect

Returns:

updated component shared state

getOptionsWithFilter

protected List<?> getOptionsWithFilter(boolean needNullSelectOption)

Returns the filtered options for the current page using a container filter. As a size effect, filteredSize is set to the total number of items passing the filter. The current container must be Container.Filterable and Container.Indexed, and the filtering mode must be suitable for container filtering (tested with #canUseContainerFilter()). Use getFilteredOptions() and sanitizeList(List, boolean) if this is not the case.

Parameters:

needNullSelectOption -

Returns:

filtered list of options (may be empty) or null if cannot use container filters

buildFilter

protected Container.Filter buildFilter(String filterString,
                                       FilteringMode filteringMode)

Constructs a filter instance to use when using a Filterable container in the ITEM_CAPTION_MODE_PROPERTY mode. Note that the client side implementation expects the filter string to apply to the item caption string it sees, so changing the behavior of this method can cause problems.

Parameters:

filterString -

filteringMode -

Returns:

containerItemSetChange

public void containerItemSetChange(Container.ItemSetChangeEvent event)

Description copied from class: AbstractSelect

Lets the listener know a Containers Item set has changed.

Specified by:

containerItemSetChange in interface Container.ItemSetChangeListener

Overrides:

containerItemSetChange in class AbstractSelect

Parameters:

event - change event text

See Also:

Container.ItemSetChangeListener.containerItemSetChange(Container.ItemSetChangeEvent)

getFilteredOptions

protected List<?> getFilteredOptions()

Filters the options in memory and returns the full filtered list. This can be less efficient than using container filters, so use getOptionsWithFilter(boolean) if possible (filterable container and suitable item caption mode etc.).

Returns:

changeVariables

public void changeVariables(Object source,
                            Map<String,Object> variables)

Invoked when the value of a variable has changed.

Specified by:

changeVariables in interface VariableOwner

Overrides:

changeVariables in class AbstractSelect

Parameters:

source - the Source of the variable change. This is the origin of the event. For example in Web Adapter this is the request.

variables - the Mapping from variable names to new variable values.

See Also:

com.vaadin.ui.AbstractComponent#changeVariables(java.lang.Object, java.util.Map)

setFilteringMode

public void setFilteringMode(FilteringMode filteringMode)

Description copied from interface: AbstractSelect.Filtering

Sets the option filtering mode.

Specified by:

setFilteringMode in interface AbstractSelect.Filtering

Parameters:

filteringMode - the filtering mode to use

getFilteringMode

public FilteringMode getFilteringMode()

Description copied from interface: AbstractSelect.Filtering

Gets the current filtering mode.

Specified by:

getFilteringMode in interface AbstractSelect.Filtering

Returns:

the filtering mode in use

addBlurListener

public void addBlurListener(FieldEvents.BlurListener listener)

Description copied from interface: FieldEvents.BlurNotifier

Adds a BlurListener to the Component which gets fired when a Field loses keyboard focus.

Specified by:

addBlurListener in interface FieldEvents.BlurNotifier

See Also:

FieldEvents.BlurListener

addListener

@Deprecated
public void addListener(FieldEvents.BlurListener listener)

Deprecated.

As of 7.0, replaced by addBlurListener(BlurListener)

Specified by:

addListener in interface FieldEvents.BlurNotifier

removeBlurListener

public void removeBlurListener(FieldEvents.BlurListener listener)

Description copied from interface: FieldEvents.BlurNotifier

Removes a BlurListener from the Component.

Specified by:

removeBlurListener in interface FieldEvents.BlurNotifier

See Also:

FieldEvents.BlurListener

removeListener

@Deprecated
public void removeListener(FieldEvents.BlurListener listener)

Deprecated.

As of 7.0, replaced by removeBlurListener(BlurListener)

Specified by:

removeListener in interface FieldEvents.BlurNotifier

addFocusListener

public void addFocusListener(FieldEvents.FocusListener listener)

Description copied from interface: FieldEvents.FocusNotifier

Adds a FocusListener to the Component which gets fired when a Field receives keyboard focus.

Specified by:

addFocusListener in interface FieldEvents.FocusNotifier

See Also:

FieldEvents.FocusListener

addListener

@Deprecated
public void addListener(FieldEvents.FocusListener listener)

Deprecated.

As of 7.0, replaced by addFocusListener(FocusListener)

Specified by:

addListener in interface FieldEvents.FocusNotifier

removeFocusListener

public void removeFocusListener(FieldEvents.FocusListener listener)

Description copied from interface: FieldEvents.FocusNotifier

Removes a FocusListener from the Component.

Specified by:

removeFocusListener in interface FieldEvents.FocusNotifier

See Also:

FieldEvents.FocusListener

removeListener

@Deprecated
public void removeListener(FieldEvents.FocusListener listener)

Deprecated.

As of 7.0, replaced by removeFocusListener(FocusListener)

Specified by:

removeListener in interface FieldEvents.FocusNotifier

setMultiSelect

@Deprecated
public void setMultiSelect(boolean multiSelect)

Deprecated.

As of 7.0, use ListSelect, OptionGroup or TwinColSelect instead

ComboBox does not support multi select mode.

Overrides:

setMultiSelect in class AbstractSelect

Parameters:

multiSelect - the New value of property multiSelect.

Throws:

UnsupportedOperationException - if trying to activate multiselect mode

See Also:

AbstractSelect.setMultiSelect(boolean)

isMultiSelect

@Deprecated
public boolean isMultiSelect()

Deprecated.

As of 7.0, use ListSelect, OptionGroup or TwinColSelect instead

ComboBox does not support multi select mode.

Overrides:

isMultiSelect in class AbstractSelect

Returns:

false

See Also:

AbstractSelect.isMultiSelect()

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.

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

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.

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. Only applies to single select mode. 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 (single select combo box only).

Returns:

true if the page with the selected item will be shown when opening the popup

See Also:

setScrollToSelectedItem(boolean)

setItemStyleGenerator

public void setItemStyleGenerator(ComboBox.ItemStyleGenerator itemStyleGenerator)

Sets the item style generator that is used to produce custom styles for showing items in the popup. The CSS class name that will be added to the item style names is v-filterselect-item-[style name].

Parameters:

itemStyleGenerator - the item style generator to set, or null to not use any custom item styles

Since:

7.5.6

getItemStyleGenerator

public ComboBox.ItemStyleGenerator getItemStyleGenerator()

Gets the currently used item style generator.

Returns:

the itemStyleGenerator the currently used item style generator, or null if no generator is used

Since:

7.5.6