com.smartgwt.client.widgets.form.fields

## Interface PickList

- All Known Implementing Classes:
    ComboBoxItem, PresetCriteriaItem, PresetDateRangeItem, SavedSearchItem, SelectItem, SelectOtherItem

      public interface PickList

  Interface to show a drop-down list of pickable options. Used by the `SelectItem` and `ComboBoxItem` classes.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `ListGridRecord[]` | `filterClientPickListData()` Returns the data to display in the pick list.
    `java.lang.Boolean` | `getAnimatePickList()` If true, when the pickList is shown, it will be shown via an animated reveal effect
    `int` | `getAnimationTime()` If this.animatePickList is true - this specifies the duration of the animation effect applied when showing the pickList
    `ListGridRecord[]` | `getClientPickListData()` Returns the set of data to be displayed in this item's PickList.
    `java.lang.String` | `getDisplayField()` Specifies an alternative field from which display values should be retrieved for this item. If this item is not databound (`optionDataSource` is unset), or bound to the same dataSource as the form as a whole, this is implemented by picking up the value of the specified field from the Form's values object. Otherwise this item will attempt to map its underlying value to a display value by retrieving a record from the `optionDataSource` where the `valueField` matches this item's value, and displaying the `displayField` value from that record. This essentially enables the specified `optionDataSource` to be used as a server based `ValueMap`.
    `java.lang.String` | `getDisplayFieldName()` Returns the `displayField` for this form item.
    `int` | `getEmptyPickListHeight()` Height for an empty pick list (showing the empty message), if the pick list has no records and `hideEmptyPickList` is `false`.
    `java.lang.String` | `getEmptyPickListMessage()` Empty message to display in the pickList if `hideEmptyPickList` is `false`.
    `java.lang.Integer` | `getFetchDelay()` For a ComboBox or other pickList that accepts user-entered criteria, how many millseconds to wait after the last user keystroke before fetching data from the server.
    `java.lang.Boolean` | `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.
    `java.lang.Boolean` | `getHideEmptyPickList()` If this pickList contains no options, should it be hidden? If unset, default behavior is to allow the empty pickList to show if it is databound.
    `DataSource` | `getOptionDataSource()`
    `java.lang.String` | `getPickListBaseStyle()` Base Style for pickList cells.
    `int` | `getPickListCellHeight()` Cell Height for this item's pickList.
    `Criteria` | `getPickListCriteria()` If this item has a databound pick-list (for example `optionDataSource` is set) this property can be used to provide static filter criteria when retrieving the data for the pickList.
    `int` | `getPickListHeaderHeight()` If this pick list is showing multiple fields, this property determines the height of the column headers for those fields.
    `int` | `getPickListHeight()` Maximum height to show the pick list before it starts to scroll.
    `java.lang.Integer` | `getPickListMaxWidth()` Maximum width for this item's pickList.
    `java.lang.Integer` | `getPickListWidth()` Default width to show the pickList.
    `java.lang.Boolean` | `getShowAllOptions()` If true, even non-matching options will be shown, with configurable `separatorRows` in between.
    `java.lang.Boolean` | `getShowOptionsFromDataSource()` If this item is part of a databound form, and has a specified `valueMap` by default we show the valueMap options in the pickList for the item.
    `TextMatchStyle` | `getTextMatchStyle()` When applying filter criteria to pickList data, what type of matching to use.
    `java.lang.String` | `getValueField()` If this form item maps data values to display values by retrieving the `displayField` values from an `optionDataSource`, this property denotes the the field to use as the underlying data value in records from the optionDataSource. If unset, assumed to be the `name` of this form item.
    `java.lang.String` | `getValueFieldName()` Getter method to retrieve the `valueField` for this item.
    `java.lang.String` | `getValueIconField()` For Databound formItems, this property determines which column `valueIcons` should show up in for this formItem's pickList. If unset valueIcons show up in the `displayField` column if specified, otherwise the `valueField` column. In most cases only the `displayField` or `valueField` will be visible.
    `void` | `setAnimatePickList(java.lang.Boolean animatePickList)` If true, when the pickList is shown, it will be shown via an animated reveal effect
    `void` | `setAnimationTime(int animationTime)` If this.animatePickList is true - this specifies the duration of the animation effect applied when showing the pickList
    `PickList` | `setDisplayField(java.lang.String displayField)` Specifies an alternative field from which display values should be retrieved for this item. If this item is not databound (`optionDataSource` is unset), or bound to the same dataSource as the form as a whole, this is implemented by picking up the value of the specified field from the Form's values object. Otherwise this item will attempt to map its underlying value to a display value by retrieving a record from the `optionDataSource` where the `valueField` matches this item's value, and displaying the `displayField` value from that record. This essentially enables the specified `optionDataSource` to be used as a server based `ValueMap`.
    `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`.
    `PickList` | `setEmptyPickListMessage(java.lang.String emptyPickListMessage)` Empty message to display in the pickList if `hideEmptyPickList` is `false`.
    `void` | `setFetchDelay(java.lang.Integer fetchDelay)` For a ComboBox or other pickList that accepts user-entered criteria, how many millseconds to wait after the last user keystroke before fetching data from the server.
    `PickList` | `setFilterLocally(java.lang.Boolean filterLocally)` If `filterLocally` is set for this item, and this item is showing options from a dataSource, fetch the entire set of options from the server, and use these values to map the item value to the appropriate display value.
    `void` | `setHideEmptyPickList(java.lang.Boolean hideEmptyPickList)` If this pickList contains no options, should it be hidden? If unset, default behavior is to allow the empty pickList to show if it is databound.
    `PickList` | `setOptionDataSource(DataSource dataSource)`
    `void` | `setOptionFilterContext(DSRequest dsRequestProperties)` If this item has a specified `optionDataSource`, and this property is not null, this will be passed to the datasource as `RPCRequest` properties when performing the fetch operation on the dataSource to obtain a data-value to display-value mapping
    `void` | `setPickListBaseStyle(java.lang.String pickListBaseStyle)` Base Style for pickList cells.
    `void` | `setPickListCellHeight(int pickListCellHeight)` Cell Height for this item's pickList.
    `PickList` | `setPickListCriteria(Criteria pickListCriteria)` If this item has a databound pick-list (for example `optionDataSource` is set) this property can be used to provide static filter criteria when retrieving the data for the pickList.
    `void` | `setPickListFilterCriteriaFunction(FilterCriteriaFunction filterCriteriaFunction)` Set the pick list filter criteria function / handler.
    `void` | `setPickListHeaderHeight(int pickListHeaderHeight)` If this pick list is showing multiple fields, this property determines the height of the column headers for those fields.
    `void` | `setPickListHeight(int pickListHeight)` Maximum height to show the pick list before it starts to scroll.
    `void` | `setPickListMaxWidth(java.lang.Integer pickListMaxWidth)` Maximum width for this item's pickList.
    `void` | `setPickListWidth(java.lang.Integer pickListWidth)` Default width to show the pickList.
    `PickList` | `setSeparatorRows(ListGridRecord[] separatorRows)` Array of records to show between matching and non-matching rows in the PickList.
    `PickList` | `setShowAllOptions(java.lang.Boolean showAllOptions)` If true, even non-matching options will be shown, with configurable `separatorRows` in between.
    `PickList` | `setShowOptionsFromDataSource(java.lang.Boolean showOptionsFromDataSource)` If this item is part of a databound form, and has a specified `valueMap` by default we show the valueMap options in the pickList for the item.
    `PickList` | `setTextMatchStyle(TextMatchStyle textMatchStyle)` When applying filter criteria to pickList data, what type of matching to use.
    `PickList` | `setValueField(java.lang.String valueField)` If this form item maps data values to display values by retrieving the `displayField` values from an `optionDataSource`, this property denotes the the field to use as the underlying data value in records from the optionDataSource. If unset, assumed to be the `name` of this form item.
    `void` | `setValueIconField(java.lang.String valueIconField)` For Databound formItems, this property determines which column `valueIcons` should show up in for this formItem's pickList. If unset valueIcons show up in the `displayField` column if specified, otherwise the `valueField` column. In most cases only the `displayField` or `valueField` will be visible.

- - ### Method Detail

    - #### setPickListHeight

          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
      Parameters:
        `pickListHeight` - pickListHeight Default value is 300

    - #### getPickListHeight

          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
      Returns:
        int

    - #### setEmptyPickListHeight

          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`.
      Parameters:
        `emptyPickListHeight` - emptyPickListHeight Default value is 100

    - #### getEmptyPickListHeight

          int getEmptyPickListHeight()

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

    - #### setEmptyPickListMessage

          PickList setEmptyPickListMessage(java.lang.String emptyPickListMessage)

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

      Note : This is an advanced setting

      Parameters:
        `emptyPickListMessage` - emptyPickListMessage Default value is null
      Returns:
        `PickList` instance, for chaining setter calls

    - #### getEmptyPickListMessage

          java.lang.String getEmptyPickListMessage()

      Empty message to display in the pickList if `hideEmptyPickList` is `false`.
      Returns:
        String

    - #### setHideEmptyPickList

          void setHideEmptyPickList(java.lang.Boolean hideEmptyPickList)

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

    - #### getHideEmptyPickList

          java.lang.Boolean getHideEmptyPickList()

      If this pickList contains no options, should it be hidden? If unset, default behavior is to allow the empty pickList to show if it is databound.
      Returns:
        Boolean

    - #### setPickListWidth

          void setPickListWidth(java.lang.Integer pickListWidth)

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

    - #### getPickListWidth

          java.lang.Integer getPickListWidth()

      Default width to show the pickList. If not specified, the width of this form item's element will be used instead.
      Returns:
        Integer

    - #### setPickListMaxWidth

          void setPickListMaxWidth(java.lang.Integer pickListMaxWidth)

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

    - #### getPickListMaxWidth

          java.lang.Integer getPickListMaxWidth()

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

    - #### setPickListBaseStyle

          void setPickListBaseStyle(java.lang.String pickListBaseStyle)

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

    - #### getPickListBaseStyle

          java.lang.String getPickListBaseStyle()

      Base Style for pickList cells. As with ListGrid Cells, will have 'over', 'selected' and 'disabled' appended on changes of state for the cells.
      Returns:
        String

    - #### setAnimatePickList

          void setAnimatePickList(java.lang.Boolean animatePickList)

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

      Note : This is an advanced setting

      Parameters:
        `animatePickList` - animatePickList Default value is null

    - #### getAnimatePickList

          java.lang.Boolean getAnimatePickList()

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

    - #### setAnimationTime

          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

      Parameters:
        `animationTime` - animationTime Default value is 200

    - #### getAnimationTime

          int getAnimationTime()

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

    - #### setPickListHeaderHeight

          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.
      Parameters:
        `pickListHeaderHeight` - pickListHeaderHeight Default value is 22

    - #### getPickListHeaderHeight

          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.
      Returns:
        int

    - #### setPickListCellHeight

          void setPickListCellHeight(int pickListCellHeight)

      Cell Height for this item's pickList.
      Parameters:
        `pickListCellHeight` - pickListCellHeight Default value is 16

    - #### getPickListCellHeight

          int getPickListCellHeight()

      Cell Height for this item's pickList.
      Returns:
        int

    - #### setValueField

          PickList setValueField(java.lang.String valueField)

      If this form item maps data values to display values by retrieving the `displayField` values from an `optionDataSource`, this property denotes the the field to use as the underlying data value in records from the optionDataSource.
      If unset, assumed to be the `name` of this form item.

      Note : This is an advanced setting

      Parameters:
        `valueField` - valueField Default value is null
      Returns:
        `PickList` instance, for chaining setter calls

    - #### getValueField

          java.lang.String getValueField()

      If this form item maps data values to display values by retrieving the `displayField` values from an `optionDataSource`, this property denotes the the field to use as the underlying data value in records from the optionDataSource.
      If unset, assumed to be the `name` of this form item.
      Returns:
        String

    - #### setDisplayField

          PickList setDisplayField(java.lang.String displayField)

      Specifies an alternative field from which display values should be retrieved for this item.
      If this item is not databound (`optionDataSource` is unset), or bound to the same dataSource as the form as a whole, this is implemented by picking up the value of the specified field from the Form's values object.
      Otherwise this item will attempt to map its underlying value to a display value by retrieving a record from the `optionDataSource` where the `valueField` matches this item's value, and displaying the `displayField` value from that record.
      This essentially enables the specified `optionDataSource` to be used as a server based `ValueMap`.
      Parameters:
        `displayField` - displayField Default value is null
      Returns:
        `PickList` instance, for chaining setter calls

    - #### getDisplayField

          java.lang.String getDisplayField()

      Specifies an alternative field from which display values should be retrieved for this item.
      If this item is not databound (`optionDataSource` is unset), or bound to the same dataSource as the form as a whole, this is implemented by picking up the value of the specified field from the Form's values object.
      Otherwise this item will attempt to map its underlying value to a display value by retrieving a record from the `optionDataSource` where the `valueField` matches this item's value, and displaying the `displayField` value from that record.
      This essentially enables the specified `optionDataSource` to be used as a server based `ValueMap`.
      Returns:
        String

    - #### setValueIconField

          void setValueIconField(java.lang.String valueIconField)

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

      Note : This is an advanced setting

      Parameters:
        `valueIconField` - valueIconField Default value is null

    - #### getValueIconField

          java.lang.String getValueIconField()

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

    - #### setPickListCriteria

          PickList setPickListCriteria(Criteria pickListCriteria)

      If this item has a databound pick-list (for example `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

      Parameters:
        `pickListCriteria` - pickListCriteria Default value is null
      Returns:
        `PickList` instance, for chaining setter calls

    - #### getPickListCriteria

          Criteria getPickListCriteria()

      If this item has a databound pick-list (for example `optionDataSource` is set) this property can be used to provide static filter criteria when retrieving the data for the pickList.
      Returns:
        Criteria

    - #### setShowOptionsFromDataSource

          PickList setShowOptionsFromDataSource(java.lang.Boolean showOptionsFromDataSource)

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

      Note : This is an advanced setting

      Parameters:
        `showOptionsFromDataSource` - showOptionsFromDataSource Default value is null
      Returns:
        `PickList` instance, for chaining setter calls

    - #### getShowOptionsFromDataSource

          java.lang.Boolean getShowOptionsFromDataSource()

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

    - #### setFilterLocally

          PickList setFilterLocally(java.lang.Boolean filterLocally)

      If `filterLocally` is set for this item, and this item is showing options from a dataSource, fetch the entire set of options from the server, and use these values to map the item value to the appropriate display value. Also use `"local"` type filtering on drop down list of options.
      This means data will only be fetched once from the server, and then filtered on the client.

      Note : This is an advanced setting

      Parameters:
        `filterLocally` - filterLocally Default value is false
      Returns:
        `PickList` instance, for chaining setter calls

    - #### getFilterLocally

          java.lang.Boolean getFilterLocally()

      If `filterLocally` is set for this item, and this item is showing options from a dataSource, fetch the entire set of options from the server, and use these values to map the item value to the appropriate display value. Also use `"local"` type filtering on drop down list of options.
      This means data will only be fetched once from the server, and then filtered on the client.
      Returns:
        Boolean

    - #### setTextMatchStyle

          PickList setTextMatchStyle(TextMatchStyle textMatchStyle)

      When applying filter criteria to pickList data, what type of matching to use. Legal values are "substring" (value contains user input) or "startsWith" (value starts with user input. Both matches are case insensitive.

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

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

      Parameters:
        `textMatchStyle` - textMatchStyle Default value is "startsWith"
      Returns:
        `PickList` instance, for chaining setter calls

    - #### getTextMatchStyle

          TextMatchStyle getTextMatchStyle()

      When applying filter criteria to pickList data, what type of matching to use. Legal values are "substring" (value contains user input) or "startsWith" (value starts with user input. Both matches are case insensitive.

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

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

      Returns:
        Boolean

    - #### setShowAllOptions

          PickList setShowAllOptions(java.lang.Boolean showAllOptions)

      If true, even non-matching options will be shown, with configurable `separatorRows` in between. Not valid for `optionDataSource`.
      Parameters:
        `showAllOptions` - showAllOptions Default value is null
      Returns:
        `PickList` instance, for chaining setter calls

    - #### getShowAllOptions

          java.lang.Boolean getShowAllOptions()

      If true, even non-matching options will be shown, with configurable `separatorRows` in between. Not valid for `optionDataSource`.
      Returns:
        Boolean

    - #### getValueFieldName

          java.lang.String getValueFieldName()

      Getter method to retrieve the `valueField` for this item. If unset, default behavior will return the `name` of this field.
      Returns:
        fieldName to use a "value field" in records from this items `optionDataSource`

    - #### getDisplayFieldName

          java.lang.String getDisplayFieldName()

      Returns the `displayField` for this form item. If unset, and `optionDataSource` is explicitly specified, this method will return the title field for the `optionDataSource`
      Returns:
        display field name, or null

    - #### setFetchDelay

          void setFetchDelay(java.lang.Integer fetchDelay)

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

    - #### getFetchDelay

          java.lang.Integer getFetchDelay()

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

    - #### setPickListFilterCriteriaFunction

          void setPickListFilterCriteriaFunction(FilterCriteriaFunction filterCriteriaFunction)

      Set the pick list filter criteria function / handler.
      Parameters:
        `filterCriteriaFunction` - the filter criteria function

    - #### filterClientPickListData

          ListGridRecord[] filterClientPickListData()

      Returns the data to display in the pick list.

      The default implementation applies the criteria returned by `#getPickListFilterCriteria` to the data returned by `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`.

      Returns:
        array of record objects to display in the pickList

    - #### getClientPickListData

          ListGridRecord[] getClientPickListData()

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

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

      Note that for PickLists that filter data based on user input `'ComboBox')`, this method should return the data before filtering.

      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

    - #### setSeparatorRows

          PickList setSeparatorRows(ListGridRecord[] separatorRows)

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

      Not valid for `'databound pickLists'`.

      Parameters:
        `separatorRows` - separator rows
      Returns:
        `PickList` instance, for chaining setter calls

    - #### getOptionDataSource

          DataSource getOptionDataSource()

    - #### setOptionDataSource

          PickList setOptionDataSource(DataSource dataSource)

    - #### setOptionFilterContext

          void setOptionFilterContext(DSRequest dsRequestProperties)

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

      Note : This is an advanced setting

      Parameters:
        `dsRequestProperties` - optionFilterContext Default value is null