Mask Type: Simple
- 4 minutes to read
The Simple mask type allows users to enter alphabetic, numeric or alphanumeric characters at specific positions. For example, phone numbers, zip codes, and social security numbers.
Run this Demo Center module to test various input masks: Mask Box.
Metacharacters
A metacharacter specifies a range of characters that users can enter. The following table lists the available metacharacters.
| Character | Description |
|---|---|
L |
A mandatory alphabetic character. For example, A-Z, a-z for the U.S. |
l |
An optional alphabetic character. |
A |
A mandatory alphanumeric character. For example, A-Z, a-z, 0-9 for the U.S. |
a |
An optional alphanumeric character. |
C |
A mandatory arbitrary character. |
c |
An optional arbitrary character. |
0 |
A mandatory numeric character. |
9 |
An optional numeric character. |
# |
An optional numeric character, the plus or minus sign. |
Special Characters
Special characters convert to uppercase/lowercase, add date/time separators, etc. The following table lists the available special characters.
| Character | Description |
|---|---|
> |
Converts subsequent characters to uppercase. |
< |
Converts subsequent characters to lowercase. |
<> |
Discards case conversion for subsequent characters. |
/ |
Separates months, days, and years. The culture’s DateSeparator property specifies the actual character. |
: |
Separates hours, minutes, and seconds. The culture’s TimeSeparator property specifies the actual character. |
$ |
Inserts the currency symbol. The culture’s CurrencySymbol property specifies the actual character. |
Literal Characters
Literal characters are arbitrary read-only characters in the edit box. If you add a character that is not a meta or special character into a mask expression, the character is displayed in the edit box as is. To display a meta or special character as a literal, precede it with a backslash.
Examples
Example 1
(000)000-00-00 - a mask that allows users to enter a phone number. Each ‘0’ metacharacter requires a user to enter a digit. Dashes and brackets are literals.
Value is not entered:
Value is entered:
Example 2
(999)000-00-00 - a phone number with an optional area code. Each ‘9‘ metacharacter allows users to omit a digit.
Value is a valid phone number without a code part:
Example 3
\A>LL-00 - a mask to enter two upper-case letters and two numbers separated by a dash and preceded with the ‘A‘ literal. A backslash precedes the literal to distinguish it from a metacharacter.
Value is not entered:
Value is entered:
Simple Mask Options
When you click the ellipsis button next to the MaskSettings property, the Mask Settings dialog appears. Click “Show Advanced Options” in the bottom left corner to view optional Simple Mask settings.
“Placeholder character”
Allows you to choose a character displayed for empty metacharacters. The default placeholder character is underscore (“_”).
//Fluent API
using DevExpress.XtraEditors.Mask;
textEdit5.Properties.MaskSettings.Configure<MaskSettings.Simple>(settings => {
settings.MaskExpression = "(000)000-00-00";
settings.Placeholder = '?';
});
//regular API
using DevExpress.XtraEditors.Mask;
var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.Simple>();
settings.MaskExpression = "(000)000-00-00";
settings.Placeholder = '?';
//Data Annotation Attribute (for code-first sources)
using System.ComponentModel.DataAnnotations;
[SimpleEditMask("(000)000-00-00", Placeholder = '?')]
public string PhoneNumber { get; set; }
“Save static literals to edit value”
This property specifies whether read-only literal characters should be saved to the editor’s EditValue. For example, if the editor mask is “ID: 00000”, the editor saves only five digits as its EditValue if this property is disabled, and the entire “ID: 12345” string if enabled.
//Fluent API
using DevExpress.XtraEditors.Mask;
textEdit5.Properties.MaskSettings.Configure<MaskSettings.Simple>(settings => {
settings.MaskExpression = "ID: 00000";
settings.SaveLiterals = true;
});
//regular API
using DevExpress.XtraEditors.Mask;
var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.Simple>();
settings.MaskExpression = "ID: 00000";
settings.SaveLiterals = true;
//Data Annotation Attribute (for code-first sources)
using System.ComponentModel.DataAnnotations;
[SimpleEditMask("ID: 00000", SaveLiterals = true)]
public string PhoneNumber { get; set; }