com.smartgwt.client.widgets.form.fields

Class TextItem

java.lang.Object

com.smartgwt.client.core.JsObject

com.smartgwt.client.core.DataClass

com.smartgwt.client.core.RefDataClass

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

com.smartgwt.client.widgets.form.fields.TextItem

All Implemented Interfaces:

com.google.gwt.event.shared.HasHandlers, HasBlurHandlers, HasChangedHandlers, HasChangeHandlers, HasClickHandlers, HasDoubleClickHandlers, HasEditorEnterHandlers, HasEditorExitHandlers, HasFocusHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasPendingStatusChangedHandlers, HasPickerIconClickHandlers, HasShowContextMenuHandlers, HasTitleClickHandlers, HasTitleDoubleClickHandlers, HasTitleHoverHandlers, HasValueHoverHandlers, HasValueIconClickHandlers

Direct Known Subclasses:

ColorItem, ComboBoxItem, DoubleItem, FloatItem, IntegerItem, PasswordItem, SpinnerItem, UploadItem

public class TextItem
extends FormItem

FormItem for managing a text field.

Nested Class Summary

Nested classes/interfaces inherited from class com.smartgwt.client.widgets.form.fields.FormItem

FormItem.CustomStateGetter, FormItem.StateCustomizer

Field Summary

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

configOnly, scClassName, warnOnEditorTypeConversion, warnOnEditorTypeConversionDefault

Fields inherited from class com.smartgwt.client.core.RefDataClass

id

Fields inherited from class com.smartgwt.client.core.DataClass

factoryCreated, factoryProperties

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

jsObj

Constructor Summary

Constructors

Constructor and Description
TextItem()
TextItem(com.google.gwt.core.client.JavaScriptObject jsObj)
TextItem(java.lang.String name)
TextItem(java.lang.String name, java.lang.String title)

Method Summary

Modifier and Type	Method and Description
static void	changeAutoChildDefaults(java.lang.String autoChildName, Canvas defaults) Changes the defaults for Canvas AutoChildren named autoChildName.
static void	changeAutoChildDefaults(java.lang.String autoChildName, FormItem defaults) Changes the defaults for FormItem AutoChildren named autoChildName.
static void	changePickerIconDefaults(FormItemIcon defaults)
void	deselectValue() If this item currently has focus, clear the current selection.
void	deselectValue(java.lang.Boolean start) If this item currently has focus, clear the current selection.
java.lang.Boolean	getBrowserAutoCapitalize()
java.lang.Boolean	getBrowserAutoCorrect() In Mobile Safari, should automatic correction be offered for text in the item's text box? If null, then Mobile Safari determines automatically whether to enable autocorrect.
java.lang.String	getBrowserInputType() This property corresponds to the HTML5 "inputType" attribute applied to the <input> element for this TextItem.
java.lang.Boolean	getChangeOnKeypress() Should this form item fire its change handler (and store its value in the form) on every keypress? Set to false to suppress the 'change' handler firing (and the value stored) on every keypress.
CharacterCasing	getCharacterCasing() Should entered characters be converted to upper or lowercase? Also applies to values applied with FormItem.setValue().
java.lang.String	getEditProxyConstructor() Default class used to construct the EditProxy for this component when the component is first placed into edit mode.
boolean	getEnforceLength() If a length is specified for this item, should user input be limited to the specified length? If set to true, user input and values passed to setValue() will be trimmed to the specified length.
java.lang.String	getEnteredValue() Returns the raw text value that currently appears in the text field, which can differ from FormItem.getValue() in various cases - for example: for items that constrain the value range, such as a DateItem with enforceDate:true, or a ComboBoxItem with addUnknownValues:false for items with a defined valueMap or edit value formatter and parser functions which converts display value to data value while the item has focus if changeOnKeypress is false
java.lang.Boolean	getEscapeHTML() By default HTML characters will be escaped when canEdit is false and readOnlyDisplay is "static", so that the raw value of the field (for example "<b>AAA</b>") is displayed to the user rather than the interpreted HTML (for example "AAA").
java.lang.Boolean	getFetchMissingValues() If this form item has a specified FormItem.optionDataSource, should the item ever perform a fetch against this dataSource to retrieve the related record.
java.lang.Boolean	getFormatOnBlur() With formatOnBlur enabled, this textItem will format its value according to the rules described in FormItem.mapValueToDisplay() as long as the item does not have focus.
java.lang.Boolean	getFormatOnFocusChange() Should FormItem.formatEditorValue() re-run whenever this item recieves or loses focus? Setting this property allows developers to conditionally format the display value based on item.hasFocus, typically to display a longer, more informative string while the item does not have focus, and simplifying it down to an easier-to-edit string when the user puts focus into the item.
java.lang.String	getHint() Returns the hint text for this item.
java.lang.String	getKeyPressFilter() Sets a keypress filter regular expression to limit valid characters that can be entered by the user.
java.lang.Integer	getLength() If set, the maximum number of characters for this field.
java.lang.String	getMask() Input mask used to restrict and format text within this item.
java.lang.Boolean	getMaskOverwriteMode() During entry into a masked field, should keystrokes overwrite current position value? By default new keystrokes are inserted into the field.
java.lang.String	getMaskPadChar() Character that is used to fill required empty mask positions to display text while control has no focus.
java.lang.String	getMaskPromptChar() Character that is used to fill required empty mask positions to display text while control has focus.
java.lang.Boolean	getMaskSaveLiterals() Should entered mask value be saved with embedded literals?
static TextItem	getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)
java.lang.Boolean	getPrintFullText() When generating a print-view of the component containing this TextItem, should the form item expand to accommodate its value? If set to false the text box will not expand to fit its content in the print view, instead showing exactly as it does in the live form.
java.lang.Boolean	getSaveOnEnter() Text items will submit their containing form on enter keypress if saveOnEnter is true.
int[]	getSelectionRange() For text-based items, this method returns the indices of the start/end of the current selection if the item currently has the focus.
java.lang.Boolean	getSelectOnClick() Allows the selectOnClick behavior to be configured on a per-FormItem basis.
java.lang.Boolean	getSelectOnFocus() Allows the selectOnFocus behavior to be configured on a per-FormItem basis.
java.lang.Boolean	getShowHintInField() If showing a hint for this form item, should the hint be shown within the field?
boolean	getShowInputElement() When set to false, prevents this item's input element from being written into the DOM.
boolean	getSupportsCutPasteEvents() Does the current formItem support native cut and paste events?
java.lang.Boolean	getSuppressBrowserClearIcon() This attribute currently only has an effect in Internet Explorer.
java.lang.String	getTextBoxStyle() Base CSS class name for this item's input element.
boolean	getUsePlaceholderForHint() If showing the hint in field and if supported by the browser, should the HTML5 placeholder attribute be used to display the hint within the field? If set to false, then use of the placeholder attribute is disabled and an alternative technique to display the hint in-field is used instead.
java.lang.String	getValueAsString() Return the value tracked by this form item.
boolean	pendingStatusChanged(DynamicForm form, FormItem item, boolean pendingStatus, java.lang.Object newValue, java.lang.Object value) Notification method called when showPending is enabled and this text item should either clear or show its pending visual state.
void	selectValue() Put focus in this item and select the entire value.
TextItem	setBrowserAutoCapitalize(java.lang.Boolean browserAutoCapitalize) Note : This is an advanced setting
TextItem	setBrowserAutoCorrect(java.lang.Boolean browserAutoCorrect) In Mobile Safari, should automatic correction be offered for text in the item's text box? If null, then Mobile Safari determines automatically whether to enable autocorrect.
TextItem	setBrowserInputType(java.lang.String browserInputType) This property corresponds to the HTML5 "inputType" attribute applied to the <input> element for this TextItem.
TextItem	setChangeOnKeypress(java.lang.Boolean changeOnKeypress) Should this form item fire its change handler (and store its value in the form) on every keypress? Set to false to suppress the 'change' handler firing (and the value stored) on every keypress.
TextItem	setCharacterCasing(CharacterCasing characterCasing) Should entered characters be converted to upper or lowercase? Also applies to values applied with FormItem.setValue().
static void	setDefaultProperties(TextItem textItemProperties) Class level method to set the default properties of this class.
TextItem	setEditProxyConstructor(java.lang.String editProxyConstructor) Default class used to construct the EditProxy for this component when the component is first placed into edit mode.
TextItem	setEnforceLength(boolean enforceLength) If a length is specified for this item, should user input be limited to the specified length? If set to true, user input and values passed to setValue() will be trimmed to the specified length.
TextItem	setEscapeHTML(java.lang.Boolean escapeHTML) By default HTML characters will be escaped when canEdit is false and readOnlyDisplay is "static", so that the raw value of the field (for example "<b>AAA</b>") is displayed to the user rather than the interpreted HTML (for example "AAA").
TextItem	setFetchMissingValues(java.lang.Boolean fetchMissingValues) If this form item has a specified FormItem.optionDataSource, should the item ever perform a fetch against this dataSource to retrieve the related record.
TextItem	setFormatOnBlur(java.lang.Boolean formatOnBlur) With formatOnBlur enabled, this textItem will format its value according to the rules described in FormItem.mapValueToDisplay() as long as the item does not have focus.
TextItem	setFormatOnFocusChange(java.lang.Boolean formatOnFocusChange) Should FormItem.formatEditorValue() re-run whenever this item recieves or loses focus? Setting this property allows developers to conditionally format the display value based on item.hasFocus, typically to display a longer, more informative string while the item does not have focus, and simplifying it down to an easier-to-edit string when the user puts focus into the item.
TextItem	setKeyPressFilter(java.lang.String keyPressFilter) Sets a keypress filter regular expression to limit valid characters that can be entered by the user.
TextItem	setLength(java.lang.Integer length) If set, the maximum number of characters for this field.
TextItem	setMask(java.lang.String mask) Input mask used to restrict and format text within this item.
TextItem	setMaskOverwriteMode(java.lang.Boolean maskOverwriteMode) During entry into a masked field, should keystrokes overwrite current position value? By default new keystrokes are inserted into the field.
TextItem	setMaskPadChar(java.lang.String maskPadChar) Character that is used to fill required empty mask positions to display text while control has no focus.
TextItem	setMaskPromptChar(java.lang.String maskPromptChar) Character that is used to fill required empty mask positions to display text while control has focus.
TextItem	setMaskSaveLiterals(java.lang.Boolean maskSaveLiterals) Should entered mask value be saved with embedded literals?
void	setPastedValueTransformer(PastedValueTransformer customizer) Notification fired in response to a clipboard "paste" event on freeform text items, giving developers an opportunity to reformat the pasted text.
TextItem	setPrintFullText(java.lang.Boolean printFullText) When generating a print-view of the component containing this TextItem, should the form item expand to accommodate its value? If set to false the text box will not expand to fit its content in the print view, instead showing exactly as it does in the live form.
TextItem	setSaveOnEnter(java.lang.Boolean saveOnEnter) Text items will submit their containing form on enter keypress if saveOnEnter is true.
void	setSelectionRange(int start, int end) Puts focus into this form item and selects characters between the given indices.
TextItem	setSelectOnClick(java.lang.Boolean selectOnClick) Allows the selectOnClick behavior to be configured on a per-FormItem basis.
TextItem	setSelectOnFocus(java.lang.Boolean selectOnFocus) Allows the selectOnFocus behavior to be configured on a per-FormItem basis.
TextItem	setShowHintInField(java.lang.Boolean showHintInField) If showing a hint for this form item, should the hint be shown within the field?
TextItem	setShowInputElement(boolean showInputElement) When set to false, prevents this item's input element from being written into the DOM.
TextItem	setSupportsCutPasteEvents(boolean supportsCutPasteEvents) Does the current formItem support native cut and paste events?
TextItem	setSuppressBrowserClearIcon(java.lang.Boolean suppressBrowserClearIcon) This attribute currently only has an effect in Internet Explorer.
TextItem	setTextBoxStyle(java.lang.String textBoxStyle) Base CSS class name for this item's input element.
TextItem	setUsePlaceholderForHint(boolean usePlaceholderForHint) If showing the hint in field and if supported by the browser, should the HTML5 placeholder attribute be used to display the hint within the field? If set to false, then use of the placeholder attribute is disabled and an alternative technique to display the hint in-field is used instead.
java.lang.Boolean	shouldFetchMissingValue(java.lang.Object newValue) If this field has a specified optionDataSource, should we perform a fetch against that dataSource to find the record that matches this field's value?

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

