com.smartgwt.client.widgets.form.fields
Class SelectItem

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

All Implemented Interfaces:

HasHandlers, HasBlurHandlers, HasChangedHandlers, HasChangeHandlers, HasClickHandlers, HasDataArrivedHandlers, HasDoubleClickHandlers, HasEditorEnterHandlers, HasEditorExitHandlers, HasFocusHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasPickerIconClickHandlers, HasTitleClickHandlers, HasTitleDoubleClickHandlers, HasTitleHoverHandlers, PickList

Direct Known Subclasses:

SelectOtherItem

public class SelectItem
extends FormItem
implements PickList, HasDataArrivedHandlers

FormItem that allows picking between several mutually exclusive options via a select list.

Options may be derived from a dataSource or a valueMap.

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

See Also:

com.smartgwt.client.widgets.form.fields.FormItem#getValueMap

Field Summary

Fields inherited from class com.smartgwt.client.core.JsObject

jsObj

Constructor Summary

SelectItem()

SelectItem(JavaScriptObject jsObj)

SelectItem(String name)

SelectItem(String name, String title)

Method Summary

HandlerRegistration	addDataArrivedHandler(DataArrivedHandler handler) Add a dataArrived handler.
void	defaultDynamicValue() Expression evaluated to determine the defaultValue when no value is provided for this item.
void	fetchData() Only applies to databound items (see optionDataSource). Performs a fetch type operation on this item's DataSource to retrieve the set of valid options for the item, based on the current pickListCriteria.
void	fetchData(DSCallback callback) Only applies to databound items (see optionDataSource). Performs a fetch type operation on this item's DataSource to retrieve the set of valid options for the item, based on the current pickListCriteria.
void	fetchData(DSCallback callback, DSRequest requestProperties) Only applies to databound items (see optionDataSource). Performs a fetch type operation on this item's DataSource to retrieve the set of valid options for the item, based on the current pickListCriteria.
ListGridRecord[]	filterClientPickListData() Returns the data to display in the pick list.
Boolean	getAddUnknownValues() If we're setting the value of a select item and the value isn't a legal value in the valueMap, whether we should allow the value (creating a new option for it) or reject it.
Boolean	getAllowEmptyValue() If set to true, always show an empty option in this item's pickList, allowing the user to clear the value (even if there is no empty entry in the valueMap for the item).
Boolean	getAnimatePickList() If true, when the pickList is shown, it will be shown via an animated reveal effect
int	getAnimationTime() If this.animatePickList is true - this specifies the duration of the animation effect applied when showing the pickList
Boolean	getAutoFetchData() If this select item retrieves its options from a dataSource, should options be fetched from the server when the item is first drawn, or should this fetch be delayed until the user opens the pickList.
Boolean	getCachePickListResults() For databound pickLists (see optionDataSource), by default Smart GWT will cache and re-use datasets shown by pickLists in an LRU (least recently used) caching pattern.
ListGridRecord[]	getClientPickListData() Returns the set of data to be displayed in this item's PickList.
String	getControlStyle() Base CSS class name for a form item's control box (surrounds text box and picker).
Boolean	getDefaultToFirstOption() Select the first option as the default value for this SelectItem.
Boolean	getDefaultValue() Static default value for this SelectItem.
String	getDisplayField() Specifies an alternative field from which display values should be retrieved for this item.
String	getDisplayFieldName() Returns the displayField for this 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.
Boolean	getEscapeHTML() By default HTML values in a selectItem will be interpreted by the browser.
Integer	getFetchDelay() For a ComboBox or other pickList that accepts user-entered criteria, how many millseconds to wait after the last user keystroke before fetching data from the server.
Boolean	getFetchDisplayedFieldsOnly() If this item has a specified optionDataSource and this property is true, the list of fields used by this pickList will be passed to the datasource as outputs.
Boolean	getFilterLocally() If filterLocally is set for this item, and this item is showing options from a dataSource, fetch the entire set of options from the server, and use these values to map the item value to the appropriate display value.
int	getHeight() Default height for select items is 19px.
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.
Boolean	getMultiple() If true, multiple values may be selected.
MultipleAppearance	getMultipleAppearance() How should items with multiple set to 'true' be displayed?
DataSource	getOptionDataSource()
String	getOptionOperationId() If this item has a specified optionDataSource, this attribute may be set to specify an explicit operationId when performing a fetch against the option dataSource to pick up display value mapping.
static SelectItem	getOrCreateRef(JavaScriptObject jsObj)
Integer	getPickerIconHeight() If showPickerIcon is true for this item, this property governs the size of the picker icon.
String	getPickerIconSrc() If showPickerIcon is true for this item, this property governs the src of the picker icon image to be displayed.
String	getPickerIconStyle() Base CSS class name for a form item's picker icon cell.
Integer	getPickerIconWidth() If showPickerIcon is true for this item, this property governs the size of the picker icon.
String	getPickListBaseStyle() Base Style for pickList cells.
Criteria	getPickListCriteria() If this item has a databound pickList (for example optionDataSource is set), this property can be used to provide static filter criteria when retrieving the data for the pickList.
protected Criteria	getPickListFilterCriteria() Returns a set of filter criteria to be applied to the data displayed in the pickList when it is shown.
int	getPickListHeaderHeight() If this pick list is showing multiple fields, this property determines the height of the column headers for those fields.
int	getPickListHeight() Maximum height to show the pick list before it starts to scroll.
Integer	getPickListWidth() Default width to show the pickList.
Boolean	getProgressiveLoading() Indicates whether or not this SelectItem will load its list of options progressively.
Boolean	getSaveOnEnter() Select items will submit their containing form on enter keypress if saveOnEnter is true.
ListGridRecord	getSelectedRecord() Returns the entire record object associated with the current value for this item (or null if no matching record exists in the PickList data).
ListGridRecord[]	getSelectedRecords() For a SelectItem with an setOptionDataSource(com.smartgwt.client.data.DataSource) optionDataSource} and allowing multiple selection multiple :true, returns the list of currently selected records, or null if none are selected.
Boolean	getShowAllOptions() If true, even non-matching options will be shown, with configurable separatorRows in between.
Boolean	getShowFocused() When this item receives focus, should it be re-styled to indicate it has focus?
Boolean	getShowHintInField() If showing a hint for this form item, should it be shown within the field?
Boolean	getShowOptionsFromDataSource() If this item is part of a databound form, and has a specified valueMap, by default we show the valueMap options in the pickList for the item.
Boolean	getShowOver() When the user rolls over the select item, should the pickButton display it's Over state?
Boolean	getShowPickerIcon() Should we show a special 'picker' icon for this form item.
String	getSortField() Specifies the field by which this item should be initially sorted.
Integer	getSortFieldAsInt() Specifies the field by which this item should be initially sorted.
String	getTextBoxStyle() Base CSS class name for a form item's text box element.
TextMatchStyle	getTextMatchStyle() When applying filter criteria to pickList data, what type of matching to use.
String	getValueAsString() Return the value tracked by this form item.
String	getValueField() If this form item maps data values to display values by retrieving the 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.
String[]	getValues() Returns the values of a SelectItem with multiple=true as an array of Strings.
Boolean	isMultiple() If true, multiple values may be selected.
void	setAddUnknownValues(Boolean addUnknownValues) If we're setting the value of a select item and the value isn't a legal value in the valueMap, whether we should allow the value (creating a new option for it) or reject it.
void	setAllowEmptyValue(Boolean allowEmptyValue) If set to true, always show an empty option in this item's pickList, allowing the user to clear the value (even if there is no empty entry in the valueMap for the item).
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
void	setAutoFetchData(Boolean autoFetchData) If this select item retrieves its options from a dataSource, should options be fetched from the server when the item is first drawn, or should this fetch be delayed until the user opens the pickList.
void	setCachePickListResults(Boolean cachePickListResults) For databound pickLists (see optionDataSource), by default Smart GWT will cache and re-use datasets shown by pickLists in an LRU (least recently used) caching pattern.
void	setControlStyle(String controlStyle) Base CSS class name for a form item's control box (surrounds text box and picker).
void	setDefaultToFirstOption(Boolean defaultToFirstOption) Select the first option as the default value for this SelectItem.
void	setDefaultValue(Boolean defaultValue) Static default value for this SelectItem.
void	setDefaultValues(Integer... defaultValues) Default values used when no value is provided for this item.
void	setDefaultValues(String... defaultValues) Default values used when no value is provided for this item.
void	setDisplayField(String displayField) Specifies an alternative field from which display values should be retrieved for this item.
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.
void	setEmptyPickListMessage(String emptyPickListMessage) Empty message to display in the pickList if hideEmptyPickList is false.
void	setEscapeHTML(Boolean escapeHTML) By default HTML values in a selectItem will be interpreted by the browser.
void	setFetchDelay(Integer fetchDelay) For a ComboBox or other pickList that accepts user-entered criteria, how many millseconds to wait after the last user keystroke before fetching data from the server.
void	setFetchDisplayedFieldsOnly(Boolean fetchDisplayedFieldsOnly) If this item has a specified optionDataSource and this property is true, the list of fields used by this pickList will be passed to the datasource as outputs.
void	setFields(FormItemIcon pickerIconProperties)
void	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	setHeight(int height) Default height for select items is 19px.
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.
void	setJavaScriptObject(JavaScriptObject jsObj)
void	setMultiple(Boolean multiple) If true, multiple values may be selected.
void	setMultipleAppearance(MultipleAppearance multipleAppearance) How should items with multiple set to 'true' be displayed?
void	setOptionDataSource(DataSource dataSource) If set, this FormItem will derive data to show in the PickList by fetching records from the specified optionDataSource.
void	setOptionFilterContext(DSRequest dsRequestProperties) If this item has a specified optionDataSource, and this property is 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	setOptionOperationId(String optionOperationId) If this item has a specified optionDataSource, this attribute may be set to specify an explicit operationId when performing a fetch against the option dataSource to pick up display value mapping.
void	setPickerIconHeight(Integer pickerIconHeight) If showPickerIcon is true for this item, this property governs the size of the picker icon.
void	setPickerIconSrc(String pickerIconSrc) If showPickerIcon is true for this item, this property governs the src of the picker icon image to be displayed.
void	setPickerIconStyle(String pickerIconStyle) Base CSS class name for a form item's picker icon cell.
void	setPickerIconWidth(Integer pickerIconWidth) If showPickerIcon is true for this item, this property governs the size of the picker icon.
void	setPickListBaseStyle(String pickListBaseStyle) Base Style for pickList cells.
void	setPickListCriteria(Criteria pickListCriteria) If this item has a databound pickList (for example optionDataSource is set), this property can be used to provide static filter criteria when retrieving the data for the pickList.
void	setPickListCriteria(DSRequest optionFilterContext) If this item has a specified optionDataSource, and this property is not null, this will be passed to the datasource as RPCRequest properties when performing the filter operation on the dataSource to obtain the set of options for the list.
void	setPickListFields(ListGridField... pickListFields) This property allows the developer to specify which field[s] will be displayed in the drop down list of options.
void	setPickListFilterCriteriaFunction(FilterCriteriaFunction filterCriteriaFunction) Deprecated. in favor of setPickListFilterCriteriaFunction(FormItemCriteriaFunction)
void	setPickListFilterCriteriaFunction(FormItemCriteriaFunction filterCriteriaFunction) Set up a method to return filter criteria for options displayed for this item.
void	setPickListHeaderHeight(int pickListHeaderHeight) If this pick list is showing multiple fields, this property determines the height of the column headers for those fields.
void	setPickListHeight(int pickListHeight) Maximum height to show the pick list before it starts to scroll.
void	setPickListProperties(ListGrid pickListProperties) Set the properties to be applied to the pickList created for this Form Item.
void	setPickListSort(SortSpecifier[] sortSpecifiers) This method sorts the pickList on one or more fields, creating the underlying JS object if needed.
void	setPickListWidth(Integer pickListWidth) Default width to show the pickList.
void	setProgressiveLoading(Boolean progressiveLoading) Indicates whether or not this SelectItem will load its list of options progressively.
void	setSaveOnEnter(Boolean saveOnEnter) Select items will submit their containing form on enter keypress if saveOnEnter is true.
void	setSeparatorRows(ListGridRecord[] separatorRows) Array of records to show between matching and non-matching rows in the PickList.
void	setShowAllOptions(Boolean showAllOptions) If true, even non-matching options will be shown, with configurable separatorRows in between.
void	setShowFocused(Boolean showFocused) When this item receives focus, should it be re-styled to indicate it has focus?
void	setShowHintInField(Boolean showHintInField) If showing a hint for this form item, should it be shown within the field?
void	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.
void	setShowOver(Boolean showOver) When the user rolls over the select item, should the pickButton display it's Over state?
void	setShowPickerIcon(Boolean showPickerIcon) Should we show a special 'picker' icon for this form item.
void	setSortField(Integer sortField) Specifies the field by which this item should be initially sorted.
void	setSortField(String sortField) Specifies the field by which this item should be initially sorted.
void	setTextBoxStyle(String textBoxStyle) Base CSS class name for a form item's text box element.
void	setTextMatchStyle(TextMatchStyle textMatchStyle) When applying filter criteria to pickList data, what type of matching to use.
void	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.
void	setValues(String... values) Set the values of a SelectItem with multiple=true.
void	showPicker() Method to show a picker for this item.

