Class sap.ui.commons.TextFieldModule: sap/ui/commons/TextField

extends Control

Renders an input field for text input.
Deprecated API:
Since version 1.38. Instead, use the sap.m.Input control.
Constructor Summary
new sap.ui.commons.TextField(sID?, mSettings?)Constructor for a new TextField.
Event Summary
change(oControlEvent)Event is fired when the text in the field has changed AND the focus leaves the TextField or the Enter key is pressed.
liveChange(oControlEvent)This event if fired during typing into the TextField and returns the currently entered value.
Events borrowed from class sap.ui.core.Control
Method Summary
sap.ui.commons.TextField.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.ui.commons.TextField with name sClassName and enriches it with the information contained in oClassInfo.
sap.ui.commons.TextField.getMetadata()Returns a metadata object for class sap.ui.commons.TextField.
_checkChange(oEvent)Compares the previous value with the current value and fires the change event if the TextField is editable and the value has changed.
addAriaDescribedBy(vAriaDescribedBy)Adds some ariaDescribedBy into the association ariaDescribedBy.
addAriaLabelledBy(vAriaLabelledBy)Adds some ariaLabelledBy into the association ariaLabelledBy.
attachChange(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the change event of this sap.ui.commons.TextField.
attachLiveChange(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the liveChange event of this sap.ui.commons.TextField.
bindValue(oBindingInfo)Binds property value to model data.
detachChange(fnFunction, oListener)Detaches event handler fnFunction from the change event of this sap.ui.commons.TextField.
detachLiveChange(fnFunction, oListener)Detaches event handler fnFunction from the liveChange event of this sap.ui.commons.TextField.
fireChange(mParameters?)Fires event change to attached listeners.
fireLiveChange(mParameters?)Fires event liveChange to attached listeners.
getAccessibleRole()Gets current value of property accessibleRole.
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.
getEditable()Gets current value of property editable.
getEnabled()Gets current value of property enabled.
getFocusInfo()Returns an object representing the serialized focus information
getHelpId()Gets current value of property helpId.
getImeMode()Gets current value of property imeMode.
getInputDomRef()Method for accessing the DOM Ref of the input element.
getLiveValue()Returns the current value of the TextField.
getMaxLength()Gets current value of property maxLength.
getName()Gets current value of property name.
getPlaceholder()Gets current value of property placeholder.
getRequired()Gets current value of property required.
getTextAlign()Gets current value of property textAlign.
getTextDirection()Gets current value of property textDirection.
getValue()Gets current value of property value.
getValueState()Gets current value of property valueState.
getWidth()Gets current value of property width.
onfocusin(oEvent)Event handler called when control is receiving the focus
onkeyup(oEvent)Event handler for keyup.
onsapenter(oEvent)Event handler called when enter key is pressed.
onsapfocusleave(oEvent)Event handler called when control is losing the focus
onselectstart(oEvent)Event handler called when text selection starts.
removeAllAriaDescribedBy()Removes all the controls in the association named ariaDescribedBy.
removeAllAriaLabelledBy()Removes all the controls in the association named ariaLabelledBy.
removeAriaDescribedBy(vAriaDescribedBy)Removes an ariaDescribedBy from the association named ariaDescribedBy.
removeAriaLabelledBy(vAriaLabelledBy)Removes an ariaLabelledBy from the association named ariaLabelledBy.
setAccessibleRole(sAccessibleRole)Sets a new value for property accessibleRole.
setDesign(sDesign)Sets a new value for property design.
setEditable(bEditable)Sets a new value for property editable.
setEnabled(bEnabled)Sets a new value for property enabled.
setHelpId(sHelpId)Sets a new value for property helpId.
setImeMode(sImeMode)Sets a new value for property imeMode.
setMaxLength(iMaxLength)Sets a new value for property maxLength.
setName(sName)Sets a new value for property name.
setPlaceholder(sPlaceholder)Sets a new value for property placeholder.
setRequired(bRequired)Sets a new value for property required.
setTextAlign(sTextAlign)Sets a new value for property textAlign.
setTextDirection(sTextDirection)Sets a new value for property textDirection.
setValue(sValue)Sets a new value for property value.
setValueState(sValueState)Sets a new value for property valueState.
setWidth(sWidth)Sets a new value for property width.
unbindValue()Unbinds property value from model data.
Constructor Detail
new sap.ui.commons.TextField(sID?, mSettings?)

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 for a general description of the syntax of the settings object.

The supported settings are:

  • Properties

  • Associations

  • Events

    • change : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]
    • liveChange : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]

In addition, all settings applicable to the base type sap.ui.core.Control can be used as well.

