com.extjs.gxt.ui.client.widget.form
Class ComboBox<D extends ModelData>

java.lang.Object
  com.google.gwt.user.client.ui.UIObject
      com.google.gwt.user.client.ui.Widget
          com.extjs.gxt.ui.client.widget.Component
              com.extjs.gxt.ui.client.widget.BoxComponent
                  com.extjs.gxt.ui.client.widget.form.Field<D>
                      com.extjs.gxt.ui.client.widget.form.TextField<Data>
                          com.extjs.gxt.ui.client.widget.form.TriggerField<D>
                              com.extjs.gxt.ui.client.widget.form.ComboBox<D>

Type Parameters:

D - the model data type

All Implemented Interfaces:

Observable, SelectionProvider<D>, com.google.gwt.user.client.EventListener

Direct Known Subclasses:

SimpleComboBox, ThemeSelector, TimeField

public class ComboBox<D extends ModelData>
extends TriggerField<D>
implements SelectionProvider<D>

A combobox component.

When not forcing a selection (setForceSelection(boolean)) getValue() can return null event 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 Field.getRawValue() to get the fields string value.

Combo uses a XTemplate to render it's drop down list. A custom template can be specified to customize the display of the drop down list. See setTemplate(XTemplate).

A custom PropertyEditor can be used to "format" the value that is displayed in the combo's text field. For example:

  combo.setPropertyEditor(new ListModelPropertyEditor<State>(){
      public String getStringValue(State value) {
        return value.getAbbr() + " " + value.getName();
      }
    });
 

A ModelProcessor can be used to "format" the values in the drop down list:

    combo.getView().setModelProcessor(new ModelProcessor() {
      public State prepareData(State model) {
        model.set("test", model.getAbbr() + " " + model.getName());
        return model;
      }
    });
 

Events:

Expand : FieldEvent(field)

Fires when the dropdown list is expanded.

• field : this

Collapse : FieldEvent(field)

Fires when the dropdown list is collapsed.

• field : this

BeforeSelect : FieldEvent(field)

Fires before a list item is selected. Listeners can set the doit field to false to cancel the action.

• field : this

Select : FieldEvent(field)

Fires when a list item is selected.

• field : this

BeforeQuery : FieldEvent(field, value)

Fires before all queries are processed. Listeners can set the doit field to false to cancel the action.

• field : this
• value : query

Inherited Events:

Field Focus

Field Blur

Field Change

Field Invalid

Field Valid

Field KeyPress

Field SpecialKey

TriggerField TriggerClick

Nested Class Summary

class	ComboBox.ComboBoxMessages ComboBox error messages.
static class	ComboBox.TriggerAction TriggerAction enum.

Nested classes/interfaces inherited from class com.extjs.gxt.ui.client.widget.form.TextField

TextField.TextFieldMessages

Nested classes/interfaces inherited from class com.extjs.gxt.ui.client.widget.form.Field

Field.FieldMessages

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

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

Field Summary

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

DEBUG_ID_PREFIX

Constructor Summary

ComboBox()
Creates a combo box.

Method Summary