Methods inherited from class com.smartgwt.client.widgets.form.fields.FormItem

_getValue, addBlurHandler, addChangedHandler, addChangeHandler, addClickHandler, addDoubleClickHandler, addEditorEnterHandler, addEditorExitHandler, addFocusHandler, addIconClickHandler, addIconKeyPressHandler, addItemHoverHandler, addKeyDownHandler, addKeyPressHandler, addKeyUpHandler, addPickerIconClickHandler, addTitleClickHandler, addTitleDoubleClickHandler, addTitleHoverHandler, blurItem, canEditCriterion, clearValue, convertToFormItemArray, disable, enable, focusInItem, getAccessKey, getAlign, getAllowExpressions, getAlwaysFetchMissingValues, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsString, getBrowserSpellCheck, getCanEdit, getCanFocus, getCellHeight, getCellStyle, getClassName, getConfig, getContainerWidget, getCriteriaField, getCriterion, getCriterion, getDataPath, getDateFormatter, getDecimalPad, getDecimalPrecision, getDefaultIconSrc, getDisabled, getDisableIconsOnReadOnly, getDisplayValue, getDisplayValue, getEditorTypeConfig, getEditPendingCSSText, getEmptyDisplayValue, getEmptyValueIcon, getEndRow, getErrorIconHeight, getErrorIconSrc, getErrorIconWidth, getErrorMessageWidth, getFetchMissingValues, getFieldName, getForm, getFullDataPath, getGlobalTabIndex, getHint, getHintStyle, getHoverAlign, getHoverDelay, getHoverHeight, getHoverOpacity, getHoverStyle, getHoverVAlign, getHoverWidth, getIcon, getIconHeight, getIconPageRect, getIconPrompt, getIconRect, getIconVAlign, getIconWidth, getImageURLPrefix, getImageURLSuffix, getImplicitSave, getImplicitSaveOnBlur, getInputFormat, getLeft, getLocateItemBy, getMultipleValueSeparator, getName, getOperator, getOptionCriteria, getOptionFilterContext, getPageLeft, getPageRect, getPageTop, getPickerIconName, getPickerIconPrompt, getPrintTextBoxStyle, getPrintTitleStyle, getPrompt, getRect, getRedrawOnChange, getRejectInvalidValueOnChange, getRequired, getRequiredMessage, getRowSpan, getSelectOnFocus, getShouldSaveValue, getShowDisabled, getShowErrorIcon, getShowErrorStyle, getShowErrorText, getShowFocusedIcons, getShowFocusedPickerIcon, getShowHint, getShowIcons, getShowOverIcons, getShowTitle, getShowValueIconOnly, getStartRow, getStopOnError, getSuppressValueIcon, getSynchronousValidation, getTabIndex, getTextAlign, getTimeFormatter, getTitle, getTitleAlign, getTitleColSpan, getTitleOrientation, getTitleStyle, getTitleVAlign, getTooltip, getTop, getType, getValidateOnChange, getValidateOnExit, getValidOperators, getVAlign, getValue, getValueIconHeight, getValueIconLeftPadding, getValueIconRightPadding, getValueIconSize, getValueIconWidth, getVisible, getVisibleHeight, getVisibleWidth, getWidth, getWrapTitle, hasAdvancedCriteria, hide, hideIcon, invalidateDisplayValueCache, isCreated, isDisabled, isDrawn, isVisible, redraw, setAccessKey, setAlign, setAllowExpressions, setAlwaysFetchMissingValues, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setBrowserSpellCheck, setCanEdit, setCanEditCriterionPredicate, setCanFocus, setCellHeight, setCellStyle, setColSpan, setColSpan, setCriteriaField, setCriterion, setCriterionGetter, setCriterionSetter, setDataPath, setDateFormatter, setDecimalPad, setDecimalPrecision, setDefaultIconSrc, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDisabled, setDisableIconsOnReadOnly, setDisplayFormat, setDisplayFormat, setEditorType, setEditorValueFormatter, setEditorValueParser, setEditPendingCSSText, setEmptyDisplayValue, setEmptyValueIcon, setEndRow, setErrorFormatter, setErrorIconHeight, setErrorIconSrc, setErrorIconWidth, setErrorMessageWidth, setErrorOrientation, setFetchMissingValues, setGlobalTabIndex, setHeight, setHint, setHintStyle, setHoverAlign, setHoverDelay, setHoverHeight, setHoverOpacity, setHoverStyle, setHoverVAlign, setHoverWidth, setIconHeight, setIconPrompt, setIcons, setIconVAlign, setIconWidth, setImageURLPrefix, setImageURLSuffix, setImplicitSave, setImplicitSaveOnBlur, setInitHandler, setInputFormat, setInputTransformer, setItemHoverFormatter, setItemTitleHoverFormatter, setLeft, setLocateItemBy, setMultipleValueSeparator, setName, setOperator, setOptionCriteria, setOptionFilterContext, setPickerIconName, setPickerIconPrompt, setPrintTextBoxStyle, setPrintTitleStyle, setPrompt, setProperty, setProperty, setProperty, setProperty, setProperty, setRedrawOnChange, setRedrawOnChange, setRejectInvalidValueOnChange, setRequired, setRequiredMessage, setRowSpan, setSelectOnFocus, setShouldSaveValue, setShowDisabled, setShowErrorIcon, setShowErrorStyle, setShowErrorText, setShowFocusedIcons, setShowFocusedPickerIcon, setShowHint, setShowIcons, setShowIfCondition, setShowOverIcons, setShowTitle, setShowValueIconOnly, setStartRow, setStopOnError, setSuppressValueIcon, setSynchronousValidation, setTabIndex, setTextAlign, setTimeFormatter, setTitle, setTitleAlign, setTitleColSpan, setTitleOrientation, setTitleStyle, setTitleVAlign, setTooltip, setTop, setType, setValidateOnChange, setValidateOnExit, setValidators, setValidOperators, setVAlign, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValueFormatter, setValueIconHeight, setValueIconLeftPadding, setValueIconMapper, setValueIconRightPadding, setValueIcons, setValueIconSize, setValueIconWidth, setValueMap, setValueMap, setVisible, setWidth, setWidth, setWrapTitle, shouldFetchMissingValue, shouldSaveOnEnter, show, showIcon, stopHover, updateState, validate

