ComboBoxItem

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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

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.TextItem
                      com.smartgwt.client.widgets.form.fields.ComboBoxItem

All Implemented Interfaces:: HasHandlers, HasBlurHandlers, HasChangedHandlers, HasChangeHandlers, HasClickHandlers, HasDataArrivedHandlers, HasDoubleClickHandlers, HasFocusHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasTitleClickHandlers, HasTitleDoubleClickHandlers, HasTitleHoverHandlers, PickList

public class ComboBoxItem
extends TextItem
implements PickList, HasDataArrivedHandlers
extends TextItem
implements PickList, HasDataArrivedHandlers

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 PickList interface for further settings.

The two most common use cases for ComboBoxItems are:

With addUnknownValues set to true, the ComboBoxItem acts as a freeform text entry field with the picklist providing essentially a set of suggested completions similar to a URL bar in a web browser.
With addUnkownValues set to false, the ComboBoxItem acts similarly to a SelectItem where a fixed set of options is available to the user and the text entry field is essentially used to filter which of these options are visible

Other commonly used settings to configure ComboBoxItem behavior are:
- defaultToFirstOption - this will select the first option from the pickList as a default value for the item - and
- completeOnTab which causes the current selection in the pickList (if there is one) to be chosen when the user tabs out of the field, allowing a user to type a few characters and hit tab to auto-complete to the first matched option. completeOnTab is automatically set to true if addUnknownValues is false.

Field Summary

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

Constructor Summary
`ComboBoxItem()`
`ComboBoxItem(JavaScriptObject jsObj)`
`ComboBoxItem(String name)`
`ComboBoxItem(String name, String title)`