_getValue, addBlurHandler, addChangedHandler, addChangeHandler, addClickHandler, addDoubleClickHandler, addEditorEnterHandler, addEditorExitHandler, addFocusHandler, addIcon, addIcon, addIconClickHandler, addIconKeyPressHandler, addItemHoverHandler, addKeyDownHandler, addKeyPressHandler, addKeyUpHandler, addPendingStatusChangedHandler, addPickerIconClickHandler, addShowContextMenuHandler, addTitleClickHandler, addTitleDoubleClickHandler, addTitleHoverHandler, addValueHoverHandler, addValueIconClickHandler, applyFormula, asSGWTComponent, blurItem, canEditCriterion, clearErrors, clearValue, disable, disableIcon, enable, enableIcon, error, error, errorIfNotCreated, focusAfterItem, focusInItem, getAccessKey, getAlign, getAllowExpressions, getAlwaysFetchMissingValues, getAlwaysShowControlBox, getApplyAlignToText, getApplyHeightToTextBox, getAriaRole, getAttribute, getAttributeAsBoolean, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsObject, getAttributeAsString, getAutoComplete, getAutoCompleteKeywords, getBrowserSpellCheck, getCanEdit, getCanEditOpaqueValues, getCanFocus, getCanSelectText, getCanTabToIcons, getCanvasAutoChild, getCellHeight, getCellStyle, getClassName, getClipStaticValue, getClipTitle, getConfig, getContainerWidget, getControlStyle, getCriteriaField, getCriterion, getCriterion, getCursorPosition, getCustomState, getDataPath, getDateFormatter, getDecimalPad, getDecimalPrecision, getDefaultIconSrc, getDefaultOperator, getDestroyed, getDisabled, getDisabledHover, getDisableIconsOnReadOnly, getDisplayField, getDisplayFieldName, getDisplayValue, getDisplayValue, getEditorTypeConfig, getEditPendingCSSText, getEmptyDisplayValue, getEmptyValueIcon, getEndRow, getErrorIconHeight, getErrorIconSrc, getErrorIconWidth, getErrorMessageWidth, getErrors, getExportFormat, getFieldName, getFilterLocally, getForeignDisplayField, getForm, getFormat, getFormItemAutoChild, getFormula, getFullDataPath, getGlobalTabIndex, getGridColNum, getGridRowNum, getHeight, getHeightAsString, getHidden, getHintStyle, getHoverAlign, getHoverDelay, getHoverFocusKey, getHoverHeight, getHoverHeightAsString, getHoverOpacity, getHoverPersist, getHoverStyle, getHoverVAlign, getHoverWidth, getHoverWidthAsString, getIcon, getIconHeight, getIconHSpace, getIconPageRect, getIconPrompt, getIconRect, getIcons, getIconTabPosition, getIconVAlign, getIconWidth, getID, getImageURLPrefix, getImageURLSuffix, getImplicitSave, getImplicitSaveOnBlur, getInputFormat, getLeft, getLinearColSpan, getLinearColSpanAsString, getLinearEndRow, getLinearEndRowAsString, getLinearStartRow, getLinearStartRowAsString, getLinearWidth, getLinearWidthAsString, getListGrid, getLoadingDisplayValue, getLocateItemBy, getMinHintWidth, getMultiple, getMultipleValueSeparator, getName, getNullOriginalValueText, getOperator, getOptionCriteria, getOptionDataSource, getOptionDataSourceAsString, getOptionFilterContext, getOptionOperationId, getOptionTextMatchStyle, getOriginalValueMessage, getPageLeft, getPageRect, getPageTop, getPaletteDefaults, getPicker, getPickerIcon, getPickerIcon, getPickerIconHeight, getPickerIconName, getPickerIconPrompt, getPickerIconProperties, getPickerIconSrc, getPickerIconStyle, getPickerIconTabPosition, getPickerIconWidth, getPixelHeight, getPixelWidth, getPrintReadOnlyTextBoxStyle, getPrintTextBoxStyle, getPrintTitleStyle, getPrompt, getReadOnlyCanSelectText, getReadOnlyControlStyle, getReadOnlyDisplay, getReadOnlyHover, getReadOnlyTextBoxStyle, getReadOnlyWhen, getRect, getRedrawOnChange, getRejectInvalidValueOnChange, getRequired, getRequiredMessage, getRequiredWhen, getRowSpan, getScClassName, getSelectedRecord, getShouldSaveValue, getShowClippedTitleOnHover, getShowClippedValueOnHover, getShowDeletions, getShowDisabled, getShowDisabledIconsOnFocus, getShowDisabledPickerIconOnFocus, getShowErrorIcon, getShowErrorStyle, getShowErrorText, getShowFocused, getShowFocusedErrorState, getShowFocusedIcons, getShowFocusedPickerIcon, getShowHint, getShowIcons, getShowIconsOnFocus, getShowImageAsURL, getShowOldValueInHover, getShowOver, getShowOverIcons, getShowPending, getShowPickerIcon, getShowPickerIconOnFocus, getShowRTL, getShowTitle, getShowValueIconOnly, getStartRow, getStaticHeight, getStopOnError, getStoreDisplayValues, getSuppressValueIcon, getSynchronousValidation, getTabIndex, getTextAlign, getTextFormula, getTimeFormatter, getTitle, getTitleAlign, getTitleColSpan, getTitleOrientation, getTitleStyle, getTitleVAlign, getTooltip, getTop, getType, getUpdateControlOnOver, getUpdatePickerIconOnOver, getUpdateTextBoxOnOver, getUseAdvancedCriteria, getUseDisabledHintStyleForReadOnly, getUseLocalDisplayFieldValue, getValidateOnChange, getValidateOnExit, getValidOperators, getVAlign, getValue, getValueAsFloat, getValueAsInteger, getValueAsLong, getValueAsRecordList, getValueDeselectedCSSText, getValueField, getValueFieldName, getValueIconHeight, getValueIconLeftPadding, getValueIconRightPadding, getValueIconSize, getValueIconWidth, getValueMap, getValueMapAsArray, getVisible, getVisibleHeight, getVisibleTitleWidth, getVisibleWhen, getVisibleWidth, getWarnOnEditorTypeConversion, getWarnOnEditorTypeConversionDefault, getWidth, getWidthAsString, getWrapHintText, getWrapStaticValue, getWrapTitle, handleWarnOnEditorTypeConversion, hasAdvancedCriteria, hasErrors, hide, hideIcon, invalidateDisplayValueCache, isConfigOnly, isCreated, isCutEvent, isDisabled, isDrawn, isFocused, isInGrid, isPasteEvent, isVisible, linkToInstanceUponCreate, mapDisplayToValue, mapValueToDisplay, mapValueToDisplay, mapValueToDisplay, redraw, redraw, removeIcon, selectedRecordChanged, setAccessKey, setAlign, setAllowExpressions, setAlwaysFetchMissingValues, setAlwaysShowControlBox, setApplyAlignToText, setApplyHeightToTextBox, setAriaRole, setAriaState, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAutoChildConstructor, setAutoChildProperties, setAutoChildProperties, setAutoChildProperties, setAutoChildVisibility, setAutoComplete, setAutoCompleteKeywords, setBrowserSpellCheck, setCanEdit, setCanEditCriterionPredicate, setCanEditOpaqueValues, setCanFocus, setCanSelectText, setCanTabToIcons, setCellHeight, setCellStyle, setClipStaticValue, setClipTitle, setColSpan, setColSpan, setConfigOnly, setControlStyle, setCriteriaField, setCriterion, setCriterionGetter, setCriterionSetter, setCustomStateGetter, setDataPath, setDateFormatter, setDecimalPad, setDecimalPrecision, setDefaultIconSrc, setDefaultOperator, setDefaultProperties, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDisabled, setDisabledHover, setDisableIconsOnReadOnly, setDisplayField, setDisplayFormat, setDisplayFormat, setEditorProperties, setEditorType, setEditorType, setEditorType, setEditorValueFormatter, setEditorValueParser, setEditPendingCSSText, setEmptyDisplayValue, setEmptyValueIcon, setEndRow, setErrorFormatter, setErrorIconHeight, setErrorIconSrc, setErrorIconWidth, setErrorMessageWidth, setErrorOrientation, setErrors, setErrors, setExportFormat, setFilterLocally, setForeignDisplayField, setFormat, setFormula, setGlobalTabIndex, setHeight, setHeight, setHidden, setHint, setHintStyle, setHoverAlign, setHoverDelay, setHoverFocusKey, setHoverHeight, setHoverHeight, setHoverOpacity, setHoverPersist, setHoverStyle, setHoverVAlign, setHoverWidth, setHoverWidth, setIconDisabled, setIconHeight, setIconHSpace, setIconPrompt, setIcons, setIconShowOnFocus, setIconVAlign, setIconWidth, setID, setImageURLPrefix, setImageURLSuffix, setImplicitSave, setImplicitSaveOnBlur, setInitHandler, setInputFormat, setInputTransformer, setItemHoverFormatter, setItemTitleHoverFormatter, setItemValueHoverFormatter, setJavaScriptObject, setLeft, setLinearColSpan, setLinearColSpan, setLinearEndRow, setLinearEndRow, setLinearStartRow, setLinearStartRow, setLinearWidth, setLinearWidth, setLoadingDisplayValue, setLocateItemBy, setMinHintWidth, setMultiple, setMultipleValueSeparator, setName, setNullOriginalValueText, setNullProperty, setOperator, setOptionCriteria, setOptionDataSource, setOptionDataSource, setOptionFilterContext, setOptionOperationId, setOptionTextMatchStyle, setOriginalValueMessage, setPickerIconHeight, setPickerIconName, setPickerIconPrompt, setPickerIconProperties, setPickerIconSrc, setPickerIconStyle, setPickerIconWidth, setPrintReadOnlyTextBoxStyle, setPrintTextBoxStyle, setPrintTitleStyle, setPrompt, setProperty, setProperty, setProperty, setProperty, setProperty, setReadOnlyCanSelectText, setReadOnlyControlStyle, setReadOnlyDisplay, setReadOnlyHover, setReadOnlyTextBoxStyle, setReadOnlyWhen, setRedrawOnChange, setRejectInvalidValueOnChange, setRequired, setRequiredMessage, setRequiredWhen, setRowSpan, setScClassName, setShouldSaveValue, setShowClippedTitleOnHover, setShowClippedValueOnHover, setShowDeletions, setShowDisabled, setShowDisabledIconsOnFocus, setShowDisabledPickerIconOnFocus, setShowErrorIcon, setShowErrorStyle, setShowErrorText, setShowFocused, setShowFocusedErrorState, setShowFocusedIcons, setShowFocusedPickerIcon, setShowHint, setShowIcons, setShowIconsOnFocus, setShowIfCondition, setShowImageAsURL, setShowOldValueInHover, setShowOver, setShowOverIcons, setShowPending, setShowPickerIcon, setShowPickerIconOnFocus, setShowRTL, setShowTitle, setShowValueIconOnly, setStartRow, setStateCustomizer, setStaticHeight, setStopOnError, setStoreDisplayValues, setSuppressValueIcon, setSynchronousValidation, setTabIndex, setTextAlign, setTextFormula, setTimeFormatter, setTitle, setTitleAlign, setTitleColSpan, setTitleHoverFormatter, setTitleOrientation, setTitleStyle, setTitleVAlign, setTooltip, setTop, setType, setUpdateControlOnOver, setUpdatePickerIconOnOver, setUpdateTextBoxOnOver, setUseAdvancedCriteria, setUseDisabledHintStyleForReadOnly, setUseLocalDisplayFieldValue, setValidateOnChange, setValidateOnExit, setValidators, setValidOperators, setVAlign, setValue, setValue, setValue, setValue, setValue, setValue, setValueDeselectedCSSText, setValueField, setValueFormatter, setValueHoverFormatter, setValueIconHeight, setValueIconLeftPadding, setValueIconMapper, setValueIconRightPadding, setValueIcons, setValueIconSize, setValueIconWidth, setValueMap, setValueMap, setVisible, setVisibleWhen, setWarnOnEditorTypeConversion, setWarnOnEditorTypeConversionDefault, setWidth, setWidth, setWrapHintText, setWrapStaticValue, setWrapTitle, shouldApplyHeightToTextBox, shouldSaveOnEnter, shouldStopKeyPressBubbling, show, showIcon, showPicker, stopHover, storeValue, storeValue, updateState, validate, valueClipped

