A control that is used for multi-line input of text.
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.
Parameters that determine the size:
rows
- Number of visible text lines (overruled by height
, if both are set)cols
- Number of visible characters per line line (overruled by width
, if both are set)height
- Height of the controlwidth
- Width of the controlgrowing
- The text area adjusts its size based on the contentgrowingMaxLines
- Threshold for the growing
property (shouldn't exceed the screen size)maxLength
- Maximum number of characters that can be entered in a text areawrapping
- The way the entered text is wrapped by the controlshowExceededText
- Determines how text beyond the maxLength
length is handled
showExceededText
is set to TRUE and you paste a longer text, all characters beyond the maxLength
limit are automatically selected.showExceededText
is set to TRUE, the control will display a counter for the remaining characters.
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 |
Name | Type | Default Value | Description |
---|---|---|---|
cols | int | 20 | Defines the visible width of the control, in average character widths. Note: The |
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 |
growingMaxLines | int | 0 | Defines the maximum number of lines that the control can grow. |
height | sap.ui.core.CSSSize | Defines the height of the control. Visibility: public |
|
maxLength | int | 0 | Defines the maximum number of characters that the |
rows | int | 2 | Defines the number of visible text lines for the control. Note: The |
showExceededText | boolean | false | Determines whether the characters, exceeding the maximum allowed character count, are visible in the input field. If set to |
valueLiveUpdate | boolean | false | Indicates when the |
wrapping | sap.ui.core.Wrapping | None | Indicates how the control wraps the text, e.g. |
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. |
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 |
showValueStateMessage | boolean | true | Indicates whether the value state message should be shown or not. |
textAlign | sap.ui.core.TextAlign | Initial | Defines the horizontal alignment of the text that is shown inside the input field. |
textDirection | sap.ui.core.TextDirection | Inherit | Defines the text directionality of the input field, e.g. |
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. |
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. |
|
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 |
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 |
Event | Description |
---|---|
liveChange |
Is fired whenever the user has modified the text shown on the text area. |
Method | Description |
---|---|
attachLiveChange |
Attaches event handler When called, the context of the event handler (its Is fired whenever the user has modified the text shown on the text area. |
detachLiveChange |
Detaches event handler 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
|
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 Default value is |
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 Default value is |
getGrowingMaxLines |
Gets current value of property growingMaxLines. Defines the maximum number of lines that the control can grow. Default value is |
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 Default value is |
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 Default value is |
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 Default value is |
getValueLiveUpdate |
Gets current value of property valueLiveUpdate. Indicates when the Default value is |
getWrapping |
Gets current value of property wrapping. Indicates how the control wraps the text, e.g. Default value is |
setCols |
Sets a new value for property cols. Defines the visible width of the control, in average character widths. Note: The When called with a value of Default value is |
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 When called with a value of Default value is |
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 Default value is |
setHeight |
Sets a new value for property height. Defines the height of the control. When called with a value of |
setMaxLength |
Sets a new value for property maxLength. Defines the maximum number of characters that the When called with a value of Default value is |
setRows |
Sets a new value for property rows. Defines the number of visible text lines for the control. Note: The When called with a value of Default value is |
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 When called with a value of Default value is |
setValueLiveUpdate |
Sets a new value for property valueLiveUpdate. Indicates when the When called with a value of Default value is |
setWrapping |
Sets a new value for property wrapping. Indicates how the control wraps the text, e.g. When called with a value of Default value is |
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 |
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 |
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 |
Fires event liveChange to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
value | string |
The new |
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
.
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
.
Gets current value of property growingMaxLines.
Defines the maximum number of lines that the control can grow.
Default value is 0
.
Gets current value of property maxLength.
Defines the maximum number of characters that the value
can be.
Default value is 0
.
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
.
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
.
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
.
Gets current value of property wrapping.
Indicates how the control wraps the text, e.g. Soft
, Hard
, Off
.
Default value is None
.
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |