{"id":3473,"date":"2011-09-27T08:53:00","date_gmt":"2011-09-27T16:53:00","guid":{"rendered":"http:\/\/www.sapien.com\/blog\/?p=3473"},"modified":"2011-09-27T08:53:41","modified_gmt":"2011-09-27T16:53:41","slug":"primalforms-2011-spotlight-on-the-maskedtextbox-control","status":"publish","type":"post","link":"https:\/\/dev.sapien.com\/blog\/2011\/09\/27\/primalforms-2011-spotlight-on-the-maskedtextbox-control\/","title":{"rendered":"PrimalForms 2011: Spotlight on the MaskedTextBox Control"},"content":{"rendered":"

The \u201cSpotlight on Controls\u201d series focuses on a single WinForms control in PrimalForms 2011 , details the important Properties, Methods, and Events of the control and demonstrates how to utilize the control. Most of the information about the controls is still applicable to previous versions of PrimalForms.<\/em><\/p>\n

Last time we took a look at the ErrorProvider<\/a> control. This time we will look at the MaskedTextBox control:<\/p>\n

MaskedTextBox Control <\/strong>[System.Windows.Forms.MaskedTextBox]<\/span><\/p>\n

Represents an enhanced text box control that supports a declarative syntax for accepting or rejecting user input.<\/p>\n

\"MaskedTextBoxToolbox\"<\/p>\n

Default Event: MaskInputRejected<\/p>\n

Why use a MaskedTextBox control?<\/em><\/p>\n

Use the MaskedTextBox to distinguish between proper and improper user input. By using a mask, you can specify the format of the input without custom validation.<\/p>\n

<\/font><\/span><\/strong><\/p>\n

Important Properties:<\/font><\/span><\/strong><\/p>\n

Mask<\/strong> <\/p>\n

This property sets the string governing the input for this control.  <\/p>\n

Why use the Mask property? <\/p>\n

Use the Mask property to limit the textbox\u2019s input to a specific format. You can define your own custom mask or preferably select from a predefined set using the designer. The designer has a useful set of predefined masks such as date time formats, phone numbers, and zip codes. <\/p>\n

\"Designer<\/a><\/p>\n

You can access the predefined mask via the Property Pane: <\/p>\n

\"Edit <\/p>\n

Or directly in the designer: <\/p>\n

\"Edit <\/p>\n

If you need to create you own format, please refer to the following table or go to the Mask Property MSDN Help Page<\/a> for more details.<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Mask Element<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
0<\/td>\nDigit, required. This element will accept any single digit between 0 and 9.<\/td>\n<\/tr>\n
9<\/td>\nDigit or space, optional. <\/td>\n<\/tr>\n
#<\/td>\nDigit or space, optional. If this position is blank in the mask, it will be rendered as a space in the Text property. Plus (+) and minus (-) signs are allowed.<\/td>\n<\/tr>\n
L<\/td>\nLetter, required. Restricts input to the ASCII letters a-z and A-Z. This mask element is equivalent to [a-zA-Z] in regular expressions. <\/td>\n<\/tr>\n
?<\/td>\nLetter, optional. Restricts input to the ASCII letters a-z and A-Z. This mask element is equivalent to [a-zA-Z]? in regular expressions. <\/td>\n<\/tr>\n
&<\/td>\nCharacter, required. If the AsciiOnly property is set to true, this element behaves like the “L” element. <\/td>\n<\/tr>\n
C<\/td>\nCharacter, optional. Any non-control character. If the AsciiOnly property is set to true, this element behaves like the “?” element.<\/td>\n<\/tr>\n
A<\/td>\nAlphanumeric, required. If the AsciiOnly property is set to true, the only characters it will accept are the ASCII letters a-z and A-Z. This mask element behaves like the “a” element.<\/td>\n<\/tr>\n
a<\/td>\nAlphanumeric, optional. If the AsciiOnly property is set to true, the only characters it will accept are the ASCII letters a-z and A-Z. This mask element behaves like the “A” element.<\/td>\n<\/tr>\n
.<\/td>\nDecimal placeholder. The actual display character used will be the decimal symbol appropriate to the culture.<\/td>\n<\/tr>\n
,<\/td>\nThousands placeholder. The actual display character used will be the thousands placeholder appropriate to the culture.<\/td>\n<\/tr>\n
:<\/td>\nTime separator. The actual display character used will be the time symbol appropriate to the culture.<\/td>\n<\/tr>\n
\/<\/td>\nDate separator. The actual display character used will be the date symbol appropriate to culture.<\/td>\n<\/tr>\n
$<\/td>\nCurrency symbol. The actual character displayed will be the currency symbol appropriate to the culture.<\/td>\n<\/tr>\n
<<\/td>\nShift down. Converts all characters that follow to lowercase. <\/td>\n<\/tr>\n
><\/td>\nShift up. Converts all characters that follow to uppercase.<\/td>\n<\/tr>\n
|<\/td>\nDisable a previous shift up or shift down.<\/td>\n<\/tr>\n
\\<\/td>\nEscape. Escapes a mask character, turning it into a literal. “\\\\” is the escape sequence for a backslash. <\/td>\n<\/tr>\n
All other characters<\/td>\nLiterals. All non-mask elements will appear as themselves within MaskedTextBox. Literals always occupy a static position in the mask at run time, and cannot be moved or deleted by the user.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

An example mask for a US phone number is a follows:<\/p>\n

(999) 000-0000<\/p>\n

In this mask the first three digits are optional and the last seven are required. The parentheses are considered Literals, which means the user cannot altered them.<\/p>\n

<\/strong>Resulting MaskedTextBox with Phone Number Mask:
\"MaskedTextBox<\/p>\n

BeepOnError<\/strong><\/p>\n

This property indicates whether the masked text box control raises the system beep for each user key stroke that it rejects.<\/p>\n

Values (Default: $False<\/span>): <\/p>\n

\n

$True<\/span>\/ $False<\/span><\/p>\n<\/blockquote>\n

Culture<\/strong><\/p>\n

This property sets the culture information associated with the masked text box.<\/p>\n

Set this property if you are specifically targeting a culture that is not the current default (English (United States) for US machines). This effects the format of the date time entries and these changed will be reflected when selecting predefined masks as mentioned above.<\/p>\n

<\/strong> <\/p>\n

MaskCompleted<\/strong><\/p>\n

This property indicates whether all required inputs have been entered into the input mask.<\/p>\n

The MaskCompleted property can be useful when it comes to validating the data. See the MaskFull property for an example.<\/p>\n

 <\/p>\n

MaskFull<\/strong><\/p>\n

This property indicates whether all required and optional inputs have been entered into the input mask. <\/p>\n

This property is similar to MaskCompleted property with the exception that it also encompasses optional inputs specified in the Mask property. To compare these properties and to demonstrate their usefulness when it comes to validating, we will look at validating a phone number. The predefined Mask for a US phone number specifies that the area code (first three digits) is optional and the remaining seven digits are mandatory.<\/p>\n

The following examples will help demonstrate the difference between the two properties:<\/p>\n

Partially completed phone number:<\/p>\n

\"Partial<\/p>\n\n\n\n\n\n
Property<\/strong><\/td>\nValue<\/strong><\/td>\n<\/tr>\n
MaskCompleted<\/td>\nFalse<\/td>\n<\/tr>\n
MaskFull<\/td>\nFalse<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

 <\/p>\n

Phone number without an area code:<\/p>\n

\"Phone<\/p>\n\n\n\n\n\n
Property<\/strong><\/td>\nValue<\/strong><\/td>\n<\/tr>\n
MaskCompleted<\/td>\nTrue<\/td>\n<\/tr>\n
MaskFull<\/td>\nFalse<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

 <\/p>\n

Completed phone number:<\/p>\n

\"Completed<\/p>\n\n\n\n\n\n
Property<\/strong><\/td>\nValue<\/strong><\/td>\n<\/tr>\n
MaskCompleted<\/td>\nTrue<\/td>\n<\/tr>\n
MaskFull<\/td>\nTrue<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

<\/strong> <\/p>\n

Text<\/strong><\/p>\n

The property gets or sets the text as it is currently displayed to the user.  <\/p>\n

The value returned may include formatting characters specified in the Mask property. See the TextMaskFormat property for more information. <\/p>\n

<\/strong> <\/p>\n

TextMask<\/strong>Format<\/strong><\/p>\n

This property determines whether the string returned by the Text property includes literals and\/or prompt characters.<\/p>\n

Use the TextMaskFormat if you need to modify the format of the string that is returned by the Text property of the MaskedTextBox control.<\/p>\n

Values (Default: IncludeLiterals<\/em>):<\/p>\n

The example values displayed are based on he following MaskTextBox:<\/p>\n

\"Phone<\/p>\n

\n

IncludePrompt<\/em>
Return text input by the user as well as any instances of the prompt character.<\/p>\n

Text: “___5555555”<\/font><\/p>\n

IncludeLiterals<\/em>
Return text input by the user as well as any literal characters defined in the mask. <\/p>\n

Text: “(   ) 555-5555”<\/font> <\/p>\n

IncludePromptAndLiterals<\/em>
Return text input by the user as well as any literal characters defined in the mask and any instances of the prompt character. <\/p>\n

Text:  “(___) 555-5555”<\/font> <\/p>\n

ExcludePromptAndLiterals<\/em>
Return only text input by the user. <\/p>\n

Text: ”   5555555″<\/strong><\/font><\/p>\n<\/blockquote>\n

ValidatingType<\/strong><\/p>\n

This property contains the data type used to verify the data input by the user. <\/p>\n

<\/font><\/strong>You need not set this property normally, since the preset Masks already set this property appropriately. This ensures data types are within the correct range. For example \u201c77\/77\/7777\u201d is a valid format for a date, but the value is not. <\/p>\n

You must set the ValidatingType property to a type, which in PowerShell is defined by the full class name surrounded by brackets. For example, to set the ValidatingType to a DateTime you will need to do the following:<\/p>\n

$maskedtextboxBirthDate<\/span>.ValidatingType <\/span>=<\/span> [System.DateTime]<\/span><\/pre>\n
Again you need not set this property if you are using a predefined mask. <\/p>\n
Note: The ValidatingType property looks for a static method named \u201cParse\u201d that must be present in the Type to validate the content. Since the DateTime class has a Parse method, it is compatible:<\/p>\n
\n
[System.DateTime]::Parse()<\/p>\n<\/blockquote>\n
<\/font><\/strong>Other Common Types with the Parse static method includes the all the basic value types, such as:<\/p>\n
\n
[Int]<\/p>\n
[Double]<\/p>\n
[Float]<\/p>\n<\/blockquote>\n
All enumerators are compatible, such as:<\/p>\n
\n
[System.Windows.Forms.DialogResult]<\/p>\n
[Microsoft.PowerShell.ExecutionPolicy]<\/p>\n<\/blockquote>\n
 <\/p>\n
Important Methods:<\/font><\/strong><\/p>\n
ValidateText<\/strong><\/p>\n
This method converts the user input string to an instance of the validating type.<\/p>\n
<\/font><\/strong>Use this method to determine if the content of the MaskTextBox is valid. This method requires that a compatible type be set in the ValdiatingType property. If the ValidateText fails it will return a $null <\/span>value otherwise it will return an object of the corresponding type.<\/p>\n
Example:<\/font><\/p>\n
    <\/span>if<\/span>(<\/span>$maskedtextboxBirthDate<\/span>.ValidatingType <\/span>-ne<\/span> <\/span>$null<\/span>)\n    {\n        <\/span>if<\/span>(<\/span>$maskedtextboxBirthDate<\/span>.ValidateText() <\/span>-eq<\/span> <\/span>$null<\/span>)\n        {\n            <\/span>#Validation Failed<\/span>\n        <\/span>}\n        <\/span>else<\/span>\n        {\n            <\/span>#Validation Successful<\/span>  \n        }\n    }\n<\/span><\/pre>\n
Note: The MaskTextBox will automatically validate the text when it loses focus. <\/font><\/p>\n
<\/font><\/strong> <\/p>\n
Important  Events:<\/font><\/strong><\/p>\n
MaskInputRejected<\/strong><\/p>\n
This event occurs when the user’s input or assigned character does not match the corresponding format element of the input mask.<\/p>\n
Use this event when you want to react to invalid input:<\/p>\n
$maskedtextboxPhone_MaskInputRejected<\/span>=<\/span>[System.Windows.Forms.MaskInputRejectedEventHandler]{\n<\/span>#Event Argument: $_ = [System.Windows.Forms.MaskInputRejectedEventArgs]    <\/span>\n    <\/span>$labelError<\/span>.Text <\/span>=<\/span> <\/span>\"Failed input -Postion ({0}): {1}\"<\/span>  <\/span>-f<\/span> <\/span>$_<\/span>.Position, <\/span>$_<\/span>.RejectionHint.ToString()\n}<\/span><\/pre>\n
The event passes a parameter variable $_<\/span> . Use this variable to access the following properties:<\/p>\n
\n
$_<\/span>.Position<\/span><\/p>\n
Returns the position in the mask corresponding to the invalid input character.<\/p>\n<\/blockquote>\n
\n
$_<\/span>.RejectionHint<\/span><\/p>\n
Returns an enumerated value [System.ComponentModel.MaskedTextResultHint] that describes why the input character was rejected. Please see the MSDN MaskTextResultHist Help page<\/a> for more information.<\/p>\n<\/blockquote>\n
 <\/p>\n
TypeValidationCompleted<\/strong><\/p>\n
This event occurs when MaskedTextBox has finished parsing the current value using the ValidatingType property.<\/p>\n
Use this event in order to react to when a type validation fails or succeeds. This event is also fired when the ValdiateText method is called.<\/p>\n
$maskedtextboxBirthDate_TypeValidationCompleted<\/span>=<\/span>[System.Windows.Forms.TypeValidationEventHandler]{\n<\/span>#Event Argument: $_ = [System.Windows.Forms.TypeValidationEventArgs]<\/span>\n    <\/span>if<\/span>(<\/span>$_<\/span>.IsValidInput <\/span>-eq<\/span> <\/span>$false<\/span>)\n    {\n        <\/span>$_<\/span>.Cancel <\/span>=<\/span> <\/span>$true<\/span> <\/span>#Keep the focus on the control<\/span>\n        <\/span>$errorprovider1<\/span>.SetError(<\/span>$maskedtextboxBirthDate<\/span>, <\/span>\"Invalid Date Format\"<\/span>);\n    }\n    <\/span>else<\/span>\n    {\n        <\/span>$errorprovider1<\/span>.SetError(<\/span>$maskedtextboxBirthDate<\/span>, <\/span>\"\"<\/span>);    \n    }\n}<\/span><\/pre>\n
The TypeValdiationCompleted passes a parameter variable $_<\/span>. The following are important properties you can access with this variable:<\/p>\n
\n
$_<\/span>.Cancel <\/span><\/p>\n
This property indicates whether the event should be canceled. Set it to $true <\/span>to retain the focus on the MaskTextBox.<\/p>\n
$_<\/span>.IsValidInput <\/span><\/p>\n
This property indicates whether the formatted input string was successfully converted to the validating type.<\/p>\n
$_<\/span>.ReturnValue <\/span><\/p>\n
This property returns the object that results from the conversion of the formatted input string.<\/p>\n<\/blockquote>\n
 <\/p>\n
For an example use of the MaskTextBox, please refer to the samples used in the  PrimalForms 2011:  Validating the Form<\/a> blog articles.<\/p>\n","protected":false},"excerpt":{"rendered":"
The \u201cSpotlight on Controls\u201d series focuses on a single WinForms control in PrimalForms 2011 , details the important Properties, Methods, and Events of the control and demonstrates how to utilize the control. Most of the information about the controls is still applicable to previous versions of PrimalForms. Last time we took a look at the […]<\/p>\n","protected":false},"author":10,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"footnotes":""},"categories":[509,575,644,25],"tags":[641,687,28,633,327],"class_list":["post-3473","post","type-post","status-publish","format-standard","hentry","category-primalforms-software-news","category-primalforms-2011-software-news","category-spotlight-on-controls","category-windows-powershell","tag-controls","tag-maskedtextbox","tag-powershell","tag-primalforms-2011","tag-winform"],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/3473","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/users\/10"}],"replies":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/comments?post=3473"}],"version-history":[{"count":4,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/3473\/revisions"}],"predecessor-version":[{"id":3480,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/3473\/revisions\/3480"}],"wp:attachment":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/media?parent=3473"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/categories?post=3473"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/tags?post=3473"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}