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

java.lang.Object
  extended by com.smartgwt.client.core.JsObject
      extended by com.smartgwt.client.core.DataClass
          extended by com.smartgwt.client.core.RefDataClass
              extended by com.smartgwt.client.widgets.form.fields.FormItem
                  extended by com.smartgwt.client.widgets.form.fields.ComboBoxItem
All Implemented Interfaces:
HasHandlers, HasBlurHandlers, HasChangedHandlers, HasChangeHandlers, HasClickHandlers, HasDoubleClickHandlers, HasFocusHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasTitleHoverHandlers, PickList

public class ComboBoxItem
extends FormItem
implements PickList

The Combobox is a text input field which can show a list of options via a drop-down PickList.

The set of options will be filtered based on the current value in the text field, so only options that match what has been typed so far will be displayed. The set of options can be derived from a ValueMap or dynamically retrieved from a dataSource. See the com.smartgwt.client..PickList interface for further settings.

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


Field Summary
 
Fields inherited from class com.smartgwt.client.core.JsObject
jsObj
 
Constructor Summary
ComboBoxItem()
           
ComboBoxItem(com.google.gwt.core.client.JavaScriptObject jsObj)
           
ComboBoxItem(java.lang.String name)
           
ComboBoxItem(java.lang.String name, java.lang.String title)
           
 
Method Summary
 void defaultDynamicValue()
          Expression evaluated to determine the defaultValue when no value is provided for this item.
 void fetchData()
           
 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.
 java.lang.Boolean getAnimatePickList()
          If true, when the pickList is shown, it will be shown via an animated reveal effect
 int getAnimationTime()
          If this.animatePickList is true - this specifies the duration of the animation effect applied when showing the pickList
 java.lang.Boolean getAutoFetchData()
          If this combo box retrieves its options from a dataSource, should options be fetched from the server when the item is first written out, or should this fetch be delayed until the user opens the pickList.
 java.lang.Boolean getCompleteOnTab()
          If true, when the pickList is showing, the user can select the current value by hitting the Tab key.
 java.lang.Boolean getDefaultToFirstOption()
          Select the first option as the default value for this ComboBoxItem.
 java.lang.Boolean getDefaultValue()
          Static default value for this ComboBoxItem.
 java.lang.String getDisplayField()
          Specifies an alternative field from which display values should be retrieved for this item.
 java.lang.String getDisplayFieldName()
          Returns the displayField for this form item. If unset, and optionDataSource is explicitly specified, this method will return the title field for the optionDataSource
 int getEmptyPickListHeight()
          Height for an empty pick list (showing the empty message), if the pick list has no records and hideEmptyPickList is false.
 java.lang.String getEmptyPickListMessage()
          Empty message to display in the pickList if hideEmptyPickList is false.
 java.lang.Integer getFetchDelay()
          For a ComboBox or other pickList that accepts user-entered criteria, how many millseconds to wait after the last user keystroke before fetching data from the server.
 java.lang.Boolean getFilterLocally()
          If filterLocally is set for this item, and this item is showing options from a dataSource, fetch the entire set of options from the server, and use these values to map the item value to the appropriate display value.
 java.lang.Boolean getFilterWithValue()
          Read-only property set by the ComboBoxItem to indicate whether we should use the current typed-in value as part of the filter criteria returned by getPickListFilterCriteria().
 java.lang.Boolean getHideEmptyPickList()
          If this pickList contains no options, should it be hidden? If unset, default behavior is to allow the empty pickList to show if it is databound.
static ComboBoxItem getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)
           
 java.lang.Integer getPickerIconHeight()
          Don't specify an explicit height for the picker icon - instead have it size to match the height of the combo box item.
 java.lang.String getPickerIconSrc()
          Src for the picker icon
 java.lang.String getPickListBaseStyle()
          Base Style for pickList cells.
 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.