Method Summary
`HandlerRegistration`	`addDataArrivedHandler(DataArrivedHandler handler)` Add a dataArrived handler.
`void`	`canEditCriterion()` This method is overridden in comboBoxItem.
`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`.
`ListGridRecord[]`	`filterClientPickListData()` Returns the data to display in the pick list.
`Boolean`	`getAddUnknownValues()` This property controls whether the user can enter a value that is not present in the set of options for this 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 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.
`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.
`Boolean`	`getCompleteOnTab()` If true, when the pickList is showing, the user can select the current value by hitting the `Tab` key.
`Criterion`	`getCriterion()` Returns criterion derived from the current value of this item.
`Boolean`	`getDefaultToFirstOption()` Select the first option as the default value for this ComboBoxItem.
`Boolean`	`getDefaultValue()` Static default value for this ComboBoxItem.
`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`.
`String`	`getEnteredValue()` Returns the raw text value typed into this form field, which can differ from `FormItem.getValue` in various cases - for example: for items that constrain the value range, such as a `DateItem` with `enforceDate`:true, or a `ComboBoxItem` with `addUnknownValues`:false for items with a defined valueMap or edit value formatter and parser functions which converts display value to data value while the item has focus if `changeOnKeypress` is false
`Integer`	`getFetchDelay()` For a ComboBox or other pickList that accepts user-entered criteria, how many millseconds to wait after the last user keystroke before fetching data from the server.
`Boolean`	`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`.
`String[]`	`getFilterFields()` As the user types into this item's textBox, a comboBoxItem will show the pick-list of options, and filter the set of results displayed by the current value in the text box.
`Boolean`	`getFilterLocally()` If `filterLocally` is set for this item, and this item is showing options from a dataSource, fetch the entire set of options from the server, and use these values to map the item value to the appropriate display value.
`Boolean`	`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 `ComboBoxItem.getPickListFilterCriteria`.
`Boolean`	`getGenerateExactMatchCriteria()` When a comboBoxItem is used to generate search criteria in a SearchForm this property governs whether, if the user explicitly chose an option from the pickList, we explicitly generate criteria that will search for an exact match against the chosen value.
`Boolean`	`getHideEmptyPickList()` If this pickList contains no options, should it be hidden? If unset, default behavior is to allow the empty pickList to show if it is databound.
`DataSource`	`getOptionDataSource()`
`String`	`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 ComboBoxItem`	`getOrCreateRef(JavaScriptObject jsObj)`
`String`	`getPendingTextBoxStyle()` Optional "pending" style for this item's text box.
`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.
`String`	`getPickerIconSrc()` Src for the picker icon.
`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.
`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).
`Boolean`	`getShowAllOptions()` If true, even non-matching options will be shown, with configurable `separator rows` in between.
`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`	`getShowPickerIcon()` Show the picker icon for the ComboBox.
`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 combination?
`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.
`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.
`Boolean`	`hasAdvancedCriteria()` Will this item return advancedCriteria if `DynamicForm.getValuesAsCriteria` is called on this item's form? Overridden for ComboBoxItem to return true if `generateExactMatchCriteria` is true - in this case if an exact value is chosen from our set of options (always the case if `addUnkownValues` is false), we will use advancedCriteria to ensure the generated search criteria exactly matches the chosen value for this item.
`void`	`setAddUnknownValues(Boolean addUnknownValues)` This property controls whether the user can enter a value that is not present in the set of options for this 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 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`	`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`	`setCompleteOnTab(Boolean completeOnTab)` If true, when the pickList is showing, the user can select the current value by hitting the `Tab` key.
`void`	`setCriterion()` Overridden to support editing criterion against the display field or value field when `addUnknownValues` is true.
`void`	`setDefaultToFirstOption(Boolean defaultToFirstOption)` Select the first option as the default value for this ComboBoxItem.
`void`	`setDefaultValue(Boolean defaultValue)` Static default value for this ComboBoxItem.
`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`	`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`	`setFilterFields(String... filterFields)` As the user types into this item's textBox, a comboBoxItem will show the pick-list of options, and filter the set of results displayed by the current value in the text box.
`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`	`setGenerateExactMatchCriteria(Boolean generateExactMatchCriteria)` When a comboBoxItem is used to generate search criteria in a SearchForm this property governs whether, if the user explicitly chose an option from the pickList, we explicitly generate criteria that will search for an exact match against the chosen value.
`void`	`setHideEmptyPickList(Boolean hideEmptyPickList)` If this pickList contains no options, should it be hidden? If unset, default behavior is to allow the empty pickList to show if it is databound.
`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`	`setPendingTextBoxStyle(String pendingTextBoxStyle)` Optional "pending" style for this item's text box.
`void`	`setPickerIconHeight(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(String pickerIconSrc)` Src for the picker icon.
`void`	`setPickListBaseStyle(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(DSRequest optionFilterContext)`
`void`	`setPickListFields(ListGridField... pickListFields)`
`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`	`setPickListWidth(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(Boolean showAllOptions)` If true, even non-matching options will be shown, with configurable `separator rows` in between.
`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`	`setShowPickerIcon(Boolean showPickerIcon)` Show the picker icon for the ComboBox.
`void`	`setShowPickListOnKeypress(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 combination?
`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`	`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.
`Boolean`	`shouldGenerateExactMatchCriteria()` When a comboBoxItem is used to generate search criteria in a SearchForm, if the user explicitly chose an option from the pickList, should the criterion generated by `ComboBoxItem.getCriterion` enforce a search for an exact match against the chosen value?

Methods inherited from class com.smartgwt.client.widgets.form.fields.TextItem
deselectValue, deselectValue, getChangeOnKeypress, getCharacterCasing, getFormatOnFocusChange, getHeight, getHint, getKeyPressFilter, getLength, getMask, getMaskOverwriteMode, getMaskPadChar, getMaskPromptChar, getMaskSaveLiterals, getPrintFullText, getSelectionRange, getSelectOnFocus, getTextBoxStyle, getWidth, selectValue, setChangeOnKeypress, setCharacterCasing, setFormatOnFocusChange, setHeight, setKeyPressFilter, setLength, setMask, setMaskOverwriteMode, setMaskPadChar, setMaskPromptChar, setMaskSaveLiterals, setPrintFullText, setSelectionRange, setSelectOnFocus, setTextBoxStyle, setWidth

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

deselectValue, deselectValue, getChangeOnKeypress, getCharacterCasing, getFormatOnFocusChange, getHeight, getHint, getKeyPressFilter, getLength, getMask, getMaskOverwriteMode, getMaskPadChar, getMaskPromptChar, getMaskSaveLiterals, getPrintFullText, getSelectionRange, getSelectOnFocus, getTextBoxStyle, getWidth, selectValue, setChangeOnKeypress, setCharacterCasing, setFormatOnFocusChange, setHeight, setKeyPressFilter, setLength, setMask, setMaskOverwriteMode, setMaskPadChar, setMaskPromptChar, setMaskSaveLiterals, setPrintFullText, setSelectionRange, setSelectOnFocus, setTextBoxStyle, setWidth

Methods inherited from class com.smartgwt.client.widgets.form.fields.FormItem
addBlurHandler, addChangedHandler, addChangeHandler, addClickHandler, addDoubleClickHandler, addFocusHandler, addIconClickHandler, addIconKeyPressHandler, addItemHoverHandler, addKeyDownHandler, addKeyPressHandler, addKeyUpHandler, addTitleClickHandler, addTitleDoubleClickHandler, addTitleHoverHandler, blurItem, canEditCriterion, clearValue, disable, enable, focusInItem, getAccessKey, getAlign, getAllowExpressions, getAlwaysFetchMissingValues, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsString, getBrowserSpellCheck, getCanEdit, getCanFocus, getCellHeight, getCellStyle, getConfig, getContainerWidget, getCriteriaField, getCriterion, getDataPath, getDateFormatter, getDefaultIconSrc, getDisabled, getDisplayValue, getDisplayValue, getEditorTypeConfig, getEmptyDisplayValue, getEmptyValueIcon, getEndRow, getErrorIconHeight, getErrorIconSrc, getErrorIconWidth, getErrorMessageWidth, getFetchMissingValues, getFieldName, getForm, getFullDataPath, getGlobalTabIndex, 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, getPickerIconWidth, getPrintTextBoxStyle, getPrintTitleStyle, getPrompt, getRect, getRejectInvalidValueOnChange, getRequired, getRequiredMessage, getRowSpan, getShouldSaveValue, getShowDisabled, getShowErrorIcon, getShowErrorStyle, getShowErrorText, getShowFocused, 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, getWrapTitle, hide, invalidateDisplayValueCache, isCreated, isDisabled, isDrawn, isVisible, redraw, setAccessKey, setAlign, setAllowExpressions, setAlwaysFetchMissingValues, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setBrowserSpellCheck, setCanEdit, setCanFocus, setCellHeight, setCellStyle, setColSpan, setColSpan, setCriteriaField, setCriterion, setDataPath, setDateFormatter, setDefaultIconSrc, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDisabled, setDisplayFormat, setDisplayFormat, setEditorType, setEditorValueFormatter, setEditorValueParser, 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, setPickerIconWidth, setPrintTextBoxStyle, setPrintTitleStyle, setPrompt, setProperty, setProperty, setProperty, setProperty, setProperty, setRedrawOnChange, setRejectInvalidValueOnChange, setRequired, setRequiredMessage, setRowSpan, setShouldSaveValue, setShowDisabled, setShowErrorIcon, setShowErrorStyle, setShowErrorText, setShowFocused, 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, setWrapTitle, shouldFetchMissingValue, show, showPicker, stopHover, updateState, validate

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

addBlurHandler, addChangedHandler, addChangeHandler, addClickHandler, addDoubleClickHandler, addFocusHandler, addIconClickHandler, addIconKeyPressHandler, addItemHoverHandler, addKeyDownHandler, addKeyPressHandler, addKeyUpHandler, addTitleClickHandler, addTitleDoubleClickHandler, addTitleHoverHandler, blurItem, canEditCriterion, clearValue, disable, enable, focusInItem, getAccessKey, getAlign, getAllowExpressions, getAlwaysFetchMissingValues, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsString, getBrowserSpellCheck, getCanEdit, getCanFocus, getCellHeight, getCellStyle, getConfig, getContainerWidget, getCriteriaField, getCriterion, getDataPath, getDateFormatter, getDefaultIconSrc, getDisabled, getDisplayValue, getDisplayValue, getEditorTypeConfig, getEmptyDisplayValue, getEmptyValueIcon, getEndRow, getErrorIconHeight, getErrorIconSrc, getErrorIconWidth, getErrorMessageWidth, getFetchMissingValues, getFieldName, getForm, getFullDataPath, getGlobalTabIndex, 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, getPickerIconWidth, getPrintTextBoxStyle, getPrintTitleStyle, getPrompt, getRect, getRejectInvalidValueOnChange, getRequired, getRequiredMessage, getRowSpan, getShouldSaveValue, getShowDisabled, getShowErrorIcon, getShowErrorStyle, getShowErrorText, getShowFocused, 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, getWrapTitle, hide, invalidateDisplayValueCache, isCreated, isDisabled, isDrawn, isVisible, redraw, setAccessKey, setAlign, setAllowExpressions, setAlwaysFetchMissingValues, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setBrowserSpellCheck, setCanEdit, setCanFocus, setCellHeight, setCellStyle, setColSpan, setColSpan, setCriteriaField, setCriterion, setDataPath, setDateFormatter, setDefaultIconSrc, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDisabled, setDisplayFormat, setDisplayFormat, setEditorType, setEditorValueFormatter, setEditorValueParser, 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, setPickerIconWidth, setPrintTextBoxStyle, setPrintTitleStyle, setPrompt, setProperty, setProperty, setProperty, setProperty, setProperty, setRedrawOnChange, setRejectInvalidValueOnChange, setRequired, setRequiredMessage, setRowSpan, setShouldSaveValue, setShowDisabled, setShowErrorIcon, setShowErrorStyle, setShowErrorText, setShowFocused, 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, setWrapTitle, shouldFetchMissingValue, show, showPicker, 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, 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

ComboBoxItem

public ComboBoxItem()

ComboBoxItem

public ComboBoxItem(JavaScriptObject jsObj)

ComboBoxItem

public ComboBoxItem(String name)

ComboBoxItem

public ComboBoxItem(String name,
                    String title)

Method Detail

getOrCreateRef

public static ComboBoxItem getOrCreateRef(JavaScriptObject jsObj)

setAddUnknownValues

public void setAddUnknownValues(Boolean addUnknownValues)

This property controls whether the user can enter a value that is not present in the set of options for this item.

If set to false, the value the user enters in the text box is essentially used to filter the set of options displayed in the pickList.

In this mode, when focus is taken from the field, if the entered value does not match any entries in the ValueMap or optionDataSource, it will be discarded. Note that in this mode, completeOnTab behavior is automatically enabled so if the user enters a valid partial value such that one or more options is displayed in the pickList, and hits the Tab key, the first matching option will be chosen automatically. In this mode the user may also hit the "Escape" key to discard their edits.

Note also that when addUnknownValues is set to false, the underlying value returned by getValue will not be updated until a value is explicitly chosen. This means any change or changed handlers will not fire directly in response to the user typing in the field - they will fire when the user actually selects a value, or takes focus from the field.

If setting this property to false on a databound ComboBoxItem, data paging should be disabled - this is required since the ComboBoxItem requires all data to be present in order to determine whether an entered value is new. Data Paging can be disabled by modifying the dataFetchMode on the pickListProperties for this item.

If this property is set to true, the user is not limited to entering values present in the set of options for the item. Instead the set of options essentially become a set of suggestions that may be used, or the user can enter an entirely new value.

Parameters:: addUnknownValues - addUnknownValues Default value is true

getAddUnknownValues

public Boolean getAddUnknownValues()

This property controls whether the user can enter a value that is not present in the set of options for this item.

If set to false, the value the user enters in the text box is essentially used to filter the set of options displayed in the pickList.

Returns:: Boolean

setAutoFetchData

public void setAutoFetchData(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 Boolean getAutoFetchData()

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

setCompleteOnTab

public void setCompleteOnTab(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 Boolean getCompleteOnTab()

If true, when the pickList is showing, the user can select the current value by hitting the Tab key.

Returns:: Boolean

setDefaultToFirstOption

public void setDefaultToFirstOption(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 ComboBoxItem.defaultDynamicValue.

Parameters:: defaultToFirstOption - defaultToFirstOption Default value is false

getDefaultToFirstOption

public Boolean getDefaultToFirstOption()

Returns:: Boolean

setDefaultValue

public void setDefaultValue(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 Boolean getDefaultValue()

Static default value for this ComboBoxItem. 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.

Note : This is an advanced setting

Specified by:: setDisplayField in interface PickList
Overrides:: setDisplayField in class FormItem

Parameters:: displayField - displayField Default value is null
See Also:: FormItem.invalidateDisplayValueCache()

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.

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
See Also:: FormItem.invalidateDisplayValueCache()

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

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

setFilterFields

public void setFilterFields(String... filterFields)

As the user types into this item's textBox, a comboBoxItem will show the pick-list of options, and filter the set of results displayed by the current value in the text box. For a databound comboBoxItem, by default the entered value is filtered against the displayField if one is specified, otherwise the valueField.

This attribute allows the developer to explicitly change which fields to filter against, causing the user-entered text to be matched against any of the specified set of fields from the optionDataSource.

This essentially causes ComboBoxItem.getPickListFilterCriteria to return an AdvancedCriteria object representing "field1 starts with value or field2 starts with value or ...". The operator used is controlled by TextMatchStyle as usual, that is, "startsWith" implies the operator "iStartsWith, "substring" implies "iContains" and "exact" implies "iEquals".

The most common use case for this setting would be when a comboBoxItem is showing multiple pickListFields - if the same set of fields is specified as criteriaFields, the user can use the text-box to filter against whichever fields are visible in the pickList.

For finer grained control over comboBoxItem filtering, the setPickListFilterCriteriaFunction may be specified.

Parameters:: filterFields - filterFields Default value is null

getFilterFields

public String[] getFilterFields()

For finer grained control over comboBoxItem filtering, the setPickListFilterCriteriaFunction may be specified.

Returns:: String

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

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

getFilterWithValue

public 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 ComboBoxItem.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
See Also:: getPickListFilterCriteria(), getFilterFields()

setGenerateExactMatchCriteria

public void setGenerateExactMatchCriteria(Boolean generateExactMatchCriteria)

When a comboBoxItem is used to generate search criteria in a SearchForm this property governs whether, if the user explicitly chose an option from the pickList, we explicitly generate criteria that will search for an exact match against the chosen value.

In order to achieve this, when this property is set to true, this item will generate AdvancedCriteria in its ComboBoxItem.getCriterion method.

See ComboBoxItem.shouldGenerateExactMatchCriteria for behavior when this flag is unset.

Note : This is an advanced setting

Parameters:: generateExactMatchCriteria - generateExactMatchCriteria Default value is null

getGenerateExactMatchCriteria

public Boolean getGenerateExactMatchCriteria()

In order to achieve this, when this property is set to true, this item will generate AdvancedCriteria in its ComboBoxItem.getCriterion method.

See ComboBoxItem.shouldGenerateExactMatchCriteria for behavior when this flag is unset.

Returns:: Boolean

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 - optionOperationId 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:: String

setPendingTextBoxStyle

public void setPendingTextBoxStyle(String pendingTextBoxStyle)

Optional "pending" style for this item's text box.

If addUnknownValues is false, when the user modifies the value displayed in the combobox item text box, the underlying data value (as returned from item.getValue()) is not immediately updated - instead the value is used to filter the set of results displayed in the comboBoxItem pickList.

While the comboBoxItem is in this pending state (where the result of getEnteredValue() will not necessarily match the display value for whatever is returned by getValue()), the pendingTextBoxStyle may be applied to the text box for the item.

When the element value is updated to display the actual value for the item (typically due to the user selecting a value from the pickList), the standard textBoxStyle will be reapplied.

May be left unset in which case the standard text box style is always applied. Has no effect if addUnknownValues is true.

Parameters:: pendingTextBoxStyle - pendingTextBoxStyle Default value is null

getPendingTextBoxStyle

public String getPendingTextBoxStyle()

Optional "pending" style for this item's text box.

When the element value is updated to display the actual value for the item (typically due to the user selecting a value from the pickList), the standard textBoxStyle will be reapplied.

May be left unset in which case the standard text box style is always applied. Has no effect if addUnknownValues is true.

Returns:: String

setPickerIconHeight

public void setPickerIconHeight(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 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(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 String getPickerIconSrc()

Src for the picker icon.

Overrides:: getPickerIconSrc in class FormItem

Returns:: String

setShowAllOptions

public void setShowAllOptions(Boolean showAllOptions)

If true, even non-matching options will be shown, with configurable separator rows in between. Not valid for databound pickLists.

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 separator rows in between. Not valid for databound pickLists.

Specified by:: getShowAllOptions in interface PickList

Returns:: Boolean

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

Overrides:: setShowHintInField in class TextItem

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.

Overrides:: getShowHintInField in class TextItem

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

Specified by:: getShowOptionsFromDataSource in interface PickList

Returns:: Boolean
See Also:: Databinding overview and related methods

setShowPickerIcon

public void setShowPickerIcon(Boolean showPickerIcon)

Show the picker icon for the ComboBox.

Note : This is an advanced setting

Overrides:: setShowPickerIcon in class FormItem

Parameters:: showPickerIcon - showPickerIcon Default value is true

getShowPickerIcon

public Boolean getShowPickerIcon()

Show the picker icon for the ComboBox.

Overrides:: getShowPickerIcon in class FormItem

Returns:: Boolean

setShowPickListOnKeypress

public void setShowPickListOnKeypress(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 combination?

Parameters:: showPickListOnKeypress - showPickListOnKeypress Default value is true

getShowPickListOnKeypress

public 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 combination?

Returns:: Boolean

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 ComboBoxItem.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 ComboBoxItem.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 - valueField Default value is null

getValueField

public String getValueField()

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

Returns:: String

canEditCriterion

public void canEditCriterion()

This method is overridden in comboBoxItem. When addUnknownValues is true, comboBoxItems allow the user to edit substring match type criteria applied to the display field (if one is specified).

The user can also edit criteria attempting to match exactly against the item's field name.

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.

getCriterion

public Criterion getCriterion()

Returns criterion derived from the current value of this item.

If addUnknownValues is true for this item, we implement the following behavior.
If the user explicitly selected an item from the pickList, we treat this as an attempt to explicitly match the data value. In this case returned criteria will match the selected (data) value against this item's fieldName.
If the user typed a value into the text field, we treat this as an attempt to do a substring type filter. In this case returned criteria will match the entered text value against the displayField for this item if one is specified.

If addUnknownValues is false we always match the chosen data value against the item's fieldName.

Note that ComboBoxItem.shouldGenerateExactMatchCriteria will be called in the case when a value was explicitly picked from the set of options. If that method returns true, we will return AdvancedCriteria with an operator specified to ensure an exact match occurs.

Overrides:: getCriterion in class FormItem

Returns:: criterion object based on this fields current edited value(s).
See Also:: CriteriaEditing overview and related methods

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.

getEnteredValue

public String getEnteredValue()

Returns the raw text value typed into this form field, which can differ from FormItem.getValue in various cases - for example:

for items that constrain the value range, such as a DateItem with enforceDate:true, or a ComboBoxItem with addUnknownValues:false
for items with a defined valueMap or edit value formatter and parser functions which converts display value to data value
while the item has focus if changeOnKeypress is false

Overrides:: getEnteredValue in class TextItem

Returns:: current entered value

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

hasAdvancedCriteria

public Boolean hasAdvancedCriteria()

Will this item return advancedCriteria if DynamicForm.getValuesAsCriteria is called on this item's form? Overridden for ComboBoxItem to return true if generateExactMatchCriteria is true - in this case if an exact value is chosen from our set of options (always the case if addUnkownValues is false), we will use advancedCriteria to ensure the generated search criteria exactly matches the chosen value for this item.

Note that AdvancedCriteria are not supported by all dataSources. When a form is bound to a dataSource, we therefore default generateExactMatchCriteria to false unless the dataSource is known to support AdvancedCriteria.

As with formItem.hasAdvancedCriteria() this will also return true if a Operator was explicitly specified for this item

Overrides:: hasAdvancedCriteria in class FormItem

Returns:: true if the result of getCriterion() will be an AdvancedCriteria object.
See Also:: CriteriaEditing overview and related methods

setCriterion

public void setCriterion()

Overridden to support editing criterion against the display field or value field when addUnknownValues is true.

shouldGenerateExactMatchCriteria

public Boolean shouldGenerateExactMatchCriteria()

When a comboBoxItem is used to generate search criteria in a SearchForm, if the user explicitly chose an option from the pickList, should the criterion generated by ComboBoxItem.getCriterion enforce a search for an exact match against the chosen value?

In order to achieve this, when this property is set to true, this item will generate AdvancedCriteria in its ComboBoxItem.getCriterion method.

Default implementation will return generateExactMatchCriteria if specified, otherwise true if the DataSource for this item supports advanced criteria, false if it does not.

Returns:: should getCriterion() generate exact-match search criteria when a value was explicitly chosen from this item's set of options?

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 criteria via an override to this method the read-only property 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 - 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

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

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

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

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(DSRequest optionFilterContext)

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

Specified by:: getFetchDelay in interface PickList

Returns:: the fetch delay

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 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')}.

Parameters:: sortField - sortField Default value is null

getSortField

public String getSortField()

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

Returns:: String

setSortField

public void setSortField(Integer sortField)

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

Parameters:: sortField - sortField Default value is null

getSortFieldAsInt

public Integer getSortFieldAsInt()

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

Returns:: Integer

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 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:: dataSource - optionDataSource Default value is null

getOptionDataSource

public DataSource getOptionDataSource()

Specified by:: getOptionDataSource in interface PickList

setSeparatorRows

public void setSeparatorRows(ListGridRecord[] separatorRows)

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

Not valid for optionDataSource.

Specified by:: setSeparatorRows in interface PickList

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)

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

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.

Overrides:: getSelectedRecord in class FormItem

Returns:: the selected record or null

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 ComboBox.
Static criteria, specified via pickListCriteria, will always be included in addition to criteria returned by this method.
If you are implementing your own criteria via this API, use getFilterWithValue() to determine whether the ComboBox would ordinarily ignore the typed-in value for filtering (IE whether the filter was initialized by the user typing a partial value, or by them clicking the icon to request a complete pickList). Note that in addition to cases where the user explicitly shows the pickList, filterWithValue will also be false during a call to ComboBoxItem.fetchData() on a databound comboBox.

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.

Overrides:: getValueAsString in class TextItem

Returns:: value of this element

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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

ComboBoxItem

ComboBoxItem

ComboBoxItem

ComboBoxItem

getOrCreateRef

setAddUnknownValues

getAddUnknownValues

setAutoFetchData

getAutoFetchData

setCachePickListResults

getCachePickListResults

setCompleteOnTab

getCompleteOnTab

setDefaultToFirstOption

getDefaultToFirstOption

setDefaultValue

getDefaultValue

setDisplayField

getDisplayField

setFetchDisplayedFieldsOnly

getFetchDisplayedFieldsOnly

setFilterFields

getFilterFields

setFilterLocally

getFilterLocally

getFilterWithValue

setGenerateExactMatchCriteria

getGenerateExactMatchCriteria

setOptionOperationId

getOptionOperationId

setPendingTextBoxStyle

getPendingTextBoxStyle

setPickerIconHeight

getPickerIconHeight

setPickerIconSrc

getPickerIconSrc

setShowAllOptions

getShowAllOptions

setShowHintInField

getShowHintInField

setShowOptionsFromDataSource

getShowOptionsFromDataSource

setShowPickerIcon

getShowPickerIcon

setShowPickListOnKeypress

getShowPickListOnKeypress

setTextMatchStyle

getTextMatchStyle

setValueField

getValueField

canEditCriterion

addDataArrivedHandler

defaultDynamicValue

getCriterion

getDisplayFieldName

getEnteredValue

getValueFieldName

hasAdvancedCriteria

setCriterion

shouldGenerateExactMatchCriteria

getPickListFilterCriteria

setPickListHeight

getPickListHeight

setEmptyPickListHeight

getEmptyPickListHeight

setEmptyPickListMessage

getEmptyPickListMessage

setHideEmptyPickList

getHideEmptyPickList

setPickListWidth

getPickListWidth

setPickListBaseStyle

getPickListBaseStyle

setAnimatePickList

getAnimatePickList

setAnimationTime

getAnimationTime

setPickListHeaderHeight

getPickListHeaderHeight

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