Methods inherited from class com.smartgwt.client.core.RefDataClass

getRef, getRef, internalSetID

Methods inherited from class com.smartgwt.client.core.DataClass

applyFactoryProperties, doAddHandler, fireEvent, getAttributeAsDoubleArray, getAttributeAsElement, getAttributeAsIntArray, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsStringArray, getAttributes, getHandlerCount, isFactoryCreated, setAttribute, setAttribute, setAttribute, setAttributeAsJavaObject, setFactoryCreated

Methods inherited from class com.smartgwt.client.core.JsObject

equals, getJsObj, hashCode, setJsObj

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.google.gwt.event.shared.HasHandlers

fireEvent

Constructor Detail

TextItem

public TextItem()

TextItem

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

TextItem

public TextItem(java.lang.String name)

TextItem

public TextItem(java.lang.String name,
                java.lang.String title)

Method Detail

getOrCreateRef

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

changeAutoChildDefaults

public static void changeAutoChildDefaults(java.lang.String autoChildName,
                                           Canvas defaults)

Changes the defaults for Canvas AutoChildren named autoChildName.

Parameters:

autoChildName - name of an AutoChild to customize the defaults for.

defaults - Canvas defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.

See Also:

AutoChildUsage

changeAutoChildDefaults

public static void changeAutoChildDefaults(java.lang.String autoChildName,
                                           FormItem defaults)

Changes the defaults for FormItem AutoChildren named autoChildName.

Parameters:

autoChildName - name of an AutoChild to customize the defaults for.

defaults - FormItem defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.

See Also:

AutoChildUsage

changePickerIconDefaults

public static void changePickerIconDefaults(FormItemIcon defaults)

setBrowserAutoCapitalize

public TextItem setBrowserAutoCapitalize(java.lang.Boolean browserAutoCapitalize)

Note : This is an advanced setting

Parameters:

browserAutoCapitalize - New browserAutoCapitalize value. Default value is null

Returns:

TextItem instance, for chaining setter calls

getBrowserAutoCapitalize

public java.lang.Boolean getBrowserAutoCapitalize()

Returns:

Current browserAutoCapitalize value. Default value is null

setBrowserAutoCorrect

public TextItem setBrowserAutoCorrect(java.lang.Boolean browserAutoCorrect)

In Mobile Safari, should automatic correction be offered for text in the item's text box? If null, then Mobile Safari determines automatically whether to enable autocorrect.

