public class FormItem extends RefDataClass implements HasBlurHandlers, HasChangeHandlers, HasChangedHandlers, HasClickHandlers, HasDoubleClickHandlers, HasEditorEnterHandlers, HasEditorExitHandlers, HasFocusHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasPendingStatusChangedHandlers, HasPickerIconClickHandlers, HasShowContextMenuHandlers, HasTitleClickHandlers, HasTitleDoubleClickHandlers, HasTitleHoverHandlers, HasValueHoverHandlers, HasValueIconClickHandlers
values tracked by the form
. FormItems do not render
themselves, instead, they are provided to a DynamicForm
via DynamicForm.setItems()
See the DynamicForm
documentation for details and sample code.
Modifier and Type | Class and Description |
---|---|
static interface |
FormItem.CustomStateGetter |
static interface |
FormItem.StateCustomizer |
Modifier and Type | Field and Description |
---|---|
protected boolean |
configOnly |
protected java.lang.String |
scClassName |
protected boolean |
warnOnEditorTypeConversion |
protected static boolean |
warnOnEditorTypeConversionDefault |
id
factoryCreated, factoryProperties
Constructor and Description |
---|
FormItem() |
FormItem(com.google.gwt.core.client.JavaScriptObject jsObj) |
FormItem(java.lang.String name) |
Modifier and Type | Method and Description |
---|---|
java.lang.Object |
_getValue() |
com.google.gwt.event.shared.HandlerRegistration |
addBlurHandler(BlurHandler handler)
Add a blur handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addChangedHandler(ChangedHandler handler)
Add a changed handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addChangeHandler(ChangeHandler handler)
Add a change handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addClickHandler(ClickHandler handler)
Add a click handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addDoubleClickHandler(DoubleClickHandler handler)
Add a doubleClick handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addEditorEnterHandler(EditorEnterHandler handler)
Add a editorEnter handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addEditorExitHandler(EditorExitHandler handler)
Add a editorExit handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addFocusHandler(FocusHandler handler)
Add a focus handler.
|
FormItemIcon |
addIcon(FormItemIcon icon)
Adds a
FormItemIcon to this item. |
FormItemIcon |
addIcon(FormItemIcon icon,
int index)
Adds a
FormItemIcon to this item. |
com.google.gwt.event.shared.HandlerRegistration |
addIconClickHandler(IconClickHandler handler)
Add a iconClick handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addIconKeyPressHandler(IconKeyPressHandler handler)
Add a iconKeyPress handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addItemHoverHandler(ItemHoverHandler handler)
Add a itemHover handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addKeyDownHandler(KeyDownHandler handler)
Add a keyDown handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addKeyPressHandler(KeyPressHandler handler)
Add a keyPress handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addKeyUpHandler(KeyUpHandler handler)
Add a keyUp handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addPendingStatusChangedHandler(PendingStatusChangedHandler handler)
Add a pendingStatusChanged handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addPickerIconClickHandler(PickerIconClickHandler handler)
Add a pickerIconClick handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addShowContextMenuHandler(ShowContextMenuHandler handler)
Add a showContextMenu handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addTitleClickHandler(TitleClickHandler handler)
Add a titleClick handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addTitleDoubleClickHandler(TitleDoubleClickHandler handler)
Add a titleDoubleClick handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addTitleHoverHandler(TitleHoverHandler handler)
Add a titleHover handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addValueHoverHandler(ValueHoverHandler handler)
Add a valueHover handler.
|
com.google.gwt.event.shared.HandlerRegistration |
addValueIconClickHandler(ValueIconClickHandler handler)
Add a valueIconClick handler.
|
void |
applyFormula()
Manually sets this FormItem to the result of
formula
or textFormula . |
static <T extends RefDataClass> |
asSGWTComponent(com.google.gwt.core.client.JavaScriptObject jsObj)
Returns the existing SGWT FormItem, or creates and returns one if none exist,
associated with the supplied
JavaScriptObject . |
void |
blurItem()
Takes focus from this form item's focusable element.
|
java.lang.Boolean |
canEditCriterion(Criterion criterion)
Calls the
canEditCriterion()
method of the FormItemCanEditCriterionPredicate
that is registered with this field. |
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) |
void |
clearErrors()
Clear all error messages for this item
|
void |
clearValue()
Clear the value for this form item.
|
void |
disable()
Set this item to be disabled at runtime.
|
void |
disableIcon(java.lang.String icon)
This method will disable some icon in this item's
icons array, if it is currently enabled. |
void |
enable()
Set this item to be enabled at runtime.
|
void |
enableIcon(java.lang.String icon)
This method will enable some icon in this item's
icons
array, if it is currently disabled. |
protected void |
error(java.lang.String message) |
protected void |
error(java.lang.String attribute,
java.lang.String value) |
protected void |
errorIfNotCreated(java.lang.String property) |
void |
focusAfterItem(boolean forward)
Shifts focus to the next focusable element after this item, skipping any elements nested inside the tabbing group for
this item, such as sub-elements, nested canvases in a CanvasItem, or icons.
|
void |
focusInItem()
Move the keyboard focus into this item's focusable element
|
java.lang.String |
getAccessKey()
If specified this governs the HTML accessKey for the item.
|
Alignment |
getAlign()
Alignment of this item in its cell.
|
java.lang.Boolean |
getAllowExpressions()
For a form that produces filter criteria (see
form.getValuesAsCriteria() ), allows the user to type in simple expressions to cause filtering with that operator. |
java.lang.Boolean |
getAlwaysFetchMissingValues()
If this form item has a specified
optionDataSource and fetchMissingValues
is true, when the item value changes, a fetch will be performed against the optionDataSource to retrieve the related
record if displayField is specified and the
new item value is not present in any valueMap explicitly specified on the item. |
java.lang.Boolean |
getAlwaysShowControlBox()
A formItem showing a
pickerIcon will always
write out a "control box" around the text box and picker icon. |
boolean |
getApplyAlignToText()
|
java.lang.Boolean |
getApplyHeightToTextBox()
If
height is specified, should it be applied to the
item's text box element? |
java.lang.String |
getAriaRole()
ARIA role of this formItem.
|
java.lang.String |
getAttribute(java.lang.String attribute)
Returns attribute value as a String
|
java.lang.Boolean |
getAttributeAsBoolean(java.lang.String property)
Returns attribute value set as a Boolean.
|
java.lang.Boolean |
getAttributeAsBoolean(java.lang.String property,
boolean allowNull)
Returns attribute value set as a Boolean.
|
java.util.Date |
getAttributeAsDate(java.lang.String property)
Returns attribute value as a Date.
|
java.lang.Double |
getAttributeAsDouble(java.lang.String property)
Returns attribute as a Double.
|
java.lang.Float |
getAttributeAsFloat(java.lang.String property)
Returns attribute value as a Float.
|
java.lang.Integer |
getAttributeAsInt(java.lang.String property)
Returns attribute value as an Integer.
|
com.google.gwt.core.client.JavaScriptObject |
getAttributeAsJavaScriptObject(java.lang.String property)
Returns attribute value as a JavaScript Object.
|
java.lang.Object |
getAttributeAsObject(java.lang.String property,
com.google.gwt.core.client.JavaScriptObject convertToObject) |
java.lang.String |
getAttributeAsString(java.lang.String property)
Returns attribute value as a String.
|
AutoComplete |
getAutoComplete()
Should this item allow browser auto-completion of its value? Applies only to items based on native HTML form elements
(
TextItem , PasswordItem ,
etc), and will only have a user-visible impact for browsers where native autoComplete behavior is actually supported and
enabled via user settings. |
java.lang.String[] |
getAutoCompleteKeywords()
Set of autocompletion keywords to be used with the native "autocomplete" attribute, in accordance with the HTML5 Autofill
specification.
|
java.lang.String |
getBrowserInputType()
Form item input type - governs which keyboard should be displayed for mobile devices (supported on iPhone / iPad)
|
java.lang.Boolean |
getBrowserSpellCheck()
If this browser supports spell-checking of text editing elements, do we want this enabled for this item? If unset the
property will be inherited from the containing form.
|
java.lang.Boolean |
getCanEdit()
Is this form item editable (canEdit:true) or read-only (canEdit:false)? Setting the form item to non-editable causes it
to render as read-only.
|
java.lang.Boolean |
getCanEditOpaqueValues()
If true, indicates that this FormItem is capable of editing "opaque" values, ie, objects that are more complex than
simple primitive types like numbers, strings and dates.
|
java.lang.Boolean |
getCanFocus()
Is this form item focusable? Setting this property to true on an otherwise non-focusable element such as a
StaticTextItem will cause the item to be included in the page's tab order and
respond to keyboard events. |
boolean |
getCanSelectText()
For items showing a text value, should the user be able to select the text in this item?
|
java.lang.Boolean |
getCanTabToIcons()
Should this item's
icons and picker icon be included in the page's tab order by
default? If not explicitly set, this property will be derived from DynamicForm.canTabToIcons . |
Canvas |
getCanvasAutoChild(java.lang.String autoChildName)
Returns the
Canvas AutoChild named autoChildName if already created. |
java.lang.Integer |
getCellHeight()
If specified, this property will govern the height of the cell in which this form item is rendered.
|
java.lang.String |
getCellStyle()
CSS style applied to the form item as a whole, including the text element, any icons, and any hint text for the item.
|
java.lang.Boolean |
getChangeOnKeypress()
Should this form item fire its
change handler
(and store its value in the form) on every keypress? Set to false to suppress the 'change' handler firing
(and the value stored) on every keypress. |
java.lang.String |
getClassName()
Returns the JavaScript class name.
|
java.lang.Boolean |
getClipStaticValue()
If this item is
read-only and is using readOnlyDisplay ReadOnlyDisplayAppearance.STATIC , should the item value be clipped if it overflows the
specified size of the item? If set, overrides the form-level DynamicForm.clipStaticValue default. |
java.lang.Boolean |
getClipTitle()
If the title for this form item is showing, and is too large for the available space should the title be clipped?
|
com.google.gwt.core.client.JavaScriptObject |
getConfig()
Returns the FormItem's config object suitable for use in API's that set the editorType
|
Canvas |
getContainerWidget()
A Read-Only pointer to the Smart GWT canvas that holds this form item.
|
java.lang.String |
getControlStyle()
Base CSS class name for a form item's "control box".
|
java.lang.String |
getCriteriaField()
|
Criterion |
getCriterion()
Calls the
getCriterion() method
of the FormItemCriterionGetter
that is registered with this field. |
Criterion |
getCriterion(TextMatchStyle textMatchStyle)
Calls the
getCriterion() method
of the FormItemCriterionGetter
that is registered with this field. |
java.lang.Integer |
getCursorPosition()
For text-based items, this method returns the index of the start of the current selection if the item currently has the
focus (if no text is selected, this equates to the current position of the text editing cursor).
|
java.lang.String |
getCustomState(FormItemElementType elementType,
java.lang.String derivedState)
Optional method to retrieve a custom state suffix to append to the style name that is applied to some element of a
formItem - see
FormItemBaseStyle for more information on how state-based FormItem
style names are derived. |
java.lang.String |
getDataPath()
dataPath for this item.
|
DateDisplayFormat |
getDateFormatter()
Display format to use for date type values within this formItem.
|
java.lang.Integer |
getDecimalPad()
Applies only to fields of type "float" and enforces a minimum number of digits shown after the decimal point.
|
java.lang.Integer |
getDecimalPrecision()
Applies only to fields of type "float" and affects how many significant digits are shown.
|
java.lang.String |
getDefaultIconSrc()
Default icon image source.
|
OperatorId |
getDefaultOperator()
The default search-operator for this item when it or its form allow
filter-expressions . |
java.lang.Boolean |
getDestroyed()
The destroyed attribute will be set to true if this item has been destroyed() Note that FormItem lifecycle is managed by
the DynamicForm itself.
|
java.lang.Boolean |
getDisabled()
Deprecated.
Do not use this API. Instead, use
#isDisabled) , which correctly inherits the disabled state from containers |
java.lang.String |
getDisabledHover()
This text is shown as a tooltip prompt when the cursor hovers over this item and the item is
disabled or read-only with readOnlyDisplay:disabled . |
java.lang.Boolean |
getDisableIconsOnReadOnly()
|
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 |
getDisplayValue()
Returns this item's value with any valueMap applied to it - the value as currently displayed to the user.
|
java.lang.String |
getDisplayValue(java.lang.String value)
Returns this item's value with any valueMap applied to it - the value as currently displayed to the user.
|
com.google.gwt.core.client.JavaScriptObject |
getEditorTypeConfig() |
java.lang.String |
getEditPendingCSSText()
Custom CSS text to be applied to cells with pending edits that have not yet been submitted.
|
java.lang.String |
getEditProxyConstructor()
Default class used to construct the
EditProxy for this component when the component is
first placed into edit mode . |
java.lang.String |
getEmptyDisplayValue()
Text to display when this form item has a null or undefined value.
|
java.lang.String |
getEmptyValueIcon()
This property allows the developer to specify an icon to display when this item has no value.
|
java.lang.Boolean |
getEndRow()
Whether this item should end the row it's in in the form layout
|
int |
getErrorIconHeight()
Height of the error icon, if we're showing icons when validation errors occur.
|
java.lang.String |
getErrorIconSrc()
URL of the image to show as an error icon, if we're showing icons when validation errors occur.
|
int |
getErrorIconWidth()
Height of the error icon, if we're showing icons when validation errors occur.
|
int |
getErrorMessageWidth()
When
DynamicForm.showInlineErrors and showErrorText are both true and errorOrientation is "left" or "right",
errorMessageWidth is the amount to reduce the width of the editor to accommodate the error message and icon. |
java.lang.String[] |
getErrors()
Returns any validation errors for this field.
|
java.lang.Boolean |
getEscapeHTML()
Controls whether HTML item value(s) should be rendered or shown as HTML source.
|
java.lang.String |
getExportFormat()
FormatString used during exports for numeric or date formatting. |
java.lang.Boolean |
getFetchMissingValues()
If this form item has a specified
optionDataSource , should the item ever perform a fetch against this dataSource to retrieve the related record. |
java.lang.String |
getFieldName()
Return the name for the this formItem.
|
java.lang.Boolean |
getFilterLocally()
If this form item is mapping data values to a display value by fetching records from a dataSource (see
optionDataSource , displayField and fetchMissingValues ), setting this property to
true ensures that when the form item value is set, entire data-set from the dataSource is loaded at once and used as a
valueMap, rather than just loading the display value for the current value. |
java.lang.String |
getForeignDisplayField()
For items with an
optionDataSource , this
property specifies an explicit display field for records within the option dataSource. |
DynamicForm |
getForm()
A reference to the FormItem's DynamicForm.
|
java.lang.String |
getFormat()
FormatString for numeric or date formatting. |
FormItem |
getFormItemAutoChild(java.lang.String autoChildName)
Returns the
FormItem AutoChild named autoChildName if already created. |
UserFormula |
getFormula()
Formula to be used to calculate the numeric value of this FormItem.
|
java.lang.String |
getFullDataPath()
Return the fully-qualified dataPath for the this formItem (ie, the dataPath expressed in absolute terms from the root
of the hierarchy, rather than relative to the item's parent form).
|
java.lang.Integer |
getGlobalTabIndex()
TabIndex for the form item within the page.
|
java.lang.Integer |
getGridColNum()
If this formItem is part of a
ListGrid 's inline edit form , returns the number of the grid column this
formItem is responsible for editing, but only if a row is currently being edited. |
java.lang.Integer |
getGridRowNum()
If this formItem is part of a
ListGrid 's inline edit form , returns the number of the row currently being
edited. |
int |
getHeight()
Height of the FormItem.
|
java.lang.String |
getHeightAsString()
Height of the FormItem.
|
java.lang.Boolean |
getHidden()
Should this form item be hidden? Setting this property to
true on an item configuration will have the same
effect as having a showIf() implementation which returns
false . |
java.lang.String |
getHint()
Specifies "hint" string to show next to the form item to indicate something to the user.
|
java.lang.String |
getHintStyle()
CSS class for the "hint" string.
|
Alignment |
getHoverAlign()
Text alignment for text displayed in this item's hover canvas, if shown.
|
java.lang.Integer |
getHoverDelay()
If specified, this is the number of milliseconds to wait between the user rolling over this form item, and triggering
any hover action for it.
If not specified this.form.itemHoverDelay will be used instead. |
java.lang.String |
getHoverFocusKey()
This attribute gives users a way to pin this item's hover in place so they can interact with it (scroll it, click
embedded links, etc).
|
java.lang.Integer |
getHoverHeight()
Option to specify a height for any hover shown for this item.
|
java.lang.String |
getHoverHeightAsString()
Option to specify a height for any hover shown for this item.
|
java.lang.Integer |
getHoverOpacity()
Opacity for any hover shown for this item
|
HoverPersistMode |
getHoverPersist()
Allows interaction with hovers when the cursor is positioned over them.
|
java.lang.String |
getHoverStyle()
Explicit CSS Style for any hover shown for this item.
|
VerticalAlignment |
getHoverVAlign()
Vertical text alignment for text displayed in this item's hover canvas, if shown.
|
java.lang.Integer |
getHoverWidth()
Option to specify a width for any hover shown for this item.
|
java.lang.String |
getHoverWidthAsString()
Option to specify a width for any hover shown for this item.
|
FormItemIcon |
getIcon(java.lang.String name)
Given a
FormItemIcon.name , returns the
FormItemIcon object. |
int |
getIconHeight()
Default height for form item icons.
|
int |
getIconHSpace()
Horizontal space (in px) to leave between form item icons.
|
Rectangle |
getIconPageRect(FormItemIcon icon) |
java.lang.String |
getIconPrompt()
Default prompt (and tooltip-text) for icons.
|
Rectangle |
getIconRect(FormItemIcon icon) |
FormItemIcon[] |
getIcons()
An array of descriptor objects for icons to display in a line after this form item.
|
java.lang.Integer |
getIconTabPosition()
Returns the desired tab-position of some icon with respect to other focusable sub-elements for this formItem.
|
VerticalAlignment |
getIconVAlign()
How should icons be aligned vertically for this form item.
|
int |
getIconWidth()
Default width for form item icons.
|
java.lang.String |
getID()
Global identifier for referring to the formItem in JavaScript.
|
java.lang.String |
getImageURLPrefix()
Prefix to apply to the beginning of any
valueIcons when determining the URL for the image. |
java.lang.String |
getImageURLSuffix()
Suffix to apply to the end of any
valueIcons when
determining the URL for the image. |
java.lang.Boolean |
getImplicitSave()
When true, indicates that changes to this item will cause an automatic save on a
delay , as well as when the entire form is submitted. |
java.lang.Boolean |
getImplicitSaveOnBlur()
If set to true, this item's value will be saved immediately when its "editorExit" handler is fired.
|
java.lang.String |
getInputFormat()
For fields of type
"date" , if this is an editable field such as a TextItem , this property allows you to specify the inputFormat applied to the item. |
int |
getLeft()
Left coordinate of this item in pixels.
|
int |
getLinearColSpan()
Specifies a column span for an item in
linearMode ,
overriding the default value of "*" in that mode. |
java.lang.String |
getLinearColSpanAsString()
Specifies a column span for an item in
linearMode ,
overriding the default value of "*" in that mode. |
int |
getLinearEndRow()
|
java.lang.String |
getLinearEndRowAsString()
|
int |
getLinearStartRow()
|
java.lang.String |
getLinearStartRowAsString()
|
int |
getLinearWidth()
Specifies a width for an item in
linearMode ,
overriding the default width of "*" in that mode. |
java.lang.String |
getLinearWidthAsString()
Specifies a width for an item in
linearMode ,
overriding the default width of "*" in that mode. |
ListGrid |
getListGrid()
If this item is being used to edit cells in a ListGrid (see
isInGrid() ), this method returns the grid in question. |
java.lang.String |
getLoadingDisplayValue()
Value shown in field when
fetchMissingValues is active and a fetch is pending. |
java.lang.String |
getLocateItemBy()
When
AutoTest.getElement() is used to parse locator strings
generated by AutoTest.getLocator() for this form item, should the
item be identified? If the locator has a specified name , it is considered to definitely locate the item and no fallback approach will be used. |
java.lang.Integer |
getMinHintWidth()
If this item is showing a
hint , this setting specifies
how much horizontal space is made available for rendering the hint text by default. |
java.lang.Boolean |
getMultiple()
If true, multiple values may be selected.
|
java.lang.String |
getMultipleValueSeparator()
If this item is displaying multiple values, this property will be the string that separates those values for display
purposes.
|
java.lang.String |
getName()
Name for this form field.
|
java.lang.String |
getNullOriginalValueText()
Text shown as the value in the
originalValueMessage when showOldValueInHover is enabled, and when the value has been modified but was originally unset. |
OperatorId |
getOperator()
OperatorId to be used when DynamicForm.getValuesAsCriteria() is called. |
Criteria |
getOptionCriteria()
If this item has a specified
optionDataSource , and this property may be used
to specify criteria to pass to the datasource when
performing the fetch operation on the dataSource to obtain a data-value to display-value
mapping |
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 |
getOptionDataSourceAsString()
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. |
RPCRequest |
getOptionFilterContext()
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 |
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. |
TextMatchStyle |
getOptionTextMatchStyle()
If this item has a specified
optionDataSource , this property determines the textMatchStyle to use when
interpretating any optionCriteria during the
fetch to map valueField values to displayField values. |
static FormItem |
getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj) |
java.lang.String |
getOriginalValueMessage()
Message shown when
showOldValueInHover
is enabled and the value has been modified. |
int |
getPageLeft()
Returns the drawn page-left coordinate of this form item in pixels.
|
Rectangle |
getPageRect()
Return the page-level coordinates of this object.
|
int |
getPageTop()
Returns the drawn page-top coordinate of this form item in pixels.
|
java.util.Map |
getPaletteDefaults()
This method returns a Map of config properties suitable for use as the "defaults"
attribute of a
PaletteNode . |
Canvas |
getPicker()
The component that will be displayed when
showPicker() is called due to a click on the picker icon . |
static FormItemIcon |
getPickerIcon(PickerIconName pickerName)
Returns a
FormItemIcon for a standard picker with skin-specific
settings. |
static FormItemIcon |
getPickerIcon(PickerIconName pickerName,
FormItemIcon properties)
Returns a
FormItemIcon for a standard picker with skin-specific
settings. |
java.lang.Integer |
getPickerIconHeight()
If
showPickerIcon is true for this item, this
property governs the size of the picker icon. |
java.lang.String |
getPickerIconName()
If
showPickerIcon is true, this attribute
specifies the FormItemIcon.name applied to the
picker icon |
java.lang.String |
getPickerIconPrompt()
Prompt to show when the user hovers the mouse over the picker icon.
|
FormItemIcon |
getPickerIconProperties()
If
showPickerIcon is true for this item, this
block of properties will be applied to the pickerIcon. |
java.lang.String |
getPickerIconSrc()
If
showPickerIcon is true for this item, this
property governs the src of the picker icon image to
be displayed. |
java.lang.String |
getPickerIconStyle()
Base CSS class name for a form item's picker icon cell.
|
java.lang.Integer |
getPickerIconTabPosition()
Returns the desired tab-position of the picker icon with respect to other focusable sub-elements for this formItem.
|
java.lang.Integer |
getPickerIconWidth()
If
showPickerIcon is true for this item, this
property governs the size of the picker icon. |
int |
getPixelHeight()
Returns the specified
height of this formItem in
pixels. |
int |
getPixelWidth()
Returns the specified
width of this formItem in
pixels. |
java.lang.String |
getPrintReadOnlyTextBoxStyle()
CSS class name to apply to the print view of an item's text box if the item is
canEdit:false , with readOnlyDisplay:static . |
java.lang.String |
getPrintTextBoxStyle()
Base CSS class name for a form item's text box element when getting printable HTML for the form.
|
java.lang.String |
getPrintTitleStyle()
Base CSS stylename for a form item's title when generating print HTML for the item.
|
java.lang.String |
getPrompt()
This text is shown as a tooltip prompt when the cursor hovers over this item.
|
ReadOnlyDisplayAppearance[] |
getReadOnlyCanSelectText()
For items showing a text value with
canEdit set to
false, should the user be able to select the text in the item? |
java.lang.String |
getReadOnlyControlStyle()
Modified
control style to apply when this item
is read-only and is using readOnlyDisplay ReadOnlyDisplayAppearance.STATIC . |
ReadOnlyDisplayAppearance |
getReadOnlyDisplay()
If this item is
read-only , how should this item be
displayed to the user? If set, overrides the form-level DynamicForm.readOnlyDisplay default. |
java.lang.String |
getReadOnlyHover()
This text is shown as a tooltip prompt when the cursor hovers over this item and the item is
read-only . |
java.lang.String |
getReadOnlyTextBoxStyle()
Base text box style to apply when this item is
read-only and is using readOnlyDisplay
ReadOnlyDisplayAppearance.STATIC . |
AdvancedCriteria |
getReadOnlyWhen()
Criteria to be evaluated to determine whether this FormItem should be made
read-only . |
Rectangle |
getRect()
Return the coordinates of this object.
|
java.lang.Boolean |
getRedrawOnChange()
If true, this item will cause the entire form to be redrawn when the item's "elementChanged" event is done firing
|
java.lang.Boolean |
getRejectInvalidValueOnChange()
If validateOnChange is true, and validation fails for this item on change, with no suggested value, should we revert to
the previous value, or continue to display the bad value entered by the user.
|
java.lang.Boolean |
getRequired()
Whether a non-empty value is required for this field to pass validation.
|
java.lang.String |
getRequiredMessage()
The required message for required field errors.
|
Criteria |
getRequiredWhen()
Criteria to be evaluated to determine whether this FormItem should be
required . |
int |
getRowSpan()
Number of rows that this item spans
|
java.lang.Boolean |
getSaveOnEnter()
Set this to true to allow the parent form to save it's data when 'Enter' is pressed on this formItem and
saveOnEnter is true on the parent form. |
java.lang.String |
getScClassName()
Get the name of the underlying SmartClient class
|
ListGridRecord |
getSelectedRecord()
Get the record returned from the
optionDataSource when fetchMissingValues
is true, and the missing value is fetched. |
java.lang.Boolean |
getSelectOnClick()
Allows the
selectOnClick behavior to be configured
on a per-FormItem basis. |
java.lang.Boolean |
getSelectOnFocus()
Allows the
selectOnFocus behavior to be configured
on a per-FormItem basis. |
java.lang.Boolean |
getShouldSaveValue()
Should this item's value be saved in the form's values and hence returned from
form.getValues() ? |
boolean |
getShowClippedTitleOnHover()
If true and the title is clipped, then a hover containing the full title of this item is enabled.
|
java.lang.Boolean |
getShowClippedValueOnHover()
If true and the value is clipped, then a hover containing the full value of this item is enabled.
|
java.lang.Boolean |
getShowDeletions()
For items that support
multiple values , this
causes distinct CSS styling to be applied to values that the user has unselected. |
java.lang.Boolean |
getShowDisabled()
When this item is disabled, should it be re-styled to indicate its disabled state?
|
java.lang.Boolean |
getShowDisabledIconsOnFocus()
If
showIconsOnFocus is true, should icons
marked as disabled be shown on focus? |
java.lang.Boolean |
getShowDisabledPickerIconOnFocus()
If
showPickerIconOnFocus is true,
should the picker icon be shown on focus if it is disabled (as in a read-only item, for example?) |
java.lang.Boolean |
getShowErrorIcon()
showErrorIcons , showErrorText , errorOrientation , and showErrorStyle control how validation errors are
displayed when they are displayed inline in the form (next to the form item where there is a validation error). |
java.lang.Boolean |
getShowErrorStyle()
showErrorIcons , showErrorText , errorOrientation , and showErrorStyle control how validation errors are
displayed when they are displayed inline in the form (next to the form item where there is a validation error). |
java.lang.Boolean |
getShowErrorText()
showErrorIcons , showErrorText , errorOrientation , and showErrorStyle control how validation errors are
displayed when they are displayed inline in the form (next to the form item where there is a validation error). |
java.lang.Boolean |
getShowFocused()
When this item receives focus, should it be re-styled to indicate it has focus?
|
java.lang.Boolean |
getShowFocusedErrorState()
If set to true, when an item has errors and is focused, an "ErrorFocused" suffix will appear on the stylename.
|
java.lang.Boolean |
getShowFocusedIcons()
If we're showing icons, should we change their image source to the appropriate focused source when this item
has focus? Can be overridden on a per icon basis by the formItemIcon
showFocused property. |
java.lang.Boolean |
getShowFocusedPickerIcon()
If
showPickerIcon is true for this item,
should the picker icon show a focused image when the form item has focus? |
java.lang.Boolean |
getShowHint()
If a hint is defined for this form item, should it be shown?
|
java.lang.Boolean |
getShowIcons()
Set to false to suppress writing out any
icons for
this item. |
java.lang.Boolean |
getShowIconsOnFocus()
Show the
icons when the item gets focus, and hide them
when it loses focus. |
java.lang.Boolean |
getShowImageAsURL()
For fields of
type:"image" , if the field is non editable, and being
displayed with readOnlyDisplay:"static" ,
should the value (URL) be displayed as text, or should an image be rendered? |
java.lang.Boolean |
getShowOldValueInHover()
Causes the original value to be shown to the end user when the user hovers over the FormItem as such (when the
FormItem.itemHover() event would fire). |
boolean |
getShowOver()
When the user rolls over this item, should it be re-styled to indicate it has focus?
|
java.lang.Boolean |
getShowOverIcons()
If we're showing icons, should we change their image source to the appropriate over source when the user rolls
over (or puts focus onto) them? Can be overridden on a per icon basis by the formItemIcon
showOver
property. |
java.lang.Boolean |
getShowPending()
When
true , causes the "Pending" optional suffix to be added if the item's current value differs from the
value that would be restored by a call to DynamicForm.resetValues() . |
java.lang.Boolean |
getShowPickerIcon()
Should we show a special 'picker'
icon for this form item?
Picker icons are customizable via pickerIconProperties . |
java.lang.Boolean |
getShowPickerIconOnFocus()
Show the picker icon when the item gets focus, and hide it when it loses focus.
|
boolean |
getShowRTL()
When this item is in RTL mode, should its style name include an "RTL" suffix?
|
java.lang.Boolean |
getShowTitle()
Should we show a title cell for this formItem?
|
java.lang.Boolean |
getShowValueIconOnly()
If
valueIcons is set, this property may be set to
show the valueIcon only and prevent the standard form item element or text from displaying |
java.lang.Boolean |
getStartRow()
Whether this item should always start a new row in the form layout.
|
java.lang.Integer |
getStaticHeight()
Height of the FormItem when
canEdit is false and readOnlyDisplay is "static". |
java.lang.Boolean |
getStopOnError()
Indicates that if validation fails, the user should not be allowed to exit the field - focus will be forced back into
the field until the error is corrected.
|
java.lang.Boolean |
getStoreDisplayValues()
If specified, this overrides the
DynamicForm.storeDisplayValues property for this field. |
boolean |
getSupportsCutPasteEvents()
Does the current formItem support native cut and paste events?
|
java.lang.Boolean |
getSuppressValueIcon()
If
valueIcons is set, this property may be set to
prevent the value icons from showing up next to the form items value |
java.lang.Boolean |
getSynchronousValidation()
If enabled, whenever validation is triggered and a request to the server is required, user interactivity will be blocked
until the request returns.
|
java.lang.Integer |
getTabIndex()
TabIndex for the form item within the form, which controls the order in which controls are visited when the user hits
the tab or shift-tab keys to navigate between items.
|
Alignment |
getTextAlign()
Alignment of the text / content within this form item.
|
java.lang.String |
getTextBoxStyle()
Base CSS class name for a form item's text box element.
|
UserSummary |
getTextFormula()
Formula to be used to calculate the text value of this FormItem.
|
TimeDisplayFormat |
getTimeFormatter()
Time-format to apply to date type values within this formItem.
|
java.lang.String |
getTitle()
User visible title for this form item.
|
Alignment |
getTitleAlign()
Alignment of this item's title in its cell.
|
int |
getTitleColSpan()
Number of columns that this item's title spans.
|
TitleOrientation |
getTitleOrientation()
On which side of this item should the title be placed.
|
java.lang.String |
getTitleStyle()
Base CSS class name for a form item's title.
|
VerticalAlignment |
getTitleVAlign()
Vertical alignment of this item's title in its cell.
|
java.lang.String |
getTooltip()
This text is shown as a tooltip prompt when the cursor hovers over this item.
|
int |
getTop()
Top coordinate of this item in pixels.
|
java.lang.String |
getType()
The DynamicForm picks a field renderer based on the type of the field (and sometimes other attributes of the
field).
|
java.lang.Boolean |
getUpdateControlOnOver()
If
showOver is true, setting this property to false
will explicitly disable showing the "Over" state for the control table element of this item (if present). |
java.lang.Boolean |
getUpdatePickerIconOnOver()
If
showOver is true, setting this property to false
will explicitly disable showing the "Over" state for the PickerIcon of this item (if present) |
java.lang.Boolean |
getUpdateTextBoxOnOver()
If
showOver is true, setting this property to false
will explicitly disable showing the "Over" state for the TextBox element of this item. |
java.lang.Boolean |
getUseAdvancedCriteria()
Should this form item always produce an
AdvancedCriteria sub criterion object? When set
to true, causes hasAdvancedCriteria to
return true. |
java.lang.Boolean |
getUseDisabledHintStyleForReadOnly()
By default,
read-only fields use the same style name
as editable fields for in-field hints, unless they are disabled or configured to use a disabled ReadOnlyDisplayAppearance . |
java.lang.Boolean |
getUseLocalDisplayFieldValue()
If
displayField is specified for a field,
should the display value for the field be picked up from the record currently being edited ? |
java.lang.Boolean |
getValidateOnChange()
If true, form items will be validated when each item's "change" handler is fired as well as when the entire form is
submitted or validated.
|
java.lang.Boolean |
getValidateOnExit()
If true, form items will be validated when each item's "editorExit" handler is fired as well as when the entire form is
submitted or validated.
|
OperatorId[] |
getValidOperators()
Array of valid filtering operators (eg "greaterThan") that are legal for this FormItem.
|
VerticalAlignment |
getVAlign()
Vertical alignment of this item within its cell.
|
java.lang.Object |
getValue()
Return the value tracked by this form item.
|
java.lang.Float |
getValueAsFloat()
Return the value tracked by this form item as a Float.
|
java.lang.Integer |
getValueAsInteger()
Return the value tracked by this form item as an Integer.
|
java.lang.Long |
getValueAsLong()
Return the value tracked by this form item as a Long.
|
RecordList |
getValueAsRecordList() |
java.lang.String |
getValueDeselectedCSSText()
Custom CSS text to be applied to values that have been deleted, when
showDeletions is enabled. |
java.lang.String |
getValueField()
If this form item maps data values to display values by retrieving the
displayField values from an optionDataSource , this property denotes the the
field to use as the underlying data value in records from the optionDataSource.If not explicitly supplied, the valueField name will be derived as described in getValueFieldName() . |
java.lang.String |
getValueFieldName()
Getter method to retrieve the
valueField for this
item. |
java.lang.Integer |
getValueIconHeight()
If
valueIcons is specified, use this property to
specify a height for the value icon written out. |
int |
getValueIconLeftPadding()
If we're showing a value icon, this attribute governs the amount of space between the icon and the start edge of the
form item cell.
|
int |
getValueIconRightPadding()
If we're showing a value icon, this attribute governs the amount of space between the icon and the value text.
|
int |
getValueIconSize()
If
valueIcons is specified, this property may be
used to specify both the width and height of the icon written out. |
java.lang.Integer |
getValueIconWidth()
If
valueIcons is specified, use this property to
specify a width for the value icon written out. |
java.util.Map |
getValueMap()
In a form, valueMaps are used for FormItem types that allow the user to pick from a
limited set of values, such as a
SelectItem . |
java.lang.String[] |
getValueMapAsArray()
See also
getValueMap() |
java.lang.Boolean |
getVisible()
Whether this item is currently visible.
|
int |
getVisibleHeight()
Output the drawn height for this item in pixels.
|
int |
getVisibleTitleWidth(java.lang.Boolean labelOnly)
Returns the visible width of this item's title in px.
|
AdvancedCriteria |
getVisibleWhen()
Criteria to be evaluated to determine whether this FormItem should be visible.
|
int |
getVisibleWidth()
Output the drawn width for this item in pixels.
|
boolean |
getWarnOnEditorTypeConversion()
Gets whether a warning will be logged if the Framework replaces this SmartGWT FormItem
(that wraps the SmartClient item instance) to more closely match the underlying item's
type.
|
static boolean |
getWarnOnEditorTypeConversionDefault()
Gets whether, by default, a warning will be logged if the Framework replaces a SmartGWT
FormItem (that wraps the SmartClient item instance) to more closely match the underlying
item's type.
|
int |
getWidth()
Width of the FormItem.
|
java.lang.String |
getWidthAsString()
Width of the FormItem.
|
java.lang.Boolean |
getWrapHintText()
If this item is showing a
hint , should the hint text be
allowed to wrap? Setting this property to false will render the hint on a single line without wrapping,
expanding the width required to render the item if necessary. |
java.lang.Boolean |
getWrapStaticValue()
If this item is
read-only and is using readOnlyDisplay ReadOnlyDisplayAppearance.STATIC , should the item value wrap? |
java.lang.Boolean |
getWrapTitle()
If specified determines whether this items title should wrap.
|
void |
handleWarnOnEditorTypeConversion(FormItem oldItem,
FormItem newItem) |
java.lang.Boolean |
hasAdvancedCriteria()
Does this form item produce an
AdvancedCriteria sub criterion object? If this method
returns true, DynamicForm.getValuesAsCriteria()
on the form containing this item will always return an AdvancedCriteria object, calling
FormItemCriterionGetter.getCriterion() on each item to retrieve the individual criteria. |
boolean |
hasErrors()
Return whether this item currently has any validation errors as a result of a previous validation pass.
|
void |
hide()
Hide this form item.
|
void |
hideIcon(java.lang.String icon)
This method will hide some icon in this item's
icons
array, if it is currently visible. |
void |
invalidateDisplayValueCache()
If this item has a specified
displayField , the
value displayed to the user for this item may be derived from another field. |
boolean |
isConfigOnly() |
boolean |
isCreated() |
boolean |
isCutEvent()
Is the user performing a native "cut" event to modify the value of a freeform text field? This method may be invoked
during change notification flow methods including
FormItem.change() , FormItem.changed() and FormItem.transformInput() . |
java.lang.Boolean |
isDisabled()
Is this item disabled?
|
java.lang.Boolean |
isDrawn()
Returns true if this item has been written out into the DOM.
|
java.lang.Boolean |
isFocused()
Returns true if this formItem has the keyboard focus.
|
java.lang.Boolean |
isInGrid()
Returns true if this item's
containerWidget
is a GridRenderer or GridRenderer subclass |
boolean |
isPasteEvent()
Is the user performing a native "paste" event to modify the value of a freeform text field? This method may be invoked
during change notification flow methods including
FormItem.change() , FormItem.changed() and FormItem.transformInput() . |
java.lang.Boolean |
isVisible()
Return true if the form item is currently visible.
|
void |
linkToInstanceUponCreate() |
java.lang.Object |
mapDisplayToValue(java.lang.String value)
Given a display value for this FormItem, return the underlying data value.
|
java.lang.String |
mapValueToDisplay(com.google.gwt.core.client.JavaScriptObject value) |
java.lang.String |
mapValueToDisplay(java.util.Map value)
Given a value for this FormItem, return the value to be displayed.
|
java.lang.String |
mapValueToDisplay(java.lang.Object value) |
void |
redraw()
Redraw this form item.
|
void |
redraw(java.lang.String reason)
Redraw this form item.
|
boolean |
removeIcon(java.lang.String icon)
Given an icon's
name , remove it from this item. |
void |
selectedRecordChanged(ListGridRecord record)
Notification method fired for
data bound
items with fetchMissingValues enabled
when the selected record is updated as a
result of the value changing or a fetch for a new record completing.Note that a formItem with an optionDataSource may avoid fetching an associated record altogether in some cases. |
FormItem |
setAccessKey(java.lang.String accessKey)
If specified this governs the HTML accessKey for the item.
|
FormItem |
setAlign(Alignment align)
Alignment of this item in its cell.
|
FormItem |
setAllowExpressions(java.lang.Boolean allowExpressions)
For a form that produces filter criteria (see
form.getValuesAsCriteria() ), allows the user to type in simple expressions to cause filtering with that operator. |
FormItem |
setAlwaysFetchMissingValues(java.lang.Boolean alwaysFetchMissingValues)
If this form item has a specified
optionDataSource and fetchMissingValues
is true, when the item value changes, a fetch will be performed against the optionDataSource to retrieve the related
record if displayField is specified and the
new item value is not present in any valueMap explicitly specified on the item. |
FormItem |
setAlwaysShowControlBox(java.lang.Boolean alwaysShowControlBox)
A formItem showing a
pickerIcon will always
write out a "control box" around the text box and picker icon. |
FormItem |
setApplyAlignToText(boolean applyAlignToText)
|
FormItem |
setApplyHeightToTextBox(java.lang.Boolean applyHeightToTextBox)
If
height is specified, should it be applied to the
item's text box element? |
FormItem |
setAriaRole(java.lang.String ariaRole)
ARIA role of this formItem.
|
void |
setAriaState(java.lang.String stateName,
java.lang.Object stateValue)
Set a specific ARIA state mapping for this form item.
|
FormItem |
setAttribute(java.lang.String attribute,
BaseClass value)
Set attribute value to a BaseClass.
|
FormItem |
setAttribute(java.lang.String attribute,
BaseClass[] value)
Set attribute value to a BaseClass array.
|
FormItem |
setAttribute(java.lang.String attribute,
boolean value)
Set attribute value to a boolean.
|
FormItem |
setAttribute(java.lang.String attribute,
java.lang.Boolean value)
Set attribute value to a Boolean.
|
FormItem |
setAttribute(java.lang.String attribute,
DataClass value)
Set attribute value to a DataClass.
|
FormItem |
setAttribute(java.lang.String attribute,
DataClass[] value)
Set attribute value to a DataClass array.
|
FormItem |
setAttribute(java.lang.String attribute,
java.util.Date value)
Set attribute value to a Date.
|
FormItem |
setAttribute(java.lang.String attribute,
double value)
Set attribute value to a double.
|
FormItem |
setAttribute(java.lang.String attribute,
java.lang.Double value)
Set attribute value to a Double.
|
FormItem |
setAttribute(java.lang.String attribute,
double[] value)
Set attribute value to a double array.
|
FormItem |
setAttribute(java.lang.String attribute,
java.lang.Float value)
Set attribute value to a Float.
|
FormItem |
setAttribute(java.lang.String attribute,
int value)
Set attribute value to an int.
|
FormItem |
setAttribute(java.lang.String attribute,
int[] value)
Set attribute value to an int array.
|
FormItem |
setAttribute(java.lang.String attribute,
java.lang.Integer value)
Set attribute value to an Integer.
|
FormItem |
setAttribute(java.lang.String attribute,
java.lang.Integer[] value)
Set attribute value to an Integer array.
|
FormItem |
setAttribute(java.lang.String attribute,
com.google.gwt.core.client.JavaScriptObject value)
Set attribute value to a JavaScriptObject.
|
FormItem |
setAttribute(java.lang.String attribute,
long value)
Set attribute value to a long.
|
FormItem |
setAttribute(java.lang.String attribute,
java.util.Map value)
Set attribute value to a Map.
|
FormItem |
setAttribute(java.lang.String attribute,
java.lang.String value)
Set attribute value to a String
|
FormItem |
setAttribute(java.lang.String attribute,
java.lang.String[] value)
Set attribute value to a String array.
|
FormItem |
setAttribute(java.lang.String attribute,
ValueEnum[] value)
Set attribute value to a ValueEnum array.
|
void |
setAutoChildConstructor(java.lang.String autoChildName,
java.lang.String className)
Sets the SmartClient constructor for the AutoChild named
autoChildName . |
void |
setAutoChildProperties(java.lang.String autoChildName,
Canvas properties)
Sets the properties for creating a
Canvas AutoChild named autoChildName . |
void |
setAutoChildProperties(java.lang.String autoChildName,
EditProxy properties)
Sets the properties for creating an AutoChild named
autoChildName . |
void |
setAutoChildProperties(java.lang.String autoChildName,
FormItem properties)
Sets the properties for creating a
FormItem AutoChild named autoChildName . |
void |
setAutoChildVisibility(java.lang.String autoChildName,
boolean visible)
Sets whether to create and show the AutoChild named
autoChildName . |
FormItem |
setAutoComplete(AutoComplete autoComplete)
Should this item allow browser auto-completion of its value? Applies only to items based on native HTML form elements
(
TextItem , PasswordItem ,
etc), and will only have a user-visible impact for browsers where native autoComplete behavior is actually supported and
enabled via user settings. |
FormItem |
setAutoCompleteKeywords(java.lang.String... autoCompleteKeywords)
Set of autocompletion keywords to be used with the native "autocomplete" attribute, in accordance with the HTML5 Autofill
specification.
|
FormItem |
setBrowserInputType(java.lang.String browserInputType)
Form item input type - governs which keyboard should be displayed for mobile devices (supported on iPhone / iPad)
|
FormItem |
setBrowserSpellCheck(java.lang.Boolean browserSpellCheck)
If this browser supports spell-checking of text editing elements, do we want this enabled for this item? If unset the
property will be inherited from the containing form.
|
FormItem |
setCanEdit(java.lang.Boolean canEdit)
Is this form item editable (canEdit:true) or read-only (canEdit:false)? Setting the form item to non-editable causes it
to render as read-only.
|
void |
setCanEditCriterionPredicate(FormItemCanEditCriterionPredicate predicate)
When a dynamic form is editing an advanced criteria object via
DynamicForm.setValuesAsCriteria , this predicate is used
to determine which sub-criteria apply to which form item(s). |
FormItem |
setCanEditOpaqueValues(java.lang.Boolean canEditOpaqueValues)
If true, indicates that this FormItem is capable of editing "opaque" values, ie, objects that are more complex than
simple primitive types like numbers, strings and dates.
|
FormItem |
setCanFocus(java.lang.Boolean canFocus)
Is this form item focusable? Setting this property to true on an otherwise non-focusable element such as a
StaticTextItem will cause the item to be included in the page's tab order and
respond to keyboard events. |
FormItem |
setCanSelectText(boolean canSelectText)
For items showing a text value, should the user be able to select the text in this item?
|
FormItem |
setCanTabToIcons(java.lang.Boolean canTabToIcons)
Should this item's
icons and picker icon be included in the page's tab order by
default? If not explicitly set, this property will be derived from DynamicForm.canTabToIcons . |
FormItem |
setCellHeight(java.lang.Integer cellHeight)
If specified, this property will govern the height of the cell in which this form item is rendered.
|
FormItem |
setCellStyle(java.lang.String cellStyle)
CSS style applied to the form item as a whole, including the text element, any icons, and any hint text for the item.
|
FormItem |
setChangeOnKeypress(java.lang.Boolean changeOnKeypress)
Should this form item fire its
change handler
(and store its value in the form) on every keypress? Set to false to suppress the 'change' handler firing
(and the value stored) on every keypress. |
FormItem |
setClipStaticValue(java.lang.Boolean clipStaticValue)
If this item is
read-only and is using readOnlyDisplay ReadOnlyDisplayAppearance.STATIC , should the item value be clipped if it overflows the
specified size of the item? If set, overrides the form-level DynamicForm.clipStaticValue default. |
FormItem |
setClipTitle(java.lang.Boolean clipTitle)
If the title for this form item is showing, and is too large for the available space should the title be clipped?
|
FormItem |
setColSpan(int colSpan)
Number of columns that this item spans.
|
FormItem |
setColSpan(java.lang.String colSpan)
Number of columns that this item spans.
|
void |
setConfigOnly(boolean configOnly) |
FormItem |
setControlStyle(java.lang.String controlStyle)
Base CSS class name for a form item's "control box".
|
FormItem |
setCriteriaField(java.lang.String criteriaField)
|
void |
setCriterion(Criterion criterion)
Calls the
setCriterion() method
of the FormItemCriterionSetter
that is registered with this field. |
void |
setCriterionGetter(FormItemCriterionGetter getter)
Provides a specialized criterion from this formItem when creating an AdvancedCriteria
via
DynamicForm.getValuesAsCriteria . |
void |
setCriterionSetter(FormItemCriterionSetter setter)
Set the method to update this form item to reflect a criterion object from within an AdvancedCriteria.
|
void |
setCustomStateGetter(FormItem.CustomStateGetter getter)
Deprecated.
Do not use CustomStateGetter; use
com.smartgwt.client.widgets.form.fields.FormItem.setStateCustomizer instead |
FormItem |
setDataPath(java.lang.String dataPath)
dataPath for this item.
|
FormItem |
setDateFormatter(DateDisplayFormat dateFormatter)
Display format to use for date type values within this formItem.
|
FormItem |
setDecimalPad(java.lang.Integer decimalPad)
Applies only to fields of type "float" and enforces a minimum number of digits shown after the decimal point.
|
FormItem |
setDecimalPrecision(java.lang.Integer decimalPrecision)
Applies only to fields of type "float" and affects how many significant digits are shown.
|
FormItem |
setDefaultIconSrc(java.lang.String defaultIconSrc)
Default icon image source.
|
FormItem |
setDefaultOperator(OperatorId defaultOperator)
The default search-operator for this item when it or its form allow
filter-expressions . |
static void |
setDefaultProperties(FormItem formItemProperties)
Class level method to set the default properties of this class.
|
FormItem |
setDefaultValue(java.lang.Boolean defaultValue)
Value used when no value is provided for this item.
|
void |
setDefaultValue(java.util.Date defaultValue)
Value used when no value is provided for this item.
|
void |
setDefaultValue(java.lang.Double defaultValue)
Value used when no value is provided for this item.
|
void |
setDefaultValue(java.lang.Float defaultValue)
Value used when no value is provided for this item.
|
void |
setDefaultValue(java.lang.Integer defaultValue)
Value used when no value is provided for this item.
|
void |
setDefaultValue(java.lang.Object value) |
FormItem |
setDefaultValue(java.lang.String defaultValue)
Value used when no value is provided for this item.
|
FormItem |
setDisabled(java.lang.Boolean disabled)
Whether this item is disabled.
|
FormItem |
setDisabledHover(java.lang.String disabledHover)
This text is shown as a tooltip prompt when the cursor hovers over this item and the item is
disabled or read-only with readOnlyDisplay:disabled . |
FormItem |
setDisableIconsOnReadOnly(java.lang.Boolean disableIconsOnReadOnly)
|
FormItem |
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 . |
FormItem |
setDisplayFormat(DateDisplayFormat displayFormat)
|
void |
setDisplayFormat(TimeFormatter displayFormat)
|
void |
setEditorProperties(FormItem editorProperties)
Set default properties to use when editing.
|
void |
setEditorType(java.lang.Class<? extends FormItem> editorType)
Set the FormItem subclass to use when editing.
|
void |
setEditorType(FormItem editorType)
Deprecated.
Renamed to
setEditorProperties(FormItem) . You can also consider using
setEditorType(Class) or setEditorType(String) instead. |
void |
setEditorType(java.lang.String editorType)
Set the FormItem subclass to use when editing.
|
void |
setEditorValueFormatter(FormItemValueFormatter formatter)
An optional
FormItemValueFormatter to map this item's current data value to a
display value. |
void |
setEditorValueParser(FormItemValueParser valueParser)
An optional
FormItemValueParser to map a user-entered display value to a data
value for storage. |
FormItem |
setEditPendingCSSText(java.lang.String editPendingCSSText)
Custom CSS text to be applied to cells with pending edits that have not yet been submitted.
|
FormItem |
setEditProxyConstructor(java.lang.String editProxyConstructor)
Default class used to construct the
EditProxy for this component when the component is
first placed into edit mode . |
FormItem |
setEmptyDisplayValue(java.lang.String emptyDisplayValue)
Text to display when this form item has a null or undefined value.
|
FormItem |
setEmptyValueIcon(java.lang.String emptyValueIcon)
This property allows the developer to specify an icon to display when this item has no value.
|
FormItem |
setEndRow(java.lang.Boolean endRow)
Whether this item should end the row it's in in the form layout
|
void |
setErrorFormatter(FormItemErrorFormatter errorFormatter)
Register a custom error formatter for this FormItem.
|
FormItem |
setErrorIconHeight(int errorIconHeight)
Height of the error icon, if we're showing icons when validation errors occur.
|
FormItem |
setErrorIconSrc(java.lang.String errorIconSrc)
URL of the image to show as an error icon, if we're showing icons when validation errors occur.
|
FormItem |
setErrorIconWidth(int errorIconWidth)
Height of the error icon, if we're showing icons when validation errors occur.
|
FormItem |
setErrorMessageWidth(int errorMessageWidth)
When
DynamicForm.showInlineErrors and showErrorText are both true and errorOrientation is "left" or "right",
errorMessageWidth is the amount to reduce the width of the editor to accommodate the error message and icon. |
void |
setErrorOrientation(FormErrorOrientation errorOrientation)
If
showInlineErrors is true, where
should the error icon and text appear relative to the form item itself. |
void |
setErrors(java.lang.String error)
Sets a validation error message for this field.
|
void |
setErrors(java.lang.String[] errors)
Sets multiple validation error messages for this field.
|
FormItem |
setEscapeHTML(java.lang.Boolean escapeHTML)
Controls whether HTML item value(s) should be rendered or shown as HTML source.
|
FormItem |
setExportFormat(java.lang.String exportFormat)
FormatString used during exports for numeric or date formatting. |
FormItem |
setFetchMissingValues(java.lang.Boolean fetchMissingValues)
If this form item has a specified
optionDataSource , should the item ever perform a fetch against this dataSource to retrieve the related record. |
FormItem |
setFilterLocally(java.lang.Boolean filterLocally)
If this form item is mapping data values to a display value by fetching records from a dataSource (see
optionDataSource , displayField and fetchMissingValues ), setting this property to
true ensures that when the form item value is set, entire data-set from the dataSource is loaded at once and used as a
valueMap, rather than just loading the display value for the current value. |
FormItem |
setForeignDisplayField(java.lang.String foreignDisplayField)
For items with an
optionDataSource , this
property specifies an explicit display field for records within the option dataSource. |
FormItem |
setFormat(java.lang.String format)
FormatString for numeric or date formatting. |
FormItem |
setFormula(UserFormula formula)
Formula to be used to calculate the numeric value of this FormItem.
|
FormItem |
setGlobalTabIndex(java.lang.Integer globalTabIndex)
TabIndex for the form item within the page.
|
FormItem |
setHeight(int height)
Height of the FormItem.
|
FormItem |
setHeight(java.lang.String height)
Height of the FormItem.
|
FormItem |
setHidden(java.lang.Boolean hidden)
Should this form item be hidden? Setting this property to
true on an item configuration will have the same
effect as having a showIf() implementation which returns
false . |
FormItem |
setHint(java.lang.String hint)
Specifies "hint" string to show next to the form item to indicate something to the user.
|
FormItem |
setHintStyle(java.lang.String hintStyle)
CSS class for the "hint" string.
|
FormItem |
setHoverAlign(Alignment hoverAlign)
Text alignment for text displayed in this item's hover canvas, if shown.
|
FormItem |
setHoverDelay(java.lang.Integer hoverDelay)
If specified, this is the number of milliseconds to wait between the user rolling over this form item, and triggering
any hover action for it.
If not specified this.form.itemHoverDelay will be used instead. |
FormItem |
setHoverFocusKey(java.lang.String hoverFocusKey)
This attribute gives users a way to pin this item's hover in place so they can interact with it (scroll it, click
embedded links, etc).
|
FormItem |
setHoverHeight(java.lang.Integer hoverHeight)
Option to specify a height for any hover shown for this item.
|
FormItem |
setHoverHeight(java.lang.String hoverHeight)
Option to specify a height for any hover shown for this item.
|
FormItem |
setHoverOpacity(java.lang.Integer hoverOpacity)
Opacity for any hover shown for this item
|
FormItem |
setHoverPersist(HoverPersistMode hoverPersist)
Allows interaction with hovers when the cursor is positioned over them.
|
FormItem |
setHoverStyle(java.lang.String hoverStyle)
Explicit CSS Style for any hover shown for this item.
|
FormItem |
setHoverVAlign(VerticalAlignment hoverVAlign)
Vertical text alignment for text displayed in this item's hover canvas, if shown.
|
FormItem |
setHoverWidth(java.lang.Integer hoverWidth)
Option to specify a width for any hover shown for this item.
|
FormItem |
setHoverWidth(java.lang.String hoverWidth)
Option to specify a width for any hover shown for this item.
|
void |
setIconDisabled(java.lang.String icon,
boolean disabled)
Set an icon as enabled or disabled at runtime.
|
FormItem |
setIconHeight(int iconHeight)
Default height for form item icons.
|
FormItem |
setIconHSpace(int iconHSpace)
Horizontal space (in px) to leave between form item icons.
|
FormItem |
setIconPrompt(java.lang.String iconPrompt)
Default prompt (and tooltip-text) for icons.
|
FormItem |
setIcons(FormItemIcon... icons)
An array of descriptor objects for icons to display in a line after this form item.
|
void |
setIconShowOnFocus(java.lang.String icon,
java.lang.Boolean showOnFocus)
Sets
FormItemIcon.showOnFocus for the
supplied icon, and causes that icon's visibility to be updated and the item redrawn as appropriate. |
FormItem |
setIconVAlign(VerticalAlignment iconVAlign)
How should icons be aligned vertically for this form item.
|
FormItem |
setIconWidth(int iconWidth)
Default width for form item icons.
|
FormItem |
setID(java.lang.String ID)
Global identifier for referring to the formItem in JavaScript.
|
FormItem |
setImageURLPrefix(java.lang.String imageURLPrefix)
Prefix to apply to the beginning of any
valueIcons when determining the URL for the image. |
FormItem |
setImageURLSuffix(java.lang.String imageURLSuffix)
Suffix to apply to the end of any
valueIcons when
determining the URL for the image. |
FormItem |
setImplicitSave(java.lang.Boolean implicitSave)
When true, indicates that changes to this item will cause an automatic save on a
delay , as well as when the entire form is submitted. |
FormItem |
setImplicitSaveOnBlur(java.lang.Boolean implicitSaveOnBlur)
If set to true, this item's value will be saved immediately when its "editorExit" handler is fired.
|
void |
setInitHandler(FormItemInitHandler initHandler)
Specify a notification method to fire when this formItem is initialized in JavaScript.
|
FormItem |
setInputFormat(java.lang.String inputFormat)
For fields of type
"date" , if this is an editable field such as a TextItem , this property allows you to specify the inputFormat applied to the item. |
void |
setInputTransformer(FormItemInputTransformer inputTransformer)
The transformer is called when a FormItem's value is about to change as the result of user interaction.
|
void |
setItemHoverFormatter(FormItemHoverFormatter hoverFormatter)
The FormItemHoverFormatter should return the HTML to display in a hover canvas when the user holds the mousepointer over this item.
|
void |
setItemTitleHoverFormatter(FormItemHoverFormatter hoverFormatter)
The
FormItemHoverFormatter should return the HTML to display in a hover canvas
when the user holds the mouse pointer over this item's title and the title is clipped. |
void |
setItemValueHoverFormatter(FormItemHoverFormatter hoverFormatter)
The
FormItemHoverFormatter should return the HTML to display in a hover canvas
when the user holds the mouse pointer over this item's value and the value is clipped. |
void |
setJavaScriptObject(com.google.gwt.core.client.JavaScriptObject jsObj) |
FormItem |
setLeft(int left)
Left coordinate of this item in pixels.
|
FormItem |
setLinearColSpan(int linearColSpan)
Specifies a column span for an item in
linearMode ,
overriding the default value of "*" in that mode. |
FormItem |
setLinearColSpan(java.lang.String linearColSpan)
Specifies a column span for an item in
linearMode ,
overriding the default value of "*" in that mode. |
FormItem |
setLinearEndRow(int linearEndRow)
|
FormItem |
setLinearEndRow(java.lang.String linearEndRow)
|
FormItem |
setLinearStartRow(int linearStartRow)
|
FormItem |
setLinearStartRow(java.lang.String linearStartRow)
|
FormItem |
setLinearWidth(int linearWidth)
Specifies a width for an item in
linearMode ,
overriding the default width of "*" in that mode. |
FormItem |
setLinearWidth(java.lang.String linearWidth)
Specifies a width for an item in
linearMode ,
overriding the default width of "*" in that mode. |
FormItem |
setLoadingDisplayValue(java.lang.String loadingDisplayValue)
Value shown in field when
fetchMissingValues is active and a fetch is pending. |
FormItem |
setLocateItemBy(java.lang.String locateItemBy)
When
AutoTest.getElement() is used to parse locator strings
generated by AutoTest.getLocator() for this form item, should the
item be identified? If the locator has a specified name , it is considered to definitely locate the item and no fallback approach will be used. |
FormItem |
setMinHintWidth(java.lang.Integer minHintWidth)
If this item is showing a
hint , this setting specifies
how much horizontal space is made available for rendering the hint text by default. |
FormItem |
setMultiple(java.lang.Boolean multiple)
If true, multiple values may be selected.
|
FormItem |
setMultipleValueSeparator(java.lang.String multipleValueSeparator)
If this item is displaying multiple values, this property will be the string that separates those values for display
purposes.
|
void |
setName(java.lang.String name)
Name for this form field.
|
FormItem |
setNullOriginalValueText(java.lang.String nullOriginalValueText)
Text shown as the value in the
originalValueMessage when showOldValueInHover is enabled, and when the value has been modified but was originally unset. |
void |
setNullProperty(java.lang.String property) |
FormItem |
setOperator(OperatorId operator)
OperatorId to be used when DynamicForm.getValuesAsCriteria() is called. |
void |
setOptionCriteria(Criteria optionCriteria)
If this item has a specified
optionDataSource , and this property may be used
to specify criteria to pass to the datasource when
performing the fetch operation on the dataSource to obtain a data-value to display-value
mapping |
FormItem |
setOptionDataSource(DataSource optionDataSource)
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. |
FormItem |
setOptionDataSource(java.lang.String optionDataSource)
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. |
void |
setOptionFilterContext(RPCRequest rpcRequestProperties)
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 |
FormItem |
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. |
FormItem |
setOptionTextMatchStyle(TextMatchStyle optionTextMatchStyle)
If this item has a specified
optionDataSource , this property determines the textMatchStyle to use when
interpretating any optionCriteria during the
fetch to map valueField values to displayField values. |
FormItem |
setOriginalValueMessage(java.lang.String originalValueMessage)
Message shown when
showOldValueInHover
is enabled and the value has been modified. |
FormItem |
setPickerIconHeight(java.lang.Integer pickerIconHeight)
If
showPickerIcon is true for this item, this
property governs the size of the picker icon. |
FormItem |
setPickerIconName(java.lang.String pickerIconName)
If
showPickerIcon is true, this attribute
specifies the FormItemIcon.name applied to the
picker icon |
FormItem |
setPickerIconPrompt(java.lang.String pickerIconPrompt)
Prompt to show when the user hovers the mouse over the picker icon.
|
FormItem |
setPickerIconProperties(FormItemIcon pickerIconProperties)
If
showPickerIcon is true for this item, this
block of properties will be applied to the pickerIcon. |
FormItem |
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. |
FormItem |
setPickerIconStyle(java.lang.String pickerIconStyle)
Base CSS class name for a form item's picker icon cell.
|
FormItem |
setPickerIconWidth(java.lang.Integer pickerIconWidth)
If
showPickerIcon is true for this item, this
property governs the size of the picker icon. |
FormItem |
setPrintReadOnlyTextBoxStyle(java.lang.String printReadOnlyTextBoxStyle)
CSS class name to apply to the print view of an item's text box if the item is
canEdit:false , with readOnlyDisplay:static . |
FormItem |
setPrintTextBoxStyle(java.lang.String printTextBoxStyle)
Base CSS class name for a form item's text box element when getting printable HTML for the form.
|
FormItem |
setPrintTitleStyle(java.lang.String printTitleStyle)
Base CSS stylename for a form item's title when generating print HTML for the item.
|
FormItem |
setPrompt(java.lang.String prompt)
This text is shown as a tooltip prompt when the cursor hovers over this item.
|
void |
setProperty(java.lang.String property,
boolean value) |
void |
setProperty(java.lang.String property,
double value) |
void |
setProperty(java.lang.String property,
int value) |
void |
setProperty(java.lang.String property,
com.google.gwt.core.client.JavaScriptObject value) |
void |
setProperty(java.lang.String property,
java.lang.String value) |
FormItem |
setReadOnlyCanSelectText(ReadOnlyDisplayAppearance... readOnlyCanSelectText)
For items showing a text value with
canEdit set to
false, should the user be able to select the text in the item? |
FormItem |
setReadOnlyControlStyle(java.lang.String readOnlyControlStyle)
Modified
control style to apply when this item
is read-only and is using readOnlyDisplay ReadOnlyDisplayAppearance.STATIC . |
FormItem |
setReadOnlyDisplay(ReadOnlyDisplayAppearance readOnlyDisplay)
If this item is
read-only , how should this item be
displayed to the user? If set, overrides the form-level DynamicForm.readOnlyDisplay default. |
FormItem |
setReadOnlyHover(java.lang.String readOnlyHover)
This text is shown as a tooltip prompt when the cursor hovers over this item and the item is
read-only . |
FormItem |
setReadOnlyTextBoxStyle(java.lang.String readOnlyTextBoxStyle)
Base text box style to apply when this item is
read-only and is using readOnlyDisplay
ReadOnlyDisplayAppearance.STATIC . |
FormItem |
setReadOnlyWhen(AdvancedCriteria readOnlyWhen)
Criteria to be evaluated to determine whether this FormItem should be made
read-only . |
FormItem |
setRedrawOnChange(java.lang.Boolean redrawOnChange)
If true, this item will cause the entire form to be redrawn when the item's "elementChanged" event is done firing
|
FormItem |
setRejectInvalidValueOnChange(java.lang.Boolean rejectInvalidValueOnChange)
If validateOnChange is true, and validation fails for this item on change, with no suggested value, should we revert to
the previous value, or continue to display the bad value entered by the user.
|
FormItem |
setRequired(java.lang.Boolean required)
Whether a non-empty value is required for this field to pass validation.
|
FormItem |
setRequiredMessage(java.lang.String requiredMessage)
The required message for required field errors.
|
FormItem |
setRequiredWhen(Criteria requiredWhen)
Criteria to be evaluated to determine whether this FormItem should be
required . |
FormItem |
setRowSpan(int rowSpan)
Number of rows that this item spans
|
FormItem |
setSaveOnEnter(java.lang.Boolean saveOnEnter)
Set this to true to allow the parent form to save it's data when 'Enter' is pressed on this formItem and
saveOnEnter is true on the parent form. |
void |
setScClassName(java.lang.String scClassName)
Set the name of the underlying SmartClient class.
|
FormItem |
setSelectOnClick(java.lang.Boolean selectOnClick)
Allows the
selectOnClick behavior to be configured
on a per-FormItem basis. |
FormItem |
setSelectOnFocus(java.lang.Boolean selectOnFocus)
Allows the
selectOnFocus behavior to be configured
on a per-FormItem basis. |
FormItem |
setShouldSaveValue(java.lang.Boolean shouldSaveValue)
Should this item's value be saved in the form's values and hence returned from
form.getValues() ? |
FormItem |
setShowClippedTitleOnHover(boolean showClippedTitleOnHover)
If true and the title is clipped, then a hover containing the full title of this item is enabled.
|
FormItem |
setShowClippedValueOnHover(java.lang.Boolean showClippedValueOnHover)
If true and the value is clipped, then a hover containing the full value of this item is enabled.
|
FormItem |
setShowDeletions(java.lang.Boolean showDeletions)
For items that support
multiple values , this
causes distinct CSS styling to be applied to values that the user has unselected. |
FormItem |
setShowDisabled(java.lang.Boolean showDisabled)
When this item is disabled, should it be re-styled to indicate its disabled state?
|
FormItem |
setShowDisabledIconsOnFocus(java.lang.Boolean showDisabledIconsOnFocus)
If
showIconsOnFocus is true, should icons
marked as disabled be shown on focus? |
FormItem |
setShowDisabledPickerIconOnFocus(java.lang.Boolean showDisabledPickerIconOnFocus)
If
showPickerIconOnFocus is true,
should the picker icon be shown on focus if it is disabled (as in a read-only item, for example?) |
FormItem |
setShowErrorIcon(java.lang.Boolean showErrorIcon)
showErrorIcons , showErrorText , errorOrientation , and showErrorStyle control how validation errors are
displayed when they are displayed inline in the form (next to the form item where there is a validation error). |
FormItem |
setShowErrorStyle(java.lang.Boolean showErrorStyle)
showErrorIcons , showErrorText , errorOrientation , and showErrorStyle control how validation errors are
displayed when they are displayed inline in the form (next to the form item where there is a validation error). |
FormItem |
setShowErrorText(java.lang.Boolean showErrorText)
showErrorIcons , showErrorText , errorOrientation , and showErrorStyle control how validation errors are
displayed when they are displayed inline in the form (next to the form item where there is a validation error). |
FormItem |
setShowFocused(java.lang.Boolean showFocused)
When this item receives focus, should it be re-styled to indicate it has focus?
|
FormItem |
setShowFocusedErrorState(java.lang.Boolean showFocusedErrorState)
If set to true, when an item has errors and is focused, an "ErrorFocused" suffix will appear on the stylename.
|
FormItem |
setShowFocusedIcons(java.lang.Boolean showFocusedIcons)
If we're showing icons, should we change their image source to the appropriate focused source when this item
has focus? Can be overridden on a per icon basis by the formItemIcon
showFocused property. |
FormItem |
setShowFocusedPickerIcon(java.lang.Boolean showFocusedPickerIcon)
If
showPickerIcon is true for this item,
should the picker icon show a focused image when the form item has focus? |
FormItem |
setShowHint(java.lang.Boolean showHint)
If a hint is defined for this form item, should it be shown?
|
FormItem |
setShowIcons(java.lang.Boolean showIcons)
Set to false to suppress writing out any
icons for
this item. |
FormItem |
setShowIconsOnFocus(java.lang.Boolean showIconsOnFocus)
Show the
icons when the item gets focus, and hide them
when it loses focus. |
void |
setShowIfCondition(FormItemIfFunction showIf)
Expression that's evaluated to see if an item should be dynamically hidden.
|
FormItem |
setShowImageAsURL(java.lang.Boolean showImageAsURL)
For fields of
type:"image" , if the field is non editable, and being
displayed with readOnlyDisplay:"static" ,
should the value (URL) be displayed as text, or should an image be rendered? |
FormItem |
setShowOldValueInHover(java.lang.Boolean showOldValueInHover)
Causes the original value to be shown to the end user when the user hovers over the FormItem as such (when the
FormItem.itemHover() event would fire). |
FormItem |
setShowOver(boolean showOver)
When the user rolls over this item, should it be re-styled to indicate it has focus?
|
FormItem |
setShowOverIcons(java.lang.Boolean showOverIcons)
If we're showing icons, should we change their image source to the appropriate over source when the user rolls
over (or puts focus onto) them? Can be overridden on a per icon basis by the formItemIcon
showOver
property. |
FormItem |
setShowPending(java.lang.Boolean showPending)
When
true , causes the "Pending" optional suffix to be added if the item's current value differs from the
value that would be restored by a call to DynamicForm.resetValues() . |
FormItem |
setShowPickerIcon(java.lang.Boolean showPickerIcon)
Should we show a special 'picker'
icon for this form item?
Picker icons are customizable via pickerIconProperties . |
FormItem |
setShowPickerIconOnFocus(java.lang.Boolean showPickerIconOnFocus)
Show the picker icon when the item gets focus, and hide it when it loses focus.
|
FormItem |
setShowRTL(boolean showRTL)
When this item is in RTL mode, should its style name include an "RTL" suffix?
|
FormItem |
setShowTitle(java.lang.Boolean showTitle)
Should we show a title cell for this formItem?
|
FormItem |
setShowValueIconOnly(java.lang.Boolean showValueIconOnly)
If
valueIcons is set, this property may be set to
show the valueIcon only and prevent the standard form item element or text from displaying |
FormItem |
setStartRow(java.lang.Boolean startRow)
Whether this item should always start a new row in the form layout.
|
void |
setStateCustomizer(FormItem.StateCustomizer customizer)
Specify a StateCustomizer to use for this formItem.
|
FormItem |
setStaticHeight(java.lang.Integer staticHeight)
Height of the FormItem when
canEdit is false and readOnlyDisplay is "static". |
FormItem |
setStopOnError(java.lang.Boolean stopOnError)
Indicates that if validation fails, the user should not be allowed to exit the field - focus will be forced back into
the field until the error is corrected.
|
FormItem |
setStoreDisplayValues(java.lang.Boolean storeDisplayValues)
If specified, this overrides the
DynamicForm.storeDisplayValues property for this field. |
FormItem |
setSupportsCutPasteEvents(boolean supportsCutPasteEvents)
Does the current formItem support native cut and paste events?
|
FormItem |
setSuppressValueIcon(java.lang.Boolean suppressValueIcon)
If
valueIcons is set, this property may be set to
prevent the value icons from showing up next to the form items value |
FormItem |
setSynchronousValidation(java.lang.Boolean synchronousValidation)
If enabled, whenever validation is triggered and a request to the server is required, user interactivity will be blocked
until the request returns.
|
FormItem |
setTabIndex(java.lang.Integer tabIndex)
TabIndex for the form item within the form, which controls the order in which controls are visited when the user hits
the tab or shift-tab keys to navigate between items.
|
FormItem |
setTextAlign(Alignment textAlign)
Alignment of the text / content within this form item.
|
FormItem |
setTextBoxStyle(java.lang.String textBoxStyle)
Base CSS class name for a form item's text box element.
|
FormItem |
setTextFormula(UserSummary textFormula)
Formula to be used to calculate the text value of this FormItem.
|
FormItem |
setTimeFormatter(TimeDisplayFormat timeFormatter)
Time-format to apply to date type values within this formItem.
|
FormItem |
setTitle(java.lang.String title)
User visible title for this form item.
|
FormItem |
setTitleAlign(Alignment titleAlign)
Alignment of this item's title in its cell.
|
FormItem |
setTitleColSpan(int titleColSpan)
Number of columns that this item's title spans.
|
void |
setTitleHoverFormatter(FormItemHoverFormatter hoverFormatter)
Synonym for
setItemTitleHoverFormatter(FormItemHoverFormatter) . |
FormItem |
setTitleOrientation(TitleOrientation titleOrientation)
On which side of this item should the title be placed.
|
FormItem |
setTitleStyle(java.lang.String titleStyle)
Base CSS class name for a form item's title.
|
FormItem |
setTitleVAlign(VerticalAlignment titleVAlign)
Vertical alignment of this item's title in its cell.
|
void |
setTooltip(java.lang.String tooltip)
This text is shown as a tooltip prompt when the cursor hovers over this item.
|
FormItem |
setTop(int top)
Top coordinate of this item in pixels.
|
void |
setType(java.lang.String type)
The DynamicForm picks a field renderer based on the type of the field (and sometimes other attributes of the
field).
|
FormItem |
setUpdateControlOnOver(java.lang.Boolean updateControlOnOver)
If
showOver is true, setting this property to false
will explicitly disable showing the "Over" state for the control table element of this item (if present). |
FormItem |
setUpdatePickerIconOnOver(java.lang.Boolean updatePickerIconOnOver)
If
showOver is true, setting this property to false
will explicitly disable showing the "Over" state for the PickerIcon of this item (if present) |
FormItem |
setUpdateTextBoxOnOver(java.lang.Boolean updateTextBoxOnOver)
If
showOver is true, setting this property to false
will explicitly disable showing the "Over" state for the TextBox element of this item. |
FormItem |
setUseAdvancedCriteria(java.lang.Boolean useAdvancedCriteria)
Should this form item always produce an
AdvancedCriteria sub criterion object? When set
to true, causes hasAdvancedCriteria to
return true. |
FormItem |
setUseDisabledHintStyleForReadOnly(java.lang.Boolean useDisabledHintStyleForReadOnly)
By default,
read-only fields use the same style name
as editable fields for in-field hints, unless they are disabled or configured to use a disabled ReadOnlyDisplayAppearance . |
FormItem |
setUseLocalDisplayFieldValue(java.lang.Boolean useLocalDisplayFieldValue)
If
displayField is specified for a field,
should the display value for the field be picked up from the record currently being edited ? |
FormItem |
setValidateOnChange(java.lang.Boolean validateOnChange)
If true, form items will be validated when each item's "change" handler is fired as well as when the entire form is
submitted or validated.
|
FormItem |
setValidateOnExit(java.lang.Boolean validateOnExit)
If true, form items will be validated when each item's "editorExit" handler is fired as well as when the entire form is
submitted or validated.
|
FormItem |
setValidators(Validator... validators)
Validators for this form item.
|
FormItem |
setValidOperators(OperatorId... validOperators)
Array of valid filtering operators (eg "greaterThan") that are legal for this FormItem.
|
FormItem |
setVAlign(VerticalAlignment vAlign)
Vertical alignment of this item within its cell.
|
void |
setValue(boolean value)
Set the value of the form item.
|
void |
setValue(java.util.Date value)
Set the value of the form item.
|
void |
setValue(double value)
Set the value of the form item.
|
void |
setValue(int value)
Set the value of the form item.
|
void |
setValue(java.lang.Object value)
Set the value of the form item as an object.
|
void |
setValue(java.lang.String value)
Set the value of the form item.
|
FormItem |
setValueDeselectedCSSText(java.lang.String valueDeselectedCSSText)
Custom CSS text to be applied to values that have been deleted, when
showDeletions is enabled. |
FormItem |
setValueField(java.lang.String valueField)
If this form item maps data values to display values by retrieving the
displayField values from an optionDataSource , this property denotes the the
field to use as the underlying data value in records from the optionDataSource.If not explicitly supplied, the valueField name will be derived as described in getValueFieldName() . |
void |
setValueFormatter(FormItemValueFormatter formatter)
Optional
FormItemValueFormatter , if provided, is evaluated to get the
display value to show for this form items underlying data value. |
void |
setValueHoverFormatter(FormItemHoverFormatter hoverFormatter)
Synonym for
setItemValueHoverFormatter(FormItemHoverFormatter) . |
FormItem |
setValueIconHeight(java.lang.Integer valueIconHeight)
If
valueIcons is specified, use this property to
specify a height for the value icon written out. |
FormItem |
setValueIconLeftPadding(int valueIconLeftPadding)
If we're showing a value icon, this attribute governs the amount of space between the icon and the start edge of the
form item cell.
|
void |
setValueIconMapper(ValueIconMapper valueIconMapper)
Set the FormItem Value Icon mapper that allows the developer to specify the image source for an icon to be displayed for the current form item value.
|
FormItem |
setValueIconRightPadding(int valueIconRightPadding)
If we're showing a value icon, this attribute governs the amount of space between the icon and the value text.
|
void |
setValueIcons(java.util.Map valueIcons)
Set the valueIcons for this item.
|
FormItem |
setValueIconSize(int valueIconSize)
If
valueIcons is specified, this property may be
used to specify both the width and height of the icon written out. |
FormItem |
setValueIconWidth(java.lang.Integer valueIconWidth)
If
valueIcons is specified, use this property to
specify a width for the value icon written out. |
void |
setValueMap(java.util.Map valueMap)
Set the valueMap for this item.
|
void |
setValueMap(java.lang.String... valueMap)
Set the valueMap for this item.
|
FormItem |
setVisible(java.lang.Boolean visible)
Whether this item is currently visible.
|
FormItem |
setVisibleWhen(AdvancedCriteria visibleWhen)
Criteria to be evaluated to determine whether this FormItem should be visible.
|
void |
setWarnOnEditorTypeConversion(boolean warn)
Sets whether a warning will be logged if the Framework replaces this SmartGwt FormItem
(that wraps the SmartClient item instance) to more closely match the underlying item's
type when
getOrCreateRef() is called. |
static void |
setWarnOnEditorTypeConversionDefault(boolean warn)
Sets whether, by default, a warning will be logged if the Framework replaces a SmartGWT
FormItem (that wraps the SmartClient item instance) to more closely match the underlying
item's type.
|
FormItem |
setWidth(int width)
Width of the FormItem.
|
FormItem |
setWidth(java.lang.String width)
Width of the FormItem.
|
FormItem |
setWrapHintText(java.lang.Boolean wrapHintText)
If this item is showing a
hint , should the hint text be
allowed to wrap? Setting this property to false will render the hint on a single line without wrapping,
expanding the width required to render the item if necessary. |
FormItem |
setWrapStaticValue(java.lang.Boolean wrapStaticValue)
If this item is
read-only and is using readOnlyDisplay ReadOnlyDisplayAppearance.STATIC , should the item value wrap? |
FormItem |
setWrapTitle(java.lang.Boolean wrapTitle)
If specified determines whether this items title should wrap.
|
boolean |
shouldApplyHeightToTextBox()
If
height is specified, should it be applied to the
item's text box element? If this method returns false, the text box will not have an explicit height applied, though the
containing cell will be sized to accommodate any specified height. |
java.lang.Boolean |
shouldFetchMissingValue(java.lang.Object newValue)
If this field has a specified
optionDataSource , should we perform a fetch against that dataSource to find the record that matches this field's value? |
java.lang.Boolean |
shouldSaveOnEnter()
Returns true if 'Enter' key presses in this formItem should allow a saveOnEnter: true parent form to save it's data.
|
boolean |
shouldStopKeyPressBubbling(java.lang.String keyName,
int characterValue)
Should some keypress event on this item be prevented from bubbling (such that the containing form and ancestors do not
receive the event).
|
void |
show()
Show this form item.
|
void |
showIcon(java.lang.String icon)
This method will show some icon in this item's
icons
array, if it is not already visible. |
void |
showPicker()
Method to show a picker for this item.
|
void |
stopHover()
This method is fired when the user rolls off this item (or the title for this item) and will clear any hover canvas
shown by the item.
|
void |
storeValue(java.lang.Object value)
Store (and optionally show) a value for this form item.
|
void |
storeValue(java.lang.Object value,
java.lang.Boolean showValue)
Store (and optionally show) a value for this form item.
|
void |
updateState()
Update the visual state of a FormItem to reflect any changes in state or any changes in style settings (e.g.
|
java.lang.Boolean |
validate()
Validate this item.
|
boolean |
valueClipped()
Is the value clipped?
|
getRef, getRef, internalSetID
applyFactoryProperties, doAddHandler, fireEvent, getAttributeAsDoubleArray, getAttributeAsElement, getAttributeAsIntArray, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsStringArray, getAttributes, getHandlerCount, isFactoryCreated, setAttribute, setAttribute, setAttribute, setAttributeAsJavaObject, setFactoryCreated
protected java.lang.String scClassName
protected boolean configOnly
protected static boolean warnOnEditorTypeConversionDefault
protected boolean warnOnEditorTypeConversion
public FormItem()
public FormItem(com.google.gwt.core.client.JavaScriptObject jsObj)
public FormItem(java.lang.String name)
public static FormItem getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)
public java.util.Map getPaletteDefaults()
PaletteNode
. Use it when you need to
work with PaletteNodes indirectly, such when setting up
TileRecord
s that will be used in a
TilePalette
. See
the dev tools overview
for examples of how to
assemble and acquire a suitable defaults object when you are creating a PaletteNode
indirectlypublic 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 FormItem setAccessKey(java.lang.String accessKey)
This should be set to a character - when a user hits the html accessKey modifier for the browser, plus this character, focus will be given to the item. The accessKey modifier can vary by browser and platform.
The following list of default behavior is for reference only, developers should also consult browser documentation for additional information.
Alt
+ accessKeyAlt+Shift
+
accessKeyCtrl+Opt
+ accessKeyAlt
+ accessKeyCtrl+Opt
+ accessKeyaccessKey
- New accessKey value. Default value is nullFormItem
instance, for chaining setter callsFocus overview and related methods
public java.lang.String getAccessKey()
This should be set to a character - when a user hits the html accessKey modifier for the browser, plus this character, focus will be given to the item. The accessKey modifier can vary by browser and platform.
The following list of default behavior is for reference only, developers should also consult browser documentation for additional information.
Alt
+ accessKeyAlt+Shift
+
accessKeyCtrl+Opt
+ accessKeyAlt
+ accessKeyCtrl+Opt
+ accessKeyFocus overview and related methods
public FormItem setAlign(Alignment align)
textAlign
(typically textAlign
applies to items showing a "textBox", such as a TextItem
or SelectItem
, as well as text-only form item types such as StaticTextItem
and HeaderItem
).
If applyAlignToText
is true, then the
textAlign
setting, if unset, will default to the align
setting if set.align
- New align value. Default value is nullFormItem
instance, for chaining setter callssetApplyAlignToText(boolean)
,
Appearance overview and related methods
public Alignment getAlign()
textAlign
(typically textAlign
applies to items showing a "textBox", such as a TextItem
or SelectItem
, as well as text-only form item types such as StaticTextItem
and HeaderItem
).
If applyAlignToText
is true, then the
textAlign
setting, if unset, will default to the align
setting if set.getApplyAlignToText()
,
Appearance overview and related methods
public FormItem setAllowExpressions(java.lang.Boolean allowExpressions)
form.getValuesAsCriteria()
), allows the user to type in simple expressions to cause filtering with that operator. For
example, entering ">5" means values greater than 5, and ">0 and <5" means values between 0 and 5. The
following table lists character sequences that can be entered as a prefix to a value, and the corresponding operator
that will be used.
Prefix | Operator |
< | lessThan |
> | greaterThan |
<= | lessThanOrEqual |
>= | greaterThanOrEqual |
someValue...someValue | betweenInclusive |
! | notEqual |
^ | startsWith |
| | endsWith |
!^ | notStartsWith plus logical not |
!@ | notEndsWith plus logical not |
~ | contains |
!~ | notContains |
$ | isBlank |
!$ | notBlank |
# | isNull |
!# | isNotNull |
== | exact match (for fields where 'contains' is the default) |
Two further special notations are allowed:
In all cases, if
an operator is disallowed for the field (via field.validOperators
at either the dataSource or field level), the operator character is ignored (treated as part of a
literal value).
By default, the case-insensitive version of the operator is used (eg, startsWith will actually use "iStartsWith"). To avoid this, explicitly set item.operator (the default operator) to any case sensitive operator (eg "equals" or "contains") and case sensitive operators will be used for user-entered expressions.
Compound expressions (including "and" and "or") are allowed only for numeric or date/time types.
Note that if the user does not type a
prefix or use other special notation as described above, the operator specified via operator
is used, or if formItem.operator
is
unspecified, a default operator chosen as described under operator
.
Also note that whatever you enter will be used literally, including any whitespace characters. For example if you input '== China ' then ' China ' will be the value.
The allowExpression
behavior can be enabled for every field in a form via DynamicForm.allowExpressions
.
Finally, note that,
like operator
, enabling
allowExpressions:true
causes form.getValuesAsCriteria()
) to return AdvancedCriteria
.
allowExpressions
- New allowExpressions value. Default value is nullFormItem
instance, for chaining setter callsAdvancedFilter overview and related methods
public java.lang.Boolean getAllowExpressions()
form.getValuesAsCriteria()
), allows the user to type in simple expressions to cause filtering with that operator. For
example, entering ">5" means values greater than 5, and ">0 and <5" means values between 0 and 5. The
following table lists character sequences that can be entered as a prefix to a value, and the corresponding operator
that will be used.
Prefix | Operator |
< | lessThan |
> | greaterThan |
<= | lessThanOrEqual |
>= | greaterThanOrEqual |
someValue...someValue | betweenInclusive |
! | notEqual |
^ | startsWith |
| | endsWith |
!^ | notStartsWith plus logical not |
!@ | notEndsWith plus logical not |
~ | contains |
!~ | notContains |
$ | isBlank |
!$ | notBlank |
# | isNull |
!# | isNotNull |
== | exact match (for fields where 'contains' is the default) |
Two further special notations are allowed:
In all cases, if
an operator is disallowed for the field (via field.validOperators
at either the dataSource or field level), the operator character is ignored (treated as part of a
literal value).
By default, the case-insensitive version of the operator is used (eg, startsWith will actually use "iStartsWith"). To avoid this, explicitly set item.operator (the default operator) to any case sensitive operator (eg "equals" or "contains") and case sensitive operators will be used for user-entered expressions.
Compound expressions (including "and" and "or") are allowed only for numeric or date/time types.
Note that if the user does not type a
prefix or use other special notation as described above, the operator specified via operator
is used, or if formItem.operator
is
unspecified, a default operator chosen as described under operator
.
Also note that whatever you enter will be used literally, including any whitespace characters. For example if you input '== China ' then ' China ' will be the value.
The allowExpression
behavior can be enabled for every field in a form via DynamicForm.allowExpressions
.
Finally, note that,
like operator
, enabling
allowExpressions:true
causes form.getValuesAsCriteria()
) to return AdvancedCriteria
.
AdvancedFilter overview and related methods
public FormItem setAlwaysFetchMissingValues(java.lang.Boolean alwaysFetchMissingValues)
optionDataSource
and fetchMissingValues
is true, when the item value changes, a fetch will be performed against the optionDataSource to retrieve the related
record if displayField
is specified and the
new item value is not present in any valueMap explicitly specified on the item. Setting this property to true means
that a fetch will occur against the optionDataSource to retrieve the related record even if displayField
is unset, or the item has a valueMap
which explicitly contains this field's value.
An example of a use case where this might be set would be if formatValue()
or formatEditorValue()
were written to display
properties from the selected record
.
Note
- for efficiency we cache the associated record once a fetch has been performed, meaning if the value changes, then
reverts to a previously seen value, we do not kick off an additional fetch even if this property is true. If necessary
this cache may be explicitly invalidated via a call to invalidateDisplayValueCache()
Note : This is an advanced setting
alwaysFetchMissingValues
- New alwaysFetchMissingValues value. Default value is falseFormItem
instance, for chaining setter callspublic java.lang.Boolean getAlwaysFetchMissingValues()
optionDataSource
and fetchMissingValues
is true, when the item value changes, a fetch will be performed against the optionDataSource to retrieve the related
record if displayField
is specified and the
new item value is not present in any valueMap explicitly specified on the item. Setting this property to true means
that a fetch will occur against the optionDataSource to retrieve the related record even if displayField
is unset, or the item has a valueMap
which explicitly contains this field's value.
An example of a use case where this might be set would be if formatValue()
or formatEditorValue()
were written to display
properties from the selected record
.
Note
- for efficiency we cache the associated record once a fetch has been performed, meaning if the value changes, then
reverts to a previously seen value, we do not kick off an additional fetch even if this property is true. If necessary
this cache may be explicitly invalidated via a call to invalidateDisplayValueCache()
public FormItem setAlwaysShowControlBox(java.lang.Boolean alwaysShowControlBox)
pickerIcon
will always
write out a "control box" around the text box and picker icon. This is an HTML element styled using the specified controlStyle
. This attribute controls whether the
control box should be written out even if the picker icon is not being shown. If unset, default behavior will write out
a control table if showPickerIcon
is true and
the icon is not suppressed via FormItemIcon.showIf()
. This means the control table can be written out with no visible picker if showPickerIconOnFocus
is true and the item
does not have focus.
This attribute is useful for developers who wish to rely on styling specified via the controlStyle
even while the picker icon is not
visible.
See the form item styling overview
for details of the
control table and other styling options.
Note : This is an advanced setting
alwaysShowControlBox
- New alwaysShowControlBox value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getAlwaysShowControlBox()
pickerIcon
will always
write out a "control box" around the text box and picker icon. This is an HTML element styled using the specified controlStyle
. This attribute controls whether the
control box should be written out even if the picker icon is not being shown. If unset, default behavior will write out
a control table if showPickerIcon
is true and
the icon is not suppressed via FormItemIcon.showIf()
. This means the control table can be written out with no visible picker if showPickerIconOnFocus
is true and the item
does not have focus.
This attribute is useful for developers who wish to rely on styling specified via the controlStyle
even while the picker icon is not
visible.
See the form item styling overview
for details of the
control table and other styling options.
public FormItem setApplyAlignToText(boolean applyAlignToText)
textAlign
is unset, should the align
setting, if set, be used for this item's
textAlign
? applyAlignToText
defaults to false for most form item types. It defaults to
true for StaticTextItem
and HeaderItem
, which are text-based form item types that do not have a natural
distinction between the item and its cell.
Note : This is an advanced setting
applyAlignToText
- New applyAlignToText value. Default value is falseFormItem
instance, for chaining setter callsAppearance overview and related methods
public boolean getApplyAlignToText()
textAlign
is unset, should the align
setting, if set, be used for this item's
textAlign
? applyAlignToText
defaults to false for most form item types. It defaults to
true for StaticTextItem
and HeaderItem
, which are text-based form item types that do not have a natural
distinction between the item and its cell.
Appearance overview and related methods
public FormItem setApplyHeightToTextBox(java.lang.Boolean applyHeightToTextBox)
height
is specified, should it be applied to the
item's text box element? If unset, behavior is determined as described in shouldApplyHeightToTextBox()
Note : This is an advanced setting
applyHeightToTextBox
- New applyHeightToTextBox value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getApplyHeightToTextBox()
height
is specified, should it be applied to the
item's text box element? If unset, behavior is determined as described in shouldApplyHeightToTextBox()
public FormItem setAriaRole(java.lang.String ariaRole)
Accessibility
.
Note : This is an advanced setting
ariaRole
- New ariaRole value. Default value is nullFormItem
instance, for chaining setter callsAccessibility overview and related methods
public java.lang.String getAriaRole()
Accessibility
.Accessibility overview and related methods
public FormItem setAutoComplete(AutoComplete autoComplete)
TextItem
, PasswordItem
,
etc), and will only have a user-visible impact for browsers where native autoComplete behavior is actually supported and
enabled via user settings. Alternatively, autoCompleteKeywords
can be specified, in
which case this setting is ignored. If autoCompleteKeywords
are not provided, and
autoComplete
is not set on this FormItem, the value of DynamicForm.autoComplete
is used.
Note that even with
this value set to "none"
, native browser auto-completion may occur for log in forms (forms containing
username and password
fields). This behavior varies by
browser, and is a result of an intentional change by some browser developers to disregard the HTML setting autocomplete=off
for password items or log-in forms.
In some browsers any form redraw (including a redraw from a call to DynamicForm.setValues()
) will re-populate the form with the
natively remembered login credentials. This can make it very difficult to control the values displayed to the user, as
a call to 'setValues()' may appear to be ignored. While behavior varies by browser we have specifically observed this
behavior in Safari. Moreover in this browser, if the user asks the browser to remember login credentials for a URL, any
form with a password item and a text item may be auto-filled with the remembered login credentials, even if the form's
configuration and field names differ from those on the login form.
If an application has both an initial log in form, and a separate form within the application which makes contains a Password item (a use case might be an interface for a user with manager privileges for modifying other users' passwords), this will cause the second form to autofill with unexpected values.
Should this arise, developers can avoid this by making the initial log in interface into a separate log in page from the main application page. This is often good practice in any case for reasons outlined in the "Authentication" section of the Quick Start guide.
autoComplete
- New autoComplete value. Default value is nullFormItem
instance, for chaining setter callsDynamicForm.setAutoComplete(com.smartgwt.client.types.AutoComplete)
public AutoComplete getAutoComplete()
TextItem
, PasswordItem
,
etc), and will only have a user-visible impact for browsers where native autoComplete behavior is actually supported and
enabled via user settings. Alternatively, autoCompleteKeywords
can be specified, in
which case this setting is ignored. If autoCompleteKeywords
are not provided, and
autoComplete
is not set on this FormItem, the value of DynamicForm.autoComplete
is used.
Note that even with
this value set to "none"
, native browser auto-completion may occur for log in forms (forms containing
username and password
fields). This behavior varies by
browser, and is a result of an intentional change by some browser developers to disregard the HTML setting autocomplete=off
for password items or log-in forms.
In some browsers any form redraw (including a redraw from a call to DynamicForm.setValues()
) will re-populate the form with the
natively remembered login credentials. This can make it very difficult to control the values displayed to the user, as
a call to 'setValues()' may appear to be ignored. While behavior varies by browser we have specifically observed this
behavior in Safari. Moreover in this browser, if the user asks the browser to remember login credentials for a URL, any
form with a password item and a text item may be auto-filled with the remembered login credentials, even if the form's
configuration and field names differ from those on the login form.
If an application has both an initial log in form, and a separate form within the application which makes contains a Password item (a use case might be an interface for a user with manager privileges for modifying other users' passwords), this will cause the second form to autofill with unexpected values.
Should this arise, developers can avoid this by making the initial log in interface into a separate log in page from the main application page. This is often good practice in any case for reasons outlined in the "Authentication" section of the Quick Start guide.
DynamicForm.getAutoComplete()
public FormItem setAutoCompleteKeywords(java.lang.String... autoCompleteKeywords)
When autoCompleteKeywords are provided, the autoComplete
setting is ignored.
autoCompleteKeywords
- New autoCompleteKeywords value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.String[] getAutoCompleteKeywords()
When autoCompleteKeywords are provided, the autoComplete
setting is ignored.
public FormItem setBrowserInputType(java.lang.String browserInputType)
Note : This is an advanced setting
browserInputType
- New browserInputType value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.String getBrowserInputType()
public FormItem setBrowserSpellCheck(java.lang.Boolean browserSpellCheck)
Notes:
- this property only applies to text based items
such as TextItem and TextAreaItem.
- this property is not supported on all browsers.
Note : This is an advanced setting
browserSpellCheck
- New browserSpellCheck value. Default value is nullFormItem
instance, for chaining setter callsDynamicForm.setBrowserSpellCheck(java.lang.Boolean)
public java.lang.Boolean getBrowserSpellCheck()
Notes:
- this property only applies to text based items
such as TextItem and TextAreaItem.
- this property is not supported on all browsers.
DynamicForm.getBrowserSpellCheck()
public FormItem setCanEdit(java.lang.Boolean canEdit)
setCanEdit()
method. Read-only appearance may be
specified via readOnlyDisplay
. The default
setting for this value ("readOnly"
) differs from the disabled state in that the form item is not rendered
with disabled styling and most form items will allow copying of the contents while read-only but do not while disabled.
Note that for forms bound to a DataSource
, if this property is not explicitly set
at the item level, its default value will match the DynamicForm.canEditFieldAttribute
on the
associated dataSource field.
Developers should also be aware that the readOnlyDisplay
attribute is unrelated to the
DataSourceField.readOnlyEditorType
attribute.
When a DynamicForm is first bound to a dataSource, for canEdit:false
DataSourceFields, DataSourceField.readOnlyEditorType
will determine what FormItemType
should be created
for the field. Once created, a FormItem's type can not be changed. Setting canEdit
at runtime will simply change the appearance of the
item to allow or disallow editing of the item.
Note that this property may validly be null
as a distinct
state from false
. See DynamicForm.fieldIsEditable()
for an API that will always return true
or false
and give a
definitive answer as to whether editing is possible.
If this method is called after the component has been drawn/initialized:
Is this form item editable (canEdit:true) or read-only (canEdit:false)? Setting the form item to non-editable causes it to render as read-only, using the appearance specified via readOnlyDisplay
.
The default appearance for canEdit:false items (readOnlyDisplay:"readOnly"
) differs from the disabled state in that the form item is not rendered with disabled styling and most form items will allow copying of the contents while read-only but do not while disabled.
canEdit
- Can this form item be edited?. Default value is nullFormItem
instance, for chaining setter callssetCanEdit(java.lang.Boolean)
,
DynamicForm.setCanEdit(java.lang.Boolean)
public java.lang.Boolean getCanEdit()
setCanEdit()
method. Read-only appearance may be
specified via readOnlyDisplay
. The default
setting for this value ("readOnly"
) differs from the disabled state in that the form item is not rendered
with disabled styling and most form items will allow copying of the contents while read-only but do not while disabled.
Note that for forms bound to a DataSource
, if this property is not explicitly set
at the item level, its default value will match the DynamicForm.canEditFieldAttribute
on the
associated dataSource field.
Developers should also be aware that the readOnlyDisplay
attribute is unrelated to the
DataSourceField.readOnlyEditorType
attribute.
When a DynamicForm is first bound to a dataSource, for canEdit:false
DataSourceFields, DataSourceField.readOnlyEditorType
will determine what FormItemType
should be created
for the field. Once created, a FormItem's type can not be changed. Setting canEdit
at runtime will simply change the appearance of the
item to allow or disallow editing of the item.
Note that this property may validly be null
as a distinct
state from false
. See DynamicForm.fieldIsEditable()
for an API that will always return true
or false
and give a
definitive answer as to whether editing is possible.
This setting differs from the enabled/disabled state in that most form items will allow copying of the contents while read-only but do not while disabled.
Important note: this
method is not intended as an override point to make an item conditionally read-only. It is not called at the appropriate
times to serve as a dynamic control over editability. Developers may instead use readOnlyWhen rules
to dynamically control editability
of items. Default value is null
setCanEdit(java.lang.Boolean)
,
DynamicForm.setCanEdit(java.lang.Boolean)
public FormItem setCanEditOpaqueValues(java.lang.Boolean canEditOpaqueValues)
SimpleType system
to convert these opaque values into "atomic" values that can be
edited by the built-in editors like TextItem
. However, sometimes you
to create a custom editor that knows how to edit a particular opaque type in a domain-specific way - for example, a
composite custom FormItem that allows the user to edit both a number and a currency code, both of which are needed to
make a proper monetary amount (for that particular application). When this value is set, the FormItem will manage the
opaque value directly, rather than it being filtered through calls to getAtomicValue()
and updateAtomicValue()
. Note, if you set this flag on a FormItem
that does not have the ability to edit an opaque value (which is something that must be custom-coded) then you will get
garbage in your editor, if not an outright crash.
Note : This is an advanced setting
canEditOpaqueValues
- New canEditOpaqueValues value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getCanEditOpaqueValues()
SimpleType system
to convert these opaque values into "atomic" values that can be
edited by the built-in editors like TextItem
. However, sometimes you
to create a custom editor that knows how to edit a particular opaque type in a domain-specific way - for example, a
composite custom FormItem that allows the user to edit both a number and a currency code, both of which are needed to
make a proper monetary amount (for that particular application). When this value is set, the FormItem will manage the
opaque value directly, rather than it being filtered through calls to getAtomicValue()
and updateAtomicValue()
. Note, if you set this flag on a FormItem
that does not have the ability to edit an opaque value (which is something that must be custom-coded) then you will get
garbage in your editor, if not an outright crash.public FormItem setCanFocus(java.lang.Boolean canFocus)
StaticTextItem
will cause the item to be included in the page's tab order and
respond to keyboard events.
Note : This is an advanced setting
canFocus
- New canFocus value. Default value is nullFormItem
instance, for chaining setter callsFocus overview and related methods
public java.lang.Boolean getCanFocus()
StaticTextItem
will cause the item to be included in the page's tab order and
respond to keyboard events.TextItems
, TextAreaItems
, etc), CanvasItems
with a focusable canvas,
or items where canFocus
was explicitly set to true. Default value is nullFocus overview and related methods
public FormItem setCanSelectText(boolean canSelectText)
For canEdit:false
items, see readOnlyCanSelectText
canSelectText
- New canSelectText value. Default value is trueFormItem
instance, for chaining setter callspublic boolean getCanSelectText()
For canEdit:false
items, see readOnlyCanSelectText
public FormItem setCanTabToIcons(java.lang.Boolean canTabToIcons)
icons
and picker icon
be included in the page's tab order by
default? If not explicitly set, this property will be derived from DynamicForm.canTabToIcons
. Developers may also
suppress tabbing to individual icons by setting FormItemIcon.tabIndex
to -1
.
Note that if this form item has tabIndex -1, neither the form item nor the icons will be included in the page's tab order.
Note : This is an advanced setting
canTabToIcons
- New canTabToIcons value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getCanTabToIcons()
icons
and picker icon
be included in the page's tab order by
default? If not explicitly set, this property will be derived from DynamicForm.canTabToIcons
. Developers may also
suppress tabbing to individual icons by setting FormItemIcon.tabIndex
to -1
.
Note that if this form item has tabIndex -1, neither the form item nor the icons will be included in the page's tab order.
public FormItem setCellHeight(java.lang.Integer cellHeight)
itemLayout:"absolute"
.cellHeight
- New cellHeight value. Default value is nullFormItem
instance, for chaining setter callsFormItemStyling overview and related methods
public java.lang.Integer getCellHeight()
itemLayout:"absolute"
.FormItemStyling overview and related methods
public FormItem setCellStyle(java.lang.String cellStyle)
See FormItemStyling
for an overview
of formItem styling, and the CompoundFormItem_skinning
discussion for special skinning
considerations.
If this method is called after the component has been drawn/initialized:
Setter for cellStyle
.
cellStyle
- the new cellStyle
value. Default value is "formCell"FormItem
instance, for chaining setter callsFormItemBaseStyle
,
FormItemStyling overview and related methods
public java.lang.String getCellStyle()
See FormItemStyling
for an overview
of formItem styling, and the CompoundFormItem_skinning
discussion for special skinning
considerations.
FormItemBaseStyle
,
FormItemStyling overview and related methods
public FormItem setChangeOnKeypress(java.lang.Boolean changeOnKeypress)
change
handler
(and store its value in the form) on every keypress? Set to false
to suppress the 'change' handler firing
(and the value stored) on every keypress. Note: If false
, the value returned by getValue
will not reflect the value displayed in the form
item element as long as focus is in the form item element.
changeOnKeypress
- New changeOnKeypress value. Default value is trueFormItem
instance, for chaining setter callspublic java.lang.Boolean getChangeOnKeypress()
change
handler
(and store its value in the form) on every keypress? Set to false
to suppress the 'change' handler firing
(and the value stored) on every keypress. Note: If false
, the value returned by getValue
will not reflect the value displayed in the form
item element as long as focus is in the form item element.
public FormItem setClipStaticValue(java.lang.Boolean clipStaticValue)
read-only
and is using readOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
, should the item value be clipped if it overflows the
specified size of the item? If set, overrides the form-level DynamicForm.clipStaticValue
default.clipStaticValue
- New clipStaticValue value. Default value is nullFormItem
instance, for chaining setter callsDynamicForm.setClipStaticValue(java.lang.Boolean)
public java.lang.Boolean getClipStaticValue()
read-only
and is using readOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
, should the item value be clipped if it overflows the
specified size of the item? If set, overrides the form-level DynamicForm.clipStaticValue
default.DynamicForm.getClipStaticValue()
public FormItem setClipTitle(java.lang.Boolean clipTitle)
Null by default - if set to true or false, overrides DynamicForm.clipItemTitles
.
clipTitle
- New clipTitle value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getClipTitle()
Null by default - if set to true or false, overrides DynamicForm.clipItemTitles
.
public Canvas getContainerWidget()
DynamicForm
containing the item but in some cases editable
components handle writing out form items directly. An example of this is Grid
Editing
- when a listGrid shows per-field editors, the containerWidget
for each item will be the listGrid
body. Note that even if the containerWidget
is not a DynamicForm, a DynamicForm will still exist for
the item (available as form
), allowing access to
standard APIs such as DynamicForm.getValues()
public FormItem setControlStyle(java.lang.String controlStyle)
See alwaysShowControlBox
for details on when the control box is written out.
See FormItemStyling
for an overview of formItem styling, and the CompoundFormItem_skinning
discussion for special skinning considerations.
controlStyle
- New controlStyle value. Default value is nullFormItem
instance, for chaining setter callssetCellStyle(java.lang.String)
,
FormItemBaseStyle
,
FormItemStyling overview and related methods
public java.lang.String getControlStyle()
See alwaysShowControlBox
for details on when the control box is written out.
See FormItemStyling
for an overview of formItem styling, and the CompoundFormItem_skinning
discussion for special skinning considerations.
getCellStyle()
,
FormItemBaseStyle
,
FormItemStyling overview and related methods
public FormItem setCriteriaField(java.lang.String criteriaField)
operator
, the name of the DataSource
field for the Criterion
this FormItem generates. If not specified, defaults to name
. Generally, because criteriaField
defaults to item.name
, you don't need to specify it. However, if more than one FormItem specifies criteria
for the same DataSource field, they will need unique values for name
but should set criteriaField
to the name of DataSource field they
both target.
For example, if two DateItems are used to provide a min and max date for a single field called
"joinDate", set criteriaField
to "joinDate" on
both fields but give the fields distinct names (eg "minDate" and "maxDate") and use those names for any programmatic
access, such as DynamicForm.setValue()
.
public java.lang.String getCriteriaField()
operator
, the name of the DataSource
field for the Criterion
this FormItem generates. If not specified, defaults to name
. Generally, because criteriaField
defaults to item.name
, you don't need to specify it. However, if more than one FormItem specifies criteria
for the same DataSource field, they will need unique values for name
but should set criteriaField
to the name of DataSource field they
both target.
For example, if two DateItems are used to provide a min and max date for a single field called
"joinDate", set criteriaField
to "joinDate" on
both fields but give the fields distinct names (eg "minDate" and "maxDate") and use those names for any programmatic
access, such as DynamicForm.setValue()
.
FieldName
public FormItem setDataPath(java.lang.String dataPath)
NOTE:
the dataPath feature is intended to help certain legacy architectures, such as systems that work in terms of exchanging
large messages with several different entity types in one message, and are incapable of providing separate access to
each entity type.
See the DataPath overview
for more information.
Note that an item must have a valid dataPath or name
in
order for its value to be validated and/or saved.
public java.lang.String getDataPath()
NOTE:
the dataPath feature is intended to help certain legacy architectures, such as systems that work in terms of exchanging
large messages with several different entity types in one message, and are incapable of providing separate access to
each entity type.
See the DataPath overview
for more information.
Note that an item must have a valid dataPath or name
in
order for its value to be validated and/or saved.
DataPath
public FormItem setDateFormatter(DateDisplayFormat dateFormatter)
Note that Fields of type "date"
,
"datetime"
or "time"
will be edited using a DateItem
or TimeItem
by
default, but this can be overridden - for canEdit:false
fields, a StaticTextItem
is used by default, and the developer can always specify a
custom editorType
as well as data type
.
The timeFormatter
may also be used to format underlying
Date values as times (ommitting the date part entirely). If both dateFormatter
and
timeFormatter
are specified on an item, for fields specified as type "time"
the timeFormatter
will be used,
otherwise the dateFormatter
If item.dateFormatter
and item.timeFormatter
is
unspecified, date display format may be defined at the component level via DynamicForm.dateFormatter
, or for fields of type
"datetime"
DynamicForm.datetimeFormatter
. Otherwise the default is to use the system-wide default short date format, configured
via DateUtil.setShortDisplayFormat()
. Specify any valid
DateDisplayFormat
to change the format used by this item.
Note that if this is a
freeform editable field, such a TextItem
, with type specified as
"date"
or "datetime"
the system will automatically attempt to parse user entered values back
to a Date value, assuming the entered string matches the date format for the field. Developers may further customize
this via an explicit inputFormat
or via entirely
custom setEditorValueFormatter
and setEditorValueParser
methods.
Note : This is an advanced setting
dateFormatter
- New dateFormatter value. Default value is nullFormItem
instance, for chaining setter callssetTimeFormatter(com.smartgwt.client.types.TimeDisplayFormat)
,
setFormat(java.lang.String)
,
Appearance overview and related methods
public DateDisplayFormat getDateFormatter()
Note that Fields of type "date"
,
"datetime"
or "time"
will be edited using a DateItem
or TimeItem
by
default, but this can be overridden - for canEdit:false
fields, a StaticTextItem
is used by default, and the developer can always specify a
custom editorType
as well as data type
.
The timeFormatter
may also be used to format underlying
Date values as times (ommitting the date part entirely). If both dateFormatter
and
timeFormatter
are specified on an item, for fields specified as type "time"
the timeFormatter
will be used,
otherwise the dateFormatter
If item.dateFormatter
and item.timeFormatter
is
unspecified, date display format may be defined at the component level via DynamicForm.dateFormatter
, or for fields of type
"datetime"
DynamicForm.datetimeFormatter
. Otherwise the default is to use the system-wide default short date format, configured
via DateUtil.setShortDisplayFormat()
. Specify any valid
DateDisplayFormat
to change the format used by this item.
Note that if this is a
freeform editable field, such a TextItem
, with type specified as
"date"
or "datetime"
the system will automatically attempt to parse user entered values back
to a Date value, assuming the entered string matches the date format for the field. Developers may further customize
this via an explicit inputFormat
or via entirely
custom setEditorValueFormatter
and setEditorValueParser
methods.
getTimeFormatter()
,
getFormat()
,
Appearance overview and related methods
public FormItem setDecimalPad(java.lang.Integer decimalPad)
For example, a field value of 343.1, 343.104 and 343.09872677 would all be shown as 343.10 if decimalPad is 2.
The original unpadded value is always shown when the value is edited.
decimalPad
- New decimalPad value. Default value is nullFormItem
instance, for chaining setter callsAppearance overview and related methods
public java.lang.Integer getDecimalPad()
For example, a field value of 343.1, 343.104 and 343.09872677 would all be shown as 343.10 if decimalPad is 2.
The original unpadded value is always shown when the value is edited.
Appearance overview and related methods
public FormItem setDecimalPrecision(java.lang.Integer decimalPrecision)
For example, with decimalPrecision 3, if the field value is 343.672677, 343.673 is shown.
If the value is 125.2, 125.2 is shown -
decimalPrecision will not cause extra zeros to be added. Use DataSourceField.decimalPad
for this.
A number is always shown with its original precision when edited.
decimalPrecision
- New decimalPrecision value. Default value is nullFormItem
instance, for chaining setter callsAppearance overview and related methods
public java.lang.Integer getDecimalPrecision()
For example, with decimalPrecision 3, if the field value is 343.672677, 343.673 is shown.
If the value is 125.2, 125.2 is shown -
decimalPrecision will not cause extra zeros to be added. Use DataSourceField.decimalPad
for this.
A number is always shown with its original precision when edited.
Appearance overview and related methods
public FormItem setDefaultIconSrc(java.lang.String defaultIconSrc)
icon.src
property.icon.showOver
is true, this url will be modified by adding "_Over" to get an over state image for the icon.
Spriting
can be used for this image, by setting this property to a SCSpriteConfig
formatted string.
Note : This is an advanced setting
public java.lang.String getDefaultIconSrc()
icon.src
property.icon.showOver
is true, this url will be modified by adding "_Over" to get an over state image for the icon.
Spriting
can be used for this image, by setting this property to a SCSpriteConfig
formatted string.
SCImgURL
public FormItem setDefaultOperator(OperatorId defaultOperator)
filter-expressions
.defaultOperator
- New defaultOperator value. Default value is nullFormItem
instance, for chaining setter callsAdvancedFilter overview and related methods
public OperatorId getDefaultOperator()
filter-expressions
.AdvancedFilter overview and related methods
public java.lang.Boolean getDestroyed()
public FormItem setDisabled(java.lang.Boolean disabled)
setDisabled()
method. Note that if the
widget containing this formItem is disabled, the formItem will behave in a disabled manner regardless of the setting of
the item.disabled property. Note that not all items can be disabled, and not all browsers show an obvious disabled
style for native form elements.
If this method is called after the component has been drawn/initialized:
Set this item to be enabled or disabled at runtime.
disabled
- true if this item should be disabled. Default value is falseFormItem
instance, for chaining setter callssetDisabled(java.lang.Boolean)
,
Appearance overview and related methods
,
Enable & Disable Examplepublic FormItem setDisabledHover(java.lang.String disabledHover)
disabled
or read-only
with readOnlyDisplay:disabled
. You can also override
itemHoverHTML
on the item to show a custom hover,
whether or not the item is disabled.
Note that when the form itself is disabled
, no prompt will be shown.
disabledHover
- New disabledHover value. Default value is nullFormItem
instance, for chaining setter callsHTMLString
public java.lang.String getDisabledHover()
disabled
or read-only
with readOnlyDisplay:disabled
. You can also override
itemHoverHTML
on the item to show a custom hover,
whether or not the item is disabled.
Note that when the form itself is disabled
, no prompt will be shown.
HTMLString
public FormItem setDisableIconsOnReadOnly(java.lang.Boolean disableIconsOnReadOnly)
canEdit
is set to false, should icons
be disabled by default? This may also be specified
at the icon level. See FormItemIcon.disableOnReadOnly
.
disableIconsOnReadOnly
- New disableIconsOnReadOnly value. Default value is trueFormItem
instance, for chaining setter callspublic java.lang.Boolean getDisableIconsOnReadOnly()
canEdit
is set to false, should icons
be disabled by default? This may also be specified
at the icon level. See FormItemIcon.disableOnReadOnly
.
public FormItem 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 useLocalDisplayFieldValue
is true, (or if unset and the conditions outlined in the documentation for that property are
met).
If this field has an 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 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 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 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
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, 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.
displayField
- New displayField value. Default value is nullFormItem
instance, for chaining setter callsgetDisplayFieldName()
,
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 useLocalDisplayFieldValue
is true, (or if unset and the conditions outlined in the documentation for that property are
met).
If this field has an 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 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 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 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
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, 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.
displayField
for this item. Behavior varies based on the configuration of this item, as follows:
optionDataSource
and an explicit 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.valueField
for this item is hidden in the optionDataSource
, this method will return the title field for the optionDataSource
.getDisplayFieldName()
,
invalidateDisplayValueCache()
,
Databinding overview and related methods
public FormItem setEditPendingCSSText(java.lang.String editPendingCSSText)
Note : This is an advanced setting
editPendingCSSText
- New editPendingCSSText value. Default value is "color:#0066CC;"FormItem
instance, for chaining setter callsCSSText
,
Appearance overview and related methods
public java.lang.String getEditPendingCSSText()
CSSText
,
Appearance overview and related methods
public FormItem setEditProxyConstructor(java.lang.String editProxyConstructor)
EditProxy
for this component when the component is
first placed into edit mode
.editProxyConstructor
- New editProxyConstructor value. Default value is "FormItemEditProxy"FormItem
instance, for chaining setter callsSCClassName
public java.lang.String getEditProxyConstructor()
EditProxy
for this component when the component is
first placed into edit mode
.SCClassName
public FormItem setEmptyDisplayValue(java.lang.String emptyDisplayValue)
If the formItem has a databound pickList, and its
displayField
or valueField
(if the former isn't set) has an undefined
emptyCellValue
setting, that field's
emptyCellValue
will automatically be set to the emptyDisplayValue
.
emptyDisplayValue
- New emptyDisplayValue value. Default value is ""FormItem
instance, for chaining setter callspublic java.lang.String getEmptyDisplayValue()
If the formItem has a databound pickList, and its
displayField
or valueField
(if the former isn't set) has an undefined
emptyCellValue
setting, that field's
emptyCellValue
will automatically be set to the emptyDisplayValue
.
public FormItem setEmptyValueIcon(java.lang.String emptyValueIcon)
valueIcons
)emptyValueIcon
- New emptyValueIcon value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.String getEmptyValueIcon()
valueIcons
)public FormItem setEndRow(java.lang.Boolean endRow)
endRow
- New endRow value. Default value is falseFormItem
instance, for chaining setter callssetLinearEndRow(int)
,
FormLayout overview and related methods
public java.lang.Boolean getEndRow()
getLinearEndRow()
,
FormLayout overview and related methods
public FormItem setErrorIconHeight(int errorIconHeight)
errorIconHeight
- New errorIconHeight value. Default value is 16FormItem
instance, for chaining setter callssetShowErrorIcon(java.lang.Boolean)
public int getErrorIconHeight()
getShowErrorIcon()
public FormItem setErrorIconSrc(java.lang.String errorIconSrc)
errorIconSrc
- New errorIconSrc value. Default value is "[SKIN]/DynamicForm/validation_error_icon.png"FormItem
instance, for chaining setter callssetShowErrorIcon(java.lang.Boolean)
,
SCImgURL
public java.lang.String getErrorIconSrc()
getShowErrorIcon()
,
SCImgURL
public FormItem setErrorIconWidth(int errorIconWidth)
errorIconWidth
- New errorIconWidth value. Default value is 16FormItem
instance, for chaining setter callssetShowErrorIcon(java.lang.Boolean)
public int getErrorIconWidth()
getShowErrorIcon()
public FormItem setErrorMessageWidth(int errorMessageWidth)
DynamicForm.showInlineErrors
and showErrorText
are both true and errorOrientation
is "left" or "right",
errorMessageWidth is the amount to reduce the width of the editor to accommodate the error message and icon.errorMessageWidth
- New errorMessageWidth value. Default value is 80FormItem
instance, for chaining setter callsValidation overview and related methods
public int getErrorMessageWidth()
DynamicForm.showInlineErrors
and showErrorText
are both true and errorOrientation
is "left" or "right",
errorMessageWidth is the amount to reduce the width of the editor to accommodate the error message and icon.Validation overview and related methods
public FormItem setEscapeHTML(java.lang.Boolean escapeHTML)
This property is supported by
specific formItem sub-types (e.g. TextItem
), and
has no effect in others. To understand the effects, look at the documentation for the specific formItem sub-type in
question.
escapeHTML
- New escapeHTML value. Default value is variesFormItem
instance, for chaining setter callsAppearance overview and related methods
public java.lang.Boolean getEscapeHTML()
This property is supported by
specific formItem sub-types (e.g. TextItem
), and
has no effect in others. To understand the effects, look at the documentation for the specific formItem sub-type in
question.
Appearance overview and related methods
public FormItem setExportFormat(java.lang.String exportFormat)
FormatString
used during exports for numeric or date formatting. See DataSourceField.exportFormat
.exportFormat
- New exportFormat value. Default value is nullFormItem
instance, for chaining setter callsFormatString
,
ExportFormatting overview and related methods
public java.lang.String getExportFormat()
FormatString
used during exports for numeric or date formatting. See DataSourceField.exportFormat
.FormatString
,
ExportFormatting overview and related methods
public FormItem setFetchMissingValues(java.lang.Boolean fetchMissingValues)
optionDataSource
, should the item ever perform a fetch against this dataSource to retrieve the related record. The
fetch occurs if the item value is non null on initial draw of the form or whenever setValue() is called. Once the fetch
completes, the returned record is available via the getSelectedRecord()
api.
By default, a fetch
will only occur if displayField
is specified,
and the item does not have an explicit valueMap
containing the data value as a key.
However you can also set alwaysFetchMissingValues
to have a fetch
occur even if no displayField
is specified. This ensures getSelectedRecord()
will return a record if possible
- useful for custom formatter functions, etc.
Note - for efficiency we cache the associated record once a fetch has
been performed, meaning if the value changes, then reverts to a previously seen value, we do not kick off an additional
fetch to pick up the display value for the previously seen data value. If necessary this cache may be explicitly
invalidated via a call to invalidateDisplayValueCache()
Note : This is an advanced setting
fetchMissingValues
- New fetchMissingValues value. Default value is trueFormItem
instance, for chaining setter callssetOptionDataSource(com.smartgwt.client.data.DataSource)
,
getSelectedRecord()
,
setFilterLocally(java.lang.Boolean)
public java.lang.Boolean getFetchMissingValues()
optionDataSource
, should the item ever perform a fetch against this dataSource to retrieve the related record. The
fetch occurs if the item value is non null on initial draw of the form or whenever setValue() is called. Once the fetch
completes, the returned record is available via the getSelectedRecord()
api.
By default, a fetch
will only occur if displayField
is specified,
and the item does not have an explicit valueMap
containing the data value as a key.
However you can also set alwaysFetchMissingValues
to have a fetch
occur even if no displayField
is specified. This ensures getSelectedRecord()
will return a record if possible
- useful for custom formatter functions, etc.
Note - for efficiency we cache the associated record once a fetch has
been performed, meaning if the value changes, then reverts to a previously seen value, we do not kick off an additional
fetch to pick up the display value for the previously seen data value. If necessary this cache may be explicitly
invalidated via a call to invalidateDisplayValueCache()
getOptionDataSource()
,
getSelectedRecord()
,
getFilterLocally()
public FormItem setFilterLocally(java.lang.Boolean filterLocally)
optionDataSource
, displayField
and fetchMissingValues
), setting this property to
true ensures that when the form item value is set, entire data-set from the dataSource is loaded at once and used as a
valueMap, rather than just loading the display value for the current value. This avoids the need to perform fetches each
time setValue() is called with a new value. See also PickList.filterLocally for behavior on form items such as SelectItems that show pick-lists.
Note : This is an advanced setting
filterLocally
- New filterLocally value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getFilterLocally()
optionDataSource
, displayField
and fetchMissingValues
), setting this property to
true ensures that when the form item value is set, entire data-set from the dataSource is loaded at once and used as a
valueMap, rather than just loading the display value for the current value. This avoids the need to perform fetches each
time setValue() is called with a new value. See also PickList.filterLocally for behavior on form items such as SelectItems that show pick-lists.
public FormItem setForeignDisplayField(java.lang.String foreignDisplayField)
optionDataSource
, this
property specifies an explicit display field for records within the option dataSource. Typically this property will be
set in conjunction with displayField
in the
case where the name of the displayField within the record being edited differs from the displayField in the
optionDataSource. See DataSourceField.foreignDisplayField
for additional details.
foreignDisplayField
- New foreignDisplayField value. Default value is nullFormItem
instance, for chaining setter callsgetDisplayFieldName()
public java.lang.String getForeignDisplayField()
optionDataSource
, this
property specifies an explicit display field for records within the option dataSource. Typically this property will be
set in conjunction with displayField
in the
case where the name of the displayField within the record being edited differs from the displayField in the
optionDataSource. See DataSourceField.foreignDisplayField
for additional details.
getDisplayFieldName()
public FormItem setFormat(java.lang.String format)
FormatString
for numeric or date formatting. See DataSourceField.format
.format
- New format value. Default value is nullFormItem
instance, for chaining setter callsFormatString
,
Appearance overview and related methods
public java.lang.String getFormat()
FormatString
for numeric or date formatting. See DataSourceField.format
.FormatString
,
Appearance overview and related methods
public FormItem setFormula(UserFormula formula)
textFormula
is used instead. Available fields for
use in the formula are the current rule context
. The formula is
re-evaluated every time the rule context changes.
Values calculated by the formula will always replace the current
value of a non-editable field. For an editable field, the current value will be replaced if the end user has not
changed the value since the last time it was computed by the formula, or if the value of the field is invalid according
to declared validators
.
Note: A FormItem
using a formula must have a name
defined. shouldSaveValue
can be set to false
to
prevent the formula field from storing the calculated value into the form's values.
formula
- New formula value. Default value is nullFormItem
instance, for chaining setter callsFormulaFields overview and related methods
public UserFormula getFormula()
textFormula
is used instead. Available fields for
use in the formula are the current rule context
. The formula is
re-evaluated every time the rule context changes.
Values calculated by the formula will always replace the current
value of a non-editable field. For an editable field, the current value will be replaced if the end user has not
changed the value since the last time it was computed by the formula, or if the value of the field is invalid according
to declared validators
.
Note: A FormItem
using a formula must have a name
defined. shouldSaveValue
can be set to false
to
prevent the formula field from storing the calculated value into the form's values.
FormulaFields overview and related methods
public FormItem setGlobalTabIndex(java.lang.Integer globalTabIndex)
item.tabIndex
. Use of this API is extremely advanced and essentially implies taking over management of tab index assignment for all components on the page.
Note : This is an advanced setting
globalTabIndex
- New globalTabIndex value. Default value is nullFormItem
instance, for chaining setter callsFocus overview and related methods
public java.lang.Integer getGlobalTabIndex()
item.tabIndex
. Use of this API is extremely advanced and essentially implies taking over management of tab index assignment for all components on the page.
Focus overview and related methods
public FormItem setHeight(int height)
FormLayout
overview for details. If height is specified as a String, getHeight() will return -1. Use getHeightAsString.() in this case.
For form items having a picker icon
(e.g. SelectItem
, ComboBoxItem
) and
SpinnerItem
s, if there is no explicit pickerIconHeight
, the pickerIcon will be sized to
match the available space based on the specified item height.
Note that if spriting is being used, and the image to
be displayed in these icons is specified using css properties such as background-image
,
background-size
, changing this value may result in an unexpected appearance as the image will not
scale.
Scaleable spriting can be achieved using the SCSpriteConfig
format. See the
section on spriting in the skinning overview
for further information.
Alternatively, the pickerIconStyle
could be
changed to a custom CSS style name, and in the case of SpinnerItem
s,
the baseStyle
and src
of the SpinnerItem.increaseIcon
and SpinnerItem.decreaseIcon
AutoChildren could be
customized.
Note that when FormItem is rendered as read-only with readOnlyDisplay
as "static" the
property staticHeight
is used instead.
height
- New height value. Default value is 20FormItem
instance, for chaining setter callssetWidth(int)
,
DynamicForm.setItemLayout(com.smartgwt.client.types.FormLayoutType)
,
FormLayout overview and related methods
,
Filling Examplepublic int getHeight()
FormLayout
overview for details. If height is specified as a String, getHeight() will return -1. Use getHeightAsString.() in this case.
For form items having a picker icon
(e.g. SelectItem
, ComboBoxItem
) and
SpinnerItem
s, if there is no explicit pickerIconHeight
, the pickerIcon will be sized to
match the available space based on the specified item height.
Note that if spriting is being used, and the image to
be displayed in these icons is specified using css properties such as background-image
,
background-size
, changing this value may result in an unexpected appearance as the image will not
scale.
Scaleable spriting can be achieved using the SCSpriteConfig
format. See the
section on spriting in the skinning overview
for further information.
Alternatively, the pickerIconStyle
could be
changed to a custom CSS style name, and in the case of SpinnerItem
s,
the baseStyle
and src
of the SpinnerItem.increaseIcon
and SpinnerItem.decreaseIcon
AutoChildren could be
customized.
Note that when FormItem is rendered as read-only with readOnlyDisplay
as "static" the
property staticHeight
is used instead.
Note : This method will return -1 if the underlying SmartClient JavaScript
attribute value cannot be expressed as a(n) int. In that case, other
getters, similarly-named but ending in AsString
, AsCanvas
,
etc., may be provided.
getWidth()
,
DynamicForm.getItemLayout()
,
FormLayout overview and related methods
,
Filling Examplepublic FormItem setHeight(java.lang.String height)
FormLayout
overview for details. If height is specified as a String, getHeight() will return -1. Use getHeightAsString.() in this case.
For form items having a picker icon
(e.g. SelectItem
, ComboBoxItem
) and
SpinnerItem
s, if there is no explicit pickerIconHeight
, the pickerIcon will be sized to
match the available space based on the specified item height.
Note that if spriting is being used, and the image to
be displayed in these icons is specified using css properties such as background-image
,
background-size
, changing this value may result in an unexpected appearance as the image will not
scale.
Scaleable spriting can be achieved using the SCSpriteConfig
format. See the
section on spriting in the skinning overview
for further information.
Alternatively, the pickerIconStyle
could be
changed to a custom CSS style name, and in the case of SpinnerItem
s,
the baseStyle
and src
of the SpinnerItem.increaseIcon
and SpinnerItem.decreaseIcon
AutoChildren could be
customized.
Note that when FormItem is rendered as read-only with readOnlyDisplay
as "static" the
property staticHeight
is used instead.
height
- New height value. Default value is 20FormItem
instance, for chaining setter callssetWidth(int)
,
DynamicForm.setItemLayout(com.smartgwt.client.types.FormLayoutType)
,
FormLayout overview and related methods
,
Filling Examplepublic java.lang.String getHeightAsString()
FormLayout
overview for details. If height is specified as a String, getHeight() will return -1. Use getHeightAsString.() in this case.
For form items having a picker icon
(e.g. SelectItem
, ComboBoxItem
) and
SpinnerItem
s, if there is no explicit pickerIconHeight
, the pickerIcon will be sized to
match the available space based on the specified item height.
Note that if spriting is being used, and the image to
be displayed in these icons is specified using css properties such as background-image
,
background-size
, changing this value may result in an unexpected appearance as the image will not
scale.
Scaleable spriting can be achieved using the SCSpriteConfig
format. See the
section on spriting in the skinning overview
for further information.
Alternatively, the pickerIconStyle
could be
changed to a custom CSS style name, and in the case of SpinnerItem
s,
the baseStyle
and src
of the SpinnerItem.increaseIcon
and SpinnerItem.decreaseIcon
AutoChildren could be
customized.
Note that when FormItem is rendered as read-only with readOnlyDisplay
as "static" the
property staticHeight
is used instead.
getWidth()
,
DynamicForm.getItemLayout()
,
FormLayout overview and related methods
,
Filling Examplepublic FormItem setHidden(java.lang.Boolean hidden)
true
on an item configuration will have the same
effect as having a showIf()
implementation which returns
false
. Note this differs slightly from DataSourceField.hidden
. That property will cause the field in question to be omitted entirely from databound
components by default. A dataSourceField with hidden
set to true
can still be displayed in a
DynamicForm either by being explicitly included in the specified items array
, or by having DataBoundComponent.showHiddenFields
set to true. In
this case, this property will not be inherited onto the FormItem instance, meaning the item will be visible in the form
even though the hidden
property was set to true on the dataSourceField configuration object.
hidden
- New hidden value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getHidden()
true
on an item configuration will have the same
effect as having a showIf()
implementation which returns
false
. Note this differs slightly from DataSourceField.hidden
. That property will cause the field in question to be omitted entirely from databound
components by default. A dataSourceField with hidden
set to true
can still be displayed in a
DynamicForm either by being explicitly included in the specified items array
, or by having DataBoundComponent.showHiddenFields
set to true. In
this case, this property will not be inherited onto the FormItem instance, meaning the item will be visible in the form
even though the hidden
property was set to true on the dataSourceField configuration object.
public FormItem setHint(java.lang.String hint)
hint
for this item.hint
- new hint for the item. Default value is nullFormItem
instance, for chaining setter callssetHintStyle(java.lang.String)
,
HTMLString
,
Appearance overview and related methods
,
Hints Examplepublic java.lang.String getHint()
getHintStyle()
,
HTMLString
,
Appearance overview and related methods
,
Hints Examplepublic FormItem setHintStyle(java.lang.String hintStyle)
TextItem.showHintInField
, this only applies when
showHintInField is false.
hintStyle
- new style for hint text. Default value is "formHint"FormItem
instance, for chaining setter callssetHint(java.lang.String)
,
CSSStyleName
,
FormItemStyling overview and related methods
public java.lang.String getHintStyle()
TextItem.showHintInField
, this only applies when
showHintInField is false.getHint()
,
CSSStyleName
,
FormItemStyling overview and related methods
public FormItem setHoverAlign(Alignment hoverAlign)
hoverAlign
- New hoverAlign value. Default value is nullFormItem
instance, for chaining setter callsDynamicForm.setItemHoverAlign(com.smartgwt.client.types.Alignment)
public Alignment getHoverAlign()
DynamicForm.getItemHoverAlign()
public FormItem setHoverDelay(java.lang.Integer hoverDelay)
this.form.itemHoverDelay
will be used instead.
Note : This is an advanced setting
hoverDelay
- New hoverDelay value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Integer getHoverDelay()
this.form.itemHoverDelay
will be used instead.public FormItem setHoverFocusKey(java.lang.String hoverFocusKey)
Overrides the same attribute
on
the parent form.
hoverFocusKey
- New hoverFocusKey value. Default value is nullFormItem
instance, for chaining setter callssetHoverPersist(com.smartgwt.client.types.HoverPersistMode)
,
KeyName
public java.lang.String getHoverFocusKey()
Overrides the same attribute
on
the parent form.
getHoverPersist()
,
KeyName
public FormItem setHoverHeight(java.lang.Integer hoverHeight)
hoverHeight
- New hoverHeight value. Default value is nullFormItem
instance, for chaining setter callsDynamicForm.setItemHoverHeight(java.lang.Integer)
public java.lang.Integer getHoverHeight()
DynamicForm.getItemHoverHeight()
public FormItem setHoverHeight(java.lang.String hoverHeight)
hoverHeight
- New hoverHeight value. Default value is nullFormItem
instance, for chaining setter callsDynamicForm.setItemHoverHeight(java.lang.Integer)
public java.lang.String getHoverHeightAsString()
DynamicForm.getItemHoverHeight()
public FormItem setHoverOpacity(java.lang.Integer hoverOpacity)
hoverOpacity
- New hoverOpacity value. Default value is nullFormItem
instance, for chaining setter callsDynamicForm.setItemHoverOpacity(java.lang.Integer)
public java.lang.Integer getHoverOpacity()
DynamicForm.getItemHoverOpacity()
public FormItem setHoverPersist(HoverPersistMode hoverPersist)
Overrides the same attribute
on the parent form.
hoverPersist
- New hoverPersist value. Default value is nullFormItem
instance, for chaining setter callssetHoverFocusKey(java.lang.String)
public HoverPersistMode getHoverPersist()
Overrides the same attribute
on the parent form.
getHoverFocusKey()
public FormItem setHoverStyle(java.lang.String hoverStyle)
hoverStyle
- New hoverStyle value. Default value is nullFormItem
instance, for chaining setter callsDynamicForm.setItemHoverStyle(java.lang.String)
,
CSSStyleName
public java.lang.String getHoverStyle()
DynamicForm.getItemHoverStyle()
,
CSSStyleName
public FormItem setHoverVAlign(VerticalAlignment hoverVAlign)
hoverVAlign
- New hoverVAlign value. Default value is nullFormItem
instance, for chaining setter callsDynamicForm.setItemHoverVAlign(java.lang.Integer)
public VerticalAlignment getHoverVAlign()
DynamicForm.getItemHoverVAlign()
public FormItem setHoverWidth(java.lang.Integer hoverWidth)
hoverWidth
- New hoverWidth value. Default value is nullFormItem
instance, for chaining setter callsDynamicForm.setItemHoverWidth(java.lang.Integer)
public java.lang.Integer getHoverWidth()
DynamicForm.getItemHoverWidth()
public FormItem setHoverWidth(java.lang.String hoverWidth)
hoverWidth
- New hoverWidth value. Default value is nullFormItem
instance, for chaining setter callsDynamicForm.setItemHoverWidth(java.lang.Integer)
public java.lang.String getHoverWidthAsString()
DynamicForm.getItemHoverWidth()
public FormItem setIconHeight(int iconHeight)
FormItemIcon.height
.
Note : This is an advanced setting
iconHeight
- New iconHeight value. Default value is 20FormItem
instance, for chaining setter callspublic int getIconHeight()
FormItemIcon.height
.public FormItem setIconHSpace(int iconHSpace)
FormItemIcon.hspace
. Must be non-negative.iconHSpace
- New iconHSpace value. Default value is 3FormItem
instance, for chaining setter callspublic int getIconHSpace()
FormItemIcon.hspace
. Must be non-negative.public FormItem setIconPrompt(java.lang.String iconPrompt)
Note : This is an advanced setting
iconPrompt
- New iconPrompt value. Default value is ""FormItem
instance, for chaining setter callsHTMLString
public java.lang.String getIconPrompt()
HTMLString
public FormItem setIcons(FormItemIcon... icons)
icons
- New icons value. Default value is nullFormItem
instance, for chaining setter callsFormItemIcon
,
Icons Examplepublic FormItemIcon[] getIcons()
FormItemIcon
,
Icons Examplepublic FormItem setIconVAlign(VerticalAlignment iconVAlign)
Note : This is an advanced setting
iconVAlign
- New iconVAlign value. Default value is "bottom"FormItem
instance, for chaining setter callspublic VerticalAlignment getIconVAlign()
public FormItem setIconWidth(int iconWidth)
FormItemIcon.width
.
Note : This is an advanced setting
iconWidth
- New iconWidth value. Default value is 20FormItem
instance, for chaining setter callspublic int getIconWidth()
FormItemIcon.width
.public FormItem setID(java.lang.String ID)
form.getItem("itemName")
). An internal, unique ID will automatically be created upon instantiation for any formItem where one is not provided.
ID
- New ID value. Default value is nullFormItem
instance, for chaining setter callsGlobalId
,
Basics overview and related methods
public java.lang.String getID()
form.getItem("itemName")
). An internal, unique ID will automatically be created upon instantiation for any formItem where one is not provided.
GlobalId
,
Basics overview and related methods
public FormItem setImageURLPrefix(java.lang.String imageURLPrefix)
valueIcons
when determining the URL for the image. Will not be applied if the valueIcon
URL is absolute.
Note : This is an advanced setting
imageURLPrefix
- New imageURLPrefix value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.String getImageURLPrefix()
valueIcons
when determining the URL for the image. Will not be applied if the valueIcon
URL is absolute.public FormItem setImageURLSuffix(java.lang.String imageURLSuffix)
valueIcons
when
determining the URL for the image. A common usage would be to specify a suffix of ".gif"
in which case the
valueIcons
property would map values to the names of images without the ".gif"
extension.
Note : This is an advanced setting
imageURLSuffix
- New imageURLSuffix value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.String getImageURLSuffix()
valueIcons
when
determining the URL for the image. A common usage would be to specify a suffix of ".gif"
in which case the
valueIcons
property would map values to the names of images without the ".gif"
extension.public FormItem setImplicitSave(java.lang.Boolean implicitSave)
delay
, as well as when the entire form is submitted.
If implicitSaveOnBlur is set to true on either this formItem
or it's form
, changes will also be automatically saved
immediately on editorExit.implicitSave
- New implicitSave value. Default value is falseFormItem
instance, for chaining setter callspublic java.lang.Boolean getImplicitSave()
delay
, as well as when the entire form is submitted.
If implicitSaveOnBlur is set to true on either this formItem
or it's form
, changes will also be automatically saved
immediately on editorExit.public FormItem setImplicitSaveOnBlur(java.lang.Boolean implicitSaveOnBlur)
implicitSave
, which
causes saves during editing, after a short
delay
, and when the entire form is submitted.implicitSaveOnBlur
- New implicitSaveOnBlur value. Default value is falseFormItem
instance, for chaining setter callspublic java.lang.Boolean getImplicitSaveOnBlur()
implicitSave
, which
causes saves during editing, after a short
delay
, and when the entire form is submitted.public FormItem setInputFormat(java.lang.String inputFormat)
"date"
, if this is an editable field such as a TextItem
, this property allows you to specify the inputFormat
applied to the item.
Note : This is an advanced setting
inputFormat
- New inputFormat value. Default value is nullFormItem
instance, for chaining setter callssetDateFormatter(com.smartgwt.client.types.DateDisplayFormat)
,
DateInputFormat
public java.lang.String getInputFormat()
"date"
, if this is an editable field such as a TextItem
, this property allows you to specify the inputFormat
applied to the item.getDateFormatter()
,
DateInputFormat
public FormItem setLeft(int left)
itemLayout:"absolute"
.
itemLayout
:"absolute" only, set the left coordinate of this form item. Causes the form to redraw.
Note : This is an advanced setting
left
- New left value. Default value is 0FormItem
instance, for chaining setter callspublic int getLeft()
itemLayout:"absolute"
.public FormItem setLinearColSpan(int linearColSpan)
linearMode
,
overriding the default value of "*" in that mode.linearColSpan
- New linearColSpan value. Default value is nullFormItem
instance, for chaining setter callssetColSpan(java.lang.String)
,
FormLayout overview and related methods
public int getLinearColSpan()
linearMode
,
overriding the default value of "*" in that mode.
Note : This method will return -1 if the underlying SmartClient JavaScript
attribute value cannot be expressed as a(n) int. In that case, other
getters, similarly-named but ending in AsString
, AsCanvas
,
etc., may be provided.
com.smartgwt.client.widgets.form.fields.FormItem#getColSpan
,
FormLayout overview and related methods
public FormItem setLinearColSpan(java.lang.String linearColSpan)
linearMode
,
overriding the default value of "*" in that mode.linearColSpan
- New linearColSpan value. Default value is nullFormItem
instance, for chaining setter callssetColSpan(java.lang.String)
,
FormLayout overview and related methods
public java.lang.String getLinearColSpanAsString()
linearMode
,
overriding the default value of "*" in that mode.com.smartgwt.client.widgets.form.fields.FormItem#getColSpan
,
FormLayout overview and related methods
public FormItem setLinearEndRow(int linearEndRow)
linearEndRow
- New linearEndRow value. Default value is nullFormItem
instance, for chaining setter callsFormLayout overview and related methods
public int getLinearEndRow()
endRow
for an item in linearMode
, overriding the default of true
in
that mode.
Note : This method will return -1 if the underlying SmartClient JavaScript
attribute value cannot be expressed as a(n) int. In that case, other
getters, similarly-named but ending in AsString
, AsCanvas
,
etc., may be provided.
FormLayout overview and related methods
public FormItem setLinearEndRow(java.lang.String linearEndRow)
linearEndRow
- New linearEndRow value. Default value is nullFormItem
instance, for chaining setter callsFormLayout overview and related methods
public java.lang.String getLinearEndRowAsString()
FormLayout overview and related methods
public FormItem setLinearStartRow(int linearStartRow)
linearStartRow
- New linearStartRow value. Default value is nullFormItem
instance, for chaining setter callsFormLayout overview and related methods
public int getLinearStartRow()
startRow
for an item in linearMode
, overriding the default of false
in
that mode.
Note : This method will return -1 if the underlying SmartClient JavaScript
attribute value cannot be expressed as a(n) int. In that case, other
getters, similarly-named but ending in AsString
, AsCanvas
,
etc., may be provided.
FormLayout overview and related methods
public FormItem setLinearStartRow(java.lang.String linearStartRow)
linearStartRow
- New linearStartRow value. Default value is nullFormItem
instance, for chaining setter callsFormLayout overview and related methods
public java.lang.String getLinearStartRowAsString()
FormLayout overview and related methods
public FormItem setLinearWidth(int linearWidth)
linearMode
,
overriding the default width of "*" in that mode.linearWidth
- New linearWidth value. Default value is nullFormItem
instance, for chaining setter callssetWidth(int)
,
FormLayout overview and related methods
public int getLinearWidth()
linearMode
,
overriding the default width of "*" in that mode.
Note : This method will return -1 if the underlying SmartClient JavaScript
attribute value cannot be expressed as a(n) int. In that case, other
getters, similarly-named but ending in AsString
, AsCanvas
,
etc., may be provided.
getWidth()
,
FormLayout overview and related methods
public FormItem setLinearWidth(java.lang.String linearWidth)
linearMode
,
overriding the default width of "*" in that mode.linearWidth
- New linearWidth value. Default value is nullFormItem
instance, for chaining setter callssetWidth(int)
,
FormLayout overview and related methods
public java.lang.String getLinearWidthAsString()
linearMode
,
overriding the default width of "*" in that mode.getWidth()
,
FormLayout overview and related methods
public FormItem setLoadingDisplayValue(java.lang.String loadingDisplayValue)
fetchMissingValues
is active and a fetch is pending. The field is read-only while a fetch is pending. Set to
null
to show actual value until display value is loaded.
loadingDisplayValue
- New loadingDisplayValue value. Default value is "Loading..."FormItem
instance, for chaining setter callspublic java.lang.String getLoadingDisplayValue()
fetchMissingValues
is active and a fetch is pending. The field is read-only while a fetch is pending. Set to
null
to show actual value until display value is loaded.
public FormItem setLocateItemBy(java.lang.String locateItemBy)
AutoTest.getElement()
is used to parse locator strings
generated by AutoTest.getLocator()
for this form item, should the
item be identified? If the locator has a specified name
, it is considered to definitely locate the item and no fallback approach will be used. Otherwise, the following options are available:
"title"
use the title as an identifier within this form"value"
use the value of the item to identify it (often used for items with a static defaultValue such
as HeaderItems"index"
use the index within the form's items array. If unset, and the locator has no specified name, default behavior is to identify by title (if available), then value (if available), otherwise by index.
Note : This is an advanced setting
locateItemBy
- New locateItemBy value. Default value is nullFormItem
instance, for chaining setter callsLocatorStrategy
public java.lang.String getLocateItemBy()
AutoTest.getElement()
is used to parse locator strings
generated by AutoTest.getLocator()
for this form item, should the
item be identified? If the locator has a specified name
, it is considered to definitely locate the item and no fallback approach will be used. Otherwise, the following options are available:
"title"
use the title as an identifier within this form"value"
use the value of the item to identify it (often used for items with a static defaultValue such
as HeaderItems"index"
use the index within the form's items array. If unset, and the locator has no specified name, default behavior is to identify by title (if available), then value (if available), otherwise by index.
LocatorStrategy
public FormItem setMinHintWidth(java.lang.Integer minHintWidth)
hint
, this setting specifies
how much horizontal space is made available for rendering the hint text by default. Typically this reflects how much
space the hint text takes up before it wraps. Note that the presence of a hint may cause a form item to expand
horizontally past its specified width
. This property
value acts as a minimum - if the hint text can not wrap within this width (either due to wrapHintText
being set to false
, or due
to it containing long, un-wrappable content), it will further expand to take up the space it needs.
If unset this
property will be picked up from the DynamicForm.minHintWidth
setting.
This setting does not apply to hints that are shown in field
.
minHintWidth
- New minHintWidth value. Default value is nullFormItem
instance, for chaining setter callssetWrapHintText(java.lang.Boolean)
public java.lang.Integer getMinHintWidth()
hint
, this setting specifies
how much horizontal space is made available for rendering the hint text by default. Typically this reflects how much
space the hint text takes up before it wraps. Note that the presence of a hint may cause a form item to expand
horizontally past its specified width
. This property
value acts as a minimum - if the hint text can not wrap within this width (either due to wrapHintText
being set to false
, or due
to it containing long, un-wrappable content), it will further expand to take up the space it needs.
If unset this
property will be picked up from the DynamicForm.minHintWidth
setting.
This setting does not apply to hints that are shown in field
.
getWrapHintText()
public FormItem setMultiple(java.lang.Boolean multiple)
Only certain FormItems that support both singular and multiple values
actually use this setting, such as SelectItem
. Other FormItems such as
MultiComboBoxItem
are always effectively multiple:true, even if
multiple:true is not set.
multiple
- New multiple value. Default value is falseFormItem
instance, for chaining setter callsAppearance overview and related methods
public java.lang.Boolean getMultiple()
Only certain FormItems that support both singular and multiple values
actually use this setting, such as SelectItem
. Other FormItems such as
MultiComboBoxItem
are always effectively multiple:true, even if
multiple:true is not set.
Appearance overview and related methods
public FormItem setMultipleValueSeparator(java.lang.String multipleValueSeparator)
multipleValueSeparator
- New multipleValueSeparator value. Default value is ', 'FormItem
instance, for chaining setter callspublic java.lang.String getMultipleValueSeparator()
public java.lang.String getName()
FieldName
for details and how to check for validity. The FormItem's name determines the name of the property it edits within the form.
Note that an item must have a valid name or dataPath
in order for its value to be validated and/or
saved.
FieldName
,
Basics overview and related methods
public FormItem setNullOriginalValueText(java.lang.String nullOriginalValueText)
originalValueMessage
when showOldValueInHover
is enabled, and when the value has been modified but was originally unset.
Note : This is an advanced setting
nullOriginalValueText
- New nullOriginalValueText value. Default value is "None"FormItem
instance, for chaining setter callsHTMLString
public java.lang.String getNullOriginalValueText()
originalValueMessage
when showOldValueInHover
is enabled, and when the value has been modified but was originally unset.HTMLString
public FormItem setOperator(OperatorId operator)
OperatorId
to be used when DynamicForm.getValuesAsCriteria()
is called.
item.operator
can be used to create a form that offers search functions such as numeric range filtering,
without the more advanced user interface of the FilterBuilder
. For example,
two SpinnerItems could be created with formItem.operator
set to "greaterThan" and "lessThan" respectively
to enable filtering by a numeric range.
When item.operator
is set for any FormItem in a form,
form.getValuesAsCriteria()
will return an AdvancedCriteria
object instead
of a normal Criteria
object. Each FormItem will produce one Criterion
affecting the DataSource field specified by criteriaField
. The criteria produced by the FormItems
will be grouped under the logical operator provided by DynamicForm.operator
.
If operator
is set for some fields but not others, the default operator is
"equals" for fields with a valueMap or an optionDataSource, and for fields of type "enum" (or of a type that inherits
from "enum"). The default operator for all other fields is controlled by DynamicForm.defaultSearchOperator
.
Note: formItem.operator
is only supported for a form that has a dataSource
. In a form with no DataSource, setting
formItem.operator
will have no effect.
operator
- New operator value. Default value is nullFormItem
instance, for chaining setter callsCriteriaEditing overview and related methods
public OperatorId getOperator()
OperatorId
to be used when DynamicForm.getValuesAsCriteria()
is called.
item.operator
can be used to create a form that offers search functions such as numeric range filtering,
without the more advanced user interface of the FilterBuilder
. For example,
two SpinnerItems could be created with formItem.operator
set to "greaterThan" and "lessThan" respectively
to enable filtering by a numeric range.
When item.operator
is set for any FormItem in a form,
form.getValuesAsCriteria()
will return an AdvancedCriteria
object instead
of a normal Criteria
object. Each FormItem will produce one Criterion
affecting the DataSource field specified by criteriaField
. The criteria produced by the FormItems
will be grouped under the logical operator provided by DynamicForm.operator
.
If operator
is set for some fields but not others, the default operator is
"equals" for fields with a valueMap or an optionDataSource, and for fields of type "enum" (or of a type that inherits
from "enum"). The default operator for all other fields is controlled by DynamicForm.defaultSearchOperator
.
Note: formItem.operator
is only supported for a form that has a dataSource
. In a form with no DataSource, setting
formItem.operator
will have no effect.
CriteriaEditing overview and related methods
public FormItem setOptionDataSource(DataSource optionDataSource)
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
If this method is called after the component has been drawn/initialized:
Method to set the optionDataSource
at runtime
optionDataSource
- new optionDatasource. Default value is nullFormItem
instance, for chaining setter callsinvalidateDisplayValueCache()
,
List - Combo Box Examplepublic DataSource getOptionDataSource()
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
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
invalidateDisplayValueCache()
,
List - Combo Box Examplepublic FormItem setOptionDataSource(java.lang.String optionDataSource)
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
If this method is called after the component has been drawn/initialized:
Method to set the optionDataSource
at runtime
optionDataSource
- new optionDatasource. Default value is nullFormItem
instance, for chaining setter callsinvalidateDisplayValueCache()
,
List - Combo Box Examplepublic java.lang.String getOptionDataSourceAsString()
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
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
invalidateDisplayValueCache()
,
List - Combo Box Examplepublic FormItem 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.
Note : This is an advanced setting
optionOperationId
- New optionOperationId value. Default value is nullFormItem
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.Databinding overview and related methods
public FormItem setOptionTextMatchStyle(TextMatchStyle optionTextMatchStyle)
optionDataSource
, this property determines the textMatchStyle to use when
interpretating any optionCriteria
during the
fetch to map valueField values to displayField values.
Note : This is an advanced setting
optionTextMatchStyle
- New optionTextMatchStyle value. Default value is "exact"FormItem
instance, for chaining setter callsDatabinding overview and related methods
public TextMatchStyle getOptionTextMatchStyle()
optionDataSource
, this property determines the textMatchStyle to use when
interpretating any optionCriteria
during the
fetch to map valueField values to displayField values.Databinding overview and related methods
public FormItem setOriginalValueMessage(java.lang.String originalValueMessage)
showOldValueInHover
is enabled and the value has been modified. If unset, defaults to the form's DynamicForm.originalValueMessage
. Otherwise,
overrides the form-default originalValueMessage
for this item.
Note : This is an advanced setting
originalValueMessage
- New originalValueMessage value. Default value is nullFormItem
instance, for chaining setter callsHTMLString
public java.lang.String getOriginalValueMessage()
showOldValueInHover
is enabled and the value has been modified. If unset, defaults to the form's DynamicForm.originalValueMessage
. Otherwise,
overrides the form-default originalValueMessage
for this item.
HTMLString
public Canvas getPicker()
showPicker()
is called due to a click on the picker icon
. Can be specified directly as a Canvas, or created automatically via the com.smartgwt.client.types.AutoChild
pattern. The default autoChild configuration for the picker is a Canvas with
backgroundColor set and no other modifications.
Note that the picker is not automatically destroyed with the
FormItem that uses it, in order to allow recycling of picker components. To destroy a single-use picker, override
Canvas.destroy()
.
This component is an AutoChild named "picker". For an overview of how to use and
configure AutoChildren, see Using AutoChildren
.
public FormItem setPickerIconHeight(java.lang.Integer pickerIconHeight)
showPickerIcon
is true for this item, this
property governs the size of the picker icon. If unset, the picker icon will be sized as a square to fit in the
available height for the icon. Note that if spriting is being used, and the image to be displayed is specified
using css properties such as background-image
, background-size
, changing this value may result
in an unexpected appearance as the image will not scale.
Scaleable spriting can be achieved using the SCSpriteConfig
format. See the section on spriting in the skinning overview
for further information.
Note : This is an advanced setting
pickerIconHeight
- New pickerIconHeight value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Integer getPickerIconHeight()
showPickerIcon
is true for this item, this
property governs the size of the picker icon. If unset, the picker icon will be sized as a square to fit in the
available height for the icon. Note that if spriting is being used, and the image to be displayed is specified
using css properties such as background-image
, background-size
, changing this value may result
in an unexpected appearance as the image will not scale.
Scaleable spriting can be achieved using the SCSpriteConfig
format. See the section on spriting in the skinning overview
for further information.
public FormItem setPickerIconName(java.lang.String pickerIconName)
showPickerIcon
is true, this attribute
specifies the FormItemIcon.name
applied to the
picker icon
Note : This is an advanced setting
pickerIconName
- New pickerIconName value. Default value is "picker"FormItem
instance, for chaining setter callsIdentifier
public java.lang.String getPickerIconName()
showPickerIcon
is true, this attribute
specifies the FormItemIcon.name
applied to the
picker iconIdentifier
public FormItem setPickerIconPrompt(java.lang.String pickerIconPrompt)
pickerIconPrompt
- New pickerIconPrompt value. Default value is nullFormItem
instance, for chaining setter callsHTMLString
public java.lang.String getPickerIconPrompt()
HTMLString
public FormItem setPickerIconProperties(FormItemIcon pickerIconProperties)
showPickerIcon
is true for this item, this
block of properties will be applied to the pickerIcon. Allows for advanced customization of this icon.
Note : This is an advanced setting
pickerIconProperties
- New pickerIconProperties value. Default value is nullFormItem
instance, for chaining setter callspublic FormItemIcon getPickerIconProperties()
showPickerIcon
is true for this item, this
block of properties will be applied to the pickerIcon. Allows for advanced customization of this icon.public FormItem setPickerIconSrc(java.lang.String pickerIconSrc)
showPickerIcon
is true for this item, this
property governs the src
of the picker icon image to
be displayed. Spriting
can be used for this image, by setting this
property to a SCSpriteConfig
formatted string.
Note : This is an advanced setting
public java.lang.String getPickerIconSrc()
showPickerIcon
is true for this item, this
property governs the src
of the picker icon image to
be displayed. Spriting
can be used for this image, by setting this
property to a SCSpriteConfig
formatted string.
SCImgURL
public FormItem setPickerIconStyle(java.lang.String pickerIconStyle)
controlStyle
.pickerIconStyle
- New pickerIconStyle value. Default value is nullFormItem
instance, for chaining setter callssetCellStyle(java.lang.String)
,
FormItemBaseStyle
,
FormItemStyling overview and related methods
public java.lang.String getPickerIconStyle()
controlStyle
.getCellStyle()
,
FormItemBaseStyle
,
FormItemStyling overview and related methods
public FormItem setPickerIconWidth(java.lang.Integer pickerIconWidth)
showPickerIcon
is true for this item, this
property governs the size of the picker icon. If unset, the picker icon will be sized as a square to fit in the
available height for the icon. Note that if spriting is being used, and the image to be displayed is specified
using css properties such as background-image
, background-size
, changing this value may result
in an unexpected appearance as the image will not scale.
Scaleable spriting can be achieved using the SCSpriteConfig
format. See the section on spriting in the skinning overview
for further information.
Note : This is an advanced setting
pickerIconWidth
- New pickerIconWidth value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Integer getPickerIconWidth()
showPickerIcon
is true for this item, this
property governs the size of the picker icon. If unset, the picker icon will be sized as a square to fit in the
available height for the icon. Note that if spriting is being used, and the image to be displayed is specified
using css properties such as background-image
, background-size
, changing this value may result
in an unexpected appearance as the image will not scale.
Scaleable spriting can be achieved using the SCSpriteConfig
format. See the section on spriting in the skinning overview
for further information.
public FormItem setPrintReadOnlyTextBoxStyle(java.lang.String printReadOnlyTextBoxStyle)
canEdit:false
, with readOnlyDisplay:static
. If specified this will
take precedence over printTextBoxStyle
for
static readonly items.
printReadOnlyTextBoxStyle
- New printReadOnlyTextBoxStyle value. Default value is nullFormItem
instance, for chaining setter callsFormItemBaseStyle
,
Printing overview and related methods
public java.lang.String getPrintReadOnlyTextBoxStyle()
canEdit:false
, with readOnlyDisplay:static
. If specified this will
take precedence over printTextBoxStyle
for
static readonly items.
FormItemBaseStyle
,
Printing overview and related methods
public FormItem setPrintTextBoxStyle(java.lang.String printTextBoxStyle)
textBoxStyle
will be used instead. Note that focused
styling will never be displayed while printing, though error and disabled styling will. By default this style will
be used for printHTML for the item even if the item is canEdit:false
with readOnlyDisplay:static
.
To override this
behavior, developers may also specify a custom print style for this state via the printReadOnlyTextBoxStyle
.
printTextBoxStyle
- New printTextBoxStyle value. Default value is nullFormItem
instance, for chaining setter callsFormItemBaseStyle
,
Printing overview and related methods
public java.lang.String getPrintTextBoxStyle()
textBoxStyle
will be used instead. Note that focused
styling will never be displayed while printing, though error and disabled styling will. By default this style will
be used for printHTML for the item even if the item is canEdit:false
with readOnlyDisplay:static
.
To override this
behavior, developers may also specify a custom print style for this state via the printReadOnlyTextBoxStyle
.
FormItemBaseStyle
,
Printing overview and related methods
public FormItem setPrintTitleStyle(java.lang.String printTitleStyle)
titleStyle
will be used instead.printTitleStyle
- New printTitleStyle value. Default value is nullFormItem
instance, for chaining setter callsFormItemBaseStyle
,
Printing overview and related methods
public java.lang.String getPrintTitleStyle()
titleStyle
will be used instead.FormItemBaseStyle
,
Printing overview and related methods
public FormItem setPrompt(java.lang.String prompt)
When item is read-only
a different hover can be shown with readOnlyHover
. Or, when item is disabled
or read-only with readOnlyDisplay:disabled
a different hover can be
shown with disabledHover
.
Note that when
the form is disabled
this prompt will not be shown.
If this method is called after the component has been drawn/initialized:
Sets the prompt
for this item.
prompt
- new prompt for the item. Default value is nullFormItem
instance, for chaining setter callsHTMLString
,
Basics overview and related methods
public java.lang.String getPrompt()
When item is read-only
a different hover can be shown with readOnlyHover
. Or, when item is disabled
or read-only with readOnlyDisplay:disabled
a different hover can be
shown with disabledHover
.
Note that when
the form is disabled
this prompt will not be shown.
HTMLString
,
Basics overview and related methods
public FormItem setReadOnlyCanSelectText(ReadOnlyDisplayAppearance... readOnlyCanSelectText)
canEdit
set to
false, should the user be able to select the text in the item? Default behavior allows selection if readOnlyDisplay
is "static"
or
"readOnly"
[but not "disabled"
]. Developers may add or remove ReadOnlyDisplayAppearance values
to change this behavior.
Note that this does not apply to disabled items
, where text selection is never enabled
readOnlyCanSelectText
- New readOnlyCanSelectText value. Default value is ["static", "readOnly"]FormItem
instance, for chaining setter callspublic ReadOnlyDisplayAppearance[] getReadOnlyCanSelectText()
canEdit
set to
false, should the user be able to select the text in the item? Default behavior allows selection if readOnlyDisplay
is "static"
or
"readOnly"
[but not "disabled"
]. Developers may add or remove ReadOnlyDisplayAppearance values
to change this behavior.
Note that this does not apply to disabled items
, where text selection is never enabled
public FormItem setReadOnlyControlStyle(java.lang.String readOnlyControlStyle)
control style
to apply when this item
is read-only
and is using readOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
.readOnlyControlStyle
- New readOnlyControlStyle value. Default value is nullFormItem
instance, for chaining setter callsFormItemBaseStyle
public java.lang.String getReadOnlyControlStyle()
control style
to apply when this item
is read-only
and is using readOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
.FormItemBaseStyle
public FormItem setReadOnlyDisplay(ReadOnlyDisplayAppearance readOnlyDisplay)
read-only
, how should this item be
displayed to the user? If set, overrides the form-level DynamicForm.readOnlyDisplay
default.
readOnlyDisplay
. Note that calling this method for a ButtonItem
with ButtonItem.enableWhen
set is an error, since readOnlyDisplay
is then considered to always be "disabled".
readOnlyDisplay
- new readOnlyDisplay
value. Default value is nullFormItem
instance, for chaining setter callsDynamicForm.setReadOnlyDisplay(com.smartgwt.client.types.ReadOnlyDisplayAppearance)
,
Appearance overview and related methods
public ReadOnlyDisplayAppearance getReadOnlyDisplay()
read-only
, how should this item be
displayed to the user? If set, overrides the form-level DynamicForm.readOnlyDisplay
default.DynamicForm.getReadOnlyDisplay()
,
Appearance overview and related methods
public FormItem setReadOnlyHover(java.lang.String readOnlyHover)
read-only
. Note that when the form is disabled
this prompt will not be shown.
readOnlyHover
- New readOnlyHover value. Default value is nullFormItem
instance, for chaining setter callsHTMLString
public java.lang.String getReadOnlyHover()
read-only
. Note that when the form is disabled
this prompt will not be shown.
HTMLString
public FormItem setReadOnlyTextBoxStyle(java.lang.String readOnlyTextBoxStyle)
read-only
and is using readOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
. If set, overrides the form-level DynamicForm.readOnlyTextBoxStyle
default.readOnlyTextBoxStyle
- New readOnlyTextBoxStyle value. Default value is nullFormItem
instance, for chaining setter callsDynamicForm.setReadOnlyTextBoxStyle(java.lang.String)
,
FormItemBaseStyle
public java.lang.String getReadOnlyTextBoxStyle()
read-only
and is using readOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
. If set, overrides the form-level DynamicForm.readOnlyTextBoxStyle
default.DynamicForm.getReadOnlyTextBoxStyle()
,
FormItemBaseStyle
public FormItem setReadOnlyWhen(AdvancedCriteria readOnlyWhen)
read-only
. Appearance when read-only is determined by
readOnlyDisplay
. Criteria are evaluated
against the form's current values
as well as the current
rule context
. Criteria are re-evaluated every time form values
or the rule context changes, whether by end user action or by programmatic calls.
A basic criteria uses
textMatchStyle:"exact". When specified in Component XML
this property
allows shorthand formats
for defining criteria.
Note: A
FormItem using readOnlyWhen must have a name
defined.
shouldSaveValue
can be set to
false
to prevent the field from storing its value into the form's values.
readOnlyWhen
- New readOnlyWhen value. Default value is nullFormItem
instance, for chaining setter callsRuleCriteria overview and related methods
public AdvancedCriteria getReadOnlyWhen()
read-only
. Appearance when read-only is determined by
readOnlyDisplay
. Criteria are evaluated
against the form's current values
as well as the current
rule context
. Criteria are re-evaluated every time form values
or the rule context changes, whether by end user action or by programmatic calls.
A basic criteria uses
textMatchStyle:"exact". When specified in Component XML
this property
allows shorthand formats
for defining criteria.
Note: A
FormItem using readOnlyWhen must have a name
defined.
shouldSaveValue
can be set to
false
to prevent the field from storing its value into the form's values.
RuleCriteria overview and related methods
public FormItem setRedrawOnChange(java.lang.Boolean redrawOnChange)
redrawOnChange
- New redrawOnChange value. Default value is falseFormItem
instance, for chaining setter callspublic java.lang.Boolean getRedrawOnChange()
public FormItem setRejectInvalidValueOnChange(java.lang.Boolean rejectInvalidValueOnChange)
Note : This is an advanced setting
rejectInvalidValueOnChange
- New rejectInvalidValueOnChange value. Default value is falseFormItem
instance, for chaining setter callspublic java.lang.Boolean getRejectInvalidValueOnChange()
public FormItem setRequired(java.lang.Boolean required)
If the user does not fill in the required
field, the error message to be shown will be taken from these properties in the following order: requiredMessage
, DynamicForm.requiredMessage
, DataSource.requiredMessage
, requiredField
.
Note: if specified on a
FormItem, required
is only enforced on the client. required
should generally be specified on
a DataSourceField
.
If this method is called after the component has been drawn/initialized:
Setter to mark this formItem as required
, or not required at runtime. Note that an alternative approach to updating the required
flag directly would be to simply use a requiredIf
type validator.
Note that this method will not re-validate this item by default or clear any existing validation errors. If desired, this may be achieved by calling validate()
or DynamicForm.clearErrors()
.
required
- new required
value. Default value is falseFormItem
instance, for chaining setter callsValidation overview and related methods
,
Show & Hide Examplepublic java.lang.Boolean getRequired()
If the user does not fill in the required
field, the error message to be shown will be taken from these properties in the following order: requiredMessage
, DynamicForm.requiredMessage
, DataSource.requiredMessage
, requiredField
.
Note: if specified on a
FormItem, required
is only enforced on the client. required
should generally be specified on
a DataSourceField
.
Validation overview and related methods
,
Show & Hide Examplepublic FormItem setRequiredMessage(java.lang.String requiredMessage)
requiredMessage
- New requiredMessage value. Default value is nullFormItem
instance, for chaining setter callsHTMLString
,
Validation overview and related methods
public java.lang.String getRequiredMessage()
HTMLString
,
Validation overview and related methods
public FormItem setRequiredWhen(Criteria requiredWhen)
required
. Criteria are evaluated against the form's current values
as well as the current rule context
. Criteria are re-evaluated every time form values or the
rule context changes, whether by end user action or by programmatic calls.
A basic criteria uses
textMatchStyle:"exact". When specified in Component XML
this property
allows shorthand formats
for defining criteria.
Note: A
FormItem using requiredWhen must have a name
defined.
requiredWhen
- New requiredWhen value. Default value is nullFormItem
instance, for chaining setter callsRuleCriteria overview and related methods
public Criteria getRequiredWhen()
required
. Criteria are evaluated against the form's current values
as well as the current rule context
. Criteria are re-evaluated every time form values or the
rule context changes, whether by end user action or by programmatic calls.
A basic criteria uses
textMatchStyle:"exact". When specified in Component XML
this property
allows shorthand formats
for defining criteria.
Note: A
FormItem using requiredWhen must have a name
defined.
RuleCriteria overview and related methods
public FormItem setRowSpan(int rowSpan)
rowSpan
- New rowSpan value. Default value is 1FormItem
instance, for chaining setter callsFormLayout overview and related methods
public int getRowSpan()
FormLayout overview and related methods
public FormItem setSaveOnEnter(java.lang.Boolean saveOnEnter)
saveOnEnter
is true on the parent form.saveOnEnter
- New saveOnEnter value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getSaveOnEnter()
saveOnEnter
is true on the parent form.public FormItem setSelectOnClick(java.lang.Boolean selectOnClick)
selectOnClick
behavior to be configured
on a per-FormItem basis. Normally all items in a form default to the value of DynamicForm.selectOnClick
.selectOnClick
- New selectOnClick value. Default value is nullFormItem
instance, for chaining setter callsFocus overview and related methods
public java.lang.Boolean getSelectOnClick()
selectOnClick
behavior to be configured
on a per-FormItem basis. Normally all items in a form default to the value of DynamicForm.selectOnClick
.Focus overview and related methods
public FormItem setSelectOnFocus(java.lang.Boolean selectOnFocus)
selectOnFocus
behavior to be configured
on a per-FormItem basis. Normally all items in a form default to the value of DynamicForm.selectOnFocus
.selectOnFocus
- New selectOnFocus value. Default value is nullFormItem
instance, for chaining setter callsFocus overview and related methods
public java.lang.Boolean getSelectOnFocus()
selectOnFocus
behavior to be configured
on a per-FormItem basis. Normally all items in a form default to the value of DynamicForm.selectOnFocus
.Focus overview and related methods
public FormItem setShouldSaveValue(java.lang.Boolean shouldSaveValue)
form.getValues()
? shouldSaveValue:false
is used
to mark formItems which do not correspond to the underlying data model and should not save a value into the form's
values
. Example includes visual separators, password
re-type fields, or checkboxes used to show/hide other form items.
A shouldSaveValue:false
item should
be given a value either via defaultValue
or by
calling form.setValue(item, value)
or formItem.setValue(value)
. Providing a value via form.values
or form.setValues()
will automatically switch the item to
shouldSaveValue:true
.
Note that
shouldSaveValue
- New shouldSaveValue value. Default value is trueFormItem
instance, for chaining setter callspublic java.lang.Boolean getShouldSaveValue()
form.getValues()
? shouldSaveValue:false
is used
to mark formItems which do not correspond to the underlying data model and should not save a value into the form's
values
. Example includes visual separators, password
re-type fields, or checkboxes used to show/hide other form items.
A shouldSaveValue:false
item should
be given a value either via defaultValue
or by
calling form.setValue(item, value)
or formItem.setValue(value)
. Providing a value via form.values
or form.setValues()
will automatically switch the item to
shouldSaveValue:true
.
Note that
public FormItem setShowClippedTitleOnHover(boolean showClippedTitleOnHover)
A
TitleHoverEvent
is fired before the hover is displayed, allowing the hover to be canceled if desired. The
HTML shown in the hover can be customized by setting a FormItemHoverFormatter
on either this
FormItem
or the DynamicForm
. See setItemTitleHoverFormatter()
.
showClippedTitleOnHover
- New showClippedTitleOnHover value. Default value is trueFormItem
instance, for chaining setter callspublic boolean getShowClippedTitleOnHover()
A
TitleHoverEvent
is fired before the hover is displayed, allowing the hover to be canceled if desired. The
HTML shown in the hover can be customized by setting a FormItemHoverFormatter
on either this
FormItem
or the DynamicForm
. See setItemTitleHoverFormatter()
.
public FormItem setShowClippedValueOnHover(java.lang.Boolean showClippedValueOnHover)
A
ValueHoverEvent
is fired before the hover is displayed, allowing the hover to be canceled if desired. The
HTML shown in the hover can be customized by setting a FormItemHoverFormatter
on either this
FormItem
or the DynamicForm
. See setItemValueHoverFormatter()
.
showClippedValueOnHover
- New showClippedValueOnHover value. Default value is trueFormItem
instance, for chaining setter callspublic java.lang.Boolean getShowClippedValueOnHover()
A
ValueHoverEvent
is fired before the hover is displayed, allowing the hover to be canceled if desired. The
HTML shown in the hover can be customized by setting a FormItemHoverFormatter
on either this
FormItem
or the DynamicForm
. See setItemValueHoverFormatter()
.
public FormItem setShowDeletions(java.lang.Boolean showDeletions)
multiple values
, this
causes distinct CSS styling to be applied to values that the user has unselected. Only allowed when showPending
is true
. Defaults to the
form-level DynamicForm.showDeletions
setting if
set; otherwise, to the value of showPending
.
Only supported for MultiComboBoxItem
and for SelectItem
when multiple:true
is set. The specific default behaviors
are:
MultiComboBoxItem
, buttons corresponding to deleted values (also called "deselected
buttons") will be disabled and have their Button.baseStyle
set to MultiComboBoxItem.deselectedButtonStyle
. SelectItem
, valueDeselectedCSSText
is applied to any
deleted value in the text box. In addition, "Deselected" is appended to the cells' ListGrid.baseStyle
for cells in the pickList menu corresponding
to deleted values. NOTE: When a value is shown as deleted, this is not reflected to screen readers, and screen readers are instructed to ignore the deleted value. Therefore, it is not advisable to design a UI where it is necessary for the user to know whether a value is shown as deleted in order to work with the form.
Note : This is an advanced setting
showDeletions
- New showDeletions value. Default value is nullFormItem
instance, for chaining setter callsDynamicForm.setShowDeletions(java.lang.Boolean)
public java.lang.Boolean getShowDeletions()
multiple values
, this
causes distinct CSS styling to be applied to values that the user has unselected. Only allowed when showPending
is true
. Defaults to the
form-level DynamicForm.showDeletions
setting if
set; otherwise, to the value of showPending
.
Only supported for MultiComboBoxItem
and for SelectItem
when multiple:true
is set. The specific default behaviors
are:
MultiComboBoxItem
, buttons corresponding to deleted values (also called "deselected
buttons") will be disabled and have their Button.baseStyle
set to MultiComboBoxItem.deselectedButtonStyle
. SelectItem
, valueDeselectedCSSText
is applied to any
deleted value in the text box. In addition, "Deselected" is appended to the cells' ListGrid.baseStyle
for cells in the pickList menu corresponding
to deleted values. NOTE: When a value is shown as deleted, this is not reflected to screen readers, and screen readers are instructed to ignore the deleted value. Therefore, it is not advisable to design a UI where it is necessary for the user to know whether a value is shown as deleted in order to work with the form.
DynamicForm.getShowDeletions()
public FormItem setShowDisabled(java.lang.Boolean showDisabled)
See FormItemStyling
for more details on formItem styling.
If this method is called after the component has been drawn/initialized:
Setter method for showDisabled
Note : This is an advanced setting
showDisabled
- new showDisabled setting. Default value is trueFormItem
instance, for chaining setter callssetCellStyle(java.lang.String)
,
FormItemStyling overview and related methods
public java.lang.Boolean getShowDisabled()
See FormItemStyling
for more details on formItem styling.
getCellStyle()
,
FormItemStyling overview and related methods
public FormItem setShowDisabledIconsOnFocus(java.lang.Boolean showDisabledIconsOnFocus)
showIconsOnFocus
is true, should icons
marked as disabled be shown on focus? Default setting is false
- it is not commonly desirable to
present a user with a disabled icon on focus.
Can be overridden at the icon level by FormItemIcon.showDisabledOnFocus
Note : This is an advanced setting
showDisabledIconsOnFocus
- New showDisabledIconsOnFocus value. Default value is falseFormItem
instance, for chaining setter callspublic java.lang.Boolean getShowDisabledIconsOnFocus()
showIconsOnFocus
is true, should icons
marked as disabled be shown on focus? Default setting is false
- it is not commonly desirable to
present a user with a disabled icon on focus.
Can be overridden at the icon level by FormItemIcon.showDisabledOnFocus
public FormItem setShowDisabledPickerIconOnFocus(java.lang.Boolean showDisabledPickerIconOnFocus)
showPickerIconOnFocus
is true,
should the picker icon be shown on focus if it is disabled (as in a read-only item, for example?) Default setting is
false
- it is not commonly desirable to present a user with a disabled icon on focus.
Can be
overridden at the icon level by FormItemIcon.showDisabledOnFocus
Note : This is an advanced setting
showDisabledPickerIconOnFocus
- New showDisabledPickerIconOnFocus value. Default value is falseFormItem
instance, for chaining setter callspublic java.lang.Boolean getShowDisabledPickerIconOnFocus()
showPickerIconOnFocus
is true,
should the picker icon be shown on focus if it is disabled (as in a read-only item, for example?) Default setting is
false
- it is not commonly desirable to present a user with a disabled icon on focus.
Can be
overridden at the icon level by FormItemIcon.showDisabledOnFocus
public FormItem setShowErrorIcon(java.lang.Boolean showErrorIcon)
showErrorIcons
, showErrorText
, errorOrientation
, and showErrorStyle
control how validation errors are
displayed when they are displayed inline in the form (next to the form item where there is a validation error). To
instead display all errors at the top of the form, set showInlineErrors
:false.
showErrorIcons
, showErrorText
, errorOrientation
and showErrorStyle
are all boolean properties, and can be set on a DynamicForm to control the behavior form-wide, or set on individual
FormItems.
The HTML displayed next to a form item with errors is generated by getErrorHTML()
. The default implementation of that method
respects showErrorIcons
and showErrorText
as follows:
showErrorIcons
, or
showErrorIcon
at the FormItem level controls whether an error icon should appear next to fields which have
validation errors. The icon's appearance is governed by errorIconSrc
, errorIconWidth
and errorIconHeight
showErrorText
determines whether the text of the validation error should be displayed next to fields which have validation errors. The
attribute DynamicForm.showTitlesWithErrorMessages
may be set to prefix error messages with the form item's title +
":"
(may be desired if the item has showTitle
set to false).
If showErrorText
is unset, the error text will be shown if DynamicForm.linearMode
is true (or DynamicForm.linearOnMobile
is true for mobile devices),
otherwise it will not be shown.
In addition to this:
DynamicForm.errorOrientation
controls where the error
HTML should appear relative to form items. Therefore the combination of showErrorText
:false
and errorOrientation
:"left"
creates a
compact validation error display consisting of just an icon, to the left of the item with the error message available
via a hover (similar appearance to ListGrid validation error display).
If errorOrientation
is unset,
the error orientation will default to "top" if DynamicForm.linearMode
is enabled (or DynamicForm.linearOnMobile
is true for mobile devices) and error text is not showing, "left" otherwise.
showErrorStyle
determines whether fields with validation errors should have special styling applied to
them. Error styling is achieved by applying suffixes to existing styling applied to various parts of the form item. See
FormItemBaseStyle
for more on this.
showErrorIcon
- New showErrorIcon value. Default value is nullFormItem
instance, for chaining setter callsAppearance overview and related methods
public java.lang.Boolean getShowErrorIcon()
showErrorIcons
, showErrorText
, errorOrientation
, and showErrorStyle
control how validation errors are
displayed when they are displayed inline in the form (next to the form item where there is a validation error). To
instead display all errors at the top of the form, set showInlineErrors
:false.
showErrorIcons
, showErrorText
, errorOrientation
and showErrorStyle
are all boolean properties, and can be set on a DynamicForm to control the behavior form-wide, or set on individual
FormItems.
The HTML displayed next to a form item with errors is generated by getErrorHTML()
. The default implementation of that method
respects showErrorIcons
and showErrorText
as follows:
showErrorIcons
, or
showErrorIcon
at the FormItem level controls whether an error icon should appear next to fields which have
validation errors. The icon's appearance is governed by errorIconSrc
, errorIconWidth
and errorIconHeight
showErrorText
determines whether the text of the validation error should be displayed next to fields which have validation errors. The
attribute DynamicForm.showTitlesWithErrorMessages
may be set to prefix error messages with the form item's title +
":"
(may be desired if the item has showTitle
set to false).
If showErrorText
is unset, the error text will be shown if DynamicForm.linearMode
is true (or DynamicForm.linearOnMobile
is true for mobile devices),
otherwise it will not be shown.
In addition to this:
DynamicForm.errorOrientation
controls where the error
HTML should appear relative to form items. Therefore the combination of showErrorText
:false
and errorOrientation
:"left"
creates a
compact validation error display consisting of just an icon, to the left of the item with the error message available
via a hover (similar appearance to ListGrid validation error display).
If errorOrientation
is unset,
the error orientation will default to "top" if DynamicForm.linearMode
is enabled (or DynamicForm.linearOnMobile
is true for mobile devices) and error text is not showing, "left" otherwise.
showErrorStyle
determines whether fields with validation errors should have special styling applied to
them. Error styling is achieved by applying suffixes to existing styling applied to various parts of the form item. See
FormItemBaseStyle
for more on this.
Appearance overview and related methods
public FormItem setShowErrorStyle(java.lang.Boolean showErrorStyle)
showErrorIcons
, showErrorText
, errorOrientation
, and showErrorStyle
control how validation errors are
displayed when they are displayed inline in the form (next to the form item where there is a validation error). To
instead display all errors at the top of the form, set showInlineErrors
:false.
showErrorIcons
, showErrorText
, errorOrientation
and showErrorStyle
are all boolean properties, and can be set on a DynamicForm to control the behavior form-wide, or set on individual
FormItems.
The HTML displayed next to a form item with errors is generated by getErrorHTML()
. The default implementation of that method
respects showErrorIcons
and showErrorText
as follows:
showErrorIcons
, or
showErrorIcon
at the FormItem level controls whether an error icon should appear next to fields which have
validation errors. The icon's appearance is governed by errorIconSrc
, errorIconWidth
and errorIconHeight
showErrorText
determines whether the text of the validation error should be displayed next to fields which have validation errors. The
attribute DynamicForm.showTitlesWithErrorMessages
may be set to prefix error messages with the form item's title +
":"
(may be desired if the item has showTitle
set to false).
If showErrorText
is unset, the error text will be shown if DynamicForm.linearMode
is true (or DynamicForm.linearOnMobile
is true for mobile devices),
otherwise it will not be shown.
In addition to this:
DynamicForm.errorOrientation
controls where the error
HTML should appear relative to form items. Therefore the combination of showErrorText
:false
and errorOrientation
:"left"
creates a
compact validation error display consisting of just an icon, to the left of the item with the error message available
via a hover (similar appearance to ListGrid validation error display).
If errorOrientation
is unset,
the error orientation will default to "top" if DynamicForm.linearMode
is enabled (or DynamicForm.linearOnMobile
is true for mobile devices) and error text is not showing, "left" otherwise.
showErrorStyle
determines whether fields with validation errors should have special styling applied to
them. Error styling is achieved by applying suffixes to existing styling applied to various parts of the form item. See
FormItemBaseStyle
for more on this.
showErrorStyle
- New showErrorStyle value. Default value is nullFormItem
instance, for chaining setter callssetCellStyle(java.lang.String)
,
Appearance overview and related methods
public java.lang.Boolean getShowErrorStyle()
showErrorIcons
, showErrorText
, errorOrientation
, and showErrorStyle
control how validation errors are
displayed when they are displayed inline in the form (next to the form item where there is a validation error). To
instead display all errors at the top of the form, set showInlineErrors
:false.
showErrorIcons
, showErrorText
, errorOrientation
and showErrorStyle
are all boolean properties, and can be set on a DynamicForm to control the behavior form-wide, or set on individual
FormItems.
The HTML displayed next to a form item with errors is generated by getErrorHTML()
. The default implementation of that method
respects showErrorIcons
and showErrorText
as follows:
showErrorIcons
, or
showErrorIcon
at the FormItem level controls whether an error icon should appear next to fields which have
validation errors. The icon's appearance is governed by errorIconSrc
, errorIconWidth
and errorIconHeight
showErrorText
determines whether the text of the validation error should be displayed next to fields which have validation errors. The
attribute DynamicForm.showTitlesWithErrorMessages
may be set to prefix error messages with the form item's title +
":"
(may be desired if the item has showTitle
set to false).
If showErrorText
is unset, the error text will be shown if DynamicForm.linearMode
is true (or DynamicForm.linearOnMobile
is true for mobile devices),
otherwise it will not be shown.
In addition to this:
DynamicForm.errorOrientation
controls where the error
HTML should appear relative to form items. Therefore the combination of showErrorText
:false
and errorOrientation
:"left"
creates a
compact validation error display consisting of just an icon, to the left of the item with the error message available
via a hover (similar appearance to ListGrid validation error display).
If errorOrientation
is unset,
the error orientation will default to "top" if DynamicForm.linearMode
is enabled (or DynamicForm.linearOnMobile
is true for mobile devices) and error text is not showing, "left" otherwise.
showErrorStyle
determines whether fields with validation errors should have special styling applied to
them. Error styling is achieved by applying suffixes to existing styling applied to various parts of the form item. See
FormItemBaseStyle
for more on this.
getCellStyle()
,
Appearance overview and related methods
public FormItem setShowErrorText(java.lang.Boolean showErrorText)
showErrorIcons
, showErrorText
, errorOrientation
, and showErrorStyle
control how validation errors are
displayed when they are displayed inline in the form (next to the form item where there is a validation error). To
instead display all errors at the top of the form, set showInlineErrors
:false.
showErrorIcons
, showErrorText
, errorOrientation
and showErrorStyle
are all boolean properties, and can be set on a DynamicForm to control the behavior form-wide, or set on individual
FormItems.
The HTML displayed next to a form item with errors is generated by getErrorHTML()
. The default implementation of that method
respects showErrorIcons
and showErrorText
as follows:
showErrorIcons
, or
showErrorIcon
at the FormItem level controls whether an error icon should appear next to fields which have
validation errors. The icon's appearance is governed by errorIconSrc
, errorIconWidth
and errorIconHeight
showErrorText
determines whether the text of the validation error should be displayed next to fields which have validation errors. The
attribute DynamicForm.showTitlesWithErrorMessages
may be set to prefix error messages with the form item's title +
":"
(may be desired if the item has showTitle
set to false).
If showErrorText
is unset, the error text will be shown if DynamicForm.linearMode
is true (or DynamicForm.linearOnMobile
is true for mobile devices),
otherwise it will not be shown.
In addition to this:
DynamicForm.errorOrientation
controls where the error
HTML should appear relative to form items. Therefore the combination of showErrorText
:false
and errorOrientation
:"left"
creates a
compact validation error display consisting of just an icon, to the left of the item with the error message available
via a hover (similar appearance to ListGrid validation error display).
If errorOrientation
is unset,
the error orientation will default to "top" if DynamicForm.linearMode
is enabled (or DynamicForm.linearOnMobile
is true for mobile devices) and error text is not showing, "left" otherwise.
showErrorStyle
determines whether fields with validation errors should have special styling applied to
them. Error styling is achieved by applying suffixes to existing styling applied to various parts of the form item. See
FormItemBaseStyle
for more on this.
showErrorText
- New showErrorText value. Default value is nullFormItem
instance, for chaining setter callsAppearance overview and related methods
public java.lang.Boolean getShowErrorText()
showErrorIcons
, showErrorText
, errorOrientation
, and showErrorStyle
control how validation errors are
displayed when they are displayed inline in the form (next to the form item where there is a validation error). To
instead display all errors at the top of the form, set showInlineErrors
:false.
showErrorIcons
, showErrorText
, errorOrientation
and showErrorStyle
are all boolean properties, and can be set on a DynamicForm to control the behavior form-wide, or set on individual
FormItems.
The HTML displayed next to a form item with errors is generated by getErrorHTML()
. The default implementation of that method
respects showErrorIcons
and showErrorText
as follows:
showErrorIcons
, or
showErrorIcon
at the FormItem level controls whether an error icon should appear next to fields which have
validation errors. The icon's appearance is governed by errorIconSrc
, errorIconWidth
and errorIconHeight
showErrorText
determines whether the text of the validation error should be displayed next to fields which have validation errors. The
attribute DynamicForm.showTitlesWithErrorMessages
may be set to prefix error messages with the form item's title +
":"
(may be desired if the item has showTitle
set to false).
If showErrorText
is unset, the error text will be shown if DynamicForm.linearMode
is true (or DynamicForm.linearOnMobile
is true for mobile devices),
otherwise it will not be shown.
In addition to this:
DynamicForm.errorOrientation
controls where the error
HTML should appear relative to form items. Therefore the combination of showErrorText
:false
and errorOrientation
:"left"
creates a
compact validation error display consisting of just an icon, to the left of the item with the error message available
via a hover (similar appearance to ListGrid validation error display).
If errorOrientation
is unset,
the error orientation will default to "top" if DynamicForm.linearMode
is enabled (or DynamicForm.linearOnMobile
is true for mobile devices) and error text is not showing, "left" otherwise.
showErrorStyle
determines whether fields with validation errors should have special styling applied to
them. Error styling is achieved by applying suffixes to existing styling applied to various parts of the form item. See
FormItemBaseStyle
for more on this.
Appearance overview and related methods
public FormItem setShowFocused(java.lang.Boolean showFocused)
See FormItemStyling
for more details on formItem styling.
Note : This is an advanced setting
showFocused
- New showFocused value. Default value is falseFormItem
instance, for chaining setter callssetCellStyle(java.lang.String)
,
FormItemStyling overview and related methods
public java.lang.Boolean getShowFocused()
See FormItemStyling
for more details on formItem styling.
getCellStyle()
,
FormItemStyling overview and related methods
public FormItem setShowFocusedErrorState(java.lang.Boolean showFocusedErrorState)
Note : This is an advanced setting
showFocusedErrorState
- New showFocusedErrorState value. Default value is falseFormItem
instance, for chaining setter callssetCellStyle(java.lang.String)
,
Appearance overview and related methods
public java.lang.Boolean getShowFocusedErrorState()
getCellStyle()
,
Appearance overview and related methods
public FormItem setShowFocusedIcons(java.lang.Boolean showFocusedIcons)
showFocused
property.
Note : This is an advanced setting
showFocusedIcons
- New showFocusedIcons value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getShowFocusedIcons()
showFocused
property.public FormItem setShowFocusedPickerIcon(java.lang.Boolean showFocusedPickerIcon)
showPickerIcon
is true for this item,
should the picker icon show a focused image when the form item has focus?showFocusedPickerIcon
- New showFocusedPickerIcon value. Default value is falseFormItem
instance, for chaining setter callspublic java.lang.Boolean getShowFocusedPickerIcon()
showPickerIcon
is true for this item,
should the picker icon show a focused image when the form item has focus?public FormItem setShowHint(java.lang.Boolean showHint)
Note : This is an advanced setting
showHint
- New showHint value. Default value is trueFormItem
instance, for chaining setter callsAppearance overview and related methods
public java.lang.Boolean getShowHint()
Appearance overview and related methods
public FormItem setShowIcons(java.lang.Boolean showIcons)
icons
for
this item.
Note : This is an advanced setting
showIcons
- New showIcons value. Default value is trueFormItem
instance, for chaining setter callspublic java.lang.Boolean getShowIcons()
icons
for
this item.public FormItem setShowIconsOnFocus(java.lang.Boolean showIconsOnFocus)
icons
when the item gets focus, and hide them
when it loses focus. Can be overridden at the icon level by FormItemIcon.showOnFocus
. Note that icons
marked as disabled will not be shown on focus even if this flag is true by default. This may be overridden by showDisabledIconsOnFocus
.
If this method is called after the component has been drawn/initialized:
Sets showIconsOnFocus
and causes the visibility of all icons
to be updated and the item redrawn as appropriate.
Note : This is an advanced setting
showIconsOnFocus
- new value of showIconsOnFocus
. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getShowIconsOnFocus()
icons
when the item gets focus, and hide them
when it loses focus. Can be overridden at the icon level by FormItemIcon.showOnFocus
. Note that icons
marked as disabled will not be shown on focus even if this flag is true by default. This may be overridden by showDisabledIconsOnFocus
.
public FormItem setShowImageAsURL(java.lang.Boolean showImageAsURL)
type:"image"
, if the field is non editable, and being
displayed with readOnlyDisplay:"static"
,
should the value (URL) be displayed as text, or should an image be rendered? If unset, DynamicForm.showImageAsURL
will be consulted instead.
showImageAsURL
- New showImageAsURL value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getShowImageAsURL()
type:"image"
, if the field is non editable, and being
displayed with readOnlyDisplay:"static"
,
should the value (URL) be displayed as text, or should an image be rendered? If unset, DynamicForm.showImageAsURL
will be consulted instead.
public FormItem setShowOldValueInHover(java.lang.Boolean showOldValueInHover)
FormItem.itemHover()
event would fire). When
showOldValueInHover
and the form's
DynamicForm.showOldValueInHover
are both
unset, defaults to the value of showPending
.
The message shown is controlled by originalValueMessage
, unless the item is disabled
and disabledHover
is set - in this case, the
hover shows the disabledHover
HTML.
Note : This is an advanced setting
showOldValueInHover
- New showOldValueInHover value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getShowOldValueInHover()
FormItem.itemHover()
event would fire). When
showOldValueInHover
and the form's
DynamicForm.showOldValueInHover
are both
unset, defaults to the value of showPending
.
The message shown is controlled by originalValueMessage
, unless the item is disabled
and disabledHover
is set - in this case, the
hover shows the disabledHover
HTML.
public FormItem setShowOver(boolean showOver)
When enabled, the "Over"
styling is applied to the text box, control table (if present), and pickerIcon (if present), and any icons where FormItemIcon.showOver
is true and FormItemIcon.showOverWhen
is set to "textBox".
These behaviors can be disabled piecemeal via updateTextBoxOnOver
, updateControlOnOver
and updatePickerIconOnOver
properties.
Developers may also show rollover styling for other icons (see showOverIcons
and FormItemIcon.showOverWhen
).
See FormItemStyling
for more details on formItem styling.
Note : This is an advanced setting
showOver
- New showOver value. Default value is falseFormItem
instance, for chaining setter callsFormItemStyling overview and related methods
public boolean getShowOver()
When enabled, the "Over"
styling is applied to the text box, control table (if present), and pickerIcon (if present), and any icons where FormItemIcon.showOver
is true and FormItemIcon.showOverWhen
is set to "textBox".
These behaviors can be disabled piecemeal via updateTextBoxOnOver
, updateControlOnOver
and updatePickerIconOnOver
properties.
Developers may also show rollover styling for other icons (see showOverIcons
and FormItemIcon.showOverWhen
).
See FormItemStyling
for more details on formItem styling.
FormItemStyling overview and related methods
public FormItem setShowOverIcons(java.lang.Boolean showOverIcons)
showOver
property.
Note : This is an advanced setting
showOverIcons
- New showOverIcons value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getShowOverIcons()
showOver
property.public FormItem setShowPending(java.lang.Boolean showPending)
true
, causes the "Pending" optional suffix to be added if the item's current value differs from the
value that would be restored by a call to DynamicForm.resetValues()
. shouldSaveValue
must be true
for this setting to have an effect.
Styling of the value is updated only
after the FormItem.change()
event is
processed, so depending on the value of changeOnKeypress
, styling may be updated immediately on keystroke or only when the user leaves the field.
Default
styling is provided for the Enterprise, EnterpriseBlue, and Graphite skins only. showPending
should not be
enabled for an item when using a skin without default styling unless the default FormItem.pendingStatusChanged()
behavior is canceled and a custom pending visual state is implemented by the item.
NOTE: Whether an item is shown as pending is not reflected to screen readers. Therefore, it is not advisable to design a UI where it is necessary for the user to know whether an item is shown as pending in order to work with the form.
Note : This is an advanced setting
showPending
- New showPending value. Default value is nullFormItem
instance, for chaining setter callsPendingStatusChangedEvent
,
Pending Values Examplepublic java.lang.Boolean getShowPending()
true
, causes the "Pending" optional suffix to be added if the item's current value differs from the
value that would be restored by a call to DynamicForm.resetValues()
. shouldSaveValue
must be true
for this setting to have an effect.
Styling of the value is updated only
after the FormItem.change()
event is
processed, so depending on the value of changeOnKeypress
, styling may be updated immediately on keystroke or only when the user leaves the field.
Default
styling is provided for the Enterprise, EnterpriseBlue, and Graphite skins only. showPending
should not be
enabled for an item when using a skin without default styling unless the default FormItem.pendingStatusChanged()
behavior is canceled and a custom pending visual state is implemented by the item.
NOTE: Whether an item is shown as pending is not reflected to screen readers. Therefore, it is not advisable to design a UI where it is necessary for the user to know whether an item is shown as pending in order to work with the form.
PendingStatusChangedEvent
,
Pending Values Examplepublic FormItem 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 showPicker()
.showPickerIcon
- New showPickerIcon value. Default value is nullFormItem
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 showPicker()
.public FormItem setShowPickerIconOnFocus(java.lang.Boolean showPickerIconOnFocus)
FormItemIcon.showOnFocus
. Note that a
pickerIcon marked as disabled will not be shown on focus even if this flag is true by default. This may be overridden by
showDisabledIconsOnFocus
.
If this method is called after the component has been drawn/initialized:
Sets showPickerIconOnFocus
and causes the visibility of the picker icon to be updated and the item redrawn as appropriate.
Note : This is an advanced setting
showPickerIconOnFocus
- new value of showPickerIconOnFocus
. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getShowPickerIconOnFocus()
FormItemIcon.showOnFocus
. Note that a
pickerIcon marked as disabled will not be shown on focus even if this flag is true by default. This may be overridden by
showDisabledIconsOnFocus
.
public FormItem setShowRTL(boolean showRTL)
Note : This is an advanced setting
showRTL
- New showRTL value. Default value is falseFormItem
instance, for chaining setter callssetCellStyle(java.lang.String)
,
Appearance overview and related methods
public boolean getShowRTL()
getCellStyle()
,
Appearance overview and related methods
public FormItem setShowTitle(java.lang.Boolean showTitle)
Note: the default value of this attribute is overridden by some subclasses.
showTitle
- New showTitle value. Default value is trueFormItem
instance, for chaining setter callspublic java.lang.Boolean getShowTitle()
Note: the default value of this attribute is overridden by some subclasses.
public FormItem setShowValueIconOnly(java.lang.Boolean showValueIconOnly)
valueIcons
is set, this property may be set to
show the valueIcon only and prevent the standard form item element or text from displaying
Note : This is an advanced setting
showValueIconOnly
- New showValueIconOnly value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getShowValueIconOnly()
valueIcons
is set, this property may be set to
show the valueIcon only and prevent the standard form item element or text from displayingpublic FormItem setStartRow(java.lang.Boolean startRow)
startRow
- New startRow value. Default value is falseFormItem
instance, for chaining setter callssetLinearStartRow(int)
,
FormLayout overview and related methods
public java.lang.Boolean getStartRow()
getLinearStartRow()
,
FormLayout overview and related methods
public FormItem setStaticHeight(java.lang.Integer staticHeight)
canEdit
is false and readOnlyDisplay
is "static". The normal
height
is used if this property is not set.staticHeight
- New staticHeight value. Default value is nullFormItem
instance, for chaining setter callssetHeight(int)
,
FormLayout overview and related methods
public java.lang.Integer getStaticHeight()
canEdit
is false and readOnlyDisplay
is "static". The normal
height
is used if this property is not set.getHeight()
,
FormLayout overview and related methods
public FormItem setStopOnError(java.lang.Boolean stopOnError)
This property defaults to DynamicForm.stopOnError
if unset.
Enabling this
property also implies validateOnExit
is
automatically enabled. If there are server-based validators on this item, setting this property also implies that synchronousValidation
is forced on.
stopOnError
- New stopOnError value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getStopOnError()
This property defaults to DynamicForm.stopOnError
if unset.
Enabling this
property also implies validateOnExit
is
automatically enabled. If there are server-based validators on this item, setting this property also implies that synchronousValidation
is forced on.
public FormItem setStoreDisplayValues(java.lang.Boolean storeDisplayValues)
DynamicForm.storeDisplayValues
property for this field.
Note : This is an advanced setting
storeDisplayValues
- New storeDisplayValues value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getStoreDisplayValues()
DynamicForm.storeDisplayValues
property for this field.public FormItem setSupportsCutPasteEvents(boolean supportsCutPasteEvents)
This attribute only applies to freeform text entry
fields such as TextItem
and TextAreaItem
, and only if changeOnKeypress
is true. If true, developers can
detect the user editing the value via cut or paste interactions (triggered from keyboard shortcuts or the native
browser menu options) using the isCutEvent()
and
isPasteEvent()
methods. This allows custom
cut/paste handling to be added to the various change notification flow methods including FormItem.change()
, and FormItem.transformInput()
.
supportsCutPasteEvents
- New supportsCutPasteEvents value. Default value is falseFormItem
instance, for chaining setter callspublic boolean getSupportsCutPasteEvents()
This attribute only applies to freeform text entry
fields such as TextItem
and TextAreaItem
, and only if changeOnKeypress
is true. If true, developers can
detect the user editing the value via cut or paste interactions (triggered from keyboard shortcuts or the native
browser menu options) using the isCutEvent()
and
isPasteEvent()
methods. This allows custom
cut/paste handling to be added to the various change notification flow methods including FormItem.change()
, and FormItem.transformInput()
.
public FormItem setSuppressValueIcon(java.lang.Boolean suppressValueIcon)
valueIcons
is set, this property may be set to
prevent the value icons from showing up next to the form items value
Note : This is an advanced setting
suppressValueIcon
- New suppressValueIcon value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getSuppressValueIcon()
valueIcons
is set, this property may be set to
prevent the value icons from showing up next to the form items valuepublic FormItem setSynchronousValidation(java.lang.Boolean synchronousValidation)
If false, the form will try to avoid blocking user interaction until it is strictly required. That is until the user attempts to use a FormItem whose state could be affected by a server request that has not yet returned.
synchronousValidation
- New synchronousValidation value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getSynchronousValidation()
If false, the form will try to avoid blocking user interaction until it is strictly required. That is until the user attempts to use a FormItem whose state could be affected by a server request that has not yet returned.
public FormItem setTabIndex(java.lang.Integer tabIndex)
tabIndex is automatically assigned as the order that items
appear in the DynamicForm.items
list.
To specify the
tabindex of an item within the page as a whole (not just this form), use globalTabIndex
instead.
If this method is called after the component has been drawn/initialized:
Setter for tabIndex
.
tabIndex
- new tabIndex for the item. Default value is nullFormItem
instance, for chaining setter callsFocus overview and related methods
public java.lang.Integer getTabIndex()
tabIndex is automatically assigned as the order that items
appear in the DynamicForm.items
list.
To specify the
tabindex of an item within the page as a whole (not just this form), use globalTabIndex
instead.
Focus overview and related methods
public FormItem setTextAlign(Alignment textAlign)
align
may be used to control alignment of the entire form
item within its cell. textAlign
does not apply to all form item types; typically it applies only to items
showing a "textBox", such as a TextItem
or SelectItem
, as well as text-only form item types such as StaticTextItem
and HeaderItem
.
If applyAlignToText
is true, then
textAlign
will default to the align
setting if set. Otherwise, if this item has icons
, then textAlign
will default to Alignment.LEFT
(Alignment.RIGHT
in RTL mode
).
textAlign
- New textAlign value. Default value is nullFormItem
instance, for chaining setter callssetApplyAlignToText(boolean)
,
Appearance overview and related methods
public Alignment getTextAlign()
align
may be used to control alignment of the entire form
item within its cell. textAlign
does not apply to all form item types; typically it applies only to items
showing a "textBox", such as a TextItem
or SelectItem
, as well as text-only form item types such as StaticTextItem
and HeaderItem
.
If applyAlignToText
is true, then
textAlign
will default to the align
setting if set. Otherwise, if this item has icons
, then textAlign
will default to Alignment.LEFT
(Alignment.RIGHT
in RTL mode
).
getApplyAlignToText()
,
Appearance overview and related methods
public FormItem setTextBoxStyle(java.lang.String textBoxStyle)
See FormItemStyling
for an
overview of formItem styling, and the CompoundFormItem_skinning
discussion for special
skinning considerations.
If the textBoxStyle
is changed at runtime, updateState()
must be called to update the visual state of
this item.
textBoxStyle
- New textBoxStyle value. Default value is nullFormItem
instance, for chaining setter callssetCellStyle(java.lang.String)
,
FormItemBaseStyle
,
FormItemStyling overview and related methods
public java.lang.String getTextBoxStyle()
See FormItemStyling
for an
overview of formItem styling, and the CompoundFormItem_skinning
discussion for special
skinning considerations.
If the textBoxStyle
is changed at runtime, updateState()
must be called to update the visual state of
this item.
getCellStyle()
,
FormItemBaseStyle
,
FormItemStyling overview and related methods
public FormItem setTextFormula(UserSummary textFormula)
formula
is used instead. Available fields for use in
the formula are the current rule context
. The formula is
re-evaluated every time the rule context changes.
See formula
for details on available fields for the formula and
when the formula is calculated.
Note: A FormItem using a textFormula must have a name
defined. shouldSaveValue
can be set to false
to
prevent the formula field from storing the calculated value into the form's values.
textFormula
- New textFormula value. Default value is nullFormItem
instance, for chaining setter callsFormulaFields overview and related methods
public UserSummary getTextFormula()
formula
is used instead. Available fields for use in
the formula are the current rule context
. The formula is
re-evaluated every time the rule context changes.
See formula
for details on available fields for the formula and
when the formula is calculated.
Note: A FormItem using a textFormula must have a name
defined. shouldSaveValue
can be set to false
to
prevent the formula field from storing the calculated value into the form's values.
FormulaFields overview and related methods
public FormItem setTimeFormatter(TimeDisplayFormat timeFormatter)
"time"
though if no explicit dateFormatter
is specified it will be respected for other fields as well. If unspecified, a timeFormatter may be
defined at the component level
and will be
respected by fields of type "time"
.
Note : This is an advanced setting
timeFormatter
- New timeFormatter value. Default value is nullFormItem
instance, for chaining setter callssetFormat(java.lang.String)
,
Appearance overview and related methods
public TimeDisplayFormat getTimeFormatter()
"time"
though if no explicit dateFormatter
is specified it will be respected for other fields as well. If unspecified, a timeFormatter may be
defined at the component level
and will be
respected by fields of type "time"
.
getFormat()
,
Appearance overview and related methods
public FormItem setTitle(java.lang.String title)
title
- New title value. Default value is nullFormItem
instance, for chaining setter callsHTMLString
,
Basics overview and related methods
public java.lang.String getTitle()
HTMLString
,
Basics overview and related methods
public FormItem setTitleAlign(Alignment titleAlign)
If null, dynamically set according to text direction.
titleAlign
- New titleAlign value. Default value is nullFormItem
instance, for chaining setter callspublic Alignment getTitleAlign()
If null, dynamically set according to text direction.
public FormItem setTitleColSpan(int titleColSpan)
This setting only applies for items that are showing a title and
whose TitleOrientation
is either "left" or "right".
titleColSpan
- New titleColSpan value. Default value is 1FormItem
instance, for chaining setter callsFormLayout overview and related methods
public int getTitleColSpan()
This setting only applies for items that are showing a title and
whose TitleOrientation
is either "left" or "right".
FormLayout overview and related methods
public FormItem setTitleOrientation(TitleOrientation titleOrientation)
TitleOrientation
lists valid
options. Note that titles on the left or right take up a cell in tabular form layouts
, but titles on top do not.
titleOrientation
- New titleOrientation value. Default value is Canvas.LEFTFormItem
instance, for chaining setter callsDynamicForm.setTitleOrientation(com.smartgwt.client.types.TitleOrientation)
public TitleOrientation getTitleOrientation()
TitleOrientation
lists valid
options. Note that titles on the left or right take up a cell in tabular form layouts
, but titles on top do not.
DynamicForm.getTitleOrientation()
public FormItem setTitleStyle(java.lang.String titleStyle)
FormItemBaseStyle
so
will pick up stateful suffixes on focus, disabled state change etc. by default. Note the appearance of the title is
also affected by DynamicForm.titlePrefix
/titleSuffix
and DynamicForm.requiredTitlePrefix
/requiredTitleSuffix
.
titleStyle
- New titleStyle value. Default value is "formTitle"FormItem
instance, for chaining setter callssetCellStyle(java.lang.String)
,
FormItemBaseStyle
,
FormItemStyling overview and related methods
public java.lang.String getTitleStyle()
FormItemBaseStyle
so
will pick up stateful suffixes on focus, disabled state change etc. by default. Note the appearance of the title is
also affected by DynamicForm.titlePrefix
/titleSuffix
and DynamicForm.requiredTitlePrefix
/requiredTitleSuffix
.
getCellStyle()
,
FormItemBaseStyle
,
FormItemStyling overview and related methods
public FormItem setTitleVAlign(VerticalAlignment titleVAlign)
titleOrientation
is "left"
or
"right"
.titleVAlign
- New titleVAlign value. Default value is Canvas.CENTERFormItem
instance, for chaining setter callspublic VerticalAlignment getTitleVAlign()
titleOrientation
is "left"
or
"right"
.public FormItem setTop(int top)
itemLayout:"absolute"
.
itemLayout
:"absolute" only, set the top coordinate of this form item. Causes the form to redraw.
Note : This is an advanced setting
top
- New top value. Default value is 0FormItem
instance, for chaining setter callspublic int getTop()
itemLayout:"absolute"
.public FormItem setUpdateControlOnOver(java.lang.Boolean updateControlOnOver)
showOver
is true, setting this property to false
will explicitly disable showing the "Over" state for the control table element of this item (if present).
Note : This is an advanced setting
updateControlOnOver
- New updateControlOnOver value. Default value is nullFormItem
instance, for chaining setter callssetShowOver(boolean)
,
FormItemStyling overview and related methods
public java.lang.Boolean getUpdateControlOnOver()
showOver
is true, setting this property to false
will explicitly disable showing the "Over" state for the control table element of this item (if present).getShowOver()
,
FormItemStyling overview and related methods
public FormItem setUpdatePickerIconOnOver(java.lang.Boolean updatePickerIconOnOver)
showOver
is true, setting this property to false
will explicitly disable showing the "Over" state for the PickerIcon of this item (if present)
Note : This is an advanced setting
updatePickerIconOnOver
- New updatePickerIconOnOver value. Default value is nullFormItem
instance, for chaining setter callssetShowOver(boolean)
,
FormItemStyling overview and related methods
public java.lang.Boolean getUpdatePickerIconOnOver()
showOver
is true, setting this property to false
will explicitly disable showing the "Over" state for the PickerIcon of this item (if present)getShowOver()
,
FormItemStyling overview and related methods
public FormItem setUpdateTextBoxOnOver(java.lang.Boolean updateTextBoxOnOver)
showOver
is true, setting this property to false
will explicitly disable showing the "Over" state for the TextBox element of this item.
Note : This is an advanced setting
updateTextBoxOnOver
- New updateTextBoxOnOver value. Default value is nullFormItem
instance, for chaining setter callssetShowOver(boolean)
,
FormItemStyling overview and related methods
public java.lang.Boolean getUpdateTextBoxOnOver()
showOver
is true, setting this property to false
will explicitly disable showing the "Over" state for the TextBox element of this item.getShowOver()
,
FormItemStyling overview and related methods
public FormItem setUseAdvancedCriteria(java.lang.Boolean useAdvancedCriteria)
AdvancedCriteria
sub criterion object? When set
to true, causes hasAdvancedCriteria
to
return true. Can also be set at the ListGrid
level.useAdvancedCriteria
- New useAdvancedCriteria value. Default value is nullFormItem
instance, for chaining setter callsCriteriaEditing overview and related methods
public java.lang.Boolean getUseAdvancedCriteria()
AdvancedCriteria
sub criterion object? When set
to true, causes hasAdvancedCriteria
to
return true. Can also be set at the ListGrid
level.CriteriaEditing overview and related methods
public FormItem setUseDisabledHintStyleForReadOnly(java.lang.Boolean useDisabledHintStyleForReadOnly)
read-only
fields use the same style name
as editable fields for in-field hints, unless they are disabled
or configured to use a disabled ReadOnlyDisplayAppearance
. This is described under TextItem.showHintInField
If
useDisabledHintStyleForReadOnly
is set, the "HintDisabled" style will be used for read-only fields
regardless of their ReadOnlyDisplayAppearance
. This allows you to use a different in-field hint style for
read-only fields without having to use a general disabled appearance for those fields
useDisabledHintStyleForReadOnly
- New useDisabledHintStyleForReadOnly value. Default value is nullFormItem
instance, for chaining setter callsAppearance overview and related methods
public java.lang.Boolean getUseDisabledHintStyleForReadOnly()
read-only
fields use the same style name
as editable fields for in-field hints, unless they are disabled
or configured to use a disabled ReadOnlyDisplayAppearance
. This is described under TextItem.showHintInField
If
useDisabledHintStyleForReadOnly
is set, the "HintDisabled" style will be used for read-only fields
regardless of their ReadOnlyDisplayAppearance
. This allows you to use a different in-field hint style for
read-only fields without having to use a general disabled appearance for those fields
Appearance overview and related methods
public FormItem setUseLocalDisplayFieldValue(java.lang.Boolean useLocalDisplayFieldValue)
displayField
is specified for a field,
should the display value for the field be picked up from the record currently being edited
? This behavior is typically
valuable for dataBound components where the displayField is specified at the DataSourceField level. See DataSourceField.displayField
for more on this.
Note that
for DataSources backed by the Smart GWT server
, fields with a
specified DataSourceField.foreignKey
and DataSourceField.displayField
will automatically have this
property set to true if not explicitly set to false in the dataSource configuration.
Otherwise, if not explicitly set, local display value will be used unless:
DataSourceField.foreignKey
specificationname
differs from the valueField
for the itemuseLocalDisplayFieldValue
- New useLocalDisplayFieldValue value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getUseLocalDisplayFieldValue()
displayField
is specified for a field,
should the display value for the field be picked up from the record currently being edited
? This behavior is typically
valuable for dataBound components where the displayField is specified at the DataSourceField level. See DataSourceField.displayField
for more on this.
Note that
for DataSources backed by the Smart GWT server
, fields with a
specified DataSourceField.foreignKey
and DataSourceField.displayField
will automatically have this
property set to true if not explicitly set to false in the dataSource configuration.
Otherwise, if not explicitly set, local display value will be used unless:
DataSourceField.foreignKey
specificationname
differs from the valueField
for the itempublic FormItem setValidateOnChange(java.lang.Boolean validateOnChange)
Note that this property can also be set at the form level or on each validator; If true at
the form or field level, validators not explicitly set with validateOnChange:false
will be fired on change
- displaying errors and rejecting the change on validation failure.
validateOnChange
- New validateOnChange value. Default value is falseFormItem
instance, for chaining setter callsDynamicForm.setValidateOnChange(java.lang.Boolean)
public java.lang.Boolean getValidateOnChange()
Note that this property can also be set at the form level or on each validator; If true at
the form or field level, validators not explicitly set with validateOnChange:false
will be fired on change
- displaying errors and rejecting the change on validation failure.
DynamicForm.getValidateOnChange()
public FormItem setValidateOnExit(java.lang.Boolean validateOnExit)
Note that this property can also be set at the form level. If true at either level the validator will be fired on editorExit.
validateOnExit
- New validateOnExit value. Default value is falseFormItem
instance, for chaining setter callsDynamicForm.setValidateOnExit(java.lang.Boolean)
public java.lang.Boolean getValidateOnExit()
Note that this property can also be set at the form level. If true at either level the validator will be fired on editorExit.
DynamicForm.getValidateOnExit()
public FormItem setValidators(Validator... validators)
Note: these validators will only be run on the client; to do real
client-server validation, validators must be specified via DataSourceField.validators
.
validators
- New validators value. Default value is nullFormItem
instance, for chaining setter callspublic FormItem setValidOperators(OperatorId... validOperators)
Applies only to
form/formItem when allowExpressions
is
true, allowing the user to input expressions.
validOperators
- New validOperators value. Default value is nullFormItem
instance, for chaining setter callsAdvancedFilter overview and related methods
public OperatorId[] getValidOperators()
Applies only to
form/formItem when allowExpressions
is
true, allowing the user to input expressions.
AdvancedFilter overview and related methods
public FormItem setVAlign(VerticalAlignment vAlign)
shouldApplyHeightToTextBox()
is true, for
this to have a visible effect, the cell height must exceed the specified height of the item, either due to an explicit
cellHeight
specification, or due to the row being
expanded by another taller item. Has no effect if DynamicForm.itemLayout
is set to "absolute"
for the form.
vAlign
- New vAlign value. Default value is Canvas.CENTERFormItem
instance, for chaining setter callspublic VerticalAlignment getVAlign()
shouldApplyHeightToTextBox()
is true, for
this to have a visible effect, the cell height must exceed the specified height of the item, either due to an explicit
cellHeight
specification, or due to the row being
expanded by another taller item. Has no effect if DynamicForm.itemLayout
is set to "absolute"
for the form.
titleOrientation
is "top", this method will
return "top", so that items of varying height are top-aligned, beneath their titles. Default value is Canvas.CENTERpublic FormItem setValueDeselectedCSSText(java.lang.String valueDeselectedCSSText)
showDeletions
is enabled.
Note : This is an advanced setting
public java.lang.String getValueDeselectedCSSText()
showDeletions
is enabled.CSSText
public FormItem setValueField(java.lang.String valueField)
displayField
values from an optionDataSource
, this property denotes the the
field to use as the underlying data value in records from the optionDataSource.getValueFieldName()
.valueField
- New valueField value. Default value is nullFormItem
instance, for chaining setter callsDatabinding overview and related methods
public java.lang.String getValueField()
displayField
values from an optionDataSource
, this property denotes the the
field to use as the underlying data value in records from the optionDataSource.getValueFieldName()
.valueField
for this
item. For items with a specified 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 name
of this field. Default value is null
Databinding overview and related methods
public FormItem setValueIconHeight(java.lang.Integer valueIconHeight)
valueIcons
is specified, use this property to
specify a height for the value icon written out.valueIconHeight
- New valueIconHeight value. Default value is nullFormItem
instance, for chaining setter callssetValueIconWidth(java.lang.Integer)
,
setValueIconSize(int)
public java.lang.Integer getValueIconHeight()
valueIcons
is specified, use this property to
specify a height for the value icon written out.getValueIconWidth()
,
getValueIconSize()
public FormItem setValueIconLeftPadding(int valueIconLeftPadding)
NOTE: In RTL mode, the valueIconLeftPadding is applied to the right of the value icon.
valueIconLeftPadding
- New valueIconLeftPadding value. Default value is 0FormItem
instance, for chaining setter callssetValueIcons(java.util.Map)
public int getValueIconLeftPadding()
NOTE: In RTL mode, the valueIconLeftPadding is applied to the right of the value icon.
com.smartgwt.client.widgets.form.fields.FormItem#getValueIcons
public FormItem setValueIconRightPadding(int valueIconRightPadding)
NOTE: In RTL mode, the valueIconRightPadding is applied to the left of the value icon.
valueIconRightPadding
- New valueIconRightPadding value. Default value is 3FormItem
instance, for chaining setter callssetValueIcons(java.util.Map)
public int getValueIconRightPadding()
NOTE: In RTL mode, the valueIconRightPadding is applied to the left of the value icon.
com.smartgwt.client.widgets.form.fields.FormItem#getValueIcons
public FormItem setValueIconSize(int valueIconSize)
valueIcons
is specified, this property may be
used to specify both the width and height of the icon written out. Note that valueIconWidth
and valueIconHeight
take precedence over this value, if
specified.valueIconSize
- New valueIconSize value. Default value is 16FormItem
instance, for chaining setter callssetValueIconWidth(java.lang.Integer)
,
setValueIconHeight(java.lang.Integer)
public int getValueIconSize()
valueIcons
is specified, this property may be
used to specify both the width and height of the icon written out. Note that valueIconWidth
and valueIconHeight
take precedence over this value, if
specified.getValueIconWidth()
,
getValueIconHeight()
public FormItem setValueIconWidth(java.lang.Integer valueIconWidth)
valueIcons
is specified, use this property to
specify a width for the value icon written out.valueIconWidth
- New valueIconWidth value. Default value is nullFormItem
instance, for chaining setter callssetValueIconHeight(java.lang.Integer)
,
setValueIconSize(int)
public java.lang.Integer getValueIconWidth()
valueIcons
is specified, use this property to
specify a width for the value icon written out.getValueIconHeight()
,
getValueIconSize()
public FormItem setVisible(java.lang.Boolean visible)
visible
can only be set on creation. After creation, use
show()
and hide()
to manipulate visibility.
visible
- New visible value. Default value is trueFormItem
instance, for chaining setter callsAppearance overview and related methods
public java.lang.Boolean getVisible()
visible
can only be set on creation. After creation, use
show()
and hide()
to manipulate visibility.
Appearance overview and related methods
public FormItem setVisibleWhen(AdvancedCriteria visibleWhen)
Criteria are evaluated against the
form's current values
as well as the current rule context
. Criteria are re-evaluated every time form values or the
rule context changes, whether by end user action or by programmatic calls.
If both showIf()
and visibleWhen
are specified,
visibleWhen
is ignored.
A basic criteria uses textMatchStyle:"exact". When specified in Component XML
this property allows shorthand formats
for defining criteria.
Note: A FormItem using
visibleWhen must have a name
defined. shouldSaveValue
can be set to false
to
prevent the field from storing its value into the form's values.
visibleWhen
- New visibleWhen value. Default value is nullFormItem
instance, for chaining setter callsAppearance overview and related methods
public AdvancedCriteria getVisibleWhen()
Criteria are evaluated against the
form's current values
as well as the current rule context
. Criteria are re-evaluated every time form values or the
rule context changes, whether by end user action or by programmatic calls.
If both showIf()
and visibleWhen
are specified,
visibleWhen
is ignored.
A basic criteria uses textMatchStyle:"exact". When specified in Component XML
this property allows shorthand formats
for defining criteria.
Note: A FormItem using
visibleWhen must have a name
defined. shouldSaveValue
can be set to false
to
prevent the field from storing its value into the form's values.
Appearance overview and related methods
public FormItem setWidth(int width)
column spanning
item). You may also use "100%" as a synonym for "*", but other percentages are not supported. Note
that for "absolute" item layout rather than the default "table" layout, the rules for specifying the width are slightly
different. All percent sizes are allowed, but not "*". See DynamicForm.itemLayout
for further details.
If width is specified as a String, getWidth() will return -1. Use getWidthAsString.() in this case.
See the FormLayout
overview for details.
width
- New width value. Default value is "*"FormItem
instance, for chaining setter callssetLinearWidth(int)
,
setHeight(int)
,
DynamicForm.setItemLayout(com.smartgwt.client.types.FormLayoutType)
,
FormLayout overview and related methods
,
Spanning Examplepublic int getWidth()
column spanning
item). You may also use "100%" as a synonym for "*", but other percentages are not supported. Note
that for "absolute" item layout rather than the default "table" layout, the rules for specifying the width are slightly
different. All percent sizes are allowed, but not "*". See DynamicForm.itemLayout
for further details.
If width is specified as a String, getWidth() will return -1. Use getWidthAsString.() in this case.
See the FormLayout
overview for details.
Note : This method will return -1 if the underlying SmartClient JavaScript
attribute value cannot be expressed as a(n) int. In that case, other
getters, similarly-named but ending in AsString
, AsCanvas
,
etc., may be provided.
getLinearWidth()
,
getHeight()
,
DynamicForm.getItemLayout()
,
FormLayout overview and related methods
,
Spanning Examplepublic FormItem setWidth(java.lang.String width)
column spanning
item). You may also use "100%" as a synonym for "*", but other percentages are not supported. Note
that for "absolute" item layout rather than the default "table" layout, the rules for specifying the width are slightly
different. All percent sizes are allowed, but not "*". See DynamicForm.itemLayout
for further details.
If width is specified as a String, getWidth() will return -1. Use getWidthAsString.() in this case.
See the FormLayout
overview for details.
width
- New width value. Default value is "*"FormItem
instance, for chaining setter callssetLinearWidth(int)
,
setHeight(int)
,
DynamicForm.setItemLayout(com.smartgwt.client.types.FormLayoutType)
,
FormLayout overview and related methods
,
Spanning Examplepublic java.lang.String getWidthAsString()
column spanning
item). You may also use "100%" as a synonym for "*", but other percentages are not supported. Note
that for "absolute" item layout rather than the default "table" layout, the rules for specifying the width are slightly
different. All percent sizes are allowed, but not "*". See DynamicForm.itemLayout
for further details.
If width is specified as a String, getWidth() will return -1. Use getWidthAsString.() in this case.
See the FormLayout
overview for details.
getLinearWidth()
,
getHeight()
,
DynamicForm.getItemLayout()
,
FormLayout overview and related methods
,
Spanning Examplepublic FormItem setWrapHintText(java.lang.Boolean wrapHintText)
hint
, should the hint text be
allowed to wrap? Setting this property to false
will render the hint on a single line without wrapping,
expanding the width required to render the item if necessary. If unset this property will be picked up from the
DynamicForm.wrapHintText
setting.
This setting
does not apply to hints that are shown in
field
.
wrapHintText
- New wrapHintText value. Default value is nullFormItem
instance, for chaining setter callssetMinHintWidth(java.lang.Integer)
public java.lang.Boolean getWrapHintText()
hint
, should the hint text be
allowed to wrap? Setting this property to false
will render the hint on a single line without wrapping,
expanding the width required to render the item if necessary. If unset this property will be picked up from the
DynamicForm.wrapHintText
setting.
This setting
does not apply to hints that are shown in
field
.
getMinHintWidth()
public FormItem setWrapStaticValue(java.lang.Boolean wrapStaticValue)
read-only
and is using readOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
, should the item value wrap?wrapStaticValue
- New wrapStaticValue value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getWrapStaticValue()
read-only
and is using readOnlyDisplay
ReadOnlyDisplayAppearance.STATIC
, should the item value wrap?public FormItem setWrapTitle(java.lang.Boolean wrapTitle)
wrapItemTitles
at the DynamicForm level.wrapTitle
- New wrapTitle value. Default value is nullFormItem
instance, for chaining setter callspublic java.lang.Boolean getWrapTitle()
wrapItemTitles
at the DynamicForm level.public FormItemIcon addIcon(FormItemIcon icon)
FormItemIcon
to this item. If the optional index parameter is
not passed, the icon is added to the end of the existing icon list
. If the passed icon already exists in the
icon list
, by name
, the original icon is moved to the new index and no
new icon is added.
icon
- the icon to addpublic FormItemIcon addIcon(FormItemIcon icon, int index)
FormItemIcon
to this item. If the optional index parameter is
not passed, the icon is added to the end of the existing icon list
. If the passed icon already exists in the
icon list
, by name
, the original icon is moved to the new index and no
new icon is added.
icon
- the icon to addindex
- the index to add the icon at - if omitted, add the icon to the end of the current icon listpublic void applyFormula()
formula
or textFormula
. Formulas are normally
automatically recomputed and the result automatically applied to the FormItem according to the rules described under
formula
. applyFormula()
exists to cover
any rare cases where these rules are not correct. Calling applyFormula()
has no effect if no formula
or textFormula
is configured for this FormItem.
public com.google.gwt.event.shared.HandlerRegistration addBlurHandler(BlurHandler handler)
Called when this FormItem loses focus.
addBlurHandler
in interface HasBlurHandlers
handler
- the blur handlerHandlerRegistration
used to remove this handlerpublic void blurItem()
Focus overview and related methods
public com.google.gwt.event.shared.HandlerRegistration addChangeHandler(ChangeHandler handler)
Called when a FormItem's value is about to change as the result of user interaction. This method fires after the user performed an action that would change the value of this field, but before the element itself is changed.
Returning
false cancels the change. Note that if what you want to do is transform the user's input, for example,
automatically change separator characters to a standard separator character, you should implement transformInput
rather than using a combination of
change() and setValue() to accomplish the same thing. Returning false from change
is intended for
rejecting input entirely, such as typing invalid characters.
Note that if you ask the form for the current value in this handler, you will get the old value because the change has not yet been committed. The new value is available as a parameter to this method.
Change/Changed notifications vs "...When" rules: the change
and
changed
events only fire when an end user modifies a field value. If you are trying to dynamically control
the visibility or enabled state of other components in response to these events, consider instead using properties
such as Canvas.visibleWhen
, item.readOnlyWhen
, Canvas.enableWhen
on the target component. (Similar properties are
available on FormItem
, Canvas
,
MenuItem
and other components).
addChangeHandler
in interface HasChangeHandlers
handler
- the change handlerHandlerRegistration
used to remove this handlerpublic com.google.gwt.event.shared.HandlerRegistration addChangedHandler(ChangedHandler handler)
Called when a FormItem's value has been changed as the result of user interaction. This method fires after the newly specified value has been stored.
Change/Changed notifications vs "...When" rules: the change
and
changed
events only fire when an end user modifies a field value. If you are trying to dynamically control
the visibility or enabled state of other components in response to these events, consider instead using properties
such as Canvas.visibleWhen
, item.readOnlyWhen
, Canvas.enableWhen
on the target component. (Similar properties are
available on FormItem
, Canvas
,
MenuItem
and other components).
addChangedHandler
in interface HasChangedHandlers
handler
- the changed handlerHandlerRegistration
used to remove this handlerpublic void clearErrors()
public void clearValue()
Note that if a default value is specified, value will be set to that default value, otherwise value will be cleared, (and removed from the containing form's values).
public com.google.gwt.event.shared.HandlerRegistration addClickHandler(ClickHandler handler)
Called when this FormItem is clicked on.
Note: click()
is available on StaticTextItem, BlurbItems,
ButtonItem, and derivatives. Other form items (such as HiddenItem) do not support click()
.
addClickHandler
in interface HasClickHandlers
handler
- the click handlerHandlerRegistration
used to remove this handlerpublic void disable()
getDisabled()
,
Enable overview and related methods
public void disableIcon(java.lang.String icon)
icons
array, if it is currently enabled.icon
- name
of the icon to be disabled.
See Identifier
FormItemIcon.getDisabled()
,
Identifier
,
Enable overview and related methods
public com.google.gwt.event.shared.HandlerRegistration addDoubleClickHandler(DoubleClickHandler handler)
Called when this FormItem is double-clicked.
addDoubleClickHandler
in interface HasDoubleClickHandlers
handler
- the doubleClick handlerHandlerRegistration
used to remove this handlerpublic com.google.gwt.event.shared.HandlerRegistration addEditorEnterHandler(EditorEnterHandler handler)
Notification method fired when the user enters this formItem. Differs from FormItem.focus()
in that while focus
and
blur
may fire multiple as the user navigates sub elements of an item (such as interacting with a pick
list), editorEnter
will typically fire once when the user starts to edit this item as a whole, and once
when the user moves onto a different item or component
addEditorEnterHandler
in interface HasEditorEnterHandlers
handler
- the editorEnter handlerHandlerRegistration
used to remove this handlerpublic com.google.gwt.event.shared.HandlerRegistration addEditorExitHandler(EditorExitHandler handler)
Notification method fired when the user leaves this formItem. Differs from FormItem.blur()
in that while focus
and
blur
may fire multiple as the user navigates sub elements of an item (such as interacting with a pick
list), editorEnter
will typically fire once when the user starts to edit this item as a whole, and
editorExit
fires once when the user moves onto a different item or component
addEditorExitHandler
in interface HasEditorExitHandlers
handler
- the editorExit handlerHandlerRegistration
used to remove this handlerpublic void enable()
getDisabled()
,
Enable overview and related methods
public void enableIcon(java.lang.String icon)
icons
array, if it is currently disabled.icon
- name
of the icon to be enabled.
See Identifier
FormItemIcon.getDisabled()
,
Identifier
,
Enable overview and related methods
public com.google.gwt.event.shared.HandlerRegistration addFocusHandler(FocusHandler handler)
Called when this FormItem receives focus.
addFocusHandler
in interface HasFocusHandlers
handler
- the focus handlerHandlerRegistration
used to remove this handlerpublic void focusAfterItem(boolean forward)
This method makes use of the TabIndexManager.shiftFocusAfterGroup()
method to
request focus be changed to the next registered entry. By default standard focusable Smart GWT UI elements, including
Canvases, FormItems, FormItemIcons, etc are registered with the TabIndexManager in the appropriate order, and will
accept focus if focusable
, and not disabled
or masked
.
Canvases support a similar method: Canvas.focusAfterGroup()
.
NOTE: Focusable elements
created directly in the raw HTML bootstrap or by application code will not be passed focus by this method unless they
have also been explicitly registered with the TabIndexManager. See the TabOrderOverview
for more information.
forward
- direction to shift focus - true to move forward, false to move backwards (as with a shift+tab interaction).Focus overview and related methods
public void focusInItem()
Focus overview and related methods
public java.lang.Integer getCursorPosition()
TextItem.getSelectionRange()
for details of what is
returned if the item does not have the focus (note, it is important to read this documentation, because the behavior
when the item does not have the focus varies by browser)public java.lang.String getCustomState(FormItemElementType elementType, java.lang.String derivedState)
FormItemBaseStyle
for more information on how state-based FormItem
style names are derived. If this method exists on a formItem, the framework will call it, passing in the state
suffix it has derived. Your getCustomState()
implementation can make use of this derived state or ignore
it. For example, if you wanted two different types of focus styling depending on some factor unrelated to focus, you
would probably make use of the incoming "Focused" state and return something like "Focused1" or "Focused2". On the
other hand, if you want your custom state to just override whatever the system derived, you would ignore the incoming
state. Finally, if you do not wish to provide a custom style for this formItem element at this time - for example, you
are only interested in providing a custom "textBox" style and this call is for a "cell" element type - your
getCustomStyle()
method should just return the state it was passed.
This method is an advanced API, and you should only provide an implementation of it if you have specialized styling requirements. If you do implement it, note that it will be called very frequently, from rendering code: if your custom logic does significant processing, it could introduce a system-wide performance problem.
elementType
- The element type to return a custom state forderivedState
- The state suffix the system derivedFormItemBaseStyle
public java.lang.String getDisplayFieldName()
displayField
for this item. Behavior varies based on the configuration of this item, as follows:
optionDataSource
and an explicit 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.valueField
for this item is hidden in the optionDataSource
, this method will return the title field for the optionDataSource
.FieldName
public java.lang.String getFieldName()
Drawing overview and related methods
public java.lang.String getFullDataPath()
name
that specifies no dataPath, on a form that specifies a dataPath of /order/items
, this
method will return /order/items/name
DataPath
public java.lang.Integer getGridColNum()
ListGrid
's inline edit form
, returns the number of the grid column this
formItem is responsible for editing, but only if a row is currently being edited. If the formItem is not part of
a ListGrid inline edit for any reason, this method returns null. Reasons for a formItem not being part of an inline
edit includepublic java.lang.Integer getGridRowNum()
ListGrid
's inline edit form
, returns the number of the row currently being
edited. If the formItem is not part of a ListGrid inline edit for any reason, this method returns null. Reasons for a
formItem not being part of an inline edit includepublic FormItemIcon getIcon(java.lang.String name)
FormItemIcon.name
, returns the
FormItemIcon
object.name
- specified FormItemIcon.name
.
See Identifier
null
if there is no such icon.Identifier
public java.lang.Integer getIconTabPosition()
Default implementation returns the index of the icon in the icons array, (plus one if a pickerIcon is showing) meaning users can tab through icons in order. Has no effect for non-focusable icons.
public ListGrid getListGrid()
isInGrid()
), this method returns the grid in question.public int getPageLeft()
Positioning overview and related methods
public int getPageTop()
Positioning overview and related methods
public java.lang.Integer getPickerIconTabPosition()
Default implementation returns zero, making the picker the first focusable element after the items text box.
public int getPixelHeight()
height
of this formItem in
pixels. For heights specified as a percentage value or "*"
, the pixel height may not be available prior
to the item being drawn. In cases where the height has not yet been resolved to a pixel value, this method will return
-1
.public int getPixelWidth()
width
of this formItem in
pixels. For widths specified as a percentage value or "*"
, the pixel width may not be available prior to
the item being drawn. In cases where the width has not yet been resolved to a pixel value, this method will return
-1
.public ListGridRecord getSelectedRecord()
optionDataSource
when fetchMissingValues
is true, and the missing value is fetched. fetchMissingValues
kicks off the fetch when the
form item is initialized with a non null value or when setValue() is called on the item. Note that this method will
return null before the fetch completes, or if no record is found in the optionDataSource matching the underlying value.
public java.lang.Float getValueAsFloat()
getValue()
public java.lang.Integer getValueAsInteger()
getValue()
public java.lang.String getValueFieldName()
valueField
for this
item. For items with a specified 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 name
of this field.
optionDataSource
public int getVisibleTitleWidth(java.lang.Boolean labelOnly)
labelOnly
- If true, returns the visible width of the title text only; if false (the default)
returns the width of the title cellSizing overview and related methods
public java.lang.Boolean hasAdvancedCriteria()
AdvancedCriteria
sub criterion object? If this method
returns true, DynamicForm.getValuesAsCriteria()
on the form containing this item will always return an AdvancedCriteria
object, calling
FormItemCriterionGetter.getCriterion()
on each item to retrieve the individual criteria. Default
implementation will return true
if operator
is explicitly specified.
CriteriaEditing overview and related methods
public boolean hasErrors()
ErrorHandling overview and related methods
public void hide()
public void hideIcon(java.lang.String icon)
icons
array, if it is currently visible. Note that once this method has been called, any previously specified FormItemIcon.showIf()
will be discarded.icon
- name
of the icon to be hidden.
See Identifier
Identifier
public com.google.gwt.event.shared.HandlerRegistration addIconClickHandler(IconClickHandler handler)
Notification method called when the user clicks on a form item icon.
The icon's FormItemIcon.formItemClick()
method if any
is called first. Then, if the clicked icon is the picker icon
, the FormItem.pickerIconClick()
method is
called. Then, this method is called.
This event may be cancelled to suppress the FormItem.click()
handler from also firing in response
to the user interaction.
addIconClickHandler
in interface HasIconClickHandlers
handler
- the iconClick handlerHandlerRegistration
used to remove this handlerpublic com.google.gwt.event.shared.HandlerRegistration addIconKeyPressHandler(IconKeyPressHandler handler)
StringMethod. Default action to fire when an icon has keyboard focus and the user types a key. May be
overridden by setting keyPress
on the form item icon directly.
addIconKeyPressHandler
in interface HasIconKeyPressHandlers
handler
- the iconKeyPress handlerHandlerRegistration
used to remove this handlerpublic void invalidateDisplayValueCache()
displayField
, the
value displayed to the user for this item may be derived from another field. The display field can be either another
field value in the same record or a field that must be retrieved from a related optionDataSource
if fetchMissingValues
is true. In this latter case,
we perform a fetch against the option dataSource when the item value changes in order to determine the display value to
show (and we make the associated record available via getSelectedRecord()
).
We cache this data on the form item, so if the item value changes to a new value, then reverts to a previously-seen value, the display value and selected record are already available without the need for an additional fetch. The cached values will also be kept in synch with the dataSource data assuming it is modified via standard add, update or delete operations.
This method explicitly invalidates this cache of optionDataSource data, and if the item value is non null and fetchMissingValues is still true, re-fetches the data.
public boolean isCutEvent()
FormItem.change()
, FormItem.changed()
and FormItem.transformInput()
. See supportsCutPasteEvents
.public java.lang.Boolean isDrawn()
Drawing overview and related methods
public java.lang.Boolean isFocused()
synchronousFocusNotifications
).
In this case, this method can correctly
return false when, intuitively, you would expect it to return true:
someItem.focusInItem(); if (someItem.isFocused()) { // In most browsers we would get here, but not in Internet Explorer with // EventHandler.synchronousFocusNotifications disabled }
public java.lang.Boolean isInGrid()
containerWidget
is a GridRenderer
or GridRenderer subclasspublic boolean isPasteEvent()
FormItem.change()
, FormItem.changed()
and FormItem.transformInput()
. See supportsCutPasteEvents
.public java.lang.Boolean isVisible()
Canvas API
, it indicates visibility settings only and so will return true
for an item that is not drawn.Visibility overview and related methods
public com.google.gwt.event.shared.HandlerRegistration addItemHoverHandler(ItemHoverHandler handler)
Optional stringMethod to fire when the user hovers over this item. Call com.smartgwt.client.widgets.form.fields.events.ItemHoverEvent#cancel()
from within ItemHoverHandler.onItemHover(com.smartgwt.client.widgets.form.fields.events.ItemHoverEvent)
to suppress default behavior of showing a
hover canvas containing the HTML returned by formItem.itemHoverHTML()
/ form.itemHoverHTML()
.
addItemHoverHandler
in interface HasItemHoverHandlers
handler
- the itemHover handlerHandlerRegistration
used to remove this handlerpublic com.google.gwt.event.shared.HandlerRegistration addKeyDownHandler(KeyDownHandler handler)
StringMethod fired in response to a keydown while focused in this form item.
addKeyDownHandler
in interface HasKeyDownHandlers
handler
- the keyDown handlerHandlerRegistration
used to remove this handlerpublic com.google.gwt.event.shared.HandlerRegistration addKeyPressHandler(KeyPressHandler handler)
StringMethod fired when the user presses a key while focused in this form item.
addKeyPressHandler
in interface HasKeyPressHandlers
handler
- the keyPress handlerHandlerRegistration
used to remove this handlerpublic com.google.gwt.event.shared.HandlerRegistration addKeyUpHandler(KeyUpHandler handler)
StringMethod fired in response to a keyup while focused in this form item.
addKeyUpHandler
in interface HasKeyUpHandlers
handler
- the keyUp handlerHandlerRegistration
used to remove this handlerpublic com.google.gwt.event.shared.HandlerRegistration addPendingStatusChangedHandler(PendingStatusChangedHandler handler)
Notification method called when showPending
is
enabled and this form item should either clear or show its "Pending" visual state.
The default behavior is that the
titleStyle
and cellStyle
are updated to include/exclude the "Pending"
suffix. Standard form item types may implement additional default behavior (see any item-specific pendingStatusChanged()
documentation). Returning false
will cancel the default behavior.
The pendingStatusChanged()
notification method is typically used by CanvasItem
-derived form items,
where a custom or supplemental pending visual state is desired.
addPendingStatusChangedHandler
in interface HasPendingStatusChangedHandlers
handler
- the pendingStatusChanged handlerHandlerRegistration
used to remove this handlerpublic com.google.gwt.event.shared.HandlerRegistration addPickerIconClickHandler(PickerIconClickHandler handler)
Notification method called when the picker
icon
is clicked. This method will fire after the FormItemIcon.formItemClick()
handler for
the pickerIcon
. If the event is not
cancelled, the standard FormItem.iconClick()
will also fire.
The default implementation will call FormItem.showPicker()
.
addPickerIconClickHandler
in interface HasPickerIconClickHandlers
handler
- the pickerIconClick handlerHandlerRegistration
used to remove this handlerpublic void redraw()
Depending on the item and the containerWidget
it's embedded in, this may redraw
this particular item or require a redraw of all items in the form.
Do not call this method unless the documentation
directs you to do so. Calling redraw()
unnecessarily has significant performance consequences.
public void redraw(java.lang.String reason)
Depending on the item and the containerWidget
it's embedded in, this may redraw
this particular item or require a redraw of all items in the form.
Do not call this method unless the documentation
directs you to do so. Calling redraw()
unnecessarily has significant performance consequences.
reason
- optional reason for performing the redraw, which may appear in diagnostic logs if enabledpublic boolean removeIcon(java.lang.String icon)
name
, remove it from this item.icon
- the name of the icon to remove.
See Identifier
Identifier
public void selectedRecordChanged(ListGridRecord record)
data bound
items
with fetchMissingValues
enabled
when the selected record
is updated as a
result of the value changing or a fetch for a new record completing.fetchMissingValues
and alwaysFetchMissingValues
. Developers
should also be aware that if PickList.fetchDisplayedFieldsOnly is set (or some custom fetch operation
has been specified), the data
returned from the server may include only a subset of dataSource fields rather than complete records.record
- new selected record. May be null if the item has been set to a value with no associated record.public void setIconDisabled(java.lang.String icon, boolean disabled)
icon
- name
of the icon to be disabled/enabled.
See Identifier
disabled
- true if icon should be disabledFormItemIcon.getDisabled()
,
Enable overview and related methods
public void setIconShowOnFocus(java.lang.String icon, java.lang.Boolean showOnFocus)
FormItemIcon.showOnFocus
for the
supplied icon, and causes that icon's visibility to be updated and the item redrawn as appropriate.icon
- name
of the icon to update.
See Identifier
showOnFocus
- new value of FormItemIcon.showOnFocus
public boolean shouldApplyHeightToTextBox()
height
is specified, should it be applied to the
item's text box element? If this method returns false, the text box will not have an explicit height applied, though the
containing cell will be sized to accommodate any specified height. This is used in cases where the text box does not
have distinctive styling (for example in standard StaticTextItem
s). As
the textBox has no explicit height, it fits the content. Since the text box is not visually distinct to the user, this
makes vAlign
behave as expected with the text value
of the item being vertically aligned within the cell.
Default implementation will return applyHeightToTextBox
if explicitly set
otherwise false
if readOnlyDisplay
is set to "static"
and the item is not editable
, otherwise true.
public java.lang.Boolean shouldFetchMissingValue(java.lang.Object newValue)
optionDataSource
, should we perform a fetch against that dataSource to find the record that matches this field's value?
If the value is non-null, this method is called when the item is first rendered or whenever the value is changed
via a call to setValue()
. If it returns true, a fetch
will be dispatched against the optionDataSource to get the record matching the value
When the fetch completes, if a
record was found that matches the data value (and the form item value has not subsequently changed again), the item
will be re-rendered to reflect any changes to the display value, and the record matching the value will be available via
this.getSelectedRecord()
.
Default
behavior will return false if this.fetchMissingValues
is set to false. Otherwise it will return true if this.alwaysFetchMissingValues
is set to
true, or if a displayField
is specified for
this item and the item value is not already present in the item's valueMap.
newValue
- The new data value of the item.public java.lang.Boolean shouldSaveOnEnter()
saveOnEnter
or false if that property is unset.public boolean shouldStopKeyPressBubbling(java.lang.String keyName, int characterValue)
This method is called after standard item keypress handlers when the user presses a key while focused in this item. Returning true will suppress bubbling of the event to the containing form. This is useful to avoid having the form react to key events which "have meaning" to the focused item.
Default implementation varies by item type. In short character keys are suppressed for all editable fields, as are keys which will modify the current state of the field ("Arrow" keys for moving around free form text editors, etc).
Note that when this method returns true,
no keyPress
event will fire on the form for the key
pressed. However developers will still receive the separate DynamicForm.itemKeyPress()
event.
keyName
- name of the key pressed.
See KeyName
characterValue
- If this was a character key, this is the numeric value for the characterpublic void show()
This will cause the form to redraw. If this item had an item.showIf expression, it will be destroyed.
public com.google.gwt.event.shared.HandlerRegistration addShowContextMenuHandler(ShowContextMenuHandler handler)
Called when the mouse is right-clicked anywhere in this formItem. If the implementation returns false, default browser behavior is cancelled.
Note that it can be bad practice to cancel this method if the mouse is over the data
element for the item, because doing so would replace the builtin browser-default menus that users may expect. You can
use DynamicForm.getEventItemInfo()
to return an
info object that can be used to determine which part of the item is under the mouse.
addShowContextMenuHandler
in interface HasShowContextMenuHandlers
handler
- the showContextMenu handlerHandlerRegistration
used to remove this handlerpublic void showIcon(java.lang.String icon)
icons
array, if it is not already visible. Note that once this method has been called, any previously specified FormItemIcon.showIf()
will be discarded. Note that if the form item's showIcons property is set to false, no icons will be displayed for the item. In this case this method will not cause the icon to be displayed.
icon
- name
of the icon to be shown.
See Identifier
Identifier
public void showPicker()
pickerIcon
. May also be called programmatically.
Default implementation lazily creates and shows the Picker Autochild
.
Developers wishing to show a custom
picker widget can either implement a FormItem.pickerIconClick()
handler with an entirely custom implementation (and bypass the call to
showPicker()
altogether), or use the AutoChild pattern
to
customize the automatically generated picker
autoChild
.
public void stopHover()
public void storeValue(java.lang.Object value)
This method will fire standard FormItem.change()
and DynamicForm.itemChanged()
handlers, and store the
value passed in such that subsequent calls to getValue()
or DynamicForm.getValue()
will return the new
value for this item.
This method is intended to provide a way for custom formItems - most commonly canvasItems
- to provide a new interface to the user, allowing them
to manipulate the item's value, for example in an embedded CanvasItem.canvas
, or a pop-up dialog launched from an
icon
, etc. Developers should call this method when the
user interacts with this custom interface in order to store the changed value.
shouldSaveValue
for CanvasItems is false by
default. Custom CanvasItems will need to override shouldSaveValue to true if the values stored via this API should be
included in the form's getValues()
and saved with the
form when saveData()
is called.
If you cannot easily
detect interactions that should change the value as the user performs them, a workaround is to call
storeValue
right before the form saves.
Note that this method is not designed for customizing a value
which is already being saved by a standard user interaction. For example you should not call this method from a change handler
. Other APIs such as FormItem.transformInput()
exist for this.
value
- value to save for this itempublic void storeValue(java.lang.Object value, java.lang.Boolean showValue)
This method will fire standard FormItem.change()
and DynamicForm.itemChanged()
handlers, and store the
value passed in such that subsequent calls to getValue()
or DynamicForm.getValue()
will return the new
value for this item.
This method is intended to provide a way for custom formItems - most commonly canvasItems
- to provide a new interface to the user, allowing them
to manipulate the item's value, for example in an embedded CanvasItem.canvas
, or a pop-up dialog launched from an
icon
, etc. Developers should call this method when the
user interacts with this custom interface in order to store the changed value.
shouldSaveValue
for CanvasItems is false by
default. Custom CanvasItems will need to override shouldSaveValue to true if the values stored via this API should be
included in the form's getValues()
and saved with the
form when saveData()
is called.
If you cannot easily
detect interactions that should change the value as the user performs them, a workaround is to call
storeValue
right before the form saves.
Note that this method is not designed for customizing a value
which is already being saved by a standard user interaction. For example you should not call this method from a change handler
. Other APIs such as FormItem.transformInput()
exist for this.
value
- value to save for this itemshowValue
- Should the formItem be updated to display the new value?public com.google.gwt.event.shared.HandlerRegistration addTitleClickHandler(TitleClickHandler handler)
Notification method fired when the user clicks the title for this item
addTitleClickHandler
in interface HasTitleClickHandlers
handler
- the titleClick handlerHandlerRegistration
used to remove this handlerpublic com.google.gwt.event.shared.HandlerRegistration addTitleDoubleClickHandler(TitleDoubleClickHandler handler)
Notification method fired when the user double-clicks the title for this item
addTitleDoubleClickHandler
in interface HasTitleDoubleClickHandlers
handler
- the titleDoubleClick handlerHandlerRegistration
used to remove this handlerpublic com.google.gwt.event.shared.HandlerRegistration addTitleHoverHandler(TitleHoverHandler handler)
Optional stringMethod to fire when the user hovers over this item's title. Call com.smartgwt.client.widgets.form.fields.events.TitleHoverEvent#cancel()
from within TitleHoverHandler.onTitleHover(com.smartgwt.client.widgets.form.fields.events.TitleHoverEvent)
to suppress default behavior of showing a
hover canvas containing the HTML returned by formItem.titleHoverHTML()
/
form.titleHoverHTML()
.
addTitleHoverHandler
in interface HasTitleHoverHandlers
handler
- the titleHover handlerHandlerRegistration
used to remove this handlerpublic void updateState()
textBoxStyle
). Calls to updateState()
normally occur automatically as a consequence of focus changes, items becoming disabled, etc. This method is advanced
and intended only for use in workarounds.
public java.lang.Boolean validate()
public boolean valueClipped()
The form item must have value clipping enabled. If a form item type supports the clipValue
attribute, then clipValue must be true. TextItem
s and derivatives (e.g.
SpinnerItem
) automatically clip their values.
public com.google.gwt.event.shared.HandlerRegistration addValueHoverHandler(ValueHoverHandler handler)
Optional stringMethod to fire when the user hovers over this item's value. Call com.smartgwt.client.widgets.form.fields.events.ValueHoverEvent#cancel()
from within ValueHoverHandler.onValueHover(com.smartgwt.client.widgets.form.fields.events.ValueHoverEvent)
to suppress default behavior of showing a
hover canvas containing the HTML returned by FormItem.valueHoverHTML()
/ DynamicForm.valueHoverHTML()
.
addValueHoverHandler
in interface HasValueHoverHandlers
handler
- the valueHover handlerHandlerRegistration
used to remove this handlerpublic com.google.gwt.event.shared.HandlerRegistration addValueIconClickHandler(ValueIconClickHandler handler)
Notification method fires when the user clicks a value icon
for this item.
addValueIconClickHandler
in interface HasValueIconClickHandlers
handler
- the valueIconClick handlerHandlerRegistration
used to remove this handlerpublic static FormItemIcon getPickerIcon(PickerIconName pickerName)
FormItemIcon
for a standard picker with skin-specific
settings.pickerName
- Name of picker iconpublic static FormItemIcon getPickerIcon(PickerIconName pickerName, FormItemIcon properties)
FormItemIcon
for a standard picker with skin-specific
settings.pickerName
- Name of picker iconproperties
- Properties to apply to new picker iconpublic static void setDefaultProperties(FormItem formItemProperties)
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.
formItemProperties
- properties that should be used as new defaults when instances of this class are createdSGWTProperties
public java.lang.String getScClassName()
public void setScClassName(java.lang.String scClassName)
scClassName
- the SmartClient classpublic static <T extends RefDataClass> T asSGWTComponent(com.google.gwt.core.client.JavaScriptObject jsObj)
JavaScriptObject
. If
the supplied object is not a SmartClient FormItem, a warning will be logged and null
returned; otherwise the FormItem will be returned as the appropriate subtype of SGWT
FormItem.jsObj
- SmartClient FormItem whose wrapper is wantedpublic java.lang.String getClassName()
public void setInitHandler(FormItemInitHandler initHandler)
initHandler
- public FormItem setAttribute(java.lang.String attribute, java.lang.String value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, java.util.Map value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, BaseClass[] value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, DataClass[] value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, java.util.Date value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, ValueEnum[] value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, DataClass value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, BaseClass value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, com.google.gwt.core.client.JavaScriptObject value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, java.lang.String[] value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, boolean value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, java.lang.Boolean value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, int value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, java.lang.Integer value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, long value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, java.lang.Float value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, double value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, java.lang.Double value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, int[] value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, java.lang.Integer[] value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic FormItem setAttribute(java.lang.String attribute, double[] value)
DataClass
setAttribute
in class DataClass
DataClass
instance, for chaining
setter callspublic java.lang.String getAttribute(java.lang.String attribute)
DataClass
getAttribute
in class DataClass
public java.lang.String getAttributeAsString(java.lang.String property)
DataClass
getAttributeAsString
in class DataClass
public java.util.Date getAttributeAsDate(java.lang.String property)
DataClass
getAttributeAsDate
in class DataClass
public java.lang.Double getAttributeAsDouble(java.lang.String property)
DataClass
getAttributeAsDouble
in class DataClass
public com.google.gwt.core.client.JavaScriptObject getAttributeAsJavaScriptObject(java.lang.String property)
DataClass
getAttributeAsJavaScriptObject
in class DataClass
public java.lang.Integer getAttributeAsInt(java.lang.String property)
DataClass
getAttributeAsInt
in class DataClass
public java.lang.Float getAttributeAsFloat(java.lang.String property)
DataClass
getAttributeAsFloat
in class DataClass
public java.lang.Boolean getAttributeAsBoolean(java.lang.String property)
DataClass
getAttributeAsBoolean
will return Boolean false
if the attribute value is null
or not a Boolean. Use the two parameter
variant of this API DataClass.getAttributeAsBoolean(String, boolean)
if you want
null
returned for null
attribute values.getAttributeAsBoolean
in class DataClass
property
- the property namepublic java.lang.Boolean getAttributeAsBoolean(java.lang.String property, boolean allowNull)
DataClass
null
or not a Boolean, the return value depends upon allowNull
. If
allowNull
is true, null
will be returned; otherwise Boolean
false
will be returned. For a simpler approach that never returns
null
, use the one parameter variant of this API
DataClass.getAttributeAsBoolean(String)
.getAttributeAsBoolean
in class DataClass
property
- the property nameallowNull
- whether to allow nullpublic java.lang.Object getAttributeAsObject(java.lang.String property, com.google.gwt.core.client.JavaScriptObject convertToObject)
public void setNullProperty(java.lang.String property)
public void setProperty(java.lang.String property, java.lang.String value)
public void setProperty(java.lang.String property, boolean value)
public void setProperty(java.lang.String property, int value)
public void setProperty(java.lang.String property, double value)
public void setProperty(java.lang.String property, com.google.gwt.core.client.JavaScriptObject value)
public final void setJavaScriptObject(com.google.gwt.core.client.JavaScriptObject jsObj)
setJavaScriptObject
in class JsObject
protected final void error(java.lang.String attribute, java.lang.String value) throws java.lang.IllegalStateException
java.lang.IllegalStateException
protected final void errorIfNotCreated(java.lang.String property) throws java.lang.IllegalStateException
java.lang.IllegalStateException
protected final void error(java.lang.String message) throws java.lang.IllegalStateException
java.lang.IllegalStateException
public void setAutoChildConstructor(java.lang.String autoChildName, java.lang.String className)
autoChildName
.autoChildName
- the name of the AutoChildclassName
- the SmartClient class name to use when constructing the AutoChild.AutoChildUsage
public void setAutoChildProperties(java.lang.String autoChildName, Canvas properties) throws java.lang.IllegalStateException
Canvas
AutoChild named autoChildName
.
properties
must not have already been created
(properties.isCreated()
must be false
).
NOTE: Overrides at override points are not applied to AutoChildren created from
properties
; that is, if the Java Class
of properties
overrides a Smart GWT override point, the custom method implementation will not be called.
java.lang.IllegalStateException
- if properties
has been created.AutoChildUsage
public void setAutoChildProperties(java.lang.String autoChildName, FormItem properties) throws java.lang.IllegalStateException
FormItem
AutoChild named autoChildName
.
properties
must not have already been created
(properties.isCreated()
must be false
).
NOTE: Overrides at override points are not applied to AutoChildren created from
properties
; that is, if the Java Class
of properties
overrides a Smart GWT override point, the custom method implementation will not be called.
java.lang.IllegalStateException
- if properties
has been created.AutoChildUsage
public void setAutoChildProperties(java.lang.String autoChildName, EditProxy properties) throws java.lang.IllegalStateException
autoChildName
.
properties
must not have already been created
(properties.isCreated()
must be false
).
java.lang.IllegalStateException
- if properties
has been created.AutoChildUsage
public void setAutoChildVisibility(java.lang.String autoChildName, boolean visible)
autoChildName
.
NOTE: This API is not valid for all AutoChildren because some AutoChildren cannot be hidden without destroying the main functions of the component.
autoChildName
- name of an AutoChildvisible
- whether to show the AutoChildpublic final Canvas getCanvasAutoChild(java.lang.String autoChildName)
Canvas
AutoChild named autoChildName
if already created.autoChildName
- name of an AutoChild to return.java.lang.RuntimeException
- if the AutoChild is not a SmartClient Canvas
object.public final FormItem getFormItemAutoChild(java.lang.String autoChildName)
FormItem
AutoChild named autoChildName
if already created.autoChildName
- name of an AutoChild to return.java.lang.RuntimeException
- if the AutoChild is not a SmartClient FormItem
object.public void setName(java.lang.String name)
FieldName
for details and how to check for validity. The FormItem's name determines the name of the property it edits within the form.
Note that an item must have a valid name or dataPath
in order for its value to be validated and/or
saved.
name
- New name value. Default value is nullFieldName
,
Basics overview and related methods
public void setErrorOrientation(FormErrorOrientation errorOrientation)
showInlineErrors
is true, where
should the error icon and text appear relative to the form item itself. Valid options are "top"
,
"bottom"
, "left"
or "right"
.errorOrientation
.errorOrientation
- errorOrientation Default value is nullpublic void setType(java.lang.String type)
type
- type Default value is "text"public FormItem setColSpan(java.lang.String colSpan)
The colSpan
setting does not include the title shown
for items with showTitle
:true, so the
effective colSpan
is one higher than this setting for items that are showing a title and whose
TitleOrientation
is either "left" or "right".
colSpan
- colSpan Default value is 1FormItem
instance, for
chaining setter callspublic FormItem setColSpan(int colSpan)
The colSpan
setting does not include the title shown
for items with showTitle
set to true, so the
effective colSpan
is one higher than this setting for items that are showing a title and whose
TitleOrientation
is either "left" or "right".
colSpan
- colSpan Default value is 1FormItem
instance, for
chaining setter callspublic java.lang.String getType()
public FormItem setDefaultValue(java.lang.String defaultValue)
null
programmatically, it will be reverted to the defaultValue
. Developers
should use the values
object if their intention
is to provide an initial value for a field in a form rather than a value to use in place of null
.defaultValue
- defaultValue Default value is nullFormItem
instance, for
chaining setter callspublic void setDefaultValue(java.lang.Integer defaultValue)
null
programmatically, it will be reverted to the defaultValue
. Developers
should use the values
object if their intention
is to provide an initial value for a field in a form rather than a value to use in place of null
.defaultValue
- defaultValue Default value is nullpublic void setDefaultValue(java.util.Date defaultValue)
null
programmatically, it will be reverted to the defaultValue
. Developers
should use the values
object if their intention
is to provide an initial value for a field in a form rather than a value to use in place of null
.defaultValue
- defaultValue Default value is nullpublic FormItem setDefaultValue(java.lang.Boolean defaultValue)
null
programmatically, it will be reverted to the defaultValue
. Developers
should use the values
object if their intention
is to provide an initial value for a field in a form rather than a value to use in place of null
.defaultValue
- defaultValue Default value is nullFormItem
instance, for
chaining setter callspublic void setDefaultValue(java.lang.Float defaultValue)
null
programmatically, it will be reverted to the defaultValue
. Developers
should use the values
object if their intention
is to provide an initial value for a field in a form rather than a value to use in place of null
.defaultValue
- defaultValue Default value is nullpublic void setDefaultValue(java.lang.Double defaultValue)
null
programmatically, it will be reverted to the defaultValue
. Developers
should use the values
object if their intention
is to provide an initial value for a field in a form rather than a value to use in place of null
.defaultValue
- defaultValue Default value is nullpublic void setDefaultValue(java.lang.Object value)
public void setValueMap(java.lang.String... valueMap)
valueMap
- the value mapgetValueMapAsArray()
public void setValueMap(java.util.Map valueMap)
valueMap
- the value mapgetValueMap()
public void setValueIcons(java.util.Map valueIcons)
valueIcons
- mapping of logical values for this item to icon src URLspublic void setEditorProperties(FormItem editorProperties)
The type of FormItem to use for editing is normally derived automatically from
type
, which is the
data type of the field, by the rules explained
here
.
Note: When you supply a custom FormItem via setEditorProperties(), you're really providing properties which are then used to create
multiple FormItems (eg, in grids, forms and trees) and there's an underlying limitation here where event handlers have to be written to
dynamically receive the actual FormItem rather than relying on "this" (because there's more than one "this").
This means you need to follow the special rules indicated for
DataSourceField.setEditorProperties(FormItem)
.
As an alternative, you can use setEditorType(String)
or
setEditorType(Class)
to avoid these limitations, if you register
the FormItem subclass with the reflection mechanism
.
editorProperties
- FormItem with the properties you want to set as defaults.public void setEditorType(FormItem editorType)
setEditorProperties(FormItem)
. You can also consider using
setEditorType(Class)
or setEditorType(String)
instead.setEditorProperties(FormItem)
.editorType
- FormItem with the properties you want to set as defaultspublic void setEditorType(java.lang.String editorType)
The type of FormItem
to use for editing is normally derived automatically from the
type
,
which is the data type of the field, by the rules explained
here
.
Note: The editorType must be registered for use with the
reflection mechanism
.
By doing so, you avoid the limitations of setEditorProperties(FormItem)
.
editorType
- the fully-qualified class name of a FormItem
subclass.java.lang.IllegalArgumentException
- if the editorType class has not been registered for use with the
reflection mechanism
,
or if it does not inherit from
FormItem
.public void setEditorType(java.lang.Class<? extends FormItem> editorType)
The type of FormItem
to use for editing is normally derived automatically from the
type
,
which is the data type of the field, by the rules explained
here
.
Note: The editorType must be registered for use with the
reflection mechanism
.
By doing so, you avoid the limitations of setEditorProperties(FormItem)
.
editorType
- a FormItem
subclass.java.lang.IllegalArgumentException
- if the editorType class has not been registered for use with the
reflection mechanism
,
or if it does not inherit from
FormItem
.public void setValue(int value)
value
- the form item valuepublic void setValue(double value)
value
- the form item valuepublic void setValue(java.util.Date value)
value
- the form item valuepublic void setValue(java.lang.String value)
value
- the form item valuepublic void setValue(boolean value)
value
- the form item valuepublic void setValue(java.lang.Object value)
FormItemValueParser
and FormItemValueFormatter
API's for custom value parsing and formatting.value
- the form item valuepublic java.lang.String getDisplayValue()
public java.lang.String getDisplayValue(java.lang.String value)
public int getVisibleHeight()
public int getVisibleWidth()
public Rectangle getPageRect()
public Rectangle getRect()
public Rectangle getIconRect(FormItemIcon icon)
public Rectangle getIconPageRect(FormItemIcon icon)
public com.google.gwt.core.client.JavaScriptObject getConfig()
public com.google.gwt.core.client.JavaScriptObject getEditorTypeConfig()
public void setTooltip(java.lang.String tooltip)
setPrompt(java.lang.String)
.tooltip
- tooltip Default value is nullpublic java.lang.String getTooltip()
getPrompt()
public void setOptionFilterContext(RPCRequest rpcRequestProperties)
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
rpcRequestProperties
- optionFilterContext Default value is nullpublic RPCRequest getOptionFilterContext()
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
mappingpublic void setOptionCriteria(Criteria optionCriteria)
optionDataSource
, and this property may be used
to specify criteria to pass to the datasource when
performing the fetch operation on the dataSource to obtain a data-value to display-value
mapping
Note : This is an advanced setting
optionCriteria
- optionCriteria Default value is nullpublic Criteria getOptionCriteria()
optionDataSource
, and this property may be used
to specify criteria to pass to the datasource when
performing the fetch operation on the dataSource to obtain a data-value to display-value
mappingpublic void setShowIfCondition(FormItemIfFunction showIf)
showIf
- the showIf handlerFormItem#setRedrawOnChange(boolean)
public void setErrorFormatter(FormItemErrorFormatter errorFormatter)
errorFormatter
- the error formatter.public void setInputTransformer(FormItemInputTransformer inputTransformer)
change
event.inputTransformer
- the input transformerpublic void setItemHoverFormatter(FormItemHoverFormatter hoverFormatter)
hoverFormatter
- the hover formatterpublic void setItemTitleHoverFormatter(FormItemHoverFormatter hoverFormatter)
FormItemHoverFormatter
should return the HTML to display in a hover canvas
when the user holds the mouse pointer over this item's title and the title is clipped. Return
null to suppress the hover canvas altogether.hoverFormatter
- the hover formatterDynamicForm.titleClipped(com.smartgwt.client.widgets.form.fields.FormItem)
public void setTitleHoverFormatter(FormItemHoverFormatter hoverFormatter)
setItemTitleHoverFormatter(FormItemHoverFormatter)
.hoverFormatter
- the hover formatterpublic void setItemValueHoverFormatter(FormItemHoverFormatter hoverFormatter)
FormItemHoverFormatter
should return the HTML to display in a hover canvas
when the user holds the mouse pointer over this item's value and the value is clipped. Return
null to suppress the hover canvas altogether.hoverFormatter
- the hover formattervalueClipped()
public void setValueHoverFormatter(FormItemHoverFormatter hoverFormatter)
setItemValueHoverFormatter(FormItemHoverFormatter)
.hoverFormatter
- the hover formatterpublic DynamicForm getForm()
Note that you must treat this as a read-only reference to the from
public java.lang.Object getValue()
List
or RecordList
instance
is returned.
Note that for FormItems that have a ValueMap or where a formatter
has been defined, getValue()
returns the underlying value of the FormItem, not the displayed value.
public java.lang.Object _getValue()
public java.lang.Long getValueAsLong()
This method may be
preferred over
getValueAsInteger()
as an underlying JavaScript number has an integral range that is more that Java Integer
but less than Java Long (see background).
If you're actually using Long values where
you might need the entire range, see
DataSourceField.stringInBrowser
for suggested approaches.
getValue()
,
getValueAsInteger()
public RecordList getValueAsRecordList()
public void setValueFormatter(FormItemValueFormatter formatter)
FormItemValueFormatter
, if provided, is evaluated to get the
display value to show for this form items underlying data value. If you are considering using this method,
you should first consider using FormItem.setFormat
,
which provides for simple and flexible declarative
formatting of dates, times and numbers, without the need to write formatting code.
This provides a way to perform a more complex data
to display value manipulation than a simple valueMap
. Note that by default this formatter will only be applied to static displays such
as StaticTextItem
or SelectItem
,
and does not apply to values displayed in a freely editable text entry field (such as a
TextItem
or TextAreaItem
), unless
TextItem.setFormatOnBlur(java.lang.Boolean)
is set to true
,
which causes this formatter to be applied while the item does not have focus, and then be cleared when the user moves focus to
the text field.
See also setEditorValueFormatter(com.smartgwt.client.widgets.form.FormItemValueFormatter)
and
setEditorValueParser(com.smartgwt.client.widgets.form.FormItemValueParser)
.
formatter
- the FormItemValueFormatterpublic void setEditorValueFormatter(FormItemValueFormatter formatter)
FormItemValueFormatter
to map this item's current data value to a
display value. Note that this only applies to items which show a free-form entry area, such as a TextItem
or TextAreaItem
. For
display values which will not be directly manipulated by the user, use setValueFormatter(com.smartgwt.client.widgets.form.FormItemValueFormatter)
instead.
See also setEditorValueParser(com.smartgwt.client.widgets.form.FormItemValueParser)
.
formatter
- the FormItemValueFormatterpublic void setEditorValueParser(FormItemValueParser valueParser)
FormItemValueParser
to map a user-entered display value to a data
value for storage. This method only applies to form items which show a free-form text entry area, such at the TextItem
or TextAreaItem
.
See also com.smartgwt.client.widgets.form.fields.FormItem#formatEditorValue
valueParser
- the FormItemValueParserpublic void setValueIconMapper(ValueIconMapper valueIconMapper)
setValueIcons(java.util.Map)
.valueIconMapper
- the valueIconMapperpublic FormItem setDisplayFormat(DateDisplayFormat displayFormat)
"date"
or "time"
will be edited using a DateItem
or TimeItem
by
default. However this can be overridden - for canEdit:false
fields, a StaticTextItem
is used by default, and the developer can always specify a
custom editorType
as well as data type
.
For fields of type "date"
, set
this property to a valid DateDisplayFormat
to specify how the date should be
formatted.
For fields of type "time"
, set this property to a valid timeFormatter
to specify how the time should be formatted.
Note that if
dateFormatter
or timeFormatter
are specified they will take precedence
over this setting.
If this field is of type "date"
and is editable, the inputFormat
may be used to specify how user-edited date
strings will be parsed.
Note : This is an advanced setting
displayFormat
- displayFormat Default value is nullFormItem
instance, for
chaining setter callssetInputFormat(java.lang.String)
,
setDateFormatter(com.smartgwt.client.types.DateDisplayFormat)
,
setTimeFormatter(com.smartgwt.client.types.TimeDisplayFormat)
public void setDisplayFormat(TimeFormatter displayFormat)
"date"
or "time"
will be edited using a DateItem
or TimeItem
by
default. However this can be overridden - for canEdit:false
fields, a StaticTextItem
is used by default, and the developer can always specify a
custom editorType
as well as data type
.
For fields of type "date"
, set
this property to a valid DateDisplayFormat
to specify how the date should be
formatted.
For fields of type "time"
, set this property to a valid timeFormatter
to specify how the time should be formatted.
Note that if
dateFormatter
or timeFormatter
are specified they will take precedence
over this setting.
If this field is of type "date"
and is editable, the inputFormat
may be used to specify how user-edited date
strings will be parsed.
Note : This is an advanced setting
displayFormat
- displayFormat Default value is nullsetInputFormat(java.lang.String)
,
setDateFormatter(com.smartgwt.client.types.DateDisplayFormat)
,
setTimeFormatter(com.smartgwt.client.types.TimeDisplayFormat)
public void setCanEditCriterionPredicate(FormItemCanEditCriterionPredicate predicate)
DynamicForm.setValuesAsCriteria
, this predicate is used
to determine which sub-criteria apply to which form item(s). This method will be called on each item, and passed the
sub-criterion of the AdvancedCriteria object. It should return true if the item can edit the criterion, otherwise false.
If it returns true, setValuesAsCriteria() will call FormItemCriterionSetter.setCriterion
from
the registered FormItemCriterionSetter
to actually apply the criterion to
the form item, and DynamicForm.getValuesAsCriteria
can subsequently retrieve the edited criterion by calling FormItemCriterionGetter.getCriterion
from
the registered FormItemCriterionGetter
.
Default implementation will
return true if the criterion fieldName
and operator
match the fieldName and operator (or
default operator) for this item.
predicate
- the predicate to determine the form items that can edit the criterion in questionCriteriaEditing overview and related methods
public final java.lang.Boolean canEditCriterion(Criterion criterion)
canEditCriterion()
method of the FormItemCanEditCriterionPredicate
that is registered with this field.criterion
- sub-criterion from an AdvancedCriteria objectCriteriaEditing overview and related methods
public void setCriterionGetter(FormItemCriterionGetter getter)
DynamicForm.getValuesAsCriteria
. This API is provided to allow you to specify a more complex criterion than the "field-operator-value" criterions that are built-in. Note that the built-in behavior is generally quite flexible and powerful enough for most requirements. An example of a case where you might want to override this method is if you wanted to implement a date range selection (ie, date > x AND date < y) on a form that was combining its other criteria fields with an "or" operator.
Note that this method is part of the criteria editing subsystem: if overridden, it is likely that you will want to also
override FormItem.hasAdvancedCriteria
to
ensure this method is called by the form, and to support editing of existing advanced criteria you may also need to
set the FormItemCanEditCriterionPredicate
and the FormItemCriterionSetter
.
The default implementation
will return a criterion including the form item value, fieldName and specified operator
, or a default operator derived from the form item
data type if no explicit operator is specified.
getter
- provides a method to get a criterion object based on this field's current edited value(s).CriteriaEditing overview and related methods
public final Criterion getCriterion()
getCriterion()
method
of the FormItemCriterionGetter
that is registered with this field.CriteriaEditing overview and related methods
public final Criterion getCriterion(TextMatchStyle textMatchStyle)
getCriterion()
method
of the FormItemCriterionGetter
that is registered with this field.textMatchStyle
- If passed assume the textMatchStyle will be used when performing a fetch operation with these criteria. This may
impact the criterion's operator property.CriteriaEditing overview and related methods
public void setCriterionSetter(FormItemCriterionSetter setter)
DynamicForm.setValuesAsCriteria
when the
registered FormItemCanEditCriterionPredicate
returns true for this item.
Default implementation simply calls FormItem.setValue
with the value
of the criterion passed in
setter
- provides a method to update this field with the edited criterionpublic final void setCriterion(Criterion criterion)
setCriterion()
method
of the FormItemCriterionSetter
that is registered with this field.criterion
- criterion to editpublic void setAriaState(java.lang.String stateName, java.lang.Object stateValue) throws java.lang.IllegalStateException
com.smartgwt.docs.Accessibility
.stateName
- stateValue
- java.lang.IllegalStateException
- ARIA state cannot be changed after the form item has been created.public java.lang.String[] getErrors()
public void setErrors(java.lang.String error)
public void setErrors(java.lang.String[] errors)
public java.lang.Boolean isDisabled()
public java.lang.Boolean getDisabled()
#isDisabled)
, which correctly inherits the disabled state from containerspublic void setCustomStateGetter(FormItem.CustomStateGetter getter)
com.smartgwt.client.widgets.form.fields.FormItem.setStateCustomizer
insteadIf defined, the CustomStateGetter's getCustomState() method will be called whenever the framework needs to determine which style to use for the formItem in its state at that time
getter
- the CustomStateGetter objectpublic void setStateCustomizer(FormItem.StateCustomizer customizer)
CustomStateGetter
;
the only difference between the two interfaces is that the StateCustomizer
's getCustomState()
method is
passed the applicable FormItem, so application code does not need to track this information. The StateCustomizer's getCustomState() method will be called whenever the framework needs to determine which style to use for the formItem in its state at that time
customizer
- the StateCustomizer objectpublic void setConfigOnly(boolean configOnly)
public boolean isConfigOnly()
public void linkToInstanceUponCreate()
public java.lang.Object mapDisplayToValue(java.lang.String value)
This method is called by the framework to derive an underlying data value for a given display value
(ie, the value the user sees and interacts with) in a FormItem. Your own code can call this method if you need to
programmatically obtain the underlying data value for a given display value. However, this method is not an override
point. If you have a field that requires the stored value to be different from the displayed value, and the requirement
cannot be satisfied with a valueMap
for some
reason, you can add custom parsing logic by setting an editor value parser
This method is also not intended as a place where you can validate, sanitize, transform or canonicalize user input
input masks
or
a addChangeHandler(com.smartgwt.client.widgets.form.fields.events.ChangeHandler
change handler)
mask validator
with "transformTo". See the link to "mask validator" for more
details and an example of thisinput transformer
editor value parser
, it is calledSimpleType
that has had an edit parser
applied with the setEditParser()
API, the edit parser is calledSimpleType
that inheritsFrom
"date", "time" or "datetime", it will be parsed as a date, time or datetime. Note, this parsing step
is applied on top of custom SimpleType- and FormItem-level parsingvalueMap
, a value is derived by looking up the display
value (including the effects of any parsing we may have done so far) in the valueMapmapValueToDisplay()
, there
is no special built-in handling of DataSourceField.multiple
:true
fields. If you want an array to be parsed out of some user input, you must write
the parser method to do so.value
- display valuemapValueToDisplay(java.util.Map)
public java.lang.String mapValueToDisplay(java.util.Map value)
This method is called by the framework to derive a display value for a given data value in a FormItem. Your own code can call this method if you need to programmatically obtain the display value (for example, to display in a hover prompt or error message). However, this method is not an override point. There are several supported ways to apply custom formatting to your form values:
SimpleType
, specify a format
on the
SimpleType. This is the most general approach. Note, this is a static formatter: it will only affect the format of
values the user can interact with if TextItem.formatOnBlur
is setDataSource-described field
, the best approach is DataSourceField.format
. This overrides SimpleType-level formatting
and, again, is static formattingformat
can
also be declared for individual FormItems. This overrides DataSource-level formattingdateFormatter
and timeFormatter
at both FormItem
and
DynamicForm
levels. Generally, however, we recommend the generic declarative
format
as the simpler approachsetValueFormatter(com.smartgwt.client.widgets.form.FormItemValueFormatter)
for static-valued items like StaticTextItem
or SelectItem
,
and setEditorValueFormatter(com.smartgwt.client.widgets.form.FormItemValueFormatter)
for other types of FormItemvalueMap
, the display value is derived by looking up the value in the valueMapdisplayField
and an optionDataSource
, the display value is derived by
looking up the "displayField" corresponding to the value in the optionDataSource's local cachevalueMap
and no optionDataSource
. In
this case, the passed-in value is treated as the display value for all further purposes.StaticTextItem
or SelectItem
setValueFormatter()
API, the value formatter is
calledformat
, the formst is applied in line with the
rules of FormatString
SimpleType
that declares a format
, the format is appliedsetEditorValueFormatter()
API, the editor value
formatter is called SimpleType
that has had an edit formatter applied with the
setEditFormatter()
API, the edit formatter is calledtimeFormatter
and no dateFormatter
, the timeFormatter is calledSimpleType
that inheritsFrom
"time", the value is formatted using the
default time format
dateFormatter
. SimpleType
that declares a
normalDisplayFormatter
, this is usedtoLocaleString()
method, if the value has one,
or the toString()
method if it does notemptyDisplayValue
value formatter
that is capable of formatting an array-valued
field in some way that makes sense for the particular application domain. However, for items that are marked to
handle multiple
values, array values are treated
differently. In this case, the display value is built up by calling mapValueToDisplay()
recursively for
each array entry, and concatenating these partial display values together using the multipleValueSeparator
.
value
- value to be mapped to a display valueSelectItem
or StaticTextItem
,
the display value string will be interpreted as HTML by the browser. See
SelectItem.escapeHTML
for more detailsmapDisplayToValue(java.lang.String)
public java.lang.String mapValueToDisplay(com.google.gwt.core.client.JavaScriptObject value)
public java.lang.String mapValueToDisplay(java.lang.Object value)
public static boolean getWarnOnEditorTypeConversionDefault()
getWarnOnEditorTypeConversion()
public static void setWarnOnEditorTypeConversionDefault(boolean warn)
warn
- whether to warn if SmartGWT FormItem wrapping a SmartClient item is replacedsetWarnOnEditorTypeConversion(boolean)
public boolean getWarnOnEditorTypeConversion()
setWarnOnEditorTypeConversionDefault(boolean)
.public void setWarnOnEditorTypeConversion(boolean warn)
getOrCreateRef()
is called. A SmartGWT FormItem
created using the default or (String) name constructor will never be replaced unless
it has the base class (i.e. FormItem) type, in which case it's always replaced as no
SmartClient FormItem instance will ever have the FormItem class type. A SmartGWT
FormItem created using the
JavaScriptObject
constructor (perhaps
indirectly via
FormItemFactory
) will be
replaced by a call to getOrCreateRef()
if the wrapping SmartGWT
FormItem type ends up mismatching the underlying SmartClient instance. This may happen
if:DynamicForm
instance
doesn't exist, so
FormItemFactory
(if used)
is unable to select the right SmartGWT FormItem class to wrap the underlying SmartClient
item instance
Note that when calling a SmartGWT FormItem constructor taking a JavaScriptObject, you can
call setAttribute()
on the "editorType" property and pass the
desired FormItem subclass name to ensure that the ultimate SmartClient instance type
matches the SmartGWT FormItem constructor you've chosen (except when creating the base
class FormItem type - that will always be replaced). You can use
setEditorType()
instead of setAttribute() if you've made the
Java annotation to generate the appropriate BeanFactory, but that's really only needed if
the type being set doesn't correspond to a native SmartGWT Framework FormItem class.
The default value can be configured by calling
setWarnOnEditorTypeConversionDefault(boolean)
.
warn
- whether to warn if SmartGWT FormItem wrapping a SmartClient item is replacedpublic void handleWarnOnEditorTypeConversion(FormItem oldItem, FormItem newItem)
public java.util.Map getValueMap()
SelectItem
.
An item's valueMap can be either an Array of String values or a Map of stored String
property names to Java Objects.
To set the initial selection for a form item with a valueMap, use defaultValue
.
See also DataSourceField.valueMap
.
setValueMap(String...)
,
getValueMapAsArray()
,
setValueMap(Map)
public java.lang.String[] getValueMapAsArray()
getValueMap()