Input Mask

  • 5 minutes to read

Input masks restrict data input and allow you to guide users to enter correct values. For instance, you can apply the phone number "(000)000-00-00" mask, so that users are unable to enter anything but 10 digits in the given format.

Phone number mask

Input masks are in effect only when an editor is focused. Inactive editors can use a different format to display their values (the display format). The following figure illustrates an editor with a "long date" input mask and a "short date" display format.

Masks and display formats

Masks are supported for all TextEdit descendants, except for the following editors:

Run this Demo Center module to test various input masks: Mask Box.

Mask Types

DevExpress editors support multiple mask types. Each type allows you to choose from a variety of predefined mask expressions, or build your own.

  • DateTime type - allows you to specify masks for date and time values. Uses the standard .NET numeric format for mask expressions.

  • DateTime with Offset type - includes same mask expressions as the regular "DateTime" type, and additionally displays a user time zone.

  • Numeric type - allows an editor to accept only numeric values (percentages, currecies, etc.).

  • Extended Regular Expressions type - use these masks if an editor should do one of the following:

  • accept values with a custom range of characters at a specific position (for instance, a 16-character licence code where each character can be either a digit or a letter);
  • accept values of an indeterminate length (for instance, an e-mail address);
  • accept values in either of multiple allowed formats;
  • auto-complete values entered by a user.

Mask expression syntax is similar to that of the POSIX ERE specification.

  • Simple type - use masks of this type when an editor should accept values in a fixed format without alternatives (for instance, phone numbers or zip codes).

  • TimeSpan type - allows users to enter time intervals.

  • Simplified Regular Expressions - the simplified version of the "Extended Regular Expressions" Mask type. Supports backward compatibility with XtraEditors v2.0. We recommend that you use the RegEx type instead.

How to Apply Masks

In Visual Studio Designer

In the Visual Studio Property Grid, click the ellipsis button next to the Properties.MaskSettings property. In the "Mask Settings" dialog that pops up, select the required mask type and choose any of the predefined expressions. To specify additional mask settings, tick the corresponding checkbox at the bottom left corner of a dialog. Available settings depend on the active mask type.

Mask Settings Dialog

If there is no ready-to-use expression that fits your needs, click "Create New Mask..." and combine metacharacters to create a custom expression.

Custom RegEx mask

In Code

To set up a mask expression and configure mask settings in code, use the MaskSettings.Configure method. This method requires that you specify one of the following types defined in the DevExpress.Data.Mask.Internal namespace:

  • MaskSettings.Numeric
  • MaskSettings.DateTime
  • MaskSettings.DateTimeOffset
  • MaskSettings.TimeSpan
  • MaskSettings.Simple
  • MaskSettings.Regular
  • MaskSettings.RegExp

For example, the following code applies a numeric mask that allows users to enter decimal numbers in the "000.00" format, and specifies two additional settings: hides zeros that do not affect the value ("0.9" instead of "0.9"), and show a decimal separator even when the fractional part is 0 ("110." instead of "110").

using DevExpress.XtraEditors.Mask;

//Fluent API
textEdit5.Properties.MaskSettings.Configure<MaskSettings.Numeric>(settings => {
    settings.MaskExpression = "##0.##";
    settings.AutoHideDecimalSeparator = false;
    settings.HideInsignificantZeros = true;
});

//regular API
var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.Numeric>();
settings.MaskExpression = "##0.##";
settings.AutoHideDecimalSeparator = false;
settings.HideInsignificantZeros = true;

At the Data Source Layer

If your editor is bound to a field of a code-first data source, you can decorate this field with an "...EditMask" attribute. An editor bound to this field applies a mask of the required type, and sets up additional options you specified as attribute parameters.

For example, the following code applies two masks:

  • a RegEx type mask that accepts any number of literals and automatically capitalizes the first character. The AllowBlankInput parameter allows users to leave this editor empty, and disabled ShowPlaceholders hides placeholders.
  • a DateTime type mask that displays dates in the short "MM/DD/YYYY" format.
public class Employee {
    [RegExEditMask("[A-Z][a-z]+", AllowBlankInput = true, ShowPlaceholders = false)]
    public string FirstName { get; set; }
    [EditMask("d")]
    public DateTime HiredAt { get; set; }
}

The list below enumerates available data attributes. All attributes are declared in the System.ComponentModel.DataAnnotations namespace and stored in the DevExpress.Data assembly.

  • NumericEditMask
  • DateTimeEditMask
  • DateTimeOffsetEditMask
  • TimeSpanEditMask
  • SimpleEditMask
  • RegularEditMask
  • RegExEditMask

The EditMask attribute can be used instead of any of these attributes. It exposes only basic mask settings, and applies a mask type that fits the type of a property. For example, in the code sample above the attribute applies the DateTime mask because the "HiredAt" property is of DateTime type.

Editor Properties

In addition to advanced mask settings, editors have their own settings that can also affect mask behavior.

  • BeepOnError - allows masked editors to play a system error sound when a user enters an invalid character (for example, a literal in an editor with a phone number mask).

  • MaxLength - specifies the maximum number of characters a user can enter.

  • CharacterCasing - allows you to forcibly switch all literals entered to an editor to either upper or lower case.

  • UseMaskAsDisplayFormat - when this setting is on, an inactive editor displays its value in the same format as it does when focused.

See Also