The Combobox is a text input field which can show a list of options via a drop-down PickList.

The set of options
will be filtered based on the current value in the text field, so only options that match what has been typed so far
will be displayed. The set of options can be derived from a ValueMap or dynamically retrieved from a dataSource. See
the PickList interface for further settings.

The two most common use cases for ComboBoxItems are:

With
addUnknownValues set to true, the
ComboBoxItem acts as a freeform text entry field with the picklist providing essentially a set of suggested completions
similar to a URL bar in a web browser.

With addUnknownValues set to false, the
ComboBoxItem acts similarly to a SelectItem where a fixed set of options is available to the user and the text entry
field is essentially used to filter which of these options are visible

Other commonly used settings to
configure ComboBoxItem behavior are: - defaultToFirstOption - this will select
the first option from the pickList as a default value for the item - and - completeOnTab which causes the current selection
in the pickList (if there is one) to be chosen when the user tabs out of the field, allowing a user to type a few
characters and hit tab to auto-complete to the first matched option. completeOnTab is automatically set to
true if addUnknownValues is false.

ComboBoxItem does not provide built-in support for multiple selection. For a Combobox that does provide such a
multiple-select feature use MultiComboBoxItem.

Only applies to databound items (see PickList.optionDataSource). Performs a fetch type operation on this item's
DataSource to retrieve the set of valid options for the item, based on the current PickList.pickListCriteria.

Only applies to databound items (see PickList.optionDataSource). Performs a fetch type operation on this item's
DataSource to retrieve the set of valid options for the item, based on the current PickList.pickListCriteria.

If addUnknownValues is
false, this property determines whether the user can clear the comboBoxItem value, or whether they are
constrained to choosing one of the available options (in which case clearing the text box will simply revert to the last
picked value when the user leaves the field).

If this combo box retrieves its options from a dataSource, should options be fetched from the server when
the item is first written out, or should this fetch be delayed until the user opens the pickList.

For databound pickLists (see PickList.optionDataSource), by default Smart GWT will cache and re-use datasets shown by
different pickLists displayed by different SelectItems in an LRU (least recently used) caching pattern.

Returns the raw text value that currently appears in the text field, which can differ from FormItem.getValue() in various cases - for example:
for items that constrain the value range, such as a DateItem with
enforceDate:true, or a ComboBoxItem with addUnknownValues:false for items with
a defined valueMap or edit value formatter and parser functions which converts display value to data value
while the item has focus if changeOnKeypress is false

If filterLocally is set for this item, and this item is showing options from a dataSource, fetch the
entire set of options from the server, and use these values to map the item value to the appropriate display value.

When a comboBoxItem is used to generate search criteria in a SearchForm this property governs whether, if the user
explicitly chose an option from the pickList, we explicitly generate criteria that will search for an exact match
against the chosen value.

If set, this FormItem will map stored values to display values as though a com.smartgwt.client.types.ValueMap
were specified, by fetching records from the specified optionDataSource and extracting the valueField and displayField in loaded records, to derive one valueMap
entry per record loaded from the optionDataSource.

If this item has a specified optionDataSource, this attribute may be set to specify an explicit DSRequest.operationId when performing a fetch against the option
dataSource to pick up display value mapping.

If this form item maps data values to display values by retrieving the FormItem.displayField values from an optionDataSource, this property denotes the the
field to use as the underlying data value in records from the optionDataSource. If not explicitly supplied, the
valueField name will be derived as described in FormItem.getValueFieldName().

For Databound formItems, this property determines which column valueIcons should show up in for this formItem's pickList. If unset valueIcons show up in the displayField column if specified, otherwise
the valueField column. In most cases
only the displayField or valueField will be visible.

Will this item return advancedCriteria if DynamicForm.getValuesAsCriteria() is called on this item's form? Overridden for ComboBoxItem to return true if generateExactMatchCriteria is true -
in this case if an exact value is chosen from our set of options (always the case if addUnkownValues is
false), we will use advancedCriteria to ensure the generated search criteria exactly matches the chosen value for this
item.

If addUnknownValues is
false, this property determines whether the user can clear the comboBoxItem value, or whether they are
constrained to choosing one of the available options (in which case clearing the text box will simply revert to the last
picked value when the user leaves the field).

If this combo box retrieves its options from a dataSource, should options be fetched from the server when
the item is first written out, or should this fetch be delayed until the user opens the pickList.

For databound pickLists (see PickList.optionDataSource), by default Smart GWT will cache and re-use datasets shown by
different pickLists displayed by different SelectItems in an LRU (least recently used) caching pattern.

If filterLocally is set for this item, and this item is showing options from a dataSource, fetch the
entire set of options from the server, and use these values to map the item value to the appropriate display value.

When a comboBoxItem is used to generate search criteria in a SearchForm this property governs whether, if the user
explicitly chose an option from the pickList, we explicitly generate criteria that will search for an exact match
against the chosen value.

