class sap.ui.commons.TextField

Control sample: sap.ui.commons.TextField
Visiblity: public
UX Guidelines:
Implements: sap.ui.commons.ToolbarItemsap.ui.core.IFormContent
Available since: N/A
Module: sap/ui/commons/TextField
Application Component: CA-UI5-CTR

Renders an input field for text input.


Constructor

Constructor for a new TextField.

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.ui.commons.TextField(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
accessibleRole sap.ui.core.AccessibleRole Textbox

Accessibility role for the text field.

Visibility: public
design sap.ui.core.Design Standard

Font type. valid values are Standard and Monospace.

Visibility: public
editable boolean true

Switches edit state of the control. Read-only fields have different colors, depending on theme setting.

Visibility: public
enabled boolean true

Switches enabled state of the control. Disabled fields have different colors, and can not be focused.

Visibility: public
helpId string empty string

Unique identifier used for help service.

Visibility: public
imeMode sap.ui.core.ImeMode Auto

State of the Input Method Editor (IME).

Visibility: public
maxLength int 0

Maximum number of characters. Value '0' means the feature is switched off.

Visibility: public
name string

The name property to be used in the HTML code (e.g. for HTML forms that send data to the server via 'submit').

Visibility: public
placeholder string

Placeholder for the text field.

Since: 1.14.0.

Visibility: public
required boolean false

Depending on theme the TextField is shown as required. If a Label is assigned to the TextField it will visualize the requires state too.

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

Sets the horizontal alignment of the text.

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

Direction of the text. Possible values: "rtl", "ltr".

Visibility: public
value string empty string

Text inside the TextField

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

Visualizes warnings or errors related to the text field. Possible values: Warning, Error, Success.

Visibility: public
width sap.ui.core.CSSSize

Width of text field. When it is set (CSS-size such as % or px), this is the exact size. When left blank, the text field length defines the width.

Visibility: public

Associations

Name Cardinality Type Description
ariaDescribedBy 0..n sap.ui.core.Control

Association to controls / IDs which describe this control (see WAI-ARIA attribute aria-describedby).

ariaLabelledBy 0..n sap.ui.core.Control

Association to controls / IDs which label this control (see WAI-ARIA attribute aria-labelledby).


Events Overview

Event Description
change

Event is fired when the text in the field has changed AND the focus leaves the TextField or the Enter key is pressed.

liveChange

This event if fired during typing into the TextField and returns the currently entered value. Note: This is not the content of the value property. The value property is only updated by ENTER and by leaving the control.

change

Event is fired when the text in the field has changed AND the focus leaves the TextField or the Enter key is pressed.

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

The new / changed value of the TextField.

liveChange

This event if fired during typing into the TextField and returns the currently entered value. Note: This is not the content of the value property. The value property is only updated by ENTER and by leaving the control.

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

Current visible value of the TextField.


Methods Overview

Method Description
_checkChange

Compares the previous value with the current value and fires the change event if the TextField is editable and the value has changed.

addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

attachChange

Attaches event handler fnFunction to the change event of this sap.ui.commons.TextField.

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.ui.commons.TextField itself.

Event is fired when the text in the field has changed AND the focus leaves the TextField or the Enter key is pressed.

attachLiveChange

Attaches event handler fnFunction to the liveChange event of this sap.ui.commons.TextField.

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.ui.commons.TextField itself.

This event if fired during typing into the TextField and returns the currently entered value. Note: This is not the content of the value property. The value property is only updated by ENTER and by leaving the control.

bindValue

Binds property value to model data.

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

detachChange

Detaches event handler fnFunction from the change event of this sap.ui.commons.TextField.

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

detachLiveChange

Detaches event handler fnFunction from the liveChange event of this sap.ui.commons.TextField.

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

sap.ui.commons.TextField.extend

Creates a new subclass of class sap.ui.commons.TextField 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.

fireChange

Fires event change to attached listeners.

fireLiveChange

Fires event liveChange to attached listeners.

getAccessibilityInfo

References:

  • sap.ui.core.Control#getAccessibilityInfo

getAccessibleRole

Gets current value of property accessibleRole.

Accessibility role for the text field.

Default value is Textbox.

getAriaDescribedBy

Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getDesign

Gets current value of property design.

Font type. valid values are Standard and Monospace.

Default value is Standard.

getEditable

Gets current value of property editable.

Switches edit state of the control. Read-only fields have different colors, depending on theme setting.

Default value is true.

getEnabled

Gets current value of property enabled.

Switches enabled state of the control. Disabled fields have different colors, and can not be focused.

Default value is true.

getFocusInfo

Returns an object representing the serialized focus information

getHelpId

Gets current value of property helpId.

Unique identifier used for help service.

Default value is empty string.

getImeMode

Gets current value of property imeMode.

State of the Input Method Editor (IME).

Default value is Auto.

getInputDomRef

Method for accessing the DOM Ref of the input element.

getLiveValue

Returns the current value of the TextField. In case of editing the TextField you can access the current value via this method. The validated value is accessible via the property value.

getMaxLength

Gets current value of property maxLength.

Maximum number of characters. Value '0' means the feature is switched off.

Default value is 0.

sap.ui.commons.TextField.getMetadata

Returns a metadata object for class sap.ui.commons.TextField.

getName

Gets current value of property name.

The name property to be used in the HTML code (e.g. for HTML forms that send data to the server via 'submit').

getPlaceholder

Gets current value of property placeholder.

Placeholder for the text field.

getRequired

Gets current value of property required.

Depending on theme the TextField is shown as required. If a Label is assigned to the TextField it will visualize the requires state too.

Default value is false.

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.

Direction of the text. Possible values: "rtl", "ltr".

Default value is Inherit.

getValue

Gets current value of property value.

Text inside the TextField

Default value is empty string.

getValueState

Gets current value of property valueState.

Visualizes warnings or errors related to the text field. Possible values: Warning, Error, Success.

Default value is None.

getWidth

Gets current value of property width.

Width of text field. When it is set (CSS-size such as % or px), this is the exact size. When left blank, the text field length defines the width.

onfocusin

Event handler called when control is receiving the focus

onkeyup

Event handler for keyup. fire the liveChange event

onsapenter

Event handler called when enter key is pressed.

References:

  • sap.ui.commons.TextField#onfocusout

onsapfocusleave

Event handler called when control is losing the focus

onselectstart

Event handler called when text selection starts. When the text field is disabled, the text should not be selectable, so cancel the event.

removeAllAriaDescribedBy

Removes all the controls in the association named ariaDescribedBy.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAriaDescribedBy

Removes an ariaDescribedBy from the association named ariaDescribedBy.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

setAccessibleRole

Sets a new value for property accessibleRole.

Accessibility role for the text field.

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

Default value is Textbox.

setDesign

Sets a new value for property design.

Font type. valid values are Standard and Monospace.

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

Default value is Standard.

setEditable

Sets a new value for property editable.

Switches edit state of the control. Read-only fields have different colors, depending on theme setting.

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

Default value is true.

setEnabled

Sets a new value for property enabled.

Switches enabled state of the control. Disabled fields have different colors, and can not be focused.

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

Default value is true.

setHelpId

Sets a new value for property helpId.

Unique identifier used for help service.

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

Default value is empty string.

setImeMode

Sets a new value for property imeMode.

State of the Input Method Editor (IME).

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

Default value is Auto.

setMaxLength

Sets a new value for property maxLength.

Maximum number of characters. Value '0' means the feature is switched off.

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

Default value is 0.

setName

Sets a new value for property name.

The name property to be used in the HTML code (e.g. for HTML forms that send data to the server via 'submit').

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

setPlaceholder

Sets a new value for property placeholder.

Placeholder for the text field.

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

setRequired

Sets a new value for property required.

Depending on theme the TextField is shown as required. If a Label is assigned to the TextField it will visualize the requires state too.

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

Default value is false.

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.

Direction of the text. Possible values: "rtl", "ltr".

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

Default value is Inherit.

setValue

Sets a new value for property value.

Text inside the TextField

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

Default value is empty string.

setValueState

Sets a new value for property valueState.

Visualizes warnings or errors related to the text field. Possible values: Warning, Error, Success.

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

Default value is None.

setWidth

Sets a new value for property width.

Width of text field. When it is set (CSS-size such as % or px), this is the exact size. When left blank, the text field length defines the width.

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

unbindValue

Unbinds property value from model data.

_checkChange

Compares the previous value with the current value and fires the change event if the TextField is editable and the value has changed.

Param Type DefaultValue Description
oEvent jQuery.Event

The event object.

addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

Param Type DefaultValue Description
vAriaDescribedBy sap.ui.core.ID sap.ui.core.Control

The ariaDescribedBy to add; if empty, nothing is inserted

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to add; if empty, nothing is inserted

attachChange

Attaches event handler fnFunction to the change event of this sap.ui.commons.TextField.

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.ui.commons.TextField itself.

Event is fired when the text in the field has changed AND the focus leaves the TextField or the Enter key is pressed.

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.ui.commons.TextField itself

attachLiveChange

Attaches event handler fnFunction to the liveChange event of this sap.ui.commons.TextField.

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.ui.commons.TextField itself.

This event if fired during typing into the TextField and returns the currently entered value. Note: This is not the content of the value property. The value property is only updated by ENTER and by leaving the control.

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.ui.commons.TextField itself

bindValue

Binds property value 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

detachChange

Detaches event handler fnFunction from the change event of this sap.ui.commons.TextField.

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

detachLiveChange

Detaches event handler fnFunction from the liveChange event of this sap.ui.commons.TextField.

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.ui.commons.TextField.extend

Creates a new subclass of class sap.ui.commons.TextField 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

fireChange

Fires event change to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

newValue string

The new / changed value of the TextField.

fireLiveChange

Fires event liveChange to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

liveValue string

Current visible value of the TextField.

getAccessibilityInfo

References:

getAccessibleRole

Gets current value of property accessibleRole.

Accessibility role for the text field.

Default value is Textbox.

getAriaDescribedBy

Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getDesign

Gets current value of property design.

Font type. valid values are Standard and Monospace.

Default value is Standard.

getEditable

Gets current value of property editable.

Switches edit state of the control. Read-only fields have different colors, depending on theme setting.

Default value is true.

getEnabled

Gets current value of property enabled.

Switches enabled state of the control. Disabled fields have different colors, and can not be focused.

Default value is true.

getFocusInfo

Returns an object representing the serialized focus information

getHelpId

Gets current value of property helpId.

Unique identifier used for help service.

Default value is empty string.

getImeMode

Gets current value of property imeMode.

State of the Input Method Editor (IME).

Default value is Auto.

getInputDomRef

Method for accessing the DOM Ref of the input element.

getLiveValue

Returns the current value of the TextField. In case of editing the TextField you can access the current value via this method. The validated value is accessible via the property value.

getMaxLength

Gets current value of property maxLength.

Maximum number of characters. Value '0' means the feature is switched off.

Default value is 0.

sap.ui.commons.TextField.getMetadata

Returns a metadata object for class sap.ui.commons.TextField.

getName

Gets current value of property name.

The name property to be used in the HTML code (e.g. for HTML forms that send data to the server via 'submit').

getPlaceholder

Gets current value of property placeholder.

Placeholder for the text field.

getRequired

Gets current value of property required.

Depending on theme the TextField is shown as required. If a Label is assigned to the TextField it will visualize the requires state too.

Default value is false.

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.

Direction of the text. Possible values: "rtl", "ltr".

Default value is Inherit.

getValue

Gets current value of property value.

Text inside the TextField

Default value is empty string.

getValueState

Gets current value of property valueState.

Visualizes warnings or errors related to the text field. Possible values: Warning, Error, Success.

Default value is None.

getWidth

Gets current value of property width.

Width of text field. When it is set (CSS-size such as % or px), this is the exact size. When left blank, the text field length defines the width.

onfocusin

Event handler called when control is receiving the focus

Param Type DefaultValue Description
oEvent jQuery.Event

The event object.

onkeyup

Event handler for keyup. fire the liveChange event

Param Type DefaultValue Description
oEvent jQuery.Event

The event object.

onsapenter

Event handler called when enter key is pressed.

References:

Param Type DefaultValue Description
oEvent jQuery.Event

The event object.

onsapfocusleave

Event handler called when control is losing the focus

Param Type DefaultValue Description
oEvent jQuery.Event

The event object.

onselectstart

Event handler called when text selection starts. When the text field is disabled, the text should not be selectable, so cancel the event.

Param Type DefaultValue Description
oEvent jQuery.Event

The event object.

removeAllAriaDescribedBy

Removes all the controls in the association named ariaDescribedBy.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAriaDescribedBy

Removes an ariaDescribedBy from the association named ariaDescribedBy.

Param Type DefaultValue Description
vAriaDescribedBy int sap.ui.core.ID sap.ui.core.Control

The ariaDescribedBy to be removed or its index or ID

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy int sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to be removed or its index or ID

setAccessibleRole

Sets a new value for property accessibleRole.

Accessibility role for the text field.

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

Default value is Textbox.

Param Type DefaultValue Description
sAccessibleRole sap.ui.core.AccessibleRole Textbox

New value for property accessibleRole

setDesign

Sets a new value for property design.

Font type. valid values are Standard and Monospace.

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

Default value is Standard.

Param Type DefaultValue Description
sDesign sap.ui.core.Design Standard

New value for property design

setEditable

Sets a new value for property editable.

Switches edit state of the control. Read-only fields have different colors, depending on theme setting.

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
bEditable boolean true

New value for property editable

setEnabled

Sets a new value for property enabled.

Switches enabled state of the control. Disabled fields have different colors, and can not be focused.

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
bEnabled boolean true

New value for property enabled

setHelpId

Sets a new value for property helpId.

Unique identifier used for help service.

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
sHelpId string ''

New value for property helpId

setImeMode

Sets a new value for property imeMode.

State of the Input Method Editor (IME).

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

Default value is Auto.

Param Type DefaultValue Description
sImeMode sap.ui.core.ImeMode Auto

New value for property imeMode

setMaxLength

Sets a new value for property maxLength.

Maximum number of characters. Value '0' means the feature is switched off.

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

setName

Sets a new value for property name.

The name property to be used in the HTML code (e.g. for HTML forms that send data to the server via 'submit').

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

Param Type DefaultValue Description
sName string

New value for property name

setPlaceholder

Sets a new value for property placeholder.

Placeholder for the text field.

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

Param Type DefaultValue Description
sPlaceholder string

New value for property placeholder

setRequired

Sets a new value for property required.

Depending on theme the TextField is shown as required. If a Label is assigned to the TextField it will visualize the requires state too.

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

New value for property required

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.

Direction of the text. Possible values: "rtl", "ltr".

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

setValue

Sets a new value for property value.

Text inside the TextField

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
sValue string ''

New value for property value

setValueState

Sets a new value for property valueState.

Visualizes warnings or errors related to the text field. Possible values: Warning, Error, Success.

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
sValueState sap.ui.core.ValueState None

New value for property valueState

setWidth

Sets a new value for property width.

Width of text field. When it is set (CSS-size such as % or px), this is the exact size. When left blank, the text field length defines the width.

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

unbindValue

Unbinds property value from model data.