Adding mask characters

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

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

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; }

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.