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