If this item has a specified optionDataSource, and this property is
not null, this will be passed to the datasource as RPCRequest properties when
performing the fetch operation on the dataSource to obtain a data-value to display-value
mapping

If this item has a specified optionDataSource, this attribute may be set to specify an explicit DSRequest.operationId when performing a fetch against the option
dataSource to pick up display value mapping.

If this form item maps data values to display values by retrieving the FormItem.displayField values from an optionDataSource, this property denotes the the
field to use as the underlying data value in records from the optionDataSource. If not explicitly supplied, the
valueField name will be derived as described in FormItem.getValueFieldName().

For Databound formItems, this property determines which column valueIcons should show up in for this formItem's pickList. If unset valueIcons show up in the displayField column if specified, otherwise
the valueField column. In most cases
only the displayField or valueField will be visible.

When a comboBoxItem is used to generate search criteria in a SearchForm, if the user explicitly chose an option from
the pickList, should the criterion generated by the FormItemCriterionGetter's getCriterion()
method enforce a search for an exact match against the chosen value?

changePickerIconDefaults

setAddUnknownValues

This property controls whether the user can enter a value that is not present in the set of options for this item.

If set to false, the value the user enters in the text box is essentially used to filter the set of options displayed
in the pickList.

In this mode, when focus is taken from the field, if the entered value does not match any entries
in the com.smartgwt.client.types.ValueMap or optionDataSource, it will be discarded. Note
that in this mode, completeOnTab behavior
is automatically enabled so if the user enters a valid partial value such that one or more options is displayed in the
pickList, and hits the Tab key, the first matching option will be chosen automatically. In this mode the user may also
hit the "Escape" key to discard their edits.

Note also that when addUnknownValues is set
to false, the underlying value returned by getValue()
will not be updated until a value is explicitly chosen. This means any change or changed handlers will not fire directly
in response to the user typing in the field - they will fire when the user actually selects a value, or takes focus from
the field.

If this property is set to true, the user is not limited to entering values present in the set of options
for the item. Instead the set of options essentially become a set of suggestions that may be used, or the user can enter
an entirely new value.

getAddUnknownValues

This property controls whether the user can enter a value that is not present in the set of options for this item.

If set to false, the value the user enters in the text box is essentially used to filter the set of options displayed
in the pickList.

In this mode, when focus is taken from the field, if the entered value does not match any entries
in the com.smartgwt.client.types.ValueMap or optionDataSource, it will be discarded. Note
that in this mode, completeOnTab behavior
is automatically enabled so if the user enters a valid partial value such that one or more options is displayed in the
pickList, and hits the Tab key, the first matching option will be chosen automatically. In this mode the user may also
hit the "Escape" key to discard their edits.

Note also that when addUnknownValues is set
to false, the underlying value returned by getValue()
will not be updated until a value is explicitly chosen. This means any change or changed handlers will not fire directly
in response to the user typing in the field - they will fire when the user actually selects a value, or takes focus from
the field.

If this property is set to true, the user is not limited to entering values present in the set of options
for the item. Instead the set of options essentially become a set of suggestions that may be used, or the user can enter
an entirely new value.

Returns:

Current addUnknownValues value. Default value is true

setAllowEmptyValue

If addUnknownValues is
false, this property determines whether the user can clear the comboBoxItem value, or whether they are
constrained to choosing one of the available options (in which case clearing the text box will simply revert to the last
picked value when the user leaves the field).

See also specialValues as a way of providing several
different special values in addition to an empty value, such as "Invalid". Note that setting specialValues
disables the use of allowEmptyValue - see details of how to have an empty value while using
specialValues in in the
specialValues documentation.

getAllowEmptyValue

public java.lang.Boolean getAllowEmptyValue()

If addUnknownValues is
false, this property determines whether the user can clear the comboBoxItem value, or whether they are
constrained to choosing one of the available options (in which case clearing the text box will simply revert to the last
picked value when the user leaves the field).

See also specialValues as a way of providing several
different special values in addition to an empty value, such as "Invalid". Note that setting specialValues
disables the use of allowEmptyValue - see details of how to have an empty value while using
specialValues in in the
specialValues documentation.

Returns:

Current allowEmptyValue value. Default value is true

setAllowExpressions

The interface is not compatible with the
allowExpressions feature. A ComboBoxItem normally starts fetching matches as you type, and that mixes very
strangely with the idea of entering expressions like "a..b" - you will have the ComboBox seemingly
switching back and forth between treating the text as a normal search string vs as a special expression on a
per-keystroke basis.

We recommend a normal TextItem as the correct UI element to supply for users to enter filter
expressions.

getAllowExpressions

The interface is not compatible with the
allowExpressions feature. A ComboBoxItem normally starts fetching matches as you type, and that mixes very
strangely with the idea of entering expressions like "a..b" - you will have the ComboBox seemingly
switching back and forth between treating the text as a normal search string vs as a special expression on a
per-keystroke basis.

