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

java.lang.Object
  extended by com.smartgwt.client.core.JsObject
      extended by com.smartgwt.client.core.DataClass
          extended by com.smartgwt.client.core.RefDataClass
              extended by com.smartgwt.client.widgets.form.fields.FormItem
All Implemented Interfaces:
HasHandlers, HasBlurHandlers, HasChangedHandlers, HasChangeHandlers, HasClickHandlers, HasDoubleClickHandlers, HasFocusHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasTitleHoverHandlers
Direct Known Subclasses:
BlurbItem, BooleanItem, CanvasItem, CheckboxItem, ColorPickerItem, ComboBoxItem, DateItem, FloatItem, HeaderItem, HiddenItem, IntegerItem, NativeCheckboxItem, RadioGroupItem, SelectItem, SpacerItem, StaticTextItem, TextAreaItem, TextItem

public class FormItem
extends RefDataClass
implements HasFocusHandlers, HasBlurHandlers, HasChangeHandlers, HasChangedHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasKeyDownHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasClickHandlers, HasDoubleClickHandlers, HasTitleHoverHandlers

An Item that can participate in a DynamicForm, managing some value.

FormItems are never directly created, instead, FormItem descriptors are passed to a DynamicForm. See the DynamicForm documentation for details.


Field Summary
 
Fields inherited from class com.smartgwt.client.core.JsObject
jsObj
 
Constructor Summary
FormItem()
           
FormItem(JavaScriptObject jsObj)
           
 
Method Summary
 HandlerRegistration addBlurHandler(BlurHandler handler)
          Add a blur handler.
 HandlerRegistration addChangedHandler(ChangedHandler handler)
          Add a changed handler.
 HandlerRegistration addChangeHandler(ChangeHandler handler)
          Add a change handler.
 HandlerRegistration addClickHandler(ClickHandler handler)
          Add a click handler.
 HandlerRegistration addDoubleClickHandler(DoubleClickHandler handler)
          Add a doubleClick handler.
 HandlerRegistration addFocusHandler(FocusHandler handler)
          Add a focus handler.
 HandlerRegistration addIconClickHandler(IconClickHandler handler)
          Add a iconClick handler.
 HandlerRegistration addIconKeyPressHandler(IconKeyPressHandler handler)
          Add a iconKeyPress handler.
 HandlerRegistration addItemHoverHandler(ItemHoverHandler handler)
          Add a itemHover handler.
 HandlerRegistration addKeyDownHandler(KeyDownHandler handler)
          Add a keyDown handler.
 HandlerRegistration addKeyPressHandler(KeyPressHandler handler)
          Add a keyPress handler.
 HandlerRegistration addKeyUpHandler(KeyUpHandler handler)
          Add a keyUp handler.
 HandlerRegistration addTitleHoverHandler(TitleHoverHandler handler)
          Add a titleHover handler.
 void blurItem()
          Takes focus from this form item's focusable element.
 void clearValue()
          Clear the value for this form item.
 void disable()
          Set this item to be disabled at runtime.
 void enable()
          Set this item to be enabled at runtime.
 void focusInItem()
          Move the keyboard focus into this item's focusable element
 String getAccessKey()
          AccessKey - a keyboard shortcut to trigger a form item's default behavior.
Note: Alt+ (or in Moz Firefox 2.0 and above, Shift+Alt+) the specified key will trigger the form item's default behavior.
 Alignment getAlign()
          Alignment of this item in its cell.
 String getAttribute(String attribute)
           
 Boolean getAttributeAsBoolean(String attribute)
           
 Date getAttributeAsDate(String attribute)
           
 Double getAttributeAsDouble(String attribute)
           
 Float getAttributeAsFloat(String attribute)
           
 Integer getAttributeAsInt(String attribute)
           
 JavaScriptObject getAttributeAsJavaScriptObject(String attribute)
           
 String getAttributeAsString(String attribute)
           
 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.
 JavaScriptObject getConfig()
           
 String getCriteriaField()
          When using operator, the name of the DataSource field for the ${isc.DocUtils.linkForRef('object:Criterion')} this FormItem generates.
 void getCriterion()
          Override this method if you need to provide a specialized criterion from this formItem when creating an AdvancedCriteria via DynamicForm.getValuesAsCriteria().
 String getDataPath()
          dataPath for this item.
 DateDisplayFormat getDateFormatter()
          Display format to use for date type values within this formItem.
 String getDefaultIconSrc()
          Default icon image source.
 Boolean getDisabled()
          Whether this item is disabled.
 String getDisplayField()
          Specifies an alternative field from which display values should be retrieved for this item.
 String getDisplayFieldName()
          Returns the displayField for this form item.
 String getDisplayValue()
          Returns this item's value with any valueMap applied to it - the value as currently displayed to the user.
 String getDisplayValue(String value)
          Returns this item's value with any valueMap applied to it - the value as currently displayed to the user.
 String getEmptyDisplayValue()
          Text to display when this form item has a null or undefined value.
 String getEmptyValueIcon()
          This property allows the developer to specify an icon to display when this item has no value.
 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.
 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 showInlineErrors and showErrorText are both true and errorOrientation is "left" or "right", errorMessageWidth is the amount to reduce the width of the editor to accomodate the error message and icon.
 Boolean getFetchMissingValues()
          If displayField is specified for this item, should the item perform a fetch on the optionDataSource to retrieve the display value for the item when setValue(int) is called with a value for which we do not already have a mapped display value?
 String getFieldName()
          Return the name for the this formItem.
 Boolean getFilterLocally()
          If this form item is mapping data values to a display value by fetching them 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.
 DynamicForm getForm()
          A reference to the FormItem's DynamicForm.
 Integer getGlobalTabIndex()
          TabIndex for the form item within the page.
 int getHeight()
          Default height of this item.
 String getHint()
          Specifies "hint" string to show next to the form item to indicate something to the user.
 String getHintStyle()
          CSS class for the "hint" string.
 Alignment getHoverAlign()
          Text alignment for text displayed in this item's hover canvas, if shown.
 Integer getHoverDelay()
          If specified, this is the number of miliseconds 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.
 Integer getHoverHeight()
          Option to specify a height for any hover shown for this item.
 Integer getHoverOpacity()
          Opacity for any hover shown for this item
 String getHoverStyle()
          Explict CSS Style for any hover shown for this item.
 Integer getHoverVAlign()
          Vertical text alignment for text displayed in this item's hover canvas, if shown.
 Integer getHoverWidth()
          Option to specify a width for any hover shown for this item.
 int getIconHeight()
          Default height for form item icons
 Rectangle getIconPageRect(FormItemIcon icon)
           
 String getIconPrompt()
          Default prompt (and tooltip-text) for icons.
 Rectangle getIconRect(FormItemIcon icon)
           
 VerticalAlignment getIconVAlign()
          How should icons be aligned vertically for this form item.
 int getIconWidth()
          Default width for form item icons
 String getImageURLPrefix()
          Prefix to apply to the beginning of any valueIcons when determining the URL for the image.
 String getImageURLSuffix()
          Suffix to apply to the end of any valueIcons when determining the URL for the image.
 int getLeft()
          Left coordinate of this item in pixels.
 String getName()
          Name for this form field.
 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
 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
 String getOptionOperationId()
          If this item has a specified optionDataSource, this attribute may be set to specify an explicit operationId when performing a fetch against the option dataSource to pick up display value mapping.
static FormItem getOrCreateRef(JavaScriptObject jsObj)
           
 Integer getPickerIconHeight()
          If showPickerIcon is true for this item, this property governs the size of the picker icon.
 String getPickerIconSrc()
          If showPickerIcon is true for this item, this property governs the src of the picker icon image to be displayed.
 Integer getPickerIconWidth()
          If showPickerIcon is true for this item, this property governs the size of the picker icon.
 String getPrompt()
          This text is shown as a tooltip prompt when the cursor hovers over this item.
 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.
 Boolean getRequired()
          Whether a non-empty value is required for this field to pass validation.
 int getRowSpan()
          Number of rows that this item spans
 Boolean getSelectOnFocus()
          Allows the 'selectOnFocus' behavior to be configured on a per-FormItem basis.
 Boolean getShouldSaveValue()
          Should this item's value be saved in the form's values and hence returned from DynamicForm.getValues()?
 Boolean getShowDisabled()
          When this item is disabled, should it be re-styled to indicate its disabled state?
 Boolean getShowErrorIcon()
          'showErrorIcons', 'showErrorText', and 'showErrorStyle' control how validation errors are displayed next to form items when showInlineErrors is true.
 Boolean getShowErrorStyle()
          'showErrorIcons', 'showErrorText', and 'showErrorStyle' control how validation errors are displayed next to form items when showInlineErrors is true.
 Boolean getShowErrorText()
          'showErrorIcons', 'showErrorText', and 'showErrorStyle' control how validation errors are displayed next to form items when showInlineErrors is true.
 Boolean getShowFocused()
          When this item recieves focus, should it be re-styled to indicate it has focus?
 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.
 Boolean getShowFocusedPickerIcon()
          If showPickerIcon is true for this item, should the picker icon show a focused image when the form item has focus?
 Boolean getShowHint()
          If a hint is defined for this form item, should it be shown?
 Boolean getShowIcons()
          Set to false to suppress writing out any icons for this item.
 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.
 Boolean getShowPickerIcon()
          Should we show a special 'picker' icon for this form item.
 Boolean getShowTitle()
          Should we show a title cell for this formItem?
 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
 Boolean getStartRow()
          Whether this item should always start a new row in the form layout.
 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
 Integer getTabIndex()
          tabIndex for the form item within the form.
 Alignment getTextAlign()
          Alignment of the text / content within this form item.
 String getTextBoxStyle()
          Base CSS class name for a form item's text box element.
 TimeFormatter getTimeFormatter()
          Time-format to apply to date type values within this formItem.
 String getTitle()
          User visible title for this form item.
 Alignment getTitleAlign()
          Alignment of this item's title in its cell.
 TitleOrientation getTitleOrientation()
          On which side of this item should the title be placed.
 String getTitleStyle()
          Base CSS class name for a form item's title.
 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.
 String getType()
          The DynamicForm picks a field renderer based on the type of the field (and sometimes other attributes of the field).
 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.
 Object getValue()
           
 String getValueField()
          If this form item maps data values to display values by retrieving the displayField values from an 'optionDataSource', this property denotes the the field to use as the underlying data value in records from the optionDataSource.
