Masked Input

• Jan 19, 2022
• 5 minutes to read

DevExpress WinUI Editors support masks when you edit their values. Masks restrict data input and format data output.

Editors support following mask types:

• Numeric

  This mask type restricts input to numeric values. If you need to restrict input to currency values, you can specify the one-character “c” mask. In this case, the mask does not allow more than two digits after the decimal point. Users can navigate through digits and use Up/Down arrows or the mouse wheel to increase/decrease editor values.

• Date-Time

  You can use this mask type for date-time values. You can also specify the mask using .NET Framework format strings because the same user capabilities are available. These include navigation between value sections (days, months, years, hours, etc.) and incremental value modifications using the keyboard and the mouse wheel.

• Simple Masks

  You should use this mask type when you need to enter strings of limited length, such as phone numbers, zip codes, social security numbers, etc. The mask is specified using a sequence of characters. Some characters serve as placeholders for digits or letters, while others are literals used to separate value sections. An example of such literals is parentheses for the area code in a phone number.

• Regular Expression Masks

  If the mask types listed above do not meet your business requirements, you can use regular expressions that have no limitations. Any regular expression can be used as a mask.

You can use the TextEdit.TextInputSettings property to define an editor’s mask settings. Masks are usually used in edit mode. When the UseAsDisplayFormat property is true and an editor is not in edit mode, its display text can be also formatted using the specified mask . If this property is false, an editor’s display text is composed using the TextEdit.DisplayFormatString format in display mode.

Mask Types

Set the TextEdit.TextInputSettings property to TextInputMaskSettings to enable masked input. A mask string identifies a data input pattern. You can use either predefined mask strings or compose your own mask expressions. Mask strings should be set according to the mask type. The following table lists available mask types:

Mask Type	Use this mask if…	Description	Samples
None		Masked mode is disabled.
DateTime DateTimeAdvancingCaret	…an editor requires that date/time values be in a specific format.	Masks of the DateTime/DateTimeAdvancingCaret type significantly simplify the input of date/time values. Predefined masks can be used to enter values using common date/time patterns. It’s also possible to create custom masks that specify which parts (year, month, day, hour, minute, etc.) of a date/time value can be edited. The syntax used for these masks is similar to the date/time formats described in the Standard Date and Time Format Strings topic in MSDN.	EditMask: D (long date pattern); EditMask: yyyy-MMM-d, HH:mm:ss (custom date pattern);
Numeric	…an editor requires that numeric values be in a specific format.	Masks of the Numeric type significantly simplify the input of numeric values (currency, integer, float, etc.). Masks in this mode allow numeric values to be entered using various common and custom patterns. It is possible to specify the number of optional and required digits to the left and to the right of the decimal separator, whether to display thousand separators, etc. The syntax used for these masks is similar to the numeric formats described in the Standard Numeric Format Strings topic in MSDN. Specific masks are dependent upon the current culture’s settings.	EditMask: c (currency); EditMask: # ##0.00 $ (custom);
Simple	…the string an end-user can enter is of a fixed format (without alternatives) and a fixed length (for instance, phone numbers and alpha-numeric sequences).	This mask type also supports optional characters (for instance, when it is possible to specify that the code of a phone number should contain 0 to 3 digits). Any auxiliary characters can be included in these masks. These auxiliary characters will be displayed in the edit box as is, and will be skipped while editing (for instance, hyphens in phone numbers).	EditMask: [phone] (phone number)
Regular		In this mode, masks use the simplified regular expression syntax. This mode is designed for backwards compatibility. Instead, use the RegEx mode, which implements full functional regular expressions that give you more flexibility to control data input.
RegEx	… the length of the string an end-user can enter is not fixed; or … the value can be entered using one of several alternative forms; or … only characters from a specific range can be entered at a specific position; or … the auto-complete feature is available (an end-user enters text and the editor completes this variant if there are no other alternatives)	In this mode you can construct masks using full functional regular expressions. This gives you great flexibility to control data input. For instance, it’s possible to create a single mask that will allow end-users to enter a time value using either the 12-hour or 24-hour format.	EditMask: ((+\d)?(\d{3}))?\d{3}-\d\d-\d\d (several valid forms to enter a phone number)