com.sencha.gxt.widget.core.client.form

Class ComboBox<T>

java.lang.Object

Widget

com.sencha.gxt.widget.core.client.Component

com.sencha.gxt.widget.core.client.cell.CellComponent<T>

com.sencha.gxt.widget.core.client.form.Field<T>

com.sencha.gxt.widget.core.client.form.ValueBaseField<T>

com.sencha.gxt.widget.core.client.form.TriggerField<T>

com.sencha.gxt.widget.core.client.form.ComboBox<T>

Type Parameters:

T - the data type

All Implemented Interfaces:

HasGestureRecognizers, BeforeHideEvent.HasBeforeHideHandlers, BeforeQueryEvent.HasBeforeQueryHandlers<T>, BeforeShowContextMenuEvent.HasBeforeShowContextMenuHandler, BeforeShowEvent.HasBeforeShowHandlers, BlurEvent.HasBlurHandlers, CollapseEvent.HasCollapseHandlers, DisableEvent.HasDisableHandlers, EnableEvent.HasEnableHandlers, ExpandEvent.HasExpandHandlers, FocusEvent.HasFocusHandlers, HideEvent.HasHideHandlers, InvalidEvent.HasInvalidHandlers, MoveEvent.HasMoveHandlers, ParseErrorEvent.HasParseErrorHandlers, ShowContextMenuEvent.HasShowContextMenuHandler, ShowEvent.HasShowHandlers, TriggerClickEvent.HasTriggerClickHandlers, ValidEvent.HasValidHandlers, HasErrorHandler, IsField<T>, HasFocusSupport, HasItemId

Direct Known Subclasses:

SimpleComboBox, TimeField

public class ComboBox<T>
extends TriggerField<T>
implements ExpandEvent.HasExpandHandlers, CollapseEvent.HasCollapseHandlers, BeforeQueryEvent.HasBeforeQueryHandlers<T>

A combobox control with support for autocomplete, remote loading, and many other features.

A ComboBox is like a combination of a traditional HTML text <input> field and a <select> field; the user is able to type freely into the field, and/or pick values from a dropdown selection list. The user can input any value by default, even if it does not appear in the selection list; to prevent free-form values and restrict them to items in the list, set setForceSelection(boolean) to true.

When not forcing a selection (setForceSelection(boolean)) CellComponent.getValue() can return null even if the user has typed text into the field if that text cannot be tied to a model from from the combo's store. In this case, you can use ValueBaseField.getText() to get the fields string value.

The selection list's options are populated from any ListStore. If the selection list is not otherwise in a list store, you may find it easier to use SimpleComboBox.

Nested Class Summary

Nested classes/interfaces inherited from class com.sencha.gxt.widget.core.client.form.Field

Field.FieldStyles

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	autoComplete

Fields inherited from class com.sencha.gxt.widget.core.client.form.ValueBaseField

impl

Fields inherited from class com.sencha.gxt.widget.core.client.form.Field

forceInvalidText, hasFocus, name, originalValue, parseError, preventMark, validationTask

Fields inherited from class com.sencha.gxt.widget.core.client.cell.CellComponent

valueUpdater

Fields inherited from class com.sencha.gxt.widget.core.client.Component

adjustSize, allowTextSelection, cacheSizes, disableContextMenu, disabled, disabledStyle, ensureVisibilityOnSizing, height, hidden, lastSize, layer, left, mask, maskMessage, monitorWindowResize, pageX, pageY, resizeHandler, shim, tabIndex, toolTip, toolTipConfig, top, width, windowResizeDelay, windowResizeTask

Constructor Summary

Constructors