protected  Criteria getPickListFilterCriteria()
          Returns filter criteria for options displayed for this item.
 int getPickListHeaderHeight()
          If this pick list is showing multiple fields, this property determines the height of the column headers for those fields.
 int getPickListHeight()
          Maximum height to show the pick list before it starts to scroll.
 java.lang.Integer getPickListWidth()
          Default width to show the pickList.
 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).
 java.lang.Boolean getShowAllOptions()
          If true, even non-matching options will be shown, with configurable separatorRows in between.
 java.lang.Boolean getShowOptionsFromDataSource()
          If this item is part of a databound form, and has a specified valueMap by default we show the valueMap options in the pickList for the item. Setting this property to true will ensure that the options displayed in our pickList are derived from the form's dataSource.
 java.lang.Boolean getShowPickerIcon()
          Show the picker icon for the combo box
 java.lang.Boolean getShowPickListOnKeypress()
          Should the list of options be displayed whenever the user types into the the combo-box textArea, or only when the user clicks on the pick button or uses the explicit Alt+Arrow Down key combo?
 TextMatchStyle getTextMatchStyle()
          When applying filter criteria to pickList data, what type of matching to use.
 java.lang.String getValueField()
          If this form item maps data values to display values by retrieving the displayField values from an optionDataSource, this property denotes the the field to use as the underlying data value in records from the optionDataSource.
If unset, assumed to be the name of this form item.
 java.lang.String getValueFieldName()
          Getter method to retrieve the valueField for this item. If unset, default behavior will return the name of this field.
 java.lang.String getValueIconField()
          For Databound formItems, this property determines which column valueIcons should show up in for this formItem's pickList.
