Xceed Grid for WinForms v4.3 Documentation
Welcome to Xceed Grid for WinForms v4.3 / Advanced Concepts / Editors - Advanced Concepts / Adding mask characters

In This Topic
    Adding mask characters
    In This Topic

    The WinTextBox control (via its TextBoxArea) offers the possibility to limit the inputted text using a set of predefined mask characters. Supported mask characters can be added or removed using the MaskChars property and the IsCharValid method.

    MaskChars property

    The MaskChars property, by default,  offers the following mask characters: 

    # Digits or white space
    9 Digits only
    A Alpha-numeric values only
    a Alpha-numeric values or white space
    @ Letters only
    & Any printable character (ASCII characters from 32 to 126 and 128 to 255)

    The following table provides a list of characters which are not mask characters but still affect the formatting of the text: 

    > When used as the first character of a mask, it converts all inputted characters to uppercase. When used elsewhere within the mask, it is considered as a literal.
    < When used as the first character of a mask, it converts all inputted characters to lowercase. When used elsewhere within the mask, it is considered as a literal.
    \ The character following this character will always be considered as a literal. For example, \9 will be the 9 literal instead of the digits mask character.

    To add or remove supported mask characters, the MaskChars property of the TextBoxArea must be overridden. Existing mask chars can then be removed, or new mask chars can be added. For example, in the code below, we will add "$" as a supported mask character:

    VB.NET
    Copy Code
    Protected Overrides ReadOnly Property MaskChars() As Char()
      Get
        Dim chars( MyBase.MaskChars.Length + 1 ) As Char
        MyBase.MaskChars.CopyTo( chars, 0 )
        chars( MyBase.MaskChars.Length ) = "$"c
        Return chars
      End Get
    End Property
    C#
    Copy Code
    protected override char[] MaskChars
    {
      get
      {
        char[] chars = new char[ base.MaskChars.Length + 1 ];
        base.MaskChars.CopyTo( chars, 0 );
        chars[ base.MaskChars.Length ] = '$';
        return chars;
      }
    }
    In addition to adding or removing supported mask chars, the IsCharValid method must also be overridden in order to validate a character against the supported mask chars. It is suggested that the base implementation of the IsCharValid method be called first, before providing validation for the new mask chars. Of course, if MaskChars contains only new mask chars, or if the default validation is to be changed, then there is no need to call the base implementation. For example, in the code below, we will validate characters against the default mask chars as well as the new "$" mask char:
    VB.NET
    Copy Code
    Protected Overrides Function IsCharValid( ByVal maskChar As Char, _
                                              ByVal charToValidate As Char ) As Boolean
      Dim valid As Boolean = MyBase.IsCharValid( maskChar, charToValidate )
      If Not valid Then
        If ( maskChar = "$"c And charToValidate = "+"c Or _
                                 charToValidate = "-"c Or charToValidate = "*"c Or _
                                 charToValidate = "/"c ) Then
          valid = True
        End If
      End If
        Return valid
    End Function
    C#
    Copy Code
    protected override bool IsCharValid( char maskChar, char charToValidate )
    {
      bool valid = base.IsCharValid( maskChar, charToValidate );
      if( !valid )
      {
        if( maskChar == '$' &&
            charToValidate == '+' || charToValidate == '-' ||
            charToValidate == '*' || charToValidate == '/' )
        {
          valid = true;
        }      
      }  
      return valid;
    }
    In addition to overriding the MaskChars property and the IsCharValid method of the TextBoxArea, it is also necessary to create a custom WinTextBox control which will use the custom TextBoxArea. This is done be deriving from the WinTextBox class and overriding the CreateTextBoxArea method. For example, in the code below, the CreateTextBoxArea has been overridden to return a new instance of the custom TextBoxArea:
    VB.NET
    Copy Code
    Protected Overrides Function CreateTextBoxArea() As TextBoxArea
      Return New CustomTextBoxArea( Me )
    End Function
    C#
    Copy Code
    protected override TextBoxArea CreateTextBoxArea()
    {
      return new CustomTextBoxArea( this );
    }
    The new WinTextBox control can then be used like any other control. For example in the code below, the custom WinTextBox control is used to display a mask that includes the additional mask char that was added to the TextBoxArea's MaskChars property.
    VB.NET
    Copy Code
    Dim text As New Xceed.Editors.Samples.CustomWinTextBox
    text.TextBoxArea.Mask = "9$9"
    text.Location = New Point(10, 10)
    Me.Controls.Add(text)
    C#
    Copy Code
    Xceed.Editors.Samples.CustomWinTextBox text = new Xceed.Editors.Samples.CustomWinTextBox();         
    text.TextBoxArea.Mask = "9$9";     
    text.Location = new Point( 10, 10 );
    this.Controls.Add( text );
    Full implementations of the custom WinTextBox control (VB.NET - C#) and the custom TextBoxArea (VB.NET - C#) are also available.