Constructor and Description
ComboBox(ComboBoxCell<T> cell) Creates a new combo box with the given cell.
ComboBox(ListStore<T> store, LabelProvider<? super T> labelProvider) Creates a combo box that renders all items with the given label provider.
ComboBox(ListStore<T> store, LabelProvider<? super T> labelProvider, <any> renderer) Creates a combo box that renders the input value with the label provider and the drop down values with the renderer.
ComboBox(ListStore<T> store, LabelProvider<? super T> labelProvider, <any> renderer, TriggerFieldCell.TriggerFieldAppearance appearance) Creates a combo box that renders the input value with the label provider and the drop down values with the renderer.
ComboBox(ListStore<T> store, LabelProvider<? super T> labelProvider, ListView<T,?> listView) Creates a combo box that renders the input value with the label provider.
ComboBox(ListStore<T> store, LabelProvider<? super T> labelProvider, ListView<T,?> listView, TriggerFieldCell.TriggerFieldAppearance appearance) Creates a combo box that renders the input value with the label provider.

Method Summary

Modifier and Type	Method and Description
HandlerRegistration	addBeforeQueryHandler(BeforeQueryEvent.BeforeQueryHandler<T> handler) Adds a BeforeQueryEvent.BeforeQueryHandler handler for BeforeQueryEvent events.
HandlerRegistration	addBeforeSelectionHandler(<any> handler)
HandlerRegistration	addCollapseHandler(CollapseEvent.CollapseHandler handler) Adds a CollapseEvent.CollapseHandler handler for CollapseEvent events.
HandlerRegistration	addExpandHandler(ExpandEvent.ExpandHandler handler) Adds a ExpandEvent.ExpandHandler handler for ExpandEvent events.
HandlerRegistration	addSelectionHandler(<any> handler)
void	clear() Clears the value from the field.
void	collapse() Hides the dropdown list if it is currently expanded.
void	doQuery(String query, boolean force) Execute a query to filter the dropdown list.
void	expand() Expands the dropdown list if it is currently hidden.
String	getAllQuery() Returns the all query.
ComboBoxCell<T>	getCell() Get the Cell wrapped by this widget.
LabelProvider<? super T>	getLabelProvider() Returns the combo's label provider.
ListView<T,?>	getListView() Returns the combo's list view.
Loader<?,?>	getLoader() Returns the combo's loader.
int	getMaxHeight() Returns the dropdown list's max height.
int	getMinChars() Returns the minimum characters used for autocomplete and typeahead.
int	getMinListWidth() Returns the dropdown list's minimum width.
int	getPageSize() Returns the page size.
int	getQueryDelay() Returns the query delay.
ListStore<T>	getStore() Returns the combo's list store.
ComboBoxCell.TriggerAction	getTriggerAction() Returns the trigger action.
int	getTypeAheadDelay() Returns the type ahead delay in milliseconds.
boolean	isExpanded() Returns true if the dropdown is expanded.
boolean	isForceSelection() Returns true if the field's value is forced to one of the value in the list.
boolean	isTypeAhead() Returns true if type ahead is enabled.
boolean	isUseQueryCache() Returns the state if the query cache is used or not.
protected void	onAfterFirstAttach() Called immediately after the first time the widget becomes attached to the browser's document only the first time.
protected void	onCellParseError(ParseErrorEvent event)
protected void	onDetach()
void	select(int index) Select an item in the dropdown list by its numeric index in the list.
void	select(T item) Select an item in the dropdown list.
void	setAllQuery(String allQuery) The text query to send to the server to return all records for the list with no filtering (defaults to '').
void	setExpanded(boolean expand) Sets the panel's expand state.
void	setForceSelection(boolean forceSelection) Sets whether the combo's value is restricted to one of the values in the list, false to allow the user to set arbitrary text into the field (defaults to false).
void	setLoader(Loader<?,?> loader) Sets the comobo's loader.
void	setLoadingIndicator(SafeHtml html) Sets the loading indicator html to be displayed during a load request.
void	setMaxHeight(int maxHeight) Sets the maximum height in pixels of the dropdown list before scrollbars are shown (defaults to 300).
void	setMinChars(int minChars) Sets the minimum number of characters the user must type before autocomplete and typeahead active (defaults to 4 if remote, or 0 if local).
void	setMinListWidth(int minListWidth) Sets the minimum width of the dropdown list in pixels (defaults to 70, will be ignored if listWidth has a higher value).
void	setPageSize(int pageSize) Sets the page size.
void	setQueryDelay(int queryDelay) The length of time in milliseconds to delay between the start of typing and sending the query to filter the dropdown list.
void	setStore(ListStore<T> store) Sets the combo's store.
void	setTriggerAction(ComboBoxCell.TriggerAction triggerAction) The action to execute when the trigger field is activated.
void	setTypeAhead(boolean typeAhead) True to populate and autoselect the remainder of the text being typed after a configurable delay (setTypeAheadDelay(int)) if it matches a known value (defaults to false)
void	setTypeAheadDelay(int typeAheadDelay) The length of time in milliseconds to wait until the typeahead text is displayed if typeAhead = true (defaults to 250).
void	setUseQueryCache(boolean useQueryCache) Set this to false to disable the last query cache (defaults to true).

