Package com.smartgwt.client.widgets.form.fields

# Class SelectItem

java.lang.Object
com.smartgwt.client.core.JsObject
com.smartgwt.client.core.DataClass
com.smartgwt.client.core.RefDataClass
com.smartgwt.client.data.Field
com.smartgwt.client.widgets.form.fields.FormItem
com.smartgwt.client.widgets.form.fields.SelectItem

All Implemented Interfaces:
  `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`

Direct Known Subclasses:
  `PresetCriteriaItem`, `SavedSearchItem`, `SelectOtherItem`

public class SelectItem extends FormItem implements PickList, HasDataArrivedHandlers
FormItem that allows picking between several mutually exclusive options via a select list.

Options may be derived from a `dataSource` or a `valueMap`.

Note that to select the first option as a default value for the item, `defaultToFirstOption` may be set.

See Also:
  - `FormItem.getValueMap()`

- ## 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
  Description
  `SelectItem()`
  `SelectItem(JavaScriptObject jsObj)`
  `SelectItem(String name)`
  `SelectItem(String name, String title)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `HandlerRegistration`
  `addDataArrivedHandler(DataArrivedHandler handler)`
  Add a dataArrived handler.
  `static void`
  `changeAutoChildDefaults(String autoChildName, Canvas defaults)`
  Changes the defaults for Canvas AutoChildren named `autoChildName`.
  `static void`
  `changeAutoChildDefaults(String autoChildName, FormItem defaults)`
  Changes the defaults for FormItem AutoChildren named `autoChildName`.
  `static void`
  `changePickerIconDefaults(FormItemIcon defaults)`
  `Object`
  `defaultDynamicValue(FormItem item, DynamicForm form, Map values)`
  Expression evaluated to determine the `defaultValue` when no value is provided for this item.
  `void`
  `fetchData()`
  Only applies to databound items (see 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 pickListCriteria.
  `void`
  `fetchData(DSCallback callback)`
  `void`
  `fetchData(DSCallback callback, DSRequest requestProperties)`
  Only applies to databound items (see 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 pickListCriteria.
  `ListGridRecord[]`
  `filterClientPickListData()`
  Returns the data to display in the pick list.
  `Boolean`
  `getAddUnknownValues()`
  If this item's value is set (via `setValue()` or similar) to a value which is not present in the `com.smartgwt.client.types.ValueMap`, should the value be rejected.
  `Boolean`
  `getAllowEmptyValue()`
  If set to true, always show an empty option in this item's pickList, allowing the user to clear the value (even if there is no empty entry in the valueMap for the item).
  `boolean`
  `getAllowMultiCharSearch()`
  By default, if multiple keys are pressed in quick succession, a SelectItem will buffer them together and use the resulting multi-char string when searching.
  `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
  `Boolean`
  `getAutoFetchData()`
  If this select item retrieves its options from a `dataSource`, should options be fetched from the server when the item is first drawn, or should this fetch be delayed until the user opens the pickList.
  `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 pickLists in an LRU (least recently used) caching pattern.
  `boolean`
  `getCanSelectText()`
  By default SelectItems do not allow users to select the text of the selected value.
  `ClickMaskMode`
  `getClickMaskMode()`
  Determines the behavior of the click-mask thrown up when this pickList is visible.
  `ListGridRecord[]`
  `getClientPickListData()`
  Returns the set of data to be displayed in this item's PickList.
  `String`
  `getControlStyle()`
  Base CSS class name for a form item's "control box".
  `String`
  `getDataSetType()`
  Whether to show the picker as a flat list, or a collapsible tree.
  `Boolean`
  `getDefaultToFirstOption()`
  Select the first option as the default value for this SelectItem.
  `Object`
  `getDefaultValue()`
  Static default value for this SelectItem.
  `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`.
  `String`
  `getDisplayFieldName()`
  Returns the `displayField` for this item.
  `String`
  `getEditProxyConstructor()`
  Default class used to construct the `EditProxy` for this component when the component is `first placed into edit mode`.
  `String`
  `getEmptyDisplayValue()`
  Text to display when this form item has a null or undefined value.
  `int`
  `getEmptyPickListHeight()`
  Height for an empty pick list (showing the empty message), if the pick list has no records and `hideEmptyPickList` is `false`.
  `String`
  `getEmptyPickListMessage()`
  Empty message to display in the selectItem if PickList.hideEmptyPickList is `false`.
  `Boolean`
  `getEscapeHTML()`
  By default HTML values in a selectItem will be interpreted by the browser.
  `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.
  `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`.
  `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`
  `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.
  `Boolean`
  `getMultiple()`
  If true, multiple values may be selected.
  `MultipleAppearance`
  `getMultipleAppearance()`
  How should items with `multiple` set to 'true' be displayed?
  `Boolean`
  `getOpenOnDownArrow()`
  Causes the PickList to open when the down arrow is pressed, default false.
  `Boolean`
  `getOpenOnSpace()`
  Causes the PickList to open when the spacebar is pressed, default false.
  `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.
  `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 SelectItem`
  `getOrCreateRef(JavaScriptObject jsObj)`
  `NavigationButton`
  `getPickerClearButton()`
  `NavigationButton` to clear the picker value, created when `pickListPlacement` indicates that the search interface takes over the entire panel or screen.
  `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.
  `String`
  `getPickerExitButtonTitle()`
  The title for the `pickerExitButton`.
  `Integer`
  `getPickerIconHeight()`
  If `showPickerIcon` is true for this item, this property governs the size of the picker icon.
  `String`
  `getPickerIconSrc()`
  If `showPickerIcon` is true for this item, this property governs the `src` of the picker icon image to be displayed.
  `String`
  `getPickerIconStyle()`
  Base CSS class name for a form item's picker icon cell.
  `Integer`
  `getPickerIconWidth()`
  If `showPickerIcon` is true for this item, this property governs the size of the picker icon.
  `NavigationBar`
  `getPickerNavigationBar()`
  `NavigationBar` created when `pickListPlacement` indicates that the search interface takes over the entire panel or screen.
  `ListGrid`
  `getPickList()`
  ListGrid-based AutoChild created by the system to display a list of pickable options for this item.
  `String`
  `getPickListBaseStyle()`
  Base Style for pickList cells.
  `int`
  `getPickListCellHeight()`
  Cell Height for this item's pickList.
  `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.
  `ListGridField[]`
  `getPickListFields()`
  This property allows the developer to specify which field[s] will be displayed in the drop down list of options.
  `protected Criteria`
  `getPickListFilterCriteria()`
  Returns a set of filter criteria to be applied to the data displayed in the pickList when it is shown.
  `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.
  `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.
  `String`
  `getPickListPlacementAsString()`
  Controls where the PickList is placed.
  `Integer`
  `getPickListWidth()`
  Default width to show the pickList.
  `String`
  `getPickTreeConstructor()`
  The Class to use when creating a picker of type "tree" for a FormItem.
  `Boolean`
  `getProgressiveLoading()`
  Indicates whether or not this SelectItem will load its list of options `progressively`.
  `String`
  `getRootNodeId()`
  When this item is showing a tree-based picker, this is the `id` of the record to use as the `root` node.
  `Integer`
  `getRootNodeIdAsInt()`
  When this item is showing a tree-based picker, this is the `id` of the record to use as the `root` node.
  `Boolean`
  `getSaveOnEnter()`
  Select items will submit their containing form on enter keypress if `saveOnEnter` is true.
  `ListGridRecord`
  `getSelectedRecord()`
  Get the record returned from the `optionDataSource` when `fetchMissingValues` is true, and the missing value is fetched.
  `ListGridRecord[]`
  `getSelectedRecords()`
  For a SelectItem with an `optionDataSource` and allowing multiple selection (`via multiple:true`), returns the list of currently selected records, or null if none are selected.
  `Boolean`
  `getSeparateSpecialValues()`
  If true, `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`.
  `Boolean`
  `getShowAllOptions()`
  If true, even non-matching options will be shown, with configurable `separatorRows` in between.
  `Boolean`
  `getShowFocused()`
  When this item receives focus, should it be re-styled to indicate it has focus?
  `Boolean`
  `getShowHintInField()`
  If showing a hint for this form item, should it be shown within the field?
  `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.
  `boolean`
  `getShowOver()`
  When the user rolls over this item, should it be re-styled to indicate it has focus?
  `Boolean`
  `getShowPickerIcon()`
  Should we show a special 'picker' `icon` for this form item? Picker icons are customizable via `pickerIconProperties`.
  `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.
  `String`
  `getSortField()`
  Specifies one or more fields by which this item should be initially sorted.
  `Integer`
  `getSortFieldAsInt()`
  Specifies one or more fields by which this item should be initially sorted.
  `String[]`
  `getSortFieldAsStringArray()`
  Specifies one or more fields by which this item should be initially sorted.
  `Map`
  `getSpecialValues()`
  A set of "special" values such as "All", "None" or "Invalid" that do not appear in the normal `com.smartgwt.client.types.ValueMap` or in the data returned by the `optionDataSource`.
  `String`
  `getTextBoxStyle()`
  Base CSS class name for a form item's text box element.
  `TextMatchStyle`
  `getTextMatchStyle()`
  When applying filter criteria to pickList data, what type of matching to use.
  `Boolean`
  `getUpdateControlOnOver()`
  If `FormItem.showOver` is true, setting this property to false will explicitly disable showing the "Over" state for the control table element of this item (if present).
  `Boolean`
  `getUpdateTextBoxOnOver()`
  If `FormItem.showOver` is true, setting this property to false will explicitly disable showing the "Over" state for the TextBox element of this item.
  `Boolean`
  `getUseClientFiltering()`
  For `databound` items, this property will be passed to the generated ResultSet data object for the pickList as `ResultSet.useClientFiltering`.
  `String`
  `getValueAsString()`
  Return the value tracked by this form item.
  `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()`.
  `String`
  `getValueFieldName()`
  Getter method to retrieve the `FormItem.valueField` for this item.
  `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.
  `String[]`
  `getValues()`
  Returns the values of a SelectItem with multiple=true as an array of Strings.
  `Boolean`
  `isMultiple()`
  If true, multiple values may be selected.
  `Boolean`
  `pendingStatusChanged(DynamicForm form, FormItem item, boolean pendingStatus, Object newValue, Object value)`
  Notification method called when `showPending` is enabled and this `SelectItem` should either clear or show its pending visual state.
  `SelectItem`
  `setAddUnknownValues(Boolean addUnknownValues)`
  If this item's value is set (via `setValue()` or similar) to a value which is not present in the `com.smartgwt.client.types.ValueMap`, should the value be rejected.
  `SelectItem`
  `setAllowEmptyValue(Boolean allowEmptyValue)`
  If set to true, always show an empty option in this item's pickList, allowing the user to clear the value (even if there is no empty entry in the valueMap for the item).
  `SelectItem`
  `setAllowMultiCharSearch(boolean allowMultiCharSearch)`
  By default, if multiple keys are pressed in quick succession, a SelectItem will buffer them together and use the resulting multi-char string when searching.
  `void`
  `setAnimatePickList(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
  `SelectItem`
  `setAutoFetchData(Boolean autoFetchData)`
  If this select item retrieves its options from a `dataSource`, should options be fetched from the server when the item is first drawn, or should this fetch be delayed until the user opens the pickList.
  `SelectItem`
  `setAutoOpenTree(String autoOpenTree)`
  When this item is showing a tree-based picker, which nodes should be opened automatically.
  `SelectItem`
  `setCachePickListResults(Boolean cachePickListResults)`
  For databound pickLists (see PickList.optionDataSource), by default Smart GWT will cache and re-use datasets shown by pickLists in an LRU (least recently used) caching pattern.
  `SelectItem`
  `setCanSelectText(boolean canSelectText)`
  By default SelectItems do not allow users to select the text of the selected value.
  `SelectItem`
  `setClickMaskMode(ClickMaskMode clickMaskMode)`
  Determines the behavior of the click-mask thrown up when this pickList is visible.
  `SelectItem`
  `setControlStyle(String controlStyle)`
  Base CSS class name for a form item's "control box".
  `SelectItem`
  `setDataSetType(String dataSetType)`
  Whether to show the picker as a flat list, or a collapsible tree.
  `static void`
  `setDefaultProperties(SelectItem selectItemProperties)`
  Class level method to set the default properties of this class.
  `SelectItem`
  `setDefaultToFirstOption(Boolean defaultToFirstOption)`
  Select the first option as the default value for this SelectItem.
  `void`
  `setDefaultValues(Integer... defaultValues)`
  Default values used when no value is provided for this item.
  `void`
  `setDefaultValues(String... defaultValues)`
  Default values used when no value is provided for this item.
  `SelectItem`
  `setDisplayField(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`.
  `SelectItem`
  `setEditProxyConstructor(String editProxyConstructor)`
  Default class used to construct the `EditProxy` for this component when the component is `first placed into edit mode`.
  `SelectItem`
  `setEmptyDisplayValue(String emptyDisplayValue)`
  Text to display when this form item has a null or undefined value.
  `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`.
  `SelectItem`
  `setEmptyPickListMessage(String emptyPickListMessage)`
  Empty message to display in the selectItem if PickList.hideEmptyPickList is `false`.
  `SelectItem`
  `setEscapeHTML(Boolean escapeHTML)`
  By default HTML values in a selectItem will be interpreted by the browser.
  `void`
  `setFetchDelay(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.
  `SelectItem`
  `setFetchDisplayedFieldsOnly(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`.
  `SelectItem`
  `setFilterLocally(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.
  `void`
  `setHideEmptyPickList(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.
  `SelectItem`
  `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`.
  `SelectItem`
  `setInitialSort(SortSpecifier... initialSort)`
  An array of `SortSpecifier` objects used to set up the initial sort configuration for this pickList.
  `SelectItem`
  `setMultiple(Boolean multiple)`
  If true, multiple values may be selected.
  `SelectItem`
  `setMultipleAppearance(MultipleAppearance multipleAppearance)`
  How should items with `multiple` set to 'true' be displayed?
  `SelectItem`
  `setOpenOnDownArrow(Boolean openOnDownArrow)`
  Causes the PickList to open when the down arrow is pressed, default false.
  `SelectItem`
  `setOpenOnSpace(Boolean openOnSpace)`
  Causes the PickList to open when the spacebar is pressed, default false.
  `SelectItem`
  `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&#010 not null, this will be passed to the datasource as `RPCRequest` properties when&#010 performing the fetch operation on the dataSource to obtain a data-value to display-value&#010 mapping
  `SelectItem`
  `setOptionOperationId(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.
  `SelectItem`
  `setPickerClearButtonTitle(String pickerClearButtonTitle)`
  The title for the `pickerClearButton`.
  `SelectItem`
  `setPickerExitButtonTitle(String pickerExitButtonTitle)`
  The title for the `pickerExitButton`.
  `SelectItem`
  `setPickerIconHeight(Integer pickerIconHeight)`
  If `showPickerIcon` is true for this item, this property governs the size of the picker icon.
  `SelectItem`
  `setPickerIconSrc(String pickerIconSrc)`
  If `showPickerIcon` is true for this item, this property governs the `src` of the picker icon image to be displayed.
  `SelectItem`
  `setPickerIconStyle(String pickerIconStyle)`
  Base CSS class name for a form item's picker icon cell.
  `SelectItem`
  `setPickerIconWidth(Integer pickerIconWidth)`
  If `showPickerIcon` is true for this item, this property governs the size of the picker icon.
  `void`
  `setPickListBaseStyle(String pickListBaseStyle)`
  Base Style for pickList cells.
  `void`
  `setPickListCellHeight(int pickListCellHeight)`
  Cell Height for this item's pickList.
  `SelectItem`
  `setPickListConstructor(String pickListConstructor)`
  The Class to use when creating a picker of type "list" for a FormItem.
  `SelectItem`
  `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)`
  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 filter operation on the dataSource to obtain the set of options for the list.
  `SelectItem`
  `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(Integer pickListMaxWidth)`
  Maximum width for this item's pickList.
  `SelectItem`
  `setPickListPlacement(PanelPlacement pickListPlacement)`
  Controls where the PickList is placed.
  `SelectItem`
  `setPickListPlacement(Canvas pickListPlacement)`
  Controls where the PickList is placed.
  `SelectItem`
  `setPickListPlacement(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(Integer pickListWidth)`
  Default width to show the pickList.
  `SelectItem`
  `setPickTreeConstructor(String pickTreeConstructor)`
  The Class to use when creating a picker of type "tree" for a FormItem.
  `SelectItem`
  `setProgressiveLoading(Boolean progressiveLoading)`
  Indicates whether or not this SelectItem will load its list of options `progressively`.
  `SelectItem`
  `setRootNodeId(Integer rootNodeId)`
  When this item is showing a tree-based picker, this is the `id` of the record to use as the `root` node.
  `SelectItem`
  `setRootNodeId(String rootNodeId)`
  When this item is showing a tree-based picker, this is the `id` of the record to use as the `root` node.
  `SelectItem`
  `setSaveOnEnter(Boolean saveOnEnter)`
  Select items will submit their containing form on enter keypress if `saveOnEnter` is true.
  `SelectItem`
  `setSeparateSpecialValues(Boolean separateSpecialValues)`
  If true, `special values` such as the empty value will be shown in a separate non-scrolling area, in the `separateValuesList`.
  `SelectItem`
  `setSeparatorRows(ListGridRecord[] separatorRows)`
  Array of records to show between matching and non-matching rows in the PickList.
  `SelectItem`
  `setShowAllOptions(Boolean showAllOptions)`
  If true, even non-matching options will be shown, with configurable `separatorRows` in between.
  `SelectItem`
  `setShowFocused(Boolean showFocused)`
  When this item receives focus, should it be re-styled to indicate it has focus?
  `SelectItem`
  `setShowHintInField(Boolean showHintInField)`
  If showing a hint for this form item, should it be shown within the field?
  `SelectItem`
  `setShowOptionsFromDataSource(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.
  `SelectItem`
  `setShowOver(boolean showOver)`
  When the user rolls over this item, should it be re-styled to indicate it has focus?
  `SelectItem`
  `setShowPickerIcon(Boolean showPickerIcon)`
  Should we show a special 'picker' `icon` for this form item? Picker icons are customizable via `pickerIconProperties`.
  `SelectItem`
  `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.
  `SelectItem`
  `setSortField(Integer sortField)`
  Specifies one or more fields by which this item should be initially sorted.
  `SelectItem`
  `setSortField(String sortField)`
  Specifies one or more fields by which this item should be initially sorted.
  `SelectItem`
  `setSortField(String... sortField)`
  Specifies one or more fields by which this item should be initially sorted.
  `void`
  `setSpecialValues(String... values)`
  Set the specialValues for this item.
  `void`
  `setSpecialValues(LinkedHashMap valueMap)`
  Set the specialValues for this item.
  `SelectItem`
  `setSpecialValues(Map specialValues)`
  A set of "special" values such as "All", "None" or "Invalid" that do not appear in the normal `com.smartgwt.client.types.ValueMap` or in the data returned by the `optionDataSource`.
  `SelectItem`
  `setTextBoxStyle(String textBoxStyle)`
  Base CSS class name for a form item's text box element.
  `SelectItem`
  `setTextMatchStyle(TextMatchStyle textMatchStyle)`
  When applying filter criteria to pickList data, what type of matching to use.
  `SelectItem`
  `setUpdateControlOnOver(Boolean updateControlOnOver)`
  If `FormItem.showOver` is true, setting this property to false will explicitly disable showing the "Over" state for the control table element of this item (if present).
  `SelectItem`
  `setUpdateTextBoxOnOver(Boolean updateTextBoxOnOver)`
  If `FormItem.showOver` is true, setting this property to false will explicitly disable showing the "Over" state for the TextBox element of this item.
  `SelectItem`
  `setUseClientFiltering(Boolean useClientFiltering)`
  For `databound` items, this property will be passed to the generated ResultSet data object for the pickList as `ResultSet.useClientFiltering`.
  `SelectItem`
  `setValueField(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(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.
  `void`
  `setValues(String... values)`
  Set the values of a SelectItem with multiple=true.
  `void`
  `showPicker()`
  Method to show a picker for this item.

  ### 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, checkFormItemType, clearErrors, clearValue, disable, disableIcon, enable, enableIcon, error, error, errorIfNotCreated, focusAfterItem, focusInItem, getAccessKey, getAlign, getAllowExpressions, getAlwaysFetchMissingValues, getAlwaysShowControlBox, getApplyAlignToText, getApplyHeightToTextBox, getAriaRole, getAttribute, getAttributeAsBoolean, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsObject, getAttributeAsString, getAutoComplete, getAutoCompleteKeywords, getBrowserInputType, getBrowserSpellCheck, getCanEdit, getCanEditOpaqueValues, getCanFocus, getCanHover, getCanTabToIcons, getCanvasAutoChild, getCellHeight, getCellStyle, getChangeOnKeypress, getClassName, getClipStaticValue, getClipTitle, getConfig, getContainerWidget, getCriteriaField, getCriterion, getCriterion, getCursorPosition, getCustomState, getDataPath, getDateFormatter, getDecimalPad, getDecimalPrecision, getDefaultIconSrc, getDefaultOperator, getDeferActionConversion, getDestroyed, getDisabled, getDisabledHover, getDisableIconsOnReadOnly, getDisplayValue, getDisplayValue, getEditorTypeConfig, getEditPendingCSSText, getEmptyValueIcon, getEndRow, getErrorIconHeight, getErrorIconProperties, getErrorIconSrc, getErrorIconWidth, getErrorMessageWidth, getErrors, getExportFormat, getExtraControlTableCSS, getExtraTextBoxCSS, getFetchMissingValues, getFieldName, getForeignDisplayField, getForm, getFormat, getFormItemAutoChild, getFormula, getFullDataPath, getGlobalTabIndex, getGridColNum, getGridRowNum, getHeight, getHeightAsString, getHidden, getHint, getHintStyle, getHoverAlign, getHoverDelay, getHoverFocusKey, getHoverHeight, getHoverHeightAsString, getHoverOpacity, getHoverPersist, getHoverStyle, getHoverVAlign, getHoverWidth, getHoverWidthAsString, getIcon, getIconBaseStyle, getIconHeight, getIconHSpace, getIconPageRect, getIconPrompt, getIconRect, getIcons, getIconTabPosition, getIconVAlign, getIconWidth, getID, getImageURLPrefix, getImageURLSuffix, getImplicitSave, getImplicitSaveOnBlur, getInputFormat, getLeft, getLinearColSpan, getLinearColSpanAsString, getLinearEndRow, getLinearEndRowAsString, getLinearStartRow, getLinearStartRowAsString, getLinearWidth, getLinearWidthAsString, getListGrid, getLoadingDisplayValue, getLocateItemBy, getMinHintWidth, getMultipleValueSeparator, getName, getNullOriginalValueText, getOperator, getOptionCriteria, getOptionDataSourceAsString, getOptionFilterContext, getOptionTextMatchStyle, getOriginalValueMessage, getPageLeft, getPageRect, getPageTop, getPaletteDefaults, getPicker, getPickerIcon, getPickerIcon, getPickerIconName, getPickerIconPrompt, getPickerIconProperties, getPickerIconTabPosition, getPixelHeight, getPixelWidth, getPrintReadOnlyTextBoxStyle, getPrintTextBoxStyle, getPrintTitleStyle, getPrompt, getReadOnlyCanSelectText, getReadOnlyControlStyle, getReadOnlyDisplay, getReadOnlyHover, getReadOnlyTextBoxStyle, getReadOnlyWhen, getRect, getRedrawOnChange, getRejectInvalidValueOnChange, getRequired, getRequiredMessage, getRequiredRightTitlePrefix, getRequiredRightTitleSuffix, getRequiredTitlePrefix, getRequiredTitleSuffix, getRequiredWhen, getRightTitlePrefix, getRightTitleSuffix, getRowSpan, getScClassName, getSelectOnClick, getSelectOnFocus, getShouldSaveValue, getShowClippedTitleOnHover, getShowClippedValueOnHover, getShowDeletions, getShowDisabled, getShowDisabledIconsOnFocus, getShowDisabledPickerIconOnFocus, getShowErrorIcon, getShowErrorIconInline, getShowErrorStyle, getShowErrorText, getShowFocusedErrorState, getShowFocusedIcons, getShowFocusedPickerIcon, getShowHint, getShowIcons, getShowIconsOnFocus, getShowImageAsURL, getShowOldValueInHover, getShowOverIcons, getShowPending, getShowPickerIconOnFocus, getShowRTL, getShowTitle, getShowValueIconOnly, getStartRow, getStaticHeight, getStopOnError, getStoreDisplayValues, getSupportsCutPasteEvents, getSuppressValueIcon, getSynchronousValidation, getTabIndex, getTextAlign, getTextFormula, getTimeFormatter, getTitle, getTitleAlign, getTitleColSpan, getTitleOrientation, getTitlePrefix, getTitleStyle, getTitleSuffix, getTitleVAlign, getTooltip, getTop, getType, getUpdatePickerIconOnOver, getUseAdvancedCriteria, getUseDisabledHintStyleForReadOnly, getUseLocalDisplayFieldValue, getValidateOnChange, getValidateOnExit, getValidOperators, getVAlign, getValue, getValueAsFloat, getValueAsInteger, getValueAsLong, getValueAsRecordList, getValueDeselectedCSSText, getValueIconHeight, getValueIconLeftPadding, getValueIconRightPadding, getValueIconSize, getValueIconWidth, getValueMap, getValueMapAsArray, getVisible, getVisibleHeight, getVisibleTitleWidth, getVisibleWhen, getVisibleWidth, getWarnOnEditorTypeConversion, getWarnOnEditorTypeConversionDefault, getWidth, getWidthAsString, getWrapHintText, getWrapStaticValue, getWrapTitle, handleWarnOnEditorTypeConversion, hasAdvancedCriteria, hasErrors, hide, hideIcon, invalidateDisplayValueCache, isAssignableFrom, isConfigOnly, isCreated, isCutEvent, isDisabled, isDrawn, isFocused, isInGrid, isPasteEvent, isVisible, linkToInstanceUponCreate, mapDisplayToValue, mapValueToDisplay, mapValueToDisplay, mapValueToDisplay, redraw, redraw, removeIcon, selectedRecordChanged, setAccessKey, setAlign, setAllowExpressions, 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, setBrowserInputType, setBrowserSpellCheck, setCanEdit, setCanEditCriterionPredicate, setCanEditOpaqueValues, setCanFocus, setCanHover, setCanTabToIcons, setCellHeight, setCellStyle, setChangeOnKeypress, setClipStaticValue, setClipTitle, setColSpan, setColSpan, setConfigOnly, setCriteriaField, setCriterion, setCriterionGetter, setCriterionSetter, setCustomStateGetter, setDataPath, setDateFormatter, setDecimalPad, setDecimalPrecision, setDefaultIconSrc, setDefaultOperator, setDefaultProperties, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDeferActionConversion, setDisabled, setDisabledHover, setDisableIconsOnReadOnly, setDisplayFormat, setDisplayFormat, setEditorProperties, setEditorType, setEditorType, setEditorType, setEditorValueFormatter, setEditorValueParser, setEditPendingCSSText, setEmptyValueIcon, setEndRow, setErrorFormatter, setErrorIconHeight, setErrorIconProperties, setErrorIconSrc, setErrorIconWidth, setErrorMessageWidth, setErrorOrientation, setErrors, setErrors, setExportFormat, setExtraControlTableCSS, setExtraTextBoxCSS, setFetchMissingValues, setForeignDisplayField, setFormat, setFormula, setGlobalTabIndex, setHeight, setHeight, setHidden, setHint, setHintStyle, setHoverAlign, setHoverDelay, setHoverFocusKey, setHoverHeight, setHoverHeight, setHoverOpacity, setHoverPersist, setHoverStyle, setHoverVAlign, setHoverWidth, setHoverWidth, setIconBaseStyle, setIconDisabled, setIconHeight, setIconHSpace, setIconPrompt, setIcons, setIconShowOnFocus, setIconVAlign, setIconWidth, setID, setImageURLPrefix, setImageURLSuffix, setImplicitSave, setImplicitSaveOnBlur, setInitHandler, setInputFormat, setInputTransformer, setItemHoverFormatter, setItemTitleHoverFormatter, setItemValueHoverFormatter, setJavaScriptObject, setLeft, setLinearColSpan, setLinearColSpan, setLinearEndRow, setLinearEndRow, setLinearStartRow, setLinearStartRow, setLinearWidth, setLinearWidth, setLoadingDisplayValue, setLocateItemBy, setMinHintWidth, setMultipleValueSeparator, setName, setNullOriginalValueText, setNullProperty, setOperator, setOptionCriteria, setOptionDataSource, setOptionFilterContext, setOptionTextMatchStyle, setOriginalValueMessage, setPickerIconName, setPickerIconPrompt, setPickerIconProperties, setPrintReadOnlyTextBoxStyle, setPrintTextBoxStyle, setPrintTitleStyle, setPrompt, setProperty, setProperty, setProperty, setProperty, setProperty, setReadOnlyCanSelectText, setReadOnlyControlStyle, setReadOnlyDisplay, setReadOnlyHover, setReadOnlyTextBoxStyle, setReadOnlyWhen, setRedrawOnChange, setRejectInvalidValueOnChange, setRequired, setRequiredMessage, setRequiredRightTitlePrefix, setRequiredRightTitleSuffix, setRequiredTitlePrefix, setRequiredTitleSuffix, setRequiredWhen, setRightTitlePrefix, setRightTitleSuffix, setRowSpan, setScClassName, setSelectOnClick, setSelectOnFocus, setShouldSaveValue, setShowClippedTitleOnHover, setShowClippedValueOnHover, setShowDeletions, setShowDisabled, setShowDisabledIconsOnFocus, setShowDisabledPickerIconOnFocus, setShowErrorIcon, setShowErrorIconInline, setShowErrorStyle, setShowErrorText, setShowFocusedErrorState, setShowFocusedIcons, setShowFocusedPickerIcon, setShowHint, setShowIcons, setShowIconsOnFocus, setShowIfCondition, setShowImageAsURL, setShowOldValueInHover, setShowOverIcons, setShowPending, setShowPickerIconOnFocus, setShowRTL, setShowTitle, setShowValueIconOnly, setStartRow, setStateCustomizer, setStaticHeight, setStopOnError, setStoreDisplayValues, setSupportsCutPasteEvents, setSuppressValueIcon, setSynchronousValidation, setTabIndex, setTextAlign, setTextFormula, setTimeFormatter, setTitle, setTitleAlign, setTitleColSpan, setTitleHoverFormatter, setTitleOrientation, setTitlePrefix, setTitleStyle, setTitleSuffix, setTitleVAlign, setTooltip, setTop, setType, setUpdatePickerIconOnOver, setUseAdvancedCriteria, setUseDisabledHintStyleForReadOnly, setUseLocalDisplayFieldValue, setUseObjectFactoryForTypeFallback, setValidateOnChange, setValidateOnExit, setValidators, setValidOperators, setVAlign, setValue, setValue, setValue, setValue, setValue, setValue, setValueByDisplayValue, setValueByDisplayValue, setValueDeselectedCSSText, setValueFormatter, setValueHoverFormatter, setValueIconHeight, setValueIconLeftPadding, setValueIconMapper, setValueIconRightPadding, setValueIcons, setValueIconSize, setValueIconWidth, setValueMap, setValueMap, setVisible, setVisibleWhen, setWarnOnEditorTypeConversion, setWarnOnEditorTypeConversionDefault, setWidth, setWidth, setWrapHintText, setWrapStaticValue, setWrapTitle, shouldApplyHeightToTextBox, shouldFetchMissingValue, shouldSaveOnEnter, shouldStopKeyPressBubbling, show, showIcon, stopHover, storeValue, storeValue, updateState, validate, valueClipped`

  ### Methods inherited from class com.smartgwt.client.data.Field

  `getCanExport, getExportTitle, getPrimaryKey, getSortByField, setCanExport, setExportTitle, setPrimaryKey, setSortByField`

  ### 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, getAttributeAsElement, 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 Details

  - ### SelectItem

    public SelectItem()

  - ### SelectItem

    public SelectItem(JavaScriptObject jsObj)

  - ### SelectItem

    public SelectItem(String name)

  - ### SelectItem

    public SelectItem(String name, String title)

- ## Method Details

  - ### getOrCreateRef

    public static SelectItem getOrCreateRef(JavaScriptObject jsObj)

  - ### changeAutoChildDefaults

    public static void changeAutoChildDefaults(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(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 SelectItem setAddUnknownValues(Boolean addUnknownValues)
    If this item's value is set (via `setValue()` or similar) to a value which is not present in the `com.smartgwt.client.types.ValueMap`, should the value be rejected.

    If set to `false` the setValue() call will have no effect if the value is not a valid option.

    If set to `true` the item's value will be updated to the new value, and the value will be added to the set of options displayed in the pick-list until the next call to `setValueMap()` or `setValue()`.

    Exception: If the value is set to `null` but there is no null entry in the valueMap for this item, setting `addUnknownValues` to true will not cause a null option to show up at the top of the select item pickList. Whether an empty option is shown in the pickList is governed by `allowEmptyValue` instead.

    Note that this property has no effect if the selectItem has a specified `optionDataSource`. If `setValue()` is called on a databound SelectItem and the new value does not match any loaded options, the value will be accepted, but not added to the options displayed in the pickList. Also note that if a `displayField` exists, a fetch will be performed in an attempt to retrieve a valid display value, as described under `FormItem.fetchMissingValues`. If specified the `FormItem.loadingDisplayValue` will be displayed while the fetch is in progress, and then the real value (mapped to a display field value if a matching record was found) will be displayed when the fetch completes.

    Note : This is an advanced setting

    Parameters:
      `addUnknownValues` - New addUnknownValues value. Default value is true
    Returns:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - Dependent Selects Example

  - ### getAddUnknownValues

    public Boolean getAddUnknownValues()
    If this item's value is set (via `setValue()` or similar) to a value which is not present in the `com.smartgwt.client.types.ValueMap`, should the value be rejected.

    If set to `false` the setValue() call will have no effect if the value is not a valid option.

    If set to `true` the item's value will be updated to the new value, and the value will be added to the set of options displayed in the pick-list until the next call to `setValueMap()` or `setValue()`.

    Exception: If the value is set to `null` but there is no null entry in the valueMap for this item, setting `addUnknownValues` to true will not cause a null option to show up at the top of the select item pickList. Whether an empty option is shown in the pickList is governed by `allowEmptyValue` instead.

    Note that this property has no effect if the selectItem has a specified `optionDataSource`. If `setValue()` is called on a databound SelectItem and the new value does not match any loaded options, the value will be accepted, but not added to the options displayed in the pickList. Also note that if a `displayField` exists, a fetch will be performed in an attempt to retrieve a valid display value, as described under `FormItem.fetchMissingValues`. If specified the `FormItem.loadingDisplayValue` will be displayed while the fetch is in progress, and then the real value (mapped to a display field value if a matching record was found) will be displayed when the fetch completes.

    Returns:
      Current addUnknownValues value. Default value is true
    See Also:
      - Dependent Selects Example

  - ### setAllowEmptyValue

    public SelectItem setAllowEmptyValue(Boolean allowEmptyValue)
    If set to true, always show an empty option in this item's pickList, allowing the user to clear the value (even if there is no empty entry in the valueMap for the item).

    The empty value will be displayed with the `emptyDisplayValue`.

    With a `databound selectItem`, enabling `allowEmptyValue` disables data paging by default - all data matching the current criteria will be requested. However, enabling `separateSpecialValues` allows data paging to be used if required.

    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 false
    Returns:
      `SelectItem` instance, for chaining setter calls

  - ### getAllowEmptyValue

    public Boolean getAllowEmptyValue()
    If set to true, always show an empty option in this item's pickList, allowing the user to clear the value (even if there is no empty entry in the valueMap for the item).

    The empty value will be displayed with the `emptyDisplayValue`.

    With a `databound selectItem`, enabling `allowEmptyValue` disables data paging by default - all data matching the current criteria will be requested. However, enabling `separateSpecialValues` allows data paging to be used if required.

    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 false

  - ### setAllowMultiCharSearch

    public SelectItem setAllowMultiCharSearch(boolean allowMultiCharSearch)
    By default, if multiple keys are pressed in quick succession, a SelectItem will buffer them together and use the resulting multi-char string when searching. Set this attribute to false to force the item to match only one character at a time.
    Parameters:
      `allowMultiCharSearch` - New allowMultiCharSearch value. Default value is true
    Returns:
      `SelectItem` instance, for chaining setter calls

  - ### getAllowMultiCharSearch

    public boolean getAllowMultiCharSearch()
    By default, if multiple keys are pressed in quick succession, a SelectItem will buffer them together and use the resulting multi-char string when searching. Set this attribute to false to force the item to match only one character at a time.
    Returns:
      Current allowMultiCharSearch value. Default value is true

  - ### setAutoFetchData

    public SelectItem setAutoFetchData(Boolean autoFetchData)
    If this select item retrieves its options from a `dataSource`, should options be fetched from the server when the item is first drawn, or should this fetch be delayed until the user opens the pickList.

    The default is true in order to allow the user to select a value via keyboard input while keyboard focus is on the SelectItem but the pickList has not actually been shown.

    Note : This is an advanced setting

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

  - ### getAutoFetchData

    public Boolean getAutoFetchData()
    If this select item retrieves its options from a `dataSource`, should options be fetched from the server when the item is first drawn, or should this fetch be delayed until the user opens the pickList.

    The default is true in order to allow the user to select a value via keyboard input while keyboard focus is on the SelectItem but the pickList has not actually been shown.

    Returns:
      Current autoFetchData value. Default value is true

  - ### setAutoOpenTree

    public SelectItem setAutoOpenTree(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:
      `SelectItem` instance, for chaining setter calls

  - ### getAutoOpenTree

    public 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 SelectItem setCachePickListResults(Boolean cachePickListResults)
    For databound pickLists (see PickList.optionDataSource), by default Smart GWT will cache and re-use datasets shown by pickLists in an LRU (least recently used) caching pattern.

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

    Parameters:
      `cachePickListResults` - New cachePickListResults value. Default value is true
    Returns:
      `SelectItem` 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 pickLists in an LRU (least recently used) caching pattern.

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

    Returns:
      Current cachePickListResults value. Default value is true

  - ### setCanSelectText

    public SelectItem setCanSelectText(boolean canSelectText)
    By default SelectItems do not allow users to select the text of the selected value.
    Overrides:
      `setCanSelectText` in class `FormItem`
    Parameters:
      `canSelectText` - New canSelectText value. Default value is false
    Returns:
      `SelectItem` instance, for chaining setter calls

  - ### getCanSelectText

    public boolean getCanSelectText()
    By default SelectItems do not allow users to select the text of the selected value.
    Overrides:
      `getCanSelectText` in class `FormItem`
    Returns:
      Current canSelectText value. Default value is false

  - ### setClickMaskMode

    public SelectItem setClickMaskMode(ClickMaskMode clickMaskMode)
    Determines the behavior of the click-mask thrown up when this pickList is visible.

    The default value, "hard", matches the familiar behavior of combos and selects on Windows, Mac and other platforms - mouse-events such as rollovers are blocked and, when a click is received, the picker is hidden and the event is cancelled.

    When `clickMaskMode` is "soft", mouse-events continue to fire, meaning that rollover styles, for example, continue to be updated. When a click is received in this mode, the picker is hidden and the click event is allowed to proceed to its target - this means that clicking an item with an open picker will re-open the picker.

    Parameters:
      `clickMaskMode` - New clickMaskMode value. Default value is "hard"
    Returns:
      `SelectItem` instance, for chaining setter calls

  - ### getClickMaskMode

    public ClickMaskMode getClickMaskMode()
    Determines the behavior of the click-mask thrown up when this pickList is visible.

    The default value, "hard", matches the familiar behavior of combos and selects on Windows, Mac and other platforms - mouse-events such as rollovers are blocked and, when a click is received, the picker is hidden and the event is cancelled.

    When `clickMaskMode` is "soft", mouse-events continue to fire, meaning that rollover styles, for example, continue to be updated. When a click is received in this mode, the picker is hidden and the click event is allowed to proceed to its target - this means that clicking an item with an open picker will re-open the picker.

    Returns:
      Current clickMaskMode value. Default value is "hard"

  - ### setControlStyle

    public SelectItem setControlStyle(String controlStyle)
    Base CSS class name for a form item's "control box". This is an HTML element which contains the text box and picker icon for the item.

    See `FormItem.alwaysShowControlBox` for details on when the control box is written out.

    See `FormItemStyling` for an overview of formItem styling, and the `CompoundFormItem_skinning` discussion for special skinning considerations.

    Note : This is an advanced setting

    Overrides:
      `setControlStyle` in class `FormItem`
    Parameters:
      `controlStyle` - New controlStyle value. Default value is "selectItemControl"
    Returns:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `FormItem.setCellStyle(java.lang.String)`
      - `FormItemBaseStyle`
      - `Appearance overview and related methods`

  - ### getControlStyle

    public String getControlStyle()
    Base CSS class name for a form item's "control box". This is an HTML element which contains the text box and picker icon for the item.

    See `FormItem.alwaysShowControlBox` for details on when the control box is written out.

    See `FormItemStyling` for an overview of formItem styling, and the `CompoundFormItem_skinning` discussion for special skinning considerations.

    Overrides:
      `getControlStyle` in class `FormItem`
    Returns:
      Current controlStyle value. Default value is "selectItemControl"
    See Also:
      - `FormItem.getCellStyle()`
      - `FormItemBaseStyle`
      - `Appearance overview and related methods`

  - ### setDataSetType

    public SelectItem setDataSetType(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:
      `SelectItem` instance, for chaining setter calls

  - ### getDataSetType

    public 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 SelectItem setDefaultToFirstOption(Boolean defaultToFirstOption)
    Select the first option as the default value for this SelectItem.

    If options are derived from a dataSource, the first value returned by the server will be used, otherwise the first value in the valueMap. Note that setting this property to true will trigger a fetch at soon as the form is created, because the form will try to establish a default value at that time.

    If enabled, this setting overrides `defaultValue` and `defaultDynamicValue()`.

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

  - ### getDefaultToFirstOption

    public Boolean getDefaultToFirstOption()
    Select the first option as the default value for this SelectItem.

    If options are derived from a dataSource, the first value returned by the server will be used, otherwise the first value in the valueMap. Note that setting this property to true will trigger a fetch at soon as the form is created, because the form will try to establish a default value at that time.

    If enabled, this setting overrides `defaultValue` and `defaultDynamicValue()`.

    Returns:
      Current defaultToFirstOption value. Default value is false

  - ### getDefaultValue

    public Object getDefaultValue()
    Static default value for this SelectItem. To default to the first option use `defaultToFirstOption` instead.
    Overrides:
      `getDefaultValue` in class `FormItem`
    Returns:
      Current defaultValue value. Default value is null
    See Also:
      - `com.smartgwt.client.widgets.form.fields.FormItem#defaultDynamicValue`
      - Enable & Disable Example

  - ### setDisplayField

    public SelectItem setDisplayField(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:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `FormItem.getDisplayFieldName()`
      - `FormItem.invalidateDisplayValueCache()`
      - `DataBinding`
      - List - Related Records Example

  - ### getDisplayField

    public 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 foreignDisplay or displayField specification was found, and the `FormItem.valueField` for this item is hidden in the `FormItem.optionDataSource`, this method will return the title field for the `optionDataSource`.
      . Default value is null
    See Also:
      - `FormItem.getDisplayFieldName()`
      - `FormItem.invalidateDisplayValueCache()`
      - `DataBinding`
      - List - Related Records Example

  - ### setEditProxyConstructor

    public SelectItem setEditProxyConstructor(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 `FormItem`
    Parameters:
      `editProxyConstructor` - New editProxyConstructor value. Default value is "SelectItemEditProxy"
    Returns:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `SCClassName`

  - ### getEditProxyConstructor

    public 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 `FormItem`
    Returns:
      Current editProxyConstructor value. Default value is "SelectItemEditProxy"
    See Also:
      - `SCClassName`

  - ### setEmptyDisplayValue

    public SelectItem setEmptyDisplayValue(String emptyDisplayValue)
    Text to display when this form item has a null or undefined value.

    If the formItem has a databound pickList, and its `FormItem.displayField` or `FormItem.valueField` (if the former isn't set) has an undefined `emptyCellValue` setting, that field's `emptyCellValue` will automatically be set to the `emptyDisplayValue`.

    Overrides:
      `setEmptyDisplayValue` in class `FormItem`
    Parameters:
      `emptyDisplayValue` - New emptyDisplayValue value. Default value is "&nbsp;"
    Returns:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `HTMLString`

  - ### getEmptyDisplayValue

    public String getEmptyDisplayValue()
    Text to display when this form item has a null or undefined value.

    If the formItem has a databound pickList, and its `FormItem.displayField` or `FormItem.valueField` (if the former isn't set) has an undefined `emptyCellValue` setting, that field's `emptyCellValue` will automatically be set to the `emptyDisplayValue`.

    Overrides:
      `getEmptyDisplayValue` in class `FormItem`
    Returns:
      Current emptyDisplayValue value. Default value is "&nbsp;"
    See Also:
      - `HTMLString`

  - ### setEmptyPickListMessage

    public SelectItem setEmptyPickListMessage(String emptyPickListMessage)
    Empty message to display in the selectItem 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:
      `SelectItem` instance, for chaining setter calls

  - ### getEmptyPickListMessage

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

  - ### setEscapeHTML

    public SelectItem setEscapeHTML(Boolean escapeHTML)
    By default HTML values in a selectItem will be interpreted by the browser. Setting this flag to true will causes HTML characters to be escaped, meaning the raw value of the field (for example `"<b>AAA</b>"`) is displayed to the user rather than the interpreted HTML (for example `"AAA"`)
    Overrides:
      `setEscapeHTML` in class `FormItem`
    Parameters:
      `escapeHTML` - New escapeHTML value. Default value is false
    Returns:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `Appearance overview and related methods`

  - ### getEscapeHTML

    public Boolean getEscapeHTML()
    By default HTML values in a selectItem will be interpreted by the browser. Setting this flag to true will causes HTML characters to be escaped, meaning the raw value of the field (for example `"<b>AAA</b>"`) is displayed to the user rather than the interpreted HTML (for example `"AAA"`)
    Overrides:
      `getEscapeHTML` in class `FormItem`
    Returns:
      Current escapeHTML value. Default value is false
    See Also:
      - `Appearance overview and related methods`

  - ### setFetchDisplayedFieldsOnly

    public SelectItem setFetchDisplayedFieldsOnly(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:
      `SelectItem` instance, for chaining setter calls

  - ### getFetchDisplayedFieldsOnly

    public 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

  - ### setFilterLocally

    public SelectItem setFilterLocally(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:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `FormItem.setFilterLocally(java.lang.Boolean)`

  - ### getFilterLocally

    public 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()`

  - ### setIconPlacement

    public SelectItem 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:
      `SelectItem` 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 SelectItem 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:
      `SelectItem` 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

  - ### setMultiple

    public SelectItem setMultiple(Boolean multiple)
    If true, multiple values may be selected.

    The SelectItem will either render as a drop-down allowing multiple selections, or a multi-row list of options similar to a small headerless `ListGrid`, based on the `MultipleAppearance` setting.

    The logical value of the formItem, as retrieved by `getValue()` and set via `setValue()`, is an Array of Strings reflecting the selected values.

    When this value is true, we disable doubleClick events by default, instead issuing two single clicks by forcibly setting `noDoubleClicks: true`. If you need to work with doubleClick events, you can disable this default behavior by explicitly setting formItem.pickListProperties.noDoubleClicks: false.

    Note: `multiple:true` SelectItems with multipleAppearance:"grid" do not currently support optionDataSource binding. You can get around this by calling `DataSource.fetchData()` directly and calling `dsResponse.data.getValueMap()` to obtain a valueMap.

    #### Databound pickLists and missing values

    When a SelectItem has an optionDataSource, if the current value includes entries that do not correspond to records loaded in the pickList, those entries will be dropped if the user makes any changes to the selection. This can occur when:
    - Data paging causes records for some selected values to fall outside the loaded data window
    - The pickListCriteria excludes some selected values
    - The value was set programmatically to something that doesn't exist in the DataSource

    To avoid this issue with data paging, you can set `pickListProperties.dataProperties.fetchMode` to `"local"` to ensure all matching records are loaded upfront:

          ListGrid pickListProperties = new ListGrid();
          pickListProperties.setDataProperties(new ResultSet() {{
              setFetchMode(FetchMode.LOCAL);
          }});
          selectItem.setPickListProperties(pickListProperties);

    For large datasets where loading all records is not practical, consider using `MultiPickerItem` instead. MultiPickerItem provides a dedicated interface for viewing and managing selected values, allowing users to see and deselect any selected value without needing to scroll through or filter the entire dataset.

    If the `multiple` attribute is not explicitly specified, it will default to `false`, unless thie item has a specified `valueMap` and is part of a `filter interface` with `SearchForm.useMultiSelectForValueMaps` set to true.

    Overrides:
      `setMultiple` in class `FormItem`
    Parameters:
      `multiple` - New multiple value. Default value is null
    Returns:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `Appearance overview and related methods`

  - ### getMultiple

    public Boolean getMultiple()
    If true, multiple values may be selected.

    The SelectItem will either render as a drop-down allowing multiple selections, or a multi-row list of options similar to a small headerless `ListGrid`, based on the `MultipleAppearance` setting.

    The logical value of the formItem, as retrieved by `getValue()` and set via `setValue()`, is an Array of Strings reflecting the selected values.

    When this value is true, we disable doubleClick events by default, instead issuing two single clicks by forcibly setting `noDoubleClicks: true`. If you need to work with doubleClick events, you can disable this default behavior by explicitly setting formItem.pickListProperties.noDoubleClicks: false.

    Note: `multiple:true` SelectItems with multipleAppearance:"grid" do not currently support optionDataSource binding. You can get around this by calling `DataSource.fetchData()` directly and calling `dsResponse.data.getValueMap()` to obtain a valueMap.

    #### Databound pickLists and missing values

    When a SelectItem has an optionDataSource, if the current value includes entries that do not correspond to records loaded in the pickList, those entries will be dropped if the user makes any changes to the selection. This can occur when:
    - Data paging causes records for some selected values to fall outside the loaded data window
    - The pickListCriteria excludes some selected values
    - The value was set programmatically to something that doesn't exist in the DataSource

    To avoid this issue with data paging, you can set `pickListProperties.dataProperties.fetchMode` to `"local"` to ensure all matching records are loaded upfront:

          ListGrid pickListProperties = new ListGrid();
          pickListProperties.setDataProperties(new ResultSet() {{
              setFetchMode(FetchMode.LOCAL);
          }});
          selectItem.setPickListProperties(pickListProperties);

    For large datasets where loading all records is not practical, consider using `MultiPickerItem` instead. MultiPickerItem provides a dedicated interface for viewing and managing selected values, allowing users to see and deselect any selected value without needing to scroll through or filter the entire dataset.

    If the `multiple` attribute is not explicitly specified, it will default to `false`, unless thie item has a specified `valueMap` and is part of a `filter interface` with `SearchForm.useMultiSelectForValueMaps` set to true.

    Overrides:
      `getMultiple` in class `FormItem`
    Returns:
      Current multiple value. Default value is null
    See Also:
      - `Appearance overview and related methods`

  - ### setMultipleAppearance

    public SelectItem setMultipleAppearance(MultipleAppearance multipleAppearance)
    How should items with `multiple` set to 'true' be displayed?
    Parameters:
      `multipleAppearance` - New multipleAppearance value. Default value is "picklist"
    Returns:
      `SelectItem` instance, for chaining setter calls

  - ### getMultipleAppearance

    public MultipleAppearance getMultipleAppearance()
    How should items with `multiple` set to 'true' be displayed?
    Returns:
      Current multipleAppearance value. Default value is "picklist"

  - ### setOpenOnDownArrow

    public SelectItem setOpenOnDownArrow(Boolean openOnDownArrow)
    Causes the PickList to open when the down arrow is pressed, default false.

    For native OS widgets, the down arrow changes the value of a select on Windows, but opens the select on Macs. This setting is not recommended unless you are certain that all users of your applications will expect the Mac convention.

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

  - ### getOpenOnDownArrow

    public Boolean getOpenOnDownArrow()
    Causes the PickList to open when the down arrow is pressed, default false.

    For native OS widgets, the down arrow changes the value of a select on Windows, but opens the select on Macs. This setting is not recommended unless you are certain that all users of your applications will expect the Mac convention.

    Returns:
      Current openOnDownArrow value. Default value is false

  - ### setOpenOnSpace

    public SelectItem setOpenOnSpace(Boolean openOnSpace)
    Causes the PickList to open when the spacebar is pressed, default false.

    For native OS widgets, space opens the PickList on Macs, but not on Windows. Consider using this setting if your users are almost entirely Mac users, or enabling it only for users running MacOS.

    However, before using this setting, consider that it means that Spacebar will not be able to be used for another purpose when focus is in a SelectItem.

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

  - ### getOpenOnSpace

    public Boolean getOpenOnSpace()
    Causes the PickList to open when the spacebar is pressed, default false.

    For native OS widgets, space opens the PickList on Macs, but not on Windows. Consider using this setting if your users are almost entirely Mac users, or enabling it only for users running MacOS.

    However, before using this setting, consider that it means that Spacebar will not be able to be used for another purpose when focus is in a SelectItem.

    Returns:
      Current openOnSpace value. Default value is false

  - ### setOptionOperationId

    public SelectItem setOptionOperationId(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:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `DataBinding`

  - ### getOptionOperationId

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

  - ### 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 `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 SelectItem setPickerClearButtonTitle(String pickerClearButtonTitle)
    The title for the `pickerClearButton`.
    Parameters:
      `pickerClearButtonTitle` - New pickerClearButtonTitle value. Default value is "Clear"
    Returns:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `HTMLString`

  - ### getPickerClearButtonTitle

    public 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 SelectItem setPickerExitButtonTitle(String pickerExitButtonTitle)
    The title for the `pickerExitButton`.
    Parameters:
      `pickerExitButtonTitle` - New pickerExitButtonTitle value. Default value is "Done"
    Returns:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `HTMLString`

  - ### getPickerExitButtonTitle

    public String getPickerExitButtonTitle()
    The title for the `pickerExitButton`.
    Returns:
      Current pickerExitButtonTitle value. Default value is "Done"
    See Also:
      - `HTMLString`

  - ### setPickerIconHeight

    public SelectItem setPickerIconHeight(Integer pickerIconHeight)
    If `showPickerIcon` is true for this item, this property governs the size of the picker icon. If unset, the picker icon will be sized as a square to fit in the available height for the icon.

    Note that if spriting is being used, and the image to be displayed is specified using css properties such as `background-image`, `background-size`, changing this value may result in an unexpected appearance as the image will not scale.
    Scaleable spriting can be achieved using the `SCSpriteConfig` format. See the section on spriting in the `skinning overview` for further information.

    Note : This is an advanced setting

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

  - ### getPickerIconHeight

    public Integer getPickerIconHeight()
    If `showPickerIcon` is true for this item, this property governs the size of the picker icon. If unset, the picker icon will be sized as a square to fit in the available height for the icon.

    Note that if spriting is being used, and the image to be displayed is specified using css properties such as `background-image`, `background-size`, changing this value may result in an unexpected appearance as the image will not scale.
    Scaleable spriting can be achieved using the `SCSpriteConfig` format. See the section on spriting in the `skinning overview` for further information.

    Overrides:
      `getPickerIconHeight` in class `FormItem`
    Returns:
      Current pickerIconHeight value. Default value is null

  - ### setPickerIconSrc

    public SelectItem setPickerIconSrc(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 `pickerIconStyle` property.

    Note : This is an advanced setting

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

  - ### getPickerIconSrc

    public 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 `pickerIconStyle` property.

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

  - ### setPickerIconStyle

    public SelectItem setPickerIconStyle(String pickerIconStyle)
    Base CSS class name for a form item's picker icon cell. If unset, inherits from this item's `controlStyle`.
    Overrides:
      `setPickerIconStyle` in class `FormItem`
    Parameters:
      `pickerIconStyle` - New pickerIconStyle value. Default value is "selectItemPickerIcon"
    Returns:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `FormItem.setCellStyle(java.lang.String)`
      - `FormItemBaseStyle`
      - `FormItem Styling`

  - ### getPickerIconStyle

    public String getPickerIconStyle()
    Base CSS class name for a form item's picker icon cell. If unset, inherits from this item's `controlStyle`.
    Overrides:
      `getPickerIconStyle` in class `FormItem`
    Returns:
      Current pickerIconStyle value. Default value is "selectItemPickerIcon"
    See Also:
      - `FormItem.getCellStyle()`
      - `FormItemBaseStyle`
      - `FormItem Styling`

  - ### setPickerIconWidth

    public SelectItem setPickerIconWidth(Integer pickerIconWidth)
    If `showPickerIcon` is true for this item, this property governs the size of the picker icon. If unset, the picker icon will be sized as a square to fit in the available height for the icon.

    Note that if spriting is being used, and the image to be displayed is specified using css properties such as `background-image`, `background-size`, changing this value may result in an unexpected appearance as the image will not scale.
    Scaleable spriting can be achieved using the `SCSpriteConfig` format. See the section on spriting in the `skinning overview` for further information.

    Note : This is an advanced setting

    Overrides:
      `setPickerIconWidth` in class `FormItem`
    Parameters:
      `pickerIconWidth` - New pickerIconWidth value. Default value is null
    Returns:
      `SelectItem` instance, for chaining setter calls

  - ### getPickerIconWidth

    public Integer getPickerIconWidth()
    If `showPickerIcon` is true for this item, this property governs the size of the picker icon. If unset, the picker icon will be sized as a square to fit in the available height for the icon.

    Note that if spriting is being used, and the image to be displayed is specified using css properties such as `background-image`, `background-size`, changing this value may result in an unexpected appearance as the image will not scale.
    Scaleable spriting can be achieved using the `SCSpriteConfig` format. See the section on spriting in the `skinning overview` for further information.

    Overrides:
      `getPickerIconWidth` in class `FormItem`
    Returns:
      Current pickerIconWidth value. Default value is null

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

  - ### getPickList

    public ListGrid getPickList()
    ListGrid-based AutoChild created by the system to display a list of pickable options for this item.

    The pickList is automatically generated and displayed by the system when necessary. It may be customized via properties such as `pickListConstructor`, `pickTreeConstructor`, `pickListProperties` and more. See the PickList overview for more information.

    Accessing the generated pickList at runtime is an advanced usage. In most cases developers should not modify this generated component directly but should instead use attributes on the formItem to configure it.

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

    Returns:
      Current pickList value. Default value is null

  - ### setPickListConstructor

    public SelectItem setPickListConstructor(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:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `SCClassName`
      - `PickList overview and related methods`

  - ### getPickListConstructor

    public 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 SelectItem 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:
      `SelectItem` 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 SelectItem 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:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `setValueField(java.lang.String)`
      - `PickList overview and related methods`
      - List - Related Records Example

  - ### getPickListFields

    public ListGridField[] getPickListFields()
    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`.

    Returns:
      Current pickListFields value. Default value is null
    See Also:
      - `getValueField()`
      - `PickList overview and related methods`
      - List - Related Records Example

  - ### setPickListPlacement

    public SelectItem 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 accommodate 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 `done button` that hides the expanded interface.

    Parameters:
      `pickListPlacement` - New pickListPlacement value. Default value is null
    Returns:
      `SelectItem` 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 accommodate 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 `done button` that hides the expanded interface.

    Returns:
      Current pickListPlacement value. Default value is null

  - ### setPickListPlacement

    public SelectItem 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 accommodate 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 `done button` that hides the expanded interface.

    Parameters:
      `pickListPlacement` - New pickListPlacement value. Default value is null
    Returns:
      `SelectItem` 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 accommodate 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 `done button` that hides the expanded interface.

    Returns:
      Current pickListPlacement value. Default value is null

  - ### setPickListPlacement

    public SelectItem setPickListPlacement(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 accommodate 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 `done button` that hides the expanded interface.

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

  - ### getPickListPlacementAsString

    public 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 accommodate 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 `done button` that hides the expanded interface.

    Returns:
      Current pickListPlacement value. Default value is null

  - ### setPickTreeConstructor

    public SelectItem setPickTreeConstructor(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:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `SCClassName`

  - ### getPickTreeConstructor

    public 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 SelectItem setProgressiveLoading(Boolean progressiveLoading)
    Indicates whether or not this SelectItem will load its list of options `progressively`. This property is copied onto the underlying PickList.
    Parameters:
      `progressiveLoading` - New progressiveLoading value. Default value is null
    Returns:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `DataSource.setProgressiveLoading(java.lang.Boolean)`
      - `Progressive Loading`

  - ### getProgressiveLoading

    public Boolean getProgressiveLoading()
    Indicates whether or not this SelectItem will load its list of options `progressively`. This property is copied onto the underlying PickList.
    Returns:
      Current progressiveLoading value. Default value is null
    See Also:
      - `DataSource.getProgressiveLoading()`
      - `Progressive Loading`

  - ### setRootNodeId

    public SelectItem setRootNodeId(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:
      `SelectItem` instance, for chaining setter calls

  - ### getRootNodeId

    public 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 SelectItem setRootNodeId(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:
      `SelectItem` instance, for chaining setter calls

  - ### getRootNodeIdAsInt

    public 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 SelectItem setSaveOnEnter(Boolean saveOnEnter)
    Select 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 `FormItem`
    Parameters:
      `saveOnEnter` - New saveOnEnter value. Default value is true
    Returns:
      `SelectItem` instance, for chaining setter calls

  - ### getSaveOnEnter

    public Boolean getSaveOnEnter()
    Select 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 `FormItem`
    Returns:
      Current saveOnEnter value. Default value is true

  - ### setSeparateSpecialValues

    public SelectItem setSeparateSpecialValues(Boolean separateSpecialValues)
    If true, `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:
      `SelectItem` instance, for chaining setter calls

  - ### getSeparateSpecialValues

    public Boolean getSeparateSpecialValues()
    If true, `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

  - ### setShowFocused

    public SelectItem setShowFocused(Boolean showFocused)
    When this item receives focus, should it be re-styled to indicate it has focus?

    See `FormItemStyling` for more details on formItem styling.

    Note : This is an advanced setting

    Overrides:
      `setShowFocused` in class `FormItem`
    Parameters:
      `showFocused` - New showFocused value. Default value is true, [IRWA]
    Returns:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `FormItem.setCellStyle(java.lang.String)`
      - `FormItem Styling`

  - ### getShowFocused

    public Boolean getShowFocused()
    When this item receives focus, should it be re-styled to indicate it has focus?

    See `FormItemStyling` for more details on formItem styling.

    Overrides:
      `getShowFocused` in class `FormItem`
    Returns:
      Current showFocused value. Default value is true, [IRWA]
    See Also:
      - `FormItem.getCellStyle()`
      - `FormItem Styling`

  - ### setShowHintInField

    public SelectItem setShowHintInField(Boolean showHintInField)
    If showing a hint for this form item, should it be shown within the field?

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

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

  - ### getShowHintInField

    public Boolean getShowHintInField()
    If showing a hint for this form item, should it be shown within the field?

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

    Returns:
      Current showHintInField value. Default value is null
    See Also:
      - `FormItem.getHint()`
      - `Appearance overview and related methods`

  - ### setShowOptionsFromDataSource

    public SelectItem setShowOptionsFromDataSource(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:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `DataBinding`

  - ### getShowOptionsFromDataSource

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

  - ### setShowOver

    public SelectItem setShowOver(boolean showOver)
    When the user rolls over this item, should it be re-styled to indicate it has focus?

    By default this property is true for SelectItems, and `updateTextBoxOnOver` and `updateControlOnOver` are set to false. This means the picker icon will show over styling when the user rolls over the control table.
    These defaults may be overridden by different Smart GWT skins.

    See `FormItemStyling` for more details on formItem styling.

    Note : This is an advanced setting

    Overrides:
      `setShowOver` in class `FormItem`
    Parameters:
      `showOver` - New showOver value. Default value is true
    Returns:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `FormItem Styling`

  - ### getShowOver

    public boolean getShowOver()
    When the user rolls over this item, should it be re-styled to indicate it has focus?

    By default this property is true for SelectItems, and `updateTextBoxOnOver` and `updateControlOnOver` are set to false. This means the picker icon will show over styling when the user rolls over the control table.
    These defaults may be overridden by different Smart GWT skins.

    See `FormItemStyling` for more details on formItem styling.

    Overrides:
      `getShowOver` in class `FormItem`
    Returns:
      Current showOver value. Default value is true
    See Also:
      - `FormItem Styling`

  - ### setShowPickerIcon

    public SelectItem setShowPickerIcon(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:
      `SelectItem` instance, for chaining setter calls

  - ### getShowPickerIcon

    public 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

  - ### setSingleClickFolderToggle

    public SelectItem 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:
      `SelectItem` 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 SelectItem setSortField(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:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - Sort Example

  - ### getSortField

    public 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 SelectItem setSortField(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:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - Sort Example

  - ### getSortFieldAsStringArray

    public 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 SelectItem setSortField(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:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - Sort Example

  - ### getSortFieldAsInt

    public 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

  - ### setSpecialValues

    public SelectItem setSpecialValues(Map specialValues)
    A set of "special" values such as "All", "None" or "Invalid" that do not appear in the normal `com.smartgwt.client.types.ValueMap` or in the data returned by the `optionDataSource`.

    Like other uses of `com.smartgwt.client.types.ValueMap`, either a list of values or a mapping from stored to display value can be provided.

    These values can either be shown at the top of the list of values (in the order specified), or can be shown in a separate, non-scrolling region - the setting `separateSpecialValues` controls this. Note that data paging can only be used if `separateSpecialValues` is enabled.

    If `specialValues` are configured, `allowEmptyValue` is ignored - an empty value, if desired, must be included in the `specialValues`. To provide a `specialValue` which clears the value of the field, use the special constant emptyStoredValue.

    `specialValues` can also be used to take a value that does appear in the normal data and redundantly display it at the top of the list to make it more accessible. Note that in this case it is expected that the special value appears both at the top of the list and in it's normal position in the list, so this works best with `separateSpecialValues` mode enabled.

    Also, if an `optionDataSource` is used, `specialValues` that appear in the normal dataset will be updated by automatic `cache synchronization` (if the `displayField` is updated). However when using a distinct `valueField` and `displayField`, you are required to provide `specialValues` as a map (there is no support for `fetchMissingValues` automatically fetching appropriate display values).

    Note that specialValues are not supported in conjunction with `MultiComboBoxItem`. Whereas with `selectItem.multiple:true`, specialValues will never be normal values that may be selected. So, specialValues should have options such as "Select All", "Select None" and others.

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

  - ### getSpecialValues

    public Map getSpecialValues()
    A set of "special" values such as "All", "None" or "Invalid" that do not appear in the normal `com.smartgwt.client.types.ValueMap` or in the data returned by the `optionDataSource`.

    Like other uses of `com.smartgwt.client.types.ValueMap`, either a list of values or a mapping from stored to display value can be provided.

    These values can either be shown at the top of the list of values (in the order specified), or can be shown in a separate, non-scrolling region - the setting `separateSpecialValues` controls this. Note that data paging can only be used if `separateSpecialValues` is enabled.

    If `specialValues` are configured, `allowEmptyValue` is ignored - an empty value, if desired, must be included in the `specialValues`. To provide a `specialValue` which clears the value of the field, use the special constant emptyStoredValue.

    `specialValues` can also be used to take a value that does appear in the normal data and redundantly display it at the top of the list to make it more accessible. Note that in this case it is expected that the special value appears both at the top of the list and in it's normal position in the list, so this works best with `separateSpecialValues` mode enabled.

    Also, if an `optionDataSource` is used, `specialValues` that appear in the normal dataset will be updated by automatic `cache synchronization` (if the `displayField` is updated). However when using a distinct `valueField` and `displayField`, you are required to provide `specialValues` as a map (there is no support for `fetchMissingValues` automatically fetching appropriate display values).

    Note that specialValues are not supported in conjunction with `MultiComboBoxItem`. Whereas with `selectItem.multiple:true`, specialValues will never be normal values that may be selected. So, specialValues should have options such as "Select All", "Select None" and others.

    Returns:
      Current specialValues value. Default value is null

  - ### setTextBoxStyle

    public SelectItem setTextBoxStyle(String textBoxStyle)
    Base CSS class name for a form item's text box element.

    See `FormItemStyling` for an overview of formItem styling, and the `CompoundFormItem_skinning` discussion for special skinning considerations.

    If the `textBoxStyle` is changed at runtime, `updateState()` must be called to update the visual state of this item.

    Note : This is an advanced setting

    Overrides:
      `setTextBoxStyle` in class `FormItem`
    Parameters:
      `textBoxStyle` - New textBoxStyle value. Default value is "selectItemText"
    Returns:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `FormItem.setCellStyle(java.lang.String)`
      - `FormItemBaseStyle`
      - `Appearance overview and related methods`

  - ### getTextBoxStyle

    public String getTextBoxStyle()
    Base CSS class name for a form item's text box element.

    See `FormItemStyling` for an overview of formItem styling, and the `CompoundFormItem_skinning` discussion for special skinning considerations.

    If the `textBoxStyle` is changed at runtime, `updateState()` must be called to update the visual state of this item.

    Overrides:
      `getTextBoxStyle` in class `FormItem`
    Returns:
      Current textBoxStyle value. Default value is "selectItemText"
    See Also:
      - `FormItem.getCellStyle()`
      - `FormItemBaseStyle`
      - `Appearance overview and related methods`

  - ### setTextMatchStyle

    public SelectItem 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:
      `SelectItem` 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"

  - ### setUpdateControlOnOver

    public SelectItem setUpdateControlOnOver(Boolean updateControlOnOver)
    If `FormItem.showOver` is true, setting this property to false will explicitly disable showing the "Over" state for the control table element of this item (if present).

    Note : This is an advanced setting

    Overrides:
      `setUpdateControlOnOver` in class `FormItem`
    Parameters:
      `updateControlOnOver` - New updateControlOnOver value. Default value is false
    Returns:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `setShowOver(boolean)`
      - `FormItem Styling`

  - ### getUpdateControlOnOver

    public Boolean getUpdateControlOnOver()
    If `FormItem.showOver` is true, setting this property to false will explicitly disable showing the "Over" state for the control table element of this item (if present).
    Overrides:
      `getUpdateControlOnOver` in class `FormItem`
    Returns:
      Current updateControlOnOver value. Default value is false
    See Also:
      - `getShowOver()`
      - `FormItem Styling`

  - ### setUpdateTextBoxOnOver

    public SelectItem setUpdateTextBoxOnOver(Boolean updateTextBoxOnOver)
    If `FormItem.showOver` is true, setting this property to false will explicitly disable showing the "Over" state for the TextBox element of this item.

    Note : This is an advanced setting

    Overrides:
      `setUpdateTextBoxOnOver` in class `FormItem`
    Parameters:
      `updateTextBoxOnOver` - New updateTextBoxOnOver value. Default value is false
    Returns:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `setShowOver(boolean)`
      - `FormItem Styling`

  - ### getUpdateTextBoxOnOver

    public Boolean getUpdateTextBoxOnOver()
    If `FormItem.showOver` is true, setting this property to false will explicitly disable showing the "Over" state for the TextBox element of this item.
    Overrides:
      `getUpdateTextBoxOnOver` in class `FormItem`
    Returns:
      Current updateTextBoxOnOver value. Default value is false
    See Also:
      - `getShowOver()`
      - `FormItem Styling`

  - ### setUseClientFiltering

    public SelectItem setUseClientFiltering(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:
      `SelectItem` instance, for chaining setter calls

  - ### getUseClientFiltering

    public 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 SelectItem setValueField(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:
      `SelectItem` instance, for chaining setter calls
    See Also:
      - `DataBinding`
      - List - Related Records Example

  - ### getValueField

    public 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`
      - List - Related Records Example

  - ### addDataArrivedHandler

    public 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 Object defaultDynamicValue(FormItem item, DynamicForm form, Map values)
    Expression evaluated to determine the `defaultValue` when no value is provided for this item. To default to the first option use `defaultToFirstOption` instead.
    Parameters:
      `item` - the form item itself (also available as "this")
      `form` - the managing DynamicForm instance
      `values` - the current set of values for the form as a whole
    Returns:
      dynamically calculated default value for this item

  - ### getDisplayFieldName

    public 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 foreignDisplay or displayField specification was found, and the `FormItem.valueField` for this item is hidden in the `FormItem.optionDataSource`, this method will return the title field for the `optionDataSource`.
    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`

  - ### getSelectedRecord

    public ListGridRecord getSelectedRecord()
    Get the record returned from the `optionDataSource` when `fetchMissingValues` is true, and the missing value is fetched.

    `FormItem.fetchMissingValues` kicks off the fetch when the form item is initialized with a non null value or when setValue() is called on the item. Note that this method will return null before the fetch completes, or if no record is found in the optionDataSource matching the underlying value.

    Overrides:
      `getSelectedRecord` in class `FormItem`
    Returns:
      selected record

  - ### getSelectedRecords

    public ListGridRecord[] getSelectedRecords()
    For a SelectItem with an `optionDataSource` and allowing multiple selection (`via multiple:true`), returns the list of currently selected records, or null if none are selected.
    Returns:
      the list of selected records, or null if none are selected

  - ### getValueFieldName

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

  - ### pendingStatusChanged

    public Boolean pendingStatusChanged(DynamicForm form, FormItem item, boolean pendingStatus, Object newValue, Object value)
    Notification method called when `showPending` is enabled and this `SelectItem` should either clear or show its pending visual state.

    The default behavior is that the `titleStyle` and `cellStyle` are updated to include/exclude the "Pending" suffix. In addition, a `multiple` `SelectItem` when displayed in the pending state will apply `FormItem.editPendingCSSText` to any new value in the text box and also append "Pending" to the cells' `ListGrid.baseStyle` for cells in the pickList menu corresponding to new values. Returning `false` will cancel this default behavior.

    Parameters:
      `form` - the managing `DynamicForm` instance.
      `item` - the form item itself (also available as "this").
      `pendingStatus` - `true` if the item should show its pending visual state; `false` otherwise.
      `newValue` - the current form item value.
      `value` - the value that would be restored by a call to `DynamicForm.resetValues()`.
    Returns:
      `false` to cancel the default behavior.

  - ### showPicker

    public void showPicker()
    Method to show a picker for this item. By default this method is called if the user clicks on a `pickerIcon`. May also be called programmatically.

    Overridden from the default `FormItem.showPicker()` implementation to show the PickList

    Overrides:
      `showPicker` in class `FormItem`

  - ### setDefaultProperties

    public static void setDefaultProperties(SelectItem selectItemProperties)
    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:
      `selectItemProperties` - properties that should be used as new defaults when instances of this class are created
    See Also:
      - `SGWTProperties`

  - ### getPickListFilterCriteria

    protected Criteria getPickListFilterCriteria()
    Returns a set of filter criteria to be applied to the data displayed in the pickList when it is shown.
    If this is a databound item, the criteria will be passed as criteria to DataSource.fetchData(). Otherwise an equivalent client-side filter will be performed on the data returned by PickList.getClientPickListData().
    By default returns PickList.pickListCriteria if specified, otherwise an empty set of criteria so all records will be displayed. 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(String... values)
    Set the specialValues for this item.
    Parameters:
      `values` - the special values

  - ### setSpecialValues

    public void setSpecialValues(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(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 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(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 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(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 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(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 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(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 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(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 specified for this item.

    Note : This is an advanced setting

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

  - ### getValueIconField

    public 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 specified for this item.
    Specified by:
      `getValueIconField` in interface `PickList`
    Returns:
      String

  - ### setShowAllOptions

    public SelectItem setShowAllOptions(Boolean showAllOptions)
    If true, even non-matching options will be shown, with configurable `separatorRows` in between. Not valid for `optionDataSource`.
    Specified by:
      `setShowAllOptions` in interface `PickList`
    Parameters:
      `showAllOptions` - showAllOptions Default value is null
    Returns:
      `SelectItem` instance, for chaining setter calls

  - ### getShowAllOptions

    public Boolean getShowAllOptions()
    If true, even non-matching options will be shown, with configurable `separatorRows` in between. Not valid for `optionDataSource`.
    Specified by:
      `getShowAllOptions` in interface `PickList`
    Returns:
      Boolean

  - ### setPickListCriteria

    public void setPickListCriteria(DSRequest optionFilterContext)
    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 filter operation on the dataSource to obtain the set of options for the list.

    Note : This is an advanced setting

    Parameters:
      `optionFilterContext` - optionFilterContext Default value is null

  - ### setOptionDataSource

    public SelectItem 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 `ComboBoxItem.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:
      `optionDataSource` - optionDataSource Default value is null
    Returns:
      `SelectItem` 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

  - ### setSeparatorRows

    public SelectItem setSeparatorRows(ListGridRecord[] separatorRows)
    Description copied from interface: `PickList`
    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` - separator rows
    Returns:
      `PickList` instance, for chaining setter calls

  - ### setDefaultValues

    public void setDefaultValues(String... defaultValues)
    Default values used when no value is provided for this item. Note that whenever this item's value is cleared by the user or set to `null` programmatically, it will be reverted to the `defaultValues`.
    Parameters:
      `defaultValues` - the defaultValues. Default value is null

  - ### setDefaultValues

    public void setDefaultValues(Integer... defaultValues)
    Default values used when no value is provided for this item. Note that whenever this item's value is cleared by the user or set to `null` programmatically, it will be reverted to the `defaultValues`.
    Parameters:
      `defaultValues` - the defaultValues. Default value is null

  - ### setFetchDelay

    public void setFetchDelay(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 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

  - ### getValues

    public String[] getValues()
    Returns the values of a SelectItem with multiple=true as an array of Strings.
    Returns:
      value of selection. If no values are selected, and empty array is returned

  - ### setValues

    public void setValues(String... values)
    Set the values of a SelectItem with multiple=true.
    Parameters:
      `values` - the SelectItem values

  - ### isMultiple

    public Boolean isMultiple()
    If true, multiple values may be selected.

    The SelectItem will either render as a drop-down allowing multiple selections, or a multi-row list of options similar to a small headerless `ListGrid`, based on the `MultipleAppearance` setting.

    The logical value of the formItem, as retrieved by `getValue()` and set via `setValue()`, is an Array of Strings reflecting the selected values.

    When this value is true, we disable doubleClick events by default, instead issuing two single clicks by forcibly setting `noDoubleClicks: true`. If you need to work with doubleClick events, you can disable this default behavior by explicitly setting formItem.pickListProperties.noDoubleClicks: false.

    Note: `multiple:true` SelectItems do not currently support optionDataSource binding. You can get around this by calling `DataSource.fetchData` directly and calling `dsResponse.data.getValueMap()` to obtain a valueMap.

    Returns:
      Boolean
    See Also:
      - `Appearance overview and related methods`

  - ### filterClientPickListData

    public ListGridRecord[] filterClientPickListData()
    Description copied from interface: `PickList`
    Returns the data to display in the pick list.

    The default implementation applies the criteria returned by `#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 `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()
    Description copied from interface: `PickList`
    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.

    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

  - ### 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.
    The criteria returned by this method are used to decide which options should appear in the drop-down PickList shown by this SelectItem.
    Static criteria, specified via pickListCriteria, will always be included in addition to criteria returned by this method.

  - ### 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 `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&#010 not null, this will be passed to the datasource as `RPCRequest` properties when&#010 performing the fetch operation on the dataSource to obtain a data-value to display-value&#010 mapping

    Note : This is an advanced setting

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

  - ### getValueAsString

    public String getValueAsString()
    Return the value tracked by this form item.
    Returns:
      value of this element

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

  - ### fetchData

    public void fetchData()
    Only applies to databound items (see 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 pickListCriteria.

  - ### fetchData

    public void fetchData(DSCallback callback)

  - ### fetchData

    public void fetchData(DSCallback callback, DSRequest requestProperties)
    Only applies to databound items (see 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 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.