If unset valueIcons show up in the displayField column if specified, otherwise the valueField column.
In most cases only the displayField or valueField will be visible.
 void setAnimatePickList(java.lang.Boolean animatePickList)
          If true, when the pickList is shown, it will be shown via an animated reveal effect
 void setAnimationTime(int animationTime)
          If this.animatePickList is true - this specifies the duration of the animation effect applied when showing the pickList
 void setAutoFetchData(java.lang.Boolean autoFetchData)
          If this combo box retrieves its options from a dataSource, should options be fetched from the server when the item is first written out, or should this fetch be delayed until the user opens the pickList.
 void setCompleteOnTab(java.lang.Boolean completeOnTab)
          If true, when the pickList is showing, the user can select the current value by hitting the Tab key.
 void setDefaultToFirstOption(java.lang.Boolean defaultToFirstOption)
          Select the first option as the default value for this ComboBoxItem.
 void setDefaultValue(java.lang.Boolean defaultValue)
          Static default value for this ComboBoxItem.
 void setDisplayField(java.lang.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(java.lang.String emptyPickListMessage)
          Empty message to display in the pickList if hideEmptyPickList is false.
 void setFetchDelay(java.lang.Integer fetchDelay)
          For a ComboBox or other pickList that accepts user-entered criteria, how many millseconds to wait after the last user keystroke before fetching data from the server.
 void setFilterLocally(java.lang.Boolean filterLocally)
          If filterLocally is set for this item, and this item is showing options from a dataSource, fetch the entire set of options from the server, and use these values to map the item value to the appropriate display value.
 void setHideEmptyPickList(java.lang.Boolean hideEmptyPickList)
          If this pickList contains no options, should it be hidden? If unset, default behavior is to allow the empty pickList to show if it is databound.
 void setOptionDataSource(DataSource dataSource)
          If set, this FormItem will derive data to show in the PickList by fetching records from the specified optionDataSource.
 void setPickerIconHeight(java.lang.Integer pickerIconHeight)
          Don't specify an explicit height for the picker icon - instead have it size to match the height of the combo box item.
 void setPickerIconSrc(java.lang.String pickerIconSrc)
          Src for the picker icon
 void setPickListBaseStyle(java.lang.String pickListBaseStyle)
          Base Style for pickList cells.
 void 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 setPickListCriteria(RPCRequest optionFilterContext)
           
 void setPickListFields(ListGridField... pickListFields)
           
 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 setPickListWidth(java.lang.Integer pickListWidth)
          Default width to show the pickList.
 void setSeparatorRows(ListGridRecord[] separatorRows)
          Array of records to show between matching and non-matching rows in the PickList.
 void setShowAllOptions(java.lang.Boolean showAllOptions)
          If true, even non-matching options will be shown, with configurable separatorRows in between.
 void setShowOptionsFromDataSource(java.lang.Boolean showOptionsFromDataSource)
          If this item is part of a databound form, and has a specified valueMap by default we show the valueMap options in the pickList for the item. Setting this property to true will ensure that the options displayed in our pickList are derived from the form's dataSource.
 void setShowPickerIcon(java.lang.Boolean showPickerIcon)
          Show the picker icon for the combo box
 void setShowPickListOnKeypress(java.lang.Boolean showPickListOnKeypress)
          Should the list of options be displayed whenever the user types into the the combo-box textArea, or only when the user clicks on the pick button or uses the explicit Alt+Arrow Down key combo?
 void setTextMatchStyle(TextMatchStyle textMatchStyle)
          When applying filter criteria to pickList data, what type of matching to use.
 void setValueField(java.lang.String valueField)
          If this form item maps data values to display values by retrieving the displayField values from an optionDataSource, this property denotes the the field to use as the underlying data value in records from the optionDataSource.
If unset, assumed to be the name of this form item.
 void setValueIconField(java.lang.String valueIconField)
          For Databound formItems, this property determines which column valueIcons should show up in for this formItem's pickList.
If unset valueIcons show up in the displayField column if specified, otherwise the valueField column.
In most cases only the displayField or valueField will be visible.
 
Methods inherited from class com.smartgwt.client.widgets.form.fields.FormItem
addBlurHandler, addChangedHandler, addChangeHandler, addClickHandler, addDoubleClickHandler, addFocusHandler, addIconClickHandler, addIconKeyPressHandler, addItemHoverHandler, addKeyDownHandler, addKeyPressHandler, addKeyUpHandler, addTitleHoverHandler, blurItem, disable, enable, focusInItem, getAccessKey, getAlign, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsString, getCellStyle, getConfig, getCriteriaField, getCriterion, getDateFormatter, getDefaultIconSrc, getDisabled, getDisplayValue, getDisplayValue, getEmptyDisplayValue, getEmptyValueIcon, getEndRow, getErrorIconHeight, getErrorIconSrc, getErrorIconWidth, getErrorMessageWidth, getFetchMissingValues, getFieldName, getGlobalTabIndex, getHeight, getHint, getHintStyle, getHoverAlign, getHoverDelay, getHoverHeight, getHoverOpacity, getHoverStyle, getHoverVAlign, getHoverWidth, getIconHeight, getIconPageRect, getIconPrompt, getIconRect, getIconVAlign, getIconWidth, getImageURLPrefix, getImageURLSuffix, getLeft, getName, getOperator, getPickerIconWidth, getPrompt, getRejectInvalidValueOnChange, getRequired, getRowSpan, getSelectOnFocus, getShouldSaveValue, getShowDisabled, getShowErrorIcon, getShowErrorStyle, getShowErrorText, getShowFocused, getShowFocusedIcons, getShowFocusedPickerIcon, getShowHint, getShowIcons, getShowOverIcons, getShowTitle, getShowValueIconOnly, getStartRow, getSuppressValueIcon, getTabIndex, getTextAlign, getTextBoxStyle, getTimeFormatter, getTitle, getTitleAlign, getTitleOrientation, getTitleStyle, getTooltip, getTop, getType, getValidateOnChange, getValue, getValueIconHeight, getValueIconLeftPadding, getValueIconRightPadding, getValueIconSize, getValueIconWidth, getVisible, getWidth, getWrapTitle, hide, isCreated, isDisabled, isDrawn, redraw, setAccessKey, setAlign, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setCellStyle, setColSpan, setColSpan, setCriteriaField, setDateFormatter, setDefaultIconSrc, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDisabled, setEditorType, setEmptyDisplayValue, setEmptyValueIcon, setEndRow, setErrorFormatter, setErrorIconHeight, setErrorIconSrc, setErrorIconWidth, setErrorMessageWidth, setErrorOrientation, setFetchMissingValues, setGlobalTabIndex, setHeight, setHeight, setHint, setHintStyle, setHoverAlign, setHoverDelay, setHoverHeight, setHoverOpacity, setHoverStyle, setHoverVAlign, setHoverWidth, setIconHeight, setIconPrompt, setIcons, setIconVAlign, setIconWidth, setImageURLPrefix, setImageURLSuffix, setInputTransformer, setItemHoverFormatter, setItemTitleHoverFormatter, setLeft, setName, setOperator, setPickerIconWidth, setPrompt, setProperty, setProperty, setProperty, setProperty, setRedrawOnChange, setRejectInvalidValueOnChange, setRequired, setRowSpan, setSelectOnFocus, setShouldSaveValue, setShowDisabled, setShowErrorIcon, setShowErrorStyle, setShowErrorText, setShowFocused, setShowFocusedIcons, setShowFocusedPickerIcon, setShowHint, setShowIcons, setShowIfCondition, setShowOverIcons, setShowTitle, setShowValueIconOnly, setStartRow, setSuppressValueIcon, setTabIndex, setTextAlign, setTextBoxStyle, setTimeFormatter, setTitle, setTitleAlign, setTitleOrientation, setTitleStyle, setTooltip, setTop, setType, setValidateOnChange, setValidators, setValue, setValue, setValue, setValue, setValue, setValue, setValueIconHeight, setValueIconLeftPadding, setValueIconRightPadding, setValueIcons, setValueIconSize, setValueIconWidth, setValueMap, setValueMap, setVisible, setWidth, setWidth, setWrapTitle, show, stopHover, updateState
 
Methods inherited from class com.smartgwt.client.core.RefDataClass
getRef, getRef
 
Methods inherited from class com.smartgwt.client.core.DataClass
doAddHandler, fireEvent, getAttributeAsIntArray, getAttributeAsMap, getAttributeAsObject, getAttributeAsStringArray, getAttributes, getHandlerCount, getJsObj, 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
 
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
 
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
 
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
 
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
 
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
 
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
 
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
 
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
 
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
 
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
 
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
 
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
 

Constructor Detail

ComboBoxItem

public ComboBoxItem()

ComboBoxItem

public ComboBoxItem(com.google.gwt.core.client.JavaScriptObject jsObj)

ComboBoxItem

public ComboBoxItem(java.lang.String name)

ComboBoxItem

public ComboBoxItem(java.lang.String name,
                    java.lang.String title)
Method Detail

getOrCreateRef

public static ComboBoxItem getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)