Methods inherited from class com.smartgwt.client.core.RefDataClass

getRef, getRef

Methods inherited from class com.smartgwt.client.core.DataClass

doAddHandler, fireEvent, getAttributeAsDoubleArray, getAttributeAsIntArray, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsStringArray, getAttributes, getHandlerCount, getJsObj, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute

Methods inherited from class com.smartgwt.client.core.JsObject

setJsObj

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.google.gwt.event.shared.HasHandlers

fireEvent

Constructor Detail

SelectItem

public SelectItem()

SelectItem

public SelectItem(JavaScriptObject jsObj)

SelectItem

public SelectItem(String name)

SelectItem

public SelectItem(String name,
                  String title)

Method Detail

getOrCreateRef

public static SelectItem getOrCreateRef(JavaScriptObject jsObj)

setJavaScriptObject

public void setJavaScriptObject(JavaScriptObject jsObj)

Overrides:

setJavaScriptObject in class FormItem

setAddUnknownValues

public void setAddUnknownValues(Boolean addUnknownValues)

If we're setting the value of a select item and the value isn't a legal value in the valueMap, whether we should allow the value (creating a new option for it) or reject it.

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

Note : This is an advanced setting

Parameters:

addUnknownValues - addUnknownValues Default value is true

See Also:

Dependent Selects Example

getAddUnknownValues

