Mask Editors Overview
- 9 minutes to read
The DevExpress text editors (TextEdit descendants) support masks, which help you implement restricted data input as well as formatted data output. The sections in this topic provide general information on mask functionality.
General Information
Masks are typically used to restrict data input in editors in edit mode. When an editor does not have focus, its value is formatted by default according to the display format (RepositoryItem.DisplayFormat). Masks can also be used for the same purposes - to format a value in display mode. This feature is enabled with the MaskProperties.UseMaskAsDisplayFormat property. However, due to performance issues, we recommend using masks instead of display formats only for standalone text editors. See the MaskProperties.UseMaskAsDisplayFormat property description to learn more.
The LookUpEdit, GridLookUpEdit, MemoEdit, MemoExEdit and ImageComboBoxEdit controls do not support editing in masked mode.
Using masks in editors is useful when the entered string must match a specific format. For instance, a text editor should accept date/time values only in a 24-hour format, or only numeric values. Another example is entering a phone number within an editor (an end-user needs to enter only digits, while hyphens should be automatically skipped while editing). To support these and other data input formats, the masked mode can be used.
Editor mask settings can be accessed using the RepositoryItemTextEdit.Mask property of the editor’s TextEdit.Properties object. The RepositoryItemTextEdit.Mask property represents an instance of the MaskProperties class and this contains mask settings (mask type, mask, whether the mask’s literal characters should be saved to the edit value, etc.).
At design time, you can use the Mask Editor to customize mask settings. The editor provides multiple predefined masks. It’s also possible to create custom masks. The editor’s Test Input box allows you to test the selected mask. To invoke the editor, click the ellipsis button (…) for the RepositoryItemTextEdit.Mask property in the Properties grid.
Mask Types
To enable masked input, select the required mask type using the MaskProperties.MaskType property and specify a mask string using the MaskProperties.EditMask property. A mask string identifies a data input pattern. You can either use predefined mask strings or compose your own mask expressions. Mask strings should be set according to the mask type. Available mask types are listed in the following table.
Mask Type | Use this mask if… | Description | Samples |
|---|---|---|---|
None | Masked mode is disabled. | ||
DateTime DateTimeAdvancingCaret | an editor should accept date/time values in a specific format. | DateTime/DateTimeAdvancingCaret type masks significantly simplify inputting 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 Date and Time Format Strings topic in MSDN. The data input pattern imposed by the mask is affected by the current culture’s settings. These settings can be customized using the Regional Options dialog in the control panel. See the Mask Type: Date-time topic for more information. | EditMask: D (long date pattern); Current culture: English (USA)
EditMask: yyyy-MMM-d, HH:mm:ss (custom date pattern); Current culture: French (France)
|
Numeric | an editor should accept numeric values in a specific format. | Numeric type masks 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’s possible to specify the number of optional and required digits to the left and to the right of the decimal separator, or whether or not to display thousand separators, etc. The syntax used for these masks is similar to the numeric formats described in the Numeric Format Strings topic in MSDN. Specific masks are dependent upon the current culture settings. See the Mask Type: Numeric topic for more information. | EditMask: c (currency); Current culture: English (USA)
EditMask: # ##0.00 $;(# ##0.00 $) (custom); Current culture: French (France)
|
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, it’s 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 and these auxiliary characters will be displayed in the edit box as is and will be skipped while editing (for instance, hyphens in phone numbers). See the Mask Type: Simple topic for more information. | EditMask: (999)000-00-00 (phone number)
|
Regular | In this mode, masks use the simplified regular expression syntax, which is similar to the one that was implemented in version 2 of the XtraEditors. This mode is designed for backwards compatibility. Instead, use the RegEx mode, which implements Extended Regular Expressions that give you more flexibility with controlling data input. For information on the regular expression syntax used in this mode, see the Mask Type: Simplified Regular Expressions topic. | ||
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 should be 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 Extended Regular Expressions. This gives you great flexibility with controlling 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. See the Mask Type: Extended Regular Expressions topic for information on the regular expressions syntax used in this mode. The syntax used by masks in this mode is similar to the syntax defined by the POSIX ERE specification. | EditMask: ((+\d)?(\d{3}))?\d{3}-\d\d-\d\d (several valid forms to enter a phone number)
|
The following example shows how to make a text editor accept date/time values using the long date pattern.
textEdit1.Properties.Mask.MaskType = DevExpress.XtraEditors.Mask.MaskType.DateTime;
textEdit1.Properties.Mask.EditMask = "D";
The result is displayed in the following image.
Additional Customization of Mask Editors
The MaskProperties class that encapsulates mask functionality provides a number of additional customization settings.
The following table explains which options are in effect for various mask types (such options are indicated using the 
icon).
| Option | MaskType.DateTime | MaskType.Numeric | MaskType.Simple | MaskType.Regular | MaskType.RegEx |
|---|---|---|---|---|---|
| BeepOnError | |
|
|
|
|
| SaveLiteral | |
|
|||
| IgnoreMaskBlank | |
|
|
||
| PlaceHolder | |
|
|
||
| ShowPlaceHolders | |
||||
| AutoComplete | |
The BeepOnError Option
For all mask types, the Boolean MaskProperties.BeepOnError property is available. Set this property to true to enable beeping when an end-user tries to type an invalid character. Suppose a mask of a Numeric type is used. In such a case, an editor will produce a beep sound each time an end-user tries to type a non-numeric character.
The SaveLiteral Option
For the Simple and Regular mask types, this option specifies whether or not constantly displayed mask characters (literals) are included in an editor’s value. In other words, you can control whether such characters appear in the value obtained via the BaseEdit.EditValue property. The MaskProperties.SaveLiteral property must be set to false to make such characters inaccessible. In such an instance, if the displayed value is ‘(555)123-76-34‘, the value obtained via the BaseEdit.EditValue property is ‘5551237634‘.
The PlaceHolder and ShowPlaceHolders Options
For the Simple, Regular and RegEx mask types, the placeholders in the edit box are represented using the special character determined by the MaskProperties.PlaceHolder property. You can use this property to change the default placeholder (the “_” character).
For the RegEx mask type, placeholders can be hidden by setting the MaskProperties.ShowPlaceHolders property to false.
The following images show an empty text editor whose mask is set to “CODE-\d{3}-NO-\d{3}” (the mask type is RegEx).
(the ShowPlaceHolders property is set to true; The ‘_’ symbol is used as a placeholder.)
(the ShowPlaceHolders property is set to false)
The IgnoreMaskBlank Option
For the Simple, Regular and RegEx mask types, the MaskProperties.IgnoreMaskBlank property is in effect. If this property is set to true, an empty editor can lose focus. If the editor’s value is only partially completed, focus cannot be moved from the editor until an end-user enters the entire value or removes the value by clearing the edit box.
If this property is set to false, focus cannot be moved from the editor until the value is completed entirely.
An error in the editor is indicated by an error icon.
To provide an appropriate response when an invalid value is entered, the BaseEdit.InvalidValue event can be handled.
The AutoComplete Option
The automatic completion feature can be enabled for the RegEx mask type. In this mode, the editor will try to complete a value partially entered by an end-user. Use the MaskProperties.AutoComplete property to specify which auto-complete mode is enabled
Auto-complete mode | Description |
|---|---|
Strong | Each time an end-user types a character, the editor determines if the following placeholder can be filled automatically. If only a specific character can be inserted in this position, the editor automatically displays this character and moves the caret to the right of this character. Assume that the edit mask is set to “\R{MonthNames}” (the editor will accept the names of the months). When the “M” character is entered by an end-user in the empty edit box, the second placeholder is filled automatically with the “a” character since there are two months starting with “M” (March and May) and both contain an “a” in the second position.
If the “r” character is pressed, then the editor automatically completes the input and displays “March”.
|
Optimistic | When an end-user enters a character in an empty edit box for the first time, the editor automatically fills all the following placeholders with default values. For placeholders that accept only numeric values, the ‘0’ character is the default. For placeholders that accept word characters, the “a” character is the default. Assume that the mask is set to “\R{MonthNames}”. After the “M” character is entered, the editor inserts the “May” month automatically (this is the shortest variant between the two alternatives - March and May).
For instance, the edit mask is set to “\d{3}-\d{2}-\d{2}” (a telephone number pattern). When the first character is entered (e.g., “1”) in the empty edit box, the following placeholders are automatically filled with the default values (the “0” characters) and then selected.
|
If the MaskProperties.AutoComplete property is set to AutoCompleteType.Default, the editor will use the AutoCompleteType.Strong auto-complete mode in this case.