windowsforms-583-controls-and-libraries-editors-and-simple-controls-common-editor-features-and-concepts-input-mask.md
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.
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 are supported for all TextEdit descendants, except for the following editors:
Run this Demo Center module to test various input masks: Mask Box.
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.
DateOnly type — Allows you to specify masks for values of the DateOnly type. Uses the standard .NET numeric format for mask expressions.
TimeOnly type — Allows you to specify masks for values of the TimeOnly type. Uses the standard .NET numeric format for mask expressions.
DateTime with Offset type — Includes the 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, currencies, etc.).
Extended Regular Expressions type — Use these masks if an editor should do one of the following:
Simple type — Use this mask 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.
In the Visual Studio Property Grid, click the ellipsis button next to the Properties.MaskSettings property. In the invoked “Mask Settings” dialog, 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 the dialog. Available settings depend on the active mask type.
If there is no ready-to-use expression that fits your needs, click “Create New Mask…” and combine metacharacters to create a custom expression.
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:
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.90”), and shows 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;
Imports DevExpress.XtraEditors.Mask
' Fluent API
TextEdit5.Properties.MaskSettings.Configure(Of MaskSettings.Numeric)(
Sub(settings)
settings.MaskExpression = "###.##"
settings.AutoHideDecimalSeparator = False
settings.HideInsignificantZeros = True
End Sub)
' Regular API
Dim settings As MaskSettings.Numeric = TextEdit5.Properties.MaskSettings.Configure(Of MaskSettings.Numeric)()
settings.MaskExpression = "###.##"
settings.AutoHideDecimalSeparator = False
settings.HideInsignificantZeros = True
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 set to true allows users to leave this editor empty, and ShowPlaceholders set to false 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; }
}
Public Class Employee
<RegExEditMask("[A-Z][a-z]+", AllowBlankInput := True, ShowPlaceholders := False)>
Public Property FirstName() As String
<EditMask("d")>
Public Property HiredAt() As Date
End Class
The list below enumerates available data attributes. All attributes are declared in the System.ComponentModel.DataAnnotations namespace and stored in the DevExpress.Data assembly.
NumericEditMaskDateOnlyEditMaskTimeOnlyEditMaskDateTimeEditMaskDateTimeOffsetEditMaskTimeSpanEditMaskSimpleEditMaskRegularEditMaskRegExEditMaskThe 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 the property. For example, in the code sample above, the attribute applies the DateTime mask because the “HiredAt” property is of the DateTime type.
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 into 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.
If you wish to allow users to manually choose the mask type and format, call the EditMaskSettings method. It shows the same “Mask Settings” dialog invoked in the Visual Studio designer. The Boolean value returned by this method specifies whether a user has changed mask settings or closed the dialog without making any changes.
bool maskSettingsChanged = textEdit1.Properties.ResetMaskSettings();
Dim maskSettingsChanged As Boolean = textEdit1.Properties.ResetMaskSettings()
The optional method parameter allows you to set the value used to preview custom masks in the “Create New Mask…” dialog.
textEdit1.Properties.EditMaskSettings(9999.99m);
textEdit1.Properties.EditMaskSettings(9999.99D)
Use the MaskSettings.Save and MaskSettings.Restore methods to import and export mask settings. The following code illustrates how to copy mask settings from textEdit1 to multiple editors.
// Save and restore from a local variable
var state = textEdit1.Properties.MaskSettings.Save();
textEdit2.Properties.MaskSettings.Restore(state);
textEdit3.Properties.MaskSettings.Restore(state);
textEdit4.Properties.MaskSettings.Restore(state);
// Save and restore from a stream
textEdit1.Properties.MaskSettings.Save(myStream);
textEdit2.Properties.MaskSettings.Restore(myStream);
textEdit3.Properties.MaskSettings.Restore(myStream);
textEdit4.Properties.MaskSettings.Restore(myStream);
' Save and restore from a local variable
Dim state = textEdit1.Properties.MaskSettings.Save()
textEdit2.Properties.MaskSettings.Restore(state)
textEdit3.Properties.MaskSettings.Restore(state)
textEdit4.Properties.MaskSettings.Restore(state)
' Save and restore from a stream
textEdit1.Properties.MaskSettings.Save(myStream)
textEdit2.Properties.MaskSettings.Restore(myStream)
textEdit3.Properties.MaskSettings.Restore(myStream)
textEdit4.Properties.MaskSettings.Restore(myStream)
Custom masks created in the “Mask Settings” dialog are saved to the following file: C:\Users\Public\Documents\DevExpress\Masks\user.masksettings. You can share this file with other developers so that they can reuse your saved masks.
Tip
“Use Mask as Display Format” and “Beep on Invalid Input” options are editor settings rather than mask settings. The values of these settings cannot be saved or restored.
See Also
Mask Type: Extended Regular Expressions