class sap.m.MaskInput

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

The sap.m.MaskInput control allows users to easily enter data in a certain format and in a fixed-width input (for example: date, time, phone number, credit card number, currency, IP address, MAC address, and others).

This control can be a drop target.

Constructor

Constructor for a new MaskInput.

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.MaskInput(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
effectiveShowClearIcon boolean false

Specifies whether the clear icon should be shown/hidden on user interaction.

Visibility: hidden
mask string

Mask defined by its characters type (respectively, by its length). You should consider the following important facts: 1. The mask characters normally correspond to an existing rule (one rule per unique char). Characters which don't, are considered immutable characters (for example, the mask '2099', where '9' corresponds to a rule for digits, has the characters '2' and '0' as immutable). 2. Adding a rule corresponding to the placeholderSymbol is not recommended and would lead to an unpredictable behavior. 3. You can use the special escape character '^' called "Caret" prepending a rule character to make it immutable. Use the double escape '^^' if you want to make use of the escape character as an immutable one.

Visibility: public
placeholderSymbol string _

Defines a placeholder symbol. Shown at the position where there is no user input yet.

Visibility: public
showClearIcon boolean false

Specifies whether a clear icon is shown. Pressing the icon will clear input's value and fire the change event.

Since: 1.96.

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
rules 0..n sap.m.MaskInputRule

A list of validation rules (one rule per mask character).

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.


Methods Overview

Method Description
addRule

Adds some rule to the aggregation rules.

destroyRules

Destroys all the rules in the aggregation rules.

sap.m.MaskInput.extend

Creates a new subclass of class sap.m.MaskInput 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.

getMask

Gets current value of property mask.

Mask defined by its characters type (respectively, by its length). You should consider the following important facts: 1. The mask characters normally correspond to an existing rule (one rule per unique char). Characters which don't, are considered immutable characters (for example, the mask '2099', where '9' corresponds to a rule for digits, has the characters '2' and '0' as immutable). 2. Adding a rule corresponding to the placeholderSymbol is not recommended and would lead to an unpredictable behavior. 3. You can use the special escape character '^' called "Caret" prepending a rule character to make it immutable. Use the double escape '^^' if you want to make use of the escape character as an immutable one.

sap.m.MaskInput.getMetadata

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

getPlaceholderSymbol

Gets current value of property placeholderSymbol.

Defines a placeholder symbol. Shown at the position where there is no user input yet.

Default value is "_".

getRules

Gets content of aggregation rules.

A list of validation rules (one rule per mask character).

getShowClearIcon

Gets current value of property showClearIcon.

Specifies whether a clear icon is shown. Pressing the icon will clear input's value and fire the change event.

Default value is false.

indexOfRule

Checks for the provided sap.m.MaskInputRule in the aggregation rules. and returns its index if found or -1 otherwise.

insertRule

Inserts a rule into the aggregation rules.

removeAllRules

Removes all the controls from the aggregation rules.

Additionally, it unregisters them from the hosting UIArea.

removeRule

Removes a rule from the aggregation rules.

setMask

Sets a new value for property mask.

Mask defined by its characters type (respectively, by its length). You should consider the following important facts: 1. The mask characters normally correspond to an existing rule (one rule per unique char). Characters which don't, are considered immutable characters (for example, the mask '2099', where '9' corresponds to a rule for digits, has the characters '2' and '0' as immutable). 2. Adding a rule corresponding to the placeholderSymbol is not recommended and would lead to an unpredictable behavior. 3. You can use the special escape character '^' called "Caret" prepending a rule character to make it immutable. Use the double escape '^^' if you want to make use of the escape character as an immutable one.

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

setPlaceholderSymbol

Sets a new value for property placeholderSymbol.

Defines a placeholder symbol. Shown at the position where there is no user input yet.

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

Default value is "_".

setShowClearIcon

Sets a new value for property showClearIcon.

Specifies whether a clear icon is shown. Pressing the icon will clear input's value and fire the change event.

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

Default value is false.

addRule

Adds some rule to the aggregation rules.

Param Type DefaultValue Description
oRule sap.m.MaskInputRule

The rule to add; if empty, nothing is inserted

destroyRules

Destroys all the rules in the aggregation rules.

sap.m.MaskInput.extend

Creates a new subclass of class sap.m.MaskInput 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

getMask

Gets current value of property mask.

Mask defined by its characters type (respectively, by its length). You should consider the following important facts: 1. The mask characters normally correspond to an existing rule (one rule per unique char). Characters which don't, are considered immutable characters (for example, the mask '2099', where '9' corresponds to a rule for digits, has the characters '2' and '0' as immutable). 2. Adding a rule corresponding to the placeholderSymbol is not recommended and would lead to an unpredictable behavior. 3. You can use the special escape character '^' called "Caret" prepending a rule character to make it immutable. Use the double escape '^^' if you want to make use of the escape character as an immutable one.

sap.m.MaskInput.getMetadata

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

getPlaceholderSymbol

Gets current value of property placeholderSymbol.

Defines a placeholder symbol. Shown at the position where there is no user input yet.

Default value is "_".

getRules

Gets content of aggregation rules.

A list of validation rules (one rule per mask character).

getShowClearIcon

Gets current value of property showClearIcon.

Specifies whether a clear icon is shown. Pressing the icon will clear input's value and fire the change event.

Default value is false.

indexOfRule

Checks for the provided sap.m.MaskInputRule in the aggregation rules. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oRule sap.m.MaskInputRule

The rule whose index is looked for

insertRule

Inserts a rule into the aggregation rules.

Param Type DefaultValue Description
oRule sap.m.MaskInputRule

The rule to insert; if empty, nothing is inserted

iIndex int

The 0-based index the rule should be inserted at; for a negative value of iIndex, the rule is inserted at position 0; for a value greater than the current size of the aggregation, the rule is inserted at the last position

removeAllRules

Removes all the controls from the aggregation rules.

Additionally, it unregisters them from the hosting UIArea.

removeRule

Removes a rule from the aggregation rules.

Param Type DefaultValue Description
vRule int string sap.m.MaskInputRule

The rule to remove or its index or id

setMask

Sets a new value for property mask.

Mask defined by its characters type (respectively, by its length). You should consider the following important facts: 1. The mask characters normally correspond to an existing rule (one rule per unique char). Characters which don't, are considered immutable characters (for example, the mask '2099', where '9' corresponds to a rule for digits, has the characters '2' and '0' as immutable). 2. Adding a rule corresponding to the placeholderSymbol is not recommended and would lead to an unpredictable behavior. 3. You can use the special escape character '^' called "Caret" prepending a rule character to make it immutable. Use the double escape '^^' if you want to make use of the escape character as an immutable one.

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

Param Type DefaultValue Description
sMask string

New value for property mask

setPlaceholderSymbol

Sets a new value for property placeholderSymbol.

Defines a placeholder symbol. Shown at the position where there is no user input yet.

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

Default value is "_".

Param Type DefaultValue Description
sPlaceholderSymbol string "_"

New value for property placeholderSymbol

setShowClearIcon

Sets a new value for property showClearIcon.

Specifies whether a clear icon is shown. Pressing the icon will clear input's value and fire the change event.

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

New value for property showClearIcon