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

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

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.

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

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.

setEnforceLength

public void 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. Given how text areas are typically used to edit longer values than non-wrapping
TextItems, this value is false by default for textAreaItems.

Parameters:

enforceLength - New enforceLength value. Default value is false

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. Given how text areas are typically used to edit longer values than non-wrapping
TextItems, this value is false by default for textAreaItems.

Returns:

Current enforceLength value. Default value is false

setFormatOnBlur

public void setFormatOnBlur(java.lang.Boolean formatOnBlur)

With formatOnBlur enabled, this textAreaItem 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

getFormatOnBlur

public java.lang.Boolean getFormatOnBlur()

With formatOnBlur enabled, this textAreaItem 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

setHeight

public void setHeight(int height)

Default height of this item

Note that when item is rendered as read-only with readOnlyDisplay as
"static" the property FormItem.staticHeight is
used instead.

setLength

public void setLength(java.lang.Integer length)

If set, 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.

getLength

public java.lang.Integer getLength()

If set, 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.

setPrintFullText

public void setPrintFullText(java.lang.Boolean printFullText)

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

getPrintFullText

public java.lang.Boolean getPrintFullText()

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

setShowHintInField

Unless the HTML5 placeholder attribute is used to display the hint (see usePlaceholderForHint),
the value of the data element 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:

getShowHintInField

Unless the HTML5 placeholder attribute is used to display the hint (see usePlaceholderForHint),
the value of the data element 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:

setUsePlaceholderForHint

public void 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:

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:

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.

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:

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:

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.

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.

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

transformPastedValue

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:

item - Item into which the user pasted a value

form - Pointer to the item's form

pastedValue - Pasted text value

Returns:

Reformatted version of the pasted text.

setDefaultProperties

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:

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