Methods inherited from class com.sencha.gxt.widget.core.client.form.TriggerField

addTriggerClickHandler, isEditable, isFinishEditOnEnter, isMonitorTab, onBlur, setEditable, setFinishEditOnEnter, setHideTrigger, setMonitorTab

Methods inherited from class com.sencha.gxt.widget.core.client.form.ValueBaseField

addChangeHandler, addKeyDownHandler, addKeyPressHandler, addKeyUpHandler, addParseErrorHandler, doAutoValidate, getCurrentValue, getCursorPos, getDirection, getDirectionEstimator, getEmptyText, getFocusEl, getImpl, getInputEl, getPropertyEditor, getSelectedText, getSelectionLength, getText, getValueOrThrow, isAllowBlank, isClearValueOnParseError, isCurrentValid, isCurrentValid, isReadOnly, isSelectOnFocus, onRedraw, select, selectAll, setAllowBlank, setClearValueOnParseError, setCursorPos, setDirection, setDirectionEstimator, setDirectionEstimator, setEmptyText, setId, setPropertyEditor, setReadOnly, setSelectionRange, setSelectOnFocus, setTabIndex, setText, setValue, validateCurrent

Methods inherited from class com.sencha.gxt.widget.core.client.form.Field

addInvalidHandler, addValidator, addValidHandler, addValueChangeHandler, clearInvalid, finishEditing, flush, forceInvalid, getErrors, getErrorSupport, getName, getOriginalValue, getValidateOnBlur, getValidationDelay, getValidators, isAutoValidate, isEditing, isValid, isValid, markInvalid, markInvalid, onBrowserEvent, onDisable, onEnable, onFocus, onKeyDown, onKeyPress, onKeyUp, onLogicalBlur, onLogicalFocus, onNavigationKey, onPropertyChange, removeValidator, reset, setAutoValidate, setDelegate, setErrors, setErrorSupport, setName, setOriginalValue, setValidateOnBlur, setValidationDelay, setValue, showErrors, validate, validate, validateValue

Methods inherited from class com.sencha.gxt.widget.core.client.cell.CellComponent

createContext, getElement, getKey, getKeyProvider, getValue, onResize, redraw, redraw, setKeyProvider, setValue

Methods inherited from class com.sencha.gxt.widget.core.client.Component