We recommend a normal TextItem as the correct UI element to supply for users to enter filter
expressions.

setAutoFetchData

If this combo box retrieves its options from a dataSource, should options be fetched from the server when
the item is first written out, or should this fetch be delayed until the user opens the pickList.

getAutoFetchData

public java.lang.Boolean getAutoFetchData()

If this combo box retrieves its options from a dataSource, should options be fetched from the server when
the item is first written out, or should this fetch be delayed until the user opens the pickList.

setCachePickListResults

For databound pickLists (see PickList.optionDataSource), by default Smart GWT will cache and re-use datasets shown by
different pickLists displayed by different SelectItems in an LRU (least recently used) caching pattern.

Setting this
flag to false avoids this caching for situations where it is too aggressive.

Note that this does not control re-use
of data within a single pickList. To control when client-side filtering is used in ComboBoxItem, see useClientFiltering and filterLocally.

getCachePickListResults

public boolean getCachePickListResults()

For databound pickLists (see PickList.optionDataSource), by default Smart GWT will cache and re-use datasets shown by
different pickLists displayed by different SelectItems in an LRU (least recently used) caching pattern.

Setting this
flag to false avoids this caching for situations where it is too aggressive.

Note that this does not control re-use
of data within a single pickList. To control when client-side filtering is used in ComboBoxItem, see useClientFiltering and filterLocally.

setDefaultToFirstOption

Select the first option as the default value for this ComboBoxItem. If options are derived from a dataSource, the first
value returned by the server will be used, otherwise the first value in the valueMap. If enabled, this setting overrides
defaultValue and defaultDynamicValue().

getDefaultToFirstOption

public java.lang.Boolean getDefaultToFirstOption()

Select the first option as the default value for this ComboBoxItem. If options are derived from a dataSource, the first
value returned by the server will be used, otherwise the first value in the valueMap. If enabled, this setting overrides
defaultValue and defaultDynamicValue().

Returns:

Current defaultToFirstOption value. Default value is false

getDefaultValue

public java.lang.Object getDefaultValue()

Static default value for this ComboBoxItem. To default to the first option use defaultToFirstOption instead.

If this field has an FormItem.optionDataSource, this property is used by default to identify which value to use as a display value in
records from this related dataSource. In this usage the specified displayField must be explicitly defined in the
optionDataSource to be used - see getDisplayFieldName() for more on this behavior. If not using local display values, the display value
for this item will be derived by performing a fetch against the option dataSource to find a record where the
value field matches this item's value, and
use the displayField value from that record. In addition to this, PickList-based form items that
provide a list of possible options such as the SelectItem or ComboBoxItem will show the displayField values to the user by
default, allowing them to choose a new data value (see FormItem.valueField) from a list of user-friendly
display values.

This essentially allows the specified optionDataSource to be used as a server based
valueMap.

Note: Developers may specify the FormItem.foreignDisplayField property in
addition to displayField. This is useful for cases where the display field name in the local dataSource
differs from the display field name in the optionDataSource. See the documentation for DataSourceField.foreignDisplayField for more on this.

Note that if optionDataSource is set and no valid display field is specified, FormItem.getDisplayFieldName() will return the
dataSource title field by default.

If a displayField is specified for a freeform text based item (such as a ComboBoxItem), any user-entered value will be treated as a display value. In
this scenario, items will derive the data value for the item from the first record where the displayField value matches
the user-entered value. To avoid ambiguity, developers may wish to avoid this usage if display values are not unique.

If this field has an FormItem.optionDataSource, this property is used by default to identify which value to use as a display value in
records from this related dataSource. In this usage the specified displayField must be explicitly defined in the
optionDataSource to be used - see getDisplayFieldName() for more on this behavior. If not using local display values, the display value
for this item will be derived by performing a fetch against the option dataSource to find a record where the
value field matches this item's value, and
use the displayField value from that record. In addition to this, PickList-based form items that
provide a list of possible options such as the SelectItem or ComboBoxItem will show the displayField values to the user by
default, allowing them to choose a new data value (see FormItem.valueField) from a list of user-friendly
display values.

This essentially allows the specified optionDataSource to be used as a server based
valueMap.

Note: Developers may specify the FormItem.foreignDisplayField property in
addition to displayField. This is useful for cases where the display field name in the local dataSource
differs from the display field name in the optionDataSource. See the documentation for DataSourceField.foreignDisplayField for more on this.

Note that if optionDataSource is set and no valid display field is specified, FormItem.getDisplayFieldName() will return the
dataSource title field by default.

If a displayField is specified for a freeform text based item (such as a ComboBoxItem), any user-entered value will be treated as a display value. In
this scenario, items will derive the data value for the item from the first record where the displayField value matches
the user-entered value. To avoid ambiguity, developers may wish to avoid this usage if display values are not unique.

