Input Mask

  • 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)

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

CD_MaskOverview_RegEx_phone1

CD_MaskOverview_RegEx_phone2

CD_MaskOverview_RegEx_phone3

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

CD_MaskOverview_Numeric_c

  • # ##0.00 $;(# ##0.00 $)

CD_MaskOverview_Numeric_custom

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

CD_MaskOverview_DateTime_D

  • yyyy-MMM-d, HH:mm:ss

CD_MaskOverview_DateTime_Custom

TimeSpan, TimeSpanAdvancingCaret

An editor should accept time span values in a specific format.

Use the standard time span .Net format to specify mask expressions. See Mask Type: TimeSpan for more information.

  • c

  • d.hh:mm:ss.fffffff

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.

  • (999)000-00-00

CD_MaskOverview_Simple_phone

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]*

CD_MaskOverview_Simple_phone

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.

CD_Mask_DateTime_D-long


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 (555)123-45-67. If this option is enabled, the editor's EditValue property equals (555)123-45-67; 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.

CD_Mask_ShowPlaceholder_true

CD_Mask_ShowPlaceholder_false

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.

CD_Mask_IgnoreMaskBlank_false

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

CD_Mask_AutoComplete_Strong_1

Then, if the user types 'r', the editor automatically completes the value with 'March'.

CD_Mask_AutoComplete_Strong_2

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.

    CD_Mask_AutoComplete_Optimistic1

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

    CD_Mask_AutoComplete_Optimistic

See Also