addBeforeHideHandler, addBeforeShowContextMenuHandler, addBeforeShowHandler, addBlurHandler, addDisableHandler, addEnableHandler, addFocusHandler, addGestureRecognizer, addHideHandler, addMoveHandler, addResizeHandler, addShowContextMenuHandler, addShowHandler, addStyleDependentName, addStyleOnOver, adjustPosition, adjustSize, applyState, assertAfterRender, assertPreRender, blur, clearSizeCache, disable, disableContextMenu, disableEvents, enable, enableEvents, fireCancellableEvent, fireEvent, focus, getData, getFocusSupport, getGestureRecognizer, getGestureRecognizerCount, getHideMode, getId, getItemId, getOffsetHeight, getOffsetWidth, getPositionEl, getShadow, getShadowPosition, getStateId, getTabIndex, getToolTip, hide, hideShadow, hideToolTip, isAllowTextSelection, isAutoHeight, isAutoWidth, isDeferHeight, isEnabled, isMonitorWindowResize, isRendered, isStateful, isVisible, isVisible, mask, mask, notifyHide, notifyShow, onAttach, onHide, onHideContextMenu, onLoad, onPosition, onRightClick, onShow, onShowContextMenu, onTouch, onUnload, onWindowResize, removeStyleDependentName, removeStyleOnOver, removeToolTip, setAllowTextSelection, setBorders, setBounds, setBounds, setContextMenu, setData, setDeferHeight, setEnabled, setHeight, setHeight, setHideMode, setItemId, setMonitorWindowResize, setPagePosition, setPixelSize, setPosition, setShadow, setShadowPosition, setSize, setStateful, setStateId, setStyleDependentName, setToolTip, setToolTipConfig, setVisible, setWidth, setWidth, show, sync, syncSize, unmask

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.sencha.gxt.widget.core.client.event.BlurEvent.HasBlurHandlers

addBlurHandler

Field Detail

autoComplete

protected boolean autoComplete

Constructor Detail

ComboBox

public ComboBox(ComboBoxCell<T> cell)

Creates a new combo box with the given cell.

Parameters:

cell - the cell

ComboBox

public ComboBox(ListStore<T> store,
                LabelProvider<? super T> labelProvider)

Creates a combo box that renders all items with the given label provider.

Parameters:

store - the store containing the data that can be selected

labelProvider - converts the current model type into a string value to display in the text box

ComboBox

public ComboBox(ListStore<T> store,
                LabelProvider<? super T> labelProvider,
                ListView<T,?> listView)

Creates a combo box that renders the input value with the label provider.

Parameters:

store - the store containing the data that can be selected

labelProvider - converts the current model type into a string value to display in the text box

listView - the list view

ComboBox

public ComboBox(ListStore<T> store,
                LabelProvider<? super T> labelProvider,
                ListView<T,?> listView,
                TriggerFieldCell.TriggerFieldAppearance appearance)

Creates a combo box that renders the input value with the label provider.

Parameters:

store - the store containing the data that can be selected

labelProvider - converts the current model type into a string value to display in the text box

listView - the list view

appearance - the appearance

ComboBox

public ComboBox(ListStore<T> store,
                LabelProvider<? super T> labelProvider,
                <any> renderer)

Creates a combo box that renders the input value with the label provider and the drop down values with the renderer.

Parameters:

store - the store containing the data that can be selected

labelProvider - converts the current model type into a string value to display in the text box

renderer - draws the current model as html in the drop down

ComboBox

public ComboBox(ListStore<T> store,
                LabelProvider<? super T> labelProvider,
                <any> renderer,
                TriggerFieldCell.TriggerFieldAppearance appearance)

Creates a combo box that renders the input value with the label provider and the drop down values with the renderer.

Parameters:

store - the store containing the data that can be selected

labelProvider - converts the current model type into a string value to display in the text box

renderer - draws the current model as html in the drop down

appearance - the appearance

Method Detail

addBeforeQueryHandler

public HandlerRegistration addBeforeQueryHandler(BeforeQueryEvent.BeforeQueryHandler<T> handler)

Description copied from interface: BeforeQueryEvent.HasBeforeQueryHandlers

Adds a BeforeQueryEvent.BeforeQueryHandler handler for BeforeQueryEvent events.

Specified by:

addBeforeQueryHandler in interface BeforeQueryEvent.HasBeforeQueryHandlers<T>

Parameters:

handler - the handler

Returns:

the registration for the event

addBeforeSelectionHandler

public HandlerRegistration addBeforeSelectionHandler(<any> handler)

addCollapseHandler

public HandlerRegistration addCollapseHandler(CollapseEvent.CollapseHandler handler)

