WinTextBox control

The WinTextBox class represents an extensible and themable textbox control for Windows Forms which can be used as a regular or masked textbox , as well as a container control. It supports both Windows XP and classic Windows themes and can adapt to the current Windows Theme. The WinTexBox control can contain any of the Xceed editors as well as any other .NET control.

Textbox area

The WinTextBox control is a container control which contains an inner textbox. All of the inner textbox's properties and events are accessed via the WinTextBox control's TextBoxArea. Any properties that are set directly on the WinTextBox control will also affect any embedded child controls. For example, if the ForeColor property of the WinTextBox control is set to Color.Green, then the foreground color of all the embedded controls, including the TextBoxArea, will be changed to green. If the ForeColor property of the TextBoxArea is set to Color.Green, then only the foreground color of the TextBoxArea will be changed to green.

Masks

The text entered into the WinTextBox control can be formatted according to the mask provided by the Mask property. By default, the following mask characters are supported:

#	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.

The casing characters (< and >) only affect the characters entered by keyboard when they are the first characters of the mask. Casing characters located anywhere else are considered to be literals. All other characters are considered as literals.

The CharacterCasing property can be used to force letters to be upper or lower case in the case where a mask is not applied to the text.

By default, the "_" (underscore) character is used as a prompt to indicate the format of the mask that is being used. For example, if the Mask property is set to ">@9@-9@9", then "___-___" will appear in the textbox at runtime to indicate that 6 characters are required, and that they are separated into 2 groups of 3 by a hyphen.

VB.NET	Copy Code
Dim textBox As New WinTextBox() ' Canadian postal code format textBox.TextBoxArea.Mask = ">@9@-9@9" textBox.Location = New Point( 10, 10 ) Me.Controls.Add( textBox )

C#	Copy Code
WinTextBox textBox = new WinTextBox(); // Canadian postal code format textBox.TextBoxArea.Mask = ">@9@-9@9"; textBox.Location = new Point( 10, 10 ); this.Controls.Add( textBox );

The mask's prompt character can be modified by setting the MaskPromptChar property to the desired character. For example, if we retake the example above but change the prompt character to "*", then "***-***" would appear in the textbox at runtime rather than "___-___".

VB.NET	Copy Code
Dim textBox As New WinTextBox() ' Canadian postal code format textBox.TextBoxArea.Mask = ">@9@-9@9" textBox.TextBoxArea.MaskPromptChar = '*' textBox.Location = New Point( 10, 10 ) Me.Controls.Add( textBox )

VB.NET

Copy Code

Dim textBox As New WinTextBox()
' Canadian postal code format
textBox.TextBoxArea.Mask = ">@9@-9@9"
textBox.TextBoxArea.MaskPromptChar = '*'
textBox.Location = New Point( 10, 10 )
Me.Controls.Add( textBox )

C#	Copy Code
WinTextBox textBox = new WinTextBox(); // Canadian postal code format textBox.TextBoxArea.Mask = ">@9@-9@9"; textBox.TextBoxArea.MaskPromptChar = '*'; textBox.Location = new Point( 10, 10 ); this.Controls.Add( textBox );

Copy Code

WinTextBox textBox = new WinTextBox();
// Canadian postal code format
textBox.TextBoxArea.Mask = ">@9@-9@9";
textBox.TextBoxArea.MaskPromptChar = '*';
textBox.Location = new Point( 10, 10 );
this.Controls.Add( textBox );

To camouflage the text that is entered, the PasswordChar property can be used. For example, setting the PasswordChar property to "*" will replace each character that is entered with a "*" rather than displaying the actual character.

Validation

Every time the focus is removed from the WinTextBox control's TextBoxArea, the TextBoxArea's Validating event is raised. In the case where the date entered into the TextBoxArea does not match the EditFormatProvider, the Validating event's e.Cancel property will automatically be set to true (indicating that there was an error) and the focus will remain in the TextBoxArea. If the date is valid, e.Cancel will be false, and the focus will be sent to the next control.

Note that the TextBoxArea will also raise the ValidatingText event during the Validating event where extra custom text validation can be provided. e. FullValidation indicates if the text is currently being validated only against its mask or against all of the validation criteria. If the custom validation detects that the e. EditText is invalid, e. Valid should be set to false.