void	addSelectionChangedListener(SelectionChangedListener listener) Add a selection changed listener.
void	clearSelections() Clears any text/value currently set in the field.
void	collapse() Hides the dropdown list if it is currently expanded.
void	doQuery(java.lang.String q, boolean forceAll) 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.
java.lang.String	getDisplayField() Returns the display field.
boolean	getForceSelection() Returns true if the field's value is forced to one of the value in the list.
java.lang.String	getItemSelector() Returns the item selector.
java.lang.String	getListAlign() Returns the list's list align value.
java.lang.String	getListStyle() Returns the list style.
ListView<D>	getListView() Returns the combo's list view.
java.lang.String	getLoadingText() Returns the loading text.
int	getMaxHeight() Returns the dropdown list's max height.
ComboBox.ComboBoxMessages	getMessages() Returns the field's messages.
int	getMinChars() Returns the min characters used for autocompete and typeahead.
int	getMinListWidth() Returns the dropdown list's min width.
ModelStringProvider<D>	getModelStringProvider() Deprecated. see setModelStringProvider(ModelStringProvider)
int	getPageSize() Returns the page size.
PagingToolBar	getPagingToolBar() Returns the combo's paging tool bar.
ListModelPropertyEditor<D>	getPropertyEditor() Returns the field's property editor.
int	getQueryDelay() Returns the query delay.
java.lang.String	getSelectedStyle() Returns the selected style.
java.util.List<D>	getSelection() Returns the current selection.
ListStore<D>	getStore() Returns the combo's store.
XTemplate	getTemplate() Returns the custom template.
ComboBox.TriggerAction	getTriggerAction() Returns the trigger action.
int	getTypeAheadDelay() Returns the type ahead delay in milliseconds.
D	getValue() Returns the typed value of the field.
java.lang.String	getValueField() Returns the value field name.
ListView<D>	getView() Returns the combo's list view.
boolean	isExpanded() Returns true if the panel is expanded.
boolean	isLazyRender() Returns true if lazy rendering is enabled.
boolean	isTypeAhead() Returns true if type ahead is enabled.
void	onComponentEvent(ComponentEvent ce) Any events a component receives will be forwarded to this method.
void	removeSelectionListener(SelectionChangedListener listener) Removes a selection changed listener.
void	reset() Resets the current field value to the originally loaded value and clears any validation messages.
void	select(int index) Select an item in the dropdown list by its numeric index in the 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	setDisplayField(java.lang.String displayField) The underlying data field name to bind to this ComboBox (defaults to 'text').
void	setEditable(boolean value) Allow or prevent the user from directly editing the field text.
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	setItemSelector(java.lang.String itemSelector) This setting is required if a custom XTemplate has been specified.
void	setLazyRender(boolean lazyRender) True to lazily render the combo's drop down list (default to false, pre-render).
void	setListAlign(java.lang.String listAlign) Sets a valid anchor position value.
void	setListStyle(java.lang.String listStyle) Sets the style for the drop down list (defaults to 'x-combo-list');
void	setLoadingText(java.lang.String loadingText) Sets the loading text.
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	setModelStringProvider(ModelStringProvider<D> modelStringProvider) Deprecated. the preferred way to provide "formatted" values is to use a ModelProcessor with the comobo's view.
void	setPageSize(int pageSize) Sets the page size.
void	setPropertyEditor(PropertyEditor<D> propertyEditor) Sets the field's property editor which is used to translate typed values to string, and string values back to typed values.
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	setRawValue(java.lang.String text) Sets the underlying DOM field's value directly, bypassing validation.
void	setSelectedStyle(java.lang.String selectedStyle) Sets the CSS style name to apply to the selected item in the dropdown list (defaults to 'x-combo-selected').
void	setSelection(java.util.List<D> selection) Sets the current selection for this selection provider.
void	setSimpleTemplate(java.lang.String html) Sets the template fragment to be used for the text of each combo list item.
void	setStore(ListStore<D> store) Sets the combo's store.
void	setTemplate(java.lang.String html) Sets the custom template used to render the combo's drop down list.Use this to create custom UI layouts for items in the list.
void	setTemplate(XTemplate template) Sets the custom template used to render the combo's drop down list.
void	setTriggerAction(ComboBox.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 (typeAheadDelay) 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	setValue(D value) Sets a data value into the field and validates it.
void	setValueField(java.lang.String valueField) Sets the model field used to retrieve the "value" from the model.
void	setView(ListView view) Sets the combo's view.

Methods inherited from class com.extjs.gxt.ui.client.widget.form.TriggerField

getElement, getTriggerStyle, isHideTrigger, setHideTrigger, setTriggerStyle

Methods inherited from class com.extjs.gxt.ui.client.widget.form.TextField

getAllowBlank, getCursorPos, getMaxLength, getMinLength, getRegex, getSelectedText, getSelectionLength, getSelectOnFocus, getValidator, isPassword, select, selectAll, setAllowBlank, setCursorPos, setEmptyText, setMaxLength, setMinLength, setPassword, setRegex, setSelectionRange, setSelectOnFocus, setValidator

Methods inherited from class com.extjs.gxt.ui.client.widget.form.Field

addInputStyleName, addKeyListener, clearInvalid, focus, forceInvalid, getAutoValidate, getEmptyText, getFieldLabel, getLabelSeparator, getLabelStyle, getMessageTarget, getName, getOriginalValue, getRawValue, getValidateOnBlur, getValidationDelay, isDirty, isHideLabel, isReadOnly, isValid, markInvalid, removeInputStyleName, removeKeyListener, setAutoValidate, setFieldLabel, setHideLabel, setLabelSeparator, setLabelStyle, setMessages, setMessageTarget, setName, setOriginalValue, setReadOnly, setTabIndex, setValidateOnBlur, setValidationDelay, updateOriginalValue, validate

Methods inherited from class com.extjs.gxt.ui.client.widget.BoxComponent

getBounds, getHeight, getHeight, getPosition, getShadow, getSize, getWidth, getWidth, isAutoHeight, isAutoWidth, isDeferHeight, isShim, setAutoHeight, setAutoWidth, setBounds, setBounds, setDeferHeight, setHeight, setHeight, setPagePosition, setPagePosition, setPixelSize, setPosition, setShadow, setShim, setSize, setSize, setWidth, setWidth

Methods inherited from class com.extjs.gxt.ui.client.widget.Component

addListener, addPlugin, addStyleName, addWidgetListener, disable, disableEvents, disableTextSelection, el, enable, enableEvents, fireEvent, fireEvent, fireEvent, fly, getBaseStyle, getBorders, getData, getData, getId, getItemId, getModel, getState, getToolTip, hide, hideToolTip, isDisabledEvents, isEnabled, isRendered, isVisible, onBrowserEvent, recalculate, removeAllListeners, removeFromParent, removeListener, removeStyleName, removeWidgetListener, render, render, saveState, setBorders, setData, setData, setElement, setEnabled, setEnableState, setId, setIntStyleAttribute, setItemId, setStyleAttribute, setStyleName, setTitle, setToolTip, setToolTip, setVisible, show, sinkEvents, toString

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

getParent, isAttached

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

addStyleDependentName, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getOffsetHeight, getOffsetWidth, getStyleName, getStylePrimaryName, getTitle, isVisible, removeStyleDependentName, setStylePrimaryName, setVisible, unsinkEvents

Methods inherited from class java.lang.Object

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

Constructor Detail

ComboBox

public ComboBox()

Creates a combo box.

Method Detail

addSelectionChangedListener

public void addSelectionChangedListener(SelectionChangedListener listener)

Description copied from interface: SelectionProvider

Add a selection changed listener.

Specified by:

addSelectionChangedListener in interface SelectionProvider<D extends ModelData>

Parameters:

listener - a selection changed listener

clearSelections

public void clearSelections()

Clears any text/value currently set in the field.

collapse

public void collapse()

Hides the dropdown list if it is currently expanded. Fires the Collapse event on completion.

doQuery

public void doQuery(java.lang.String q,
                    boolean forceAll)

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:

q - the query

forceAll - 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. Fires the expand event on completion.

getAllQuery

public java.lang.String getAllQuery()

Returns the all query.

Returns:

the all query

getDisplayField

public java.lang.String getDisplayField()

Returns the display field.

Returns:

the display field

getForceSelection

public boolean getForceSelection()

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

Returns:

the force selection state

getItemSelector

public java.lang.String getItemSelector()

Returns the item selector.

Returns:

the item selector

getListAlign

public java.lang.String getListAlign()

Returns the list's list align value.

Returns:

the list align valu

getListStyle

public java.lang.String getListStyle()

Returns the list style.

Returns:

the list style

getListView

public ListView<D> getListView()

Returns the combo's list view.

Returns:

the view

getLoadingText

public java.lang.String getLoadingText()

Returns the loading text.

Returns:

the loading text

getMaxHeight

public int getMaxHeight()

Returns the dropdown list's max height.

Returns:

the max height

getMessages

public ComboBox.ComboBoxMessages getMessages()

Description copied from class: Field

Returns the field's messages.

Overrides:

getMessages in class TextField<D extends ModelData>

Returns:

the messages

getMinChars

public int getMinChars()

Returns the min characters used for autocompete and typeahead.

Returns:

the minimum number of characters

getMinListWidth

public int getMinListWidth()

Returns the dropdown list's min width.

Returns:

the min width

getModelStringProvider

public ModelStringProvider<D> getModelStringProvider()

Deprecated. see setModelStringProvider(ModelStringProvider)

Returns the model string provider.

Returns:

the model string provider

getPageSize

public int getPageSize()

Returns the page size.

Returns:

the page size

getPagingToolBar

public PagingToolBar getPagingToolBar()

Returns the combo's paging tool bar.

Returns:

the tool bar

getPropertyEditor

public ListModelPropertyEditor<D> getPropertyEditor()

Description copied from class: Field

Returns the field's property editor.

Overrides:

getPropertyEditor in class Field<D extends ModelData>

Returns:

the property editor

getQueryDelay

public int getQueryDelay()

Returns the query delay.

Returns:

the query delay

getSelectedStyle

public java.lang.String getSelectedStyle()

Returns the selected style.

Returns:

the selected style

getSelection

public java.util.List<D> getSelection()

Description copied from interface: SelectionProvider

Returns the current selection.

Specified by:

getSelection in interface SelectionProvider<D extends ModelData>

Returns:

the current selection

getStore

public ListStore<D> getStore()

Returns the combo's store.

Returns:

the store

getTemplate

public XTemplate getTemplate()

Returns the custom template.

Returns:

the template

getTriggerAction

public ComboBox.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

getValue

public D getValue()

Description copied from class: Field

Returns the typed value of the field.

Overrides:

getValue in class Field<D extends ModelData>

Returns:

the fields value

getValueField

public java.lang.String getValueField()

Returns the value field name.

Returns:

the value field name

getView

public ListView<D> getView()

Returns the combo's list view.

Returns:

the view

isExpanded

public boolean isExpanded()

Returns true if the panel is expanded.

Returns:

the expand state

isLazyRender

public boolean isLazyRender()

Returns true if lazy rendering is enabled.

Returns:

true of lazy rendering

isTypeAhead

public boolean isTypeAhead()

Returns true if type ahead is enabled.

Returns:

the type ahead state

removeSelectionListener

public void removeSelectionListener(SelectionChangedListener listener)

Description copied from interface: SelectionProvider

Removes a selection changed listener.

Specified by:

removeSelectionListener in interface SelectionProvider<D extends ModelData>

Parameters:

listener - a selection changed listener

reset

public void reset()

Description copied from class: Field

Resets the current field value to the originally loaded value and clears any validation messages.

Overrides:

reset in class Field<D extends ModelData>

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

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

setDisplayField

public void setDisplayField(java.lang.String displayField)

The underlying data field name to bind to this ComboBox (defaults to 'text').

Parameters:

displayField - the display field

setEditable

public void setEditable(boolean value)

Allow or prevent the user from directly editing the field text. If false is passed, the user will only be able to select from the items defined in the dropdown list.

Parameters:

value - true to allow the user to directly edit the field text

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

setItemSelector

public void setItemSelector(java.lang.String itemSelector)

This setting is required if a custom XTemplate has been specified.

Parameters:

itemSelector - the item selector

setLazyRender

public void setLazyRender(boolean lazyRender)

True to lazily render the combo's drop down list (default to false, pre-render).

Parameters:

lazyRender - true to lazy render the drop down list

setListAlign

public void setListAlign(java.lang.String listAlign)

Sets a valid anchor position value. See El.alignTo(com.google.gwt.user.client.Element, java.lang.String, int[]) for details on supported anchor positions (defaults to 'tl-bl?').

Parameters:

listAlign - the new list align value

setListStyle

public void setListStyle(java.lang.String listStyle)

Sets the style for the drop down list (defaults to 'x-combo-list');

Parameters:

listStyle - the list style

setLoadingText

public void setLoadingText(java.lang.String loadingText)

Sets the loading text.

Parameters:

loadingText - the loading text

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

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 -

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

setModelStringProvider

public void setModelStringProvider(ModelStringProvider<D> modelStringProvider)

Deprecated. the preferred way to provide "formatted" values is to use a ModelProcessor with the comobo's view.

Sets the model string provider (defaults to BaseModelStringProvider .

Parameters:

modelStringProvider - the string provider

setPageSize

public void setPageSize(int pageSize)

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

Parameters:

pageSize - the page size

setPropertyEditor

public void setPropertyEditor(PropertyEditor<D> propertyEditor)

Description copied from class: Field

Sets the field's property editor which is used to translate typed values to string, and string values back to typed values.

Overrides:

setPropertyEditor in class Field<D extends ModelData>

Parameters:

propertyEditor - the property editor

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

setRawValue

public void setRawValue(java.lang.String text)

Description copied from class: Field

Sets the underlying DOM field's value directly, bypassing validation. To set the value with validation see Field.setValue(D).

Overrides:

setRawValue in class Field<D extends ModelData>

Parameters:

text - the raw value

setSelectedStyle

public void setSelectedStyle(java.lang.String selectedStyle)

Sets the CSS style name to apply to the selected item in the dropdown list (defaults to 'x-combo-selected').

Parameters:

selectedStyle - the selected style

setSelection

public void setSelection(java.util.List<D> selection)

Description copied from interface: SelectionProvider

Sets the current selection for this selection provider.

Specified by:

setSelection in interface SelectionProvider<D extends ModelData>

Parameters:

selection - the new selection

setSimpleTemplate

public void setSimpleTemplate(java.lang.String html)

Sets the template fragment to be used for the text of each combo list item.

 
  combo.setSimpleTemplate("{abbr} {name}"); 
 
 

Parameters:

html - the html used only for the text of each item in the list

setStore

public void setStore(ListStore<D> store)

Sets the combo's store.

Parameters:

store - the store

setTemplate

public void setTemplate(java.lang.String html)

Sets the custom template used to render the combo's drop down list.Use this to create custom UI layouts for items in the list.

If you wish to preserve the default visual look of list items, add the CSS class name 'x-combo-list-item' to the template's container element.

Parameters:

html - the html

setTemplate

public void setTemplate(XTemplate template)

Sets the custom template used to render the combo's drop down list.

Parameters:

template - the template

setTriggerAction

public void setTriggerAction(ComboBox.TriggerAction triggerAction)

The action to execute when the trigger field is activated. Use ComboBox.TriggerAction.ALL to run the query specified by the allQuery config option (defaults to ComboBox.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 (typeAheadDelay) if it matches a known value (defaults to false)

Parameters:

typeAhead -

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

setValue

public void setValue(D value)

Description copied from class: Field

Sets a data value into the field and validates it. If the field is rendered, To set the value directly without validation see Field.setRawValue(java.lang.String).

Overrides:

setValue in class TextField<D extends ModelData>

Parameters:

value - the value to set

setValueField

public void setValueField(java.lang.String valueField)

Sets the model field used to retrieve the "value" from the model. If specified, a hidden form field will contain the value. The hidden form field name will be the combo's field name plus "-hidden".

Parameters:

valueField - the value field name

setView

public void setView(ListView view)

Sets the combo's view.

Parameters:

view - the view

onComponentEvent

public void onComponentEvent(ComponentEvent ce)

Description copied from class: Component

Any events a component receives will be forwarded to this method. Subclasses should override as needed. The Component.onBrowserEvent(com.google.gwt.user.client.Event) method should not be overridden or modified.

Overrides:

onComponentEvent in class Field<D extends ModelData>

Parameters:

ce - the base event