public Boolean getAddUnknownValues()

If we're setting the value of a select item and the value isn't a legal value in the valueMap, whether we should allow the value (creating a new option for it) or reject it.

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

Returns:

Boolean

See Also:

Dependent Selects Example

setAllowEmptyValue

public void setAllowEmptyValue(Boolean allowEmptyValue)

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

The empty value will be displayed with the emptyDisplayValue.

With a databound selectItem, enabling allowEmptyValue disables data paging - all data matching the current criteria will be requested.

Parameters:

allowEmptyValue - allowEmptyValue Default value is false

getAllowEmptyValue

public Boolean getAllowEmptyValue()

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

The empty value will be displayed with the emptyDisplayValue.

With a databound selectItem, enabling allowEmptyValue disables data paging - all data matching the current criteria will be requested.

Returns:

Boolean

setAutoFetchData

public void setAutoFetchData(Boolean autoFetchData)

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

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

Note : This is an advanced setting

Parameters:

autoFetchData - autoFetchData Default value is true

getAutoFetchData

public Boolean getAutoFetchData()

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

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

Returns:

Boolean

setCachePickListResults

public void setCachePickListResults(Boolean cachePickListResults)

For databound pickLists (see optionDataSource), by default Smart GWT will cache and re-use datasets shown by pickLists in an LRU (least recently used) caching pattern.

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

Parameters:

cachePickListResults - cachePickListResults Default value is true

getCachePickListResults

public Boolean getCachePickListResults()

For databound pickLists (see optionDataSource), by default Smart GWT will cache and re-use datasets shown by pickLists in an LRU (least recently used) caching pattern.

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

Returns:

Boolean

setControlStyle

public void setControlStyle(String controlStyle)

Base CSS class name for a form item's control box (surrounds text box and picker).

NOTE: See the CompoundFormItem_skinning discussion for special skinning considerations.

Parameters:

controlStyle - . See FormItemBaseStyle. Default value is "selectItemControl", [IRA]

See Also:

FormItem.setCellStyle(java.lang.String), Appearance overview and related methods

getControlStyle

public String getControlStyle()

Base CSS class name for a form item's control box (surrounds text box and picker).

NOTE: See the CompoundFormItem_skinning discussion for special skinning considerations.

Returns:

. See FormItemBaseStyle

See Also:

FormItem.getCellStyle(), Appearance overview and related methods

setDefaultToFirstOption

public void setDefaultToFirstOption(Boolean defaultToFirstOption)

Select the first option as the default value for this SelectItem.

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

If enabled, this setting overrides defaultValue and SelectItem.defaultDynamicValue.

Parameters:

defaultToFirstOption - defaultToFirstOption Default value is false

getDefaultToFirstOption

public Boolean getDefaultToFirstOption()

Select the first option as the default value for this SelectItem.

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

If enabled, this setting overrides defaultValue and SelectItem.defaultDynamicValue.

Returns:

Boolean

setDefaultValue

public void setDefaultValue(Boolean defaultValue)

Static default value for this SelectItem. To default to the first option use defaultToFirstOption instead.

Overrides:

setDefaultValue in class FormItem

Parameters:

defaultValue - defaultValue Default value is null

getDefaultValue

public Boolean getDefaultValue()

Static default value for this SelectItem. To default to the first option use defaultToFirstOption instead.

Returns:

Boolean

setDisplayField

public void setDisplayField(String displayField)

Specifies an alternative field from which display values should be retrieved for this item.

The display field can be either another field value in the same record or a field that must be retrieved from a related optionDataSource.

If this item is not databound (optionDataSource is unset), or bound to the same dataSource as the form as a whole, this item will call form.getValue() the form named after 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. Note that if optionDataSource is set and this value is not set, FormItem.getDisplayFieldName will return the dataSource title field by default.

This essentially enables the specified optionDataSource to be used as a server based valueMap.

Specified by:

setDisplayField in interface PickList

Overrides:

setDisplayField in class FormItem

Parameters:

displayField - . See String. Default value is null

See Also:

List - Related Records Example

getDisplayField

public String getDisplayField()

Specifies an alternative field from which display values should be retrieved for this item.

The display field can be either another field value in the same record or a field that must be retrieved from a related optionDataSource.

If this item is not databound (optionDataSource is unset), or bound to the same dataSource as the form as a whole, this item will call form.getValue() the form named after 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. Note that if optionDataSource is set and this value is not set, FormItem.getDisplayFieldName will return the dataSource title field by default.

This essentially enables the specified optionDataSource to be used as a server based valueMap.

Specified by:

getDisplayField in interface PickList

Overrides:

getDisplayField in class FormItem

Returns:

. See String

See Also:

List - Related Records Example

setEscapeHTML

public void setEscapeHTML(Boolean escapeHTML)

By default HTML values in a selectItem will be interpreted by the browser. Setting this flag to true will causes HTML characters to be escaped, meaning the raw value of the field (for example "<b>AAA</b>") is displayed to the user rather than the interpreted HTML (for example "AAA")

Parameters:

escapeHTML - escapeHTML Default value is false

See Also:

Appearance overview and related methods

getEscapeHTML

public Boolean getEscapeHTML()

By default HTML values in a selectItem will be interpreted by the browser. Setting this flag to true will causes HTML characters to be escaped, meaning the raw value of the field (for example "<b>AAA</b>") is displayed to the user rather than the interpreted HTML (for example "AAA")

Returns:

Boolean

See Also:

Appearance overview and related methods

setFetchDisplayedFieldsOnly

public void setFetchDisplayedFieldsOnly(Boolean fetchDisplayedFieldsOnly)

If this item has a specified optionDataSource and this property is true, the list of fields used by this pickList will be passed to the datasource as outputs. If the datasource supports this feature the returned fields will be limited to this list. A custom datasource will need to add code to implement field limiting.

This list of used fields consists of the values of valueField, displayField and pickListFields.

NOTE: When enabled, getSelectedRecord will only include the fetched fields.

Note : This is an advanced setting

Parameters:

fetchDisplayedFieldsOnly - fetchDisplayedFieldsOnly Default value is null

getFetchDisplayedFieldsOnly

public Boolean getFetchDisplayedFieldsOnly()

If this item has a specified optionDataSource and this property is true, the list of fields used by this pickList will be passed to the datasource as outputs. If the datasource supports this feature the returned fields will be limited to this list. A custom datasource will need to add code to implement field limiting.

This list of used fields consists of the values of valueField, displayField and pickListFields.

NOTE: When enabled, getSelectedRecord will only include the fetched fields.

Returns:

Boolean

setFilterLocally

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

Specified by:

setFilterLocally in interface PickList

Overrides:

setFilterLocally in class FormItem

Parameters:

filterLocally - filterLocally Default value is false

See Also:

FormItem.setFilterLocally(java.lang.Boolean)

getFilterLocally

public Boolean getFilterLocally()

If filterLocally is set for this item, and this item is showing options from a dataSource, fetch the entire set of options from the server, and use these values to map the item value to the appropriate display value. Also use "local" type filtering on drop down list of options.