Otherwise if an explicit displayField is specified it will be returned by
default. If the displayField was specified on the underlying dataSource field, and no matching field is
present in the optionDataSource for
the item, we avoid returning the specified displayField value and instead return the title field of the option
DataSource. We do this to avoid confusion for the case where the displayField is intended as a display-field value for
showing another field value within the same record in the underlying dataSource only.

If no explicit
foreignDisplay or displayField specification was found, and the FormItem.valueField for this item is hidden in the
FormItem.optionDataSource, this method will
return the title field for the optionDataSource.

setFetchDisplayedFieldsOnly

If this item has a specified optionDataSource and this property is true, the list of fields
used by this pickList will be passed to the datasource as DSRequest.outputs. If the datasource supports this feature the returned fields will be limited to this list. A custom
datasource will need to add code to implement field limiting.

getFetchDisplayedFieldsOnly

public java.lang.Boolean getFetchDisplayedFieldsOnly()

If this item has a specified optionDataSource and this property is true, the list of fields
used by this pickList will be passed to the datasource as DSRequest.outputs. If the datasource supports this feature the returned fields will be limited to this list. A custom
datasource will need to add code to implement field limiting.

setFilterFields

As the user types into this item's textBox, a comboBoxItem will show the pick-list of options, and filter the set of
results displayed by the current value in the text box. For a databound comboBoxItem, by default the entered value is
filtered against the displayField if one is
specified, otherwise the valueField.

This
attribute allows the developer to explicitly change which fields to filter against, causing the user-entered text to be
matched against any of the specified set of fields from the optionDataSource.

This essentially causes
getPickListFilterCriteria() to
return an AdvancedCriteria object representing "field1 starts with value or field2
starts with value or ...". The operator used is controlled by TextMatchStyle as usual, that is, "startsWith" implies the operator "iStartsWith, "substring"
implies "iContains" and "exact" implies "iEquals".

The most common use case for this setting would be when a
comboBoxItem is showing multiple pickListFields - if the same set of fields is specified as filterFields, the user can use the text-box to
filter against whichever fields are visible in the pickList.

For finer grained control over comboBoxItem filtering,
the comboBoxItem.setPickListFilterCriteriaFunction() may be specified.

getFilterFields

public java.lang.String[] getFilterFields()

As the user types into this item's textBox, a comboBoxItem will show the pick-list of options, and filter the set of
results displayed by the current value in the text box. For a databound comboBoxItem, by default the entered value is
filtered against the displayField if one is
specified, otherwise the valueField.

This
attribute allows the developer to explicitly change which fields to filter against, causing the user-entered text to be
matched against any of the specified set of fields from the optionDataSource.

This essentially causes
getPickListFilterCriteria() to
return an AdvancedCriteria object representing "field1 starts with value or field2
starts with value or ...". The operator used is controlled by TextMatchStyle as usual, that is, "startsWith" implies the operator "iStartsWith, "substring"
implies "iContains" and "exact" implies "iEquals".

The most common use case for this setting would be when a
comboBoxItem is showing multiple pickListFields - if the same set of fields is specified as filterFields, the user can use the text-box to
filter against whichever fields are visible in the pickList.

For finer grained control over comboBoxItem filtering,
the comboBoxItem.setPickListFilterCriteriaFunction() may be specified.

setFilterLocally

If filterLocally is set for this item, and this item is showing options from a dataSource, fetch the
entire set of options from the server, and use these values to map the item value to the appropriate display value. Also
use "local" type filtering on drop down list of options.

This means data will only be fetched once from
the server, and then filtered on the client.

Note - when this property is set to false, filtering will
still be performed on the client if a complete set of data for some criteria has been cached by a fetch, and a
subsequent fetch has more restrictive criteria. To explicitly disable client-side filtering set the useClientFiltering property to false.

getFilterLocally

public java.lang.Boolean getFilterLocally()

If filterLocally is set for this item, and this item is showing options from a dataSource, fetch the
entire set of options from the server, and use these values to map the item value to the appropriate display value. Also
use "local" type filtering on drop down list of options.

This means data will only be fetched once from
the server, and then filtered on the client.

Note - when this property is set to false, filtering will
still be performed on the client if a complete set of data for some criteria has been cached by a fetch, and a
subsequent fetch has more restrictive criteria. To explicitly disable client-side filtering set the useClientFiltering property to false.

getFilterWithValue

public boolean getFilterWithValue()

Read-only property set by the ComboBoxItem to indicate whether we should use the current typed-in value as part of the
filter criteria returned by getPickListFilterCriteria(). You can check this flag in order to mimic the ComboBoxItem's default behavior if you
provide a custom implementation of getPickListFilterCriteria().

setFormatOnBlur

