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