This means data will only be fetched once from the server, and then filtered on the client.

Specified by:

getFilterLocally in interface PickList

Overrides:

getFilterLocally in class FormItem

Returns:

Boolean

See Also:

FormItem.getFilterLocally()

setHeight

public void setHeight(int height)

Default height for select items is 19px.

Overrides:

setHeight in class FormItem

Parameters:

height - height Default value is 19

See Also:

Appearance overview and related methods

getHeight

public int getHeight()

Default height for select items is 19px.

Overrides:

getHeight in class FormItem

Returns:

int

See Also:

Appearance overview and related methods

setMultiple

public void setMultiple(Boolean multiple)

If true, multiple values may be selected.

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

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

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

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

Parameters:

multiple - multiple Default value is false

See Also:

Appearance overview and related methods

getMultiple

public Boolean getMultiple()

If true, multiple values may be selected.

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

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

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

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

Returns:

Boolean

See Also:

Appearance overview and related methods

setMultipleAppearance

public void setMultipleAppearance(MultipleAppearance multipleAppearance)

How should items with multiple set to 'true' be displayed?

Parameters:

multipleAppearance - multipleAppearance Default value is "picklist"

getMultipleAppearance

public MultipleAppearance getMultipleAppearance()

How should items with multiple set to 'true' be displayed?

Returns:

MultipleAppearance

setOptionOperationId

public void setOptionOperationId(String optionOperationId)

If this item has a specified optionDataSource, this attribute may be set to specify an explicit operationId when performing a fetch against the option dataSource to pick up display value mapping.

Overrides:

setOptionOperationId in class FormItem

Parameters:

optionOperationId - . See String. Default value is null

getOptionOperationId

public String getOptionOperationId()

If this item has a specified optionDataSource, this attribute may be set to specify an explicit operationId when performing a fetch against the option dataSource to pick up display value mapping.

Overrides:

getOptionOperationId in class FormItem

Returns:

. See String

setPickerIconHeight

public void setPickerIconHeight(Integer pickerIconHeight)

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

Note : This is an advanced setting

Overrides:

setPickerIconHeight in class FormItem

Parameters:

pickerIconHeight - pickerIconHeight Default value is null

getPickerIconHeight

public Integer getPickerIconHeight()

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

Overrides:

getPickerIconHeight in class FormItem

Returns:

Integer

setPickerIconSrc

public void setPickerIconSrc(String pickerIconSrc)

If showPickerIcon is true for this item, this property governs the src of the picker icon image to be displayed.

Note : This is an advanced setting

Overrides:

setPickerIconSrc in class FormItem

Parameters:

pickerIconSrc - . See SCImgURL. Default value is "[SKIN]/DynamicForm/SelectItem_PickButton_icon.gif"

getPickerIconSrc

public String getPickerIconSrc()

If showPickerIcon is true for this item, this property governs the src of the picker icon image to be displayed.

Overrides:

getPickerIconSrc in class FormItem

Returns:

. See SCImgURL

setPickerIconStyle

public void setPickerIconStyle(String pickerIconStyle)

Base CSS class name for a form item's picker icon cell. If unset inherits from this items controlStyle.

Parameters:

pickerIconStyle - . See FormItemBaseStyle. Default value is "selectItemPickerIcon", [IRA]

See Also:

setControlStyle(java.lang.String), Appearance overview and related methods

getPickerIconStyle

public String getPickerIconStyle()

Base CSS class name for a form item's picker icon cell. If unset inherits from this items controlStyle.

Returns:

. See FormItemBaseStyle

See Also:

getControlStyle(), Appearance overview and related methods

setPickerIconWidth

public void setPickerIconWidth(Integer pickerIconWidth)

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

Note : This is an advanced setting

Overrides:

setPickerIconWidth in class FormItem

Parameters:

pickerIconWidth - pickerIconWidth Default value is null

getPickerIconWidth

public Integer getPickerIconWidth()

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

Overrides:

getPickerIconWidth in class FormItem

Returns:

Integer

setPickListCriteria

public void setPickListCriteria(Criteria pickListCriteria)

