Input Mask

• Jul 29, 2019
• 5 minutes to read

Overview

Text editors support input masks. An input mask restricts the data input and formats data output. For example, a text editor should only accept phone numbers or date-time values in 24-hour format.

Note

Run the XtraEditors demo to try out input masks.

All TextEdit descendants support input masks except LookUpEdit, GridLookUpEdit, TreeListLookUpEdit, MemoEdit, MemoExEdit, and ImageComboBoxEdit controls.

Specify Input Mask in Designer

Use Mask Editor to specify an input mask. To invoke the editor, click the TextEdit.Properties.Mask property’s ellipsis button in the Properties window. The editor allows you to apply a predefined mask or create a custom mask.

You can also specify mask settings in Visual Studio’s Properties window.

Mask Expression and Mask Type

The TextEdit.Properties.Mask property provides access to a MaskProperties class instance that specifies an input mask. Use the MaskProperties.EditMask and MaskProperties.MaskType properties to specify the mask expression and type (the expression is parsed according to the type). The following table lists available types.

Mask Type	Use Case	Description	Example (the result depends on the current culture)
Simple	An editor should accept values in a fixed format without alternatives. For instance, phone numbers and alpha-numeric sequences.	The mask expression can contain meta, special, and literal characters. See Mask Type: Simple for more information.	[phone]
Numeric	An editor should accept numeric values in a specific format.	Use the standard numeric .Net format to specify mask expressions. See Mask Type: Numeric for more information.	c # ##0.00 $;(# ##0.00 $)
DateTime, DateTimeAdvancingCaret	An editor should accept date-time values in a specific format.	Use the standard date-time .Net format to specify mask expressions. See Mask Type: Date-time for more information.	D yyyy-MMM-d, HH:mm:ss
RegEx	An editor should accept values with a custom range of characters at a specific position. An editor should accept values of indeterminate length. An editor should accept values in one of several formats. An editor should support the auto-complete feature.	Use the extended regular expression syntax to specify mask expressions. This syntax is similar to the syntax defined in the POSIX ERE specification. See Mask Type: Extended Regular Expressions for more information.	((\+\d)?\(\d{3}\))?\d{3}-\d\d-\d\d
Regular	An editor should accept values with a custom range of characters at a specific position. An editor should accept values of indeterminate length.	Use the simplified regular expression syntax to specify mask expressions. See Mask Type: Simplified Regular Expressions for more information. Note This type supports backward compatibility with XtraEditors version 2. We recommend you use RegEx type instead.	[0-9A-F]*
None	An editor should not provide a masked input.	The input mask is disabled.

The code below shows how to enable the long date format.

C#

textEdit1.Properties.Mask.MaskType = DevExpress.XtraEditors.Mask.MaskType.DateTime;
textEdit1.Properties.Mask.EditMask = "D";

VB.NET

TextEdit1.Properties.Mask.MaskType = DevExpress.XtraEditors.Mask.MaskType.DateTime
TextEdit1.Properties.Mask.EditMask = "D"

Options

The MaskProperties class also contains the following options (depending on the mask type):

Option	MaskType.DateTime	MaskType.Numeric	MaskType.Simple	MaskType.Regular	MaskType.RegEx
BeepOnError
SaveLiteral
IgnoreMaskBlank
PlaceHolder
ShowPlaceHolders
AutoComplete

Input Mask as Output Format

The TextEdit.Properties.DisplayFormat property specifies how to format the editor’s value when it is not focused. Enable the TextEdit.Properties.Mask.UseMaskAsDisplayFormat setting to use the input mask as an output format.

BeepOnError Option

Set the MaskProperties.BeepOnError property to true to play the beep system sound when a user enters an invalid character. For example, a user enters a letter in an editor that accepts numbers only.

SaveLiteral Option

The MaskProperties.SaveLiteral property specifies whether the text editor’s value comprises mask literals. For example, an editor accepts phone numbers in the specified format and the user enters [phone]. If this option is enabled, the editor’s EditValue property equals [phone]; otherwise, the property equals 5551234567.

PlaceHolder and ShowPlaceHolders Options

Use the MaskProperties.PlaceHolder property to change the default _ placeholder. Placeholders can be hidden for the RegEx type with the MaskProperties.ShowPlaceHolders property.

The following images show an empty text editor whose mask is set to the CODE-\d{3}-NO-\d{3} regular expression. In the first image, placeholders are shown. In the second image, placeholders are hidden.

IgnoreMaskBlank Option

The MaskProperties.IgnoreMaskBlank property specifies whether the editor can lose focus if its value is not completely entered. If the setting is enabled, the editor can only lose focus if the user completes the value or discards the changes. Use the BaseEdit.InvalidValue event to show an error message.

AutoComplete Option

The MaskProperties.AutoComplete property specifies auto-complete mode.

Mode	Description	Example
Strong, Default	The editor completes the value by one character at a time.	If the mask expression is \R{MonthNames}, the editor accepts month names. When the user enters ‘M’, the editor automatically adds ‘a’ because March and May start with ‘Ma’. Then, if the user types ‘r’, the editor automatically completes the value with ‘March’.
Optimistic	The editor completes the value at once. The default letter is ‘a’, the default number is ‘0’.	The mask expression is \R{MonthNames}. If the user enters ‘M’, the editor automatically completes the value with ‘May’ since it is the shortest variant between March and May. The editor accepts phone numbers in the \d{3}-\d{2}-\d{2} format. If the user enters ‘1’, the editor automatically fills in all other places with ‘0’.