class sap.m.TextArea

Control sample: sap.m.TextArea
Visiblity: public
UX Guidelines: Text Area
Implements:
Available since: N/A
Extends: sap.m.InputBase
Module: sap/m/TextArea
Application Component: CA-UI5-CTR

A control that is used for multi-line input of text.

Overview

The text area is used to enter multiple lines of text. When empty, it can hold a placeholder similar to an input. You can define the height and width of the text area and also determine specific behavior when handling long texts.

Structure

Parameters that determine the size:

Parameters that determine the behavior:

Usage

When to use

Responsive Behavior


Constructor

Constructor for a new TextArea.

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject#constructor for a general description of the syntax of the settings object.

new sap.m.TextArea(sId?, mSettings?)
Param Type Default Value Description
sId? string

ID for the new control, generated automatically if no ID is given

mSettings? object

Initial settings for the new control


Properties

Name Type Default Value Description
cols int 20

Defines the visible width of the control, in average character widths. Note: The width property wins over the cols property, if both are set.

Visibility: public
growing boolean false

Indicates the ability of the control to automatically grow and shrink dynamically with its content. Note: This property should not be used when the height property is set.

Since: 1.38.0.

Visibility: public
growingMaxLines int 0

Defines the maximum number of lines that the control can grow.

Since: 1.38.0.

Visibility: public
height sap.ui.core.CSSSize

Defines the height of the control.

Visibility: public
maxLength int 0

Defines the maximum number of characters that the value can be.

Visibility: public
rows int 2

Defines the number of visible text lines for the control. Note: The height property wins over the rows property, if both are set.

Visibility: public
showExceededText boolean false

Determines whether the characters, exceeding the maximum allowed character count, are visible in the input field.

If set to false the user is not allowed to enter more characters than what is set in the maxLength property. If set to true the characters exceeding the maxLength value are selected on paste and the counter below the input field displays their number.

Since: 1.48.

Visibility: public
valueLiveUpdate boolean false

Indicates when the value property gets updated with the user changes. Setting it to true updates the value property whenever the user has modified the text shown on the text area.

Since: 1.30.

Visibility: public
wrapping sap.ui.core.Wrapping None

Indicates how the control wraps the text, e.g. Soft, Hard, Off.

Visibility: public

Borrowed Properties

Name Type Default Value Description
editable boolean true

Defines whether the control can be modified by the user or not. Note: A user can tab to non-editable control, highlight it, and copy the text from it.

Since: 1.12.0.

Visibility: public
enabled boolean true

Indicates whether the user can interact with the control or not. Note: Disabled controls cannot be focused and they are out of the tab-chain.

Visibility: public
name string

The name to be used in the HTML code (for example, for HTML forms that send data to the server via submission).

Visibility: public
placeholder string

Defines a short hint intended to aid the user with data entry when the control has no value.

Visibility: public
required boolean false

Indicates that user input is required. This property is only needed for accessibility purposes when a single relationship between the field and a label (see aggregation labelFor of sap.m.Label) cannot be established (e.g. one label should label multiple fields).

Since: 1.38.4.

Visibility: public
showValueStateMessage boolean true

Indicates whether the value state message should be shown or not.

Since: 1.26.0.

Visibility: public
textAlign sap.ui.core.TextAlign Initial

Defines the horizontal alignment of the text that is shown inside the input field.

Since: 1.26.0.

Visibility: public
textDirection sap.ui.core.TextDirection Inherit

Defines the text directionality of the input field, e.g. RTL, LTR

Since: 1.28.0.

Visibility: public
value string

Defines the value of the control.

Visibility: public
valueState sap.ui.core.ValueState None

Visualizes the validation state of the control, e.g. Error, Warning, Success.

Visibility: public
valueStateText string

Defines the text that appears in the value state message pop-up. If this is not specified, a default text is shown from the resource bundle.

Since: 1.26.0.

Visibility: public
width sap.ui.core.CSSSize

Defines the width of the control.

Note: If the provided width is too small, the control gets stretched to its min width, which is needed in order for the control to be usable and well aligned.

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
_counter 0..1 sap.m.Text

