KB Article T954426
Visible to All Users

Input Masks in Editors - WinForms Cheat Sheet

Other DevExpress WinForms Cheat Sheets


You can use masks to restrict data input in DevExpress text editors and format data output.

The following mask types are available:

  • DateTime - Masks to enter date-time values.
  • DateTime with Offset - Masks to enter date-time values along with a user time zone.
  • Numeric - Masks for numeric values (percentage, currency, etc.)
  • Extended Regular Expressions - Masks that use regular expressions to specify an input pattern. The regular expression syntax is based on the POSIX ERE specification.
  • Simple - Masks that accept values in a fixed format without alternatives (for instance, phone numbers, zip codes, and social security numbers).
  • TimeSpan - Masks to enter time span values.
Set an input mask in the VS designer

At design time, click the control's smart tag and select Change Mask.
TextEdit-Smart tag-Change Mask

This action opens the Mask Settings dialog where you can specify a mask and mask options.
Mask Settings Dialog

Another way to open the Mask Settings dialog is to click the ellipsis button for the editor's Properties.MaskSettings property in the VS Property grid.

See the following topic for more information: Apply Masks in Visual Studio Designer.

Set an input mask in code

To set a mask expression and configure mask settings in code, use the MaskSettings.Configure method:

C#
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;

See the following topic for more information: Apply Masks in Code.

Examples

Enter date-time values

The DateEdit, TimeEdit, and DateTimeOffsetEdit controls provide native support for date-time value input. Users can enter values in the edit box according to a specific pattern (mask) and select values from the editor's drop-down list.
However, you can allow any text editor to accept date-time values. See the following topic for more information: How to: Enter date-time values

Enter numeric values

The CalcEdit and SpinEdit editors allow you to edit numeric values in various formats (integer and floating-point values, currency and percentage) according to the currently selected mask.
You can also allow any text editor to accept numeric values. See the following topic for more information: How to: Enter numeric values

Set an input mask at the data source layer

Decorate a field in the bound data source with one of the following attributes: EditMask, NumericEditMask, DateTimeEditMask, DateTimeOffsetEditMask, TimeSpanEditMask, SimpleEditMask, RegularEditMask, and RegExEditMask. These attributes are declared in the System.ComponentModel.DataAnnotations namespace and stored in the DevExpress.Data assembly.

C#
public class Employee { [RegExEditMask("[A-Z][a-z]+", AllowBlankInput = true, ShowPlaceholders = false)] public string FirstName { get; set; } [EditMask("d")] //this attribute exposes only basic mask settings, and applies a mask type that fits the property type public DateTime HiredAt { get; set; } }

See the following topic for more information: Apply Masks at the Data Source Layer.

Set an input mask for cell editors in container controls (GridControl, TreeList, VGridControl, PivotGridControl, etc.)

Ensure that you assigned an in-place editor (the RepositoryItem object) to a column(field) in a container control. Use the in-place editor's RepositoryItemTextEdit.MaskSettings property to set a mask.
See also: Replace Default Cell Editors.

Specify a thousand separator, precision character, and currency symbol

The currency symbol, thousand separator, precision character, etc. - they all depend on the current culture. In particular, the CultureInfo.NumberFormat property specifies a numeric format. Users can change the regional format in the Windows Settings panel. Standard approaches to modifying formats are also available, for example:

C#
CultureInfo myCI = new CultureInfo("en-US", false); myCI.NumberFormat.NumberDecimalSeparator = " "; Thread.CurrentThread.CurrentCulture = myCI; Thread.CurrentThread.CurrentUICulture = myCI;
Format editor values when an editor is not focused

Masks are used to format values when an editor is active. Enable the RepositoryItemTextEdit.UseMaskAsDisplayFormat option to apply the current mask as a display format for the editor's non-focused state. As a result, the editor text in edit and display modes will be identical.

Switch all literals entered into an editor to either upper or lower case
Specify the maximum number of characters a user can enter
Play a system error sound when a user enters an invalid character

Help us improve this article

Comments (2)
S S
Simon 'Skip' Gardiner 2 years ago

    Can I confirm the following and also wonder whether there is a plan to bring any of it back?:

    We can no longer bind mask expressions and types to controls

    Sasha (DevExpress Support) 2 years ago

      Hello Simon,

      To avoid mixing multiple questions in one thread, I created a separate ticket on your behalf: Masks - How to bind mask expressions and types to controls. I will address it shortly.

      Disclaimer: The information provided on DevExpress.com and affiliated web properties (including the DevExpress Support Center) is provided "as is" without warranty of any kind. Developer Express Inc disclaims all warranties, either express or implied, including the warranties of merchantability and fitness for a particular purpose. Please refer to the DevExpress.com Website Terms of Use for more information in this regard.

      Confidential Information: Developer Express Inc does not wish to receive, will not act to procure, nor will it solicit, confidential or proprietary materials and information from you through the DevExpress Support Center or its web properties. Any and all materials or information divulged during chats, email communications, online discussions, Support Center tickets, or made available to Developer Express Inc in any manner will be deemed NOT to be confidential by Developer Express Inc. Please refer to the DevExpress.com Website Terms of Use for more information in this regard.