com.vaadin.ui
Class ComboBox

java.lang.Object
  com.vaadin.server.AbstractClientConnector
      com.vaadin.ui.AbstractComponent
          com.vaadin.ui.AbstractField<java.lang.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<java.lang.Object>, Property.Editor, Property.ReadOnlyStatusChangeListener, Property.ReadOnlyStatusChangeNotifier, Property.ValueChangeListener, Property.ValueChangeNotifier, Property.Viewer, Validatable, Action.ShortcutNotifier, ConnectorEventListener, FieldEvents.BlurNotifier, FieldEvents.FocusNotifier, MethodEventSource, ClientConnector, Sizeable, VariableOwner, com.vaadin.shared.Connector, AbstractSelect.Filtering, Component, Component.Focusable, Field<java.lang.Object>, LegacyComponent, java.io.Serializable, java.util.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/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.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.Component

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

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.server.Sizeable

Sizeable.Unit

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

Field.ValueChangeEvent

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

Buffered.SourceException

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

Field Summary

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

ComboBox()

ComboBox(java.lang.String caption)

ComboBox(java.lang.String caption, java.util.Collection<?> options)

ComboBox(java.lang.String caption, Container dataSource)

Method Summary

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(java.lang.String filterString, com.vaadin.shared.ui.combobox.FilteringMode filteringMode) Constructs a filter instance to use when using a Filterable container in the ITEM_CAPTION_MODE_PROPERTY mode.
void	changeVariables(java.lang.Object source, java.util.Map<java.lang.String,java.lang.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 java.util.List<?>	getFilteredOptions() Filters the options in memory and returns the full filtered list.
com.vaadin.shared.ui.combobox.FilteringMode	getFilteringMode() Gets the current filtering mode.
java.lang.String	getInputPrompt() Gets the current input prompt.
protected java.util.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.
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(com.vaadin.shared.ui.combobox.FilteringMode filteringMode) Sets the option filtering mode.
void	setInputPrompt(java.lang.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	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	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, 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, shouldHideErrors, toString, validate, validate, valueChange

Methods inherited from class com.vaadin.ui.AbstractComponent

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, 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.ui.LegacyComponent

markAsDirty

Methods inherited from interface com.vaadin.server.VariableOwner

isEnabled, isImmediate

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.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.shared.Connector

getConnectorId

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.event.Action.ShortcutNotifier

addShortcutListener, removeShortcutListener

Field Detail

pageLength

protected int pageLength

Holds value of property pageLength. 0 disables paging.

Constructor Detail

ComboBox

public ComboBox()

ComboBox

public ComboBox(java.lang.String caption,
                java.util.Collection<?> options)

ComboBox

public ComboBox(java.lang.String caption,
                Container dataSource)

ComboBox

public ComboBox(java.lang.String caption)

Method Detail

getInputPrompt

public java.lang.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(java.lang.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:

getOptionsWithFilter

protected java.util.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 Filterable and Indexed, and the filtering mode must be suitable for container filtering (tested with #canUseContainerFilter()). Use getFilteredOptions() and sanitetizeList(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(java.lang.String filterString,
                                       com.vaadin.shared.ui.combobox.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(com.vaadin.data.Container.ItemSetChangeEvent)

getFilteredOptions

protected java.util.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(java.lang.Object source,
                            java.util.Map<java.lang.String,java.lang.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(com.vaadin.shared.ui.combobox.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 com.vaadin.shared.ui.combobox.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:

java.lang.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

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

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)