WinForms — Deprecation of the MaskBox Property

In our v20.2 release cycle, we announced the availability of our Advanced Text Editors mode. Advanced Text Editor mode introduced a number of high-impact features including caret/selection animation support and embedded text labels. Our release announcement detailed future plans and our intention to make this the default editor mode once all reported issues were addressed. Though we have yet to make this the default mode, our newest WXI skin is a big step towards this objective.

As you may already know, all text editors switch to this Advanced Mode when the WXI skin is active. Tinted text selection may have been a clue in this regard, but it certainly wasn't the only reason for the switch-over. In the new WXI skin, editors utilize additional background elements that correspond to different editor states. More elements mean additional client area and bounds calculations, increased border and content drawing logic, and an increase in overall complexity. Solving these challenges in standard mode would've produced side effects and artifacts. Accordingly, we made the decision to leverage the power of Advanced Mode to resolve these issues.

The use of Advanced Mode within the WXI skin prompted internal discussions that revolved around the compatibility of legacy code (code written specifically for legacy, non-Advanced editor mode). First and foremost among the areas of concern was the MaskBox property. This property allows you to obtain a standard WinForms text box control (the foundation of the DevExpress WinForms TextEdit editor). Since TextEdits in Advanced Mode are complete custom controls and no longer based on standard TextBoxes (see this initial post for more information: WinForms TextEdit — New v20.2 Features), the MaskBox property for these editors returns null (Nothing in VB.NET).

We analyzed numerous Support Center questions in search of real-life use cases that required access to the standard text box via the MaskBox property. Based on our research, the majority of these cases fall into one of the two main categories: autocomplete and text processing (including custom input masks).

Text Auto Completion

Autocomplete functionality is now available via native TextEditor API. To introduce autocomplete, set the Editor.AdvancedModeOptions.AutoCompleteSource property to specify whether the editor suggests entries from your custom data source or an auto-populated source (recent items, URLs from the history list, system file and folder names, etc). You’ll need to specify the appropriate mode (Suggest, Append, a combination of both, or SuggestSingleWord), and assign your custom data source (if you selected CustomSource auto-complete mode).

using DevExpress.XtraEditors;

void OnFormLoad(object sender, EventArgs e) {
    var DaysOfTheWeek = new AutoCompleteStringCollection();
    DaysOfTheWeek.AddRange(new string[]
      {"Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"});

    textEdit1.Properties.UseAdvancedMode = DevExpress.Utils.DefaultBoolean.True;
    textEdit1.Properties.AdvancedModeOptions.AutoCompleteMode =
        TextEditAutoCompleteMode.SuggestAppend;
    textEdit1.Properties.AdvancedModeOptions.AutoCompleteSource =
        AutoCompleteSource.CustomSource;
    textEdit1.Properties.AdvancedModeOptions.AutoCompleteCustomSource = DaysOfTheWeek;
 }

See this help article for more information on how to set up the autocomplete functionality in text editors: Text Auto Completion.

Masks and Text Processing API

In previous release cycles, we introduced a series of methods to help obtain and modify editor text:

• GetCharFromPosition(System.Drawing.Point)
• GetCharIndexFromPosition(System.Drawing.Point)
• GetFirstCharIndexFromLine(System.Int32)
• and others (see the complete list of TextEdit methods here)

These methods are identical to standard TextBox methods, for instance TextBoxBase.GetCharFromPosition(Point). If you retrieved the standard TextBox to utilize its methods, you can now use native TextEdit API to obtain the same result.

As for low-level input masks, we recently added the EnableCustomMaskTextInput method. This method allows you to manually track user actions and assign editor values as needed.

For example, if you need to limit the number of bytes entered by a user, previous versions required you to implement a custom TextEdit descendant with an overridden TextEdit.CreateMaskBoxInstance method, which accepted custom TextBoxMaskBox objects. User input would then be handled by this custom class.

With our EnableCustomMaskTextInput method, you no longer need any inheritance logic. All you need is to check byte length directly in the assigned callback.

using DevExpress.Data.Mask;

int m_maxByteLength = 5;

textEdit1.Properties.EnableCustomMaskTextInput(args => {
    // Do nothing if no edits were made
    if (args.IsCanceled || args.ActionType == CustomTextMaskInputAction.Init)
        return;

    if (GetByteLength(args.ResultEditText) > m_maxByteLength) {
        args.Cancel();
        return;
    }
    args.SetResult(
        args.ResultEditText, args.ResultCursorPosition, args.ResultSelectionAnchor);
});

int GetByteLength(string text) {
    return System.Text.Encoding.Default.GetBytes(text).Length;
}

MaskBox Deprecation

To sum up, our updated TextEdit API allows you to address all popular usage scenarios that previously required the use of the MaskBox property. This means that we can now deprecate this property. This isn't to say we're going to remove this property entirely, and render your existing code invalid. Rather, we now consider all MaskBox-related scenarios obsolete and will recommend the use of our native editor API instead.

If you are currently using the MaskBox property for a use-case scenario that cannot be implemented via the TextEdit's Advanced Mode API, please contact us via the DevExpress Support Center or use the text field below. We will do our best to address your requirements.

Your Feedback Matters