Parameters:
stringsID?id for the new control, generated automatically if no ID is given
objectmSettings?Initial settings for the new control
Event Detail
change(oControlEvent)
Event is fired when the text in the field has changed AND the focus leaves the TextField or the Enter key is pressed.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
stringoControlEvent.getParameters.newValueThe new / changed value of the TextField.
liveChange(oControlEvent)
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.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
stringoControlEvent.getParameters.liveValueCurrent visible value of the TextField.
Method Detail
sap.ui.commons.TextField.extend(sClassName, oClassInfo?, FNMetaImpl?): function

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.

Parameters:
stringsClassNameName of the class being created
objectoClassInfo?Object literal with information about the class
functionFNMetaImpl?Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
Returns:
functionCreated class / constructor function
sap.ui.commons.TextField.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.ui.commons.TextField.
Returns:
sap.ui.base.MetadataMetadata object describing this class
_checkChange(oEvent)
Compares the previous value with the current value and fires the change event if the TextField is editable and the value has changed.
Parameters:
jQuery.EventoEventThe event object.
addAriaDescribedBy(vAriaDescribedBy): sap.ui.commons.TextField
Adds some ariaDescribedBy into the association ariaDescribedBy.
Parameters:
sap.ui.core.ID|sap.ui.core.ControlvAriaDescribedBythe ariaDescribedBy to add; if empty, nothing is inserted
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
addAriaLabelledBy(vAriaLabelledBy): sap.ui.commons.TextField
Adds some ariaLabelledBy into the association ariaLabelledBy.
Parameters:
sap.ui.core.ID|sap.ui.core.ControlvAriaLabelledBythe ariaLabelledBy to add; if empty, nothing is inserted
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
attachChange(oData?, fnFunction, oListener?): sap.ui.commons.TextField

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.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.ui.commons.TextField itself
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
attachLiveChange(oData?, fnFunction, oListener?): sap.ui.commons.TextField

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.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.ui.commons.TextField itself
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
bindValue(oBindingInfo): sap.ui.commons.TextField

Binds property value to model data.

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

Parameters:
objectoBindingInfoThe binding information
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
detachChange(fnFunction, oListener): sap.ui.commons.TextField

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.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
detachLiveChange(fnFunction, oListener): sap.ui.commons.TextField

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.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
fireChange(mParameters?): sap.ui.commons.TextField
Fires event change to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
stringmParameters.newValue?The new / changed value of the TextField.
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
fireLiveChange(mParameters?): sap.ui.commons.TextField
Fires event liveChange to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
stringmParameters.liveValue?Current visible value of the TextField.
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
getAccessibilityInfo()
See:
sap.ui.core.Control#getAccessibilityInfo
getAccessibleRole(): sap.ui.core.AccessibleRole

Gets current value of property accessibleRole.

Accessibility role for the text field.

Default value is Textbox.

Returns:
sap.ui.core.AccessibleRoleValue of property accessibleRole
getAriaDescribedBy(): sap.ui.core.ID[]
Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.
Returns:
sap.ui.core.ID[]
getAriaLabelledBy(): sap.ui.core.ID[]
Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.
Returns:
sap.ui.core.ID[]
getDesign(): sap.ui.core.Design

Gets current value of property design.

Font type. valid values are Standard and Monospace.

Default value is Standard.

Returns:
sap.ui.core.DesignValue of property design
getEditable(): boolean

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.

Returns:
booleanValue of property editable
getEnabled(): boolean

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.

Returns:
booleanValue of property enabled
getFocusInfo(): object
Returns an object representing the serialized focus information
Returns:
objectan object representing the serialized focus information
getHelpId(): string

Gets current value of property helpId.

Unique identifier used for help service.

Default value is .

Returns:
stringValue of property helpId
getImeMode(): sap.ui.core.ImeMode

Gets current value of property imeMode.

State of the Input Method Editor (IME).

Default value is Auto.

Returns:
sap.ui.core.ImeModeValue of property imeMode
getInputDomRef(): object
Method for accessing the DOM Ref of the input element.
Returns:
objectDOM reference or null
getLiveValue(): string
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.
Returns:
stringlive value
getMaxLength(): int

Gets current value of property maxLength.

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

Default value is 0.

Returns:
intValue of property maxLength
getName(): string

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').

Returns:
stringValue of property name
getPlaceholder(): string

Gets current value of property placeholder.

Placeholder for the text field.

Returns:
stringValue of property placeholder
Since:
1.14.0
getRequired(): boolean

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.

Returns:
booleanValue of property required
getTextAlign(): sap.ui.core.TextAlign

Gets current value of property textAlign.

Sets the horizontal alignment of the text.

Default value is Begin.

Returns:
sap.ui.core.TextAlignValue of property textAlign
getTextDirection(): sap.ui.core.TextDirection

Gets current value of property textDirection.

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

Default value is Inherit.

