1. Introduction to MaskedEdit Control & Mask Property
A ‘MaskedEdit Control’ is a special form of Edit Control. In Edit Control, a user enters the data. Then, developers will do validation and even manipulate the data to a specific format before saving it to the database. But the MaskedEdit control takes the data in a formatted way, and in the interim, it validates the keyed-in data. Say, for example, if we you expect a number the Control will accepts only accept digits 0 through 9 and scraps all other keyed-in Chars. The ‘Mask Property’ controls the data format and data character validation. Like the text box control, the output from the Masked Edit also read from the text property. Have a look at the below image:
Mask Property of a Masked Edit Control
First, the Control is set with the Mask Property. This property educates the control, what key stroke it can process and what it can skip. In the above picture 9 specifies that we expect a number in the placeholder as optional. That means when user enters something, it should be a number. As it is an optional letter, the user no need to fill all the placeholders. Below the Mask Property box in the picture there is another red box. It shows what users see when a masked control is displayed to them. It gives him/her knowledge (also with label Phone No in front of it) of what they should feed-in and in what format.
2. About the MaskedEdit Control Example
The picture of the example is below:
Masked Edit Control Example
The first text box alike control is actually a Masked Edit control. It gets the user input in a structured way. There are some sample masks in the radio group for exploring. Apart from these standard masks, we can provide our own format based on the need. The Show Output button will extract the text content from Masked Edit and will display it in the text box control next to it.
Hide Mask on Leave check box shows the mask format in the control when the input focus is set to the Mask Control. Beep on Error check box informs the Masked Edit control to make the beep sound when a wrong character enters it. Include literal and include Prompt will control the text output from the mask control to skip the literal character or the prompt letters. The ‘Prompt Char:’ part of the dialog shows the Prompt Char. The example also allows us to set a different prompt character at run time using single character Masked Edit control. One can look at the bold values of properties in the downloaded example to know the properties set to this second Single Char Masked Edit Control. The set button will set the prompt char for the big Masked Edit control at the top of the form.
This is a simple example, and all we did is assigning the properties to explore Masked Edit Control. The example will show how the control saves time when we need a formatted input and need for validation like I need only chars or numbers. Let us explore the code and we left the form design to you and it is simple drag drop of some controls.
3. The Mask property of MaskedEdit Control
The ‘Mask Property’ is the heart of the Masked Edit control and this property tells the Masked Edit how it should behave and what input key it should process and what it should not. Look at the radio group representing some fixed masks. The first one says it expects some number and the fourth one says it expects number but in the form of hour, minute, seconds.
We will take the fourth mask for explanation. The zeros in the mask say that a number (0-9) should be entered and the colon ‘:’ is the literal that cannot be changed. So, when user types the time they no need to type the colons as it already there in the required position. The below table shows mask characters and its descriptions.
| Sl. No | Mask Char | Description of Mask | Is Needed |
|---|---|---|---|
| 1 | # | You can type +/- | [Optional] |
| 2 | 0 | Digit zero to 9 | [Required] |
| 3 | 9 | Digit 0 – 9 | [Optional] |
| 4 | A | Alpha Numeric | [Required] |
| 5 | a | Alpha Numeric | [Optional] |
| 6 | L | Letters a-z, A-Z | [Required] |
| 7 | ? | Letters a-z, A-Z | [Optional] |
| 8 | C | Any non-control chars | [Optional] |
3.1 About the Masks
One can refer the documentation for more mask letters. But Mask Letters in the above table is enough to frame a Mask to get the controlled input. As we see in the table, each Mask Character has a meaning and an acceptance rule. Say, for example, the Mask Character 0 states that it will only accept the number. OK. What if the use types ‘M’ in the placeholder for 0? The input is skipped. What is Optional and Required? When we type a wrong character in the placeholder, the keyed-in character is skipped for both Required and Optional. This may make one to think in case of ‘Required’ they cannot move to next character until they fill the required character. But for ‘Optional’ they can move out. Is this Right?
But this is not how the C# Masked Edit Control behaves. One can still skip the required placeholder and take the output from the Masked Edit control. Then how the control responds when the user does not fill in the required character? Before exploring the answer for this question, let us set the Mask Property based on the radio selection. Below code will do this job:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
//Mask 001: Set different Masks based on the selected // radio buttons. These masks control the output in a // specific format. private void radMask1_CheckedChanged(object sender, EventArgs e) { maskedInput.Mask = radMask1.Text; } private void radMask2_CheckedChanged(object sender, EventArgs e) { maskedInput.Mask = radMask2.Text; } private void radMask3_CheckedChanged(object sender, EventArgs e) { maskedInput.Mask = radMask3.Text; } private void radMask4_CheckedChanged(object sender, EventArgs e) { maskedInput.Mask = radMask4.Text; } private void radMask5_CheckedChanged(object sender, EventArgs e) { maskedInput.Mask = radMask5.Text; } |
Note, we just set the caption text of the radio control to the mask property of Masked Edit control.
4. The MaskCompleted and MaskFull Properties
The MaskedEdit Control sets the ‘MaskCompleted Property’ only when the Required Mask Characters are filled. This property doesn’t care about the Optional Mask Characters. MaskedEdit Control also sets the ‘MaskFull Property’ to true when all the required and optional placeholders in the mask are filled.
The below code shows the usage of the MaskCompleted property. We check out the ‘Textchanged Event’ of the Masked Edit control and show the mask-completed label when the ‘MaskCompleted Property’ is set to true.
|
1 2 3 4 5 6 7 8 9 10 |
//Mask 007: Show the Mask Completed label when required // input is completed. private void maskedInput_TextChanged(object sender, EventArgs e) { if (maskedInput.MaskCompleted == true) lblMaskCompleted.Visible = true; else lblMaskCompleted.Visible = false; } |
Below is the video that shows how the mask is shown to the user and how do we use the mask completed property.
5. Hide Prompt Character of MaskedEdit Control
The ‘HidePromptOnLeave Property’ is used to hide the prompt character when we leave the Masked Edit control. In other words, the Control shows the prompt character only when we set focus to the control. In the example, if we place a check mark on the ‘Hide Mask On Leave’ check box, set this property to true. Below is the code:
|
1 2 3 4 5 6 |
//Mask 003: Hides the prompt chars on the mask when we leave //the control private void chkHideMsk_CheckedChanged(object sender, EventArgs e) { maskedInput.HidePromptOnLeave = chkHideMsk.Checked; } |
How the above code effects the Masked Edit control is shown in the below video:
6. BeepOnError Property
The BeepOnError Property makes a bell sound if PC sounds only available. If you have a proper sound card, then it plays sound file (.wav) for the error. You can set a different error sound in the control panel through sound option. Below is the code that sets the BeepOnError to true when the checkbox is in the checked state.
|
1 2 3 4 5 6 7 |
//Mask 004: When user enters the invalid char raises the beep (Or //plays corrosponding .wav file when external sound device is //connected) private void chkBeepErr_CheckedChanged(object sender, EventArgs e) { maskedInput.BeepOnError = chkBeepErr.Checked; } |
7. Setting the Prompt Character
The ‘PromptChar Property’ is used to set different prompt character to the Masked Edit control. In the example, a Masked Edit control is used to set the prompt character. And the Mask Property for this control is a single ‘C’. This means we can enter only one character and it can be any character with the exception to the control keys. Have a look at the properties set (Bold values) for the small edit box after downloading the sample. Below is the code that sets different prompt character to the masked text box control by changing it from default underscore (_).
|
1 2 3 4 5 6 |
//Mask 006: Setting the different mask prompt charactor private void btnSet_Click(object sender, EventArgs e) { maskedInput.PromptChar = System.Convert.ToChar( txtmskPromptChar.Text); } |
In the code, we are converting the entered text (Single character) to Character data type as expected by the property PromptChar. Below video shows PromptChar property in effect.
8. TextMaskFormat Property
Go back to the Section 1 of this article and have a look at the depiction to know about Prompt Character & Mask Literal. The text property will retrieve the value in the Masked Edit control and when retrieving we we can skip or allow those Prompt Characters and Mask Literals. The ‘TextMaskFormat Property’ informs the Masked Edit control, how the output from the control should be extracted from the Masked Edit control. Below is the code that shows the usage of this property.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 |
//Mask 005: When we take the output from mask control, we have the //option of skipping the Prompt and/or literal. private void chkIncludeLiteral_CheckedChanged(object sender, EventArgs e) { SetOutputFormat(); } private void chkIncludePrompt_CheckedChanged(object sender, EventArgs e) { SetOutputFormat(); } private void SetOutputFormat() { if (chkIncludeLiteral.Checked == true) { if (chkIncludePrompt.Checked == true) { maskedInput.TextMaskFormat = MaskFormat.IncludePromptAndLiterals; } else { maskedInput.TextMaskFormat = MaskFormat.IncludeLiterals; } } else { if (chkIncludePrompt.Checked == true) { maskedInput.TextMaskFormat = MaskFormat.IncludePrompt; } else { maskedInput.TextMaskFormat = MaskFormat.ExcludePromptAndLiterals; } } } |
By setting the proper constant value from the ‘MaskFormat Enumeration’ to the ‘TextMaskFormat Property’, we can control how we want to pull the data in the Masked Edit control. The video below is showing how this property controls the output by including or skipping the Prompt and literal characters.
9. Summary
The Masked Edit control is useful when we want to educate user in which format the input field expects the data. The mask letters do not allow entering wrong characters in the placeholder. In the meantime, it allows skipping the placeholder for required character by not entering anything. So, the coder should make use of the MaskCompleted property to make sure the user fills all needed characters in the placeholders. Finally, we have the option to pick in what format we want to store the output, and this format is controlled by TextMaskFormat property.
Download Source Code : MaskedEdit Control Example From Google Drive
Categories: C#
Tags: BeepOnError, HidePromptOnLeave, Mask Property, MaskCompleted Property, PromptChar, TextMaskFormat
Do you like this Example? Please comment about it for others!!
This site uses Akismet to reduce spam. Learn how your comment data is processed.