setDefaultValue

public void setDefaultValue(java.lang.Boolean defaultValue)
Static default value for this ComboBoxItem. To default to the first option use defaultToFirstOption instead.

Overrides:
setDefaultValue in class FormItem
Parameters:
defaultValue - defaultValue Default value is null

getDefaultValue

public java.lang.Boolean getDefaultValue()
Static default value for this ComboBoxItem. To default to the first option use defaultToFirstOption instead.

Returns:
Boolean

setDefaultToFirstOption

public void setDefaultToFirstOption(java.lang.Boolean defaultToFirstOption)
Select the first option as the default value for this ComboBoxItem. If options are derived from a dataSource, the first value returned by the server will be used, otherwise the first value in the valueMap. If enabled, this setting overrides defaultValue and defaultDynamicValue()|.

Parameters:
defaultToFirstOption - defaultToFirstOption Default value is false

getDefaultToFirstOption

public java.lang.Boolean getDefaultToFirstOption()
Select the first option as the default value for this ComboBoxItem. If options are derived from a dataSource, the first value returned by the server will be used, otherwise the first value in the valueMap. If enabled, this setting overrides defaultValue and defaultDynamicValue()|.

Returns:
Boolean

setShowPickerIcon

public void setShowPickerIcon(java.lang.Boolean showPickerIcon)
Show the picker icon for the combo box

Note : This is an advanced setting

Overrides:
setShowPickerIcon in class FormItem
Parameters:
showPickerIcon - showPickerIcon Default value is true

getShowPickerIcon

public java.lang.Boolean getShowPickerIcon()
Show the picker icon for the combo box

Overrides:
getShowPickerIcon in class FormItem
Returns:
Boolean

setPickerIconHeight

public void setPickerIconHeight(java.lang.Integer pickerIconHeight)
Don't specify an explicit height for the picker icon - instead have it size to match the height of the combo box item.

Overrides:
setPickerIconHeight in class FormItem
Parameters:
pickerIconHeight - pickerIconHeight Default value is null

getPickerIconHeight

public java.lang.Integer getPickerIconHeight()
Don't specify an explicit height for the picker icon - instead have it size to match the height of the combo box item.

Overrides:
getPickerIconHeight in class FormItem
Returns:
Integer

setPickerIconSrc

public void setPickerIconSrc(java.lang.String pickerIconSrc)
Src for the picker icon

Note : This is an advanced setting

Overrides:
setPickerIconSrc in class FormItem
Parameters:
pickerIconSrc - pickerIconSrc Default value is "[SKIN]/DynamicForm/ComboBoxItem_PickButton_icon.gif"

getPickerIconSrc