With formatOnBlur enabled, this comboBoxItem will format its value according to the rules described in
FormItem.mapValueToDisplay() as long as the
item does not have focus. Once the user puts focus into the item the formatter will be removed. This provides a simple
way for developers to show a nicely formatted display value in a freeform text field, without the need for an explicit
FormItem.formatEditorValue() and FormItem.parseEditorValue() pair.

getFormatOnBlur

public java.lang.Boolean getFormatOnBlur()

With formatOnBlur enabled, this comboBoxItem will format its value according to the rules described in
FormItem.mapValueToDisplay() as long as the
item does not have focus. Once the user puts focus into the item the formatter will be removed. This provides a simple
way for developers to show a nicely formatted display value in a freeform text field, without the need for an explicit
FormItem.formatEditorValue() and FormItem.parseEditorValue() pair.

setGenerateExactMatchCriteria

When a comboBoxItem is used to generate search criteria in a SearchForm this property governs whether, if the user
explicitly chose an option from the pickList, we explicitly generate criteria that will search for an exact match
against the chosen value.

In order to achieve this, when this property is set to true, this item will generate
AdvancedCriteria in the default FormItemCriterionGetter's
getCriterion() method.

getGenerateExactMatchCriteria

public java.lang.Boolean getGenerateExactMatchCriteria()

When a comboBoxItem is used to generate search criteria in a SearchForm this property governs whether, if the user
explicitly chose an option from the pickList, we explicitly generate criteria that will search for an exact match
against the chosen value.

In order to achieve this, when this property is set to true, this item will generate
AdvancedCriteria in the default FormItemCriterionGetter's
getCriterion() method.

setOptionOperationId

If this item has a specified optionDataSource, this attribute may be set to specify an explicit DSRequest.operationId when performing a fetch against the option
dataSource to pick up display value mapping.

getOptionOperationId

public java.lang.String getOptionOperationId()

If this item has a specified optionDataSource, this attribute may be set to specify an explicit DSRequest.operationId when performing a fetch against the option
dataSource to pick up display value mapping.

setPendingTextBoxStyle

If addUnknownValues is false, when the user
modifies the value displayed in the combobox item text box, the underlying data value (as returned from item.getValue())
is not immediately updated - instead the value is used to filter the set of results displayed in the comboBoxItem
pickList.

While the comboBoxItem is in this pending state (where the result of getEnteredValue() will not
necessarily match the display value for whatever is returned by getValue()), the pendingTextBoxStyle may be applied to
the text box for the item.

When the element value is updated to display the actual value for the item (typically due
to the user selecting a value from the pickList), the standard TextItem.textBoxStyle will be reapplied.

May be
left unset in which case the standard text box style is always applied. Has no effect if addUnknownValues is true.

getPendingTextBoxStyle

public java.lang.String getPendingTextBoxStyle()

Optional "pending" style for this item's text box.

If addUnknownValues is false, when the user
modifies the value displayed in the combobox item text box, the underlying data value (as returned from item.getValue())
is not immediately updated - instead the value is used to filter the set of results displayed in the comboBoxItem
pickList.

While the comboBoxItem is in this pending state (where the result of getEnteredValue() will not
necessarily match the display value for whatever is returned by getValue()), the pendingTextBoxStyle may be applied to
the text box for the item.

When the element value is updated to display the actual value for the item (typically due
to the user selecting a value from the pickList), the standard TextItem.textBoxStyle will be reapplied.

May be
left unset in which case the standard text box style is always applied. Has no effect if addUnknownValues is true.

setPickListFields

This property allows the developer to specify which field[s] will be displayed in the drop down list of options.

