Mask Type: Custom

• Nov 07, 2022
• 3 minutes to read

You can use custom masks to specify complex patterns that are difficult to implement via other mask types. Another advantage of custom masks is that you can help users enter correct values. Even if the entered character does not match the mask, you can review the input and transform it into an acceptable value. You can find examples in the sections below.

Apply a Custom Mask

Do the following to specify a custom mask:

1. Set the editor’s MaskType property to Custom.
2. Handle the CustomMask event.
3. Process the text displayed in the editor (e.CurrentEditText), the text entered by a user (e.InsertedText), or the edited text (e.ResultEditText).
4. Call the e.SetResult method to specify the editor’s final text. Use the e.Cancel method to prevent text changes.

Run Demo: Custom Masks

You can also specify custom masks for editors that operate in In-Place Mode. To do this, set the *EditSettings object’s MaskType property to Custom and attach the TextEdit.CustomMask event:

XAML

<dxg:GridColumn FieldName="ProductName">
    <dxg:GridColumn.EditSettings>
        <dxe:TextEditSettings MaskType="Custom" dxe:TextEdit.CustomMask="OnCustomMask"/>
    </dxg:GridColumn.EditSettings>
</dxg:GridColumn>

C#

void OnCustomMask(object sender, DevExpress.Xpf.Editors.CustomMaskEventArgs e) {
    // Process user input.
}

VB.NET

Private Sub OnCustomMask(ByVal sender As Object, ByVal e As DevExpress.Xpf.Editors.CustomMaskEventArgs)
    ' Process user input.
End Sub

The CustomMaskEventArgs class contains API that allows you to obtain the initial editor text, the user action that triggered the event, and the result of this action. You can also process the editor’s selected text, caret position, or obtain a transcription of the user action.

Examples

Allow Users to Enter Only Predefined Values

The following code sample allows users to enter only valid image file names:

XAML

<dxe:TextEdit MaskType="Custom" CustomMask="OnCustomMask"/>

C#

void OnCustomMask(object sender, DevExpress.Xpf.Editors.CustomMaskEventArgs e) {
    var imageExtensions = new string[] {".jpeg", ".jpg", ".png", ".gif", ".tiff", ".tif", ".bmp", ".svg", ".esp"};
    var enteredExtension = Path.GetExtension(e.ResultEditText);

    if (e.ResultEditText.Any(x => Path.GetInvalidFileNameChars().Contains(x)))
        e.Cancel();

    if (!imageExtensions.Any(x => x.StartsWith(enteredExtension, System.StringComparison.OrdinalIgnoreCase)))
        e.Cancel();
}

VB.NET

Private Sub OnCustomMask(ByVal sender As Object, ByVal e As DevExpress.Xpf.Editors.CustomMaskEventArgs)
    Dim imageExtensions = New String() {".jpeg", ".jpg", ".png", ".gif", ".tiff", ".tif", ".bmp", ".svg", ".esp"}
    Dim enteredExtension = Path.GetExtension(e.ResultEditText)

    If e.ResultEditText.Any(Function(x) Path.GetInvalidFileNameChars().Contains(x)) Then e.Cancel()

    If Not imageExtensions.Any(Function(x) x.StartsWith(enteredExtension, System.StringComparison.OrdinalIgnoreCase)) Then e.Cancel()
End Sub

Enter Unique Characters Only

The code sample below does not allow users to enter strings that have repeated characters:

XAML

<dxe:TextEdit MaskType="Custom" CustomMask="OnCustomMask"/>

C#

void OnCustomMask_1(object sender, DevExpress.Xpf.Editors.CustomMaskEventArgs e) {
    if (e.IsCanceled || e.ActionType == CustomTextMaskInputAction.Init)
        return;
    foreach (var c in e.InsertedText) {
        if (e.CurrentEditText.Contains(c))
            e.Cancel();
    }
}

VB.NET

Private Sub OnCustomMask_1(ByVal sender As Object, ByVal e As DevExpress.Xpf.Editors.CustomMaskEventArgs)
    If e.IsCanceled OrElse e.ActionType = CustomTextMaskInputAction.Init Then Return

    For Each c In e.InsertedText
        If e.CurrentEditText.Contains(c) Then e.Cancel()
    Next
End Sub

Capitalize Entered Characters

The following code sample allows users to enter only Latin letters and capitalizes entered characters:

XAML

<dxe:TextEdit MaskType="Custom" CustomMask="OnCustomMask"/>

C#

void OnCustomMask(object sender, DevExpress.Xpf.Editors.CustomMaskEventArgs e) {
    if (e.ActionType == CustomTextMaskInputAction.Init || e.IsCanceled == true)
        return;
    var textInfo = CultureInfo.InvariantCulture.TextInfo;
    if (!Regex.IsMatch(e.InsertedText, @"^[a-zA-Z]+$") && e.ActionType == CustomTextMaskInputAction.Insert)
        e.Cancel();
    else e.SetResult(textInfo.ToUpper(e.ResultEditText), e.ResultCursorPosition);
}

VB.NET

Private Sub OnCustomMask(ByVal sender As Object, ByVal e As DevExpress.Xpf.Editors.CustomMaskEventArgs)
    If e.ActionType = CustomTextMaskInputAction.Init OrElse e.IsCanceled = True Then Return
    Dim textInfo = CultureInfo.InvariantCulture.TextInfo

    If Not Regex.IsMatch(e.InsertedText, "^[a-zA-Z]+$") AndAlso e.ActionType = CustomTextMaskInputAction.Insert Then
        e.Cancel()
    Else
        e.SetResult(textInfo.ToUpper(e.ResultEditText), e.ResultCursorPosition)
    End If
End Sub