If unset, assumed to be the name of this form item.
 String getValueFieldName()
          Getter method to retrieve the valueField for this item.
 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 left 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 label of the form item
 int getValueIconSize()
          If valueIcons is specified, this property may be used to specify both the width and height of the icon written out.
 Integer getValueIconWidth()
          If valueIcons is specified, use this property to specify a width for the value icon written out.
 Boolean getVisible()
          Whether this item is currently visible.
 int getWidth()
          By default, items take up the entire width of their cell
 Boolean getWrapTitle()
          If specified determines whether this items title should wrap.
 void hide()
          Hide this form item.
protected  boolean isCreated()
           
 Boolean isDisabled()
          Is this item disabled?
 Boolean isDrawn()
          Returns true if this item has been written out into the DOM.
 void redraw()
          Causes the FormItem to be redrawn immediately with the new properties.
 void setAccessKey(String accessKey)
          AccessKey - a keyboard shortcut to trigger a form item's default behavior.
Note: Alt+ (or in Moz Firefox 2.0 and above, Shift+Alt+) the specified key will trigger the form item's default behavior.
 void setAlign(Alignment align)
          Alignment of this item in its cell.
 void setAttribute(String attribute, BaseClass[] value)
           
 void setAttribute(String attribute, boolean value)
           
 void setAttribute(String attribute, Boolean value)
           
 void setAttribute(String attribute, DataClass value)
           
 void setAttribute(String attribute, DataClass[] value)
           
 void setAttribute(String attribute, Date value)
           
 void setAttribute(String attribute, double value)
           
 void setAttribute(String attribute, int value)
           
 void setAttribute(String attribute, int[] value)
           
 void setAttribute(String attribute, JavaScriptObject value)
           
 void setAttribute(String attribute, Map value)
           
 void setAttribute(String attribute, String value)
           
 void setAttribute(String attribute, String[] value)
           
 void setAttribute(String attribute, ValueEnum[] value)
           
 void setCellStyle(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.
 void setColSpan(int colSpan)
          Number of columns that this item spans.
 void setColSpan(String colSpan)
          Number of columns that this item spans.
 void setCriteriaField(String criteriaField)
          When using operator, the name of the DataSource field for the ${isc.DocUtils.linkForRef('object:Criterion')} this FormItem generates.
 void setDataPath(String dataPath)
          dataPath for this item.
 void setDateFormatter(DateDisplayFormat dateFormatter)
          Display format to use for date type values within this formItem.
 void setDefaultIconSrc(String defaultIconSrc)
          Default icon image source.
 void setDefaultValue(Boolean defaultValue)
          Value used when no value is provided for this item.
 void setDefaultValue(Date defaultValue)
          Value used when no value is provided for this item.
 void setDefaultValue(Float defaultValue)
          Value used when no value is provided for this item.
 void setDefaultValue(Integer defaultValue)
          Value used when no value is provided for this item.
 void setDefaultValue(String defaultValue)
          Value used when no value is provided for this item.
 void setDisabled(Boolean disabled)
          Whether this item is disabled.
 void setDisplayField(String displayField)
          Specifies an alternative field from which display values should be retrieved for this item.
 void setEditorType(FormItem editorType)
          Name of the FormItem to use for editing, eg "TextItem" or "SelectItem".
 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.
 void setEmptyDisplayValue(String emptyDisplayValue)
          Text to display when this form item has a null or undefined value.
 void setEmptyValueIcon(String emptyValueIcon)
          This property allows the developer to specify an icon to display when this item has no value.
 void setEndRow(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.
 void setErrorIconHeight(int errorIconHeight)
          Height of the error icon, if we're showing icons when validation errors occur.
 void setErrorIconSrc(String errorIconSrc)
          URL of the image to show as an error icon, if we're showing icons when validation errors occur.
 void setErrorIconWidth(int errorIconWidth)
          Height of the error icon, if we're showing icons when validation errors occur.
 void setErrorMessageWidth(int errorMessageWidth)
          When showInlineErrors and showErrorText are both true and errorOrientation is "left" or "right", errorMessageWidth is the amount to reduce the width of the editor to accomodate 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 setFetchMissingValues(Boolean fetchMissingValues)
          If displayField is specified for this item, should the item perform a fetch on the optionDataSource to retrieve the display value for the item when setValue(int) is called with a value for which we do not already have a mapped display value?
 void setFilterLocally(Boolean filterLocally)
          If this form item is mapping data values to a display value by fetching them 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.
 void setGlobalTabIndex(Integer globalTabIndex)
          TabIndex for the form item within the page.
 void setHeight(int height)
          Default height of this item.
 void setHeight(String height)
           
 void setHint(String hint)
          Specifies "hint" string to show next to the form item to indicate something to the user.
 void setHintStyle(String hintStyle)
          CSS class for the "hint" string.
 void setHoverAlign(Alignment hoverAlign)
          Text alignment for text displayed in this item's hover canvas, if shown.
 void setHoverDelay(Integer hoverDelay)
          If specified, this is the number of miliseconds 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.
 void setHoverHeight(Integer hoverHeight)
          Option to specify a height for any hover shown for this item.
 void setHoverOpacity(Integer hoverOpacity)
          Opacity for any hover shown for this item
 void setHoverStyle(String hoverStyle)
          Explict CSS Style for any hover shown for this item.
 void setHoverVAlign(Integer hoverVAlign)
          Vertical text alignment for text displayed in this item's hover canvas, if shown.
 void setHoverWidth(Integer hoverWidth)
          Option to specify a width for any hover shown for this item.
 void setIconHeight(int iconHeight)
          Default height for form item icons
 void setIconPrompt(String iconPrompt)
          Default prompt (and tooltip-text) for icons.
 void setIcons(FormItemIcon... icons)
          An array of descriptor objects for icons to display in a line after this form item.
 void setIconVAlign(VerticalAlignment iconVAlign)
          How should icons be aligned vertically for this form item.
 void setIconWidth(int iconWidth)
          Default width for form item icons
 void setImageURLPrefix(String imageURLPrefix)
          Prefix to apply to the beginning of any valueIcons when determining the URL for the image.
 void setImageURLSuffix(String imageURLSuffix)
          Suffix to apply to the end of any valueIcons when determining the URL for the image.
 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 mousepointer over the item's title.
 void setLeft(int left)
          Left coordinate of this item in pixels.
 void setName(String name)
          Name for this form field.
 void 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
 void setOptionDataSource(DataSource dataSource)
           
 void setOptionFilterContext(RPCRequest optionFilterContext)
          If this item has a specified optionDataSource, and this property is not null, this will be passed to the datasource as RPCRequest properties when performing the fetch operation on the dataSource to obtain a data-value to display-value mapping
 void setOptionOperationId(String optionOperationId)
          If this item has a specified optionDataSource, this attribute may be set to specify an explicit operationId when performing a fetch against the option dataSource to pick up display value mapping.
 void setPickerIconHeight(Integer pickerIconHeight)
          If showPickerIcon is true for this item, this property governs the size of the picker icon.
 void setPickerIconSrc(String pickerIconSrc)
          If showPickerIcon is true for this item, this property governs the src of the picker icon image to be displayed.
 void setPickerIconWidth(Integer pickerIconWidth)
          If showPickerIcon is true for this item, this property governs the size of the picker icon.
 void setPrompt(String prompt)
          This text is shown as a tooltip prompt when the cursor hovers over this item.
 void setProperty(String property, boolean value)
           
 void setProperty(String property, double value)
           
 void setProperty(String property, JavaScriptObject value)
           
 void setProperty(String property, String value)
           
 void setRedrawOnChange(boolean redrawOnChange)
          Setting to true causes the FormItem to be immediately redrawn with the new properties when its value changes
 void setRejectInvalidValueOnChange(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.
 void setRequired(Boolean required)
          Whether a non-empty value is required for this field to pass validation.
 void setRowSpan(int rowSpan)
          Number of rows that this item spans
 void setSelectOnFocus(Boolean selectOnFocus)
          Allows the 'selectOnFocus' behavior to be configured on a per-FormItem basis.
 void setShouldSaveValue(Boolean shouldSaveValue)
          Should this item's value be saved in the form's values and hence returned from DynamicForm.getValues()?
 void setShowDisabled(Boolean showDisabled)
          When this item is disabled, should it be re-styled to indicate its disabled state?
 void setShowErrorIcon(Boolean showErrorIcon)
          'showErrorIcons', 'showErrorText', and 'showErrorStyle' control how validation errors are displayed next to form items when showInlineErrors is true.
 void setShowErrorStyle(Boolean showErrorStyle)
          'showErrorIcons', 'showErrorText', and 'showErrorStyle' control how validation errors are displayed next to form items when showInlineErrors is true.
 void setShowErrorText(Boolean showErrorText)
          'showErrorIcons', 'showErrorText', and 'showErrorStyle' control how validation errors are displayed next to form items when showInlineErrors is true.
 void setShowFocused(Boolean showFocused)
          When this item recieves focus, should it be re-styled to indicate it has focus?
 void setShowFocusedIcons(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.
 void setShowFocusedPickerIcon(Boolean showFocusedPickerIcon)
          If showPickerIcon is true for this item, should the picker icon show a focused image when the form item has focus?
 void setShowHint(Boolean showHint)
          If a hint is defined for this form item, should it be shown?
 void setShowIcons(Boolean showIcons)
          Set to false to suppress writing out any icons for this item.
 void setShowIfCondition(FormItemIfFunction showIf)
          Expression that's evaluated to see if an item should be dynamically hidden.
 void setShowOverIcons(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.
 void setShowPickerIcon(Boolean showPickerIcon)
          Should we show a special 'picker' icon for this form item.
 void setShowTitle(Boolean showTitle)
          Should we show a title cell for this formItem?
 void setShowValueIconOnly(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
 void setStartRow(Boolean startRow)
          Whether this item should always start a new row in the form layout.
 void setSuppressValueIcon(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
 void setTabIndex(Integer tabIndex)
          tabIndex for the form item within the form.
 void setTextAlign(Alignment textAlign)
          Alignment of the text / content within this form item.
 void setTextBoxStyle(String textBoxStyle)
          Base CSS class name for a form item's text box element.
 void setTimeFormatter(TimeFormatter timeFormatter)
          Time-format to apply to date type values within this formItem.
 void setTitle(String title)
          User visible title for this form item.
 void setTitleAlign(Alignment titleAlign)
          Alignment of this item's title in its cell.
 void setTitleOrientation(TitleOrientation titleOrientation)
          On which side of this item should the title be placed.
 void setTitleStyle(String titleStyle)
          Base CSS class name for a form item's title.
 void setTooltip(String tooltip)
          This text is shown as a tooltip prompt when the cursor hovers over this item.
 void setTop(int top)
          Top coordinate of this item in pixels.
 void setType(String type)
          The DynamicForm picks a field renderer based on the type of the field (and sometimes other attributes of the field).
 void setValidateOnChange(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.
 void setValidators(Validator... validators)
          Validators for this form item.
 void setValue(boolean value)
           
 void setValue(Date value)
           
 void setValue(double value)
           
 void setValue(float value)
           
 void setValue(int value)
           
 void setValue(String value)
           
 void setValueField(String valueField)
          If this form item maps data values to display values by retrieving the displayField values from an 'optionDataSource', this property denotes the the field to use as the underlying data value in records from the optionDataSource.
If unset, assumed to be the name of this form item.
 void setValueFormatter(FormItemValueFormatter formatter)
          Optional FormItemValueFormatter, if provided, is evaluated to get the display value to show for this form items underlying data value.
 void setValueIconHeight(Integer valueIconHeight)
          If valueIcons is specified, use this property to specify a height for the value icon written out.
 void setValueIconLeftPadding(int valueIconLeftPadding)
          If we're showing a value icon, this attribute governs the amount of space between the icon and the left edge of the form item cell
 void setValueIconRightPadding(int valueIconRightPadding)
          If we're showing a value icon, this attribute governs the amount of space between the icon and the label of the form item
 void setValueIcons(Map valueIcons)
          Set the valueIcons for this item.
 void setValueIconSize(int valueIconSize)
          If valueIcons is specified, this property may be used to specify both the width and height of the icon written out.
 void setValueIconWidth(Integer valueIconWidth)
          If valueIcons is specified, use this property to specify a width for the value icon written out.
 void setValueMap(LinkedHashMap valueMap)
          Set the valueMap for this item.
 void setValueMap(String... valueMap)
          Set the valueMap for this item.
 void setVisible(Boolean visible)
          Whether this item is currently visible.
 void setWidth(int width)
          By default, items take up the entire width of their cell
 void setWidth(String width)
           
 void setWrapTitle(Boolean wrapTitle)
          If specified determines whether this items title should wrap.
 void show()
          Show this form 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 updateState()
          Update the visual state of a FormItem to reflect any changes in state or any changes in style settings (eg textBoxStyle).
 
Methods inherited from class com.smartgwt.client.core.RefDataClass
getRef, getRef
 
Methods inherited from class com.smartgwt.client.core.DataClass
doAddHandler, fireEvent, getAttributeAsIntArray, getAttributeAsMap, getAttributeAsObject, getAttributeAsStringArray, getAttributes, getHandlerCount, getJsObj, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute
 
Methods inherited from class com.smartgwt.client.core.JsObject
setJsObj
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
 

Constructor Detail

FormItem

public FormItem()

FormItem

public FormItem(JavaScriptObject jsObj)
Method Detail

getOrCreateRef

public static FormItem getOrCreateRef(JavaScriptObject jsObj)

setDataPath

public void setDataPath(String dataPath)
dataPath for this item. Allows the user to edit details nested data structures in a flat set of form fields

Parameters:
dataPath - dataPath Default value is null

getDataPath

public String getDataPath()
dataPath for this item. Allows the user to edit details nested data structures in a flat set of form fields

Returns:
Return the dataPath for the this formItem.

setTitle

public void setTitle(String title)
User visible title for this form item.

Parameters:
title - title Default value is null

getTitle

public String getTitle()
User visible title for this form item.

Returns:
Return the title of this formItem

setEmptyDisplayValue

public void setEmptyDisplayValue(String emptyDisplayValue)
Text to display when this form item has a null or undefined value.

Parameters:
emptyDisplayValue - emptyDisplayValue Default value is ""

getEmptyDisplayValue

public String getEmptyDisplayValue()
Text to display when this form item has a null or undefined value.

Returns:
String

setOptionOperationId

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

Note : This is an advanced setting

Parameters:
optionOperationId - optionOperationId Default value is null

getOptionOperationId

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

Returns:
String

setValueField

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

Parameters:
valueField - valueField Default value is null

getValueField

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

Returns:
String

setDisplayField

public void setDisplayField(String displayField)
Specifies an alternative field from which display values should be retrieved for this item.

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

If this item is not databound (optionDataSource is unset), or bound to the same dataSource as the form as a whole, this item will call DynamicForm.getValue(java.lang.String) the form named after is implemented by picking up the value of the specified field from the Form's values object.

Otherwise this item will attempt to map its underlying value to a display value by retrieving a record from the optionDataSource where the valueField matches this item's value, and displaying the displayField value from that record. Note that if optionDataSource is set and this value is not set, getDisplayFieldName() will return the dataSource title field by default.

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

Parameters:
displayField - displayField Default value is null

getDisplayField

public String getDisplayField()
Specifies an alternative field from which display values should be retrieved for this item.

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

If this item is not databound (optionDataSource is unset), or bound to the same dataSource as the form as a whole, this item will call DynamicForm.getValue(java.lang.String) the form named after is implemented by picking up the value of the specified field from the Form's values object.

Otherwise this item will attempt to map its underlying value to a display value by retrieving a record from the optionDataSource where the valueField matches this item's value, and displaying the displayField value from that record. Note that if optionDataSource is set and this value is not set, getDisplayFieldName() will return the dataSource title field by default.

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

Returns:
String

setFetchMissingValues

public void setFetchMissingValues(Boolean fetchMissingValues)
If displayField is specified for this item, should the item perform a fetch on the optionDataSource to retrieve the display value for the item when setValue(int) is called with a value for which we do not already have a mapped display value?

As noted under optionDataSource, you may also specify a com.smartgwt.client..ValueMap and it will be consulted first before fetching from the optionDataSource.

Note : This is an advanced setting

Parameters:
fetchMissingValues - fetchMissingValues Default value is true

getFetchMissingValues

public Boolean getFetchMissingValues()
If displayField is specified for this item, should the item perform a fetch on the optionDataSource to retrieve the display value for the item when setValue(int) is called with a value for which we do not already have a mapped display value?

As noted under optionDataSource, you may also specify a com.smartgwt.client..ValueMap and it will be consulted first before fetching from the optionDataSource.

Returns:
Boolean

setFilterLocally

public void setFilterLocally(Boolean filterLocally)
If this form item is mapping data values to a display value by fetching them 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. This avoids the need to perform fetches each time setValue() is called with a new value.

See also filterLocally for behavior on form items such as SelectItems that show pick-lists.

Note : This is an advanced setting

Parameters:
filterLocally - filterLocally Default value is null

getFilterLocally

public Boolean getFilterLocally()
If this form item is mapping data values to a display value by fetching them 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. This avoids the need to perform fetches each time setValue() is called with a new value.

See also filterLocally for behavior on form items such as SelectItems that show pick-lists.

Returns:
Boolean

setDateFormatter

public void setDateFormatter(DateDisplayFormat dateFormatter)
Display format to use for date type values within this formItem. Default is to use the system-wide default short date format, configured via com.smartgwt.client..Date#setShortDisplayFormat. Specify any valid DateDisplayFormat to change the format used by this item.
Note: if both dateFormatter and 'timeFormatter' are specified on an item, Date type values will be formatted as dates using dateFormatter.
See also displayFormat for formatting dates displayed in DateItems.

Note : This is an advanced setting

Parameters:
dateFormatter - dateFormatter Default value is null

getDateFormatter

public DateDisplayFormat getDateFormatter()
Display format to use for date type values within this formItem. Default is to use the system-wide default short date format, configured via com.smartgwt.client..Date#setShortDisplayFormat. Specify any valid DateDisplayFormat to change the format used by this item.
Note: if both dateFormatter and 'timeFormatter' are specified on an item, Date type values will be formatted as dates using dateFormatter.
See also displayFormat for formatting dates displayed in DateItems.

Returns:
DateDisplayFormat

setTimeFormatter

public void setTimeFormatter(TimeFormatter timeFormatter)
Time-format to apply to date type values within this formItem. If specified, any dates displayed in this item will be formatted as times using the appropriate format.
Has no effect if +lilnk{formItem.dateFormatter} is also set.
See also displayFormat for formatting values displayed in TimeItems.

Note : This is an advanced setting

Parameters:
timeFormatter - timeFormatter Default value is null

getTimeFormatter

public TimeFormatter getTimeFormatter()
Time-format to apply to date type values within this formItem. If specified, any dates displayed in this item will be formatted as times using the appropriate format.
Has no effect if +lilnk{formItem.dateFormatter} is also set.
See also displayFormat for formatting values displayed in TimeItems.

Returns:
TimeFormatter

setEmptyValueIcon

public void setEmptyValueIcon(String emptyValueIcon)
This property allows the developer to specify an icon to display when this item has no value. It is configured in the same way as any other valueIcon (see valueIcons)

Parameters:
emptyValueIcon - emptyValueIcon Default value is null

getEmptyValueIcon

public String getEmptyValueIcon()
This property allows the developer to specify an icon to display when this item has no value. It is configured in the same way as any other valueIcon (see valueIcons)

Returns:
String

setShowValueIconOnly

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

Note : This is an advanced setting

Parameters:
showValueIconOnly - showValueIconOnly Default value is null

getShowValueIconOnly

public 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

Returns:
Boolean

setSuppressValueIcon

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

Note : This is an advanced setting

Parameters:
suppressValueIcon - suppressValueIcon Default value is null

getSuppressValueIcon

public 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

Returns:
Boolean

setValueIconWidth

public void setValueIconWidth(Integer valueIconWidth)
If valueIcons is specified, use this property to specify a width for the value icon written out.

Parameters:
valueIconWidth - valueIconWidth Default value is null

getValueIconWidth

public Integer getValueIconWidth()
If valueIcons is specified, use this property to specify a width for the value icon written out.

Returns:
Integer

setValueIconHeight

public void setValueIconHeight(Integer valueIconHeight)
If valueIcons is specified, use this property to specify a height for the value icon written out.

Parameters:
valueIconHeight - valueIconHeight Default value is null

getValueIconHeight

public Integer getValueIconHeight()
If valueIcons is specified, use this property to specify a height for the value icon written out.

Returns:
Integer

setValueIconSize

public void setValueIconSize(int valueIconSize)
If 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 presidence over this value, if specified.

Parameters:
valueIconSize - valueIconSize Default value is 16

getValueIconSize

public int getValueIconSize()
If 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 presidence over this value, if specified.

Returns:
int

setValueIconLeftPadding

public void setValueIconLeftPadding(int valueIconLeftPadding)
If we're showing a value icon, this attribute governs the amount of space between the icon and the left edge of the form item cell

Parameters:
valueIconLeftPadding - valueIconLeftPadding Default value is 0

getValueIconLeftPadding

public int getValueIconLeftPadding()
If we're showing a value icon, this attribute governs the amount of space between the icon and the left edge of the form item cell

Returns:
int

setValueIconRightPadding

public void setValueIconRightPadding(int valueIconRightPadding)
If we're showing a value icon, this attribute governs the amount of space between the icon and the label of the form item

Parameters:
valueIconRightPadding - valueIconRightPadding Default value is 3

getValueIconRightPadding

public int getValueIconRightPadding()
If we're showing a value icon, this attribute governs the amount of space between the icon and the label of the form item

Returns:
int

setImageURLPrefix

public void setImageURLPrefix(String imageURLPrefix)
Prefix to apply to the beginning of any valueIcons when determining the URL for the image. Will not be applied if the valueIcon URL is absolute.

Note : This is an advanced setting

Parameters:
imageURLPrefix - imageURLPrefix Default value is null

getImageURLPrefix

public String getImageURLPrefix()
Prefix to apply to the beginning of any valueIcons when determining the URL for the image. Will not be applied if the valueIcon URL is absolute.

Returns:
String

setImageURLSuffix

public void setImageURLSuffix(String imageURLSuffix)
Suffix to apply to the end of any 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

Parameters:
imageURLSuffix - imageURLSuffix Default value is null

getImageURLSuffix

public String getImageURLSuffix()
Suffix to apply to the end of any 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.

Returns:
String

setShowPickerIcon

public void setShowPickerIcon(Boolean showPickerIcon)
Should we show a special 'picker' icon for this form item. Picker icons are customizeable via pickerIconProperties. By default they will be rendered inside the Form Item's "control box" area, and will call com.smartgwt.client.widgets.form.fields.FormItem#showPicker when clicked.

Parameters:
showPickerIcon - showPickerIcon Default value is false

getShowPickerIcon

public Boolean getShowPickerIcon()
Should we show a special 'picker' icon for this form item. Picker icons are customizeable via pickerIconProperties. By default they will be rendered inside the Form Item's "control box" area, and will call com.smartgwt.client.widgets.form.fields.FormItem#showPicker when clicked.

Returns:
Boolean

setShowFocusedPickerIcon

public void setShowFocusedPickerIcon(Boolean showFocusedPickerIcon)
If showPickerIcon is true for this item, should the picker icon show a focused image when the form item has focus?

Parameters:
showFocusedPickerIcon - showFocusedPickerIcon Default value is false

getShowFocusedPickerIcon

public Boolean getShowFocusedPickerIcon()
If showPickerIcon is true for this item, should the picker icon show a focused image when the form item has focus?

Returns:
Boolean

setPickerIconSrc

public void setPickerIconSrc(String pickerIconSrc)
If showPickerIcon is true for this item, this property governs the src of the picker icon image to be displayed.

Note : This is an advanced setting

Parameters:
pickerIconSrc - pickerIconSrc Default value is ""

getPickerIconSrc

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

Returns:
String

setPickerIconWidth

public void setPickerIconWidth(Integer pickerIconWidth)
If showPickerIcon is true for this item, this property governs the size of the picker icon. If unset picker icon will be sized as a square to fit in the avaliable height for the icon.

Note : This is an advanced setting

Parameters:
pickerIconWidth - pickerIconWidth Default value is null

getPickerIconWidth

public Integer getPickerIconWidth()
If showPickerIcon is true for this item, this property governs the size of the picker icon. If unset picker icon will be sized as a square to fit in the avaliable height for the icon.

Returns:
Integer

setPickerIconHeight

public void setPickerIconHeight(Integer pickerIconHeight)
If showPickerIcon is true for this item, this property governs the size of the picker icon. If unset picker icon will be sized as a square to fit in the avaliable height for the icon.

Note : This is an advanced setting

Parameters:
pickerIconHeight - pickerIconHeight Default value is null

getPickerIconHeight

public Integer getPickerIconHeight()
If showPickerIcon is true for this item, this property governs the size of the picker icon. If unset picker icon will be sized as a square to fit in the avaliable height for the icon.

Returns:
Integer

setRequired

public void setRequired(Boolean required)
Whether a non-empty value is required for this field to pass validation.

If the user does not fill in the required field, the com.smartgwt.client.widgets.form.validator.Validator#requiredField error message will be shown.

Note: if specified on a FormItem, required is only enforced on the client. required should generally be specified on a DataSourceField.

Parameters:
required - required Default value is null

getRequired

public Boolean getRequired()
Whether a non-empty value is required for this field to pass validation.

If the user does not fill in the required field, the com.smartgwt.client.widgets.form.validator.Validator#requiredField error message will be shown.

Note: if specified on a FormItem, required is only enforced on the client. required should generally be specified on a DataSourceField.

Returns:
Boolean

setVisible

public void setVisible(Boolean visible)
Whether this item is currently visible.

visible can only be set on creation. After creation, use show() and hide() to manipulate visibility.

Parameters:
visible - visible Default value is true

getVisible

public Boolean getVisible()
Whether this item is currently visible.

visible can only be set on creation. After creation, use show() and hide() to manipulate visibility.

Returns:
Boolean

setDisabled

public void setDisabled(Boolean disabled)
Whether this item is disabled. Can be updated at runtime via the 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. Set this item to be enabled or disabled at runtime.

Parameters:
disabled - true if this item should be disabled. Default value is false

getDisabled

public Boolean getDisabled()
Whether this item is disabled. Can be updated at runtime via the 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.

Returns:
Boolean

setAccessKey

public void setAccessKey(String accessKey)
AccessKey - a keyboard shortcut to trigger a form item's default behavior.
Note: Alt+ (or in Moz Firefox 2.0 and above, Shift+Alt+) the specified key will trigger the form item's default behavior.

Parameters:
accessKey - accessKey Default value is null

getAccessKey

public String getAccessKey()
AccessKey - a keyboard shortcut to trigger a form item's default behavior.
Note: Alt+ (or in Moz Firefox 2.0 and above, Shift+Alt+) the specified key will trigger the form item's default behavior.

Returns:
String

setTabIndex

public void setTabIndex(Integer tabIndex)
tabIndex for the form item within the form. Auto-assigned if not specified.
Note: This controls the tab order within the form.

To specify the tabindex of an item within the page as a whole (not just this form), use globalTabIndex instead.

Parameters:
tabIndex - tabIndex Default value is null

getTabIndex

public Integer getTabIndex()
tabIndex for the form item within the form. Auto-assigned if not specified.
Note: This controls the tab order within the form.

To specify the tabindex of an item within the page as a whole (not just this form), use globalTabIndex instead.

Returns:
Integer

setGlobalTabIndex

public void setGlobalTabIndex(Integer globalTabIndex)
TabIndex for the form item within the page. Takes presidence over any local tab index specified as 'item.tabIndex'.

Note : This is an advanced setting

Parameters:
globalTabIndex - globalTabIndex Default value is null

getGlobalTabIndex

public Integer getGlobalTabIndex()
TabIndex for the form item within the page. Takes presidence over any local tab index specified as 'item.tabIndex'.

Returns:
Integer

setSelectOnFocus

public void setSelectOnFocus(Boolean selectOnFocus)
Allows the 'selectOnFocus' behavior to be configured on a per-FormItem basis. Normally all items in a form default to the value of selectOnFocus.

Parameters:
selectOnFocus - selectOnFocus Default value is null

getSelectOnFocus

public Boolean getSelectOnFocus()
Allows the 'selectOnFocus' behavior to be configured on a per-FormItem basis. Normally all items in a form default to the value of selectOnFocus.

Returns:
Boolean

setShowTitle

public void setShowTitle(Boolean showTitle)
Should we show a title cell for this formItem?

Note: the default value of this attribute is overridden by some subclasses.

Parameters:
showTitle - showTitle Default value is true

getShowTitle

public Boolean getShowTitle()
Should we show a title cell for this formItem?

Note: the default value of this attribute is overridden by some subclasses.

Returns:
Boolean

setTitleOrientation

public void setTitleOrientation(TitleOrientation titleOrientation)
On which side of this item should the title be placed. 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.

Parameters:
titleOrientation - titleOrientation Default value is Canvas.LEFT

getTitleOrientation

public TitleOrientation getTitleOrientation()
On which side of this item should the title be placed. 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.

Returns:
TitleOrientation

setTitleAlign

public void setTitleAlign(Alignment titleAlign)
Alignment of this item's title in its cell.

If null, dynamically set according to text direction.

Parameters:
titleAlign - titleAlign Default value is null

getTitleAlign

public Alignment getTitleAlign()
Alignment of this item's title in its cell.

If null, dynamically set according to text direction.

Returns:
Alignment

setWrapTitle

public void setWrapTitle(Boolean wrapTitle)
If specified determines whether this items title should wrap. Overrides 'wrapItemTitles' at the DynamicForm level.

Parameters:
wrapTitle - wrapTitle Default value is null

getWrapTitle

public Boolean getWrapTitle()
If specified determines whether this items title should wrap. Overrides 'wrapItemTitles' at the DynamicForm level.

Returns:
Boolean

setValidateOnChange

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

Note that this property can also be set at the form, level; If true at either level the valiator will be fired on change - displaying errors and rejecting the change on validation failure.

Parameters:
validateOnChange - validateOnChange Default value is false

getValidateOnChange

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

Note that this property can also be set at the form, level; If true at either level the valiator will be fired on change - displaying errors and rejecting the change on validation failure.

Returns:
Boolean

setRejectInvalidValueOnChange

public void setRejectInvalidValueOnChange(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. May be set at the item or form level.

Note : This is an advanced setting

Parameters:
rejectInvalidValueOnChange - rejectInvalidValueOnChange Default value is false

getRejectInvalidValueOnChange

public 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. May be set at the item or form level.

Returns:
Boolean

setWidth

public void setWidth(int width)
By default, items take up the entire width of their cell

Parameters:
width - width Default value is "*"

getWidth

public int getWidth()
By default, items take up the entire width of their cell

Returns:
int

setHeight

public void setHeight(int height)
Default height of this item.

Parameters:
height - height Default value is 20

getHeight

public int getHeight()
Default height of this item.

Returns:
int

setRowSpan

public void setRowSpan(int rowSpan)
Number of rows that this item spans

Parameters:
rowSpan - rowSpan Default value is 1

getRowSpan

public int getRowSpan()
Number of rows that this item spans

Returns:
int

setStartRow

public void setStartRow(Boolean startRow)
Whether this item should always start a new row in the form layout.

Parameters:
startRow - startRow Default value is false

getStartRow

public Boolean getStartRow()
Whether this item should always start a new row in the form layout.

Returns:
Boolean

setEndRow

public void setEndRow(Boolean endRow)
Whether this item should end the row it's in in the form layout

Parameters:
endRow - endRow Default value is false

getEndRow

public Boolean getEndRow()
Whether this item should end the row it's in in the form layout

Returns:
Boolean

setAlign

public void setAlign(Alignment align)
Alignment of this item in its cell. Note that the alignment of content within this item can be separately controlled via textAlign (typically only applies to items showing a "textBox", such as TextItem or SelectItem).

Parameters:
align - align Default value is Canvas.LEFT

getAlign

public Alignment getAlign()
Alignment of this item in its cell. Note that the alignment of content within this item can be separately controlled via textAlign (typically only applies to items showing a "textBox", such as TextItem or SelectItem).

Returns:
Alignment

setTextAlign

public void setTextAlign(Alignment textAlign)
Alignment of the text / content within this form item. Note that align may be used to control alignment of the entire form item within its cell. May not apply to all form item types.

Parameters:
textAlign - textAlign Default value is Canvas.LEFT

getTextAlign

public Alignment getTextAlign()
Alignment of the text / content within this form item. Note that align may be used to control alignment of the entire form item within its cell. May not apply to all form item types.

Returns:
Alignment

setLeft

public void setLeft(int left)
Left coordinate of this item in pixels. Applies only when the containing DynamicForm sets itemLayout:"absolute". For a form with 'itemLayout':"absolute" only, set the left coordinate of this form item.

Causes the form to redraw.

Note : This is an advanced setting

Parameters:
left - left Default value is 0

getLeft

public int getLeft()
Left coordinate of this item in pixels. Applies only when the containing DynamicForm sets itemLayout:"absolute".

Returns:
int

setTop

public void setTop(int top)
Top coordinate of this item in pixels. Applies only when the containing DynamicForm sets itemLayout:"absolute". For a form with 'itemLayout':"absolute" only, set the top coordinate of this form item.

Causes the form to redraw.

Note : This is an advanced setting

Parameters:
top - top Default value is 0

getTop

public int getTop()
Top coordinate of this item in pixels. Applies only when the containing DynamicForm sets itemLayout:"absolute".

Returns:
int

setDefaultIconSrc

public void setDefaultIconSrc(String defaultIconSrc)
Default icon image source. Specify as the partial URL to an image, relative to the imgDir of this component. To specify image source for a specific icon use the icon.src property.
If this item is drawn in the disabled state, the url will be modified by adding "_Disabled" to get a disabled state image for the icon. If icon.showOver is true, this url will be modified by adding "_Over" to get an over state image for the icon.

Note : This is an advanced setting

Parameters:
defaultIconSrc - defaultIconSrc Default value is "[SKIN]/DynamicForm/default_formItem_icon.gif"

getDefaultIconSrc

public String getDefaultIconSrc()
Default icon image source. Specify as the partial URL to an image, relative to the imgDir of this component. To specify image source for a specific icon use the icon.src property.
If this item is drawn in the disabled state, the url will be modified by adding "_Disabled" to get a disabled state image for the icon. If icon.showOver is true, this url will be modified by adding "_Over" to get an over state image for the icon.

Returns:
String

setShowOverIcons

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

Note : This is an advanced setting

Parameters:
showOverIcons - showOverIcons Default value is null

getShowOverIcons

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

Returns:
Boolean

setShowFocusedIcons

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

Note : This is an advanced setting

Parameters:
showFocusedIcons - showFocusedIcons Default value is null

getShowFocusedIcons

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

Returns:
Boolean

setIconVAlign

public void setIconVAlign(VerticalAlignment iconVAlign)
How should icons be aligned vertically for this form item.

Note : This is an advanced setting

Parameters:
iconVAlign - iconVAlign Default value is "bottom"

getIconVAlign

public VerticalAlignment getIconVAlign()
How should icons be aligned vertically for this form item.

Returns:
VerticalAlignment

setIconHeight

public void setIconHeight(int iconHeight)
Default height for form item icons

Note : This is an advanced setting

Parameters:
iconHeight - iconHeight Default value is 20

getIconHeight

public int getIconHeight()
Default height for form item icons

Returns:
Takes an icon definition object, and returns the height for that icon in px.

setIconWidth

public void setIconWidth(int iconWidth)
Default width for form item icons

Note : This is an advanced setting

Parameters:
iconWidth - iconWidth Default value is 20

getIconWidth

public int getIconWidth()
Default width for form item icons

Returns:
Takes an icon definition object, and returns the width for that icon in px.

setPrompt

public void setPrompt(String prompt)
This text is shown as a tooltip prompt when the cursor hovers over this item.

Parameters:
prompt - prompt Default value is null

getPrompt

public String getPrompt()
This text is shown as a tooltip prompt when the cursor hovers over this item.

Returns:
String

setIconPrompt

public void setIconPrompt(String iconPrompt)
Default prompt (and tooltip-text) for icons.

Note : This is an advanced setting

Parameters:
iconPrompt - iconPrompt Default value is ""

getIconPrompt

public String getIconPrompt()
Default prompt (and tooltip-text) for icons.

Returns:
String

setShowIcons

public void setShowIcons(Boolean showIcons)
Set to false to suppress writing out any icons for this item.

Note : This is an advanced setting

Parameters:
showIcons - showIcons Default value is true

getShowIcons

public Boolean getShowIcons()
Set to false to suppress writing out any icons for this item.

Returns:
Boolean

setErrorIconHeight

public void setErrorIconHeight(int errorIconHeight)
Height of the error icon, if we're showing icons when validation errors occur.

Parameters:
errorIconHeight - errorIconHeight Default value is 16

getErrorIconHeight

public int getErrorIconHeight()
Height of the error icon, if we're showing icons when validation errors occur.

Returns:
int

setErrorIconWidth

public void setErrorIconWidth(int errorIconWidth)
Height of the error icon, if we're showing icons when validation errors occur.

Parameters:
errorIconWidth - errorIconWidth Default value is 16

getErrorIconWidth

public int getErrorIconWidth()
Height of the error icon, if we're showing icons when validation errors occur.

Returns:
int

setErrorIconSrc

public void setErrorIconSrc(String errorIconSrc)
URL of the image to show as an error icon, if we're showing icons when validation errors occur.

Parameters:
errorIconSrc - errorIconSrc Default value is "[SKIN]/DynamicForm/validation_error_icon.png"

getErrorIconSrc

public String getErrorIconSrc()
URL of the image to show as an error icon, if we're showing icons when validation errors occur.

Returns:
String

setShowErrorIcon

public void setShowErrorIcon(Boolean showErrorIcon)
'showErrorIcons', 'showErrorText', and 'showErrorStyle' control how validation errors are displayed next to form items when showInlineErrors is true. These properties are boolean values, 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 com.smartgwt.client.widgets.form.fields.FormItem#getErrorHTML. The default implemenation 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 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).

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

In addition to this, showErrorStyle determines whether fields with validation errors should have special styling applied to them. See com.smartgwt.client..FormItemBaseStyle for a discussion for how error styling is calculated.

Parameters:
showErrorIcon - showErrorIcon Default value is null

getShowErrorIcon

public Boolean getShowErrorIcon()
'showErrorIcons', 'showErrorText', and 'showErrorStyle' control how validation errors are displayed next to form items when showInlineErrors is true. These properties are boolean values, 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 com.smartgwt.client.widgets.form.fields.FormItem#getErrorHTML. The default implemenation 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 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).

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

In addition to this, showErrorStyle determines whether fields with validation errors should have special styling applied to them. See com.smartgwt.client..FormItemBaseStyle for a discussion for how error styling is calculated.

Returns:
Boolean

setShowErrorText

public void setShowErrorText(Boolean showErrorText)
'showErrorIcons', 'showErrorText', and 'showErrorStyle' control how validation errors are displayed next to form items when showInlineErrors is true. These properties are boolean values, 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 com.smartgwt.client.widgets.form.fields.FormItem#getErrorHTML. The default implemenation 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 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).

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

In addition to this, showErrorStyle determines whether fields with validation errors should have special styling applied to them. See com.smartgwt.client..FormItemBaseStyle for a discussion for how error styling is calculated.

Parameters:
showErrorText - showErrorText Default value is null

getShowErrorText

public Boolean getShowErrorText()
'showErrorIcons', 'showErrorText', and 'showErrorStyle' control how validation errors are displayed next to form items when showInlineErrors is true. These properties are boolean values, 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 com.smartgwt.client.widgets.form.fields.FormItem#getErrorHTML. The default implemenation 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 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).

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

In addition to this, showErrorStyle determines whether fields with validation errors should have special styling applied to them. See com.smartgwt.client..FormItemBaseStyle for a discussion for how error styling is calculated.

Returns:
Boolean

setShowErrorStyle

public void setShowErrorStyle(Boolean showErrorStyle)
'showErrorIcons', 'showErrorText', and 'showErrorStyle' control how validation errors are displayed next to form items when showInlineErrors is true. These properties are boolean values, 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 com.smartgwt.client.widgets.form.fields.FormItem#getErrorHTML. The default implemenation 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 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).

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

In addition to this, showErrorStyle determines whether fields with validation errors should have special styling applied to them. See com.smartgwt.client..FormItemBaseStyle for a discussion for how error styling is calculated.

Parameters:
showErrorStyle - showErrorStyle Default value is null

getShowErrorStyle

public Boolean getShowErrorStyle()
'showErrorIcons', 'showErrorText', and 'showErrorStyle' control how validation errors are displayed next to form items when showInlineErrors is true. These properties are boolean values, 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 com.smartgwt.client.widgets.form.fields.FormItem#getErrorHTML. The default implemenation 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 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).

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

In addition to this, showErrorStyle determines whether fields with validation errors should have special styling applied to them. See com.smartgwt.client..FormItemBaseStyle for a discussion for how error styling is calculated.

Returns:
Boolean

setHint

public void setHint(String hint)
Specifies "hint" string to show next to the form item to indicate something to the user. This string generally appears to the right of the form item. Set the hint text for this item

Parameters:
hint - new hint for the item. Default value is null

getHint

public String getHint()
Specifies "hint" string to show next to the form item to indicate something to the user. This string generally appears to the right of the form item.

Returns:
String

setShowHint

public void setShowHint(Boolean showHint)
If a hint is defined for this form item, should it be shown?

Note : This is an advanced setting

Parameters:
showHint - showHint Default value is true

getShowHint

public Boolean getShowHint()
If a hint is defined for this form item, should it be shown?

Returns:
Boolean

setShowFocused

public void setShowFocused(Boolean showFocused)
When this item recieves focus, should it be re-styled to indicate it has focus?

Note : This is an advanced setting

Parameters:
showFocused - showFocused Default value is false

getShowFocused

public Boolean getShowFocused()
When this item recieves focus, should it be re-styled to indicate it has focus?

Returns:
Boolean

setShowDisabled

public void setShowDisabled(Boolean showDisabled)
When this item is disabled, should it be re-styled to indicate its disabled state?

Note : This is an advanced setting

Parameters:
showDisabled - showDisabled Default value is true

getShowDisabled

public Boolean getShowDisabled()
When this item is disabled, should it be re-styled to indicate its disabled state?

Returns:
Boolean

setCellStyle

public void setCellStyle(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. Applied to the cell containing the form item.

NOTE: See the CompoundFormItem_skinning discussion for special skinning considerations.

Parameters:
cellStyle - cellStyle Default value is "formCell"

getCellStyle

public 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. Applied to the cell containing the form item.

NOTE: See the CompoundFormItem_skinning discussion for special skinning considerations.

Returns:
String

setHintStyle

public void setHintStyle(String hintStyle)
CSS class for the "hint" string. Set the hintStyle for this item

Parameters:
hintStyle - new style for hint text. Default value is "formHint"

getHintStyle

public String getHintStyle()
CSS class for the "hint" string.

Returns:
String

setTitleStyle

public void setTitleStyle(String titleStyle)
Base CSS class name for a form item's title.

Parameters:
titleStyle - titleStyle Default value is "formTitle"

getTitleStyle

public String getTitleStyle()
Base CSS class name for a form item's title.

Returns:
String

setTextBoxStyle

public void setTextBoxStyle(String textBoxStyle)
Base CSS class name for a form item's text box element.

NOTE: See the CompoundFormItem_skinning discussion for special skinning considerations.

Parameters:
textBoxStyle - textBoxStyle Default value is null

getTextBoxStyle

public String getTextBoxStyle()
Base CSS class name for a form item's text box element.

NOTE: See the CompoundFormItem_skinning discussion for special skinning considerations.

Returns:
String

setHoverDelay

public void setHoverDelay(Integer hoverDelay)
If specified, this is the number of miliseconds 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.

Note : This is an advanced setting

Parameters:
hoverDelay - hoverDelay Default value is null

getHoverDelay

public Integer getHoverDelay()
If specified, this is the number of miliseconds 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.

Returns:
Integer

setHoverWidth

public void setHoverWidth(Integer hoverWidth)
Option to specify a width for any hover shown for this item.

Parameters:
hoverWidth - hoverWidth Default value is null

getHoverWidth

public Integer getHoverWidth()
Option to specify a width for any hover shown for this item.

Returns:
Integer

setHoverHeight

public void setHoverHeight(Integer hoverHeight)
Option to specify a height for any hover shown for this item.

Parameters:
hoverHeight - hoverHeight Default value is null

getHoverHeight

public Integer getHoverHeight()
Option to specify a height for any hover shown for this item.

Returns:
Integer

setHoverAlign

public void setHoverAlign(Alignment hoverAlign)
Text alignment for text displayed in this item's hover canvas, if shown.

Parameters:
hoverAlign - hoverAlign Default value is null

getHoverAlign

public Alignment getHoverAlign()
Text alignment for text displayed in this item's hover canvas, if shown.

Returns:
Alignment

setHoverVAlign

public void setHoverVAlign(Integer hoverVAlign)
Vertical text alignment for text displayed in this item's hover canvas, if shown.

Parameters:
hoverVAlign - hoverVAlign Default value is null

getHoverVAlign

public Integer getHoverVAlign()
Vertical text alignment for text displayed in this item's hover canvas, if shown.

Returns:
Integer

setHoverStyle

public void setHoverStyle(String hoverStyle)
Explict CSS Style for any hover shown for this item.

Parameters:
hoverStyle - hoverStyle Default value is null

getHoverStyle

public String getHoverStyle()
Explict CSS Style for any hover shown for this item.

Returns:
String

setHoverOpacity

public void setHoverOpacity(Integer hoverOpacity)
Opacity for any hover shown for this item

Parameters:
hoverOpacity - hoverOpacity Default value is null

getHoverOpacity

public Integer getHoverOpacity()
Opacity for any hover shown for this item

Returns:
Integer

setOperator

public void 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 date range filtering, without the more advanced user interface of the FilterBuilder.

When item.operator is set for any FormItem in a form, form.getValuesAsCriteria() will return an ${isc.DocUtils.linkForRef('object:AdvancedCriteria')} object instead of a normal Criteria object. Each FormItem will produce one ${isc.DocUtils.linkForRef('object:Criterion')} affecting the DataSource field specified by criteriaField. The criteria produced by the FormItems will be grouped under the logical operator provided by 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 "iContains" (case-insensitive match)

Note: Advanced criteria will only be created for items in a Databound form. If this item is part of a form with no 'dataSource', the operator attribute will have no effect.

Parameters:
operator - operator Default value is null

getOperator

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 date range filtering, without the more advanced user interface of the FilterBuilder.

When item.operator is set for any FormItem in a form, form.getValuesAsCriteria() will return an ${isc.DocUtils.linkForRef('object:AdvancedCriteria')} object instead of a normal Criteria object. Each FormItem will produce one ${isc.DocUtils.linkForRef('object:Criterion')} affecting the DataSource field specified by criteriaField. The criteria produced by the FormItems will be grouped under the logical operator provided by 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 "iContains" (case-insensitive match)

Note: Advanced criteria will only be created for items in a Databound form. If this item is part of a form with no 'dataSource', the operator attribute will have no effect.

Returns:
OperatorId

setCriteriaField

public void setCriteriaField(String criteriaField)
When using operator, the name of the DataSource field for the ${isc.DocUtils.linkForRef('object: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(java.lang.String, java.lang.String).

Parameters:
criteriaField - criteriaField Default value is null

getCriteriaField

public String getCriteriaField()
When using operator, the name of the DataSource field for the ${isc.DocUtils.linkForRef('object: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(java.lang.String, java.lang.String).

Returns:
String

setErrorMessageWidth

public void setErrorMessageWidth(int errorMessageWidth)
When showInlineErrors and showErrorText are both true and errorOrientation is "left" or "right", errorMessageWidth is the amount to reduce the width of the editor to accomodate the error message and icon.

Parameters:
errorMessageWidth - errorMessageWidth Default value is 80

getErrorMessageWidth

public int getErrorMessageWidth()
When showInlineErrors and showErrorText are both true and errorOrientation is "left" or "right", errorMessageWidth is the amount to reduce the width of the editor to accomodate the error message and icon.

Returns:
int

setShouldSaveValue

public void setShouldSaveValue(Boolean shouldSaveValue)
Should this item's value be saved in the form's values and hence returned from DynamicForm.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 can use DynamicForm.setValue(java.lang.String, java.lang.String) or setValue(int). Providing a value via 'form.values' or DynamicForm.setValues(java.util.Map) will automatically switch the item to shouldSaveValue:true.

Note that

Parameters:
shouldSaveValue - shouldSaveValue Default value is true

getShouldSaveValue

public Boolean getShouldSaveValue()
Should this item's value be saved in the form's values and hence returned from DynamicForm.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 can use DynamicForm.setValue(java.lang.String, java.lang.String) or setValue(int). Providing a value via 'form.values' or DynamicForm.setValues(java.util.Map) will automatically switch the item to shouldSaveValue:true.

Note that

Returns:
Boolean

getFieldName

public String getFieldName()
Return the name for the this formItem.

Returns:
name for this form item

updateState

public void updateState()
Update the visual state of a FormItem to reflect any changes in state or any changes in style settings (eg 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.


isDrawn

public Boolean isDrawn()
Returns true if this item has been written out into the DOM.

Returns:
whether this item is drawn

show

public void show()
Show this form item.

This will cause the form to redraw. If this item had an item.showIf expression, it will be destroyed.


hide

public void hide()
Hide this form item.

This will cause the form to redraw. If this item had an item.showIf expression, it will be destroyed.


getValueFieldName

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

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

getDisplayFieldName

public String getDisplayFieldName()
Returns the displayField for this form item. If unset, and optionDataSource is explicitly specified, this method will return the title field for the optionDataSource

Returns:
display field name, or null

clearValue

public void clearValue()
Clear the value for this form item.

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


getCriterion

public void getCriterion()
Override this method if you need to provide a specialized criterion from this formItem when creating an AdvancedCriteria via 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.


stopHover

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


addItemHoverHandler

public HandlerRegistration addItemHoverHandler(ItemHoverHandler handler)
Add a itemHover handler.

Optional stringMethod to fire when the user hovers over this item. Return false to suppress default behavior of showing a hover canvas containing the HTML returned by formItem.itemHoverHTML() / form.itemHoverHTML().

Specified by:
addItemHoverHandler in interface HasItemHoverHandlers
Parameters:
handler - the itemHover handler
Returns:
HandlerRegistration used to remove this handler

addTitleHoverHandler

public HandlerRegistration addTitleHoverHandler(TitleHoverHandler handler)
Add a titleHover handler.

Optional stringMethod to fire when the user hovers over this item's title. Return false to suppress default behavior of showing a hover canvas containing the HTML returned by formItem.titleHoverHTML() / form.titleHoverHTML().

Specified by:
addTitleHoverHandler in interface HasTitleHoverHandlers
Parameters:
handler - the titleHover handler
Returns:
HandlerRegistration used to remove this handler

isDisabled

public Boolean isDisabled()
Is this item disabled?

Returns:
disabledtrue if this item is be disabled

enable

public void enable()
Set this item to be enabled at runtime.


disable

public void disable()
Set this item to be disabled at runtime.


focusInItem

public void focusInItem()
Move the keyboard focus into this item's focusable element


blurItem

public void blurItem()
Takes focus from this form item's focusable element.


addFocusHandler

public HandlerRegistration addFocusHandler(FocusHandler handler)
Add a focus handler.

Called when this FormItem receives focus.

Specified by:
addFocusHandler in interface HasFocusHandlers
Parameters:
handler - the focus handler
Returns:
HandlerRegistration used to remove this handler

addBlurHandler

public HandlerRegistration addBlurHandler(BlurHandler handler)
Add a blur handler.

Called when this FormItem loses focus.

Specified by:
addBlurHandler in interface HasBlurHandlers
Parameters:
handler - the blur handler
Returns:
HandlerRegistration used to remove this handler

addClickHandler

public HandlerRegistration addClickHandler(ClickHandler handler)
Add a click 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().

Specified by:
addClickHandler in interface HasClickHandlers
Parameters:
handler - the click handler
Returns:
HandlerRegistration used to remove this handler

addDoubleClickHandler

public HandlerRegistration addDoubleClickHandler(DoubleClickHandler handler)
Add a doubleClick handler.

Called when this FormItem is double-clicked.

Specified by:
addDoubleClickHandler in interface HasDoubleClickHandlers
Parameters:
handler - the doubleClick handler
Returns:
HandlerRegistration used to remove this handler

addIconClickHandler

public HandlerRegistration addIconClickHandler(IconClickHandler handler)
Add a iconClick handler.

StringMethod. Default action to fire when the user clicks on a form item icon. May be overridden by setting click on the form item icon directly.

Specified by:
addIconClickHandler in interface HasIconClickHandlers
Parameters:
handler - the iconClick handler
Returns:
HandlerRegistration used to remove this handler

addIconKeyPressHandler

public HandlerRegistration addIconKeyPressHandler(IconKeyPressHandler handler)
Add a iconKeyPress 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.

Specified by:
addIconKeyPressHandler in interface HasIconKeyPressHandlers
Parameters:
handler - the iconKeyPress handler
Returns:
HandlerRegistration used to remove this handler

addChangeHandler

public HandlerRegistration addChangeHandler(ChangeHandler handler)
Add a change 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 setInputTransformer(com.smartgwt.client.widgets.form.FormItemInputTransformer) 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 commited. The new value is available as a parameter to this method.

Specified by:
addChangeHandler in interface HasChangeHandlers
Parameters:
handler - the change handler
Returns:
HandlerRegistration used to remove this handler

addChangedHandler

public HandlerRegistration addChangedHandler(ChangedHandler handler)
Add a changed 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.

Specified by:
addChangedHandler in interface HasChangedHandlers
Parameters:
handler - the changed handler
Returns:
HandlerRegistration used to remove this handler

addKeyPressHandler

public HandlerRegistration addKeyPressHandler(KeyPressHandler handler)
Add a keyPress handler.

StringMethod fired when the user presses a key while focused in this form item.

Specified by:
addKeyPressHandler in interface HasKeyPressHandlers
Parameters:
handler - the keyPress handler
Returns:
HandlerRegistration used to remove this handler

addKeyDownHandler

public HandlerRegistration addKeyDownHandler(KeyDownHandler handler)
Add a keyDown handler.

StringMethod fired in response to a keydown while focused in this form item.

Specified by:
addKeyDownHandler in interface HasKeyDownHandlers
Parameters:
handler - the keyDown handler
Returns:
HandlerRegistration used to remove this handler

addKeyUpHandler

public HandlerRegistration addKeyUpHandler(KeyUpHandler handler)
Add a keyUp handler.

StringMethod fired in response to a keyup while focused in this form item.

Specified by:
addKeyUpHandler in interface HasKeyUpHandlers
Parameters:
handler - the keyUp handler
Returns:
HandlerRegistration used to remove this handler

setAttribute

public void setAttribute(String attribute,
                         String value)
Overrides:
setAttribute in class DataClass

setAttribute

public void setAttribute(String attribute,
                         Boolean value)
Overrides:
setAttribute in class DataClass

setAttribute

public void setAttribute(String attribute,
                         Map value)
Overrides:
setAttribute in class DataClass

setAttribute

public void setAttribute(String attribute,
                         int[] value)
Overrides:
setAttribute in class DataClass

setAttribute

public void setAttribute(String attribute,
                         BaseClass[] value)
Overrides:
setAttribute in class DataClass

setAttribute

public void setAttribute(String attribute,
                         DataClass[] value)
Overrides:
setAttribute in class DataClass

setAttribute

public void setAttribute(String attribute,
                         double value)
Overrides:
setAttribute in class DataClass

setAttribute

public void setAttribute(String attribute,
                         int value)
Overrides:
setAttribute in class DataClass

setAttribute

public void setAttribute(String attribute,
                         Date value)
Overrides:
setAttribute in class DataClass

setAttribute

public void setAttribute(String attribute,
                         ValueEnum[] value)
Overrides:
setAttribute in class DataClass

setAttribute

public void setAttribute(String attribute,
                         DataClass value)
Overrides:
setAttribute in class DataClass

setAttribute

public void setAttribute(String attribute,
                         JavaScriptObject value)
Overrides:
setAttribute in class DataClass

setAttribute

public void setAttribute(String attribute,
                         String[] value)
Overrides:
setAttribute in class DataClass

setAttribute

public void setAttribute(String attribute,
                         boolean value)
Overrides:
setAttribute in class DataClass

getAttribute

public String getAttribute(String attribute)
Overrides:
getAttribute in class DataClass

getAttributeAsString

public String getAttributeAsString(String attribute)
Overrides:
getAttributeAsString in class DataClass

getAttributeAsDate

public Date getAttributeAsDate(String attribute)
Overrides:
getAttributeAsDate in class DataClass

getAttributeAsDouble

public Double getAttributeAsDouble(String attribute)
Overrides:
getAttributeAsDouble in class DataClass

getAttributeAsJavaScriptObject

public JavaScriptObject getAttributeAsJavaScriptObject(String attribute)
Overrides:
getAttributeAsJavaScriptObject in class DataClass

getAttributeAsInt

public Integer getAttributeAsInt(String attribute)
Overrides:
getAttributeAsInt in class DataClass

getAttributeAsFloat

public Float getAttributeAsFloat(String attribute)
Overrides:
getAttributeAsFloat in class DataClass

getAttributeAsBoolean

public Boolean getAttributeAsBoolean(String attribute)
Overrides:
getAttributeAsBoolean in class DataClass

setProperty

public void setProperty(String property,
                        String value)

setProperty

public void setProperty(String property,
                        boolean value)

setProperty

public void setProperty(String property,
                        double value)

setProperty

public void setProperty(String property,
                        JavaScriptObject value)

isCreated

protected boolean isCreated()
Overrides:
isCreated in class JsObject

setOptionDataSource

public void setOptionDataSource(DataSource dataSource)

setName

public void setName(String name)
Name for this form field.

The FormItem's name determines the name of the property it edits within the form.

Parameters:
name - name Default value is null

getName

public String getName()
Name for this form field.

The FormItem's name determines the name of the property it edits within the form.

Returns:
String

setValidators

public void setValidators(Validator... validators)
Validators for this form item.

Note: these validators will only be run on the client; to do real client-server validation, validators must be specified on the DataSource.

Parameters:
validators - the validators

setIcons

public void setIcons(FormItemIcon... icons)
An array of descriptor objects for icons to display in a line after this form item. These icons are clickable images, often used to display some kind of helper for populating a form item.

Parameters:
icons - icons Default value is null

setErrorOrientation

public void setErrorOrientation(FormErrorOrientation errorOrientation)
If 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".
If unset the orientation will be derived from errorOrientation.

Parameters:
errorOrientation - errorOrientation Default value is null

setType

public void setType(String type)
The DynamicForm picks a field renderer based on the type of the field (and sometimes other attributes of the field).

Parameters:
type - type Default value is "text"

setColSpan

public void setColSpan(String colSpan)
Number of columns that this item spans.

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

Parameters:
colSpan - colSpan Default value is 1

setColSpan

public void setColSpan(int colSpan)
Number of columns that this item spans.

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

Parameters:
colSpan - colSpan Default value is 1

getType

public String getType()
The DynamicForm picks a field renderer based on the type of the field (and sometimes other attributes of the field).

Returns:
the type

setDefaultValue

public void setDefaultValue(String defaultValue)
Value used when no value is provided for this item. Note that whenever this item's value is cleared by the user or set to null programatically, it will be reverted to the 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.

Parameters:
defaultValue - defaultValue Default value is null

setDefaultValue

public void setDefaultValue(Integer defaultValue)
Value used when no value is provided for this item. Note that whenever this item's value is cleared by the user or set to null programatically, it will be reverted to the 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.

Parameters:
defaultValue - defaultValue Default value is null

setDefaultValue

public void setDefaultValue(Date defaultValue)
Value used when no value is provided for this item. Note that whenever this item's value is cleared by the user or set to null programatically, it will be reverted to the 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.

Parameters:
defaultValue - defaultValue Default value is null

setDefaultValue

public void setDefaultValue(Boolean defaultValue)
Value used when no value is provided for this item. Note that whenever this item's value is cleared by the user or set to null programatically, it will be reverted to the 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.

Parameters:
defaultValue - defaultValue Default value is null

setDefaultValue

public void setDefaultValue(Float defaultValue)
Value used when no value is provided for this item. Note that whenever this item's value is cleared by the user or set to null programatically, it will be reverted to the 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.

Parameters:
defaultValue - defaultValue Default value is null

setValueMap

public void setValueMap(String... valueMap)
Set the valueMap for this item.

Parameters:
valueMap - the value map

setValueMap

public void setValueMap(LinkedHashMap valueMap)
Set the valueMap for this item.

Parameters:
valueMap - the value map

setValueIcons

public void setValueIcons(Map valueIcons)
Set the valueIcons for this item.

Parameters:
valueIcons - mapping of logical values for this item to icon src URLs

setWidth

public void setWidth(String width)

setHeight

public void setHeight(String height)

setRedrawOnChange

public void setRedrawOnChange(boolean redrawOnChange)
Setting to true causes the FormItem to be immediately redrawn with the new properties when its value changes

Parameters:
redrawOnChange - true to redraw on change. Default is false

setEditorType

public void setEditorType(FormItem editorType)
Name of the FormItem to use for editing, eg "TextItem" or "SelectItem".

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.

Parameters:
editorType - editorType Default value is null

getValue

public Object getValue()

setValue

public void setValue(int value)

setValue

public void setValue(float value)

setValue

public void setValue(double value)

setValue

public void setValue(Date value)

setValue

public void setValue(String value)

setValue

public void setValue(boolean value)

getDisplayValue

public String getDisplayValue()
Returns this item's value with any valueMap applied to it - the value as currently displayed to the user.

Returns:
value displayed to the user

getDisplayValue

public String getDisplayValue(String value)
Returns this item's value with any valueMap applied to it - the value as currently displayed to the user.

Returns:
value displayed to the user

redraw

public void redraw()
Causes the FormItem to be redrawn immediately with the new properties.

See Also:
setRedrawOnChange(boolean)

getIconRect

public Rectangle getIconRect(FormItemIcon icon)

getIconPageRect

public Rectangle getIconPageRect(FormItemIcon icon)

getConfig

public JavaScriptObject getConfig()

setTooltip

public void setTooltip(String tooltip)
This text is shown as a tooltip prompt when the cursor hovers over this item. Alias for setPrompt(java.lang.String).

Parameters:
tooltip - tooltip Default value is null

getTooltip

public String getTooltip()
This text is shown as a tooltip prompt when the cursor hovers over this item. Alias for getPrompt()

Returns:
String

setOptionFilterContext

public void setOptionFilterContext(RPCRequest optionFilterContext)
If this item has a specified optionDataSource, and this property is not null, this will be passed to the datasource as RPCRequest properties when performing the fetch operation on the dataSource to obtain a data-value to display-value mapping

Note : This is an advanced setting

Parameters:
optionFilterContext - optionFilterContext Default value is null

getOptionFilterContext

public 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

Returns:
RPCRequest Properties

setOptionCriteria

public 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

Note : This is an advanced setting

Parameters:
optionCriteria - optionCriteria Default value is null

getOptionCriteria

public 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

Returns:
the option criteria

setShowIfCondition

public void setShowIfCondition(FormItemIfFunction showIf)
Expression that's evaluated to see if an item should be dynamically hidden. The showIf FormItemIfFunction is is evaluated whenever the form draws or redraws.

Parameters:
showIf - the showIf handler
See Also:
setRedrawOnChange(boolean)

setErrorFormatter

public void setErrorFormatter(FormItemErrorFormatter errorFormatter)
Register a custom error formatter for this FormItem.

Parameters:
errorFormatter - the error formatter.

setInputTransformer

public void setInputTransformer(FormItemInputTransformer inputTransformer)
The transformer is 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, and allows the developer to modify / reformat the value before it gets validated / saved. Fires before the change event.

Parameters:
inputTransformer - the input transformer

setItemHoverFormatter

public 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. Return null to suppress the hover canvas altogether.

Parameters:
hoverFormatter - the hover formatter

setItemTitleHoverFormatter

public void setItemTitleHoverFormatter(FormItemHoverFormatter hoverFormatter)
The FormItemHoverFormatter should return the HTML to display in a hover canvas when the user holds the mousepointer over the item's title. Return null to suppress the hover canvas altogether.

Parameters:
hoverFormatter - the hover formatter

getForm

public DynamicForm getForm()
A reference to the FormItem's DynamicForm.

Note that you must treat this as a read-only reference to the from

Returns:
the form

setValueFormatter

public void setValueFormatter(FormItemValueFormatter formatter)
Optional FormItemValueFormatter, if provided, is evaluated to get the display value to show for this form items underlying data value.

This provides a way to perform a more complex data to display value manipulation than a simple valueMap. Note that this method will not be applied to values displayed in a freeform text entry field (such as a TextItem or TextAreaItem), where an equivalent parser method would be required to convert a user-entered value back into a data value. Use setEditorValueFormatter(com.smartgwt.client.widgets.form.FormItemValueFormatter) and setEditorValueParser(com.smartgwt.client.widgets.form.FormItemValueParser) instead for these cases.

Parameters:
formatter - the FormItemValueFormatter

setEditorValueFormatter

public void setEditorValueFormatter(FormItemValueFormatter formatter)
An optional FormItemValueFormatter to map this item's current data value to a display value.

Note that this only applies to items which show a freeform 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).

Parameters:
formatter - the FormItemValueFormatter

setEditorValueParser

public void setEditorValueParser(FormItemValueParser valueParser)
An optional FormItemValueParser to map a user-entered display value to a data value for storage. This method only applies to form items which show a freeform text entry area, such at the TextItem or TextAreaItem.

See also com.smartgwt.client.widgets.form.fields.FormItem#formatEditorValue

Parameters:
valueParser - the FormItemValueParser