Description copied from interface: CollapseEvent.HasCollapseHandlers

Adds a CollapseEvent.CollapseHandler handler for CollapseEvent events.

Specified by:

addCollapseHandler in interface CollapseEvent.HasCollapseHandlers

Parameters:

handler - the handler

Returns:

the registration for the event

addExpandHandler

public HandlerRegistration addExpandHandler(ExpandEvent.ExpandHandler handler)

Description copied from interface: ExpandEvent.HasExpandHandlers

Adds a ExpandEvent.ExpandHandler handler for ExpandEvent events.

Specified by:

addExpandHandler in interface ExpandEvent.HasExpandHandlers

Parameters:

handler - the handler

Returns:

the registration for the event

addSelectionHandler

public HandlerRegistration addSelectionHandler(<any> handler)

clear

public void clear()

Description copied from interface: IsField

Clears the value from the field.

Specified by:

clear in interface IsField<T>

Overrides:

clear in class ValueBaseField<T>

See Also:

to remove validation messages, to restore to original value and remove validation messages

collapse

public void collapse()

Hides the dropdown list if it is currently expanded.

doQuery

public void doQuery(String query,
                    boolean force)

Execute a query to filter the dropdown list. Fires the BeforeQuery event prior to performing the query allowing the query action to be canceled if needed.

Parameters:

query - the query

force - true to force the query to execute even if there are currently fewer characters in the field than the minimum specified by the minChars config option. It also clears any filter previously saved in the current store

expand

public void expand()

Expands the dropdown list if it is currently hidden.

getAllQuery

public String getAllQuery()

Returns the all query.

Returns:

the all query

getCell

public ComboBoxCell<T> getCell()

Description copied from class: CellComponent

Get the Cell wrapped by this widget.

Overrides:

getCell in class TriggerField<T>

Returns:

the Cell being wrapped

getLabelProvider

public LabelProvider<? super T> getLabelProvider()

Returns the combo's label provider.

Returns:

the label provider

getListView

public ListView<T,?> getListView()

Returns the combo's list view.

Returns:

the list view

getLoader

public Loader<?,?> getLoader()

Returns the combo's loader.

Returns:

the loader or null if not set

getMaxHeight

public int getMaxHeight()

Returns the dropdown list's max height.

Returns:

the max height

getMinChars

public int getMinChars()

Returns the minimum characters used for autocomplete and typeahead.

Returns:

the minimum number of characters

getMinListWidth

public int getMinListWidth()

Returns the dropdown list's minimum width.

Returns:

the minimum width

getPageSize

public int getPageSize()

Returns the page size.

Returns:

the page size

getStore

public ListStore<T> getStore()

Returns the combo's list store.

Returns:

the list store

getTriggerAction

public ComboBoxCell.TriggerAction getTriggerAction()

Returns the trigger action.

Returns:

the trigger action

getTypeAheadDelay

public int getTypeAheadDelay()

Returns the type ahead delay in milliseconds.

Returns:

the type ahead delay

isUseQueryCache

public boolean isUseQueryCache()

Returns the state if the query cache is used or not.

Returns:

the useQueryCache state

getQueryDelay

public int getQueryDelay()

Returns the query delay.

Returns:

the query delay

isExpanded

public boolean isExpanded()

Returns true if the dropdown is expanded.

Returns:

the expand state

isForceSelection

public boolean isForceSelection()

Returns true if the field's value is forced to one of the value in the list.

Returns:

the force selection state

isTypeAhead

public boolean isTypeAhead()

Returns true if type ahead is enabled.

Returns:

the type ahead state

select

public void select(int index)

Select an item in the dropdown list by its numeric index in the list. This function does NOT cause the select event to fire. The list must expanded for this function to work, otherwise use #setValue.

Parameters:

index - the index of the item to select

select

public void select(T item)

Select an item in the dropdown list. This function does NOT cause the select event to fire. The list must expanded for this function to work, otherwise use #setValue.

