Package 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

  Modifier and Type
  Method
  Description
  `ListGridRecord[]`
  `filterClientPickListData()`
  Returns the data to display in the pick list.
  `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.
  `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`.
  `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`.
  `String`
  `getEmptyPickListMessage()`
  Empty message to display in the pickList if `hideEmptyPickList` is `false`.
  `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`
  `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.
  `DataSource`
  `getOptionDataSource()`
  `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.
  `Integer`
  `getPickListMaxWidth()`
  Maximum width for this item's pickList.
  `Integer`
  `getPickListWidth()`
  Default width to show the pickList.
  `Boolean`
  `getShowAllOptions()`
  If true, even non-matching options will be shown, with configurable `separatorRows` in between.
  `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.
  `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.
  `String`
  `getValueFieldName()`
  Getter method to retrieve the `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.
  `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
  `PickList`
  `setDisplayField(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(String emptyPickListMessage)`
  Empty message to display in the pickList if `hideEmptyPickList` is `false`.
  `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.
  `PickList`
  `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.
  `PickList`
  `setOptionDataSource(DataSource dataSource)`
  `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
  `void`
  `setPickListBaseStyle(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(Integer pickListMaxWidth)`
  Maximum width for this item's pickList.
  `void`
  `setPickListWidth(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(Boolean showAllOptions)`
  If true, even non-matching options will be shown, with configurable `separatorRows` in between.
  `PickList`
  `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.
  `PickList`
  `setTextMatchStyle(TextMatchStyle textMatchStyle)`
  When applying filter criteria to pickList data, what type of matching to use.
  `PickList`
  `setValueField(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(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 Details

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

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

  - ### setHideEmptyPickList

    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.
    Parameters:
      `hideEmptyPickList` - hideEmptyPickList Default value is null

  - ### getHideEmptyPickList

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

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

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

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

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

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

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

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

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

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

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

  - ### getValueFieldName

    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

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

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

    Parameters:
      `dsRequestProperties` - optionFilterContext Default value is null