wpf-6945-controls-and-libraries-data-editors-common-features-masked-input.md
Most text editors (TextEdit descendants) shipped with the WPF Data Editors Library allow you to use masks during editing. Masks provide restricted data input and formatted data output.
Using masks in editors is useful when an entered string needs to match a specific format. For instance, a text editor should accept date/time values in a 24-hour format or 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). Use the masked input to support these and many other data input formats.
Note
The changes made by an end user are posted to the BaseEdit.EditValue only after the Input Validation succeeds, otherwise, the BaseEdit.EditValue property contains its previous valid value.
You can define an editor’s mask settings using the properties that have the ‘ Mask ‘ prefix (such as the TextEdit.MaskType, TextEdit.Mask, TextEdit.MaskCulture, etc.). Masks are usually used in edit mode. When an editor is not in edit mode, its display text can be also formatted using the specified mask, if the TextEdit.MaskUseAsDisplayFormat property is set to true. If this property is false , an editor’s display text is composed using the BaseEdit.DisplayFormatString format in display mode.
Users cannot move focus from the editor that contains incomplete values. Set the BaseEdit.InvalidValueBehavior property to AllowLeaveEditor to change this behavior.
IME is disabled in all masked editors.
When you use the Text property to specify the editor’s value, the value is of System.String type and the Numeric and DateTime mask types may apply incorrectly. To correctly apply mask settings, you should use EditValue property to specify the editor’s value.
Note
The following TextEdit descendants do not support the masked input: ComboBoxEdit, LookUpEdit, AutoSuggestEdit, MemoEdit, PopupColorEdit and PopupImageEdit.
WPF Data Editors fully support the following mask types.
The Mask Editor allows you to quickly create and customize masks of any complexity at design time.
Set the BaseEdit.AllowNullInput property to true , to allow entering null values into masked editors if there’s no information available for the corresponding data field. To accomplish this, press CTRL-D or CTRL-0. An alternative is to Select All within the editor and then press DEL.
When using the Simple or Regular mask type, you can specify whether 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 returned by the BaseEdit.EditValue property or not. To enable this behavior, set the TextEdit.MaskSaveLiteral property to true.
For the Simple , Regular and RegEx mask types, the placeholders in the edit box are represented using the special character determined by the TextEdit.MaskPlaceHolder property. You can use this property to change the default placeholder (the “_” character).
You can hide the placeholders for the RegEx mask type by setting the TextEdit.MaskShowPlaceHolders 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 MaskShowPlaceHolders property is set to true ; The ‘_’ symbol is used as a placeholder.)
(the MaskShowPlaceHolders property is set to false )
For the Simple , Regular and RegEx mask types the TextEdit.MaskIgnoreBlank 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 entirely completed.
An error in the editor is indicated by an error icon:
To provide an appropriate response when an invalid value is entered, handle the BaseEdit.Validate event.
You can enable the automatic completion feature for the RegEx mask type. In this mode, the editor will try to complete a value which has been partially entered by an end user. Use the TextEdit.MaskAutoComplete property to specify which autocomplete mode is enabled:
|
Autocomplete 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 the empty edit box for the first time, the editor automatically fills all the following placeholders with the 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 (for instance, “1”) in the empty edit box the following placeholders are automatically filled with the default values (the “0” characters) and selected:
|
If the TextEdit.MaskAutoComplete property is set to AutoCompleteType.Default, the editor will use the AutoCompleteType.Strong autocomplete mode, in this case.
Set the TextEdit.MaskBeepOnError property to true to enable beeping when an end user tries to type an invalid character. Suppose a mask of Numeric type is used. In such cases, an editor will produce a beep sound each time an end user tries to type a non-numeric character.