When enabled, Mobile Safari displays "autocorrect bubbles" to suggest automatic corrections:

Note : This is an advanced setting

Parameters:

browserAutoCorrect - New browserAutoCorrect value. Default value is null

Returns:

TextItem instance, for chaining setter calls

getBrowserAutoCorrect

public java.lang.Boolean getBrowserAutoCorrect()

In Mobile Safari, should automatic correction be offered for text in the item's text box? If null, then Mobile Safari determines automatically whether to enable autocorrect.

When enabled, Mobile Safari displays "autocorrect bubbles" to suggest automatic corrections:

Returns:

Current browserAutoCorrect value. Default value is null

setBrowserInputType

public TextItem setBrowserInputType(java.lang.String browserInputType)

This property corresponds to the HTML5 "inputType" attribute applied to the <input> element for this TextItem.

The only currently supported use of this attribute is hinting to touch-enabled mobile devices that a particular keyboard layout should be used. Even here, be careful; to take a random example, using type "number" on Android up to at least 3.2 leads to a keyboard with no "-" key, so negative numbers cannot be entered.

Valid values:

"text"	Normal text keyboard
"digits"	Makes the text field more suitable for entering a string of digits 0 - 9. On iOS, this causes the virtual keyboard to show a numeric keypad with only "0", "1", "2", ..., "9", and delete keys.
"email"	Makes the text field more suitable for entering an e-mail address. On iOS, this causes the virtual keyboard to show special "@" and "." keys on the alphabetic keys screen.
"tel"	Makes the text field more suitable for entering a telephone number. On iOS, this causes the virtual keyboard to show a numeric keypad with a "+*#" key for displaying punctuation keys.
"number"	Makes the text field more suitable for entering a floating-point value. On iOS, this causes the virtual keyboard to start on the number and punctuation keys screen. NOTE: This is not an appropriate text input type for credit card numbers, postal codes, ISBNs, and other formats that are not strictly parsable as floating-point numbers. This is because the browser is required to perform floating-point value sanitization to ensure that the value is a valid floating-point number.
"url"	Makes the text field more suitable for entering a URL. On iOS, this causes the virtual keyboard to show a special ".com" key.
Any vendor- specific value	If a browser supports another input type.

Note : This is an advanced setting

Overrides:

setBrowserInputType in class FormItem

Parameters:

browserInputType - New browserInputType value. Default value is null

Returns:

TextItem instance, for chaining setter calls

getBrowserInputType

public java.lang.String getBrowserInputType()

This property corresponds to the HTML5 "inputType" attribute applied to the <input> element for this TextItem.

The only currently supported use of this attribute is hinting to touch-enabled mobile devices that a particular keyboard layout should be used. Even here, be careful; to take a random example, using type "number" on Android up to at least 3.2 leads to a keyboard with no "-" key, so negative numbers cannot be entered.

Valid values:

"text"	Normal text keyboard
"digits"	Makes the text field more suitable for entering a string of digits 0 - 9. On iOS, this causes the virtual keyboard to show a numeric keypad with only "0", "1", "2", ..., "9", and delete keys.
"email"	Makes the text field more suitable for entering an e-mail address. On iOS, this causes the virtual keyboard to show special "@" and "." keys on the alphabetic keys screen.
"tel"	Makes the text field more suitable for entering a telephone number. On iOS, this causes the virtual keyboard to show a numeric keypad with a "+*#" key for displaying punctuation keys.
"number"	Makes the text field more suitable for entering a floating-point value. On iOS, this causes the virtual keyboard to start on the number and punctuation keys screen. NOTE: This is not an appropriate text input type for credit card numbers, postal codes, ISBNs, and other formats that are not strictly parsable as floating-point numbers. This is because the browser is required to perform floating-point value sanitization to ensure that the value is a valid floating-point number.
"url"	Makes the text field more suitable for entering a URL. On iOS, this causes the virtual keyboard to show a special ".com" key.
Any vendor- specific value	If a browser supports another input type.

Overrides:

getBrowserInputType in class FormItem

Returns:

Current browserInputType value. Default value is null

setChangeOnKeypress

public TextItem setChangeOnKeypress(java.lang.Boolean changeOnKeypress)

Should this form item fire its change handler (and store its value in the form) on every keypress? Set to false to suppress the 'change' handler firing (and the value stored) on every keypress.

Note: If false, the value returned by getValue will not reflect the value displayed in the form item element as long as focus is in the form item element.

Overrides:

setChangeOnKeypress in class FormItem

Parameters:

changeOnKeypress - New changeOnKeypress value. Default value is true

Returns:

TextItem instance, for chaining setter calls

getChangeOnKeypress

public java.lang.Boolean getChangeOnKeypress()

Should this form item fire its change handler (and store its value in the form) on every keypress? Set to false to suppress the 'change' handler firing (and the value stored) on every keypress.

Note: If false, the value returned by getValue will not reflect the value displayed in the form item element as long as focus is in the form item element.

Overrides:

getChangeOnKeypress in class FormItem

Returns:

Current changeOnKeypress value. Default value is true

setCharacterCasing

public TextItem setCharacterCasing(CharacterCasing characterCasing)

Should entered characters be converted to upper or lowercase? Also applies to values applied with FormItem.setValue().

Note: character casing cannot be used at the same time as a mask.

Note : This is an advanced setting

Parameters:

characterCasing - New characterCasing value. Default value is TextItem.DEFAULT

Returns:

TextItem instance, for chaining setter calls

See Also:

KeyPress Filters Example

getCharacterCasing

public CharacterCasing getCharacterCasing()

Should entered characters be converted to upper or lowercase? Also applies to values applied with FormItem.setValue().

Note: character casing cannot be used at the same time as a mask.

Returns:

Current characterCasing value. Default value is TextItem.DEFAULT

See Also:

KeyPress Filters Example

setEditProxyConstructor

public TextItem setEditProxyConstructor(java.lang.String editProxyConstructor)

Default class used to construct the EditProxy for this component when the component is first placed into edit mode.

Overrides:

setEditProxyConstructor in class FormItem

Parameters:

editProxyConstructor - New editProxyConstructor value. Default value is "TextItemEditProxy"

Returns:

TextItem instance, for chaining setter calls

See Also:

SCClassName

getEditProxyConstructor

public java.lang.String getEditProxyConstructor()

Default class used to construct the EditProxy for this component when the component is first placed into edit mode.

Overrides:

getEditProxyConstructor in class FormItem

Returns:

Current editProxyConstructor value. Default value is "TextItemEditProxy"

See Also:

SCClassName

setEnforceLength

public TextItem setEnforceLength(boolean enforceLength)

If a length is specified for this item, should user input be limited to the specified length? If set to true, user input and values passed to setValue() will be trimmed to the specified length. Otherwise values exceeding the specified length will raise an error on validation.

Note that having this value set to true limits user interactivity in some ways. For example users would be unable to paste a longer string into the field for editing without seeing it be truncated.

Parameters:

enforceLength - New enforceLength value. Default value is true

Returns:

TextItem instance, for chaining setter calls

getEnforceLength

public boolean getEnforceLength()

If a length is specified for this item, should user input be limited to the specified length? If set to true, user input and values passed to setValue() will be trimmed to the specified length. Otherwise values exceeding the specified length will raise an error on validation.

Note that having this value set to true limits user interactivity in some ways. For example users would be unable to paste a longer string into the field for editing without seeing it be truncated.

Returns:

Current enforceLength value. Default value is true

setEscapeHTML

public TextItem setEscapeHTML(java.lang.Boolean escapeHTML)

By default HTML characters will be escaped when canEdit is false and readOnlyDisplay is "static", so that the raw value of the field (for example "<b>AAA</b>") is displayed to the user rather than the interpreted HTML (for example "AAA"). Setting escapeHTML false will instead force HTML values in a textItem to be interpreted by the browser in that situation.

Overrides:

setEscapeHTML in class FormItem

Parameters:

escapeHTML - New escapeHTML value. Default value is true

Returns:

TextItem instance, for chaining setter calls

See Also:

Appearance overview and related methods

getEscapeHTML

public java.lang.Boolean getEscapeHTML()

By default HTML characters will be escaped when canEdit is false and readOnlyDisplay is "static", so that the raw value of the field (for example "<b>AAA</b>") is displayed to the user rather than the interpreted HTML (for example "AAA"). Setting escapeHTML false will instead force HTML values in a textItem to be interpreted by the browser in that situation.

Overrides:

getEscapeHTML in class FormItem

Returns:

Current escapeHTML value. Default value is true

See Also:

Appearance overview and related methods

setFetchMissingValues

public TextItem setFetchMissingValues(java.lang.Boolean fetchMissingValues)

If this form item has a specified FormItem.optionDataSource, should the item ever perform a fetch against this dataSource to retrieve the related record.

Note that for editable textItems, behavior differs slightly than for other item types as we will not issue fetches unless FormItem.alwaysFetchMissingValues has been set to true. See shouldFetchMissingValue() for more details.

Note : This is an advanced setting

Overrides:

setFetchMissingValues in class FormItem

Parameters:

fetchMissingValues - New fetchMissingValues value. Default value is true

Returns:

TextItem instance, for chaining setter calls

See Also:

FormItem.setOptionDataSource(com.smartgwt.client.data.DataSource), FormItem.getSelectedRecord(), FormItem.setFilterLocally(java.lang.Boolean)

getFetchMissingValues

public java.lang.Boolean getFetchMissingValues()

If this form item has a specified FormItem.optionDataSource, should the item ever perform a fetch against this dataSource to retrieve the related record.

Note that for editable textItems, behavior differs slightly than for other item types as we will not issue fetches unless FormItem.alwaysFetchMissingValues has been set to true. See shouldFetchMissingValue() for more details.

Overrides:

getFetchMissingValues in class FormItem

Returns:

Current fetchMissingValues value. Default value is true

See Also:

FormItem.getOptionDataSource(), FormItem.getSelectedRecord(), FormItem.getFilterLocally()

setFormatOnBlur

public TextItem setFormatOnBlur(java.lang.Boolean formatOnBlur)

With formatOnBlur enabled, this textItem will format its value according to the rules described in FormItem.mapValueToDisplay() as long as the item does not have focus. Once the user puts focus into the item the formatter will be removed. This provides a simple way for developers to show a nicely formatted display value in a freeform text field, without the need for an explicit FormItem.formatEditorValue() and FormItem.parseEditorValue() pair.

Parameters:

formatOnBlur - New formatOnBlur value. Default value is false

Returns:

TextItem instance, for chaining setter calls

getFormatOnBlur

public java.lang.Boolean getFormatOnBlur()

With formatOnBlur enabled, this textItem will format its value according to the rules described in FormItem.mapValueToDisplay() as long as the item does not have focus. Once the user puts focus into the item the formatter will be removed. This provides a simple way for developers to show a nicely formatted display value in a freeform text field, without the need for an explicit FormItem.formatEditorValue() and FormItem.parseEditorValue() pair.

Returns:

Current formatOnBlur value. Default value is false

setFormatOnFocusChange

public TextItem setFormatOnFocusChange(java.lang.Boolean formatOnFocusChange)

Should FormItem.formatEditorValue() re-run whenever this item recieves or loses focus? Setting this property allows developers to conditionally format the display value based on item.hasFocus, typically to display a longer, more informative string while the item does not have focus, and simplifying it down to an easier-to-edit string when the user puts focus into the item.

Parameters:

formatOnFocusChange - New formatOnFocusChange value. Default value is false

Returns:

TextItem instance, for chaining setter calls

getFormatOnFocusChange

public java.lang.Boolean getFormatOnFocusChange()

Should FormItem.formatEditorValue() re-run whenever this item recieves or loses focus? Setting this property allows developers to conditionally format the display value based on item.hasFocus, typically to display a longer, more informative string while the item does not have focus, and simplifying it down to an easier-to-edit string when the user puts focus into the item.

Returns:

Current formatOnFocusChange value. Default value is false

setKeyPressFilter

public TextItem setKeyPressFilter(java.lang.String keyPressFilter)

Sets a keypress filter regular expression to limit valid characters that can be entered by the user. If defined, keys that match the regular expression are allowed; all others are suppressed. The filter is applied after character casing, if defined.

Note: keypress filtering cannot be used at the same time as a mask.

If this method is called after the component has been drawn/initialized: Set the keyPressFilter for this item

Note : This is an advanced setting

Parameters:

keyPressFilter - new keyPress filter for the item. Default value is null

Returns:

TextItem instance, for chaining setter calls

See Also:

setCharacterCasing(com.smartgwt.client.types.CharacterCasing), KeyPress Filters Example

getKeyPressFilter

public java.lang.String getKeyPressFilter()

Sets a keypress filter regular expression to limit valid characters that can be entered by the user. If defined, keys that match the regular expression are allowed; all others are suppressed. The filter is applied after character casing, if defined.

Note: keypress filtering cannot be used at the same time as a mask.

Returns:

Current keyPressFilter value. Default value is null

See Also:

getCharacterCasing(), KeyPress Filters Example

setLength

public TextItem setLength(java.lang.Integer length)

If set, the maximum number of characters for this field. If enforceLength is set to true, user input will be limited to this value, and values exceeding this length passed to setValue() will be trimmed. Otherwise values exceeding the specified length will raise an error on validation.

If the item has a numeric type, like integer or float, length is applied to the raw number value, after any specified decimalPrecision and decimalPad but before any formatters - this means the string measured includes sign and decimal placeholder, and padded decimal places as required, but not thousands separators or any custom formatting.

See also DataSourceField.length.

Parameters:

length - New length value. Default value is null

Returns:

TextItem instance, for chaining setter calls

See Also:

Validation overview and related methods

getLength

public java.lang.Integer getLength()

If set, the maximum number of characters for this field. If enforceLength is set to true, user input will be limited to this value, and values exceeding this length passed to setValue() will be trimmed. Otherwise values exceeding the specified length will raise an error on validation.

If the item has a numeric type, like integer or float, length is applied to the raw number value, after any specified decimalPrecision and decimalPad but before any formatters - this means the string measured includes sign and decimal placeholder, and padded decimal places as required, but not thousands separators or any custom formatting.

See also DataSourceField.length.

Returns:

Current length value. Default value is null

See Also:

Validation overview and related methods

setMask

public TextItem setMask(java.lang.String mask)

Input mask used to restrict and format text within this item.

Overview of available mask characters

Character	Description
0	Digit (0 through 9) or plus [+] or minus [-] signs
9	Digit or space
#	Digit
L	Letter (A through Z)
?	Letter (A through Z) or space
A	Letter or digit
a	Letter or digit
C	Any character or space
<	Causes all characters that follow to be converted to lowercase
>	Causes all characters that follow to be converted to uppercase
[ ... ]	Square brakets denote the start and end of a custom regular expression character set or range.

The mask can also contain literals - arbitrary non editable characters to be displayed as part of the formatted text. Any character not matching one of the above mask characters will be considered a literal. To use one of the mask characters as a literal, it must be escaped with a pair of backslashes (\\). By default literals are formatting characters only and will not be saved as part of the item's value. This behavior is controlled via maskSaveLiterals.

When a TextItem with a mask has focus, the formatted mask string will be displayed, with the maskPromptChar displayed as a placeholder for characters that have not yet been entered.
As the user types in the field, input will be restricted to the appropriate character class for each character, with uppercase/lowercase conversion occurring automatically. When focus is moved away from the field, the displayed value will be formatted to include any literals in the appropriate places.

Sample masks:

• Phone number: (###) ###-####
• Social Security number: ###-##-####
• First name: >?<??????????
• Date: ##/##/####
• State: >LL

Custom mask characters can be defined by standard regular expression character set or range. For example, a hexadecimal color code mask could be:

• Color: \\#>[0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F]

Note: input mask cannot be used at the same time as a keyPressFilter. Also note that this property is not supported for ComboBoxItem or SpinnerItem, or for items with browserInputType set to "digits" or "number".

If this method is called after the component has been drawn/initialized: Set the mask for this item. Pass null to clear an existing mask.

Note that the current value of the field is cleared when changing the mask.

Note : This is an advanced setting

Parameters:

mask - mask to apply to text item. Default value is null

Returns:

TextItem instance, for chaining setter calls

See Also:

setKeyPressFilter(java.lang.String), Text - Masked Example

getMask

public java.lang.String getMask()

Input mask used to restrict and format text within this item.

Overview of available mask characters

Character	Description
0	Digit (0 through 9) or plus [+] or minus [-] signs
9	Digit or space
#	Digit
L	Letter (A through Z)
?	Letter (A through Z) or space
A	Letter or digit
a	Letter or digit
C	Any character or space
<	Causes all characters that follow to be converted to lowercase
>	Causes all characters that follow to be converted to uppercase
[ ... ]	Square brakets denote the start and end of a custom regular expression character set or range.

The mask can also contain literals - arbitrary non editable characters to be displayed as part of the formatted text. Any character not matching one of the above mask characters will be considered a literal. To use one of the mask characters as a literal, it must be escaped with a pair of backslashes (\\). By default literals are formatting characters only and will not be saved as part of the item's value. This behavior is controlled via maskSaveLiterals.

When a TextItem with a mask has focus, the formatted mask string will be displayed, with the maskPromptChar displayed as a placeholder for characters that have not yet been entered.
As the user types in the field, input will be restricted to the appropriate character class for each character, with uppercase/lowercase conversion occurring automatically. When focus is moved away from the field, the displayed value will be formatted to include any literals in the appropriate places.

Sample masks:

• Phone number: (###) ###-####
• Social Security number: ###-##-####
• First name: >?<??????????
• Date: ##/##/####
• State: >LL

Custom mask characters can be defined by standard regular expression character set or range. For example, a hexadecimal color code mask could be:

• Color: \\#>[0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F][0-9A-F]

Note: input mask cannot be used at the same time as a keyPressFilter. Also note that this property is not supported for ComboBoxItem or SpinnerItem, or for items with browserInputType set to "digits" or "number".

Returns:

Current mask value. Default value is null

See Also:

getKeyPressFilter(), Text - Masked Example

setMaskOverwriteMode

public TextItem setMaskOverwriteMode(java.lang.Boolean maskOverwriteMode)

During entry into a masked field, should keystrokes overwrite current position value? By default new keystrokes are inserted into the field.

Note : This is an advanced setting

Parameters:

maskOverwriteMode - New maskOverwriteMode value. Default value is null

Returns:

TextItem instance, for chaining setter calls

getMaskOverwriteMode

public java.lang.Boolean getMaskOverwriteMode()

During entry into a masked field, should keystrokes overwrite current position value? By default new keystrokes are inserted into the field.

Returns:

Current maskOverwriteMode value. Default value is null

setMaskPadChar

public TextItem setMaskPadChar(java.lang.String maskPadChar)

Character that is used to fill required empty mask positions to display text while control has no focus.

Note : This is an advanced setting

Parameters:

maskPadChar - New maskPadChar value. Default value is " "

Returns:

TextItem instance, for chaining setter calls

getMaskPadChar

public java.lang.String getMaskPadChar()

Character that is used to fill required empty mask positions to display text while control has no focus.

Returns:

Current maskPadChar value. Default value is " "

setMaskPromptChar

public TextItem setMaskPromptChar(java.lang.String maskPromptChar)

Character that is used to fill required empty mask positions to display text while control has focus.

Note : This is an advanced setting

Parameters:

maskPromptChar - New maskPromptChar value. Default value is "_"

Returns:

TextItem instance, for chaining setter calls

getMaskPromptChar

public java.lang.String getMaskPromptChar()

Character that is used to fill required empty mask positions to display text while control has focus.

Returns:

Current maskPromptChar value. Default value is "_"

setMaskSaveLiterals

public TextItem setMaskSaveLiterals(java.lang.Boolean maskSaveLiterals)

Should entered mask value be saved with embedded literals?

Note : This is an advanced setting

Parameters:

maskSaveLiterals - New maskSaveLiterals value. Default value is null

Returns:

TextItem instance, for chaining setter calls

getMaskSaveLiterals

public java.lang.Boolean getMaskSaveLiterals()

Should entered mask value be saved with embedded literals?

Returns:

Current maskSaveLiterals value. Default value is null

setPrintFullText

public TextItem setPrintFullText(java.lang.Boolean printFullText)

When generating a print-view of the component containing this TextItem, should the form item expand to accommodate its value? If set to false the text box will not expand to fit its content in the print view, instead showing exactly as it does in the live form.

Parameters:

printFullText - New printFullText value. Default value is false

Returns:

TextItem instance, for chaining setter calls

See Also:

Printing overview and related methods

getPrintFullText

public java.lang.Boolean getPrintFullText()

When generating a print-view of the component containing this TextItem, should the form item expand to accommodate its value? If set to false the text box will not expand to fit its content in the print view, instead showing exactly as it does in the live form.

Returns:

Current printFullText value. Default value is false

See Also:

Printing overview and related methods

setSaveOnEnter

public TextItem setSaveOnEnter(java.lang.Boolean saveOnEnter)

Text items will submit their containing form on enter keypress if saveOnEnter is true. Setting this property to false will disable this behavior.

Overrides:

setSaveOnEnter in class FormItem

Parameters:

saveOnEnter - New saveOnEnter value. Default value is true

Returns:

TextItem instance, for chaining setter calls

getSaveOnEnter

public java.lang.Boolean getSaveOnEnter()

Text items will submit their containing form on enter keypress if saveOnEnter is true. Setting this property to false will disable this behavior.

Overrides:

getSaveOnEnter in class FormItem

Returns:

Current saveOnEnter value. Default value is true

setSelectOnClick

public TextItem setSelectOnClick(java.lang.Boolean selectOnClick)

Allows the selectOnClick behavior to be configured on a per-FormItem basis. Normally all items in a form default to the value of DynamicForm.selectOnClick.

Overrides:

setSelectOnClick in class FormItem

Parameters:

selectOnClick - New selectOnClick value. Default value is null

Returns:

TextItem instance, for chaining setter calls

See Also:

Focus overview and related methods

getSelectOnClick

public java.lang.Boolean getSelectOnClick()

Allows the selectOnClick behavior to be configured on a per-FormItem basis. Normally all items in a form default to the value of DynamicForm.selectOnClick.

Overrides:

getSelectOnClick in class FormItem

Returns:

Current selectOnClick value. Default value is null

See Also:

Focus overview and related methods

setSelectOnFocus

public TextItem setSelectOnFocus(java.lang.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 DynamicForm.selectOnFocus.

Overrides:

setSelectOnFocus in class FormItem

Parameters:

selectOnFocus - New selectOnFocus value. Default value is null

Returns:

TextItem instance, for chaining setter calls

See Also:

Focus overview and related methods

getSelectOnFocus

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

Overrides:

getSelectOnFocus in class FormItem

Returns:

Current selectOnFocus value. Default value is null

See Also:

Focus overview and related methods

setShowHintInField

public TextItem setShowHintInField(java.lang.Boolean showHintInField)

If showing a hint for this form item, should the hint be shown within the field?

Unless the HTML5 placeholder attribute is used to display the hint (see usePlaceholderForHint), the value of the <input> element for this item will be set to the hint whenever this item is not focused. Also, when displaying the hint, the CSS style of the data element will be set to the textBoxStyle with the suffix "Hint" appended to it; or, if the item is disabled, the suffix "DisabledHint" will be used. In RTL mode when showRTL is true, an additional "RTL" suffix will be appended; i.e. the CSS style of the data element when the hint is displayed will be the textBoxStyle plus "HintRTL" or "DisabledHintRTL".

To change this attribute after being drawn, it is necessary to call FormItem.redraw() or redraw the form.

Styling the in-field hint

The in-field hint can be styled with CSS for the textBoxStyle + "Hint" / "HintRTL" / "DisabledHint" / "DisabledHintRTL" styles. For example, if this item's textBoxStyle is set to "mySpecialItem", then changing the hint color to blue can be accomplished with the following CSS:

.mySpecialItemHint,
 .mySpecialItemHintRTL,
 .mySpecialItemDisabledHint,
 .mySpecialItemDisabledHintRTL {
     color: blue;
 }

In DynamicForm.linearMode, this property will be defaulted true if left unset.

Parameters:

showHintInField - New showHintInField value. Default value is null

Returns:

TextItem instance, for chaining setter calls

See Also:

FormItem.setHint(java.lang.String), setUsePlaceholderForHint(boolean), Appearance overview and related methods

getShowHintInField

public java.lang.Boolean getShowHintInField()

If showing a hint for this form item, should the hint be shown within the field?

Unless the HTML5 placeholder attribute is used to display the hint (see usePlaceholderForHint), the value of the <input> element for this item will be set to the hint whenever this item is not focused. Also, when displaying the hint, the CSS style of the data element will be set to the textBoxStyle with the suffix "Hint" appended to it; or, if the item is disabled, the suffix "DisabledHint" will be used. In RTL mode when showRTL is true, an additional "RTL" suffix will be appended; i.e. the CSS style of the data element when the hint is displayed will be the textBoxStyle plus "HintRTL" or "DisabledHintRTL".

To change this attribute after being drawn, it is necessary to call FormItem.redraw() or redraw the form.

Styling the in-field hint

The in-field hint can be styled with CSS for the textBoxStyle + "Hint" / "HintRTL" / "DisabledHint" / "DisabledHintRTL" styles. For example, if this item's textBoxStyle is set to "mySpecialItem", then changing the hint color to blue can be accomplished with the following CSS:

.mySpecialItemHint,
 .mySpecialItemHintRTL,
 .mySpecialItemDisabledHint,
 .mySpecialItemDisabledHintRTL {
     color: blue;
 }

In DynamicForm.linearMode, this property will be defaulted true if left unset.

Returns:

Current showHintInField value. Default value is null

See Also:

FormItem.getHint(), getUsePlaceholderForHint(), Appearance overview and related methods

setShowInputElement

public TextItem setShowInputElement(boolean showInputElement)

When set to false, prevents this item's input element from being written into the DOM. If there are valueIcons or a picker icon, these are displayed as normal, and the item will auto-sizing to that content if its width is set to null.

Note : This is an advanced setting

Parameters:

showInputElement - New showInputElement value. Default value is true

Returns:

TextItem instance, for chaining setter calls

getShowInputElement

public boolean getShowInputElement()

When set to false, prevents this item's input element from being written into the DOM. If there are valueIcons or a picker icon, these are displayed as normal, and the item will auto-sizing to that content if its width is set to null.

Returns:

Current showInputElement value. Default value is true

setSupportsCutPasteEvents

public TextItem setSupportsCutPasteEvents(boolean supportsCutPasteEvents)

Does the current formItem support native cut and paste events?

This attribute only applies to freeform text entry fields such as TextItem and TextAreaItem, and only if changeOnKeypress is true. If true, developers can detect the user editing the value via cut or paste interactions (triggered from keyboard shortcuts or the native browser menu options) using the FormItem.isCutEvent() and FormItem.isPasteEvent() methods. This allows custom cut/paste handling to be added to the various change notification flow methods including FormItem.change(), and FormItem.transformInput().

Overrides:

setSupportsCutPasteEvents in class FormItem

Parameters:

supportsCutPasteEvents - New supportsCutPasteEvents value. Default value is true

Returns:

TextItem instance, for chaining setter calls

getSupportsCutPasteEvents

public boolean getSupportsCutPasteEvents()

Does the current formItem support native cut and paste events?

This attribute only applies to freeform text entry fields such as TextItem and TextAreaItem, and only if changeOnKeypress is true. If true, developers can detect the user editing the value via cut or paste interactions (triggered from keyboard shortcuts or the native browser menu options) using the FormItem.isCutEvent() and FormItem.isPasteEvent() methods. This allows custom cut/paste handling to be added to the various change notification flow methods including FormItem.change(), and FormItem.transformInput().

Overrides:

getSupportsCutPasteEvents in class FormItem

Returns:

Current supportsCutPasteEvents value. Default value is true

setSuppressBrowserClearIcon

public TextItem setSuppressBrowserClearIcon(java.lang.Boolean suppressBrowserClearIcon)

This attribute currently only has an effect in Internet Explorer. That browser will dynamically add a native "clear" icon to <input type="text" > elements when the user enters a value. Setting suppressBrowserClearIcon to true will write out HTML to suppress this icon. This can be particularly useful for items which define their own clear icon as in this sample.

If this property is not set at the item level, DynamicForm.suppressBrowserClearIcons will be used instead.

Note that as an alternative to using this feature, the icon may also be suppressed (or have other styling applied to it) directly via CSS, using the ::-ms-clear css pseudo-element (proprietary Internet Explorer feature).

Implementation note: This feature makes use of the automatically generated suppressClearIconClassName css class.

If this method is called after the component has been drawn/initialized: Setter for the suppressBrowserClearIcon

Parameters:

suppressBrowserClearIcon - new value for suppressBrowserClearIcon. Default value is null

Returns:

TextItem instance, for chaining setter calls

getSuppressBrowserClearIcon

public java.lang.Boolean getSuppressBrowserClearIcon()

This attribute currently only has an effect in Internet Explorer. That browser will dynamically add a native "clear" icon to <input type="text" > elements when the user enters a value. Setting suppressBrowserClearIcon to true will write out HTML to suppress this icon. This can be particularly useful for items which define their own clear icon as in this sample.

If this property is not set at the item level, DynamicForm.suppressBrowserClearIcons will be used instead.

Note that as an alternative to using this feature, the icon may also be suppressed (or have other styling applied to it) directly via CSS, using the ::-ms-clear css pseudo-element (proprietary Internet Explorer feature).

Implementation note: This feature makes use of the automatically generated suppressClearIconClassName css class.

Returns:

Current suppressBrowserClearIcon value. Default value is null

setTextBoxStyle

public TextItem setTextBoxStyle(java.lang.String textBoxStyle)

Base CSS class name for this item's input element. NOTE: See the CompoundFormItem_skinning discussion for special skinning considerations.

For a rounded text item, you can set textBoxStyle to "roundedTextItem". This style exists only in Enterprise, EnterpriseBlue and Graphite skins. There is no corresponding rounded style for SelectItem or ComboBoxItem as this creates an awkward seam with the pop-up list (and a rounded pop-up list wouldn't help: data could not be flush to corners). For these reasons we recommend rounded inputs only in limited cases like single standalone fields.

Overrides:

setTextBoxStyle in class FormItem

Parameters:

textBoxStyle - New textBoxStyle value. Default value is "textItem"

Returns:

TextItem instance, for chaining setter calls

See Also:

FormItemBaseStyle, Appearance overview and related methods

getTextBoxStyle

public java.lang.String getTextBoxStyle()

Base CSS class name for this item's input element. NOTE: See the CompoundFormItem_skinning discussion for special skinning considerations.

For a rounded text item, you can set textBoxStyle to "roundedTextItem". This style exists only in Enterprise, EnterpriseBlue and Graphite skins. There is no corresponding rounded style for SelectItem or ComboBoxItem as this creates an awkward seam with the pop-up list (and a rounded pop-up list wouldn't help: data could not be flush to corners). For these reasons we recommend rounded inputs only in limited cases like single standalone fields.

Overrides:

getTextBoxStyle in class FormItem

Returns:

Current textBoxStyle value. Default value is "textItem"

See Also:

FormItemBaseStyle, Appearance overview and related methods

setUsePlaceholderForHint

public TextItem setUsePlaceholderForHint(boolean usePlaceholderForHint)

If showing the hint in field and if supported by the browser, should the HTML5 placeholder attribute be used to display the hint within the field? If set to false, then use of the placeholder attribute is disabled and an alternative technique to display the hint in-field is used instead.

The HTML5 placeholder attribute is supported in the following major browsers:

• Chrome 4+
• Firefox 4+
• Internet Explorer 10+
• Safari 5+
• Opera 11.50+
• Android 2.1+ WebView (used by the stock Browser app and when packaging with PhoneGap)
• Mobile Safari for iOS 3.2+

In browsers other than the above, in-field hints are implemented via a different technique.

Note that placeholder behavior is known to differ in Internet Explorer and certain old versions of the above browsers due to a recent change in the HTML5 specification regarding the placeholder attribute. Under the old rules, the placeholder is cleared when the element is focused. In the latest HTML5 spec as published by WHATWG, the placeholder is still displayed when the element is focused as long as the value is an empty string.

Styling the placeholder

While there isn't a standard way to style the placeholder text, Chrome, Firefox, Internet Explorer, and Safari provide vendor-prefixed pseudo-classes and/or pseudo-elements that can be used in CSS selectors:

Browser	Pseudo-class or pseudo-element
Chrome, Safari	::-webkit-input-placeholder
Firefox 4 - 18	:-moz-placeholder
Firefox 19+	::-moz-placeholder
Internet Explorer	:-ms-input-placeholder

Note that unlike other browsers, Firefox 19+ applies opacity:0.4 to the placeholder text. See Bug 556145 - Placeholder text default style should use opacity instead of GrayText

Because browsers are required to ignore the entire rule if a selector is invalid, separate rules are needed for each browser. For example:

::-webkit-input-placeholder {
     color: blue;
     opacity: 1;
 }
 :-moz-placeholder {
     color: blue;
     opacity: 1;
 }
 ::-moz-placeholder {
     color: blue;
     opacity: 1;
 }
 :-ms-input-placeholder {
     color: blue;
     opacity: 1;
 }

If using Sass, it may be useful to utilize Sass' parent selector feature. For example:

.myCustomItem,
 .myCustomItemRTL,
 .myCustomItemDisabled,
 .myCustomItemDisabledRTL,
 .myCustomItemError,
 .myCustomItemErrorRTL,
 .myCustomItemFocused,
 .myCustomItemFocusedRTL,
 .myCustomItemHint,
 .myCustomItemHintRTL,
 .myCustomItemDisabledHint,
 .myCustomItemDisabledHintRTL {
     // ...
 
     &::-webkit-input-placeholder {
         color: blue;
         opacity: 1;
     }
     &:-moz-placeholder {
         color: blue;
         opacity: 1;
     }
     &::-moz-placeholder {
         color: blue;
         opacity: 1;
     }
     &:-ms-input-placeholder {
         color: blue;
         opacity: 1;
     }
 }

If using Compass, the input-placeholder mixin that was added in version 1.0 can further simplify the code to style the placeholder text For example:

.myCustomItem,
 .myCustomItemRTL,
 .myCustomItemDisabled,
 .myCustomItemDisabledRTL,
 .myCustomItemError,
 .myCustomItemErrorRTL,
 .myCustomItemFocused,
 .myCustomItemFocusedRTL,
 .myCustomItemHint,
 .myCustomItemHintRTL,
 .myCustomItemDisabledHint,
 .myCustomItemDisabledHintRTL {
     // ...
 
     @include input-placeholder {
         color: blue;
         opacity: 1;
     }
 }

Accessibility concerns

The HTML5 specification notes that a placeholder should not be used as a replacement for a title. The placeholder is intended to be a short hint that assists the user who is entering a value into the empty field. The placeholder can be mistaken by some users for a pre-filled value, particularly in Internet Explorer because the same color is used, and the placeholder text color may provide insufficient contrast, particularly in Firefox 19+ because of the default 0.4 opacity. Furthermore, not having a title reduces the hit area available for setting focus on the item.

Note : This is an advanced setting

Parameters:

usePlaceholderForHint - New usePlaceholderForHint value. Default value is true

Returns:

TextItem instance, for chaining setter calls

See Also:

FormItem.setHint(java.lang.String), Appearance overview and related methods

getUsePlaceholderForHint

public boolean getUsePlaceholderForHint()

If showing the hint in field and if supported by the browser, should the HTML5 placeholder attribute be used to display the hint within the field? If set to false, then use of the placeholder attribute is disabled and an alternative technique to display the hint in-field is used instead.

The HTML5 placeholder attribute is supported in the following major browsers:

• Chrome 4+
• Firefox 4+
• Internet Explorer 10+
• Safari 5+
• Opera 11.50+
• Android 2.1+ WebView (used by the stock Browser app and when packaging with PhoneGap)
• Mobile Safari for iOS 3.2+

In browsers other than the above, in-field hints are implemented via a different technique.

Note that placeholder behavior is known to differ in Internet Explorer and certain old versions of the above browsers due to a recent change in the HTML5 specification regarding the placeholder attribute. Under the old rules, the placeholder is cleared when the element is focused. In the latest HTML5 spec as published by WHATWG, the placeholder is still displayed when the element is focused as long as the value is an empty string.

Styling the placeholder

While there isn't a standard way to style the placeholder text, Chrome, Firefox, Internet Explorer, and Safari provide vendor-prefixed pseudo-classes and/or pseudo-elements that can be used in CSS selectors:

Browser	Pseudo-class or pseudo-element
Chrome, Safari	::-webkit-input-placeholder
Firefox 4 - 18	:-moz-placeholder
Firefox 19+	::-moz-placeholder
Internet Explorer	:-ms-input-placeholder

Note that unlike other browsers, Firefox 19+ applies opacity:0.4 to the placeholder text. See Bug 556145 - Placeholder text default style should use opacity instead of GrayText

Because browsers are required to ignore the entire rule if a selector is invalid, separate rules are needed for each browser. For example:

::-webkit-input-placeholder {
     color: blue;
     opacity: 1;
 }
 :-moz-placeholder {
     color: blue;
     opacity: 1;
 }
 ::-moz-placeholder {
     color: blue;
     opacity: 1;
 }
 :-ms-input-placeholder {
     color: blue;
     opacity: 1;
 }

If using Sass, it may be useful to utilize Sass' parent selector feature. For example:

.myCustomItem,
 .myCustomItemRTL,
 .myCustomItemDisabled,
 .myCustomItemDisabledRTL,
 .myCustomItemError,
 .myCustomItemErrorRTL,
 .myCustomItemFocused,
 .myCustomItemFocusedRTL,
 .myCustomItemHint,
 .myCustomItemHintRTL,
 .myCustomItemDisabledHint,
 .myCustomItemDisabledHintRTL {
     // ...
 
     &::-webkit-input-placeholder {
         color: blue;
         opacity: 1;
     }
     &:-moz-placeholder {
         color: blue;
         opacity: 1;
     }
     &::-moz-placeholder {
         color: blue;
         opacity: 1;
     }
     &:-ms-input-placeholder {
         color: blue;
         opacity: 1;
     }
 }

If using Compass, the input-placeholder mixin that was added in version 1.0 can further simplify the code to style the placeholder text For example:

.myCustomItem,
 .myCustomItemRTL,
 .myCustomItemDisabled,
 .myCustomItemDisabledRTL,
 .myCustomItemError,
 .myCustomItemErrorRTL,
 .myCustomItemFocused,
 .myCustomItemFocusedRTL,
 .myCustomItemHint,
 .myCustomItemHintRTL,
 .myCustomItemDisabledHint,
 .myCustomItemDisabledHintRTL {
     // ...
 
     @include input-placeholder {
         color: blue;
         opacity: 1;
     }
 }

Accessibility concerns

The HTML5 specification notes that a placeholder should not be used as a replacement for a title. The placeholder is intended to be a short hint that assists the user who is entering a value into the empty field. The placeholder can be mistaken by some users for a pre-filled value, particularly in Internet Explorer because the same color is used, and the placeholder text color may provide insufficient contrast, particularly in Firefox 19+ because of the default 0.4 opacity. Furthermore, not having a title reduces the hit area available for setting focus on the item.

Returns:

Current usePlaceholderForHint value. Default value is true

See Also:

FormItem.getHint(), Appearance overview and related methods

deselectValue

public void deselectValue()

If this item currently has focus, clear the current selection. leaving focus in the item. Has no effect if the item is undrawn or unfocused. Only applies to text-based items.

deselectValue

public void deselectValue(java.lang.Boolean start)

If this item currently has focus, clear the current selection. leaving focus in the item. Has no effect if the item is undrawn or unfocused. Only applies to text-based items.

Parameters:

start - By default the text insertion cursor will be moved to the end of the current value - pass in this parameter to move to the start instead

getEnteredValue

public java.lang.String getEnteredValue()

Returns the raw text value that currently appears in the text field, which can differ from FormItem.getValue() in various cases - for example:

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

Returns:

current entered value

getHint

public java.lang.String getHint()

Returns the hint text for this item. Default implementation returns FormItem.hint, or null if there is no hint to show.

Overrides:

getHint in class FormItem

Returns:

HTML to show as the hint for the item. See HTMLString

See Also:

Appearance overview and related methods

getSelectionRange

public int[] getSelectionRange()

For text-based items, this method returns the indices of the start/end of the current selection if the item currently has the focus. In browsers other than Internet Explorer 6-9, if this item does not have focus, then this method returns the indices of the start/end of the selection the last time that this item had focus. In IE 6-9, returns null if the item does not have focus.

In all browsers, clicking anywhere outside of the item causes the item to lose focus; hence, in IE 6-9, this method will not work in other components' event handlers for certain events. For example, within the click() handler of a button, this item will have already lost focus, so in IE 6-9, this method will return null if called within the button's click() handler. One cross-browser solution to this issue is to save the selection range for later in a mouseDown() or mouseOver() handler.

Notes:

• In browsers other than IE 6-9, calling setValue() or otherwise changing the entered value invalidates the past selection range.
• The returned indices are indices within the entered value rather than the item's value as returned by getValue(). The distinction is particularly important for TextAreaItems because browsers normalize the line endings in the <textarea> element's value. Internet Explorer 6, 7, and 8 convert line endings to "\r\n" while other browsers convert line endings to "\n" as specified by the HTML5 standard.

Returns:

2 element array showing character index of the current or past selection's start and end points within this item's entered value. In IE 6-9, returns null if the item does not have focus.

pendingStatusChanged

public boolean pendingStatusChanged(DynamicForm form,
                                    FormItem item,
                                    boolean pendingStatus,
                                    java.lang.Object newValue,
                                    java.lang.Object value)

Notification method called when showPending is enabled and this text item should either clear or show its pending visual state.

The default behavior is that the titleStyle, cellStyle, and textBoxStyle are updated to include/exclude the "Pending" suffix. Returning false will cancel this default behavior.

Parameters:

form - the managing DynamicForm instance.

item - the form item itself (also available as "this").

pendingStatus - true if the item should show its pending visual state; false otherwise.

newValue - the current form item value.

value - the value that would be restored by a call to DynamicForm.resetValues().

Returns:

false to cancel the default behavior.

selectValue

public void selectValue()

Put focus in this item and select the entire value. Only applies to text based items

setSelectionRange

public void setSelectionRange(int start,
                              int end)

Puts focus into this form item and selects characters between the given indices. Only applies to drawn text based items.

Parameters:

start - selection starting character index

end - end of selection character index

shouldFetchMissingValue

public java.lang.Boolean shouldFetchMissingValue(java.lang.Object newValue)

If this field has a specified optionDataSource, should we perform a fetch against that dataSource to find the record that matches this field's value?

For textItems this method will return false if the item is editable unless FormItem.alwaysFetchMissingValues is true, even if there is a specified displayField. We do this as, for a freeform text-entry field with a specified displayField, the correct behavior when the user enters an unrecognized value is somewhat ambiguous. The user could have entered a complete display-field value, in which case it might be appropriate to issue a fetch against the display-field of the optionDataSource, and set the underlying item value.
If a match was not found though, we necessarily treat the entered value as the new "dataValue" for the field. Should we then issue a second fetch against the optionDataSource comparing the user-entered value with the value-field of the dataSource?

There are still cases where it could make sense to issue the fetch against the dataSource, and developers who want this behavior can set alwaysFetchMissingValues to true.

See FormItem.shouldFetchMissingValue() for how this method behaves for other item types.

Overrides:

shouldFetchMissingValue in class FormItem

Parameters:

newValue - The new data value of the item.

Returns:

should we fetch the record matching the new value from the item's optionDataSource?

setPastedValueTransformer

public void setPastedValueTransformer(PastedValueTransformer customizer)

Notification fired in response to a clipboard "paste" event on freeform text items, giving developers an opportunity to reformat the pasted text. The pastedValue argument contains the text pasted from the clipboard. This method should return the text value to actually insert into the input element.

Parameters:

PastedValueTransformer - customizer

setDefaultProperties

public static void setDefaultProperties(TextItem textItemProperties)

Class level method to set the default properties of this class. If set, then all existing and subsequently created instances of this class will automatically have default properties corresponding to the properties of the class instance passed to this function. This is a powerful feature that eliminates the need for users to create a separate hierarchy of subclasses that only alter the default properties of this class. Can also be used for skinning / styling purposes.

Note: This method is intended for setting default attributes only and will affect all instances of the underlying class (including those automatically generated in JavaScript). This method should not be used to apply standard EventHandlers or override methods for a class - use a custom subclass instead. Calling this method after instances have been created can result in undefined behavior, since it bypasses any setters and a class instance may have already examined a particular property and not be expecting any changes through this route.

Parameters:

textItemProperties - properties that should be used as new defaults when instances of this class are created

See Also:

SGWTProperties

getValueAsString

public java.lang.String getValueAsString()

Return the value tracked by this form item.

Returns:

value of this element