Only applies to databound pickLists (see PickList.optionDataSource, or pickLists with custom data set up via the
advanced PickList.getClientPickListData() method.

If this property is unset, we display the PickList.displayField,
if specified, otherwise the PickList.valueField.

If there are multiple fields, column headers will be shown for
each field, the height of which can be customized via the PickList.pickListHeaderHeight attribute.

Each field to
display should be specified as a ListGridField object. Note that unlike in
listGrids, dataSource fields marked as hidden:true will be hidden by default in pickLists. To override this
behavior, ensure that you specify an explicit value for showIf.

setSeparateSpecialValues

If true, specialValues special values such
as the empty value will be shown in a separate non-scrolling area, in the separateValuesList. Aside from making these
values more easily accessible, showing them in a separate list allows data paging to be used, which is disabled if the
separateValues are shown in the normal drop-down list along with other values.

getSeparateSpecialValues

public java.lang.Boolean getSeparateSpecialValues()

If true, specialValues special values such
as the empty value will be shown in a separate non-scrolling area, in the separateValuesList. Aside from making these
values more easily accessible, showing them in a separate list allows data paging to be used, which is disabled if the
separateValues are shown in the normal drop-down list along with other values.

setShowOptionsFromDataSource

If this item is part of a databound form, and has a specified valueMap, by default we show the valueMap
options in the pickList for the item. Setting this property to true will ensure that the options displayed in our
pickList are derived from the form's dataSource.

getShowOptionsFromDataSource

public java.lang.Boolean getShowOptionsFromDataSource()

If this item is part of a databound form, and has a specified valueMap, by default we show the valueMap
options in the pickList for the item. Setting this property to true will ensure that the options displayed in our
pickList are derived from the form's dataSource.

setSortField

Specifies one or more fields by which this item should be initially sorted. It can be a field name, or an array of field names - but note that, if
multiple fields are supplied, then each will be sorted in the same direction.

For full sorting control, set initialSort to
a list of custom sortSpecifiers.

This attribute can also be set to
the index of a field in the fields array, but note that it will be converted to a string (field name) after
initialization.

getSortField

public java.lang.String getSortField()

Specifies one or more fields by which this item should be initially sorted. It can be a field name, or an array of field names - but note that, if
multiple fields are supplied, then each will be sorted in the same direction.

For full sorting control, set initialSort to
a list of custom sortSpecifiers.

This attribute can also be set to
the index of a field in the fields array, but note that it will be converted to a string (field name) after
initialization.

setSortField

Specifies one or more fields by which this item should be initially sorted. It can be a field name, or an array of field names - but note that, if
multiple fields are supplied, then each will be sorted in the same direction.

For full sorting control, set initialSort to
a list of custom sortSpecifiers.

This attribute can also be set to
the index of a field in the fields array, but note that it will be converted to a string (field name) after
initialization.

getSortFieldAsStringArray

public java.lang.String[] getSortFieldAsStringArray()

Specifies one or more fields by which this item should be initially sorted. It can be a field name, or an array of field names - but note that, if
multiple fields are supplied, then each will be sorted in the same direction.

For full sorting control, set initialSort to
a list of custom sortSpecifiers.

This attribute can also be set to
the index of a field in the fields array, but note that it will be converted to a string (field name) after
initialization.

setSortField

Specifies one or more fields by which this item should be initially sorted. It can be a field name, or an array of field names - but note that, if
multiple fields are supplied, then each will be sorted in the same direction.

For full sorting control, set initialSort to
a list of custom sortSpecifiers.

This attribute can also be set to
the index of a field in the fields array, but note that it will be converted to a string (field name) after
initialization.

getSortFieldAsInt

public java.lang.Integer getSortFieldAsInt()

Specifies one or more fields by which this item should be initially sorted. It can be a field name, or an array of field names - but note that, if
multiple fields are supplied, then each will be sorted in the same direction.

For full sorting control, set initialSort to
a list of custom sortSpecifiers.

This attribute can also be set to
the index of a field in the fields array, but note that it will be converted to a string (field name) after
initialization.

setUseClientFiltering

For databound items, this property will
be passed to the generated ResultSet data object for the pickList as ResultSet.useClientFiltering. Setting to false will disable
filtering on the client and ensure criteria are always passed to the DataSource directly.

getUseClientFiltering

public java.lang.Boolean getUseClientFiltering()

For databound items, this property will
be passed to the generated ResultSet data object for the pickList as ResultSet.useClientFiltering. Setting to false will disable
filtering on the client and ensure criteria are always passed to the DataSource directly.

Returns:

Current useClientFiltering value. Default value is null

setValueField

If this form item maps data values to display values by retrieving the FormItem.displayField values from an optionDataSource, this property denotes the the
field to use as the underlying data value in records from the optionDataSource. If not explicitly supplied, the
valueField name will be derived as described in FormItem.getValueFieldName().

getValueField

public java.lang.String getValueField()

If this form item maps data values to display values by retrieving the FormItem.displayField values from an optionDataSource, this property denotes the the
field to use as the underlying data value in records from the optionDataSource. If not explicitly supplied, the
valueField name will be derived as described in FormItem.getValueFieldName().

If unset, if a foreignKey relationship exists between
this field and the optionDataSource, this will be used, otherwise default behavior will return the FormItem.name of this field. Default value is null

defaultDynamicValue

fetchData

public void fetchData()

Only applies to databound items (see PickList.optionDataSource). Performs a fetch type operation on this item's
DataSource to retrieve the set of valid options for the item, based on the current PickList.pickListCriteria.

fetchData

fetchData

Only applies to databound items (see PickList.optionDataSource). Performs a fetch type operation on this item's
DataSource to retrieve the set of valid options for the item, based on the current PickList.pickListCriteria.

Parameters:

callback - Callback to fire when the fetch completes. Callback will fire with 4 parameters:

filterClientPickListData

The default implementation applies the criteria returned by
PickList.getPickListFilterCriteria() to the data returned by PickList.getClientPickListData(). A record passes the
filter if it has a matching value for all fields in the criteria object. Matching is performed according to TextMatchStyle.

If PickList.showAllOptions is set, all values are shown, with matching
values shown below a separator.

getClientPickListData

This method will be called for non-databound form items implementing the PickList
interface. The default implementation will derive data from the item's valueMap -
can be overridden to allow a custom set of options to be displayed.

Note that for PickLists that filter data based on user input
(ComboBox), this method should return the data before
filtering. To customize the data returned after filtering, override
filterClientPickListData()
instead.

As an example, for a formItem with valueField
set to "valueFieldName", the
default implementation would take a valueMap like the following:

valueMap: { value1: "display 1", value2: "display 2" }

.. and returning the following set of records:

[
{ valueFieldName : "value1" },
{ valueFieldName : "value2" }
]

Due to the valueMap, these records will appear as a two row pickList displayed as
"display 1" and "display 2".

Array of record objects to be displayed in the pickList. Note that when a user picks a record from the list,
the value of the field matching item.valueField will be picked. Also note that the
fields to be displayed can be customized via item.pickListFields

Otherwise if an explicit displayField is specified it will be returned by
default. If the displayField was specified on the underlying dataSource field, and no matching field is
present in the optionDataSource for
the item, we avoid returning the specified displayField value and instead return the title field of the option
DataSource. We do this to avoid confusion for the case where the displayField is intended as a display-field value for
showing another field value within the same record in the underlying dataSource only.

If no explicit
foreignDisplay or displayField specification was found, and the FormItem.valueField for this item is hidden in the
FormItem.optionDataSource, this method will
return the title field for the optionDataSource.

hasAdvancedCriteria

public java.lang.Boolean hasAdvancedCriteria()

Will this item return advancedCriteria if DynamicForm.getValuesAsCriteria() is called on this item's form? Overridden for ComboBoxItem to return true if generateExactMatchCriteria is true -
in this case if an exact value is chosen from our set of options (always the case if addUnkownValues is
false), we will use advancedCriteria to ensure the generated search criteria exactly matches the chosen value for this
item.

Note that AdvancedCriteria are not supported by all dataSources. When a form
is bound to a dataSource, we therefore default generateExactMatchCriteria to false unless the dataSource is
known to support AdvancedCriteria.

As with formItem.hasAdvancedCriteria() this will also return true if a Operator was explicitly specified for this item

shouldGenerateExactMatchCriteria

public java.lang.Boolean shouldGenerateExactMatchCriteria()

When a comboBoxItem is used to generate search criteria in a SearchForm, if the user explicitly chose an option from
the pickList, should the criterion generated by the FormItemCriterionGetter's getCriterion()
method enforce a search for an exact match against the chosen value?

In order to achieve this, when this property is
set to true, this item will generate AdvancedCriteria in the default
FormItemCriterionGetter's getCriterion() method.

setDefaultProperties

Class level method to set the default properties of this class. If set, then all
existing and subsequently created instances of this class will automatically have
default properties corresponding to
the properties of the class instance passed to this function.
This is a powerful feature that eliminates the need for users to create a separate
hierarchy of subclasses that only alter the default properties of this class. Can also
be used for skinning / styling purposes.

Note: This method is intended for
setting default attributes only and will affect all instances of the underlying class
(including those automatically generated in JavaScript). This method should not be used
to apply standard EventHandlers or override methods for a class - use a custom subclass
instead. Calling this method after instances have been created can result in undefined
behavior, since it bypasses any setters and a class instance may have already examined
a particular property and not be expecting any changes through this route.

Parameters:

comboBoxItemProperties - properties that should be used as new defaults when instances of this class are created

setSpecialValues

setPickListHeight

public void setPickListHeight(int pickListHeight)

Maximum height to show the pick list before it starts to scroll. Note that by default the pickList will be sized
to the height required by its content so it will be taller when more rows are available as selectable options

getPickListHeight

public int getPickListHeight()

Maximum height to show the pick list before it starts to scroll. Note that by default the pickList will be sized
to the height required by its content so it will be taller when more rows are available as selectable options

getPickListCellHeight

setValueIconField

public void setValueIconField(java.lang.String valueIconField)

For Databound formItems, this property determines which column valueIcons should show up in for this formItem's pickList. If unset valueIcons show up in the displayField column if specified, otherwise
the valueField column. In most cases
only the displayField or valueField will be visible. This property is typically only
required if custom pickListFields
have been specfied for this item.

getValueIconField

public java.lang.String getValueIconField()

For Databound formItems, this property determines which column valueIcons should show up in for this formItem's pickList. If unset valueIcons show up in the displayField column if specified, otherwise
the valueField column. In most cases
only the displayField or valueField will be visible. This property is typically only
required if custom pickListFields
have been specfied for this item.

setPickListCriteria

setFetchDelay

For a ComboBox or other pickList that accepts user-entered criteria, how many millseconds to wait after the last user
keystroke before fetching data from the server. The default setting will initiate a fetch if the stops typing or pauses briefly.

getFetchDelay

For a ComboBox or other pickList that accepts user-entered criteria, how many millseconds to wait after the last user
keystroke before fetching data from the server. The default setting will initiate a fetch if the stops typing or pauses briefly.

setOptionDataSource

If set, this FormItem will derive data to show in the PickList by fetching records from the specified
optionDataSource. The fetched data will be used as a valueMap by extracting the valueField and
displayField in the loaded records, to
derive one valueMap entry per record loaded from the optionDataSource. Multiple fields from the fetched data may
be shown in the pickList by setting pickListFields.

The data will be retrieved via a "fetch" operation on the DataSource, passing the pickListCriteria (if set) as criteria, and passing optionFilterContext (if set) as
DSRequest properties.

The fetch will be triggered when the pickList is first shown, or, you can set autoFetchData to fetch when the FormItem is
first drawn. You can also call com.smartgwt.client.widgets.form.fields.PickList#fetchData at any time to manually trigger
a fetch.

Data paging is automatically enabled if the optionDataSource supports it. As the pickList is
scrolled by the user, requests for additional data will be automatically issued.

For a pickList attached to a
ComboBoxItem, new fetches are issued as the user types, with criteria set as described under getPickListFilterCriteria(). If your dataSource is not
capable of filtering results by search criteria (eg the dataSource is backed by an XML flat file), you can set
filterLocally to have the entire
dataset loaded up front and filtering performed in the browser. This disables data paging.

Note that
if a normal, static valueMap is also
specified for the field (either directly in the form item or as part of the field definition in the dataSource),
it will be preferred to the data derived from the optionDataSource for whatever mappings are present.

getOptionDataSource

If set, this FormItem will map stored values to display values as though a com.smartgwt.client.types.ValueMap
were specified, by fetching records from the specified optionDataSource and extracting the valueField and displayField in loaded records, to derive one valueMap
entry per record loaded from the optionDataSource.

With the default setting of fetchMissingValues, fetches will be initiated
against the optionDataSource any time the FormItem has a non-null value and no corresponding display value is available.
This includes when the form is first initialized, as well as any subsequent calls to setValue(), such as may happen when DynamicForm.editRecord() is called. Retrieved values are
automatically cached by the FormItem.

Note that if a normal, static valueMap is also specified for the field (either
directly in the form item or as part of the field definition in the dataSource), it will be preferred to the data
derived from the optionDataSource for whatever mappings are present.

In a databound form, if displayField is specified for a FormItem and
optionDataSource is unset, optionDataSource will default to the form's current DataSource

Always uses item.optionDataSource if specified. Otherwise, if DataSourceField.foreignKey was specified, uses the target
DataSource. Otherwise, uses the DataSource of this item's form (if one is configured). Default value is null

getSelectedRecord

Returns the entire record object associated with the current value for this item (or null if no matching record exists
in the PickList data). Most commonly used for databound pickListItems to retrieve the values of other fields in the record.

setPickListProperties

Allows developers to designate a PickListMenu
as a template containing arbitrary properties to apply to the pickList that will be
created for this FormItem.

Note: Not every PickListMenu / ListGrid property is supported when assigned to a pickList.
Where there is a dedicated API on the form item (such as
PickList.setPickListCellHeight(int)), we recommend
that be used in favor of setting the equivalent property directly using this API.

setOptionFilterContext

If this item has a specified optionDataSource, and this property is
not null, this will be passed to the datasource as RPCRequest properties when
performing the fetch operation on the dataSource to obtain a data-value to display-value
mapping

setCanEditCriterionPredicate

The default canEditCriterion() predicate is overridden in comboBoxItem. When addUnknownValues is true,
comboBoxItems allow the user to edit substring match type criteria applied to the display field (if one is specified).

The user can also edit criteria attempting to match exactly against the item's field name.

setCriterionGetter

The default getCriterion() implementation returns criterion derived from the current value of this item.

If addUnknownValues is true for
this item, we implement the following behavior. If the user explicitly selected an item from the pickList, we treat
this as an attempt to explicitly match the data value. In this case returned criteria will match the selected (data) value
against this item's fieldName. If the user typed a value into the text field, we treat this as an attempt to do a substring
type filter. In this case returned criteria will match the entered text value against the displayField for this item if
one is specified.

If addUnknownValues is false we always match the chosen data value against the item's fieldName.

Note that ComboBoxItem.shouldGenerateExactMatchCriteria will be called in the case when a value was explicitly picked from the
set of options. If that method returns true, we will return AdvancedCriteria with an operator specified to ensure an
exact match occurs.

setPickListSort

This method sorts the pickList on one or more fields, creating the underlying JS object
if needed. Pass in an array of SortSpecifiers to have the grid's data sorted by the fields in each
specifier.property and in the directions specified. The grid can be sorted by any combination
of fields, including fields specified in the fields array, whether visible or hidden, and
'unused fields from the underlying dataSource',
if there is one. If multiple fields are sorted, those that are visible show a directional icon and a small
'sort-numeral' indicating that
field's index in the sort configuration.