class sap.m.Text

Control sample: sap.m.Text
Visiblity: public
UX Guidelines: Text
Implements: sap.ui.core.IShrinkablesap.ui.core.IFormContentsap.ui.core.ISemanticFormContentsap.m.IHyphenation
Available since: N/A
Module: sap/m/Text
Application Component: CA-UI5-CTR

The Text control can be used for embedding longer text paragraphs, that need text wrapping, into your app. If the configured text value contains HTML code or script tags, those will be escaped.

As of version 1.60, you can hyphenate the text with the use of the wrappingType property. For more information, see Text Controls Hyphenation.

Note: Line breaks will always be visualized except when the wrapping property is set to false. In addition, tabs and whitespace can be preserved by setting the renderWhitespace property to true.


Constructor

Constructor for a new Text.

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.Text(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
emptyIndicatorMode sap.m.EmptyIndicatorMode Off

Specifies if an empty indicator should be displayed when there is no text.

Since: 1.87.

Visibility: public
maxLines int

Limits the number of lines for wrapping texts.

Note: The multi-line overflow indicator depends on the browser line clamping support. For such browsers, this will be shown as ellipsis, for the other browsers the overflow will just be hidden.

Since: 1.13.2.

Visibility: public
renderWhitespace boolean false

Specifies how whitespace and tabs inside the control are handled. If true, whitespace will be preserved by the browser. Depending on wrapping property text will either only wrap on line breaks or wrap when necessary, and on line breaks.

Since: 1.51.

Visibility: public
text string empty string

Determines the text to be displayed.

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

Sets the horizontal alignment of the text.

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

Available options for the text direction are LTR and RTL. By default the control inherits the text direction from its parent control.

Visibility: public
width sap.ui.core.CSSSize

Sets the width of the Text control. By default, the Text control uses the full width available. Set this property to restrict the width to a custom value.

Visibility: public
wrapping boolean true

Enables text wrapping.

Visibility: public
wrappingType sap.m.WrappingType Normal

Defines the type of text wrapping to be used (hyphenated or normal).

Note: This property takes effect only when the wrapping property is set to true.

Since: 1.60.

Visibility: public

Methods Overview

Method Description
bindText

Binds property text to model data.

See ManagedObject.bindProperty for a detailed description of the possible properties of oBindingInfo

canUseNativeLineClamp

Decides whether the control can use native line clamp feature or not.

In RTL mode native line clamp feature is not supported.

clampHeight

Sets the max height to support maxLines property.

clampText

Clamps the wrapping text according to max lines and returns the found ellipsis position. Parameters can be used for better performance.

sap.m.Text.extend

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

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

getAccessibilityInfo

Gets the accessibility information for the text.

References:

  • sap.ui.core.Control#getAccessibilityInfo

getClampHeight

Returns the max height according to max lines and line height calculation. This is not calculated max height!

getEmptyIndicatorMode

Gets current value of property emptyIndicatorMode.

Specifies if an empty indicator should be displayed when there is no text.

Default value is Off.

getLineHeight

Caches and returns the computed line height of the text.

References:

  • sap.m.Text#cacheLineHeight

getMaxLines

Gets current value of property maxLines.

Limits the number of lines for wrapping texts.

Note: The multi-line overflow indicator depends on the browser line clamping support. For such browsers, this will be shown as ellipsis, for the other browsers the overflow will just be hidden.

sap.m.Text.getMetadata

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

getRenderWhitespace

Gets current value of property renderWhitespace.

Specifies how whitespace and tabs inside the control are handled. If true, whitespace will be preserved by the browser. Depending on wrapping property text will either only wrap on line breaks or wrap when necessary, and on line breaks.

Default value is false.

getText

Gets the text.

getTextAlign

Gets current value of property textAlign.

Sets the horizontal alignment of the text.

Default value is Begin.

getTextDirection

Gets current value of property textDirection.

Available options for the text direction are LTR and RTL. By default the control inherits the text direction from its parent control.

Default value is Inherit.

getTextDomRef

Returns the text node container's DOM reference. This can be different from getDomRef when inner wrapper is needed.

getWidth

Gets current value of property width.

Sets the width of the Text control. By default, the Text control uses the full width available. Set this property to restrict the width to a custom value.

getWrapping

Gets current value of property wrapping.

Enables text wrapping.

Default value is true.

getWrappingType

Gets current value of property wrappingType.

Defines the type of text wrapping to be used (hyphenated or normal).

Note: This property takes effect only when the wrapping property is set to true.

Default value is Normal.

hasMaxLines

Determines whether max lines should be rendered or not.

onAfterRendering

Overwrites onAfterRendering

setEmptyIndicatorMode

Sets a new value for property emptyIndicatorMode.

Specifies if an empty indicator should be displayed when there is no text.

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

Default value is Off.

setMaxLines

Sets a new value for property maxLines.

Limits the number of lines for wrapping texts.

Note: The multi-line overflow indicator depends on the browser line clamping support. For such browsers, this will be shown as ellipsis, for the other browsers the overflow will just be hidden.

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

sap.m.Text.setNodeValue

To prevent from the layout thrashing of the textContent call, this method first tries to set the nodeValue of the first child if it exists.

setRenderWhitespace

Sets a new value for property renderWhitespace.

Specifies how whitespace and tabs inside the control are handled. If true, whitespace will be preserved by the browser. Depending on wrapping property text will either only wrap on line breaks or wrap when necessary, and on line breaks.

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

Default value is false.

setText

Sets a new value for property text.

Determines the text to be displayed.

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

Default value is empty string.

setTextAlign

Sets a new value for property textAlign.

Sets the horizontal alignment of the text.

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

Default value is Begin.

setTextDirection

Sets a new value for property textDirection.

Available options for the text direction are LTR and RTL. By default the control inherits the text direction from its parent control.

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

Default value is Inherit.

setWidth

Sets a new value for property width.

Sets the width of the Text control. By default, the Text control uses the full width available. Set this property to restrict the width to a custom value.

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

setWrapping

Sets a new value for property wrapping.

Enables text wrapping.

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

Default value is true.

setWrappingType

Sets a new value for property wrappingType.

Defines the type of text wrapping to be used (hyphenated or normal).

Note: This property takes effect only when the wrapping property is set to true.

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

Default value is Normal.

unbindText

Unbinds property text from model data.

bindText

Binds property text to model data.

See ManagedObject.bindProperty for a detailed description of the possible properties of oBindingInfo

Param Type DefaultValue Description
oBindingInfo sap.ui.base.ManagedObject.PropertyBindingInfo

The binding information

canUseNativeLineClamp

Decides whether the control can use native line clamp feature or not.

In RTL mode native line clamp feature is not supported.

clampHeight

Sets the max height to support maxLines property.

Param Type DefaultValue Description
oDomRef HTMLElement

DOM reference of the text container.

clampText

Clamps the wrapping text according to max lines and returns the found ellipsis position. Parameters can be used for better performance.

Param Type DefaultValue Description
oDomRef HTMLElement

DOM reference of the text container.

iStartPos int

Start point of the ellipsis search.

iEndPos int

End point of the ellipsis search.

sap.m.Text.extend

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

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.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

getAccessibilityInfo

Gets the accessibility information for the text.

References:

getClampHeight

Returns the max height according to max lines and line height calculation. This is not calculated max height!

Param Type DefaultValue Description
oDomRef HTMLElement

DOM reference of the text container.

getEmptyIndicatorMode

Gets current value of property emptyIndicatorMode.

Specifies if an empty indicator should be displayed when there is no text.

Default value is Off.

getLineHeight

Caches and returns the computed line height of the text.

References:

Param Type DefaultValue Description
oDomRef HTMLElement

DOM reference of the text container.

getMaxLines

Gets current value of property maxLines.

Limits the number of lines for wrapping texts.

Note: The multi-line overflow indicator depends on the browser line clamping support. For such browsers, this will be shown as ellipsis, for the other browsers the overflow will just be hidden.

sap.m.Text.getMetadata

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

getRenderWhitespace

Gets current value of property renderWhitespace.

Specifies how whitespace and tabs inside the control are handled. If true, whitespace will be preserved by the browser. Depending on wrapping property text will either only wrap on line breaks or wrap when necessary, and on line breaks.

Default value is false.

getText

Gets the text.

Param Type DefaultValue Description
bNormalize boolean

Indication for normalized text.

getTextAlign

Gets current value of property textAlign.

Sets the horizontal alignment of the text.

Default value is Begin.

getTextDirection

Gets current value of property textDirection.

Available options for the text direction are LTR and RTL. By default the control inherits the text direction from its parent control.

Default value is Inherit.

getTextDomRef

Returns the text node container's DOM reference. This can be different from getDomRef when inner wrapper is needed.

getWidth

Gets current value of property width.

Sets the width of the Text control. By default, the Text control uses the full width available. Set this property to restrict the width to a custom value.

getWrapping

Gets current value of property wrapping.

Enables text wrapping.

Default value is true.

getWrappingType

Gets current value of property wrappingType.

Defines the type of text wrapping to be used (hyphenated or normal).

Note: This property takes effect only when the wrapping property is set to true.

Default value is Normal.

hasMaxLines

Determines whether max lines should be rendered or not.

onAfterRendering

Overwrites onAfterRendering

setEmptyIndicatorMode

Sets a new value for property emptyIndicatorMode.

Specifies if an empty indicator should be displayed when there is no text.

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

Default value is Off.

Param Type DefaultValue Description
sEmptyIndicatorMode sap.m.EmptyIndicatorMode Off

New value for property emptyIndicatorMode

setMaxLines

Sets a new value for property maxLines.

Limits the number of lines for wrapping texts.

Note: The multi-line overflow indicator depends on the browser line clamping support. For such browsers, this will be shown as ellipsis, for the other browsers the overflow will just be hidden.

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

Param Type DefaultValue Description
iMaxLines int

New value for property maxLines

sap.m.Text.setNodeValue

To prevent from the layout thrashing of the textContent call, this method first tries to set the nodeValue of the first child if it exists.

Param Type DefaultValue Description
oDomRef HTMLElement

DOM reference of the text node container.

sNodeValue string

new Node value.

setRenderWhitespace

Sets a new value for property renderWhitespace.

Specifies how whitespace and tabs inside the control are handled. If true, whitespace will be preserved by the browser. Depending on wrapping property text will either only wrap on line breaks or wrap when necessary, and on line breaks.

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
bRenderWhitespace boolean false

New value for property renderWhitespace

setText

Sets a new value for property text.

Determines the text to be displayed.

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

Default value is empty string.

Param Type DefaultValue Description
sText string ''

New value for property text

setTextAlign

Sets a new value for property textAlign.

Sets the horizontal alignment of the text.

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

Default value is Begin.

Param Type DefaultValue Description
sTextAlign sap.ui.core.TextAlign Begin

New value for property textAlign

setTextDirection

Sets a new value for property textDirection.

Available options for the text direction are LTR and RTL. By default the control inherits the text direction from its parent control.

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

Default value is Inherit.

Param Type DefaultValue Description
sTextDirection sap.ui.core.TextDirection Inherit

New value for property textDirection

setWidth

Sets a new value for property width.

Sets the width of the Text control. By default, the Text control uses the full width available. Set this property to restrict the width to a custom value.

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

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

New value for property width

setWrapping

Sets a new value for property wrapping.

Enables text wrapping.

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

Default value is true.

Param Type DefaultValue Description
bWrapping boolean true

New value for property wrapping

setWrappingType

Sets a new value for property wrappingType.

Defines the type of text wrapping to be used (hyphenated or normal).

Note: This property takes effect only when the wrapping property is set to true.

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

Default value is Normal.

Param Type DefaultValue Description
sWrappingType sap.m.WrappingType Normal

New value for property wrappingType

unbindText

Unbinds property text from model data.