Returns:
sap.ui.core.TextDirectionValue of property textDirection
getValue(): string

Gets current value of property value.

Text inside the TextField

Default value is .

Returns:
stringValue of property value
getValueState(): sap.ui.core.ValueState

Gets current value of property valueState.

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

Default value is None.

Returns:
sap.ui.core.ValueStateValue of property valueState
getWidth(): sap.ui.core.CSSSize

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.

Returns:
sap.ui.core.CSSSizeValue of property width
onfocusin(oEvent)
Event handler called when control is receiving the focus
Parameters:
jQuery.EventoEventThe event object.
onkeyup(oEvent)
Event handler for keyup. fire the liveChange event
Parameters:
jQuery.EventoEventThe event object.
onsapenter(oEvent)
Event handler called when enter key is pressed.
Parameters:
jQuery.EventoEventThe event object.
See:
sap.ui.commons.TextField#onfocusout
onsapfocusleave(oEvent)
Event handler called when control is losing the focus
Parameters:
jQuery.EventoEventThe event object.
onselectstart(oEvent)
Event handler called when text selection starts. When the text field is disabled, the text should not be selectable, so cancel the event.
Parameters:
jQuery.EventoEventThe event object.
removeAllAriaDescribedBy(): sap.ui.core.ID[]
Removes all the controls in the association named ariaDescribedBy.
Returns:
sap.ui.core.ID[]An array of the removed elements (might be empty)
removeAllAriaLabelledBy(): sap.ui.core.ID[]
Removes all the controls in the association named ariaLabelledBy.
Returns:
sap.ui.core.ID[]An array of the removed elements (might be empty)
removeAriaDescribedBy(vAriaDescribedBy): sap.ui.core.ID
Removes an ariaDescribedBy from the association named ariaDescribedBy.
Parameters:
int|sap.ui.core.ID|sap.ui.core.ControlvAriaDescribedByThe ariaDescribedBy to be removed or its index or ID
Returns:
sap.ui.core.IDThe removed ariaDescribedBy or null
removeAriaLabelledBy(vAriaLabelledBy): sap.ui.core.ID
Removes an ariaLabelledBy from the association named ariaLabelledBy.
Parameters:
int|sap.ui.core.ID|sap.ui.core.ControlvAriaLabelledByThe ariaLabelledBy to be removed or its index or ID
Returns:
sap.ui.core.IDThe removed ariaLabelledBy or null
setAccessibleRole(sAccessibleRole): sap.ui.commons.TextField

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.

Parameters:
sap.ui.core.AccessibleRolesAccessibleRoleNew value for property accessibleRole
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
setDesign(sDesign): sap.ui.commons.TextField

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.

Parameters:
sap.ui.core.DesignsDesignNew value for property design
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
setEditable(bEditable): sap.ui.commons.TextField

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.

Parameters:
booleanbEditableNew value for property editable
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
setEnabled(bEnabled): sap.ui.commons.TextField

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.

Parameters:
booleanbEnabledNew value for property enabled
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
setHelpId(sHelpId): sap.ui.commons.TextField

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 .

Parameters:
stringsHelpIdNew value for property helpId
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
setImeMode(sImeMode): sap.ui.commons.TextField

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.

Parameters:
sap.ui.core.ImeModesImeModeNew value for property imeMode
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
setMaxLength(iMaxLength): sap.ui.commons.TextField

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.

Parameters:
intiMaxLengthNew value for property maxLength
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
setName(sName): sap.ui.commons.TextField

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.

Parameters:
stringsNameNew value for property name
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
setPlaceholder(sPlaceholder): sap.ui.commons.TextField

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.

Parameters:
stringsPlaceholderNew value for property placeholder
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
Since:
1.14.0
setRequired(bRequired): sap.ui.commons.TextField

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.

Parameters:
booleanbRequiredNew value for property required
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
setTextAlign(sTextAlign): sap.ui.commons.TextField

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.

Parameters:
sap.ui.core.TextAlignsTextAlignNew value for property textAlign
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
setTextDirection(sTextDirection): sap.ui.commons.TextField

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.

Parameters:
sap.ui.core.TextDirectionsTextDirectionNew value for property textDirection
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
setValue(sValue): sap.ui.commons.TextField

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 .

Parameters:
stringsValueNew value for property value
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
setValueState(sValueState): sap.ui.commons.TextField

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.

Parameters:
sap.ui.core.ValueStatesValueStateNew value for property valueState
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
setWidth(sWidth): sap.ui.commons.TextField

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.

Parameters:
sap.ui.core.CSSSizesWidthNew value for property width
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining
unbindValue(): sap.ui.commons.TextField
Unbinds property value from model data.
Returns:
sap.ui.commons.TextFieldReference to this in order to allow method chaining