Borrowed Aggregations

Name Cardinality Type Description
formattedValueStateText 0..1 sap.m.FormattedText

Defines the formatted text that appears in the value state message pop-up. It can include links. If both valueStateText and formattedValueStateText are set - the latter is shown.

Since: 1.78.


Events Overview

Event Description
liveChange

Is fired whenever the user has modified the text shown on the text area.

liveChange

Is fired whenever the user has modified the text shown on the text area.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
value string

The new value of the control.


Methods Overview

Method Description
attachLiveChange

Attaches event handler fnFunction to the liveChange event of this sap.m.TextArea.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.TextArea itself.

Is fired whenever the user has modified the text shown on the text area.

detachLiveChange

Detaches event handler fnFunction from the liveChange event of this sap.m.TextArea.

The passed function and listener object must match the ones used for event registration.

sap.m.TextArea.extend

Creates a new subclass of class sap.m.TextArea with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.m.InputBase.extend.

fireLiveChange

Fires event liveChange to attached listeners.

getCols

Gets current value of property cols.

Defines the visible width of the control, in average character widths. Note: The width property wins over the cols property, if both are set.

Default value is 20.

getGrowing

Gets current value of property growing.

Indicates the ability of the control to automatically grow and shrink dynamically with its content. Note: This property should not be used when the height property is set.

Default value is false.

getGrowingMaxLines

Gets current value of property growingMaxLines.

Defines the maximum number of lines that the control can grow.

Default value is 0.

getHeight

Gets current value of property height.

Defines the height of the control.

getMaxLength

Gets current value of property maxLength.

Defines the maximum number of characters that the value can be.

Default value is 0.

sap.m.TextArea.getMetadata

Returns a metadata object for class sap.m.TextArea.

getRows

Gets current value of property rows.

Defines the number of visible text lines for the control. Note: The height property wins over the rows property, if both are set.

Default value is 2.

getShowExceededText

Gets current value of property showExceededText.

Determines whether the characters, exceeding the maximum allowed character count, are visible in the input field.

If set to false the user is not allowed to enter more characters than what is set in the maxLength property. If set to true the characters exceeding the maxLength value are selected on paste and the counter below the input field displays their number.

Default value is false.

getValueLiveUpdate

Gets current value of property valueLiveUpdate.

Indicates when the value property gets updated with the user changes. Setting it to true updates the value property whenever the user has modified the text shown on the text area.

Default value is false.

getWrapping

Gets current value of property wrapping.

Indicates how the control wraps the text, e.g. Soft, Hard, Off.

Default value is None.

setCols

Sets a new value for property cols.

Defines the visible width of the control, in average character widths. Note: The width property wins over the cols property, if both are set.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 20.

setGrowing

Sets a new value for property growing.

Indicates the ability of the control to automatically grow and shrink dynamically with its content. Note: This property should not be used when the height property is set.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setGrowingMaxLines

Sets a new value for property growingMaxLines.

Defines the maximum number of lines that the control can grow.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 0.

setHeight

Sets a new value for property height.

Defines the height of the control.

When called with a value of null or undefined, the default value of the property will be restored.

setMaxLength

Sets a new value for property maxLength.

Defines the maximum number of characters that the value can be.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 0.

setRows

Sets a new value for property rows.

Defines the number of visible text lines for the control. Note: The height property wins over the rows property, if both are set.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 2.

setShowExceededText

Sets a new value for property showExceededText.

Determines whether the characters, exceeding the maximum allowed character count, are visible in the input field.

If set to false the user is not allowed to enter more characters than what is set in the maxLength property. If set to true the characters exceeding the maxLength value are selected on paste and the counter below the input field displays their number.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setValueLiveUpdate

Sets a new value for property valueLiveUpdate.

Indicates when the value property gets updated with the user changes. Setting it to true updates the value property whenever the user has modified the text shown on the text area.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setWrapping

Sets a new value for property wrapping.

Indicates how the control wraps the text, e.g. Soft, Hard, Off.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is None.