Parameters:

item - the item to select

setAllQuery

public void setAllQuery(String allQuery)

The text query to send to the server to return all records for the list with no filtering (defaults to '').

Parameters:

allQuery - the all query

setExpanded

public void setExpanded(boolean expand)

Sets the panel's expand state.

Parameters:

expand - true to expand

setForceSelection

public void setForceSelection(boolean forceSelection)

Sets whether the combo's value is restricted to one of the values in the list, false to allow the user to set arbitrary text into the field (defaults to false).

Parameters:

forceSelection - true to force selection

setLoader

public void setLoader(Loader<?,?> loader)

Sets the comobo's loader. Keep in mind setMinChars(int) (defaults to 4 if remote, or 0 if local) when using the loader, as it will only load when the min amount of characters has been met.

Parameters:

loader - the loader

setMaxHeight

public void setMaxHeight(int maxHeight)

Sets the maximum height in pixels of the dropdown list before scrollbars are shown (defaults to 300).

Parameters:

maxHeight - the max hieght

setLoadingIndicator

public void setLoadingIndicator(SafeHtml html)

Sets the loading indicator html to be displayed during a load request.

• The setLoader(Loader) has to be set for this use.
• The css class name 'loading-indicator' can style the loading indicator html.

Parameters:

html - the loading html

setMinChars

public void setMinChars(int minChars)

Sets the minimum number of characters the user must type before autocomplete and typeahead active (defaults to 4 if remote, or 0 if local).

Parameters:

minChars - minimum number of characters before autocomplete and typeahead are active

setMinListWidth

public void setMinListWidth(int minListWidth)

Sets the minimum width of the dropdown list in pixels (defaults to 70, will be ignored if listWidth has a higher value).

Parameters:

minListWidth - the min width

setPageSize

public void setPageSize(int pageSize)

Sets the page size. Only applies when using a paging toolbar.

Parameters:

pageSize - the page size

setStore

public void setStore(ListStore<T> store)

Sets the combo's store.

Parameters:

store - the store

setTriggerAction

public void setTriggerAction(ComboBoxCell.TriggerAction triggerAction)

The action to execute when the trigger field is activated. Use ComboBoxCell.TriggerAction.ALL to run the query specified by the allQuery which can be set using setAllQuery(String) (defaults to ComboBoxCell.TriggerAction.QUERY).

Parameters:

triggerAction - the trigger action

setTypeAhead

public void setTypeAhead(boolean typeAhead)

True to populate and autoselect the remainder of the text being typed after a configurable delay (setTypeAheadDelay(int)) if it matches a known value (defaults to false)

Parameters:

typeAhead - true to enable type ahead

setTypeAheadDelay

public void setTypeAheadDelay(int typeAheadDelay)

The length of time in milliseconds to wait until the typeahead text is displayed if typeAhead = true (defaults to 250).

Parameters:

typeAheadDelay - the type ahead delay

setUseQueryCache

public void setUseQueryCache(boolean useQueryCache)

Set this to false to disable the last query cache (defaults to true). When set to false the store gets queried on each expand for the data that should get displayed in the list. If you use a loader, than each time the ComboBox gets expanded, the server gets asked for the data. You want to do this for example, if you filter the content of this ComboBox against some selection in another field.

Parameters:

useQueryCache - the useQueryCache to set

setQueryDelay

public void setQueryDelay(int queryDelay)

The length of time in milliseconds to delay between the start of typing and sending the query to filter the dropdown list.

Parameters:

queryDelay - the query delay

onAfterFirstAttach

protected void onAfterFirstAttach()

Description copied from class: Component

Called immediately after the first time the widget becomes attached to the browser's document only the first time.

Overrides:

onAfterFirstAttach in class Component

onCellParseError

protected void onCellParseError(ParseErrorEvent event)

Overrides:

onCellParseError in class ValueBaseField<T>

onDetach

protected void onDetach()

Overrides:

onDetach in class TriggerField<T>