public class ComboBoxItem extends TextItem implements PickList, HasDataArrivedHandlers
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:
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.addUnknownValues
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.
ComboBoxItem does not provide built-in support for multiple selection. For a Combobox that does provide such a
multiple-select feature use MultiComboBoxItem
.
FormItem.CustomStateGetter, FormItem.StateCustomizer
configOnly, scClassName, warnOnEditorTypeConversion, warnOnEditorTypeConversionDefault
id
factoryCreated, factoryProperties
Constructor and Description |
---|
ComboBoxItem() |
ComboBoxItem(com.google.gwt.core.client.JavaScriptObject jsObj) |
ComboBoxItem(java.lang.String name) |
ComboBoxItem(java.lang.String name,
java.lang.String title) |
Modifier and Type | Method and Description |
---|---|
com.google.gwt.event.shared.HandlerRegistration |
addDataArrivedHandler(DataArrivedHandler handler)
Add a dataArrived handler.
|
static void |
changeAutoChildDefaults(java.lang.String autoChildName,
Canvas defaults)
Changes the defaults for Canvas AutoChildren named
autoChildName . |
static void |
changeAutoChildDefaults(java.lang.String autoChildName,
FormItem defaults)
Changes the defaults for FormItem AutoChildren named
autoChildName . |
static void |
changePickerIconDefaults(FormItemIcon defaults) |
java.lang.Object |
defaultDynamicValue(FormItem item,
DynamicForm form,
java.util.Map values)
Expression evaluated to determine the
defaultValue when no value is provided for this item. |
void |
fetchData()
Only applies to databound items (see PickList.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 PickList.pickListCriteria. |
void |
fetchData(DSCallback callback) |
void |
fetchData(DSCallback callback,
DSRequest requestProperties)
Only applies to databound items (see PickList.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 PickList.pickListCriteria. |
ListGridRecord[] |
filterClientPickListData()
Returns the data to display in the pick list.
|
java.lang.Boolean |
getAddUnknownValues()
This property controls whether the user can enter a value that is not present in the set of options for this item.
|
java.lang.Boolean |
getAllowEmptyValue()
If
addUnknownValues is
false , this property determines whether the user can clear the comboBoxItem value, or whether they are
constrained to choosing one of the available options (in which case clearing the text box will simply revert to the last
picked value when the user leaves the field). |
java.lang.Boolean |
getAllowExpressions()
The standard
FormItem.allowExpressions
behavior is always disabled for ComboBoxItem. |
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.String |
getAutoOpenTree()
When this item is showing a tree-based picker, which nodes should be opened automatically.
|
boolean |
getCachePickListResults()
For databound pickLists (see PickList.optionDataSource), by default Smart GWT will cache and re-use datasets shown by
different pickLists displayed by different SelectItems in an LRU (least recently used) caching pattern.
|
ListGridRecord[] |
getClientPickListData()
Returns the set of data to be displayed in this item's PickList.
|
java.lang.Boolean |
getCompleteOnEnter()
If true, when the pickList is showing, the user can select the current value by hitting the
Enter key. |
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.String |
getDataSetType()
Whether to show the picker as a flat list, or a collapsible tree.
|
java.lang.Boolean |
getDefaultToFirstOption()
Select the first option as the default value for this ComboBoxItem.
|
java.lang.Object |
getDefaultValue()
Static default value for this ComboBoxItem.
|
java.lang.String |
getDisplayField()
If set, this item will display a value from another field to the user instead of showing the underlying data value for
the
field name . |
java.lang.String |
getDisplayFieldName()
Returns the
displayField for this item. |
java.lang.String |
getEditProxyConstructor()
Default class used to construct the
EditProxy for this component when the component is
first placed into edit mode . |
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 comboboxItem if PickList.hideEmptyPickList is
false . |
java.lang.String |
getEnteredValue()
Returns the raw text value that currently appears in the text 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 Note: if the pickList is being shown in any view other than the default nearOrigin , as is typically the case on a
mobile device, this method will return the value of the pickerSearchField . |
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 |
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 DSRequest.outputs . |
java.lang.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.
|
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. |
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 |
getFormatOnBlur()
With
formatOnBlur enabled, this comboBoxItem will format its value according to the rules described in
FormItem.mapValueToDisplay() as long as the
item does not have focus. |
java.lang.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.
|
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.
|
PickListItemIconPlacement |
getIconPlacement()
For PickList items with
PickListItemIconPlacement set such that the pickList does not
render near-origin, should specified icons be rendered
inline within the formItem itself, or within the pickerNavigationBar . |
SortSpecifier[] |
getInitialSort()
An array of
SortSpecifier objects used to set up the initial sort configuration for
this pickList. |
java.lang.String |
getMask()
Not applicable to a ComboBoxItem.
|
java.lang.Boolean |
getMaskOverwriteMode()
Not applicable to a ComboBoxItem.
|
java.lang.String |
getMaskPadChar()
Not applicable to a ComboBoxItem.
|
java.lang.String |
getMaskPromptChar()
Not applicable to a ComboBoxItem.
|
java.lang.Boolean |
getMaskSaveLiterals()
Not applicable to a ComboBoxItem.
|
java.lang.Integer |
getMinimumSearchLength()
Minimum length in characters before a search is performed.
|
DataSource |
getOptionDataSource()
If set, this FormItem will map stored values to display values as though a
com.smartgwt.client.types.ValueMap
were specified, by fetching records from the specified optionDataSource and extracting the valueField and displayField in loaded records, to derive one valueMap
entry per record loaded from the optionDataSource. |
java.lang.String |
getOptionOperationId()
If this item has a specified
optionDataSource , this attribute may be set to specify an explicit DSRequest.operationId when performing a fetch against the option
dataSource to pick up display value mapping. |
static ComboBoxItem |
getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj) |
java.lang.String |
getPendingTextBoxStyle()
Optional "pending" style for this item's text box.
|
NavigationButton |
getPickerClearButton()
NavigationButton to clear the picker value, created when pickListPlacement indicates that the search
interface takes over the entire panel or screen. |
java.lang.String |
getPickerClearButtonTitle()
The title for the
pickerClearButton . |
NavigationButton |
getPickerExitButton()
NavigationButton to dismiss the picker interface, created when pickListPlacement indicates that the search
interface takes over the entire panel or screen. |
java.lang.String |
getPickerExitButtonTitle()
The title for the
pickerExitButton . |
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()
If
showPickerIcon is true for this item,
this property governs the src of the picker icon
image to be displayed. |
NavigationBar |
getPickerNavigationBar()
NavigationBar created when pickListPlacement indicates that the search
interface takes over the entire panel or screen. |
NavigationButton |
getPickerSaveButton()
"Accept" button for
addUnknownValues:true ComboBoxItems showing the mobile interface. |
java.lang.String |
getPickerSaveButtonTitle()
The title for the
pickerSaveButton . |
TextItem |
getPickerSearchField()
The
pickerSearchField is a separate TextItem created for
search string entry when pickListPlacement indicates that the search interface takes over an entire panel or the entire screen. |
java.lang.String |
getPickerSearchFieldHint()
FormItem.hint for the pickerSearchField . |
DynamicForm |
getPickerSearchForm()
Form that contains the
pickerSearchField . |
java.lang.String |
getPickerSearchOrNewValueFieldHint()
|
ListGrid |
getPickList()
ListGrid-based AutoChild created by the system to display a list of pickable options for this item.
|
java.lang.String |
getPickListBaseStyle()
Base Style for pickList cells.
|
int |
getPickListCellHeight()
Cell Height for this item's pickList.
|
java.lang.String |
getPickListConstructor()
The Class to use when creating a picker of type "list" for a FormItem.
|
Criteria |
getPickListCriteria()
If this item has a databound pickList (for example PickList.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 |
getPickListMaxWidth()
Maximum width for this item's pickList.
|
PanelPlacement |
getPickListPlacement()
Controls where the PickList is placed.
|
Canvas |
getPickListPlacementAsCanvas()
Controls where the PickList is placed.
|
java.lang.String |
getPickListPlacementAsString()
Controls where the PickList is placed.
|
java.lang.Integer |
getPickListWidth()
Default width to show the pickList.
|
java.lang.String |
getPickTreeConstructor()
The Class to use when creating a picker of type "tree" for a FormItem.
|
java.lang.Boolean |
getProgressiveLoading()
Indicates whether or not this ComboBoxItem will load its list of options
progressively . |
java.lang.String |
getRootNodeId()
|
java.lang.Integer |
getRootNodeIdAsInt()
|
java.lang.Boolean |
getSaveOnEnter()
ComboBox items will submit their containing form on enter keypress if
saveOnEnter is true. |
java.lang.String |
getSearchStringTooShortMessage()
Message to display in pick list when
minimumSearchLength characters have not been entered. |
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 |
getSeparateSpecialValues()
If true,
specialValues special values such
as the empty value will be shown in a separate non-scrolling area, in the separateValuesList . |
ListGrid |
getSeparateValuesList()
AutoChild used to show
specialValues . |
java.lang.Boolean |
getShowAllOptions()
If true, even non-matching options will be shown, with configurable
separator rows in between. |
java.lang.Boolean |
getShowHintInField()
If showing a hint for this form item, should it be shown within the field?
|
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. |
java.lang.Boolean |
getShowPickerIcon()
Should we show a special 'picker'
icon for this form item?
Picker icons are customizable via pickerIconProperties . |
java.lang.Boolean |
getShowPickListOnKeypress()
Should the list of options be displayed whenever the user types into the combo-box textArea, or only when the user
clicks on the pick button or uses the explicit
Alt+Arrow Down key combination? |
boolean |
getSingleClickFolderToggle()
When this item is showing a tree-based picker, the default behavior is for folder open-state to be toggled by
double-clicking.
|
java.lang.String |
getSortField()
Specifies one or more fields by which this item should be initially sorted.
|
java.lang.Integer |
getSortFieldAsInt()
Specifies one or more fields by which this item should be initially sorted.
|
java.lang.String[] |
getSortFieldAsStringArray()
Specifies one or more fields by which this item should be initially sorted.
|
TextMatchStyle |
getTextMatchStyle()
When applying filter criteria to pickList data, what type of matching to use.
|
java.lang.Boolean |
getUseClientFiltering()
For
databound items, this property will
be passed to the generated ResultSet data object for the pickList as ResultSet.useClientFiltering . |
java.lang.String |
getValueAsString()
Return the value tracked by this form item.
|
java.lang.String |
getValueField()
If this form item maps data values to display values by retrieving the
FormItem.displayField values from an optionDataSource , this property denotes the the
field to use as the underlying data value in records from the optionDataSource.If not explicitly supplied, the valueField name will be derived as described in FormItem.getValueFieldName() . |
java.lang.String |
getValueFieldName()
Getter method to retrieve the
FormItem.valueField
for this item. |
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. |
java.lang.Boolean |
hasAdvancedCriteria()
Will this item return advancedCriteria if
DynamicForm.getValuesAsCriteria() is called on this item's form? |
ComboBoxItem |
setAddUnknownValues(java.lang.Boolean addUnknownValues)
This property controls whether the user can enter a value that is not present in the set of options for this item.
|
ComboBoxItem |
setAllowEmptyValue(java.lang.Boolean allowEmptyValue)
If
addUnknownValues is
false , this property determines whether the user can clear the comboBoxItem value, or whether they are
constrained to choosing one of the available options (in which case clearing the text box will simply revert to the last
picked value when the user leaves the field). |
ComboBoxItem |
setAllowExpressions(java.lang.Boolean allowExpressions)
The standard
FormItem.allowExpressions
behavior is always disabled for ComboBoxItem. |
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
|
ComboBoxItem |
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. |
ComboBoxItem |
setAutoOpenTree(java.lang.String autoOpenTree)
When this item is showing a tree-based picker, which nodes should be opened automatically.
|
ComboBoxItem |
setCachePickListResults(boolean cachePickListResults)
For databound pickLists (see PickList.optionDataSource), by default Smart GWT will cache and re-use datasets shown by
different pickLists displayed by different SelectItems in an LRU (least recently used) caching pattern.
|
void |
setCanEditCriterionPredicate(FormItemCanEditCriterionPredicate predicate)
The default
canEditCriterion() predicate is overridden in comboBoxItem. |
ComboBoxItem |
setCompleteOnEnter(java.lang.Boolean completeOnEnter)
If true, when the pickList is showing, the user can select the current value by hitting the
Enter key. |
ComboBoxItem |
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 |
setCriterionGetter(FormItemCriterionGetter getter)
The default
getCriterion() implementation returns criterion derived from the current value of this item. |
void |
setCriterionSetter(FormItemCriterionSetter setter)
The default
setCriterion() implementation is overridden to support editing criterion against the display field
or value field when addUnknownValues is true. |
ComboBoxItem |
setDataSetType(java.lang.String dataSetType)
Whether to show the picker as a flat list, or a collapsible tree.
|
static void |
setDefaultProperties(ComboBoxItem comboBoxItemProperties)
Class level method to set the default properties of this class.
|
ComboBoxItem |
setDefaultToFirstOption(java.lang.Boolean defaultToFirstOption)
Select the first option as the default value for this ComboBoxItem.
|
ComboBoxItem |
setDisplayField(java.lang.String displayField)
If set, this item will display a value from another field to the user instead of showing the underlying data value for
the
field name . |
ComboBoxItem |
setEditProxyConstructor(java.lang.String editProxyConstructor)
Default class used to construct the
EditProxy for this component when the component is
first placed into edit mode . |
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 . |
ComboBoxItem |
setEmptyPickListMessage(java.lang.String emptyPickListMessage)
Empty message to display in the comboboxItem if PickList.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.
|
ComboBoxItem |
setFetchDisplayedFieldsOnly(java.lang.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 DSRequest.outputs . |
ComboBoxItem |
setFilterFields(java.lang.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.
|
ComboBoxItem |
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. |
ComboBoxItem |
setFormatOnBlur(java.lang.Boolean formatOnBlur)
With
formatOnBlur enabled, this comboBoxItem will format its value according to the rules described in
FormItem.mapValueToDisplay() as long as the
item does not have focus. |
ComboBoxItem |
setGenerateExactMatchCriteria(java.lang.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(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.
|
ComboBoxItem |
setIconPlacement(PickListItemIconPlacement iconPlacement)
For PickList items with
PickListItemIconPlacement set such that the pickList does not
render near-origin, should specified icons be rendered
inline within the formItem itself, or within the pickerNavigationBar . |
ComboBoxItem |
setInitialSort(SortSpecifier... initialSort)
An array of
SortSpecifier objects used to set up the initial sort configuration for
this pickList. |
ComboBoxItem |
setMask(java.lang.String mask)
Not applicable to a ComboBoxItem.
|
ComboBoxItem |
setMaskOverwriteMode(java.lang.Boolean maskOverwriteMode)
Not applicable to a ComboBoxItem.
|
ComboBoxItem |
setMaskPadChar(java.lang.String maskPadChar)
Not applicable to a ComboBoxItem.
|
ComboBoxItem |
setMaskPromptChar(java.lang.String maskPromptChar)
Not applicable to a ComboBoxItem.
|
ComboBoxItem |
setMaskSaveLiterals(java.lang.Boolean maskSaveLiterals)
Not applicable to a ComboBoxItem.
|
ComboBoxItem |
setMinimumSearchLength(java.lang.Integer minimumSearchLength)
Minimum length in characters before a search is performed.
|
ComboBoxItem |
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 |
ComboBoxItem |
setOptionOperationId(java.lang.String optionOperationId)
If this item has a specified
optionDataSource , this attribute may be set to specify an explicit DSRequest.operationId when performing a fetch against the option
dataSource to pick up display value mapping. |
ComboBoxItem |
setPendingTextBoxStyle(java.lang.String pendingTextBoxStyle)
Optional "pending" style for this item's text box.
|
ComboBoxItem |
setPickerClearButtonTitle(java.lang.String pickerClearButtonTitle)
The title for the
pickerClearButton . |
ComboBoxItem |
setPickerExitButtonTitle(java.lang.String pickerExitButtonTitle)
The title for the
pickerExitButton . |
ComboBoxItem |
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.
|
ComboBoxItem |
setPickerIconSrc(java.lang.String pickerIconSrc)
If
showPickerIcon is true for this item,
this property governs the src of the picker icon
image to be displayed. |
ComboBoxItem |
setPickerSaveButtonTitle(java.lang.String pickerSaveButtonTitle)
The title for the
pickerSaveButton . |
ComboBoxItem |
setPickerSearchFieldHint(java.lang.String pickerSearchFieldHint)
FormItem.hint for the pickerSearchField . |
ComboBoxItem |
setPickerSearchOrNewValueFieldHint(java.lang.String pickerSearchOrNewValueFieldHint)
|
void |
setPickListBaseStyle(java.lang.String pickListBaseStyle)
Base Style for pickList cells.
|
void |
setPickListCellHeight(int pickListCellHeight)
Cell Height for this item's pickList.
|
ComboBoxItem |
setPickListConstructor(java.lang.String pickListConstructor)
The Class to use when creating a picker of type "list" for a FormItem.
|
ComboBoxItem |
setPickListCriteria(Criteria pickListCriteria)
If this item has a databound pickList (for example PickList.optionDataSource is set), this property can be used to
provide static filter criteria when retrieving the data for the pickList.
|
void |
setPickListCriteria(DSRequest optionFilterContext) |
ComboBoxItem |
setPickListFields(ListGridField... pickListFields)
This property allows the developer to specify which field[s] will be displayed in the drop down list of options.
|
void |
setPickListFilterCriteriaFunction(FilterCriteriaFunction filterCriteriaFunction)
Deprecated.
|
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 |
setPickListMaxWidth(java.lang.Integer pickListMaxWidth)
Maximum width for this item's pickList.
|
ComboBoxItem |
setPickListPlacement(Canvas pickListPlacement)
Controls where the PickList is placed.
|
ComboBoxItem |
setPickListPlacement(PanelPlacement pickListPlacement)
Controls where the PickList is placed.
|
ComboBoxItem |
setPickListPlacement(java.lang.String pickListPlacement)
Controls where the PickList is placed.
|
void |
setPickListProperties(ListGrid pickListProperties)
Allows developers to designate a
PickListMenu
as a template containing arbitrary properties to apply to the pickList that will be
created for this FormItem. |
void |
setPickListSort(SortSpecifier[] sortSpecifiers)
This method sorts the pickList on one or more fields, creating the underlying JS object
if needed.
|
void |
setPickListWidth(java.lang.Integer pickListWidth)
Default width to show the pickList.
|
ComboBoxItem |
setPickTreeConstructor(java.lang.String pickTreeConstructor)
The Class to use when creating a picker of type "tree" for a FormItem.
|
ComboBoxItem |
setProgressiveLoading(java.lang.Boolean progressiveLoading)
Indicates whether or not this ComboBoxItem will load its list of options
progressively . |
ComboBoxItem |
setRootNodeId(java.lang.Integer rootNodeId)
|
ComboBoxItem |
setRootNodeId(java.lang.String rootNodeId)
|
ComboBoxItem |
setSaveOnEnter(java.lang.Boolean saveOnEnter)
ComboBox items will submit their containing form on enter keypress if
saveOnEnter is true. |
ComboBoxItem |
setSearchStringTooShortMessage(java.lang.String searchStringTooShortMessage)
Message to display in pick list when
minimumSearchLength characters have not been entered. |
ComboBoxItem |
setSeparateSpecialValues(java.lang.Boolean separateSpecialValues)
If true,
specialValues special values such
as the empty value will be shown in a separate non-scrolling area, in the separateValuesList . |
ComboBoxItem |
setSeparatorRows(ListGridRecord[] separatorRows)
Array of records to show between matching and non-matching rows in the PickList.
|
ComboBoxItem |
setShowAllOptions(java.lang.Boolean showAllOptions)
If true, even non-matching options will be shown, with configurable
separator rows in between. |
ComboBoxItem |
setShowHintInField(java.lang.Boolean showHintInField)
If showing a hint for this form item, should it be shown within the field?
|
ComboBoxItem |
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. |
ComboBoxItem |
setShowPickerIcon(java.lang.Boolean showPickerIcon)
Should we show a special 'picker'
icon for this form item?
Picker icons are customizable via pickerIconProperties . |
ComboBoxItem |
setShowPickListOnKeypress(java.lang.Boolean showPickListOnKeypress)
Should the list of options be displayed whenever the user types into the combo-box textArea, or only when the user
clicks on the pick button or uses the explicit
Alt+Arrow Down key combination? |
ComboBoxItem |
setSingleClickFolderToggle(boolean singleClickFolderToggle)
When this item is showing a tree-based picker, the default behavior is for folder open-state to be toggled by
double-clicking.
|
void |
setSort(SortSpecifier[] sortSpecifiers)
Deprecated.
in favor of
setPickListSort(SortSpecifier[]) where
full documentation can be read. |
ComboBoxItem |
setSortField(java.lang.Integer sortField)
Specifies one or more fields by which this item should be initially sorted.
|
ComboBoxItem |
setSortField(java.lang.String... sortField)
Specifies one or more fields by which this item should be initially sorted.
|
ComboBoxItem |
setSortField(java.lang.String sortField)
Specifies one or more fields by which this item should be initially sorted.
|
void |
setSpecialValues(java.util.LinkedHashMap valueMap)
Set the specialValues for this item.
|
void |
setSpecialValues(java.lang.String... values)
Set the specialValues for this item.
|
ComboBoxItem |
setTextMatchStyle(TextMatchStyle textMatchStyle)
When applying filter criteria to pickList data, what type of matching to use.
|
ComboBoxItem |
setUseClientFiltering(java.lang.Boolean useClientFiltering)
For
databound items, this property will
be passed to the generated ResultSet data object for the pickList as ResultSet.useClientFiltering . |
ComboBoxItem |
setValueField(java.lang.String valueField)
If this form item maps data values to display values by retrieving the
FormItem.displayField values from an optionDataSource , this property denotes the the
field to use as the underlying data value in records from the optionDataSource.If not explicitly supplied, the valueField name will be derived as described in FormItem.getValueFieldName() . |
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. |
java.lang.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 the
FormItemCriterionGetter 's getCriterion()
method enforce a search for an exact match against the chosen value? |
deselectValue, deselectValue, getBrowserAutoCapitalize, getBrowserAutoCorrect, getBrowserInputType, getChangeOnKeypress, getCharacterCasing, getEnforceLength, getEscapeHTML, getFetchMissingValues, getFormatOnFocusChange, getHint, getKeyPressFilter, getLength, getPrintFullText, getSelectionRange, getSelectOnClick, getSelectOnFocus, getShowInputElement, getSupportsCutPasteEvents, getSuppressBrowserClearIcon, getTextBoxStyle, getUsePlaceholderForHint, pendingStatusChanged, selectValue, setBrowserAutoCapitalize, setBrowserAutoCorrect, setBrowserInputType, setChangeOnKeypress, setCharacterCasing, setDefaultProperties, setEnforceLength, setEscapeHTML, setFetchMissingValues, setFormatOnFocusChange, setKeyPressFilter, setLength, setPastedValueTransformer, setPrintFullText, setSelectionRange, setSelectOnClick, setSelectOnFocus, setShowInputElement, setSupportsCutPasteEvents, setSuppressBrowserClearIcon, setTextBoxStyle, setUsePlaceholderForHint, shouldFetchMissingValue
_getValue, addBlurHandler, addChangedHandler, addChangeHandler, addClickHandler, addDoubleClickHandler, addEditorEnterHandler, addEditorExitHandler, addFocusHandler, addIcon, addIcon, addIconClickHandler, addIconKeyPressHandler, addItemHoverHandler, addKeyDownHandler, addKeyPressHandler, addKeyUpHandler, addPendingStatusChangedHandler, addPickerIconClickHandler, addShowContextMenuHandler, addTitleClickHandler, addTitleDoubleClickHandler, addTitleHoverHandler, addValueHoverHandler, addValueIconClickHandler, applyFormula, asSGWTComponent, blurItem, canEditCriterion, clearErrors, clearValue, disable, disableIcon, enable, enableIcon, error, error, errorIfNotCreated, focusAfterItem, focusInItem, getAccessKey, getAlign, getAlwaysFetchMissingValues, getAlwaysShowControlBox, getApplyAlignToText, getApplyHeightToTextBox, getAriaRole, getAttribute, getAttributeAsBoolean, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsObject, getAttributeAsString, getAutoComplete, getAutoCompleteKeywords, getBrowserSpellCheck, getCanEdit, getCanEditOpaqueValues, getCanFocus, getCanSelectText, getCanTabToIcons, getCanvasAutoChild, getCellHeight, getCellStyle, getClassName, getClipStaticValue, getClipTitle, getConfig, getContainerWidget, getControlStyle, getCriteriaField, getCriterion, getCriterion, getCursorPosition, getCustomState, getDataPath, getDateFormatter, getDecimalPad, getDecimalPrecision, getDefaultIconSrc, getDefaultOperator, getDestroyed, getDisabled, getDisabledHover, getDisableIconsOnReadOnly, getDisplayValue, getDisplayValue, getEditorTypeConfig, getEditPendingCSSText, getEmptyDisplayValue, getEmptyValueIcon, getEndRow, getErrorIconHeight, getErrorIconSrc, getErrorIconWidth, getErrorMessageWidth, getErrors, getExportFormat, getFieldName, getForeignDisplayField, getForm, getFormat, getFormItemAutoChild, getFormula, getFullDataPath, getGlobalTabIndex, getGridColNum, getGridRowNum, getHeight, getHeightAsString, getHidden, getHintStyle, getHoverAlign, getHoverDelay, getHoverFocusKey, getHoverHeight, getHoverHeightAsString, getHoverOpacity, getHoverPersist, getHoverStyle, getHoverVAlign, getHoverWidth, getHoverWidthAsString, getIcon, getIconHeight, getIconHSpace, getIconPageRect, getIconPrompt, getIconRect, getIcons, getIconTabPosition, getIconVAlign, getIconWidth, getID, getImageURLPrefix, getImageURLSuffix, getImplicitSave, getImplicitSaveOnBlur, getInputFormat, getLeft, getLinearColSpan, getLinearColSpanAsString, getLinearEndRow, getLinearEndRowAsString, getLinearStartRow, getLinearStartRowAsString, getLinearWidth, getLinearWidthAsString, getListGrid, getLoadingDisplayValue, getLocateItemBy, getMinHintWidth, getMultiple, getMultipleValueSeparator, getName, getNullOriginalValueText, getOperator, getOptionCriteria, getOptionDataSourceAsString, getOptionFilterContext, getOptionTextMatchStyle, getOriginalValueMessage, getPageLeft, getPageRect, getPageTop, getPaletteDefaults, getPicker, getPickerIcon, getPickerIcon, getPickerIconName, getPickerIconPrompt, getPickerIconProperties, getPickerIconStyle, getPickerIconTabPosition, getPickerIconWidth, getPixelHeight, getPixelWidth, getPrintReadOnlyTextBoxStyle, getPrintTextBoxStyle, getPrintTitleStyle, getPrompt, getReadOnlyCanSelectText, getReadOnlyDisplay, getReadOnlyHover, getReadOnlyTextBoxStyle, getReadOnlyWhen, getRect, getRedrawOnChange, getRejectInvalidValueOnChange, getRequired, getRequiredMessage, getRequiredWhen, getRowSpan, getScClassName, getShouldSaveValue, getShowClippedTitleOnHover, getShowClippedValueOnHover, getShowDeletions, getShowDisabled, getShowDisabledIconsOnFocus, getShowDisabledPickerIconOnFocus, getShowErrorIcon, getShowErrorStyle, getShowErrorText, getShowFocused, getShowFocusedErrorState, getShowFocusedIcons, getShowFocusedPickerIcon, getShowHint, getShowIcons, getShowIconsOnFocus, getShowImageAsURL, getShowOldValueInHover, getShowOver, getShowOverIcons, getShowPending, getShowPickerIconOnFocus, getShowRTL, getShowTitle, getShowValueIconOnly, getStartRow, getStaticHeight, getStopOnError, getStoreDisplayValues, getSuppressValueIcon, getSynchronousValidation, getTabIndex, getTextAlign, getTextFormula, getTimeFormatter, getTitle, getTitleAlign, getTitleColSpan, getTitleOrientation, getTitleStyle, getTitleVAlign, getTooltip, getTop, getType, getUpdateControlOnOver, getUpdatePickerIconOnOver, getUpdateTextBoxOnOver, getUseAdvancedCriteria, getUseDisabledHintStyleForReadOnly, getUseLocalDisplayFieldValue, getValidateOnChange, getValidateOnExit, getValidOperators, getVAlign, getValue, getValueAsFloat, getValueAsInteger, getValueAsLong, getValueAsRecordList, getValueDeselectedCSSText, getValueIconHeight, getValueIconLeftPadding, getValueIconRightPadding, getValueIconSize, getValueIconWidth, getValueMap, getValueMapAsArray, getVisible, getVisibleHeight, getVisibleTitleWidth, getVisibleWhen, getVisibleWidth, getWarnOnEditorTypeConversion, getWarnOnEditorTypeConversionDefault, getWidth, getWidthAsString, getWrapHintText, getWrapTitle, handleWarnOnEditorTypeConversion, hasErrors, hide, hideIcon, invalidateDisplayValueCache, isConfigOnly, isCreated, isCutEvent, isDisabled, isDrawn, isFocused, isInGrid, isPasteEvent, isVisible, linkToInstanceUponCreate, mapDisplayToValue, mapValueToDisplay, mapValueToDisplay, mapValueToDisplay, redraw, redraw, removeIcon, selectedRecordChanged, setAccessKey, setAlign, setAlwaysFetchMissingValues, setAlwaysShowControlBox, setApplyAlignToText, setApplyHeightToTextBox, setAriaRole, setAriaState, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAutoChildConstructor, setAutoChildProperties, setAutoChildProperties, setAutoChildProperties, setAutoChildVisibility, setAutoComplete, setAutoCompleteKeywords, setBrowserSpellCheck, setCanEdit, setCanEditOpaqueValues, setCanFocus, setCanSelectText, setCanTabToIcons, setCellHeight, setCellStyle, setClipStaticValue, setClipTitle, setColSpan, setColSpan, setConfigOnly, setControlStyle, setCriteriaField, setCriterion, setCustomStateGetter, setDataPath, setDateFormatter, setDecimalPad, setDecimalPrecision, setDefaultIconSrc, setDefaultOperator, setDefaultProperties, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDisabled, setDisabledHover, setDisableIconsOnReadOnly, setDisplayFormat, setDisplayFormat, setEditorProperties, setEditorType, setEditorType, setEditorType, setEditorValueFormatter, setEditorValueParser, setEditPendingCSSText, setEmptyDisplayValue, setEmptyValueIcon, setEndRow, setErrorFormatter, setErrorIconHeight, setErrorIconSrc, setErrorIconWidth, setErrorMessageWidth, setErrorOrientation, setErrors, setErrors, setExportFormat, setForeignDisplayField, setFormat, setFormula, setGlobalTabIndex, setHeight, setHeight, setHidden, setHint, setHintStyle, setHoverAlign, setHoverDelay, setHoverFocusKey, setHoverHeight, setHoverHeight, setHoverOpacity, setHoverPersist, setHoverStyle, setHoverVAlign, setHoverWidth, setHoverWidth, setIconDisabled, setIconHeight, setIconHSpace, setIconPrompt, setIcons, setIconShowOnFocus, setIconVAlign, setIconWidth, setID, setImageURLPrefix, setImageURLSuffix, setImplicitSave, setImplicitSaveOnBlur, setInitHandler, setInputFormat, setInputTransformer, setItemHoverFormatter, setItemTitleHoverFormatter, setItemValueHoverFormatter, setJavaScriptObject, setLeft, setLinearColSpan, setLinearColSpan, setLinearEndRow, setLinearEndRow, setLinearStartRow, setLinearStartRow, setLinearWidth, setLinearWidth, setLoadingDisplayValue, setLocateItemBy, setMinHintWidth, setMultiple, setMultipleValueSeparator, setName, setNullOriginalValueText, setNullProperty, setOperator, setOptionCriteria, setOptionDataSource, setOptionFilterContext, setOptionTextMatchStyle, setOriginalValueMessage, setPickerIconName, setPickerIconPrompt, setPickerIconProperties, setPickerIconStyle, setPickerIconWidth, setPrintReadOnlyTextBoxStyle, setPrintTextBoxStyle, setPrintTitleStyle, setPrompt, setProperty, setProperty, setProperty, setProperty, setProperty, setReadOnlyCanSelectText, setReadOnlyDisplay, setReadOnlyHover, setReadOnlyTextBoxStyle, setReadOnlyWhen, setRedrawOnChange, setRejectInvalidValueOnChange, setRequired, setRequiredMessage, setRequiredWhen, setRowSpan, setScClassName, setShouldSaveValue, setShowClippedTitleOnHover, setShowClippedValueOnHover, setShowDeletions, setShowDisabled, setShowDisabledIconsOnFocus, setShowDisabledPickerIconOnFocus, setShowErrorIcon, setShowErrorStyle, setShowErrorText, setShowFocused, setShowFocusedErrorState, setShowFocusedIcons, setShowFocusedPickerIcon, setShowHint, setShowIcons, setShowIconsOnFocus, setShowIfCondition, setShowImageAsURL, setShowOldValueInHover, setShowOver, setShowOverIcons, setShowPending, setShowPickerIconOnFocus, setShowRTL, setShowTitle, setShowValueIconOnly, setStartRow, setStateCustomizer, setStaticHeight, setStopOnError, setStoreDisplayValues, setSuppressValueIcon, setSynchronousValidation, setTabIndex, setTextAlign, setTextFormula, setTimeFormatter, setTitle, setTitleAlign, setTitleColSpan, setTitleHoverFormatter, setTitleOrientation, setTitleStyle, setTitleVAlign, setTooltip, setTop, setType, setUpdateControlOnOver, setUpdatePickerIconOnOver, setUpdateTextBoxOnOver, setUseAdvancedCriteria, setUseDisabledHintStyleForReadOnly, setUseLocalDisplayFieldValue, setValidateOnChange, setValidateOnExit, setValidators, setValidOperators, setVAlign, setValue, setValue, setValue, setValue, setValue, setValue, setValueDeselectedCSSText, setValueFormatter, setValueHoverFormatter, setValueIconHeight, setValueIconLeftPadding, setValueIconMapper, setValueIconRightPadding, setValueIcons, setValueIconSize, setValueIconWidth, setValueMap, setValueMap, setVisible, setVisibleWhen, setWarnOnEditorTypeConversion, setWarnOnEditorTypeConversionDefault, setWidth, setWidth, setWrapHintText, setWrapTitle, shouldApplyHeightToTextBox, shouldSaveOnEnter, shouldStopKeyPressBubbling, show, showIcon, showPicker, stopHover, storeValue, storeValue, updateState, validate, valueClipped
getRef, getRef, internalSetID
applyFactoryProperties, doAddHandler, fireEvent, getAttributeAsDoubleArray, getAttributeAsElement, getAttributeAsIntArray, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsStringArray, getAttributes, getHandlerCount, isFactoryCreated, setAttribute, setAttribute, setAttribute, setAttributeAsJavaObject, setFactoryCreated
public ComboBoxItem()
public ComboBoxItem(com.google.gwt.core.client.JavaScriptObject jsObj)
public ComboBoxItem(java.lang.String name)
public ComboBoxItem(java.lang.String name, java.lang.String title)
public static ComboBoxItem getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)
public static void changeAutoChildDefaults(java.lang.String autoChildName, Canvas defaults)
autoChildName
.autoChildName
- name of an AutoChild to customize the defaults for.defaults
- Canvas defaults to apply. These defaults override any existing properties
without destroying or wiping out non-overridden properties. For usage tips on this
param, see SGWTProperties
.AutoChildUsage
public static void changeAutoChildDefaults(java.lang.String autoChildName, FormItem defaults)
autoChildName
.autoChildName
- name of an AutoChild to customize the defaults for.defaults
- FormItem defaults to apply. These defaults override any existing properties
without destroying or wiping out non-overridden properties. For usage tips on this
param, see SGWTProperties
.AutoChildUsage
public static void changePickerIconDefaults(FormItemIcon defaults)
public ComboBoxItem setAddUnknownValues(java.lang.Boolean addUnknownValues)
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 com.smartgwt.client.types.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 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.
addUnknownValues
- New addUnknownValues value. Default value is trueComboBoxItem
instance, for chaining setter callspublic java.lang.Boolean getAddUnknownValues()
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 com.smartgwt.client.types.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 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.
public ComboBoxItem setAllowEmptyValue(java.lang.Boolean allowEmptyValue)
addUnknownValues
is
false
, this property determines whether the user can clear the comboBoxItem value, or whether they are
constrained to choosing one of the available options (in which case clearing the text box will simply revert to the last
picked value when the user leaves the field). See also specialValues
as a way of providing several
different special values in addition to an empty value, such as "Invalid". Note that setting specialValues
disables the use of allowEmptyValue
- see details of how to have an empty value while using
specialValues
in in the
.specialValues
documentation
allowEmptyValue
- New allowEmptyValue value. Default value is trueComboBoxItem
instance, for chaining setter callspublic java.lang.Boolean getAllowEmptyValue()
addUnknownValues
is
false
, this property determines whether the user can clear the comboBoxItem value, or whether they are
constrained to choosing one of the available options (in which case clearing the text box will simply revert to the last
picked value when the user leaves the field). See also specialValues
as a way of providing several
different special values in addition to an empty value, such as "Invalid". Note that setting specialValues
disables the use of allowEmptyValue
- see details of how to have an empty value while using
specialValues
in in the
.specialValues
documentation
public ComboBoxItem setAllowExpressions(java.lang.Boolean allowExpressions)
FormItem.allowExpressions
behavior is always disabled for ComboBoxItem. The interface is not compatible with the
allowExpressions
feature. A ComboBoxItem normally starts fetching matches as you type, and that mixes very
strangely with the idea of entering expressions like "a..b"
- you will have the ComboBox seemingly
switching back and forth between treating the text as a normal search string vs as a special expression on a
per-keystroke basis.
We recommend a normal TextItem as the correct UI element to supply for users to enter filter expressions.
setAllowExpressions
in class FormItem
allowExpressions
- New allowExpressions value. Default value is nullComboBoxItem
instance, for chaining setter callsAdvancedFilter overview and related methods
public java.lang.Boolean getAllowExpressions()
FormItem.allowExpressions
behavior is always disabled for ComboBoxItem. The interface is not compatible with the
allowExpressions
feature. A ComboBoxItem normally starts fetching matches as you type, and that mixes very
strangely with the idea of entering expressions like "a..b"
- you will have the ComboBox seemingly
switching back and forth between treating the text as a normal search string vs as a special expression on a
per-keystroke basis.
We recommend a normal TextItem as the correct UI element to supply for users to enter filter expressions.
getAllowExpressions
in class FormItem
AdvancedFilter overview and related methods
public ComboBoxItem setAutoFetchData(java.lang.Boolean autoFetchData)
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
autoFetchData
- New autoFetchData value. Default value is falseComboBoxItem
instance, for chaining setter callspublic java.lang.Boolean getAutoFetchData()
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.public ComboBoxItem setAutoOpenTree(java.lang.String autoOpenTree)
loading data on demand
, opens the
top-level node and all of it's direct descendants - otherwise, opens all loaded nodes autoOpenTree
- New autoOpenTree value. Default value is "none"ComboBoxItem
instance, for chaining setter callspublic java.lang.String getAutoOpenTree()
loading data on demand
, opens the
top-level node and all of it's direct descendants - otherwise, opens all loaded nodes public ComboBoxItem setCachePickListResults(boolean cachePickListResults)
Setting this flag to false avoids this caching for situations where it is too aggressive.
Note that this does not control re-use
of data within a single pickList. To control when client-side filtering is used in ComboBoxItem, see useClientFiltering
and filterLocally
.
cachePickListResults
- New cachePickListResults value. Default value is trueComboBoxItem
instance, for chaining setter callspublic boolean getCachePickListResults()
Setting this flag to false avoids this caching for situations where it is too aggressive.
Note that this does not control re-use
of data within a single pickList. To control when client-side filtering is used in ComboBoxItem, see useClientFiltering
and filterLocally
.
public ComboBoxItem setCompleteOnEnter(java.lang.Boolean completeOnEnter)
Enter
key.
If not explicitly set, completeOnEnter will default to false for items embedded in a filtering interface
, true otherwise.
completeOnEnter
- New completeOnEnter value. Default value is nullComboBoxItem
instance, for chaining setter callspublic java.lang.Boolean getCompleteOnEnter()
Enter
key.
If not explicitly set, completeOnEnter will default to false for items embedded in a filtering interface
, true otherwise.
public ComboBoxItem setCompleteOnTab(java.lang.Boolean completeOnTab)
Tab
key.
Note that completeOnTab
is not compatible with formatOnBlur
completeOnTab
- New completeOnTab value. Default value is nullComboBoxItem
instance, for chaining setter callspublic java.lang.Boolean getCompleteOnTab()
Tab
key.
Note that completeOnTab
is not compatible with formatOnBlur
public ComboBoxItem setDataSetType(java.lang.String dataSetType)
The default value, "list", will use an instance of the pickListConstructor as the picker - "tree" will show an instance of pickTreeConstructor.
dataSetType
- New dataSetType value. Default value is "list"ComboBoxItem
instance, for chaining setter callspublic java.lang.String getDataSetType()
The default value, "list", will use an instance of the pickListConstructor as the picker - "tree" will show an instance of pickTreeConstructor.
public ComboBoxItem setDefaultToFirstOption(java.lang.Boolean defaultToFirstOption)
defaultValue
and defaultDynamicValue()
.defaultToFirstOption
- New defaultToFirstOption value. Default value is falseComboBoxItem
instance, for chaining setter callspublic java.lang.Boolean getDefaultToFirstOption()
defaultValue
and defaultDynamicValue()
.public java.lang.Object getDefaultValue()
defaultToFirstOption
instead.public ComboBoxItem setDisplayField(java.lang.String displayField)
field name
. This property is used in two ways:
The item will display the displayField value from the record currently being edited
if FormItem.useLocalDisplayFieldValue
is true, (or if unset and the conditions outlined in the documentation for that
property are met).
If this field has an FormItem.optionDataSource
, this property is used by default to identify which value to use as a display value in
records from this related dataSource. In this usage the specified displayField must be explicitly defined in the
optionDataSource to be used - see getDisplayFieldName()
for more on this behavior.
If not using local display values
, the display value
for this item will be derived by performing a fetch against the option dataSource
to find a record where the
value field
matches this item's value, and
use the displayField
value from that record.
In addition to this, PickList-based form items that
provide a list of possible options such as the SelectItem
or ComboBoxItem
will show the displayField
values to the user by
default, allowing them to choose a new data value (see FormItem.valueField
) from a list of user-friendly
display values.
This essentially allows the specified optionDataSource
to be used as a server based
valueMap
.
If local
display values
are being used and FormItem.storeDisplayValues
is true, selecting a new value will update both the value for this field and the associated
display-field value on the record being edited.
Note: Developers may specify the FormItem.foreignDisplayField
property in
addition to displayField
. This is useful for cases where the display field name in the local dataSource
differs from the display field name in the optionDataSource. See the documentation for DataSourceField.foreignDisplayField
for more on
this.
If a foreignDisplayField is specified, as with just displayField, if local display values
are being used and
FormItem.storeDisplayValues
is true, when
the user chooses a value the associated display-field value on the record being edited will be updated. In this case
it would be set to the foreignDisplayField value from the related record. This means foreignDisplayField is always
expected to be set to the equivalent field in the related dataSources.
Developers looking to display some
other arbitrary field(s) from the related dataSource during editing should consider using custom
PickList.pickListFields instead of setting a foreignDisplayField.
Note that if optionDataSource
is set
and no valid display field is specified, FormItem.getDisplayFieldName()
will return the dataSource title field by default.
If a displayField is specified
for a freeform text based item (such as a ComboBoxItem
), any
user-entered value will be treated as a display value. In this scenario, items will derive the data value for the item
from the first record where the displayField value matches the user-entered value. To avoid ambiguity, developers may
wish to avoid this usage if display values are not unique.
setDisplayField
in interface PickList
setDisplayField
in class FormItem
displayField
- New displayField value. Default value is nullComboBoxItem
instance, for chaining setter callsFormItem.getDisplayFieldName()
,
FormItem.invalidateDisplayValueCache()
,
Databinding overview and related methods
public java.lang.String getDisplayField()
field name
. This property is used in two ways:
The item will display the displayField value from the record currently being edited
if FormItem.useLocalDisplayFieldValue
is true, (or if unset and the conditions outlined in the documentation for that
property are met).
If this field has an FormItem.optionDataSource
, this property is used by default to identify which value to use as a display value in
records from this related dataSource. In this usage the specified displayField must be explicitly defined in the
optionDataSource to be used - see getDisplayFieldName()
for more on this behavior.
If not using local display values
, the display value
for this item will be derived by performing a fetch against the option dataSource
to find a record where the
value field
matches this item's value, and
use the displayField
value from that record.
In addition to this, PickList-based form items that
provide a list of possible options such as the SelectItem
or ComboBoxItem
will show the displayField
values to the user by
default, allowing them to choose a new data value (see FormItem.valueField
) from a list of user-friendly
display values.
This essentially allows the specified optionDataSource
to be used as a server based
valueMap
.
If local
display values
are being used and FormItem.storeDisplayValues
is true, selecting a new value will update both the value for this field and the associated
display-field value on the record being edited.
Note: Developers may specify the FormItem.foreignDisplayField
property in
addition to displayField
. This is useful for cases where the display field name in the local dataSource
differs from the display field name in the optionDataSource. See the documentation for DataSourceField.foreignDisplayField
for more on
this.
If a foreignDisplayField is specified, as with just displayField, if local display values
are being used and
FormItem.storeDisplayValues
is true, when
the user chooses a value the associated display-field value on the record being edited will be updated. In this case
it would be set to the foreignDisplayField value from the related record. This means foreignDisplayField is always
expected to be set to the equivalent field in the related dataSources.
Developers looking to display some
other arbitrary field(s) from the related dataSource during editing should consider using custom
PickList.pickListFields instead of setting a foreignDisplayField.
Note that if optionDataSource
is set
and no valid display field is specified, FormItem.getDisplayFieldName()
will return the dataSource title field by default.
If a displayField is specified
for a freeform text based item (such as a ComboBoxItem
), any
user-entered value will be treated as a display value. In this scenario, items will derive the data value for the item
from the first record where the displayField value matches the user-entered value. To avoid ambiguity, developers may
wish to avoid this usage if display values are not unique.
getDisplayField
in interface PickList
getDisplayField
in class FormItem
displayField
for this item. Behavior varies based on the configuration of this item, as follows:
optionDataSource
and an explicit FormItem.foreignDisplayField
is specified, this will be returned.displayField
is specified it will be returned by
default. If the displayField
was specified on the underlying dataSource field, and no matching field is
present in the optionDataSource
for
the item, we avoid returning the specified displayField value and instead return the title field of the option
DataSource. We do this to avoid confusion for the case where the displayField is intended as a display-field value for
showing another field value within the same record in the underlying dataSource only.FormItem.valueField
for this item is hidden in the
FormItem.optionDataSource
, this method will
return the title field for the optionDataSource
.FormItem.getDisplayFieldName()
,
FormItem.invalidateDisplayValueCache()
,
Databinding overview and related methods
public ComboBoxItem setEditProxyConstructor(java.lang.String editProxyConstructor)
EditProxy
for this component when the component is
first placed into edit mode
.setEditProxyConstructor
in class TextItem
editProxyConstructor
- New editProxyConstructor value. Default value is "SelectItemEditProxy"ComboBoxItem
instance, for chaining setter callsSCClassName
public java.lang.String getEditProxyConstructor()
EditProxy
for this component when the component is
first placed into edit mode
.getEditProxyConstructor
in class TextItem
SCClassName
public ComboBoxItem setEmptyPickListMessage(java.lang.String emptyPickListMessage)
false
.
Note : This is an advanced setting
setEmptyPickListMessage
in interface PickList
emptyPickListMessage
- New emptyPickListMessage value. Default value is "No items to show"ComboBoxItem
instance, for chaining setter callspublic java.lang.String getEmptyPickListMessage()
false
.getEmptyPickListMessage
in interface PickList
public ComboBoxItem setFetchDisplayedFieldsOnly(java.lang.Boolean fetchDisplayedFieldsOnly)
optionDataSource
and this property is true
, the list of fields
used by this pickList will be passed to the datasource as DSRequest.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
fetchDisplayedFieldsOnly
- New fetchDisplayedFieldsOnly value. Default value is nullComboBoxItem
instance, for chaining setter callspublic java.lang.Boolean getFetchDisplayedFieldsOnly()
optionDataSource
and this property is true
, the list of fields
used by this pickList will be passed to the datasource as DSRequest.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.
public ComboBoxItem setFilterFields(java.lang.String... filterFields)
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
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 filterFields
, 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 comboBoxItem.setPickListFilterCriteriaFunction() may be specified.
filterFields
- New filterFields value. Default value is nullComboBoxItem
instance, for chaining setter callsPickList overview and related methods
public java.lang.String[] getFilterFields()
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
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 filterFields
, 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 comboBoxItem.setPickListFilterCriteriaFunction() may be specified.
PickList overview and related methods
public ComboBoxItem setFilterLocally(java.lang.Boolean filterLocally)
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 - when this property is set to false
, filtering will
still be performed on the client if a complete set of data for some criteria has been cached by a fetch, and a
subsequent fetch has more restrictive criteria. To explicitly disable client-side filtering set the useClientFiltering
property to false.
Note : This is an advanced setting
setFilterLocally
in interface PickList
setFilterLocally
in class FormItem
filterLocally
- New filterLocally value. Default value is falseComboBoxItem
instance, for chaining setter callsFormItem.setFilterLocally(java.lang.Boolean)
public java.lang.Boolean getFilterLocally()
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 - when this property is set to false
, filtering will
still be performed on the client if a complete set of data for some criteria has been cached by a fetch, and a
subsequent fetch has more restrictive criteria. To explicitly disable client-side filtering set the useClientFiltering
property to false.
getFilterLocally
in interface PickList
getFilterLocally
in class FormItem
FormItem.getFilterLocally()
public boolean getFilterWithValue()
getPickListFilterCriteria()
. You can check this flag in order to mimic the ComboBoxItem's default behavior if you
provide a custom implementation of getPickListFilterCriteria()
.getPickListFilterCriteria()
,
getFilterFields()
public ComboBoxItem setFormatOnBlur(java.lang.Boolean formatOnBlur)
formatOnBlur
enabled, this comboBoxItem will format its value according to the rules described in
FormItem.mapValueToDisplay()
as long as the
item does not have focus. Once the user puts focus into the item the formatter will be removed. This provides a simple
way for developers to show a nicely formatted display value in a freeform text field, without the need for an explicit
FormItem.formatEditorValue()
and FormItem.parseEditorValue()
pair. Note that this
attribute is not compatible with completeOnTab
setFormatOnBlur
in class TextItem
formatOnBlur
- New formatOnBlur value. Default value is falseComboBoxItem
instance, for chaining setter callspublic java.lang.Boolean getFormatOnBlur()
formatOnBlur
enabled, this comboBoxItem will format its value according to the rules described in
FormItem.mapValueToDisplay()
as long as the
item does not have focus. Once the user puts focus into the item the formatter will be removed. This provides a simple
way for developers to show a nicely formatted display value in a freeform text field, without the need for an explicit
FormItem.formatEditorValue()
and FormItem.parseEditorValue()
pair. Note that this
attribute is not compatible with completeOnTab
getFormatOnBlur
in class TextItem
public ComboBoxItem setGenerateExactMatchCriteria(java.lang.Boolean generateExactMatchCriteria)
In order to achieve this, when this property is set to true, this item will generate
AdvancedCriteria
in the default FormItemCriterionGetter
's
getCriterion()
method.
See shouldGenerateExactMatchCriteria()
for behavior when this flag is unset.
Note : This is an advanced setting
generateExactMatchCriteria
- New generateExactMatchCriteria value. Default value is nullComboBoxItem
instance, for chaining setter callspublic java.lang.Boolean getGenerateExactMatchCriteria()
In order to achieve this, when this property is set to true, this item will generate
AdvancedCriteria
in the default FormItemCriterionGetter
's
getCriterion()
method.
See shouldGenerateExactMatchCriteria()
for behavior when this flag is unset.
public ComboBoxItem setIconPlacement(PickListItemIconPlacement iconPlacement)
PickListItemIconPlacement
set such that the pickList does not
render near-origin, should specified icons
be rendered
inline within the formItem itself, or within the pickerNavigationBar
. May be overridden
at the icon level via FormItemIcon.iconPlacement
.
For mobile browsing with limited available screen space, icons rendered in the navigation bar may be easier for the user to interact with.
iconPlacement
- New iconPlacement value. Default value is "both"ComboBoxItem
instance, for chaining setter callspublic PickListItemIconPlacement getIconPlacement()
PickListItemIconPlacement
set such that the pickList does not
render near-origin, should specified icons
be rendered
inline within the formItem itself, or within the pickerNavigationBar
. May be overridden
at the icon level via FormItemIcon.iconPlacement
.
For mobile browsing with limited available screen space, icons rendered in the navigation bar may be easier for the user to interact with.
public ComboBoxItem setInitialSort(SortSpecifier... initialSort)
SortSpecifier
objects used to set up the initial sort configuration for
this pickList. If specified, this will be used instead of any PickList.sortField specified.initialSort
- New initialSort value. Default value is nullComboBoxItem
instance, for chaining setter callspublic SortSpecifier[] getInitialSort()
SortSpecifier
objects used to set up the initial sort configuration for
this pickList. If specified, this will be used instead of any PickList.sortField specified.public ComboBoxItem setMask(java.lang.String mask)
Note : This is an advanced setting
setMask
in class TextItem
mask
- New mask value. Default value is nullComboBoxItem
instance, for chaining setter callsTextItem.setKeyPressFilter(java.lang.String)
,
Text - Masked Examplepublic java.lang.String getMask()
getMask
in class TextItem
TextItem.getKeyPressFilter()
,
Text - Masked Examplepublic ComboBoxItem setMaskOverwriteMode(java.lang.Boolean maskOverwriteMode)
Note : This is an advanced setting
setMaskOverwriteMode
in class TextItem
maskOverwriteMode
- New maskOverwriteMode value. Default value is nullComboBoxItem
instance, for chaining setter callspublic java.lang.Boolean getMaskOverwriteMode()
getMaskOverwriteMode
in class TextItem
public ComboBoxItem setMaskPadChar(java.lang.String maskPadChar)
Note : This is an advanced setting
setMaskPadChar
in class TextItem
maskPadChar
- New maskPadChar value. Default value is " "ComboBoxItem
instance, for chaining setter callspublic java.lang.String getMaskPadChar()
getMaskPadChar
in class TextItem
public ComboBoxItem setMaskPromptChar(java.lang.String maskPromptChar)
Note : This is an advanced setting
setMaskPromptChar
in class TextItem
maskPromptChar
- New maskPromptChar value. Default value is "_"ComboBoxItem
instance, for chaining setter callspublic java.lang.String getMaskPromptChar()
getMaskPromptChar
in class TextItem
public ComboBoxItem setMaskSaveLiterals(java.lang.Boolean maskSaveLiterals)
Note : This is an advanced setting
setMaskSaveLiterals
in class TextItem
maskSaveLiterals
- New maskSaveLiterals value. Default value is nullComboBoxItem
instance, for chaining setter callspublic java.lang.Boolean getMaskSaveLiterals()
getMaskSaveLiterals
in class TextItem
public ComboBoxItem setMinimumSearchLength(java.lang.Integer minimumSearchLength)
searchStringTooShortMessage
.
Note : This is an advanced setting
minimumSearchLength
- New minimumSearchLength value. Default value is nullComboBoxItem
instance, for chaining setter callspublic java.lang.Integer getMinimumSearchLength()
searchStringTooShortMessage
.public ComboBoxItem setOptionOperationId(java.lang.String optionOperationId)
optionDataSource
, this attribute may be set to specify an explicit DSRequest.operationId
when performing a fetch against the option
dataSource to pick up display value mapping.setOptionOperationId
in class FormItem
optionOperationId
- New optionOperationId value. Default value is nullComboBoxItem
instance, for chaining setter callsDatabinding overview and related methods
public java.lang.String getOptionOperationId()
optionDataSource
, this attribute may be set to specify an explicit DSRequest.operationId
when performing a fetch against the option
dataSource to pick up display value mapping.getOptionOperationId
in class FormItem
Databinding overview and related methods
public ComboBoxItem setPendingTextBoxStyle(java.lang.String pendingTextBoxStyle)
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 TextItem.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.
pendingTextBoxStyle
- New pendingTextBoxStyle value. Default value is nullComboBoxItem
instance, for chaining setter callsCSSStyleName
public java.lang.String getPendingTextBoxStyle()
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 TextItem.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.
CSSStyleName
public NavigationButton getPickerClearButton()
NavigationButton
to clear the picker value, created when pickListPlacement
indicates that the search
interface takes over the entire panel or screen. This button will only be shown if addUnknownValues
or allowEmptyValue
is true.
The following
passthroughs
apply:
This component is an AutoChild named "pickerClearButton". For an overview of how to use and
configure AutoChildren, see Using AutoChildren
.
public ComboBoxItem setPickerClearButtonTitle(java.lang.String pickerClearButtonTitle)
pickerClearButton
.pickerClearButtonTitle
- New pickerClearButtonTitle value. Default value is "Clear"ComboBoxItem
instance, for chaining setter callsHTMLString
public java.lang.String getPickerClearButtonTitle()
pickerClearButton
.HTMLString
public NavigationButton getPickerExitButton()
NavigationButton
to dismiss the picker interface, created when pickListPlacement
indicates that the search
interface takes over the entire panel or screen. The following passthroughs
apply:
This component is an AutoChild named "pickerExitButton". For an overview of how to use and
configure AutoChildren, see Using AutoChildren
.
public ComboBoxItem setPickerExitButtonTitle(java.lang.String pickerExitButtonTitle)
pickerExitButton
.pickerExitButtonTitle
- New pickerExitButtonTitle value. Default value is "Cancel"ComboBoxItem
instance, for chaining setter callsHTMLString
public java.lang.String getPickerExitButtonTitle()
pickerExitButton
.HTMLString
public ComboBoxItem setPickerIconHeight(java.lang.Integer pickerIconHeight)
Note : This is an advanced setting
setPickerIconHeight
in class FormItem
pickerIconHeight
- New pickerIconHeight value. Default value is nullComboBoxItem
instance, for chaining setter callspublic java.lang.Integer getPickerIconHeight()
getPickerIconHeight
in class FormItem
public ComboBoxItem setPickerIconSrc(java.lang.String pickerIconSrc)
showPickerIcon
is true for this item,
this property governs the src
of the picker icon
image to be displayed. When spriting
is enabled, this property will not
be used to locate an image, instead, the image is drawn via CSS based on the FormItem.pickerIconStyle
property.
Note : This is an advanced setting
setPickerIconSrc
in class FormItem
pickerIconSrc
- New pickerIconSrc value. Default value is "[SKIN]/DynamicForm/ComboBoxItem_PickButton_icon.gif"ComboBoxItem
instance, for chaining setter callsSCImgURL
public java.lang.String getPickerIconSrc()
showPickerIcon
is true for this item,
this property governs the src
of the picker icon
image to be displayed. When spriting
is enabled, this property will not
be used to locate an image, instead, the image is drawn via CSS based on the FormItem.pickerIconStyle
property.
getPickerIconSrc
in class FormItem
SCImgURL
public NavigationBar getPickerNavigationBar()
NavigationBar
created when pickListPlacement
indicates that the search
interface takes over the entire panel or screen.
This component is an AutoChild named "pickerNavigationBar". For an overview of how to use and
configure AutoChildren, see Using AutoChildren
.
public NavigationButton getPickerSaveButton()
addUnknownValues:true
ComboBoxItems showing the mobile interface. The pickerSaveButton is an automatically created
NavigationButton
autoChild to dismiss the picker interface and store out the value
entered in the pickerSearchField
,
created when pickListPlacement
indicates that the search interface takes over the entire panel or screen.
This button will only be shown when
addUnknownValues
is true. Note that if
a user has entered a partial known value, the pickList will show a filtered list of possible matches. An "Enter"
keypress (or native keyboard "Done" button click on a mobile browser keyboard) will select the first match from the
list. The pickerSaveButton provides a way for users to explicitly use the value as entered instead.
The following
passthroughs
apply:
This component is an AutoChild named "pickerSaveButton". For an overview of how to use and
configure AutoChildren, see Using AutoChildren
.
public ComboBoxItem setPickerSaveButtonTitle(java.lang.String pickerSaveButtonTitle)
pickerSaveButton
.pickerSaveButtonTitle
- New pickerSaveButtonTitle value. Default value is "Accept"ComboBoxItem
instance, for chaining setter callsHTMLString
public java.lang.String getPickerSaveButtonTitle()
pickerSaveButton
.HTMLString
public TextItem getPickerSearchField()
pickerSearchField
is a separate TextItem
created for
search string entry when pickListPlacement
indicates that the search interface takes over an entire panel or the entire screen. The
following passthroughs
apply:
This component is an AutoChild named "pickerSearchField". For an overview of how to use and
configure AutoChildren, see Using AutoChildren
.
public ComboBoxItem setPickerSearchFieldHint(java.lang.String pickerSearchFieldHint)
FormItem.hint
for the pickerSearchField
.pickerSearchFieldHint
- New pickerSearchFieldHint value. Default value is "Search"ComboBoxItem
instance, for chaining setter callsHTMLString
public java.lang.String getPickerSearchFieldHint()
FormItem.hint
for the pickerSearchField
.HTMLString
public DynamicForm getPickerSearchForm()
pickerSearchField
.
This component is an AutoChild named "pickerSearchForm". For an overview of how to use and
configure AutoChildren, see Using AutoChildren
.
public ComboBoxItem setPickerSearchOrNewValueFieldHint(java.lang.String pickerSearchOrNewValueFieldHint)
pickerSearchOrNewValueFieldHint
- New pickerSearchOrNewValueFieldHint value. Default value is "Search or enter new value"ComboBoxItem
instance, for chaining setter callsHTMLString
public java.lang.String getPickerSearchOrNewValueFieldHint()
HTMLString
public ListGrid getPickList()
The pickList is
automatically generated and displayed by the system when necessary. It may be customized via properties such as pickListConstructor
, pickTreeConstructor
, pickListProperties
and more. See the
PickList overview for more information.
Accessing the generated pickList at runtime is an advanced usage. In most cases developers should not modify this generated component directly but should instead use attributes on the formItem to configure it.
This component is an AutoChild named "pickList". For an overview of how to use and
configure AutoChildren, see Using AutoChildren
.
public ComboBoxItem setPickListConstructor(java.lang.String pickListConstructor)
PickListMenu
.pickListConstructor
- New pickListConstructor value. Default value is "PickListMenu"ComboBoxItem
instance, for chaining setter callsSCClassName
,
PickList overview and related methods
public java.lang.String getPickListConstructor()
PickListMenu
.SCClassName
,
PickList overview and related methods
public ComboBoxItem setPickListCriteria(Criteria pickListCriteria)
Note : This is an advanced setting
setPickListCriteria
in interface PickList
pickListCriteria
- New pickListCriteria value. Default value is nullComboBoxItem
instance, for chaining setter callsPickList overview and related methods
public Criteria getPickListCriteria()
getPickListCriteria
in interface PickList
PickList overview and related methods
public ComboBoxItem setPickListFields(ListGridField... pickListFields)
Only applies to databound pickLists (see PickList.optionDataSource, or pickLists with custom data set up via the advanced PickList.getClientPickListData() method.
If this property is unset, we display the PickList.displayField, if specified, otherwise the PickList.valueField.
If there are multiple fields, column headers will be shown for each field, the height of which can be customized via the PickList.pickListHeaderHeight attribute.
Each field to
display should be specified as a ListGridField
object. Note that unlike in
listGrids
, dataSource fields marked as hidden:true
will be hidden by default in pickLists. To override this
behavior, ensure that you specify an explicit value for showIf
.
Note : This is an advanced setting
pickListFields
- New pickListFields value. Default value is nullComboBoxItem
instance, for chaining setter callssetValueField(java.lang.String)
,
PickList overview and related methods
public ComboBoxItem setPickListPlacement(PanelPlacement pickListPlacement)
PanelPlacement
or a
specific widget that should be filled (by specifying an actual Canvas or Canvas.ID
). Default behavior is to "fillPanel"
if isHandset
or isTablet
, to better accommodate the smaller screen real
estate and less precise pointing ability on such devices.
When filling the whole screen, part of the screen or a
specific panel, the expanded interface is created as a standard FormItem picker
, and incorporates a navigation bar
and cancel button
that hides the expanded
interface, as well as a separate search field
.
pickListPlacement
- New pickListPlacement value. Default value is nullComboBoxItem
instance, for chaining setter callspublic PanelPlacement getPickListPlacement()
PanelPlacement
or a
specific widget that should be filled (by specifying an actual Canvas or Canvas.ID
). Default behavior is to "fillPanel"
if isHandset
or isTablet
, to better accommodate the smaller screen real
estate and less precise pointing ability on such devices.
When filling the whole screen, part of the screen or a
specific panel, the expanded interface is created as a standard FormItem picker
, and incorporates a navigation bar
and cancel button
that hides the expanded
interface, as well as a separate search field
.
public ComboBoxItem setPickListPlacement(Canvas pickListPlacement)
PanelPlacement
or a
specific widget that should be filled (by specifying an actual Canvas or Canvas.ID
). Default behavior is to "fillPanel"
if isHandset
or isTablet
, to better accommodate the smaller screen real
estate and less precise pointing ability on such devices.
When filling the whole screen, part of the screen or a
specific panel, the expanded interface is created as a standard FormItem picker
, and incorporates a navigation bar
and cancel button
that hides the expanded
interface, as well as a separate search field
.
pickListPlacement
- New pickListPlacement value. Default value is nullComboBoxItem
instance, for chaining setter callspublic Canvas getPickListPlacementAsCanvas()
PanelPlacement
or a
specific widget that should be filled (by specifying an actual Canvas or Canvas.ID
). Default behavior is to "fillPanel"
if isHandset
or isTablet
, to better accommodate the smaller screen real
estate and less precise pointing ability on such devices.
When filling the whole screen, part of the screen or a
specific panel, the expanded interface is created as a standard FormItem picker
, and incorporates a navigation bar
and cancel button
that hides the expanded
interface, as well as a separate search field
.
public ComboBoxItem setPickListPlacement(java.lang.String pickListPlacement)
PanelPlacement
or a
specific widget that should be filled (by specifying an actual Canvas or Canvas.ID
). Default behavior is to "fillPanel"
if isHandset
or isTablet
, to better accommodate the smaller screen real
estate and less precise pointing ability on such devices.
When filling the whole screen, part of the screen or a
specific panel, the expanded interface is created as a standard FormItem picker
, and incorporates a navigation bar
and cancel button
that hides the expanded
interface, as well as a separate search field
.
pickListPlacement
- New pickListPlacement value. Default value is nullComboBoxItem
instance, for chaining setter callspublic java.lang.String getPickListPlacementAsString()
PanelPlacement
or a
specific widget that should be filled (by specifying an actual Canvas or Canvas.ID
). Default behavior is to "fillPanel"
if isHandset
or isTablet
, to better accommodate the smaller screen real
estate and less precise pointing ability on such devices.
When filling the whole screen, part of the screen or a
specific panel, the expanded interface is created as a standard FormItem picker
, and incorporates a navigation bar
and cancel button
that hides the expanded
interface, as well as a separate search field
.
public ComboBoxItem setPickTreeConstructor(java.lang.String pickTreeConstructor)
pickTreeConstructor
- New pickTreeConstructor value. Default value is "PickTreeMenu"ComboBoxItem
instance, for chaining setter callsSCClassName
public java.lang.String getPickTreeConstructor()
SCClassName
public ComboBoxItem setProgressiveLoading(java.lang.Boolean progressiveLoading)
progressively
. This property is copied onto the underlying
PickList.progressiveLoading
- New progressiveLoading value. Default value is trueComboBoxItem
instance, for chaining setter callsDataSource.setProgressiveLoading(java.lang.Boolean)
,
ProgressiveLoading overview and related methods
public java.lang.Boolean getProgressiveLoading()
progressively
. This property is copied onto the underlying
PickList.DataSource.getProgressiveLoading()
,
ProgressiveLoading overview and related methods
public ComboBoxItem setRootNodeId(java.lang.String rootNodeId)
id
of the record to use as the root
node.rootNodeId
- New rootNodeId value. Default value is nullComboBoxItem
instance, for chaining setter callspublic java.lang.String getRootNodeId()
id
of the record to use as the root
node.public ComboBoxItem setRootNodeId(java.lang.Integer rootNodeId)
id
of the record to use as the root
node.rootNodeId
- New rootNodeId value. Default value is nullComboBoxItem
instance, for chaining setter callspublic java.lang.Integer getRootNodeIdAsInt()
id
of the record to use as the root
node.public ComboBoxItem setSaveOnEnter(java.lang.Boolean saveOnEnter)
saveOnEnter
is true. Setting this property to
false
will disable this behavior. Note that if the drop down list of options (pickList) is visible an
Enter
keypress is used to select a value from the available set of options and will not automatically cause
form submission.
setSaveOnEnter
in class TextItem
saveOnEnter
- New saveOnEnter value. Default value is trueComboBoxItem
instance, for chaining setter callspublic java.lang.Boolean getSaveOnEnter()
saveOnEnter
is true. Setting this property to
false
will disable this behavior. Note that if the drop down list of options (pickList) is visible an
Enter
keypress is used to select a value from the available set of options and will not automatically cause
form submission.
getSaveOnEnter
in class TextItem
public ComboBoxItem setSearchStringTooShortMessage(java.lang.String searchStringTooShortMessage)
minimumSearchLength
characters have not been entered.
Note : This is an advanced setting
searchStringTooShortMessage
- New searchStringTooShortMessage value. Default value is "Enter a longer search string to search"ComboBoxItem
instance, for chaining setter callspublic java.lang.String getSearchStringTooShortMessage()
minimumSearchLength
characters have not been entered.public ComboBoxItem setSeparateSpecialValues(java.lang.Boolean separateSpecialValues)
specialValues
special values such
as the empty value will be shown in a separate non-scrolling area, in the separateValuesList
. Aside from making these
values more easily accessible, showing them in a separate list allows data paging to be used, which is disabled if the
separateValues are shown in the normal drop-down list along with other values.separateSpecialValues
- New separateSpecialValues value. Default value is nullComboBoxItem
instance, for chaining setter callspublic java.lang.Boolean getSeparateSpecialValues()
specialValues
special values such
as the empty value will be shown in a separate non-scrolling area, in the separateValuesList
. Aside from making these
values more easily accessible, showing them in a separate list allows data paging to be used, which is disabled if the
separateValues are shown in the normal drop-down list along with other values.public ListGrid getSeparateValuesList()
specialValues
.
This component is an AutoChild named "separateValuesList". For an overview of how to use and
configure AutoChildren, see Using AutoChildren
.
public ComboBoxItem setSeparatorRows(ListGridRecord[] separatorRows)
Not valid for databound pickLists
.
setSeparatorRows
in interface PickList
separatorRows
- New separatorRows value. Default value is [{isSeparator:true}]ComboBoxItem
instance, for chaining setter callspublic ComboBoxItem setShowAllOptions(java.lang.Boolean showAllOptions)
separator rows
in between. Not valid for databound pickLists
.setShowAllOptions
in interface PickList
showAllOptions
- New showAllOptions value. Default value is nullComboBoxItem
instance, for chaining setter callspublic java.lang.Boolean getShowAllOptions()
separator rows
in between. Not valid for databound pickLists
.getShowAllOptions
in interface PickList
public ComboBoxItem setShowHintInField(java.lang.Boolean showHintInField)
CSS style for the hint is SelectItem.textBoxStyle
with the suffix "Hint"
appended to it.
setShowHintInField
in class TextItem
showHintInField
- New showHintInField value. Default value is nullComboBoxItem
instance, for chaining setter callsFormItem.setHint(java.lang.String)
,
Appearance overview and related methods
public java.lang.Boolean getShowHintInField()
CSS style for the hint is SelectItem.textBoxStyle
with the suffix "Hint"
appended to it.
getShowHintInField
in class TextItem
FormItem.getHint()
,
Appearance overview and related methods
public ComboBoxItem setShowOptionsFromDataSource(java.lang.Boolean showOptionsFromDataSource)
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
setShowOptionsFromDataSource
in interface PickList
showOptionsFromDataSource
- New showOptionsFromDataSource value. Default value is nullComboBoxItem
instance, for chaining setter callsDatabinding overview and related methods
public java.lang.Boolean getShowOptionsFromDataSource()
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
.getShowOptionsFromDataSource
in interface PickList
Databinding overview and related methods
public ComboBoxItem setShowPickerIcon(java.lang.Boolean showPickerIcon)
icon
for this form item?
Picker icons are customizable via pickerIconProperties
. By default they will be rendered inside the form item's "control box"
area. By default clicking the pickerIcon
will call FormItem.showPicker()
.setShowPickerIcon
in class FormItem
showPickerIcon
- New showPickerIcon value. Default value is trueComboBoxItem
instance, for chaining setter callspublic java.lang.Boolean getShowPickerIcon()
icon
for this form item?
Picker icons are customizable via pickerIconProperties
. By default they will be rendered inside the form item's "control box"
area. By default clicking the pickerIcon
will call FormItem.showPicker()
.getShowPickerIcon
in class FormItem
public ComboBoxItem setShowPickListOnKeypress(java.lang.Boolean showPickListOnKeypress)
Alt+Arrow Down
key combination?showPickListOnKeypress
- New showPickListOnKeypress value. Default value is trueComboBoxItem
instance, for chaining setter callspublic java.lang.Boolean getShowPickListOnKeypress()
Alt+Arrow Down
key combination?public ComboBoxItem setSingleClickFolderToggle(boolean singleClickFolderToggle)
Note: when set to true, users can only choose leaf-nodes, since clicking folders would simply toggle them.
singleClickFolderToggle
- New singleClickFolderToggle value. Default value is falseComboBoxItem
instance, for chaining setter callspublic boolean getSingleClickFolderToggle()
Note: when set to true, users can only choose leaf-nodes, since clicking folders would simply toggle them.
public ComboBoxItem setSortField(java.lang.String sortField)
field name
, or an array of field names - but note that, if
multiple fields are supplied, then each will be sorted in the same direction
. For full sorting control, set initialSort to
a list of custom sortSpecifiers
.
This attribute can also be set to the index of a field in the fields array, but note that it will be converted to a string (field name) after initialization.
sortField
- New sortField value. Default value is nullComboBoxItem
instance, for chaining setter callspublic java.lang.String getSortField()
field name
, or an array of field names - but note that, if
multiple fields are supplied, then each will be sorted in the same direction
. For full sorting control, set initialSort to
a list of custom sortSpecifiers
.
This attribute can also be set to the index of a field in the fields array, but note that it will be converted to a string (field name) after initialization.
public ComboBoxItem setSortField(java.lang.String... sortField)
field name
, or an array of field names - but note that, if
multiple fields are supplied, then each will be sorted in the same direction
. For full sorting control, set initialSort to
a list of custom sortSpecifiers
.
This attribute can also be set to the index of a field in the fields array, but note that it will be converted to a string (field name) after initialization.
sortField
- New sortField value. Default value is nullComboBoxItem
instance, for chaining setter callspublic java.lang.String[] getSortFieldAsStringArray()
field name
, or an array of field names - but note that, if
multiple fields are supplied, then each will be sorted in the same direction
. For full sorting control, set initialSort to
a list of custom sortSpecifiers
.
This attribute can also be set to the index of a field in the fields array, but note that it will be converted to a string (field name) after initialization.
public ComboBoxItem setSortField(java.lang.Integer sortField)
field name
, or an array of field names - but note that, if
multiple fields are supplied, then each will be sorted in the same direction
. For full sorting control, set initialSort to
a list of custom sortSpecifiers
.
This attribute can also be set to the index of a field in the fields array, but note that it will be converted to a string (field name) after initialization.
sortField
- New sortField value. Default value is nullComboBoxItem
instance, for chaining setter callspublic java.lang.Integer getSortFieldAsInt()
field name
, or an array of field names - but note that, if
multiple fields are supplied, then each will be sorted in the same direction
. For full sorting control, set initialSort to
a list of custom sortSpecifiers
.
This attribute can also be set to the index of a field in the fields array, but note that it will be converted to a string (field name) after initialization.
public ComboBoxItem setTextMatchStyle(TextMatchStyle textMatchStyle)
For a databound pickList (optionDataSource
set),
textMatchStyle
is sent to the server as DSRequest.textMatchStyle
.
For a non-databound pickList, textMatchStyle
is applied by
filterClientPickListData().
setTextMatchStyle
in interface PickList
textMatchStyle
- New textMatchStyle value. Default value is "startsWith"ComboBoxItem
instance, for chaining setter callspublic TextMatchStyle getTextMatchStyle()
For a databound pickList (optionDataSource
set),
textMatchStyle
is sent to the server as DSRequest.textMatchStyle
.
For a non-databound pickList, textMatchStyle
is applied by
filterClientPickListData().
getTextMatchStyle
in interface PickList
public ComboBoxItem setUseClientFiltering(java.lang.Boolean useClientFiltering)
databound
items, this property will
be passed to the generated ResultSet data object for the pickList as ResultSet.useClientFiltering
. Setting to false will disable
filtering on the client and ensure criteria are always passed to the DataSource directly.
Note : This is an advanced setting
useClientFiltering
- New useClientFiltering value. Default value is nullComboBoxItem
instance, for chaining setter callspublic java.lang.Boolean getUseClientFiltering()
databound
items, this property will
be passed to the generated ResultSet data object for the pickList as ResultSet.useClientFiltering
. Setting to false will disable
filtering on the client and ensure criteria are always passed to the DataSource directly.public ComboBoxItem setValueField(java.lang.String valueField)
FormItem.displayField
values from an optionDataSource
, this property denotes the the
field to use as the underlying data value in records from the optionDataSource.FormItem.getValueFieldName()
.setValueField
in interface PickList
setValueField
in class FormItem
valueField
- New valueField value. Default value is nullComboBoxItem
instance, for chaining setter callsDatabinding overview and related methods
public java.lang.String getValueField()
FormItem.displayField
values from an optionDataSource
, this property denotes the the
field to use as the underlying data value in records from the optionDataSource.FormItem.getValueFieldName()
.getValueField
in interface PickList
getValueField
in class FormItem
FormItem.valueField
for this item. For items with a specified FormItem.optionDataSource
, this determines which field in that dataSource corresponds to the value for this item.
If unset, if a foreignKey relationship
exists between
this field and the optionDataSource, this will be used, otherwise default behavior will return the FormItem.name
of this field. Default value is null
Databinding overview and related methods
public com.google.gwt.event.shared.HandlerRegistration addDataArrivedHandler(DataArrivedHandler handler)
If this item is showing a dataBound pickList, this notification method will be fired when new data arrives from the server.
addDataArrivedHandler
in interface HasDataArrivedHandlers
handler
- the dataArrived handlerHandlerRegistration
used to remove this handlerpublic java.lang.Object defaultDynamicValue(FormItem item, DynamicForm form, java.util.Map values)
defaultValue
when no value is provided for this item. To default to the first option use defaultToFirstOption
instead.item
- the form item itself (also available as "this")form
- the managing DynamicForm instancevalues
- the current set of values for the form as a wholepublic void fetchData()
public void fetchData(DSCallback callback)
fetchData()
public void fetchData(DSCallback callback, DSRequest requestProperties)
callback
- Callback to fire when the fetch completes. Callback will fire with 4 parameters:item
a pointer to the form item dsResponse
the DSResponse
returned by the server data
the raw data returned by the server
dsRequest
the DSRequest
sent to the server requestProperties
- properties to apply to the dsRequest for this fetch.public ListGridRecord[] filterClientPickListData()
The default implementation applies the criteria returned by
PickList.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 PickList.showAllOptions is set, all values are shown, with matching values shown below a separator.
filterClientPickListData
in interface PickList
public ListGridRecord[] getClientPickListData()
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. To customize the data returned after filtering, override
filterClientPickListData()
instead.
As an example, for a formItem with valueField
set to "valueFieldName", the
default implementation would take a valueMap like the following:
valueMap: { value1: "display 1", value2: "display 2" }.. and returning the following set of records:
[ { valueFieldName : "value1" }, { valueFieldName : "value2" } ]Due to the valueMap, these records will appear as a two row pickList displayed as "display 1" and "display 2".
getClientPickListData
in interface PickList
item.valueField
will be picked. Also note that the
fields to be displayed can be customized via item.pickListFields
public java.lang.String getDisplayFieldName()
displayField
for this item. Behavior varies based on the configuration of this item, as follows:
optionDataSource
and an explicit FormItem.foreignDisplayField
is specified, this will be returned.displayField
is specified it will be returned by
default. If the displayField
was specified on the underlying dataSource field, and no matching field is
present in the optionDataSource
for
the item, we avoid returning the specified displayField value and instead return the title field of the option
DataSource. We do this to avoid confusion for the case where the displayField is intended as a display-field value for
showing another field value within the same record in the underlying dataSource only.FormItem.valueField
for this item is hidden in the
FormItem.optionDataSource
, this method will
return the title field for the optionDataSource
.getDisplayFieldName
in interface PickList
getDisplayFieldName
in class FormItem
FieldName
public java.lang.String getEnteredValue()
FormItem.getValue()
in various cases - for example: DateItem
with
enforceDate
:true, or a ComboBoxItem
with addUnknownValues
:falsechangeOnKeypress
is false nearOrigin
, as is typically the case on a
mobile device, this method will return the value of the pickerSearchField
.getEnteredValue
in class TextItem
public java.lang.String getValueFieldName()
FormItem.valueField
for this item. For items with a specified FormItem.optionDataSource
, this determines which field in that dataSource corresponds to the value for this item.
If unset, if a foreignKey relationship
exists between
this field and the optionDataSource, this will be used, otherwise default behavior will return the FormItem.name
of this field.
getValueFieldName
in interface PickList
getValueFieldName
in class FormItem
FormItem.optionDataSource
public java.lang.Boolean hasAdvancedCriteria()
DynamicForm.getValuesAsCriteria()
is called on this item's form? This method is overridden in ComboBoxItem to
return true if shouldGenerateExactMatchCriteria()
returns true, and the user has chosen an exact value from the options in the
pickList. In this case we will use advancedCriteria to ensure the generated search criteria exactly matches the chosen
value for this item.
As with formItem.hasAdvancedCriteria() this will also return true if an Operator
was explicitly specified for this item
See ComboBoxItemCriteria
for a discussion of criterion generated by a ComboBoxItem.
hasAdvancedCriteria
in class FormItem
CriteriaEditing overview and related methods
public java.lang.Boolean shouldGenerateExactMatchCriteria()
FormItemCriterionGetter
's getCriterion()
method 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 the default
FormItemCriterionGetter
's 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.
See
ComboBoxItemCriteria
for a discussion of criterion generated by a ComboBoxItem.
public static void setDefaultProperties(ComboBoxItem comboBoxItemProperties)
Note: This method is intended for setting default attributes only and will affect all instances of the underlying class (including those automatically generated in JavaScript). This method should not be used to apply standard EventHandlers or override methods for a class - use a custom subclass instead. Calling this method after instances have been created can result in undefined behavior, since it bypasses any setters and a class instance may have already examined a particular property and not be expecting any changes through this route.
comboBoxItemProperties
- properties that should be used as new defaults when instances of this class are createdSGWTProperties
protected Criteria getPickListFilterCriteria()
See ComboBoxFiltering
for details on how pickList filter criteria
are calculated by default for a comboBoxItem.
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)
.
public void setSpecialValues(java.lang.String... values)
values
- the special valuespublic void setSpecialValues(java.util.LinkedHashMap valueMap)
valueMap
- the special value mappublic void setPickListHeight(int pickListHeight)
setPickListHeight
in interface PickList
pickListHeight
- pickListHeight Default value is 300public int getPickListHeight()
getPickListHeight
in interface PickList
public void setEmptyPickListHeight(int emptyPickListHeight)
hideEmptyPickList
is false
.setEmptyPickListHeight
in interface PickList
emptyPickListHeight
- emptyPickListHeight Default value is 100public int getEmptyPickListHeight()
hideEmptyPickList
is false
.getEmptyPickListHeight
in interface PickList
public void setHideEmptyPickList(java.lang.Boolean hideEmptyPickList)
setHideEmptyPickList
in interface PickList
hideEmptyPickList
- hideEmptyPickList Default value is nullpublic java.lang.Boolean getHideEmptyPickList()
getHideEmptyPickList
in interface PickList
public void setPickListWidth(java.lang.Integer pickListWidth)
setPickListWidth
in interface PickList
pickListWidth
- pickListWidth Default value is nullpublic java.lang.Integer getPickListWidth()
getPickListWidth
in interface PickList
public void setPickListMaxWidth(java.lang.Integer pickListMaxWidth)
setPickListWidth
the pickList will render wide enough to accomodate them. This property
allows the developer to limit how wide the pickList will render.setPickListMaxWidth
in interface PickList
pickListMaxWidth
- pickListMaxWidth Default value is 400public java.lang.Integer getPickListMaxWidth()
setPickListWidth
the pickList will render wide enough to accomodate them. This property
allows the developer to limit how wide the pickList will render.getPickListMaxWidth
in interface PickList
public void setPickListBaseStyle(java.lang.String pickListBaseStyle)
setPickListBaseStyle
in interface PickList
pickListBaseStyle
- pickListBaseStyle Default value is "pickListCell"public java.lang.String getPickListBaseStyle()
getPickListBaseStyle
in interface PickList
public void setAnimatePickList(java.lang.Boolean animatePickList)
Note : This is an advanced setting
setAnimatePickList
in interface PickList
animatePickList
- animatePickList Default value is nullpublic java.lang.Boolean getAnimatePickList()
getAnimatePickList
in interface PickList
public void setAnimationTime(int animationTime)
Note : This is an advanced setting
setAnimationTime
in interface PickList
animationTime
- animationTime Default value is 200public int getAnimationTime()
getAnimationTime
in interface PickList
public void setPickListHeaderHeight(int pickListHeaderHeight)
setPickListHeaderHeight
in interface PickList
pickListHeaderHeight
- pickListHeaderHeight Default value is 22public int getPickListHeaderHeight()
getPickListHeaderHeight
in interface PickList
public void setPickListCellHeight(int pickListCellHeight)
setPickListCellHeight
in interface PickList
pickListCellHeight
- pickListCellHeight Default value is 16public int getPickListCellHeight()
getPickListCellHeight
in interface PickList
public void setValueIconField(java.lang.String valueIconField)
valueIcons
should show up in for this formItem's pickList.displayField
column if specified, otherwise
the valueField
column.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
setValueIconField
in interface PickList
valueIconField
- valueIconField Default value is nullpublic java.lang.String getValueIconField()
valueIcons
should show up in for this formItem's pickList.displayField
column if specified, otherwise
the valueField
column.displayField
or valueField
will be visible. This property is typically only
required if custom pickListFields
have been specfied for this item.getValueIconField
in interface PickList
public void setPickListCriteria(DSRequest optionFilterContext)
public void setFetchDelay(java.lang.Integer fetchDelay)
PickList
setFetchDelay
in interface PickList
fetchDelay
- the fetch delay. defaults to 200mspublic java.lang.Integer getFetchDelay()
PickList
getFetchDelay
in interface PickList
public ComboBoxItem setOptionDataSource(DataSource dataSource)
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
setOptionDataSource
in interface PickList
setOptionDataSource
in class FormItem
dataSource
- optionDataSource Default value is nullComboBoxItem
instance, for chaining setter callsFormItem.invalidateDisplayValueCache()
,
List - Combo Box Examplepublic DataSource getOptionDataSource()
FormItem
com.smartgwt.client.types.ValueMap
were specified, by fetching records from the specified optionDataSource
and extracting the valueField
and displayField
in loaded records, to derive one valueMap
entry per record loaded from the optionDataSource. With the default setting of fetchMissingValues
, fetches will be initiated
against the optionDataSource any time the FormItem has a non-null value and no corresponding display value is available.
This includes when the form is first initialized, as well as any subsequent calls to setValue()
, such as may happen when DynamicForm.editRecord()
is called. Retrieved values are
automatically cached by the FormItem.
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.
In a databound form, if displayField
is specified for a FormItem and
optionDataSource
is unset, optionDataSource
will default to the form's current DataSource
getOptionDataSource
in interface PickList
getOptionDataSource
in class FormItem
optionDataSource
for this item.
Always uses item.optionDataSource
if specified. Otherwise, if DataSourceField.foreignKey
was specified, uses the target
DataSource. Otherwise, uses the DataSource of this item's form (if one is configured). Default value is null
FormItem.invalidateDisplayValueCache()
,
List - Combo Box Examplepublic ListGridRecord getSelectedRecord()
getSelectedRecord
in class FormItem
public void setPickListFilterCriteriaFunction(FilterCriteriaFunction filterCriteriaFunction)
setPickListFilterCriteriaFunction(FormItemCriteriaFunction)
setPickListFilterCriteriaFunction
in interface PickList
filterCriteriaFunction
- the filter criteria functionpublic void setPickListFilterCriteriaFunction(FormItemCriteriaFunction filterCriteriaFunction)
See ComboBoxFiltering
for details on how pickListCriteria are
calcualted by default for a ComboBoxItem.
public void setPickListProperties(ListGrid pickListProperties)
PickListMenu
as a template containing arbitrary properties to apply to the pickList that will be
created for this FormItem.
Note: Not every PickListMenu / ListGrid property is supported when assigned to a pickList.
Where there is a dedicated API on the form item (such as
PickList.setPickListCellHeight(int)
), we recommend
that be used in favor of setting the equivalent property directly using this API.
PickLists and ListGrid.setShowFilterEditor(boolean)
:
ComboBoxItems
do not support
setting showFilterEditor
to true on pickListProperties.
This combination of settings leads to an ambiguous user experience as the two sets of
filter-criteria (those from the text-box and those from the pickList filter editor) interact
with each other.
Calling setShowFilterEditor
on the PickListMenu passed to SelectItem.setPickListProperties(com.smartgwt.client.widgets.grid.ListGrid)
is a valid way to create a filterable pickList, on a SelectItem, but this setting is not
supported on a SelectItem with multiple set to true
- this combination of settings can cause a selected value to be filtered out of view at which
point further selection changes will discard that value.
In general we recommend the ComboBoxItem class (with
addUnknownValues set as appropriate
)
as a better interface for filtering pickList data.
pickListProperties
- the pick list propertiespublic void setOptionFilterContext(DSRequest dsRequestProperties)
PickList
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
setOptionFilterContext
in interface PickList
dsRequestProperties
- optionFilterContext Default value is nullpublic java.lang.String getValueAsString()
getValueAsString
in class TextItem
public void setCanEditCriterionPredicate(FormItemCanEditCriterionPredicate predicate)
canEditCriterion()
predicate 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.
setCanEditCriterionPredicate
in class FormItem
predicate
- the predicate to determine the form items that can edit the criterion in questionFormItem.setCanEditCriterionPredicate
,
CriteriaEditing overview and related methods
public void setCriterionGetter(FormItemCriterionGetter getter)
getCriterion()
implementation 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.
setCriterionGetter
in class FormItem
getter
- provides a method to get a criterion object based on this field's current edited value(s).FormItem.setCriterionGetter(com.smartgwt.client.widgets.form.FormItemCriterionGetter)
,
CriteriaEditing overview and related methods
public void setCriterionSetter(FormItemCriterionSetter setter)
setCriterion()
implementation is overridden to support editing criterion against the display field
or value field when addUnknownValues
is true.setCriterionSetter
in class FormItem
setter
- provides a method to update this field with the edited criterionpublic void setPickListSort(SortSpecifier[] sortSpecifiers)
'unused fields from the underlying dataSource'
,
if there is one. If multiple fields are sorted, those that are visible show a directional icon and a small
'sort-numeral'
indicating that
field's index in the sort configuration.
See ListGrid.addSort(com.smartgwt.client.data.SortSpecifier)
and com.smartgwt.client.widgets.grid.ListGrid#alterSort
APIs for information on making changes to the current sort configuration.
sortSpecifiers
- Array of SortSpecifier objectspublic void setSort(SortSpecifier[] sortSpecifiers)
setPickListSort(SortSpecifier[])
where
full documentation can be read.sortSpecifiers
- Array of SortSpecifier objects