attachLiveChange

Attaches event handler fnFunction to the liveChange event of this sap.m.TextArea.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.TextArea itself.

Is fired whenever the user has modified the text shown on the text area.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.TextArea itself

detachLiveChange

Detaches event handler fnFunction from the liveChange event of this sap.m.TextArea.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

sap.m.TextArea.extend

Creates a new subclass of class sap.m.TextArea with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.m.InputBase.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

fireLiveChange

Fires event liveChange to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

value string

The new value of the control.

getCols

Gets current value of property cols.

Defines the visible width of the control, in average character widths. Note: The width property wins over the cols property, if both are set.

Default value is 20.

getGrowing

Gets current value of property growing.

Indicates the ability of the control to automatically grow and shrink dynamically with its content. Note: This property should not be used when the height property is set.

Default value is false.

getGrowingMaxLines

Gets current value of property growingMaxLines.

Defines the maximum number of lines that the control can grow.

Default value is 0.

getHeight

Gets current value of property height.

Defines the height of the control.

getMaxLength

Gets current value of property maxLength.

Defines the maximum number of characters that the value can be.

Default value is 0.

sap.m.TextArea.getMetadata

Returns a metadata object for class sap.m.TextArea.

getRows

Gets current value of property rows.

Defines the number of visible text lines for the control. Note: The height property wins over the rows property, if both are set.

Default value is 2.

getShowExceededText

Gets current value of property showExceededText.

Determines whether the characters, exceeding the maximum allowed character count, are visible in the input field.

If set to false the user is not allowed to enter more characters than what is set in the maxLength property. If set to true the characters exceeding the maxLength value are selected on paste and the counter below the input field displays their number.

Default value is false.

getValueLiveUpdate

Gets current value of property valueLiveUpdate.

Indicates when the value property gets updated with the user changes. Setting it to true updates the value property whenever the user has modified the text shown on the text area.

Default value is false.

getWrapping

Gets current value of property wrapping.

Indicates how the control wraps the text, e.g. Soft, Hard, Off.

Default value is None.

setCols

Sets a new value for property cols.

Defines the visible width of the control, in average character widths. Note: The width property wins over the cols property, if both are set.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 20.

Param Type DefaultValue Description
iCols int 20

New value for property cols

setGrowing

Sets a new value for property growing.

Indicates the ability of the control to automatically grow and shrink dynamically with its content. Note: This property should not be used when the height property is set.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bGrowing boolean false

New value for property growing

setGrowingMaxLines

Sets a new value for property growingMaxLines.

Defines the maximum number of lines that the control can grow.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 0.

Param Type DefaultValue Description
iGrowingMaxLines int 0

New value for property growingMaxLines

setHeight

Sets a new value for property height.

Defines the height of the control.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sHeight sap.ui.core.CSSSize

New value for property height

setMaxLength

Sets a new value for property maxLength.

Defines the maximum number of characters that the value can be.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 0.

Param Type DefaultValue Description
iMaxLength int 0

New value for property maxLength

setRows

Sets a new value for property rows.

Defines the number of visible text lines for the control. Note: The height property wins over the rows property, if both are set.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 2.

Param Type DefaultValue Description
iRows int 2

New value for property rows

setShowExceededText

Sets a new value for property showExceededText.

Determines whether the characters, exceeding the maximum allowed character count, are visible in the input field.

If set to false the user is not allowed to enter more characters than what is set in the maxLength property. If set to true the characters exceeding the maxLength value are selected on paste and the counter below the input field displays their number.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bShowExceededText boolean false

New value for property showExceededText

setValueLiveUpdate

Sets a new value for property valueLiveUpdate.

Indicates when the value property gets updated with the user changes. Setting it to true updates the value property whenever the user has modified the text shown on the text area.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bValueLiveUpdate boolean false

New value for property valueLiveUpdate

setWrapping

Sets a new value for property wrapping.

Indicates how the control wraps the text, e.g. Soft, Hard, Off.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is None.

Param Type DefaultValue Description
sWrapping sap.ui.core.Wrapping None

New value for property wrapping