com.smartgwt.client.widgets.form.fields

## Class ComboBoxItem

- java.lang.Object
- - com.smartgwt.client.core.JsObject
  - - com.smartgwt.client.core.DataClass
    - - com.smartgwt.client.core.RefDataClass
      - - com.smartgwt.client.widgets.form.fields.FormItem
        - - com.smartgwt.client.widgets.form.fields.TextItem
          - - com.smartgwt.client.widgets.form.fields.ComboBoxItem

- All Implemented Interfaces:
    com.google.gwt.event.shared.HasHandlers, HasBlurHandlers, HasChangedHandlers, HasChangeHandlers, HasClickHandlers, HasDataArrivedHandlers, HasDoubleClickHandlers, HasEditorEnterHandlers, HasEditorExitHandlers, HasFocusHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasPendingStatusChangedHandlers, HasPickerIconClickHandlers, HasShowContextMenuHandlers, HasTitleClickHandlers, HasTitleDoubleClickHandlers, HasTitleHoverHandlers, HasValueHoverHandlers, HasValueIconClickHandlers, PickList

      public class ComboBoxItem
      extends TextItem
      implements PickList, HasDataArrivedHandlers

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

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class com.smartgwt.client.widgets.form.fields.FormItem

      `FormItem.CustomStateGetter, FormItem.StateCustomizer`

  - ### Field Summary

    - ### Fields inherited from class com.smartgwt.client.widgets.form.fields.FormItem

      `configOnly, scClassName, warnOnEditorTypeConversion, warnOnEditorTypeConversionDefault`

    - ### Fields inherited from class com.smartgwt.client.core.RefDataClass

      `id`

    - ### Fields inherited from class com.smartgwt.client.core.DataClass

      `factoryCreated, factoryProperties`

    - ### Fields inherited from class com.smartgwt.client.core.JsObject

      `jsObj`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ComboBoxItem()`
    `ComboBoxItem(com.google.gwt.core.client.JavaScriptObject jsObj)`
    `ComboBoxItem(java.lang.String name)`
    `ComboBoxItem(java.lang.String name, java.lang.String title)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `com.google.gwt.event.shared.HandlerRegistration` | `addDataArrivedHandler(DataArrivedHandler handler)` Add a dataArrived handler.
    `static void` | `changeAutoChildDefaults(java.lang.String autoChildName, Canvas defaults)` Changes the defaults for Canvas AutoChildren named `autoChildName`.
    `static void` | `changeAutoChildDefaults(java.lang.String autoChildName, FormItem defaults)` Changes the defaults for FormItem AutoChildren named `autoChildName`.
    `static void` | `changePickerIconDefaults(FormItemIcon defaults)`
    `void` | `defaultDynamicValue()` Expression evaluated to determine the `defaultValue` when no value is provided for this item.
    `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.
    `void` | `fetchData(DSCallback callback)`
    `void` | `fetchData(DSCallback callback, DSRequest requestProperties)` 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.
    `ListGridRecord[]` | `filterClientPickListData()` Returns the data to display in the pick list.
    `java.lang.Boolean` | `getAddUnknownValues()` This property controls whether the user can enter a value that is not present in the set of options for this item.
    `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).
    `java.lang.Boolean` | `getAllowExpressions()` The standard `FormItem.allowExpressions` behavior is always disabled for ComboBoxItem.
    `java.lang.Boolean` | `getAnimatePickList()` If true, when the pickList is shown, it will be shown via an animated reveal effect
    `int` | `getAnimationTime()` If this.animatePickList is true - this specifies the duration of the animation effect applied when showing the pickList
    `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.
    `java.lang.String` | `getAutoOpenTree()` When this item is showing a tree-based picker, which nodes should be opened automatically.
    `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.
    `ListGridRecord[]` | `getClientPickListData()` Returns the set of data to be displayed in this item's PickList.
    `java.lang.Boolean` | `getCompleteOnEnter()` If true, when the pickList is showing, the user can select the current value by hitting the `Enter` key.
    `java.lang.Boolean` | `getCompleteOnTab()` If true, when the pickList is showing, the user can select the current value by hitting the `Tab` key.
    `java.lang.String` | `getDataSetType()` Whether to show the picker as a flat list, or a collapsible tree.
    `java.lang.Boolean` | `getDefaultToFirstOption()` Select the first option as the default value for this ComboBoxItem.
    `java.lang.Object` | `getDefaultValue()` Static default value for this ComboBoxItem.
    `java.lang.String` | `getDisplayField()` If set, this item will display a value from another field to the user instead of showing the underlying data value for the `field name`.
    `java.lang.String` | `getDisplayFieldName()` Returns the `displayField` for this item.
    `java.lang.String` | `getEditProxyConstructor()` Default class used to construct the `EditProxy` for this component when the component is `first placed into edit mode`.
    `int` | `getEmptyPickListHeight()` Height for an empty pick list (showing the empty message), if the pick list has no records and `hideEmptyPickList` is `false`.
    `java.lang.String` | `getEmptyPickListMessage()` Empty message to display in the comboboxItem if PickList.hideEmptyPickList is `false`.
    `java.lang.String` | `getEnteredValue()` 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 Note: if the pickList is being shown in any view other than the default `nearOrigin`, as is typically the case on a mobile device, this method will return the value of the `pickerSearchField`.
    `java.lang.Integer` | `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.
    `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`.
    `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.
    `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.
    `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()`.
    `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.
    `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.
    `java.lang.Boolean` | `getHideEmptyPickList()` If this pickList contains no options, should it be hidden? If unset, default behavior is to allow the empty pickList to show if it is databound.
    `PickListItemIconPlacement` | `getIconPlacement()` For PickList items with `PickListItemIconPlacement` set such that the pickList does not render near-origin, should specified `icons` be rendered inline within the formItem itself, or within the `pickerNavigationBar`.
    `SortSpecifier[]` | `getInitialSort()` An array of `SortSpecifier` objects used to set up the initial sort configuration for this pickList.
    `java.lang.String` | `getMask()` Not applicable to a ComboBoxItem.
    `java.lang.Boolean` | `getMaskOverwriteMode()` Not applicable to a ComboBoxItem.
    `java.lang.String` | `getMaskPadChar()` Not applicable to a ComboBoxItem.
    `java.lang.String` | `getMaskPromptChar()` Not applicable to a ComboBoxItem.
    `java.lang.Boolean` | `getMaskSaveLiterals()` Not applicable to a ComboBoxItem.
    `java.lang.Integer` | `getMinimumSearchLength()` Minimum length in characters before a search is performed.
    `DataSource` | `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.
    `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.
    `static ComboBoxItem` | `getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)`
    `java.lang.String` | `getPendingTextBoxStyle()` Optional "pending" style for this item's text box.
    `NavigationButton` | `getPickerClearButton()` `NavigationButton` to clear the picker value, created when `pickListPlacement` indicates that the search interface takes over the entire panel or screen.
    `java.lang.String` | `getPickerClearButtonTitle()` The title for the `pickerClearButton`.
    `NavigationButton` | `getPickerExitButton()` `NavigationButton` to dismiss the picker interface, created when `pickListPlacement` indicates that the search interface takes over the entire panel or screen.
    `java.lang.String` | `getPickerExitButtonTitle()` The title for the `pickerExitButton`.
    `java.lang.Integer` | `getPickerIconHeight()` Don't specify an explicit height for the picker icon - instead have it size to match the height of the combo box item.
    `java.lang.String` | `getPickerIconSrc()` If `showPickerIcon` is true for this item, this property governs the `src` of the picker icon image to be displayed.
    `NavigationBar` | `getPickerNavigationBar()` `NavigationBar` created when `pickListPlacement` indicates that the search interface takes over the entire panel or screen.
    `NavigationButton` | `getPickerSaveButton()` "Accept" button for `addUnknownValues:true` ComboBoxItems showing the mobile interface.
    `java.lang.String` | `getPickerSaveButtonTitle()` The title for the `pickerSaveButton`.
    `TextItem` | `getPickerSearchField()` The `pickerSearchField` is a separate `TextItem` created for search string entry when `pickListPlacement` indicates that the search interface takes over an entire panel or the entire screen.
    `java.lang.String` | `getPickerSearchFieldHint()` `FormItem.hint` for the `pickerSearchField`.
    `DynamicForm` | `getPickerSearchForm()` Form that contains the `pickerSearchField`.
    `java.lang.String` | `getPickerSearchOrNewValueFieldHint()` `FormItem.hint` for the `pickerSearchField` when the combobox is configured to `allow unknown values`
    `java.lang.String` | `getPickListBaseStyle()` Base Style for pickList cells.
    `int` | `getPickListCellHeight()` Cell Height for this item's pickList.
    `java.lang.String` | `getPickListConstructor()` The Class to use when creating a picker of type "list" for a FormItem.
    `Criteria` | `getPickListCriteria()` If this item has a databound pickList (for example PickList.optionDataSource is set), this property can be used to provide static filter criteria when retrieving the data for the pickList.
    `protected Criteria` | `getPickListFilterCriteria()` Returns filter criteria for options displayed for this item.
    `int` | `getPickListHeaderHeight()` If this pick list is showing multiple fields, this property determines the height of the column headers for those fields.
    `int` | `getPickListHeight()` Maximum height to show the pick list before it starts to scroll.
    `java.lang.Integer` | `getPickListMaxWidth()` Maximum width for this item's pickList.
    `PanelPlacement` | `getPickListPlacement()` Controls where the PickList is placed.
    `Canvas` | `getPickListPlacementAsCanvas()` Controls where the PickList is placed.
    `java.lang.String` | `getPickListPlacementAsString()` Controls where the PickList is placed.
    `java.lang.Integer` | `getPickListWidth()` Default width to show the pickList.
    `java.lang.String` | `getPickTreeConstructor()` The Class to use when creating a picker of type "tree" for a FormItem.
    `java.lang.Boolean` | `getProgressiveLoading()` Indicates whether or not this ComboBoxItem will load its list of options `progressively`.
    `java.lang.String` | `getRootNodeId()` When this item is showing a tree-based picker, this is the `id` of the record to use as the `root` node.
    `java.lang.Integer` | `getRootNodeIdAsInt()` When this item is showing a tree-based picker, this is the `id` of the record to use as the `root` node.
    `java.lang.Boolean` | `getSaveOnEnter()` ComboBox items will submit their containing form on enter keypress if `saveOnEnter` is true.
    `java.lang.String` | `getSearchStringTooShortMessage()` Message to display in pick list when `minimumSearchLength` characters have not been entered.
    `ListGridRecord` | `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).
    `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`.
    `ListGrid` | `getSeparateValuesList()` AutoChild used to show `specialValues`.
    `java.lang.Boolean` | `getShowAllOptions()` If true, even non-matching options will be shown, with configurable `separator rows` in between.
    `java.lang.Boolean` | `getShowHintInField()` If showing a hint for this form item, should it be shown within the field?
    `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.
    `java.lang.Boolean` | `getShowPickerIcon()` Should we show a special 'picker' `icon` for this form item? Picker icons are customizable via `pickerIconProperties`.
    `java.lang.Boolean` | `getShowPickListOnKeypress()` Should the list of options be displayed whenever the user types into the combo-box textArea, or only when the user clicks on the pick button or uses the explicit `Alt+Arrow Down` key combination?
    `boolean` | `getSingleClickFolderToggle()` When this item is showing a tree-based picker, the default behavior is for folder open-state to be toggled by double-clicking.
    `java.lang.String` | `getSortField()` Specifies one or more fields by which this item should be initially sorted.
    `java.lang.Integer` | `getSortFieldAsInt()` Specifies one or more fields by which this item should be initially sorted.
    `java.lang.String[]` | `getSortFieldAsStringArray()` Specifies one or more fields by which this item should be initially sorted.
    `TextMatchStyle` | `getTextMatchStyle()` When applying filter criteria to pickList data, what type of matching to use.
    `java.lang.Boolean` | `getUseClientFiltering()` For `databound` items, this property will be passed to the generated ResultSet data object for the pickList as `ResultSet.useClientFiltering`.
    `java.lang.String` | `getValueAsString()` Return the value tracked by this form item.
    `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()`.
    `java.lang.String` | `getValueFieldName()` Getter method to retrieve the `FormItem.valueField` for this item.
    `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.
    `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.
    `ComboBoxItem` | `setAddUnknownValues(java.lang.Boolean addUnknownValues)` This property controls whether the user can enter a value that is not present in the set of options for this item.
    `ComboBoxItem` | `setAllowEmptyValue(java.lang.Boolean allowEmptyValue)` 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).
    `ComboBoxItem` | `setAllowExpressions(java.lang.Boolean allowExpressions)` The standard `FormItem.allowExpressions` behavior is always disabled for ComboBoxItem.
    `void` | `setAnimatePickList(java.lang.Boolean animatePickList)` If true, when the pickList is shown, it will be shown via an animated reveal effect
    `void` | `setAnimationTime(int animationTime)` If this.animatePickList is true - this specifies the duration of the animation effect applied when showing the pickList
    `ComboBoxItem` | `setAutoFetchData(java.lang.Boolean autoFetchData)` 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.
    `ComboBoxItem` | `setAutoOpenTree(java.lang.String autoOpenTree)` When this item is showing a tree-based picker, which nodes should be opened automatically.
    `ComboBoxItem` | `setCachePickListResults(boolean cachePickListResults)` 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.
    `void` | `setCanEditCriterionPredicate(FormItemCanEditCriterionPredicate predicate)` The default `canEditCriterion()` predicate is overridden in comboBoxItem.
    `ComboBoxItem` | `setCompleteOnEnter(java.lang.Boolean completeOnEnter)` If true, when the pickList is showing, the user can select the current value by hitting the `Enter` key.
    `ComboBoxItem` | `setCompleteOnTab(java.lang.Boolean completeOnTab)` If true, when the pickList is showing, the user can select the current value by hitting the `Tab` key.
    `void` | `setCriterionGetter(FormItemCriterionGetter getter)` The default `getCriterion()` implementation returns criterion derived from the current value of this item.
    `void` | `setCriterionSetter(FormItemCriterionSetter setter)` The default `setCriterion()` implementation is overridden to support editing criterion against the display field or value field when `addUnknownValues` is true.
    `ComboBoxItem` | `setDataSetType(java.lang.String dataSetType)` Whether to show the picker as a flat list, or a collapsible tree.
    `static void` | `setDefaultProperties(ComboBoxItem comboBoxItemProperties)` Class level method to set the default properties of this class.
    `ComboBoxItem` | `setDefaultToFirstOption(java.lang.Boolean defaultToFirstOption)` Select the first option as the default value for this ComboBoxItem.
    `ComboBoxItem` | `setDisplayField(java.lang.String displayField)` If set, this item will display a value from another field to the user instead of showing the underlying data value for the `field name`.
    `ComboBoxItem` | `setEditProxyConstructor(java.lang.String editProxyConstructor)` Default class used to construct the `EditProxy` for this component when the component is `first placed into edit mode`.
    `void` | `setEmptyPickListHeight(int emptyPickListHeight)` Height for an empty pick list (showing the empty message), if the pick list has no records and `hideEmptyPickList` is `false`.
    `ComboBoxItem` | `setEmptyPickListMessage(java.lang.String emptyPickListMessage)` Empty message to display in the comboboxItem if PickList.hideEmptyPickList is `false`.
    `void` | `setFetchDelay(java.lang.Integer fetchDelay)` 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.
    `ComboBoxItem` | `setFetchDisplayedFieldsOnly(java.lang.Boolean fetchDisplayedFieldsOnly)` 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`.
    `ComboBoxItem` | `setFilterFields(java.lang.String... filterFields)` 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.
    `ComboBoxItem` | `setFilterLocally(java.lang.Boolean filterLocally)` 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.
    `ComboBoxItem` | `setFormatOnBlur(java.lang.Boolean formatOnBlur)` 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.
    `ComboBoxItem` | `setGenerateExactMatchCriteria(java.lang.Boolean generateExactMatchCriteria)` 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.
    `void` | `setHideEmptyPickList(java.lang.Boolean hideEmptyPickList)` If this pickList contains no options, should it be hidden? If unset, default behavior is to allow the empty pickList to show if it is databound.
    `ComboBoxItem` | `setIconPlacement(PickListItemIconPlacement iconPlacement)` For PickList items with `PickListItemIconPlacement` set such that the pickList does not render near-origin, should specified `icons` be rendered inline within the formItem itself, or within the `pickerNavigationBar`.
    `ComboBoxItem` | `setInitialSort(SortSpecifier... initialSort)` An array of `SortSpecifier` objects used to set up the initial sort configuration for this pickList.
    `ComboBoxItem` | `setMask(java.lang.String mask)` Not applicable to a ComboBoxItem.
    `ComboBoxItem` | `setMaskOverwriteMode(java.lang.Boolean maskOverwriteMode)` Not applicable to a ComboBoxItem.
    `ComboBoxItem` | `setMaskPadChar(java.lang.String maskPadChar)` Not applicable to a ComboBoxItem.
    `ComboBoxItem` | `setMaskPromptChar(java.lang.String maskPromptChar)` Not applicable to a ComboBoxItem.
    `ComboBoxItem` | `setMaskSaveLiterals(java.lang.Boolean maskSaveLiterals)` Not applicable to a ComboBoxItem.
    `ComboBoxItem` | `setMinimumSearchLength(java.lang.Integer minimumSearchLength)` Minimum length in characters before a search is performed.
    `ComboBoxItem` | `setOptionDataSource(DataSource dataSource)` If set, this FormItem will derive data to show in the PickList by fetching records from the specified `optionDataSource`.
    `void` | `setOptionFilterContext(DSRequest dsRequestProperties)` 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
    `ComboBoxItem` | `setOptionOperationId(java.lang.String optionOperationId)` 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.
    `ComboBoxItem` | `setPendingTextBoxStyle(java.lang.String pendingTextBoxStyle)` Optional "pending" style for this item's text box.
    `ComboBoxItem` | `setPickerClearButtonTitle(java.lang.String pickerClearButtonTitle)` The title for the `pickerClearButton`.
    `ComboBoxItem` | `setPickerExitButtonTitle(java.lang.String pickerExitButtonTitle)` The title for the `pickerExitButton`.
    `ComboBoxItem` | `setPickerIconHeight(java.lang.Integer pickerIconHeight)` Don't specify an explicit height for the picker icon - instead have it size to match the height of the combo box item.
    `ComboBoxItem` | `setPickerIconSrc(java.lang.String pickerIconSrc)` If `showPickerIcon` is true for this item, this property governs the `src` of the picker icon image to be displayed.
    `ComboBoxItem` | `setPickerSaveButtonTitle(java.lang.String pickerSaveButtonTitle)` The title for the `pickerSaveButton`.
    `ComboBoxItem` | `setPickerSearchFieldHint(java.lang.String pickerSearchFieldHint)` `FormItem.hint` for the `pickerSearchField`.
    `ComboBoxItem` | `setPickerSearchOrNewValueFieldHint(java.lang.String pickerSearchOrNewValueFieldHint)` `FormItem.hint` for the `pickerSearchField` when the combobox is configured to `allow unknown values`
    `void` | `setPickListBaseStyle(java.lang.String pickListBaseStyle)` Base Style for pickList cells.
    `void` | `setPickListCellHeight(int pickListCellHeight)` Cell Height for this item's pickList.
    `ComboBoxItem` | `setPickListConstructor(java.lang.String pickListConstructor)` The Class to use when creating a picker of type "list" for a FormItem.
    `ComboBoxItem` | `setPickListCriteria(Criteria pickListCriteria)` If this item has a databound pickList (for example PickList.optionDataSource is set), this property can be used to provide static filter criteria when retrieving the data for the pickList.
    `void` | `setPickListCriteria(DSRequest optionFilterContext)`
    `ComboBoxItem` | `setPickListFields(ListGridField... pickListFields)` This property allows the developer to specify which field[s] will be displayed in the drop down list of options.
    `void` | `setPickListFilterCriteriaFunction(FilterCriteriaFunction filterCriteriaFunction)` Deprecated. in favor of `setPickListFilterCriteriaFunction(FormItemCriteriaFunction)`
    `void` | `setPickListFilterCriteriaFunction(FormItemCriteriaFunction filterCriteriaFunction)` Set up a method to return filter criteria for options displayed for this item.
    `void` | `setPickListHeaderHeight(int pickListHeaderHeight)` If this pick list is showing multiple fields, this property determines the height of the column headers for those fields.
    `void` | `setPickListHeight(int pickListHeight)` Maximum height to show the pick list before it starts to scroll.
    `void` | `setPickListMaxWidth(java.lang.Integer pickListMaxWidth)` Maximum width for this item's pickList.
    `ComboBoxItem` | `setPickListPlacement(Canvas pickListPlacement)` Controls where the PickList is placed.
    `ComboBoxItem` | `setPickListPlacement(PanelPlacement pickListPlacement)` Controls where the PickList is placed.
    `ComboBoxItem` | `setPickListPlacement(java.lang.String pickListPlacement)` Controls where the PickList is placed.
    `void` | `setPickListProperties(ListGrid pickListProperties)` Allows developers to designate a `PickListMenu` as a template containing arbitrary properties to apply to the pickList that will be created for this FormItem.
    `void` | `setPickListSort(SortSpecifier[] sortSpecifiers)` This method sorts the pickList on one or more fields, creating the underlying JS object if needed.
    `void` | `setPickListWidth(java.lang.Integer pickListWidth)` Default width to show the pickList.
    `ComboBoxItem` | `setPickTreeConstructor(java.lang.String pickTreeConstructor)` The Class to use when creating a picker of type "tree" for a FormItem.
    `ComboBoxItem` | `setProgressiveLoading(java.lang.Boolean progressiveLoading)` Indicates whether or not this ComboBoxItem will load its list of options `progressively`.
    `ComboBoxItem` | `setRootNodeId(java.lang.Integer rootNodeId)` When this item is showing a tree-based picker, this is the `id` of the record to use as the `root` node.
    `ComboBoxItem` | `setRootNodeId(java.lang.String rootNodeId)` When this item is showing a tree-based picker, this is the `id` of the record to use as the `root` node.
    `ComboBoxItem` | `setSaveOnEnter(java.lang.Boolean saveOnEnter)` ComboBox items will submit their containing form on enter keypress if `saveOnEnter` is true.
    `ComboBoxItem` | `setSearchStringTooShortMessage(java.lang.String searchStringTooShortMessage)` Message to display in pick list when `minimumSearchLength` characters have not been entered.
    `ComboBoxItem` | `setSeparateSpecialValues(java.lang.Boolean separateSpecialValues)` If true, `specialValues` special values such as the empty value will be shown in a separate non-scrolling area, in the `separateValuesList`.
    `ComboBoxItem` | `setSeparatorRows(ListGridRecord[] separatorRows)` Array of records to show between matching and non-matching rows in the PickList.
    `ComboBoxItem` | `setShowAllOptions(java.lang.Boolean showAllOptions)` If true, even non-matching options will be shown, with configurable `separator rows` in between.
    `ComboBoxItem` | `setShowHintInField(java.lang.Boolean showHintInField)` If showing a hint for this form item, should it be shown within the field?
    `ComboBoxItem` | `setShowOptionsFromDataSource(java.lang.Boolean showOptionsFromDataSource)` 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.
    `ComboBoxItem` | `setShowPickerIcon(java.lang.Boolean showPickerIcon)` Should we show a special 'picker' `icon` for this form item? Picker icons are customizable via `pickerIconProperties`.
    `ComboBoxItem` | `setShowPickListOnKeypress(java.lang.Boolean showPickListOnKeypress)` Should the list of options be displayed whenever the user types into the combo-box textArea, or only when the user clicks on the pick button or uses the explicit `Alt+Arrow Down` key combination?
    `ComboBoxItem` | `setSingleClickFolderToggle(boolean singleClickFolderToggle)` When this item is showing a tree-based picker, the default behavior is for folder open-state to be toggled by double-clicking.
    `void` | `setSort(SortSpecifier[] sortSpecifiers)` Deprecated. in favor of `setPickListSort(SortSpecifier[])` where full documentation can be read.
    `ComboBoxItem` | `setSortField(java.lang.Integer sortField)` Specifies one or more fields by which this item should be initially sorted.
    `ComboBoxItem` | `setSortField(java.lang.String... sortField)` Specifies one or more fields by which this item should be initially sorted.
    `ComboBoxItem` | `setSortField(java.lang.String sortField)` Specifies one or more fields by which this item should be initially sorted.
    `void` | `setSpecialValues(java.util.LinkedHashMap valueMap)` Set the specialValues for this item.
    `void` | `setSpecialValues(java.lang.String... values)` Set the specialValues for this item.
    `ComboBoxItem` | `setTextMatchStyle(TextMatchStyle textMatchStyle)` When applying filter criteria to pickList data, what type of matching to use.
    `ComboBoxItem` | `setUseClientFiltering(java.lang.Boolean useClientFiltering)` For `databound` items, this property will be passed to the generated ResultSet data object for the pickList as `ResultSet.useClientFiltering`.
    `ComboBoxItem` | `setValueField(java.lang.String valueField)` 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()`.
    `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.
    `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?

    - ### Methods inherited from class com.smartgwt.client.widgets.form.fields.TextItem

      `deselectValue, deselectValue, getBrowserAutoCapitalize, getBrowserAutoCorrect, getBrowserInputType, getChangeOnKeypress, getCharacterCasing, getEnforceLength, getEscapeHTML, getFetchMissingValues, getFormatOnFocusChange, getHint, getKeyPressFilter, getLength, getPrintFullText, getSelectionRange, getSelectOnClick, getSelectOnFocus, getShowInputElement, getSupportsCutPasteEvents, getSuppressBrowserClearIcon, getTextBoxStyle, getUsePlaceholderForHint, pendingStatusChanged, selectValue, setBrowserAutoCapitalize, setBrowserAutoCorrect, setBrowserInputType, setChangeOnKeypress, setCharacterCasing, setDefaultProperties, setEnforceLength, setEscapeHTML, setFetchMissingValues, setFormatOnFocusChange, setKeyPressFilter, setLength, setPastedValueTransformer, setPrintFullText, setSelectionRange, setSelectOnClick, setSelectOnFocus, setShowInputElement, setSupportsCutPasteEvents, setSuppressBrowserClearIcon, setTextBoxStyle, setUsePlaceholderForHint, shouldFetchMissingValue`

    - ### Methods inherited from class com.smartgwt.client.widgets.form.fields.FormItem

      `_getValue, addBlurHandler, addChangedHandler, addChangeHandler, addClickHandler, addDoubleClickHandler, addEditorEnterHandler, addEditorExitHandler, addFocusHandler, addIcon, addIcon, addIconClickHandler, addIconKeyPressHandler, addItemHoverHandler, addKeyDownHandler, addKeyPressHandler, addKeyUpHandler, addPendingStatusChangedHandler, addPickerIconClickHandler, addShowContextMenuHandler, addTitleClickHandler, addTitleDoubleClickHandler, addTitleHoverHandler, addValueHoverHandler, addValueIconClickHandler, applyFormula, asSGWTComponent, blurItem, canEditCriterion, clearErrors, clearValue, disable, disableIcon, enable, enableIcon, error, error, errorIfNotCreated, focusAfterItem, focusInItem, getAccessKey, getAlign, getAlwaysFetchMissingValues, getAlwaysShowControlBox, getApplyAlignToText, getApplyHeightToTextBox, getAriaRole, getAttribute, getAttributeAsBoolean, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsObject, getAttributeAsString, getAutoComplete, getAutoCompleteKeywords, getBrowserSpellCheck, getCanEdit, getCanEditOpaqueValues, getCanFocus, getCanSelectText, getCanTabToIcons, getCanvasAutoChild, getCellHeight, getCellStyle, getClassName, getClipStaticValue, getClipTitle, getConfig, getContainerWidget, getControlStyle, getCriteriaField, getCriterion, getCriterion, getCursorPosition, getCustomState, getDataPath, getDateFormatter, getDecimalPad, getDecimalPrecision, getDefaultIconSrc, getDefaultOperator, getDestroyed, getDisabled, getDisabledHover, getDisableIconsOnReadOnly, getDisplayValue, getDisplayValue, getEditorTypeConfig, getEditPendingCSSText, getEmptyDisplayValue, getEmptyValueIcon, getEndRow, getErrorIconHeight, getErrorIconSrc, getErrorIconWidth, getErrorMessageWidth, getErrors, getExportFormat, getFieldName, getForeignDisplayField, getForm, getFormat, getFormItemAutoChild, getFormula, getFullDataPath, getGlobalTabIndex, getGridColNum, getGridRowNum, getHeight, getHeightAsString, getHidden, getHintStyle, getHoverAlign, getHoverDelay, getHoverHeight, getHoverHeightAsString, getHoverOpacity, getHoverStyle, getHoverVAlign, getHoverWidth, getHoverWidthAsString, getIcon, getIconHeight, getIconHSpace, getIconPageRect, getIconPrompt, getIconRect, getIcons, getIconTabPosition, getIconVAlign, getIconWidth, getID, getImageURLPrefix, getImageURLSuffix, getImplicitSave, getImplicitSaveOnBlur, getInputFormat, getLeft, getListGrid, getLoadingDisplayValue, getLocateItemBy, getMinHintWidth, getMultiple, getMultipleValueSeparator, getName, getNullOriginalValueText, getOperator, getOptionCriteria, getOptionDataSourceAsString, getOptionFilterContext, getOptionTextMatchStyle, getOriginalValueMessage, getPageLeft, getPageRect, getPageTop, getPaletteDefaults, getPicker, getPickerIcon, getPickerIcon, getPickerIconName, getPickerIconPrompt, getPickerIconProperties, getPickerIconStyle, getPickerIconTabPosition, getPickerIconWidth, getPixelHeight, getPixelWidth, getPrintReadOnlyTextBoxStyle, getPrintTextBoxStyle, getPrintTitleStyle, getPrompt, getReadOnlyCanSelectText, getReadOnlyDisplay, getReadOnlyHover, getReadOnlyTextBoxStyle, getReadOnlyWhen, getRect, getRedrawOnChange, getRejectInvalidValueOnChange, getRequired, getRequiredMessage, getRequiredWhen, getRowSpan, getScClassName, getShouldSaveValue, getShowClippedTitleOnHover, getShowClippedValueOnHover, getShowDeletions, getShowDisabled, getShowDisabledIconsOnFocus, getShowDisabledPickerIconOnFocus, getShowErrorIcon, getShowErrorStyle, getShowErrorText, getShowFocused, getShowFocusedErrorState, getShowFocusedIcons, getShowFocusedPickerIcon, getShowHint, getShowIcons, getShowIconsOnFocus, getShowImageAsURL, getShowOldValueInHover, getShowOver, getShowOverIcons, getShowPending, getShowPickerIconOnFocus, getShowRTL, getShowTitle, getShowValueIconOnly, getStartRow, getStaticHeight, getStopOnError, getStoreDisplayValues, getSuppressValueIcon, getSynchronousValidation, getTabIndex, getTextAlign, getTextFormula, getTimeFormatter, getTitle, getTitleAlign, getTitleColSpan, getTitleOrientation, getTitleStyle, getTitleVAlign, getTooltip, getTop, getType, getUpdateControlOnOver, getUpdatePickerIconOnOver, getUpdateTextBoxOnOver, getUseAdvancedCriteria, getUseDisabledHintStyleForReadOnly, getUseLocalDisplayFieldValue, getValidateOnChange, getValidateOnExit, getValidOperators, getVAlign, getValue, getValueAsInteger, getValueAsLong, getValueAsRecordList, getValueDeselectedCSSText, getValueIconHeight, getValueIconLeftPadding, getValueIconRightPadding, getValueIconSize, getValueIconWidth, getValueMap, getValueMapAsArray, getVisible, getVisibleHeight, getVisibleTitleWidth, getVisibleWhen, getVisibleWidth, getWarnOnEditorTypeConversion, getWarnOnEditorTypeConversionDefault, getWidth, getWidthAsString, getWrapHintText, getWrapTitle, handleWarnOnEditorTypeConversion, hasErrors, hide, hideIcon, invalidateDisplayValueCache, isConfigOnly, isCreated, isCutEvent, isDisabled, isDrawn, isFocused, isInGrid, isPasteEvent, isVisible, linkToInstanceUponCreate, mapDisplayToValue, mapValueToDisplay, mapValueToDisplay, mapValueToDisplay, redraw, redraw, removeIcon, selectedRecordChanged, setAccessKey, setAlign, setAlwaysFetchMissingValues, setAlwaysShowControlBox, setApplyAlignToText, setApplyHeightToTextBox, setAriaRole, setAriaState, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAutoChildConstructor, setAutoChildProperties, setAutoChildProperties, setAutoChildProperties, setAutoChildVisibility, setAutoComplete, setAutoCompleteKeywords, setBrowserSpellCheck, setCanEdit, setCanEditOpaqueValues, setCanFocus, setCanSelectText, setCanTabToIcons, setCellHeight, setCellStyle, setClipStaticValue, setClipTitle, setColSpan, setColSpan, setConfigOnly, setControlStyle, setCriteriaField, setCriterion, setCustomStateGetter, setDataPath, setDateFormatter, setDecimalPad, setDecimalPrecision, setDefaultIconSrc, setDefaultOperator, setDefaultProperties, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDisabled, setDisabledHover, setDisableIconsOnReadOnly, setDisplayFormat, setDisplayFormat, setEditorProperties, setEditorType, setEditorType, setEditorType, setEditorValueFormatter, setEditorValueParser, setEditPendingCSSText, setEmptyDisplayValue, setEmptyValueIcon, setEndRow, setErrorFormatter, setErrorIconHeight, setErrorIconSrc, setErrorIconWidth, setErrorMessageWidth, setErrorOrientation, setErrors, setErrors, setExportFormat, setForeignDisplayField, setFormat, setFormula, setGlobalTabIndex, setHeight, setHeight, setHidden, setHint, setHintStyle, setHoverAlign, setHoverDelay, setHoverHeight, setHoverHeight, setHoverOpacity, setHoverStyle, setHoverVAlign, setHoverWidth, setHoverWidth, setIconDisabled, setIconHeight, setIconHSpace, setIconPrompt, setIcons, setIconShowOnFocus, setIconVAlign, setIconWidth, setID, setImageURLPrefix, setImageURLSuffix, setImplicitSave, setImplicitSaveOnBlur, setInitHandler, setInputFormat, setInputTransformer, setItemHoverFormatter, setItemTitleHoverFormatter, setItemValueHoverFormatter, setJavaScriptObject, setLeft, setLoadingDisplayValue, setLocateItemBy, setMinHintWidth, setMultiple, setMultipleValueSeparator, setName, setNullOriginalValueText, setNullProperty, setOperator, setOptionCriteria, setOptionDataSource, setOptionFilterContext, setOptionTextMatchStyle, setOriginalValueMessage, setPickerIconName, setPickerIconPrompt, setPickerIconProperties, setPickerIconStyle, setPickerIconWidth, setPrintReadOnlyTextBoxStyle, setPrintTextBoxStyle, setPrintTitleStyle, setPrompt, setProperty, setProperty, setProperty, setProperty, setProperty, setReadOnlyCanSelectText, setReadOnlyDisplay, setReadOnlyHover, setReadOnlyTextBoxStyle, setReadOnlyWhen, setRedrawOnChange, setRejectInvalidValueOnChange, setRequired, setRequiredMessage, setRequiredWhen, setRowSpan, setScClassName, setShouldSaveValue, setShowClippedTitleOnHover, setShowClippedValueOnHover, setShowDeletions, setShowDisabled, setShowDisabledIconsOnFocus, setShowDisabledPickerIconOnFocus, setShowErrorIcon, setShowErrorStyle, setShowErrorText, setShowFocused, setShowFocusedErrorState, setShowFocusedIcons, setShowFocusedPickerIcon, setShowHint, setShowIcons, setShowIconsOnFocus, setShowIfCondition, setShowImageAsURL, setShowOldValueInHover, setShowOver, setShowOverIcons, setShowPending, setShowPickerIconOnFocus, setShowRTL, setShowTitle, setShowValueIconOnly, setStartRow, setStateCustomizer, setStaticHeight, setStopOnError, setStoreDisplayValues, setSuppressValueIcon, setSynchronousValidation, setTabIndex, setTextAlign, setTextFormula, setTimeFormatter, setTitle, setTitleAlign, setTitleColSpan, setTitleHoverFormatter, setTitleOrientation, setTitleStyle, setTitleVAlign, setTooltip, setTop, setType, setUpdateControlOnOver, setUpdatePickerIconOnOver, setUpdateTextBoxOnOver, setUseAdvancedCriteria, setUseDisabledHintStyleForReadOnly, setUseLocalDisplayFieldValue, setValidateOnChange, setValidateOnExit, setValidators, setValidOperators, setVAlign, setValue, setValue, setValue, setValue, setValue, setValue, setValueDeselectedCSSText, setValueFormatter, setValueHoverFormatter, setValueIconHeight, setValueIconLeftPadding, setValueIconMapper, setValueIconRightPadding, setValueIcons, setValueIconSize, setValueIconWidth, setValueMap, setValueMap, setVisible, setVisibleWhen, setWarnOnEditorTypeConversion, setWarnOnEditorTypeConversionDefault, setWidth, setWidth, setWrapHintText, setWrapTitle, shouldApplyHeightToTextBox, shouldSaveOnEnter, shouldStopKeyPressBubbling, show, showIcon, showPicker, stopHover, storeValue, storeValue, updateState, validate, valueClipped`

    - ### Methods inherited from class com.smartgwt.client.core.RefDataClass

      `getRef, getRef, internalSetID`

    - ### Methods inherited from class com.smartgwt.client.core.DataClass

      `applyFactoryProperties, doAddHandler, fireEvent, getAttributeAsDoubleArray, getAttributeAsIntArray, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsStringArray, getAttributes, getHandlerCount, isFactoryCreated, setAttribute, setAttribute, setAttribute, setAttributeAsJavaObject, setFactoryCreated`

    - ### Methods inherited from class com.smartgwt.client.core.JsObject

      `equals, getJsObj, hashCode, setJsObj`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

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

      `fireEvent`

- - ### Constructor Detail

    - #### ComboBoxItem

          public ComboBoxItem()

    - #### ComboBoxItem

          public ComboBoxItem(com.google.gwt.core.client.JavaScriptObject jsObj)

    - #### ComboBoxItem

          public ComboBoxItem(java.lang.String name)

    - #### ComboBoxItem

          public ComboBoxItem(java.lang.String name,
                              java.lang.String title)

  - ### Method Detail

    - #### getOrCreateRef

          public static ComboBoxItem getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)

    - #### changeAutoChildDefaults

          public static void changeAutoChildDefaults(java.lang.String autoChildName,
                                                     Canvas defaults)

      Changes the defaults for Canvas AutoChildren named `autoChildName`.
      Parameters:
        `autoChildName` - name of an AutoChild to customize the defaults for.
        `defaults` - Canvas defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see `SGWTProperties`.
      See Also:
        `AutoChildUsage`

    - #### changeAutoChildDefaults

          public static void changeAutoChildDefaults(java.lang.String autoChildName,
                                                     FormItem defaults)

      Changes the defaults for FormItem AutoChildren named `autoChildName`.
      Parameters:
        `autoChildName` - name of an AutoChild to customize the defaults for.
        `defaults` - FormItem defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see `SGWTProperties`.
      See Also:
        `AutoChildUsage`

    - #### changePickerIconDefaults

          public static void changePickerIconDefaults(FormItemIcon defaults)

    - #### setAddUnknownValues

          public ComboBoxItem setAddUnknownValues(java.lang.Boolean addUnknownValues)

      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.

      Parameters:
        `addUnknownValues` - New addUnknownValues value. Default value is true
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getAddUnknownValues

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

          public ComboBoxItem setAllowEmptyValue(java.lang.Boolean allowEmptyValue)

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

      Parameters:
        `allowEmptyValue` - New allowEmptyValue value. Default value is true
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### 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

          public ComboBoxItem setAllowExpressions(java.lang.Boolean allowExpressions)

      The standard `FormItem.allowExpressions` behavior is always disabled for ComboBoxItem.

      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.

      Overrides:
        `setAllowExpressions` in class `FormItem`
      Parameters:
        `allowExpressions` - New allowExpressions value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `AdvancedFilter overview and related methods`

    - #### getAllowExpressions

          public java.lang.Boolean getAllowExpressions()

      The standard `FormItem.allowExpressions` behavior is always disabled for ComboBoxItem.

      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.

      Overrides:
        `getAllowExpressions` in class `FormItem`
      Returns:
        Current allowExpressions value. Default value is null
      See Also:
        `AdvancedFilter overview and related methods`

    - #### setAutoFetchData

          public ComboBoxItem setAutoFetchData(java.lang.Boolean autoFetchData)

      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.

      Note : This is an advanced setting

      Parameters:
        `autoFetchData` - New autoFetchData value. Default value is false
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### 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.
      Returns:
        Current autoFetchData value. Default value is false

    - #### setAutoOpenTree

          public ComboBoxItem setAutoOpenTree(java.lang.String autoOpenTree)

      When this item is showing a tree-based picker, which nodes should be opened automatically. Options are:
      - "none" - no nodes are opened automatically
      - "root" - opens the top-level node - in databound tree-pickers, this node is always hidden
      - "all" - when `loading data on demand`, opens the top-level node and all of it's direct descendants - otherwise, opens all loaded nodes
      Parameters:
        `autoOpenTree` - New autoOpenTree value. Default value is "none"
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getAutoOpenTree

          public java.lang.String getAutoOpenTree()

      When this item is showing a tree-based picker, which nodes should be opened automatically. Options are:
      - "none" - no nodes are opened automatically
      - "root" - opens the top-level node - in databound tree-pickers, this node is always hidden
      - "all" - when `loading data on demand`, opens the top-level node and all of it's direct descendants - otherwise, opens all loaded nodes
      Returns:
        Current autoOpenTree value. Default value is "none"

    - #### setCachePickListResults

          public ComboBoxItem setCachePickListResults(boolean cachePickListResults)

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

      Parameters:
        `cachePickListResults` - New cachePickListResults value. Default value is true
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### 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`.

      Returns:
        Current cachePickListResults value. Default value is true

    - #### setCompleteOnEnter

          public ComboBoxItem setCompleteOnEnter(java.lang.Boolean completeOnEnter)

      If true, when the pickList is showing, the user can select the current value by hitting the `Enter` key.

      If not explicitly set, completeOnEnter will default to false for items embedded in a `filtering interface`, true otherwise.

      Parameters:
        `completeOnEnter` - New completeOnEnter value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getCompleteOnEnter

          public java.lang.Boolean getCompleteOnEnter()

      If true, when the pickList is showing, the user can select the current value by hitting the `Enter` key.

      If not explicitly set, completeOnEnter will default to false for items embedded in a `filtering interface`, true otherwise.

      Returns:
        Current completeOnEnter value. Default value is null

    - #### setCompleteOnTab

          public ComboBoxItem setCompleteOnTab(java.lang.Boolean completeOnTab)

      If true, when the pickList is showing, the user can select the current value by hitting the `Tab` key.

      Note that `completeOnTab` is not compatible with `formatOnBlur`

      Parameters:
        `completeOnTab` - New completeOnTab value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getCompleteOnTab

          public java.lang.Boolean getCompleteOnTab()

      If true, when the pickList is showing, the user can select the current value by hitting the `Tab` key.

      Note that `completeOnTab` is not compatible with `formatOnBlur`

      Returns:
        Current completeOnTab value. Default value is null

    - #### setDataSetType

          public ComboBoxItem setDataSetType(java.lang.String dataSetType)

      Whether to show the picker as a flat list, or a collapsible tree.

      The default value, "list", will use an instance of the pickListConstructor as the picker - "tree" will show an instance of pickTreeConstructor.

      Parameters:
        `dataSetType` - New dataSetType value. Default value is "list"
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getDataSetType

          public java.lang.String getDataSetType()

      Whether to show the picker as a flat list, or a collapsible tree.

      The default value, "list", will use an instance of the pickListConstructor as the picker - "tree" will show an instance of pickTreeConstructor.

      Returns:
        Current dataSetType value. Default value is "list"

    - #### setDefaultToFirstOption

          public ComboBoxItem setDefaultToFirstOption(java.lang.Boolean defaultToFirstOption)

      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()`.
      Parameters:
        `defaultToFirstOption` - New defaultToFirstOption value. Default value is false
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### 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.
      Returns:
        Current defaultValue value. Default value is null

    - #### setDisplayField

          public ComboBoxItem setDisplayField(java.lang.String displayField)

      If set, this item will display a value from another field to the user instead of showing the underlying data value for the `field name`.

      This property is used in two ways:

      The item will display the displayField value from the `record currently being edited` if `FormItem.useLocalDisplayFieldValue` is true, (or if unset and the conditions outlined in the documentation for that property are met).

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

      If `local display values` are being used and `FormItem.storeDisplayValues` is true, selecting a new value will update both the value for this field and the associated display-field value on the record being edited.

      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.
      If a foreignDisplayField is specified, as with just displayField, if `local display values` are being used and `FormItem.storeDisplayValues` is true, when the user chooses a value the associated display-field value on the record being edited will be updated. In this case it would be set to the foreignDisplayField value from the related record. This means foreignDisplayField is always expected to be set to the equivalent field in the related dataSources.
      Developers looking to display some other arbitrary field(s) from the related dataSource during editing should consider using custom PickList.pickListFields instead of setting a foreignDisplayField.

      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.

      Specified by:
        `setDisplayField` in interface `PickList`
      Overrides:
        `setDisplayField` in class `FormItem`
      Parameters:
        `displayField` - New displayField value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `FormItem.getDisplayFieldName()`, `FormItem.invalidateDisplayValueCache()`, `Databinding overview and related methods`

    - #### getDisplayField

          public java.lang.String getDisplayField()

      If set, this item will display a value from another field to the user instead of showing the underlying data value for the `field name`.

      This property is used in two ways:

      The item will display the displayField value from the `record currently being edited` if `FormItem.useLocalDisplayFieldValue` is true, (or if unset and the conditions outlined in the documentation for that property are met).

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

      If `local display values` are being used and `FormItem.storeDisplayValues` is true, selecting a new value will update both the value for this field and the associated display-field value on the record being edited.

      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.
      If a foreignDisplayField is specified, as with just displayField, if `local display values` are being used and `FormItem.storeDisplayValues` is true, when the user chooses a value the associated display-field value on the record being edited will be updated. In this case it would be set to the foreignDisplayField value from the related record. This means foreignDisplayField is always expected to be set to the equivalent field in the related dataSources.
      Developers looking to display some other arbitrary field(s) from the related dataSource during editing should consider using custom PickList.pickListFields instead of setting a foreignDisplayField.

      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.

      Specified by:
        `getDisplayField` in interface `PickList`
      Overrides:
        `getDisplayField` in class `FormItem`
      Returns:
        Returns the `displayField` for this item.

        Behavior varies based on the configuration of this item, as follows:

        - If this item has an `optionDataSource` and an explicit `FormItem.foreignDisplayField` is specified, this will be returned.
        - 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 foreignDisplayField 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`.
        . Default value is null
      See Also:
        `FormItem.getDisplayFieldName()`, `FormItem.invalidateDisplayValueCache()`, `Databinding overview and related methods`

    - #### setEditProxyConstructor

          public ComboBoxItem setEditProxyConstructor(java.lang.String editProxyConstructor)

      Default class used to construct the `EditProxy` for this component when the component is `first placed into edit mode`.
      Overrides:
        `setEditProxyConstructor` in class `TextItem`
      Parameters:
        `editProxyConstructor` - New editProxyConstructor value. Default value is "SelectItemEditProxy"
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `SCClassName`

    - #### getEditProxyConstructor

          public java.lang.String getEditProxyConstructor()

      Default class used to construct the `EditProxy` for this component when the component is `first placed into edit mode`.
      Overrides:
        `getEditProxyConstructor` in class `TextItem`
      Returns:
        Current editProxyConstructor value. Default value is "SelectItemEditProxy"
      See Also:
        `SCClassName`

    - #### setEmptyPickListMessage

          public ComboBoxItem setEmptyPickListMessage(java.lang.String emptyPickListMessage)

      Empty message to display in the comboboxItem if PickList.hideEmptyPickList is `false`.

      Note : This is an advanced setting

      Specified by:
        `setEmptyPickListMessage` in interface `PickList`
      Parameters:
        `emptyPickListMessage` - New emptyPickListMessage value. Default value is "No items to show"
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getEmptyPickListMessage

          public java.lang.String getEmptyPickListMessage()

      Empty message to display in the comboboxItem if PickList.hideEmptyPickList is `false`.
      Specified by:
        `getEmptyPickListMessage` in interface `PickList`
      Returns:
        Current emptyPickListMessage value. Default value is "No items to show"

    - #### setFetchDisplayedFieldsOnly

          public ComboBoxItem setFetchDisplayedFieldsOnly(java.lang.Boolean fetchDisplayedFieldsOnly)

      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.

      This list of used fields consists of the values of `valueField`, `displayField` and `pickListFields`.

      NOTE: When enabled, `getSelectedRecord` will only include the fetched fields.

      Note : This is an advanced setting

      Parameters:
        `fetchDisplayedFieldsOnly` - New fetchDisplayedFieldsOnly value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

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

      This list of used fields consists of the values of `valueField`, `displayField` and `pickListFields`.

      NOTE: When enabled, `getSelectedRecord` will only include the fetched fields.

      Returns:
        Current fetchDisplayedFieldsOnly value. Default value is null

    - #### setFilterFields

          public ComboBoxItem setFilterFields(java.lang.String... filterFields)

      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.

      Parameters:
        `filterFields` - New filterFields value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `PickList overview and related methods`

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

      Returns:
        Current filterFields value. Default value is null
      See Also:
        `PickList overview and related methods`

    - #### setFilterLocally

          public ComboBoxItem setFilterLocally(java.lang.Boolean filterLocally)

      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.

      Note : This is an advanced setting

      Specified by:
        `setFilterLocally` in interface `PickList`
      Overrides:
        `setFilterLocally` in class `FormItem`
      Parameters:
        `filterLocally` - New filterLocally value. Default value is false
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `FormItem.setFilterLocally(java.lang.Boolean)`

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

      Specified by:
        `getFilterLocally` in interface `PickList`
      Overrides:
        `getFilterLocally` in class `FormItem`
      Returns:
        Current filterLocally value. Default value is false
      See Also:
        `FormItem.getFilterLocally()`

    - #### 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()`.
      Returns:
        Current filterWithValue value. Default value is varies
      See Also:
        `getPickListFilterCriteria()`, `getFilterFields()`

    - #### setFormatOnBlur

          public ComboBoxItem setFormatOnBlur(java.lang.Boolean formatOnBlur)

      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.

      Note that this attribute is not compatible with `completeOnTab`

      Overrides:
        `setFormatOnBlur` in class `TextItem`
      Parameters:
        `formatOnBlur` - New formatOnBlur value. Default value is false
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

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

      Note that this attribute is not compatible with `completeOnTab`

      Overrides:
        `getFormatOnBlur` in class `TextItem`
      Returns:
        Current formatOnBlur value. Default value is false

    - #### setGenerateExactMatchCriteria

          public ComboBoxItem setGenerateExactMatchCriteria(java.lang.Boolean generateExactMatchCriteria)

      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.

      See `shouldGenerateExactMatchCriteria()` for behavior when this flag is unset.

      Note : This is an advanced setting

      Parameters:
        `generateExactMatchCriteria` - New generateExactMatchCriteria value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

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

      See `shouldGenerateExactMatchCriteria()` for behavior when this flag is unset.

      Returns:
        Current generateExactMatchCriteria value. Default value is null

    - #### setIconPlacement

          public ComboBoxItem setIconPlacement(PickListItemIconPlacement iconPlacement)

      For PickList items with `PickListItemIconPlacement` set such that the pickList does not render near-origin, should specified `icons` be rendered inline within the formItem itself, or within the `pickerNavigationBar`.

      May be overridden at the icon level via `FormItemIcon.iconPlacement`.

      For mobile browsing with limited available screen space, icons rendered in the navigation bar may be easier for the user to interact with.

      Parameters:
        `iconPlacement` - New iconPlacement value. Default value is "both"
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getIconPlacement

          public PickListItemIconPlacement getIconPlacement()

      For PickList items with `PickListItemIconPlacement` set such that the pickList does not render near-origin, should specified `icons` be rendered inline within the formItem itself, or within the `pickerNavigationBar`.

      May be overridden at the icon level via `FormItemIcon.iconPlacement`.

      For mobile browsing with limited available screen space, icons rendered in the navigation bar may be easier for the user to interact with.

      Returns:
        Current iconPlacement value. Default value is "both"

    - #### setInitialSort

          public ComboBoxItem setInitialSort(SortSpecifier... initialSort)

      An array of `SortSpecifier` objects used to set up the initial sort configuration for this pickList. If specified, this will be used instead of any PickList.sortField specified.
      Parameters:
        `initialSort` - New initialSort value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getInitialSort

          public SortSpecifier[] getInitialSort()

      An array of `SortSpecifier` objects used to set up the initial sort configuration for this pickList. If specified, this will be used instead of any PickList.sortField specified.
      Returns:
        Current initialSort value. Default value is null

    - #### setMask

          public ComboBoxItem setMask(java.lang.String mask)

      Not applicable to a ComboBoxItem.

      Note : This is an advanced setting

      Overrides:
        `setMask` in class `TextItem`
      Parameters:
        `mask` - New mask value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `TextItem.setKeyPressFilter(java.lang.String)`, Text - Masked Example

    - #### getMask

          public java.lang.String getMask()

      Not applicable to a ComboBoxItem.
      Overrides:
        `getMask` in class `TextItem`
      Returns:
        Current mask value. Default value is null
      See Also:
        `TextItem.getKeyPressFilter()`, Text - Masked Example

    - #### setMaskOverwriteMode

          public ComboBoxItem setMaskOverwriteMode(java.lang.Boolean maskOverwriteMode)

      Not applicable to a ComboBoxItem.

      Note : This is an advanced setting

      Overrides:
        `setMaskOverwriteMode` in class `TextItem`
      Parameters:
        `maskOverwriteMode` - New maskOverwriteMode value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getMaskOverwriteMode

          public java.lang.Boolean getMaskOverwriteMode()

      Not applicable to a ComboBoxItem.
      Overrides:
        `getMaskOverwriteMode` in class `TextItem`
      Returns:
        Current maskOverwriteMode value. Default value is null

    - #### setMaskPadChar

          public ComboBoxItem setMaskPadChar(java.lang.String maskPadChar)

      Not applicable to a ComboBoxItem.

      Note : This is an advanced setting

      Overrides:
        `setMaskPadChar` in class `TextItem`
      Parameters:
        `maskPadChar` - New maskPadChar value. Default value is " "
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getMaskPadChar

          public java.lang.String getMaskPadChar()

      Not applicable to a ComboBoxItem.
      Overrides:
        `getMaskPadChar` in class `TextItem`
      Returns:
        Current maskPadChar value. Default value is " "

    - #### setMaskPromptChar

          public ComboBoxItem setMaskPromptChar(java.lang.String maskPromptChar)

      Not applicable to a ComboBoxItem.

      Note : This is an advanced setting

      Overrides:
        `setMaskPromptChar` in class `TextItem`
      Parameters:
        `maskPromptChar` - New maskPromptChar value. Default value is "_"
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getMaskPromptChar

          public java.lang.String getMaskPromptChar()

      Not applicable to a ComboBoxItem.
      Overrides:
        `getMaskPromptChar` in class `TextItem`
      Returns:
        Current maskPromptChar value. Default value is "_"

    - #### setMaskSaveLiterals

          public ComboBoxItem setMaskSaveLiterals(java.lang.Boolean maskSaveLiterals)

      Not applicable to a ComboBoxItem.

      Note : This is an advanced setting

      Overrides:
        `setMaskSaveLiterals` in class `TextItem`
      Parameters:
        `maskSaveLiterals` - New maskSaveLiterals value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getMaskSaveLiterals

          public java.lang.Boolean getMaskSaveLiterals()

      Not applicable to a ComboBoxItem.
      Overrides:
        `getMaskSaveLiterals` in class `TextItem`
      Returns:
        Current maskSaveLiterals value. Default value is null

    - #### setMinimumSearchLength

          public ComboBoxItem setMinimumSearchLength(java.lang.Integer minimumSearchLength)

      Minimum length in characters before a search is performed. If too few characters are entered the pick list shows `searchStringTooShortMessage`.

      Note : This is an advanced setting

      Parameters:
        `minimumSearchLength` - New minimumSearchLength value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getMinimumSearchLength

          public java.lang.Integer getMinimumSearchLength()

      Minimum length in characters before a search is performed. If too few characters are entered the pick list shows `searchStringTooShortMessage`.
      Returns:
        Current minimumSearchLength value. Default value is null

    - #### setOptionOperationId

          public ComboBoxItem setOptionOperationId(java.lang.String optionOperationId)

      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.
      Overrides:
        `setOptionOperationId` in class `FormItem`
      Parameters:
        `optionOperationId` - New optionOperationId value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `Databinding overview and related methods`

    - #### 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.
      Overrides:
        `getOptionOperationId` in class `FormItem`
      Returns:
        Current optionOperationId value. Default value is null
      See Also:
        `Databinding overview and related methods`

    - #### setPendingTextBoxStyle

          public ComboBoxItem setPendingTextBoxStyle(java.lang.String pendingTextBoxStyle)

      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.

      Parameters:
        `pendingTextBoxStyle` - New pendingTextBoxStyle value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `CSSStyleName`

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

      Returns:
        Current pendingTextBoxStyle value. Default value is null
      See Also:
        `CSSStyleName`

    - #### getPickerClearButton

          public NavigationButton getPickerClearButton()

      `NavigationButton` to clear the picker value, created when `pickListPlacement` indicates that the search interface takes over the entire panel or screen.

      This button will only be shown if `addUnknownValues` or `allowEmptyValue` is true.

      The following `passthroughs` apply:

      - `pickerClearButtonTitle` for `Button.title`

      This component is an AutoChild named "pickerClearButton". For an overview of how to use and configure AutoChildren, see `Using AutoChildren`.

      Returns:
        Current pickerClearButton value. Default value is null

    - #### setPickerClearButtonTitle

          public ComboBoxItem setPickerClearButtonTitle(java.lang.String pickerClearButtonTitle)

      The title for the `pickerClearButton`.
      Parameters:
        `pickerClearButtonTitle` - New pickerClearButtonTitle value. Default value is "Clear"
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `HTMLString`

    - #### getPickerClearButtonTitle

          public java.lang.String getPickerClearButtonTitle()

      The title for the `pickerClearButton`.
      Returns:
        Current pickerClearButtonTitle value. Default value is "Clear"
      See Also:
        `HTMLString`

    - #### getPickerExitButton

          public NavigationButton getPickerExitButton()

      `NavigationButton` to dismiss the picker interface, created when `pickListPlacement` indicates that the search interface takes over the entire panel or screen.

      The following `passthroughs` apply:

      - `pickerExitButtonTitle` for `Button.title`

      This component is an AutoChild named "pickerExitButton". For an overview of how to use and configure AutoChildren, see `Using AutoChildren`.

      Returns:
        Current pickerExitButton value. Default value is null

    - #### setPickerExitButtonTitle

          public ComboBoxItem setPickerExitButtonTitle(java.lang.String pickerExitButtonTitle)

      The title for the `pickerExitButton`.
      Parameters:
        `pickerExitButtonTitle` - New pickerExitButtonTitle value. Default value is "Cancel"
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `HTMLString`

    - #### getPickerExitButtonTitle

          public java.lang.String getPickerExitButtonTitle()

      The title for the `pickerExitButton`.
      Returns:
        Current pickerExitButtonTitle value. Default value is "Cancel"
      See Also:
        `HTMLString`

    - #### setPickerIconHeight

          public ComboBoxItem setPickerIconHeight(java.lang.Integer pickerIconHeight)

      Don't specify an explicit height for the picker icon - instead have it size to match the height of the combo box item.

      Note : This is an advanced setting

      Overrides:
        `setPickerIconHeight` in class `FormItem`
      Parameters:
        `pickerIconHeight` - New pickerIconHeight value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getPickerIconHeight

          public java.lang.Integer getPickerIconHeight()

      Don't specify an explicit height for the picker icon - instead have it size to match the height of the combo box item.
      Overrides:
        `getPickerIconHeight` in class `FormItem`
      Returns:
        Current pickerIconHeight value. Default value is null

    - #### setPickerIconSrc

          public ComboBoxItem setPickerIconSrc(java.lang.String pickerIconSrc)

      If `showPickerIcon` is true for this item, this property governs the `src` of the picker icon image to be displayed.

      When `spriting` is enabled, this property will not be used to locate an image, instead, the image is drawn via CSS based on the `FormItem.pickerIconStyle` property.

      Note : This is an advanced setting

      Overrides:
        `setPickerIconSrc` in class `FormItem`
      Parameters:
        `pickerIconSrc` - New pickerIconSrc value. Default value is "[SKIN]/DynamicForm/ComboBoxItem_PickButton_icon.gif"
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `SCImgURL`

    - #### getPickerIconSrc

          public java.lang.String getPickerIconSrc()

      If `showPickerIcon` is true for this item, this property governs the `src` of the picker icon image to be displayed.

      When `spriting` is enabled, this property will not be used to locate an image, instead, the image is drawn via CSS based on the `FormItem.pickerIconStyle` property.

      Overrides:
        `getPickerIconSrc` in class `FormItem`
      Returns:
        Current pickerIconSrc value. Default value is "[SKIN]/DynamicForm/ComboBoxItem_PickButton_icon.gif"
      See Also:
        `SCImgURL`

    - #### getPickerNavigationBar

          public NavigationBar getPickerNavigationBar()

      `NavigationBar` created when `pickListPlacement` indicates that the search interface takes over the entire panel or screen.

      This component is an AutoChild named "pickerNavigationBar". For an overview of how to use and configure AutoChildren, see `Using AutoChildren`.

      Returns:
        Current pickerNavigationBar value. Default value is null

    - #### getPickerSaveButton

          public NavigationButton getPickerSaveButton()

      "Accept" button for `addUnknownValues:true` ComboBoxItems showing the mobile interface.

      The pickerSaveButton is an automatically created `NavigationButton` autoChild to dismiss the picker interface and store out the value entered in the `pickerSearchField`, created when `pickListPlacement` indicates that the search interface takes over the entire panel or screen.

      This button will only be shown when `addUnknownValues` is true. Note that if a user has entered a partial known value, the pickList will show a filtered list of possible matches. An "Enter" keypress (or native keyboard "Done" button click on a mobile browser keyboard) will select the first match from the list. The pickerSaveButton provides a way for users to explicitly use the value as entered instead.

      The following `passthroughs` apply:

      - `pickerSaveButtonTitle` for `Button.title`

      This component is an AutoChild named "pickerSaveButton". For an overview of how to use and configure AutoChildren, see `Using AutoChildren`.

      Returns:
        Current pickerSaveButton value. Default value is null

    - #### setPickerSaveButtonTitle

          public ComboBoxItem setPickerSaveButtonTitle(java.lang.String pickerSaveButtonTitle)

      The title for the `pickerSaveButton`.
      Parameters:
        `pickerSaveButtonTitle` - New pickerSaveButtonTitle value. Default value is "Accept"
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `HTMLString`

    - #### getPickerSaveButtonTitle

          public java.lang.String getPickerSaveButtonTitle()

      The title for the `pickerSaveButton`.
      Returns:
        Current pickerSaveButtonTitle value. Default value is "Accept"
      See Also:
        `HTMLString`

    - #### getPickerSearchField

          public TextItem getPickerSearchField()

      The `pickerSearchField` is a separate `TextItem` created for search string entry when `pickListPlacement` indicates that the search interface takes over an entire panel or the entire screen.

      The following `passthroughs` apply:

      - `pickerSearchFieldHint` for `FormItem.hint`

      This component is an AutoChild named "pickerSearchField". For an overview of how to use and configure AutoChildren, see `Using AutoChildren`.

      Returns:
        Current pickerSearchField value. Default value is null

    - #### setPickerSearchFieldHint

          public ComboBoxItem setPickerSearchFieldHint(java.lang.String pickerSearchFieldHint)

      `FormItem.hint` for the `pickerSearchField`.
      Parameters:
        `pickerSearchFieldHint` - New pickerSearchFieldHint value. Default value is "Search"
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `HTMLString`

    - #### getPickerSearchFieldHint

          public java.lang.String getPickerSearchFieldHint()

      `FormItem.hint` for the `pickerSearchField`.
      Returns:
        Current pickerSearchFieldHint value. Default value is "Search"
      See Also:
        `HTMLString`

    - #### getPickerSearchForm

          public DynamicForm getPickerSearchForm()

      Form that contains the `pickerSearchField`.

      This component is an AutoChild named "pickerSearchForm". For an overview of how to use and configure AutoChildren, see `Using AutoChildren`.

      Returns:
        Current pickerSearchForm value. Default value is null

    - #### setPickerSearchOrNewValueFieldHint

          public ComboBoxItem setPickerSearchOrNewValueFieldHint(java.lang.String pickerSearchOrNewValueFieldHint)

      `FormItem.hint` for the `pickerSearchField` when the combobox is configured to `allow unknown values`
      Parameters:
        `pickerSearchOrNewValueFieldHint` - New pickerSearchOrNewValueFieldHint value. Default value is "Search or enter new value"
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `HTMLString`

    - #### getPickerSearchOrNewValueFieldHint

          public java.lang.String getPickerSearchOrNewValueFieldHint()

      `FormItem.hint` for the `pickerSearchField` when the combobox is configured to `allow unknown values`
      Returns:
        Current pickerSearchOrNewValueFieldHint value. Default value is "Search or enter new value"
      See Also:
        `HTMLString`

    - #### setPickListConstructor

          public ComboBoxItem setPickListConstructor(java.lang.String pickListConstructor)

      The Class to use when creating a picker of type "list" for a FormItem. Must be a subclass of the builtin default, `PickListMenu`.
      Parameters:
        `pickListConstructor` - New pickListConstructor value. Default value is "PickListMenu"
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `SCClassName`, `PickList overview and related methods`

    - #### getPickListConstructor

          public java.lang.String getPickListConstructor()

      The Class to use when creating a picker of type "list" for a FormItem. Must be a subclass of the builtin default, `PickListMenu`.
      Returns:
        Current pickListConstructor value. Default value is "PickListMenu"
      See Also:
        `SCClassName`, `PickList overview and related methods`

    - #### setPickListCriteria

          public ComboBoxItem setPickListCriteria(Criteria pickListCriteria)

      If this item has a databound pickList (for example PickList.optionDataSource is set), this property can be used to provide static filter criteria when retrieving the data for the pickList.

      Note : This is an advanced setting

      Specified by:
        `setPickListCriteria` in interface `PickList`
      Parameters:
        `pickListCriteria` - New pickListCriteria value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `PickList overview and related methods`

    - #### getPickListCriteria

          public Criteria getPickListCriteria()

      If this item has a databound pickList (for example PickList.optionDataSource is set), this property can be used to provide static filter criteria when retrieving the data for the pickList.
      Specified by:
        `getPickListCriteria` in interface `PickList`
      Returns:
        Current pickListCriteria value. Default value is null
      See Also:
        `PickList overview and related methods`

    - #### setPickListFields

          public ComboBoxItem setPickListFields(ListGridField... pickListFields)

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

      Note : This is an advanced setting

      Parameters:
        `pickListFields` - New pickListFields value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `setValueField(java.lang.String)`, `PickList overview and related methods`

    - #### setPickListPlacement

          public ComboBoxItem setPickListPlacement(PanelPlacement pickListPlacement)

      Controls where the PickList is placed. Can be specified as a `PanelPlacement` or a specific widget that should be filled (by specifying an actual Canvas or `Canvas.ID`).

      Default behavior is to `"fillPanel"` if `isHandset` or `isTablet`, to better accomodate the smaller screen real estate and less precise pointing ability on such devices.

      When filling the whole screen, part of the screen or a specific panel, the expanded interface is created as a `standard FormItem picker`, and incorporates a `navigation bar` and `cancel button` that hides the expanded interface, as well as a separate `search field`.

      Parameters:
        `pickListPlacement` - New pickListPlacement value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getPickListPlacement

          public PanelPlacement getPickListPlacement()

      Controls where the PickList is placed. Can be specified as a `PanelPlacement` or a specific widget that should be filled (by specifying an actual Canvas or `Canvas.ID`).

      Default behavior is to `"fillPanel"` if `isHandset` or `isTablet`, to better accomodate the smaller screen real estate and less precise pointing ability on such devices.

      When filling the whole screen, part of the screen or a specific panel, the expanded interface is created as a `standard FormItem picker`, and incorporates a `navigation bar` and `cancel button` that hides the expanded interface, as well as a separate `search field`.

      Returns:
        Current pickListPlacement value. Default value is null

    - #### setPickListPlacement

          public ComboBoxItem setPickListPlacement(Canvas pickListPlacement)

      Controls where the PickList is placed. Can be specified as a `PanelPlacement` or a specific widget that should be filled (by specifying an actual Canvas or `Canvas.ID`).

      Default behavior is to `"fillPanel"` if `isHandset` or `isTablet`, to better accomodate the smaller screen real estate and less precise pointing ability on such devices.

      When filling the whole screen, part of the screen or a specific panel, the expanded interface is created as a `standard FormItem picker`, and incorporates a `navigation bar` and `cancel button` that hides the expanded interface, as well as a separate `search field`.

      Parameters:
        `pickListPlacement` - New pickListPlacement value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getPickListPlacementAsCanvas

          public Canvas getPickListPlacementAsCanvas()

      Controls where the PickList is placed. Can be specified as a `PanelPlacement` or a specific widget that should be filled (by specifying an actual Canvas or `Canvas.ID`).

      Default behavior is to `"fillPanel"` if `isHandset` or `isTablet`, to better accomodate the smaller screen real estate and less precise pointing ability on such devices.

      When filling the whole screen, part of the screen or a specific panel, the expanded interface is created as a `standard FormItem picker`, and incorporates a `navigation bar` and `cancel button` that hides the expanded interface, as well as a separate `search field`.

      Returns:
        Current pickListPlacement value. Default value is null

    - #### setPickListPlacement

          public ComboBoxItem setPickListPlacement(java.lang.String pickListPlacement)

      Controls where the PickList is placed. Can be specified as a `PanelPlacement` or a specific widget that should be filled (by specifying an actual Canvas or `Canvas.ID`).

      Default behavior is to `"fillPanel"` if `isHandset` or `isTablet`, to better accomodate the smaller screen real estate and less precise pointing ability on such devices.

      When filling the whole screen, part of the screen or a specific panel, the expanded interface is created as a `standard FormItem picker`, and incorporates a `navigation bar` and `cancel button` that hides the expanded interface, as well as a separate `search field`.

      Parameters:
        `pickListPlacement` - New pickListPlacement value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getPickListPlacementAsString

          public java.lang.String getPickListPlacementAsString()

      Controls where the PickList is placed. Can be specified as a `PanelPlacement` or a specific widget that should be filled (by specifying an actual Canvas or `Canvas.ID`).

      Default behavior is to `"fillPanel"` if `isHandset` or `isTablet`, to better accomodate the smaller screen real estate and less precise pointing ability on such devices.

      When filling the whole screen, part of the screen or a specific panel, the expanded interface is created as a `standard FormItem picker`, and incorporates a `navigation bar` and `cancel button` that hides the expanded interface, as well as a separate `search field`.

      Returns:
        Current pickListPlacement value. Default value is null

    - #### setPickTreeConstructor

          public ComboBoxItem setPickTreeConstructor(java.lang.String pickTreeConstructor)

      The Class to use when creating a picker of type "tree" for a FormItem. Must be a subclass of the builtin default, PickTreeMenu.
      Parameters:
        `pickTreeConstructor` - New pickTreeConstructor value. Default value is "PickTreeMenu"
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `SCClassName`

    - #### getPickTreeConstructor

          public java.lang.String getPickTreeConstructor()

      The Class to use when creating a picker of type "tree" for a FormItem. Must be a subclass of the builtin default, PickTreeMenu.
      Returns:
        Current pickTreeConstructor value. Default value is "PickTreeMenu"
      See Also:
        `SCClassName`

    - #### setProgressiveLoading

          public ComboBoxItem setProgressiveLoading(java.lang.Boolean progressiveLoading)

      Indicates whether or not this ComboBoxItem will load its list of options `progressively`. This property is copied onto the underlying PickList.
      Parameters:
        `progressiveLoading` - New progressiveLoading value. Default value is true
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `DataSource.setProgressiveLoading(java.lang.Boolean)`, `ProgressiveLoading overview and related methods`

    - #### getProgressiveLoading

          public java.lang.Boolean getProgressiveLoading()

      Indicates whether or not this ComboBoxItem will load its list of options `progressively`. This property is copied onto the underlying PickList.
      Returns:
        Current progressiveLoading value. Default value is true
      See Also:
        `DataSource.getProgressiveLoading()`, `ProgressiveLoading overview and related methods`

    - #### setRootNodeId

          public ComboBoxItem setRootNodeId(java.lang.String rootNodeId)

      When this item is showing a tree-based picker, this is the `id` of the record to use as the `root` node.
      Parameters:
        `rootNodeId` - New rootNodeId value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getRootNodeId

          public java.lang.String getRootNodeId()

      When this item is showing a tree-based picker, this is the `id` of the record to use as the `root` node.
      Returns:
        Current rootNodeId value. Default value is null

    - #### setRootNodeId

          public ComboBoxItem setRootNodeId(java.lang.Integer rootNodeId)

      When this item is showing a tree-based picker, this is the `id` of the record to use as the `root` node.
      Parameters:
        `rootNodeId` - New rootNodeId value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getRootNodeIdAsInt

          public java.lang.Integer getRootNodeIdAsInt()

      When this item is showing a tree-based picker, this is the `id` of the record to use as the `root` node.
      Returns:
        Current rootNodeId value. Default value is null

    - #### setSaveOnEnter

          public ComboBoxItem setSaveOnEnter(java.lang.Boolean saveOnEnter)

      ComboBox items will submit their containing form on enter keypress if `saveOnEnter` is true. Setting this property to `false` will disable this behavior.

      Note that if the drop down list of options (pickList) is visible an `Enter` keypress is used to select a value from the available set of options and will not automatically cause form submission.

      Overrides:
        `setSaveOnEnter` in class `TextItem`
      Parameters:
        `saveOnEnter` - New saveOnEnter value. Default value is true
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getSaveOnEnter

          public java.lang.Boolean getSaveOnEnter()

      ComboBox items will submit their containing form on enter keypress if `saveOnEnter` is true. Setting this property to `false` will disable this behavior.

      Note that if the drop down list of options (pickList) is visible an `Enter` keypress is used to select a value from the available set of options and will not automatically cause form submission.

      Overrides:
        `getSaveOnEnter` in class `TextItem`
      Returns:
        Current saveOnEnter value. Default value is true

    - #### setSearchStringTooShortMessage

          public ComboBoxItem setSearchStringTooShortMessage(java.lang.String searchStringTooShortMessage)

      Message to display in pick list when `minimumSearchLength` characters have not been entered.

      Note : This is an advanced setting

      Parameters:
        `searchStringTooShortMessage` - New searchStringTooShortMessage value. Default value is "Enter a longer search string to search"
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getSearchStringTooShortMessage

          public java.lang.String getSearchStringTooShortMessage()

      Message to display in pick list when `minimumSearchLength` characters have not been entered.
      Returns:
        Current searchStringTooShortMessage value. Default value is "Enter a longer search string to search"

    - #### setSeparateSpecialValues

          public ComboBoxItem setSeparateSpecialValues(java.lang.Boolean separateSpecialValues)

      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.
      Parameters:
        `separateSpecialValues` - New separateSpecialValues value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### 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.
      Returns:
        Current separateSpecialValues value. Default value is null

    - #### getSeparateValuesList

          public ListGrid getSeparateValuesList()

      AutoChild used to show `specialValues`.

      This component is an AutoChild named "separateValuesList". For an overview of how to use and configure AutoChildren, see `Using AutoChildren`.

      Returns:
        Current separateValuesList value. Default value is null

    - #### setSeparatorRows

          public ComboBoxItem setSeparatorRows(ListGridRecord[] separatorRows)

      Array of records to show between matching and non-matching rows in the PickList.

      Not valid for `databound pickLists`.

      Specified by:
        `setSeparatorRows` in interface `PickList`
      Parameters:
        `separatorRows` - New separatorRows value. Default value is [{isSeparator:true}]
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### setShowAllOptions

          public ComboBoxItem setShowAllOptions(java.lang.Boolean showAllOptions)

      If true, even non-matching options will be shown, with configurable `separator rows` in between. Not valid for `databound pickLists`.
      Specified by:
        `setShowAllOptions` in interface `PickList`
      Parameters:
        `showAllOptions` - New showAllOptions value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getShowAllOptions

          public java.lang.Boolean getShowAllOptions()

      If true, even non-matching options will be shown, with configurable `separator rows` in between. Not valid for `databound pickLists`.
      Specified by:
        `getShowAllOptions` in interface `PickList`
      Returns:
        Current showAllOptions value. Default value is null

    - #### setShowHintInField

          public ComboBoxItem setShowHintInField(java.lang.Boolean showHintInField)

      If showing a hint for this form item, should it be shown within the field?

      CSS style for the hint is `SelectItem.textBoxStyle` with the suffix "Hint" appended to it.

      Note : This is an advanced setting

      Overrides:
        `setShowHintInField` in class `TextItem`
      Parameters:
        `showHintInField` - New showHintInField value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `FormItem.setHint(java.lang.String)`, `Appearance overview and related methods`

    - #### getShowHintInField

          public java.lang.Boolean getShowHintInField()

      If showing a hint for this form item, should it be shown within the field?

      CSS style for the hint is `SelectItem.textBoxStyle` with the suffix "Hint" appended to it.

      Overrides:
        `getShowHintInField` in class `TextItem`
      Returns:
        Current showHintInField value. Default value is null
      See Also:
        `FormItem.getHint()`, `Appearance overview and related methods`

    - #### setShowOptionsFromDataSource

          public ComboBoxItem setShowOptionsFromDataSource(java.lang.Boolean showOptionsFromDataSource)

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

      Note : This is an advanced setting

      Specified by:
        `setShowOptionsFromDataSource` in interface `PickList`
      Parameters:
        `showOptionsFromDataSource` - New showOptionsFromDataSource value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `Databinding overview and related methods`

    - #### 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`.
      Specified by:
        `getShowOptionsFromDataSource` in interface `PickList`
      Returns:
        Current showOptionsFromDataSource value. Default value is null
      See Also:
        `Databinding overview and related methods`

    - #### setShowPickerIcon

          public ComboBoxItem setShowPickerIcon(java.lang.Boolean showPickerIcon)

      Should we show a special 'picker' `icon` for this form item? Picker icons are customizable via `pickerIconProperties`. By default they will be rendered inside the form item's `"control box"` area. By default clicking the pickerIcon will call `FormItem.showPicker()`.
      Overrides:
        `setShowPickerIcon` in class `FormItem`
      Parameters:
        `showPickerIcon` - New showPickerIcon value. Default value is true
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getShowPickerIcon

          public java.lang.Boolean getShowPickerIcon()

      Should we show a special 'picker' `icon` for this form item? Picker icons are customizable via `pickerIconProperties`. By default they will be rendered inside the form item's `"control box"` area. By default clicking the pickerIcon will call `FormItem.showPicker()`.
      Overrides:
        `getShowPickerIcon` in class `FormItem`
      Returns:
        Current showPickerIcon value. Default value is true

    - #### setShowPickListOnKeypress

          public ComboBoxItem setShowPickListOnKeypress(java.lang.Boolean showPickListOnKeypress)

      Should the list of options be displayed whenever the user types into the combo-box textArea, or only when the user clicks on the pick button or uses the explicit `Alt+Arrow Down` key combination?
      Parameters:
        `showPickListOnKeypress` - New showPickListOnKeypress value. Default value is true
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getShowPickListOnKeypress

          public java.lang.Boolean getShowPickListOnKeypress()

      Should the list of options be displayed whenever the user types into the combo-box textArea, or only when the user clicks on the pick button or uses the explicit `Alt+Arrow Down` key combination?
      Returns:
        Current showPickListOnKeypress value. Default value is true

    - #### setSingleClickFolderToggle

          public ComboBoxItem setSingleClickFolderToggle(boolean singleClickFolderToggle)

      When this item is showing a tree-based picker, the default behavior is for folder open-state to be toggled by double-clicking. Set this attribute to true to toggle folders on a single-click instead.

      Note: when set to true, users can only choose leaf-nodes, since clicking folders would simply toggle them.

      Parameters:
        `singleClickFolderToggle` - New singleClickFolderToggle value. Default value is false
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getSingleClickFolderToggle

          public boolean getSingleClickFolderToggle()

      When this item is showing a tree-based picker, the default behavior is for folder open-state to be toggled by double-clicking. Set this attribute to true to toggle folders on a single-click instead.

      Note: when set to true, users can only choose leaf-nodes, since clicking folders would simply toggle them.

      Returns:
        Current singleClickFolderToggle value. Default value is false

    - #### setSortField

          public ComboBoxItem setSortField(java.lang.String sortField)

      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.

      Parameters:
        `sortField` - New sortField value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        Sort Example

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

      Returns:
        Current sortField value. Default value is null
      See Also:
        Sort Example

    - #### setSortField

          public ComboBoxItem setSortField(java.lang.String... sortField)

      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.

      Parameters:
        `sortField` - New sortField value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        Sort Example

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

      Returns:
        Current sortField value. Default value is null
      See Also:
        Sort Example

    - #### setSortField

          public ComboBoxItem setSortField(java.lang.Integer sortField)

      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.

      Parameters:
        `sortField` - New sortField value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        Sort Example

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

      Returns:
        Current sortField value. Default value is null
      See Also:
        Sort Example

    - #### setTextMatchStyle

          public ComboBoxItem setTextMatchStyle(TextMatchStyle textMatchStyle)

      When applying filter criteria to pickList data, what type of matching to use.

      For a databound pickList (`optionDataSource` set), `textMatchStyle` is sent to the server as `DSRequest.textMatchStyle`.

      For a non-databound pickList, `textMatchStyle` is applied by filterClientPickListData().

      Specified by:
        `setTextMatchStyle` in interface `PickList`
      Parameters:
        `textMatchStyle` - New textMatchStyle value. Default value is "startsWith"
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### getTextMatchStyle

          public TextMatchStyle getTextMatchStyle()

      When applying filter criteria to pickList data, what type of matching to use.

      For a databound pickList (`optionDataSource` set), `textMatchStyle` is sent to the server as `DSRequest.textMatchStyle`.

      For a non-databound pickList, `textMatchStyle` is applied by filterClientPickListData().

      Specified by:
        `getTextMatchStyle` in interface `PickList`
      Returns:
        Current textMatchStyle value. Default value is "startsWith"

    - #### setUseClientFiltering

          public ComboBoxItem setUseClientFiltering(java.lang.Boolean useClientFiltering)

      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.

      Note : This is an advanced setting

      Parameters:
        `useClientFiltering` - New useClientFiltering value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls

    - #### 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

          public ComboBoxItem setValueField(java.lang.String valueField)

      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()`.
      Specified by:
        `setValueField` in interface `PickList`
      Overrides:
        `setValueField` in class `FormItem`
      Parameters:
        `valueField` - New valueField value. Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `Databinding overview and related methods`

    - #### 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()`.
      Specified by:
        `getValueField` in interface `PickList`
      Overrides:
        `getValueField` in class `FormItem`
      Returns:
        Getter method to retrieve the `FormItem.valueField` for this item. For items with a specified `FormItem.optionDataSource`, this determines which field in that dataSource corresponds to the value for this item.

        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

      See Also:
        `Databinding overview and related methods`

    - #### addDataArrivedHandler

          public com.google.gwt.event.shared.HandlerRegistration addDataArrivedHandler(DataArrivedHandler handler)

      Add a dataArrived handler.

      If this item is showing a dataBound pickList, this notification method will be fired when new data arrives from the server.

      Specified by:
        `addDataArrivedHandler` in interface `HasDataArrivedHandlers`
      Parameters:
        `handler` - the dataArrived handler
      Returns:
        `HandlerRegistration` used to remove this handler

    - #### defaultDynamicValue

          public void defaultDynamicValue()

      Expression evaluated to determine the `defaultValue` when no value is provided for this item. To default to the first option use `defaultToFirstOption` instead.

    - #### 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

          public void fetchData(DSCallback callback)

      See Also:
        `fetchData()`

    - #### fetchData

          public void fetchData(DSCallback callback,
                                DSRequest requestProperties)

      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:
        - `item` a pointer to the form item
        - `dsResponse` the `DSResponse` returned by the server
        - `data` the raw data returned by the server
        - `dsRequest` the `DSRequest` sent to the server
        `requestProperties` - properties to apply to the dsRequest for this fetch.

    - #### filterClientPickListData

          public ListGridRecord[] filterClientPickListData()

      Returns the data to display in the pick list.

      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.

      Specified by:
        `filterClientPickListData` in interface `PickList`
      Returns:
        array of record objects to display in the pickList

    - #### getClientPickListData

          public ListGridRecord[] getClientPickListData()

      Returns the set of data to be displayed in this item's PickList.

      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".
      Specified by:
        `getClientPickListData` in interface `PickList`
      Returns:
        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`

    - #### getDisplayFieldName

          public java.lang.String getDisplayFieldName()

      Returns the `displayField` for this item.

      Behavior varies based on the configuration of this item, as follows:

      - If this item has an `optionDataSource` and an explicit `FormItem.foreignDisplayField` is specified, this will be returned.
      - 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 foreignDisplayField 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`.
      Specified by:
        `getDisplayFieldName` in interface `PickList`
      Overrides:
        `getDisplayFieldName` in class `FormItem`
      Returns:
        display field name, or null if there is no separate display field to use. See `FieldName`

    - #### getEnteredValue

          public java.lang.String getEnteredValue()

      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
      Note: if the pickList is being shown in any view other than the default `nearOrigin`, as is typically the case on a mobile device, this method will return the value of the `pickerSearchField`.
      Overrides:
        `getEnteredValue` in class `TextItem`
      Returns:
        current entered value

    - #### getValueFieldName

          public java.lang.String getValueFieldName()

      Getter method to retrieve the `FormItem.valueField` for this item. For items with a specified `FormItem.optionDataSource`, this determines which field in that dataSource corresponds to the value for this item.

      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.

      Specified by:
        `getValueFieldName` in interface `PickList`
      Overrides:
        `getValueFieldName` in class `FormItem`
      Returns:
        fieldName to use a "value field" in records from this items `FormItem.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

      Overrides:
        `hasAdvancedCriteria` in class `FormItem`
      Returns:
        true if the result of getCriterion() will be an AdvancedCriteria object.
      See Also:
        `CriteriaEditing overview and related methods`

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

      Default implementation will return `generateExactMatchCriteria` if specified, otherwise true if the DataSource for this item `supports advanced criteria`, false if it does not.

      Returns:
        should getCriterion() generate exact-match search criteria when a value was explicitly chosen from this item's set of options?

    - #### setDefaultProperties

          public static void setDefaultProperties(ComboBoxItem comboBoxItemProperties)

      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
      See Also:
        `SGWTProperties`

    - #### getPickListFilterCriteria

          protected Criteria getPickListFilterCriteria()

      Returns filter criteria for options displayed for this item.

      See `ComboBoxFiltering` for details on how pickList filter criteria are calculated by default for a comboBoxItem.

      Note : this is an override point - if overridden this method will be called by the live form item during filtering. However it is recommended that developers use `setPickListFilterCriteriaFunction(FormItemCriteriaFunction)` to build custom criteria instead of overriding this method directly. This ensures that the custom filter criteria generating code will be called even if the form item was automatically generated based on a template passed to `ListGridField.setEditorType(com.smartgwt.client.widgets.form.fields.FormItem)`.

      Returns:
        criteria to be used for databound or local filtering

    - #### setSpecialValues

          public void setSpecialValues(java.lang.String... values)

      Set the specialValues for this item.
      Parameters:
        `values` - the special values

    - #### setSpecialValues

          public void setSpecialValues(java.util.LinkedHashMap valueMap)

      Set the specialValues for this item.
      Parameters:
        `valueMap` - the special value map

    - #### 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
      Specified by:
        `setPickListHeight` in interface `PickList`
      Parameters:
        `pickListHeight` - pickListHeight Default value is 300

    - #### 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
      Specified by:
        `getPickListHeight` in interface `PickList`
      Returns:
        int

    - #### setEmptyPickListHeight

          public void setEmptyPickListHeight(int emptyPickListHeight)

      Height for an empty pick list (showing the empty message), if the pick list has no records and `hideEmptyPickList` is `false`.
      Specified by:
        `setEmptyPickListHeight` in interface `PickList`
      Parameters:
        `emptyPickListHeight` - emptyPickListHeight Default value is 100

    - #### getEmptyPickListHeight

          public int getEmptyPickListHeight()

      Height for an empty pick list (showing the empty message), if the pick list has no records and `hideEmptyPickList` is `false`.
      Specified by:
        `getEmptyPickListHeight` in interface `PickList`
      Returns:
        int

    - #### setHideEmptyPickList

          public void setHideEmptyPickList(java.lang.Boolean hideEmptyPickList)

      If this pickList contains no options, should it be hidden? If unset, default behavior is to allow the empty pickList to show if it is databound.
      Specified by:
        `setHideEmptyPickList` in interface `PickList`
      Parameters:
        `hideEmptyPickList` - hideEmptyPickList Default value is null

    - #### getHideEmptyPickList

          public java.lang.Boolean getHideEmptyPickList()

      If this pickList contains no options, should it be hidden? If unset, default behavior is to allow the empty pickList to show if it is databound.
      Specified by:
        `getHideEmptyPickList` in interface `PickList`
      Returns:
        Boolean

    - #### setPickListWidth

          public void setPickListWidth(java.lang.Integer pickListWidth)

      Default width to show the pickList. If not specified, the width of this form item's element will be used instead.
      Specified by:
        `setPickListWidth` in interface `PickList`
      Parameters:
        `pickListWidth` - pickListWidth Default value is null

    - #### getPickListWidth

          public java.lang.Integer getPickListWidth()

      Default width to show the pickList. If not specified, the width of this form item's element will be used instead.
      Specified by:
        `getPickListWidth` in interface `PickList`
      Returns:
        Integer

    - #### setPickListMaxWidth

          public void setPickListMaxWidth(java.lang.Integer pickListMaxWidth)

      Maximum width for this item's pickList. By default if the values displayed in this pickList are wider than the specified `setPickListWidth` the pickList will render wide enough to accomodate them. This property allows the developer to limit how wide the pickList will render.
      Specified by:
        `setPickListMaxWidth` in interface `PickList`
      Parameters:
        `pickListMaxWidth` - pickListMaxWidth Default value is 400

    - #### getPickListMaxWidth

          public java.lang.Integer getPickListMaxWidth()

      Maximum width for this item's pickList. By default if the values displayed in this pickList are wider than the specified `setPickListWidth` the pickList will render wide enough to accomodate them. This property allows the developer to limit how wide the pickList will render.
      Specified by:
        `getPickListMaxWidth` in interface `PickList`
      Returns:
        Integer

    - #### setPickListBaseStyle

          public void setPickListBaseStyle(java.lang.String pickListBaseStyle)

      Base Style for pickList cells. As with ListGrid Cells, will have 'over', 'selected' and 'disabled' appended on changes of state for the cells.
      Specified by:
        `setPickListBaseStyle` in interface `PickList`
      Parameters:
        `pickListBaseStyle` - pickListBaseStyle Default value is "pickListCell"

    - #### getPickListBaseStyle

          public java.lang.String getPickListBaseStyle()

      Base Style for pickList cells. As with ListGrid Cells, will have 'over', 'selected' and 'disabled' appended on changes of state for the cells.
      Specified by:
        `getPickListBaseStyle` in interface `PickList`
      Returns:
        String

    - #### setAnimatePickList

          public void setAnimatePickList(java.lang.Boolean animatePickList)

      If true, when the pickList is shown, it will be shown via an animated reveal effect

      Note : This is an advanced setting

      Specified by:
        `setAnimatePickList` in interface `PickList`
      Parameters:
        `animatePickList` - animatePickList Default value is null

    - #### getAnimatePickList

          public java.lang.Boolean getAnimatePickList()

      If true, when the pickList is shown, it will be shown via an animated reveal effect
      Specified by:
        `getAnimatePickList` in interface `PickList`
      Returns:
        Boolean

    - #### setAnimationTime

          public void setAnimationTime(int animationTime)

      If this.animatePickList is true - this specifies the duration of the animation effect applied when showing the pickList

      Note : This is an advanced setting

      Specified by:
        `setAnimationTime` in interface `PickList`
      Parameters:
        `animationTime` - animationTime Default value is 200

    - #### getAnimationTime

          public int getAnimationTime()

      If this.animatePickList is true - this specifies the duration of the animation effect applied when showing the pickList
      Specified by:
        `getAnimationTime` in interface `PickList`
      Returns:
        int

    - #### setPickListHeaderHeight

          public void setPickListHeaderHeight(int pickListHeaderHeight)

      If this pick list is showing multiple fields, this property determines the height of the column headers for those fields. Set to zero to suppress the headers entirely.
      Specified by:
        `setPickListHeaderHeight` in interface `PickList`
      Parameters:
        `pickListHeaderHeight` - pickListHeaderHeight Default value is 22

    - #### getPickListHeaderHeight

          public int getPickListHeaderHeight()

      If this pick list is showing multiple fields, this property determines the height of the column headers for those fields. Set to zero to suppress the headers entirely.
      Specified by:
        `getPickListHeaderHeight` in interface `PickList`
      Returns:
        int

    - #### setPickListCellHeight

          public void setPickListCellHeight(int pickListCellHeight)

      Cell Height for this item's pickList.
      Specified by:
        `setPickListCellHeight` in interface `PickList`
      Parameters:
        `pickListCellHeight` - pickListCellHeight Default value is 16

    - #### getPickListCellHeight

          public int getPickListCellHeight()

      Cell Height for this item's pickList.
      Specified by:
        `getPickListCellHeight` in interface `PickList`
      Returns:
        int

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

      Note : This is an advanced setting

      Specified by:
        `setValueIconField` in interface `PickList`
      Parameters:
        `valueIconField` - valueIconField Default value is null

    - #### 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.
      Specified by:
        `getValueIconField` in interface `PickList`
      Returns:
        String

    - #### setPickListCriteria

          public void setPickListCriteria(DSRequest optionFilterContext)

    - #### setFetchDelay

          public void setFetchDelay(java.lang.Integer fetchDelay)

      Description copied from interface: `PickList`
      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.
      Specified by:
        `setFetchDelay` in interface `PickList`
      Parameters:
        `fetchDelay` - the fetch delay. defaults to 200ms

    - #### getFetchDelay

          public java.lang.Integer getFetchDelay()

      Description copied from interface: `PickList`
      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.
      Specified by:
        `getFetchDelay` in interface `PickList`
      Returns:
        the fetch delay

    - #### setOptionDataSource

          public ComboBoxItem setOptionDataSource(DataSource dataSource)

      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.

      Setting optionDataSource also enables the basic `optionDataSource` behaviors, eg, fetching individual display values before the pickList is shown.

      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.

      Note : This is an advanced setting

      Specified by:
        `setOptionDataSource` in interface `PickList`
      Overrides:
        `setOptionDataSource` in class `FormItem`
      Parameters:
        `dataSource` - optionDataSource Default value is null
      Returns:
        `ComboBoxItem` instance, for chaining setter calls
      See Also:
        `FormItem.invalidateDisplayValueCache()`, List - Combo Box Example

    - #### getOptionDataSource

          public DataSource getOptionDataSource()

      Description copied from class: `FormItem`
      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

      Specified by:
        `getOptionDataSource` in interface `PickList`
      Overrides:
        `getOptionDataSource` in class `FormItem`
      Returns:
        Returns the `optionDataSource` for this item.

        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

      See Also:
        `FormItem.invalidateDisplayValueCache()`, List - Combo Box Example

    - #### getSelectedRecord

          public ListGridRecord 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.
      Overrides:
        `getSelectedRecord` in class `FormItem`
      Returns:
        the selected record or null

    - #### setPickListFilterCriteriaFunction

          public void setPickListFilterCriteriaFunction(FilterCriteriaFunction filterCriteriaFunction)

      Deprecated. in favor of `setPickListFilterCriteriaFunction(FormItemCriteriaFunction)`
      Set the pick list filter criteria function / handler.
      Specified by:
        `setPickListFilterCriteriaFunction` in interface `PickList`
      Parameters:
        `filterCriteriaFunction` - the filter criteria function

    - #### setPickListFilterCriteriaFunction

          public void setPickListFilterCriteriaFunction(FormItemCriteriaFunction filterCriteriaFunction)

      Set up a method to return filter criteria for options displayed for this item.

      See `ComboBoxFiltering` for details on how pickListCriteria are calcualted by default for a ComboBoxItem.

    - #### setPickListProperties

          public void setPickListProperties(ListGrid pickListProperties)

      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.

      PickLists and `ListGrid.setShowFilterEditor(boolean)`: `ComboBoxItems` do not support setting `showFilterEditor` to true on pickListProperties. This combination of settings leads to an ambiguous user experience as the two sets of filter-criteria (those from the text-box and those from the pickList filter editor) interact with each other.
      Calling `setShowFilterEditor` on the PickListMenu passed to `SelectItem.setPickListProperties(com.smartgwt.client.widgets.grid.ListGrid)` is a valid way to create a filterable pickList, on a SelectItem, but this setting is not supported on a SelectItem with `multiple set to true` - this combination of settings can cause a selected value to be filtered out of view at which point further selection changes will discard that value.
      In general we recommend the ComboBoxItem class (with `addUnknownValues set as appropriate`) as a better interface for filtering pickList data.

      Parameters:
        `pickListProperties` - the pick list properties

    - #### setOptionFilterContext

          public void setOptionFilterContext(DSRequest dsRequestProperties)

      Description copied from interface: `PickList`
      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

      Note : This is an advanced setting

      Specified by:
        `setOptionFilterContext` in interface `PickList`
      Parameters:
        `dsRequestProperties` - optionFilterContext Default value is null

    - #### getValueAsString

          public java.lang.String getValueAsString()

      Return the value tracked by this form item.
      Overrides:
        `getValueAsString` in class `TextItem`
      Returns:
        value of this element

    - #### setCanEditCriterionPredicate

          public void setCanEditCriterionPredicate(FormItemCanEditCriterionPredicate predicate)

      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.

      Overrides:
        `setCanEditCriterionPredicate` in class `FormItem`
      Parameters:
        `predicate` - the predicate to determine the form items that can edit the criterion in question
      See Also:
        `FormItem.setCanEditCriterionPredicate`, `CriteriaEditing overview and related methods`

    - #### setCriterionGetter

          public void setCriterionGetter(FormItemCriterionGetter getter)

      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.

      Overrides:
        `setCriterionGetter` in class `FormItem`
      Parameters:
        `getter` - provides a method to get a criterion object based on this field's current edited value(s).
      See Also:
        `FormItem.setCriterionGetter(com.smartgwt.client.widgets.form.FormItemCriterionGetter)`, `CriteriaEditing overview and related methods`

    - #### setCriterionSetter

          public void setCriterionSetter(FormItemCriterionSetter setter)

      The default `setCriterion()` implementation is overridden to support editing criterion against the display field or value field when `addUnknownValues` is true.
      Overrides:
        `setCriterionSetter` in class `FormItem`
      Parameters:
        `setter` - provides a method to update this field with the edited criterion

    - #### setPickListSort

          public void setPickListSort(SortSpecifier[] sortSpecifiers)

      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.

      See `ListGrid.addSort(com.smartgwt.client.data.SortSpecifier)` and `com.smartgwt.client.widgets.grid.ListGrid#alterSort` APIs for information on making changes to the current sort configuration.

      Parameters:
        `sortSpecifiers` - Array of SortSpecifier objects

    - #### setSort

          public void setSort(SortSpecifier[] sortSpecifiers)

      Deprecated. in favor of `setPickListSort(SortSpecifier[])` where full documentation can be read.
      Sorts the pickList on one or more fields.
      Parameters:
        `sortSpecifiers` - Array of SortSpecifier objects