If this item has a databound pickList (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

Specified by:

setPickListCriteria in interface PickList

Parameters:

pickListCriteria - pickListCriteria Default value is null

getPickListCriteria

public Criteria getPickListCriteria()

If this item has a databound pickList (for example optionDataSource is set), this property can be used to provide static filter criteria when retrieving the data for the pickList.

Specified by:

getPickListCriteria in interface PickList

Returns:

Criteria

setProgressiveLoading

public void setProgressiveLoading(Boolean progressiveLoading)

Indicates whether or not this SelectItem will load its list of options progressively. This property is copied onto the underlying PickList.

Parameters:

progressiveLoading - progressiveLoading Default value is null

See Also:

DataSource.setProgressiveLoading(java.lang.Boolean), ProgressiveLoading overview and related methods

getProgressiveLoading

public Boolean getProgressiveLoading()

Indicates whether or not this SelectItem will load its list of options progressively. This property is copied onto the underlying PickList.

Returns:

Boolean

See Also:

DataSource.getProgressiveLoading(), ProgressiveLoading overview and related methods

setSaveOnEnter

public void setSaveOnEnter(Boolean saveOnEnter)

Select items will submit their containing form on enter keypress if saveOnEnter is true. Setting this property to false will disable this behavior.

Note that if the drop down list of options (pickList) is visible an Enter keypress is used to select a value from the available set of options and will not automatically cause form submission.

Overrides:

setSaveOnEnter in class FormItem

Parameters:

saveOnEnter - saveOnEnter Default value is true

getSaveOnEnter

public Boolean getSaveOnEnter()

Select items will submit their containing form on enter keypress if saveOnEnter is true. Setting this property to false will disable this behavior.

Note that if the drop down list of options (pickList) is visible an Enter keypress is used to select a value from the available set of options and will not automatically cause form submission.

Overrides:

getSaveOnEnter in class FormItem

Returns:

Boolean

setShowFocused

public void setShowFocused(Boolean showFocused)

When this item receives focus, should it be re-styled to indicate it has focus?

Note : This is an advanced setting

Overrides:

setShowFocused in class FormItem

Parameters:

showFocused - showFocused Default value is true, [IRWA]

See Also:

FormItem.setCellStyle(java.lang.String), Appearance overview and related methods

getShowFocused

public Boolean getShowFocused()

When this item receives focus, should it be re-styled to indicate it has focus?

Overrides:

getShowFocused in class FormItem

Returns:

Boolean

See Also:

FormItem.getCellStyle(), Appearance overview and related methods

setShowHintInField

public void setShowHintInField(Boolean showHintInField)

If showing a hint for this form item, should it be shown within the field?

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

Note : This is an advanced setting

Parameters:

showHintInField - showHintInField Default value is null

See Also:

FormItem.setHint(java.lang.String), Appearance overview and related methods

getShowHintInField

public Boolean getShowHintInField()

If showing a hint for this form item, should it be shown within the field?

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

Returns:

Boolean

See Also:

FormItem.getHint(), Appearance overview and related methods

setShowOptionsFromDataSource

public void setShowOptionsFromDataSource(Boolean showOptionsFromDataSource)

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

Note : This is an advanced setting

Specified by:

setShowOptionsFromDataSource in interface PickList

Parameters:

showOptionsFromDataSource - showOptionsFromDataSource Default value is null

See Also:

Databinding overview and related methods

getShowOptionsFromDataSource

public Boolean getShowOptionsFromDataSource()

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

Specified by:

getShowOptionsFromDataSource in interface PickList

Returns:

Boolean

See Also:

Databinding overview and related methods

setShowOver

public void setShowOver(Boolean showOver)

When the user rolls over the select item, should the pickButton display it's Over state?

Note : This is an advanced setting

Parameters:

showOver - showOver Default value is true

getShowOver

public Boolean getShowOver()

When the user rolls over the select item, should the pickButton display it's Over state?

Returns:

Boolean

setShowPickerIcon

public void setShowPickerIcon(Boolean showPickerIcon)

Should we show a special 'picker' icon for this form item. Picker icons are customizable via pickerIconProperties. By default they will be rendered inside the Form Item's "control box" area, and will call SelectItem.showPicker when clicked.

Overrides:

setShowPickerIcon in class FormItem

Parameters:

showPickerIcon - showPickerIcon Default value is true

getShowPickerIcon

public Boolean getShowPickerIcon()

Should we show a special 'picker' icon for this form item. Picker icons are customizable via pickerIconProperties. By default they will be rendered inside the Form Item's "control box" area, and will call SelectItem.showPicker when clicked.

Overrides:

getShowPickerIcon in class FormItem

Returns:

Boolean

setSortField

public void setSortField(String sortField)

Specifies the field by which this item should be initially sorted. Can be set to either a field name or the index of the field in the fields Array. Note that if sortField is initially specified as a number, it will be converted to a string (field name) after the item is initialized.

Parameters:

sortField - . See String. Default value is null

See Also:

Sort Example

getSortField

public String getSortField()

Specifies the field by which this item should be initially sorted. Can be set to either a field name or the index of the field in the fields Array. Note that if sortField is initially specified as a number, it will be converted to a string (field name) after the item is initialized.

Returns:

. See String

See Also:

Sort Example

setSortField

public void setSortField(Integer sortField)

Specifies the field by which this item should be initially sorted. Can be set to either a field name or the index of the field in the fields Array. Note that if sortField is initially specified as a number, it will be converted to a string (field name) after the item is initialized.

Parameters:

sortField - sortField Default value is null

See Also:

Sort Example

setTextBoxStyle

public void setTextBoxStyle(String textBoxStyle)

Base CSS class name for a form item's text box element.

NOTE: See the CompoundFormItem_skinning discussion for special skinning considerations.

Overrides:

setTextBoxStyle in class FormItem

Parameters:

textBoxStyle - . See FormItemBaseStyle. Default value is "selectItemText", [IRA]

See Also:

FormItem.setCellStyle(java.lang.String), Appearance overview and related methods

getTextBoxStyle

public String getTextBoxStyle()

Base CSS class name for a form item's text box element.

NOTE: See the CompoundFormItem_skinning discussion for special skinning considerations.

Overrides:

getTextBoxStyle in class FormItem

Returns:

. See FormItemBaseStyle

See Also:

FormItem.getCellStyle(), Appearance overview and related methods

setTextMatchStyle

public void setTextMatchStyle(TextMatchStyle textMatchStyle)

When applying filter criteria to pickList data, what type of matching to use.

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

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

Specified by:

setTextMatchStyle in interface PickList

Parameters:

textMatchStyle - textMatchStyle Default value is "startsWith"

getTextMatchStyle

public TextMatchStyle getTextMatchStyle()

When applying filter criteria to pickList data, what type of matching to use.

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

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

Specified by:

getTextMatchStyle in interface PickList

Returns:

TextMatchStyle

setValueField

public void 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.

Specified by:

setValueField in interface PickList

Overrides:

setValueField in class FormItem

Parameters:

valueField - . See String. Default value is null

See Also:

List - Related Records Example

getValueField

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

Specified by:

getValueField in interface PickList

Overrides:

getValueField in class FormItem

Returns:

. See String

See Also:

List - Related Records Example

addDataArrivedHandler

public HandlerRegistration addDataArrivedHandler(DataArrivedHandler handler)

Add a dataArrived handler.

If this item is showing a dataBound pickList, this notification method will be fired when new data arrives from the server.

Specified by:

addDataArrivedHandler in interface HasDataArrivedHandlers

Parameters:

handler - the dataArrived handler

Returns:

HandlerRegistration used to remove this handler

defaultDynamicValue

public void defaultDynamicValue()

Expression evaluated to determine the defaultValue when no value is provided for this item. To default to the first option use defaultToFirstOption instead.

getDisplayFieldName

public String getDisplayFieldName()

Returns the displayField for this item. This will typically be specified explicitly via the displayField attribute. However, if that property is unset, and the valueField for this item is hidden in the optionDataSource, this method will return the title field for the optionDataSource.

Specified by:

getDisplayFieldName in interface PickList

Overrides:

getDisplayFieldName in class FormItem

Returns:

display field name, or null if there is no separate display field to use.

getValueFieldName

public String getValueFieldName()

Getter method to retrieve the valueField for this item. If unset, default behavior will return the name of this field.

Specified by:

getValueFieldName in interface PickList

Overrides:

getValueFieldName in class FormItem

Returns:

fieldName to use a "value field" in records from this items optionDataSource

getPickListFilterCriteria

protected Criteria getPickListFilterCriteria()

Returns a set of filter criteria to be applied to the data displayed in the pickList when it is shown.
If this is a databound item the criteria will be passed as criteria to DataSource.fetchData(). Otherwise an equivalent client-side filter will be performed on the data returned by PickList.getClientPickListData().
By default returns PickList.pickListCriteria if specified, otherwise an empty set of criteria so all records will be displayed. Note : this is an override point - if overridden this method will be called by the live form item during filtering. However it is recommended that developers use setPickListFilterCriteriaFunction(FormItemCriteriaFunction) to build custom criteria instead of overriding this method directly. This ensures that the custom filter criteria generating code will be called even if the form item was automatically generated based on a template passed to ListGridField.setEditorType(com.smartgwt.client.widgets.form.fields.FormItem).

Returns:

criteria to be used for databound or local filtering

setPickListFields

public void setPickListFields(ListGridField... pickListFields)

This property allows the developer to specify which field[s] will be displayed in the drop down list of options.

Only applies to databound pickLists (see optionDataSource, or picklists with custom data set up via the advanced PickList.getClientPickListData() method.

If this property is unset, we display the displayField, if specified, otherwise the valueField

If there are multiple fields, column headers will be shown for each field, the height of which can be customized via the pickListHeaderHeight attribute.

Each field to display should be specified as a ListGridField object. Note that unlike in ListGrid, dataSource fields marked as com.smartgwt.client.data.DataSourceField#setDis${isc.DocUtils.linkForRef('DataSourceField.display','display:true')} will not be hidden by default in pickLists. To override this behavior, ensure that you specify an explicit value for {@link com.smartgwt.client.widgets.grid.ListGridField#getShowIf showIf}

Note : This is an advanced setting

Parameters:

pickListFields - pickListFields Default value is null

setPickListHeight

public void setPickListHeight(int pickListHeight)

Maximum height to show the pick list before it starts to scroll. Note that by default the pickList will be sized to the height required by its content so it will be taller when more rows are available as selectable options

Specified by:

setPickListHeight in interface PickList

Parameters:

pickListHeight - pickListHeight Default value is 300

getPickListHeight

public int getPickListHeight()

Maximum height to show the pick list before it starts to scroll. Note that by default the pickList will be sized to the height required by its content so it will be taller when more rows are available as selectable options

Specified by:

getPickListHeight in interface PickList

Returns:

int

setEmptyPickListHeight

public void setEmptyPickListHeight(int emptyPickListHeight)

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

Specified by:

setEmptyPickListHeight in interface PickList

Parameters:

emptyPickListHeight - emptyPickListHeight Default value is 100

getEmptyPickListHeight

public int getEmptyPickListHeight()

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

Specified by:

getEmptyPickListHeight in interface PickList

Returns:

int

setEmptyPickListMessage

public void setEmptyPickListMessage(String emptyPickListMessage)

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

Note : This is an advanced setting

Specified by:

setEmptyPickListMessage in interface PickList

Parameters:

emptyPickListMessage - emptyPickListMessage Default value is null

getEmptyPickListMessage

public String getEmptyPickListMessage()

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

Specified by:

getEmptyPickListMessage in interface PickList

Returns:

String

setHideEmptyPickList

public void setHideEmptyPickList(Boolean hideEmptyPickList)

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

Specified by:

setHideEmptyPickList in interface PickList

Parameters:

hideEmptyPickList - hideEmptyPickList Default value is null

getHideEmptyPickList

public Boolean getHideEmptyPickList()

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

Specified by:

getHideEmptyPickList in interface PickList

Returns:

Boolean

setPickListWidth

public void setPickListWidth(Integer pickListWidth)

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

Specified by:

setPickListWidth in interface PickList

Parameters:

pickListWidth - pickListWidth Default value is null

getPickListWidth

public Integer getPickListWidth()

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

Specified by:

getPickListWidth in interface PickList

Returns:

Integer

setPickListBaseStyle

public void setPickListBaseStyle(String pickListBaseStyle)

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

Specified by:

setPickListBaseStyle in interface PickList

Parameters:

pickListBaseStyle - pickListBaseStyle Default value is "pickListCell"

getPickListBaseStyle

public String getPickListBaseStyle()

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

Specified by:

getPickListBaseStyle in interface PickList

Returns:

String

setAnimatePickList

public void setAnimatePickList(Boolean animatePickList)

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

Note : This is an advanced setting

Specified by:

setAnimatePickList in interface PickList

Parameters:

animatePickList - animatePickList Default value is null

getAnimatePickList

public Boolean getAnimatePickList()

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

Specified by:

getAnimatePickList in interface PickList

Returns:

Boolean

setAnimationTime

public void setAnimationTime(int animationTime)

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

Note : This is an advanced setting

Specified by:

setAnimationTime in interface PickList

Parameters:

animationTime - animationTime Default value is 200

getAnimationTime

public int getAnimationTime()

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

Specified by:

getAnimationTime in interface PickList

Returns:

int

setPickListHeaderHeight

public void setPickListHeaderHeight(int pickListHeaderHeight)

If this pick list is showing multiple fields, this property determines the height of the column headers for those fields. Set to zero to suppress the headers entirely.

Specified by:

setPickListHeaderHeight in interface PickList

Parameters:

pickListHeaderHeight - pickListHeaderHeight Default value is 22

getPickListHeaderHeight

public int getPickListHeaderHeight()

If this pick list is showing multiple fields, this property determines the height of the column headers for those fields. Set to zero to suppress the headers entirely.

Specified by:

getPickListHeaderHeight in interface PickList

Returns:

int

getSortFieldAsInt

public Integer getSortFieldAsInt()

Specifies the field by which this item should be initially sorted. Can be set to either a 'field name' or the index of the field in the fields Array. Note that if sortField is initally specified as a number, it will be converted to a string (field name) after the item is initialized.

To programmatically change sort field or direction after initialization, call ${isc.DocUtils.linkForRef('sort')}.

Returns:

Integer

setValueIconField

public void setValueIconField(String valueIconField)

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

Note : This is an advanced setting

Specified by:

setValueIconField in interface PickList

Parameters:

valueIconField - valueIconField Default value is null

getValueIconField

public String getValueIconField()

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

Specified by:

getValueIconField in interface PickList

Returns:

String

setShowAllOptions

public void setShowAllOptions(Boolean showAllOptions)

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

Specified by:

setShowAllOptions in interface PickList

Parameters:

showAllOptions - showAllOptions Default value is null

getShowAllOptions

public Boolean getShowAllOptions()

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

Specified by:

getShowAllOptions in interface PickList

Returns:

Boolean

setPickListCriteria

public void setPickListCriteria(DSRequest optionFilterContext)

If this item has a specified optionDataSource, and this property is not null, this will be passed to the datasource as RPCRequest properties when performing the filter operation on the dataSource to obtain the set of options for the list.

Note : This is an advanced setting

Parameters:

optionFilterContext - optionFilterContext Default value is null

setOptionDataSource

public void setOptionDataSource(DataSource dataSource)

If set, this FormItem will derive data to show in the PickList by fetching records from the specified optionDataSource. The fetched data will be used as a valueMap by extracting the valueField and displayField in the loaded records, to derive one valueMap entry per record loaded from the optionDataSource. Multiple fields from the fetched data may be shown in the pickList by setting pickListFields.

The data will be retrieved via a "fetch" operation on the DataSource, passing the pickListCriteria (if set) as criteria, and passing optionFilterContext (if set) as DSRequest properties.

The fetch will be triggered when the pickList is first shown, or, you can set autoFetchData to fetch when the FormItem is first drawn. You can also call com.smartgwt.client.widgets.form.fields.PickList#fetchData at any time to manually trigger a fetch.

Data paging is automatically enabled if the optionDataSource supports it. As the pickList is scrolled by the user, requests for additional data will be automatically issued.

For a pickList attached to a ComboBoxItem, new fetches are issued as the user types, with criteria set as described under ComboBoxItem.getPickListFilterCriteria(). If your dataSource is not capable of filtering results by search criteria (eg the dataSource is backed by an XML flat file), you can set filterLocally to have the entire dataset loaded up front and filtering performed in the browser. This disables data paging.

Setting optionDataSource also enables the basic optionDataSource behaviors, eg, fetching individual display values before the pickList is shown.

Note that if a normal, static valueMap is also specified for the field (either directly in the form item or as part of the field definition in the dataSource), it will be preferred to the data derived from the optionDataSource for whatever mappings are present.

Note : This is an advanced setting

Specified by:

setOptionDataSource in interface PickList

Overrides:

setOptionDataSource in class FormItem

Parameters:

optionDataSource - optionDataSource Default value is null

getOptionDataSource

public DataSource getOptionDataSource()

Specified by:

getOptionDataSource in interface PickList

setSeparatorRows

public void setSeparatorRows(ListGridRecord[] separatorRows)

Description copied from interface: PickList

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

Not valid for 'databound pickLists'.

Specified by:

setSeparatorRows in interface PickList

Parameters:

separatorRows - separator rows

setDefaultValues

public void setDefaultValues(String... defaultValues)

Default values used when no value is provided for this item. Note that whenever this item's value is cleared by the user or set to null programatically, it will be reverted to the defaultValues.

Parameters:

defaultValues - the defaultValues. Default value is null

setDefaultValues

public void setDefaultValues(Integer... defaultValues)

Default values used when no value is provided for this item. Note that whenever this item's value is cleared by the user or set to null programatically, it will be reverted to the defaultValues.

Parameters:

defaultValues - the defaultValues. Default value is null

setFetchDelay

public void setFetchDelay(Integer fetchDelay)

Description copied from interface: PickList

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

Specified by:

setFetchDelay in interface PickList

Parameters:

fetchDelay - the fetch delay. defaults to 200ms

getFetchDelay

public Integer getFetchDelay()

Description copied from interface: PickList

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

Specified by:

getFetchDelay in interface PickList

Returns:

the fetch delay

getValues

public String[] getValues()

Returns the values of a SelectItem with multiple=true as an array of Strings.

Returns:

value of selection. If no values are selected, and empty array is returned

setValues

public void setValues(String... values)

Set the values of a SelectItem with multiple=true.

Parameters:

values - the SelectItem values

isMultiple

public Boolean isMultiple()

If true, multiple values may be selected.

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

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

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

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

Returns:

Boolean

See Also:

Appearance overview and related methods

fetchData

public void fetchData()

Only applies to databound items (see optionDataSource).
Performs a fetch type operation on this item's DataSource to retrieve the set of valid options for the item, based on the current pickListCriteria.

fetchData

public void fetchData(DSCallback callback)

Only applies to databound items (see optionDataSource).
Performs a fetch type operation on this item's DataSource to retrieve the set of valid options for the item, based on the current pickListCriteria.

Parameters:

callback - Callback to fire when the fetch completes. Callback will fire with 2 parameters: item a pointer to the form item and dsResponse the DSResponse returned by the server.

fetchData

public void fetchData(DSCallback callback,
                      DSRequest requestProperties)

Only applies to databound items (see optionDataSource).
Performs a fetch type operation on this item's DataSource to retrieve the set of valid options for the item, based on the current pickListCriteria.

Parameters:

callback - Callback to fire when the fetch completes. Callback will fire with 2 parameters: item a pointer to the form item and dsResponse the DSResponse returned by the server.

requestProperties - properties to apply to the dsRequest for this fetch.

filterClientPickListData

public ListGridRecord[] filterClientPickListData()

Description copied from interface: PickList

Returns the data to display in the pick list.

The default implementation applies the criteria returned by #getPickListFilterCriteria to the data returned by PickList.getClientPickListData(). A record passes the filter if it has a matching value for all fields in the criteria object. Matching is performed according to textMatchStyle.

If showAllOptions is set, all values are shown, with matching values shown below a separator.

Specified by:

filterClientPickListData in interface PickList

Returns:

array of record objects to display in the pickList

getClientPickListData

public ListGridRecord[] getClientPickListData()

Description copied from interface: PickList

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

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

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

Specified by:

getClientPickListData in interface PickList

Returns:

Array of record objects to be displayed in the pickList. Note that when a user picks a record from the list, the value of the field matching item.valueField will be picked. Also note that the fields to be displayed can be customized via item.pickListFields

setFields

public void setFields(FormItemIcon pickerIconProperties)

showPicker

public void showPicker()

Method to show a picker for this item. By default this method is called if the user clicks on a pickerIcon, shown by setting this.showPickerIcon to true. May also be called programatically.
Default implementation lazily creates a 'picker' from the set of defaults defined on this FormItem.

Overrides:

showPicker in class FormItem

getSelectedRecord

public ListGridRecord getSelectedRecord()

Returns the entire record object associated with the current value for this item (or null if no matching record exists in the PickList data). Most commonly used for databound pickListItems to retrieve the values of other fields in the record.

Overrides:

getSelectedRecord in class FormItem

Returns:

the selected record or null

getSelectedRecords

public ListGridRecord[] getSelectedRecords()

For a SelectItem with an setOptionDataSource(com.smartgwt.client.data.DataSource) optionDataSource} and allowing multiple selection multiple :true, returns the list of currently selected records, or null if none are selected.

Returns:

the list of selected records, or null if none are selected

setPickListFilterCriteriaFunction

public void setPickListFilterCriteriaFunction(FilterCriteriaFunction filterCriteriaFunction)

Deprecated. in favor of setPickListFilterCriteriaFunction(FormItemCriteriaFunction)

Set the pick list filter criteria function / handler.

Specified by:

setPickListFilterCriteriaFunction in interface PickList

Parameters:

filterCriteriaFunction - the filter criteria function

setPickListFilterCriteriaFunction

public void setPickListFilterCriteriaFunction(FormItemCriteriaFunction filterCriteriaFunction)

Set up a method to return filter criteria for options displayed for this item.
The criteria returned by this method are used to decide which options should appear in the drop-down PickList shown by this SelectItem.
Static criteria, specified via pickListCriteria, will always be included in addition to criteria returned by this method.

setPickListProperties

public void setPickListProperties(ListGrid pickListProperties)

Set the properties to be applied to the pickList created for this Form Item.

Parameters:

pickListProperties - the pick list properties

setOptionFilterContext

public void setOptionFilterContext(DSRequest dsRequestProperties)

Description copied from interface: PickList

If this item has a specified optionDataSource, and this property is 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

Specified by:

setOptionFilterContext in interface PickList

Parameters:

dsRequestProperties - optionFilterContext Default value is null

getValueAsString

public String getValueAsString()

Return the value tracked by this form item.

Returns:

value of this element

setPickListSort

public void setPickListSort(SortSpecifier[] sortSpecifiers)

This method sorts the pickList on one or more fields, creating the underlying JS object if needed. Pass in an array of SortSpecifiers to have the grid's data sorted by the fields in each specifier.property and in the directions specified. The grid can be sorted by any combination of fields, including fields specified in the fields array, whether visible or hidden, and 'unused fields from the underlying dataSource', if there is one. If multiple fields are sorted, those that are visible show a directional icon and a small 'sort-numeral' indicating that field's index in the sort configuration.

See ListGrid.addSort(com.smartgwt.client.data.SortSpecifier) and com.smartgwt.client.widgets.grid.ListGrid#alterSort APIs for information on making changes to the current sort configuration.

Parameters:

sortSpecifiers - Array of SortSpecifier objects