public java.lang.String getPickerIconSrc()
Src for the picker icon

Overrides:
getPickerIconSrc in class FormItem
Returns:
String

setShowPickListOnKeypress

public void setShowPickListOnKeypress(java.lang.Boolean showPickListOnKeypress)
Should the list of options be displayed whenever the user types into the the combo-box textArea, or only when the user clicks on the pick button or uses the explicit Alt+Arrow Down key combo?

Parameters:
showPickListOnKeypress - showPickListOnKeypress Default value is true

getShowPickListOnKeypress

public java.lang.Boolean getShowPickListOnKeypress()
Should the list of options be displayed whenever the user types into the the combo-box textArea, or only when the user clicks on the pick button or uses the explicit Alt+Arrow Down key combo?

Returns:
Boolean

setCompleteOnTab

public void setCompleteOnTab(java.lang.Boolean completeOnTab)
If true, when the pickList is showing, the user can select the current value by hitting the Tab key.

Parameters:
completeOnTab - completeOnTab Default value is null

getCompleteOnTab

public java.lang.Boolean getCompleteOnTab()
If true, when the pickList is showing, the user can select the current value by hitting the Tab key.

Returns:
Boolean

setDisplayField

public void setDisplayField(java.lang.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 DynamicForm.getValue(java.lang.String) 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.

Note : This is an advanced setting

Specified by:
setDisplayField in interface PickList
Overrides:
setDisplayField in class FormItem
Parameters:
displayField - displayField Default value is null

getDisplayField

public java.lang.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 DynamicForm.getValue(java.lang.String) 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:
String

setValueField

public void setValueField(java.lang.String valueField)
If this form item maps data values to display values by retrieving the displayField values from an optionDataSource, this property denotes the the field to use as the underlying data value in records from the optionDataSource.
If unset, assumed to be the name of this form item.

Specified by:
setValueField in interface PickList
Overrides:
setValueField in class FormItem
Parameters:
valueField - valueField Default value is null

getValueField

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

Specified by:
getValueField in interface PickList
Overrides:
getValueField in class FormItem
Returns:
String

setFilterLocally

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

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

Note : This is an advanced setting

Specified by:
setFilterLocally in interface PickList
Overrides:
setFilterLocally in class FormItem
Parameters:
filterLocally - filterLocally Default value is false

getFilterLocally

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

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

Specified by:
getFilterLocally in interface PickList
Overrides:
getFilterLocally in class FormItem
Returns:
Boolean

setShowOptionsFromDataSource

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

Note : This is an advanced setting

Specified by:
setShowOptionsFromDataSource in interface PickList
Parameters:
showOptionsFromDataSource - showOptionsFromDataSource Default value is null

getShowOptionsFromDataSource

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

Specified by:
getShowOptionsFromDataSource in interface PickList
Returns:
Boolean

setAutoFetchData

public void setAutoFetchData(java.lang.Boolean autoFetchData)
If this combo box retrieves its options from a dataSource, should options be fetched from the server when the item is first written out, or should this fetch be delayed until the user opens the pickList.

Note : This is an advanced setting

Parameters:
autoFetchData - autoFetchData Default value is false

getAutoFetchData

public java.lang.Boolean getAutoFetchData()
If this combo box retrieves its options from a dataSource, should options be fetched from the server when the item is first written out, or should this fetch be delayed until the user opens the pickList.

Returns:
Boolean

getFilterWithValue

public java.lang.Boolean getFilterWithValue()
Read-only property set by the ComboBoxItem to indicate whether we should use the current typed-in value as part of the filter criteria returned by getPickListFilterCriteria(). You can check this flag in order to mimic the ComboBoxItem's default behavior if you provide a custom implementation of getPickListFilterCriteria().

Returns:
Boolean

setShowAllOptions

public void setShowAllOptions(java.lang.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 java.lang.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

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 java.lang.String getDisplayFieldName()
Returns the displayField for this form item. If unset, and optionDataSource is explicitly specified, this method will return the title field for the optionDataSource

Specified by:
getDisplayFieldName in interface PickList
Overrides:
getDisplayFieldName in class FormItem
Returns:
display field name, or null

getValueFieldName

public java.lang.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 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 ComboBox.
While the user is typing in a value, this method will return the typed-in value as part of the criteria, so that only matching values are shown. Matching is determined by the textMatchStyle.
If the user explicitly shows the down-down pickList, via either clicking on the drop down icon or use the Ctrl+Arrow Down key combo, the typed in value is ignored for filtering.
If included in the criteria, the typed in value will be included as a value for the displayField (or for the valueField if this.displayField is unspecified).
Static criteria, specified via pickListCriteria, will always be included.
If you are implementing your own getPickListFilterCriteria() the read-only property this.filterWithValue can be read to determine whether the ComboBox would ordinarily ignore the typed-in value for filtering. Note that in addition to cases where the user explicitly shows the pickList, filterWithValue will also be true during a call to ComboBoxItem.fetchData() on a databound comboBox.
Note : this is an override point

Returns:
criteria to be used for databound or local filtering

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(java.lang.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 java.lang.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(java.lang.Boolean hideEmptyPickList)
If this pickList contains no options, should it be hidden? If unset, default behavior is to allow the empty pickList to show if it is databound.

Specified by:
setHideEmptyPickList in interface PickList
Parameters:
hideEmptyPickList - hideEmptyPickList Default value is null

getHideEmptyPickList

public java.lang.Boolean getHideEmptyPickList()
If this pickList contains no options, should it be hidden? If unset, default behavior is to allow the empty pickList to show if it is databound.

Specified by:
getHideEmptyPickList in interface PickList
Returns:
Boolean

setPickListWidth

public void setPickListWidth(java.lang.Integer pickListWidth)
Default width to show the pickList. If not specified, the width of this form item's element will be used instead.

Specified by:
setPickListWidth in interface PickList
Parameters:
pickListWidth - pickListWidth Default value is null

getPickListWidth

public java.lang.Integer getPickListWidth()
Default width to show the pickList. If not specified, the width of this form item's element will be used instead.

Specified by:
getPickListWidth in interface PickList
Returns:
Integer

setTextMatchStyle

public void 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 com.smartgwt.client.widgets.form.fields.PickList#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. 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 com.smartgwt.client.widgets.form.fields.PickList#filterClientPickListData.

Specified by:
getTextMatchStyle in interface PickList
Returns:
TextMatchStyle

setPickListBaseStyle

public void setPickListBaseStyle(java.lang.String pickListBaseStyle)
Base Style for pickList cells. As with ListGrid Cells, will have 'over', 'selected' and 'disabled' appended on changes of state for the cells.

Specified by:
setPickListBaseStyle in interface PickList
Parameters:
pickListBaseStyle - pickListBaseStyle Default value is "pickListCell"

getPickListBaseStyle

public java.lang.String getPickListBaseStyle()
Base Style for pickList cells. As with ListGrid Cells, will have 'over', 'selected' and 'disabled' appended on changes of state for the cells.

Specified by:
getPickListBaseStyle in interface PickList
Returns:
String

setAnimatePickList

public void setAnimatePickList(java.lang.Boolean animatePickList)
If true, when the pickList is shown, it will be shown via an animated reveal effect

Note : This is an advanced setting

Specified by:
setAnimatePickList in interface PickList
Parameters:
animatePickList - animatePickList Default value is null

getAnimatePickList

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

setValueIconField

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

Note : This is an advanced setting

Specified by:
setValueIconField in interface PickList
Parameters:
valueIconField - valueIconField Default value is null

getValueIconField

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

Specified by:
getValueIconField in interface PickList
Returns:
String

setPickListCriteria

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

Specified by:
setPickListCriteria in interface PickList
Parameters:
pickListCriteria - pickListCriteria Default value is null

getPickListCriteria

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

Specified by:
getPickListCriteria in interface PickList
Returns:
Criteria

setPickListCriteria

public void setPickListCriteria(RPCRequest optionFilterContext)

setFetchDelay

public void setFetchDelay(java.lang.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 java.lang.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

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

Overrides:
setOptionDataSource in class FormItem
Parameters:
dataSource - optionDataSource Default value is null

setSeparatorRows

public void setSeparatorRows(ListGridRecord[] separatorRows)
Array of records to show between matching and non-matching rows in the PickList.

Not valid for optionDataSource.

Parameters:
separatorRows - separatorRows Default value is [{isSeparator:true}]

fetchData

public void fetchData()

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.

setPickListFields

public void setPickListFields(ListGridField... pickListFields)

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.

Returns:
the selected record or null