Home

Text-Based Controls: The Masked Text Box

 

Masked Text Box Fundamentals

 

Introduction

The regular text box, also referred to as the edit control in Microsoft Windows (Win32), allows the user to enter any type of string in the control. In some cases, you may want to exercise more control on what the user can enter in a text box. To assist the user with entering a specific value into a text box, the .NET Framework provides the masked text box.

The masked text box allows you to configure one or more placeholders in the field of the control so that the control can accept some characters, must reject some characters, and/or can display some other characters you will have put so the user cannot delete them.

Creating a Masked Text Box

To create a masked text box, use the MaskedTextBox class. That is, declare a variable of type MaskedTextBox, use the new operator to initialize it, and add it to the Controls collection of its container. Here is an example:

open System;
open System.Drawing;
open System.Windows.Forms;

let exercise : System.Windows.Forms.Form = new System.Windows.Forms.Form();

let txtFunctional : MaskedTextBox = new MaskedTextBox();

Controls.Add(txtFunctional);

do
    System.Windows.Forms.Application.Run(exercise);

Characteristics of the Masked Text Box

 

Introduction

The masked text box uses the same common characteristics of other visual control: name, location, size, background color, border size, anchoring, docking, font, etc. Like the regular text box, the MaskedTextBox class is derived from TextBoxBase that provides its fundamental properties. This means that with the masked text box, you can cut or copy text from it, you can paste text to it, you can measure the length of its text, you can select some part of its text from a specific position to another, or you can select all of its text. Like the regular text box, the masked text box uses the AsciiOnly property, which indicates whether the control should accept or allow only ASCII characters.

The primary reason for using a masked text box is to control short lengths of text entered into it. For this reason, you should not consider some of the multi-line characteristics of a regular text box: word wrapping, scroll bars, the ability to use the Tab key inside the control, etc.

The Mask

Probably the most important property of a masked text box, which sets it apart from the (traditional) text box control, is its ability to control what the user can and cannot enter in the text side. To let you configure this text, the MaskedTextBox class is equipped with a property named Mask:

member Mask : string with get, set

 To create a mask, you use some characters and combine them as you see fit. The characters you can use are:

Character Used For Placeholder Rule
0 Digit Any single digit: 0, 1, 2, 3, 4, 5, 6, 7, 8, or 9.
9 Digit or Empty Space Any single digit can be entered or an empty space can be left.
# Digit or Empty Space Any single digit, a "+" or a "-" sign can be entered, or an empty space can be left.
L Letter Any letter in either uppercase or lowercase MUST be entered and no empty space should be left. Digits and other non-literals are not allowed.
? Letter Any letter in either uppercase or lowercase can be entered or an empty space can be left. Digits and other non-literals are not allowed.
& Character Any letter, digit, or symbol, or empty space can be used. If the Asc41#iiOnly property is True, this placeholder follows the ? behavior.
C Character Any letter, digit, or symbol, or empty space can be used. If the AsciiOnly property is True, this placeholder follows the & behavior.
A or a Letters and Digits A letter (lowercase and uppercase), a digit, or an empty space is allowed. No special characters. If the AsciiOnly property is True, only a letter is allowed.
> Uppercase Converter A letter in lowercase entered in this placeholder, and any letter in lowercase entered on the right side of this placeholder until the next < or I character, will be converted to uppercase. If the letter is entered in uppercase, nothing would happen.
< Lowercase Converter A letter in uppercase entered in this placeholder, and any letter in uppercase entered on the right side of this placeholder until the next < or I character, will be converted to lowercase. If the letter is entered in lowercase, nothing would happen.
| Conversion Remover Removes the < or > rule set on the left side of this placeholder. This means that, in this placeholder and others on the right side, letters will not be converted but will be kept "as is"
. Decimal Symbol The decimal symbol must be used.
, Thousands Separator The character for the thousands separator, which is the comma in US English, must be used.
: Time Separator The character used to separate the sections of a time value, which is ":" in US English, must be used.
/ Date Separator The character used to separate the sections of a date value, which is "/" in US English, must be used.
$ Currency Symbol The currency symbol, which is $ is US and Canada, will be used
\ Escape Sequence Makes the character follow the escape sequence rules.
  Any Other Character Except for the characters reviewed above, all other characters are kept "as is".

To programmatically specify a mask, create it in a string and assign that string to the Mask property. Here is an example:

open System;
open System.Drawing;
open System.Windows.Forms;

let exercise : System.Windows.Forms.Form = new System.Windows.Forms.Form();

let txtFunctional : MaskedTextBox = new MaskedTextBox();
txtFunctional.Location <- new Point(12, 12);
txtFunctional.Mask <- "999-000-0000";

exercise.Controls.Add(txtFunctional);

do
    System.Windows.Forms.Application.Run(exercise);

This would produce:

Mask

The Placeholder Character

When you create a mask, to indicate a placeholder for a letter, a digit, or a symbol, the control uses a specific character. The default character is the underscore. If you want, you can use a different character. To support this, the MaskedTextBox class is equipped with the PromptChar property, which is of type char:

member PromptChar : char with get, set

To specify the character of the placeholders, assign a string to the PromptChar property.

 
   
 

Entering the Wrong Character

When using the masked text box, the user must know the rules to follow based on the mask in the control: dates, telephone numbers, etc. The user must also enter only the allowed characters. If the user enters an invalid character, you can make the computer produce a sound (a beep). To assist you with this, the MaskedTextBox class is equipped with a Boolean property named BeepOnError:

member BeepOnError : bool with get, set

When this property is set to true, if the user enters an invalid character, the computer produces the beep sound:

open System;
open System.Drawing;
open System.Windows.Forms;

let exercise : System.Windows.Forms.Form = new System.Windows.Forms.Form();

let txtFunctional : MaskedTextBox = new MaskedTextBox();
txtFunctional.Location <- new Point(12, 12);
txtFunctional.Mask <- "999-000-0000";
txtFunctional.BeepOnError <- true;

exercise.Controls.Add(txtFunctional);

exercise.Text <- "Mask Text Box";

do
    System.Windows.Forms.Application.Run(exercise);

Also, if the user enters an invalid character in the control, the control fires a MaskInputRejected event, which is carried by a class named MaskInputRejectedEventHandler:

member MaskInputRejected : IEvent<MaskInputRejectedEventHandler,
    MaskInputRejectedEventArgs>

Here is an example of using this event:

open System;
open System.Drawing;
open System.Windows.Forms;

let exercise : System.Windows.Forms.Form = new System.Windows.Forms.Form();

let txtFunctionalInputRejected (e: MaskInputRejectedEventArgs) =
    (MessageBox.Show "There was a problem when trying to convert the principal";) |> ignore;

let txtFunctional : MaskedTextBox = new MaskedTextBox();
txtFunctional.Location <- new Point(12, 12);
txtFunctional.Mask <- "999-000-0000";
txtFunctional.BeepOnError <- true;
txtFunctional.MaskInputRejected.Add(txtFunctionalInputRejected);
exercise.Controls.Add(txtFunctional);

exercise.Text <- "Mask Text Box";

do
    System.Windows.Forms.Application.Run(exercise);

You can (continuously) use this event to find out whenever the user enters a wrong character so you can provide assistance.

Allowing the Placeholder Character for Input

After creating the control, when the control comes up, it usually shows its placeholders using a specific character. The most regularly used character is the underscore. Put in reverse, the presence of the underscore indicates a placeholder. If you skip a placeholder by pressing the Space bar, an underscore displays in the space you left. This rule also apples for all other characters we reviewed. In some cases, you may want to formally use the character in the placeholder. To assist you with this, the MaskedTextBox class is equipped with the AllowPromptAsInput Boolean property:

member AllowPromptAsInput : bool with get, set

Hiding the Placeholder When Focus is Lost

By default, when the control comes up, it uses some characters, such as _, to show its placeholder(s). This allows the user to know where a character is expected and the number of characters that are expected. After the user has used the control and pressed Tab or clicked another control, the masked text box may still show its placeholders. If you want, you can hide the placeholders when the control looses focus. To assist you with this, the MaskedTextBox class is equipped with a Boolean property named HidePromptOnLeave:

member HidePromptOnLeave : bool with get, set

The default value of this property is false, which indicates that the control would always show its placeholder(s). Otherwise, you can set this property to true to hide the placeholder character when the control loses focus. Here is an example:

open System;
open System.Drawing;
open System.Windows.Forms;

let exercise : System.Windows.Forms.Form = new System.Windows.Forms.Form();

let txtFunctionalInputRejected (e: MaskInputRejectedEventArgs) =
    (MessageBox.Show "There was a problem when trying to convert the principal";) |> ignore;

let txtFunctional : MaskedTextBox = new MaskedTextBox();
txtFunctional.Location <- new Point(12, 12);
txtFunctional.Mask <- "999-000-0000";
txtFunctional.BeepOnError <- true;

txtFunctional.HidePromptOnLeave <- true;

txtFunctional.MaskInputRejected.Add(txtFunctionalInputRejected);
exercise.Controls.Add(txtFunctional);

exercise.Text <- "Mask Text Box";

do
    System.Windows.Forms.Application.Run(exercise);

Keeping the Format on Cut and Copy

In some cases, the user can enter less than the number of placeholders in the control. Unlike the regular text box, the user cannot enter characters beyond the number of placeholders. As a class derived from the TextBoxBase class, the masked text box is equipped with a context menu that allows the user to cut, copy, and paste. When the user performs any of these operations, you may want to control whether the mask characters would be included in the cut, copied, or pasted text. To control this, the MaskedTextBox class is equipped with a property named CutCopyMaskFormat, which is based on the MaskFormat enumeration:

member CutCopyMaskFormat : MaskFormat with get, set

Its members are: ExcludePromptAndLiterals, IncludeLiterals, IncludePrompt, and IncludePromptAndLiterals.

 
 
   
 

Home Copyright © 2012-2015, FunctionX Home