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

java.lang.Object
  com.google.gwt.user.client.ui.UIObject
      com.google.gwt.user.client.ui.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:

Editor<T>, HasEditorDelegate<T>, HasEditorErrors<T>, LeafValueEditor<T>, ValueAwareEditor<T>, HasChangeHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasAttachHandlers, HasBeforeSelectionHandlers<T>, HasResizeHandlers, HasSelectionHandlers<T>, HasValueChangeHandlers<T>, HasHandlers, AutoDirectionHandler.Target, HasDirection, HasDirectionEstimator, EventListener, TakesValue<T>, HasEnabled, HasName, HasText, HasValue<T>, HasVisibility, IsWidget, HasKeyProvider<T>, 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, IsField<T>, HasFocusSupport, HasItemId

Direct Known Subclasses:

SimpleComboBox, TimeField

public class ComboBox<T>
extends TriggerField<T>
implements HasBeforeSelectionHandlers<T>, HasSelectionHandlers<T>, 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

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

UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled

Nested classes/interfaces inherited from interface com.google.gwt.i18n.client.HasDirection

HasDirection.Direction

Field Summary

Fields inherited from class com.google.gwt.user.client.ui.UIObject

DEBUG_ID_PREFIX

Constructor Summary

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

ComboBox(ListStore<T> store, LabelProvider<? super T> labelProvider, SafeHtmlRenderer<T> 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, SafeHtmlRenderer<T> 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, TriggerFieldCell.TriggerFieldAppearance appearance)
Creates a combo box that renders all items with the given label provider.

Method Summary

HandlerRegistration	addBeforeQueryHandler(BeforeQueryEvent.BeforeQueryHandler<T> handler) Adds a BeforeQueryEvent.BeforeQueryHandler handler for BeforeQueryEvent events.
HandlerRegistration	addBeforeSelectionHandler(BeforeSelectionHandler<T> 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(SelectionHandler<T> handler)
void	clear() Clears the value from the field.
void	collapse() Hides the dropdown list if it is currently expanded.
void	doQuery(java.lang.String query, boolean force) Execute a query to filter the dropdown list.
void	expand() Expands the dropdown list if it is currently hidden.
java.lang.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	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.
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.
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(java.lang.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	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	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).

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

addTriggerClickHandler, isEditable, isMonitorTab, setEditable, setHideTrigger, setMonitorTab

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

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

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

addInvalidHandler, addValidator, addValidHandler, addValueChangeHandler, clearInvalid, finishEditing, flush, forceInvalid, getErrorSupport, getName, getValidateOnBlur, getValidationDelay, getValidators, isAutoValidate, isEditing, isReadOnly, isValid, isValid, markInvalid, onBrowserEvent, onPropertyChange, removeValidator, reset, setAutoValidate, setDelegate, setErrorSupport, setName, setOriginalValue, setValidateOnBlur, setValidationDelay, setValue, showErrors, validate, validate

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

getElement, getKeyProvider, getValue, redraw, setValue

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

addBeforeHideHandler, addBeforeShowContextMenuHandler, addBeforeShowHandler, addBlurHandler, addDisableHandler, addEnableHandler, addFocusHandler, addHideHandler, addMoveHandler, addResizeHandler, addShowContextMenuHandler, addShowHandler, addStyleOnOver, clearSizeCache, disable, disableEvents, enable, enableEvents, fireEvent, focus, getData, getFocusSupport, getHideMode, getId, getItemId, getOffsetHeight, getOffsetWidth, getShadow, getStateId, getToolTip, hide, hideToolTip, isAllowTextSelection, isAutoHeight, isAutoWidth, isDeferHeight, isEnabled, isRendered, isStateful, isVisible, isVisible, mask, mask, removeToolTip, setAllowTextSelection, setBorders, setBounds, setBounds, setContextMenu, setData, setDeferHeight, setEnabled, setHeight, setHeight, setHideMode, setItemId, setPagePosition, setPixelSize, setPosition, setShadow, setSize, setStateful, setStateId, setTabIndex, setToolTip, setToolTipConfig, setVisible, setWidth, setWidth, show, sync, syncSize, unmask

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

addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, getLayoutData, getParent, isAttached, removeFromParent, setLayoutData, sinkEvents

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

addStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getOffsetHeight, getOffsetWidth, getStyleName, getStylePrimaryName, getTitle, isVisible, removeStyleDependentName, removeStyleName, setStyleDependentName, setStyleName, setStyleName, setStylePrimaryName, setTitle, setVisible, sinkBitlessEvent, toString, unsinkEvents

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.google.gwt.event.shared.HasHandlers

fireEvent

Methods inherited from interface com.google.gwt.user.client.ui.IsWidget

asWidget

Methods inherited from interface com.google.gwt.user.client.TakesValue

getValue

Methods inherited from interface com.google.gwt.user.client.ui.HasValue

getValue, setValue

Constructor Detail

ComboBox

public ComboBox(ComboBoxCell<T> cell)

Creates a new combo box with the given cell.

Parameters:

cell - the cell

ComboBox

@UiConstructor
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,
                SafeHtmlRenderer<T> 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,
                SafeHtmlRenderer<T> 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

ComboBox

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

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

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(BeforeSelectionHandler<T> handler)

Specified by:

addBeforeSelectionHandler in interface HasBeforeSelectionHandlers<T>

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(SelectionHandler<T> handler)

Specified by:

addSelectionHandler in interface HasSelectionHandlers<T>

clear

public void clear()

Description copied from class: Field

Clears the value from the field.

Specified by:

clear in interface IsField<T>

Overrides:

clear in class Field<T>

collapse

public void collapse()

Hides the dropdown list if it is currently expanded.

doQuery

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

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

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

Parameters:

loader - the loader

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