MaskedTextBox


The MaskedTextBox control is a text box that provides a mask that helps guide the user in entering a value in a particular format. The mask determines which characters are allowed at different positions in the text. It displays placeholder characters to help prompt the user and underscores where the user can enter characters. For example, an empty United States phone number field would appear as (___)___-____ in the MaskedTextBox.

The control’s Mask property uses the characters shown in the following table.

Open table as spreadsheet

Character

Meaning

0

A required digit between 0 and 9.

9

An optional digit or space.

#

An optional digit, space, +, or -. If the user leaves this blank, this character appears as a space in the control’s Text, InputText, and OutputText properties.

L

A required letter a–z or A–Z.

?

An optional letter a–z or A–Z.

&

A required nonspace character.

C

An optional character.

A

A required alphanumeric character a–z, A–Z, or 0–9.

a

An optional alphanumeric character a–z, A–Z, or 0–9.

.

A decimal separator placeholder. The control automatically displays the appropriate decimal separator character for the current UI culture.

,

A thousands separator placeholder. The control automatically displays the appropriate thousands separator character for the current UI culture.

:

A time separator placeholder. The control automatically displays the appropriate time separator character for the current UI culture.

/

A date separator placeholder. The control automatically displays the appropriate date separator character for the current UI culture.

$

A currency symbol placeholder. The control automatically displays the appropriate currency symbol character for the current UI culture.

<

Automatically converts the characters that the user types after this point into lowercase.

>

Automatically converts the characters that the user types after this point into uppercase.

|

Disables the previous < or > character.

\

Escapes a character so it is displayed literally by the control even if the character would otherwise have special meaning. For example, \9 places a 9 in the output and \\ displays a \.

All other characters appear as literals within the mask. Dashes and parentheses are common literal characters. For example, the Social Security number mask 000-00-0000 displays dashes as in “ --”.

The control’s MaskCompleted property returns True if the user has entered characters to satisfy all of the required pieces of the mask. For example, suppose that the control uses the mask (999)000-0000 to represent a United States phone number. The control’s MaskCompleted property returns True if the user enters (123)456-7890 (here the parentheses and dashes are added automatically by the control).

Because the first three digits are optional, the property is also True if the user enters ( )456-7890. Because the last seven digits are required, the MaskCompleted property returns False if the user enters (123) -7890.

The following table shows the MaskTextBox control’s most useful properties. Note that this control inherits from the TextBox control, so it inherits most of that control’s properties, methods, and events. See the section “TextBox” later in this appendix for more information.

Open table as spreadsheet

Property

Purpose

AllowPromptAsInput

Determines whether the user can enter the prompt character determined by the PromptChar property (normally an underscore).

AsciiOnly

Determines whether the control allows non-ASCII Unicode characters.

BeepOnError

Determines whether the control beeps whenever the user types an invalid keystroke.

EnableCutCopyLiterals

Determines whether literal characters such as the parentheses in the mask (999)000-0000 are included when the user copies and pastes the control’s text.

HidePromptOnLeave

Determines whether the control hides its prompt characters when it loses the focus.

IncludeLiterals

Determines whether the control includes literal characters in the Text and OutputText properties.

IncludePrompt

Determines whether the control includes the PromptChar character in the OutputText property.

InputText

Gets or sets the characters input by the user. This doesn’t include any literal mask characters.

Mask

Gets or sets the mask.

MaskCompleted

Returns True if the user’s input satisfies the required mask characters.

MaskFull

Returns True if the user has entered characters for all of the mask’s required and optional elements.

OutputText

Returns the user’s text modified by the IncludeLiterals and IncludePrompt properties.

PromptChar

Determines the character that the control uses as a placeholder for user input.

Text

Gets or sets the text as it is currently displayed to the user, including prompt and literal characters.

The following table describes the control’s most useful events.

Open table as spreadsheet

Event

Occurs When

InputTextChanged

The control’s text has been modified.

MaskChanged

The control’s mask changed.

MaskInputRejected

The user’s input does not satisfy mask at the current position.

OutputTextChanged

The control’s text has been modified.

TextChanged

The control’s text has been modified.

Unfortunately, the MaskedTextBox control is relatively inflexible. It requires the user to enter exactly the right characters at the right positions, and there can be no variation in the format. For example, a single mask cannot let the user enter a telephone number in either of the formats 456-7890 or (123)456-7890. The mask (999)000-0000 makes the first three digits optional, but the user must enter spaces in those positions or skip over them. The mask also considers each character separately, so this mask accepts the value ( 3)456-7890.

This inflexibility means the MaskedTextBox control is most useful when you know exactly what the user will need to enter. If you want the user to type a four-digit telephone extension, a seven-digit phone number, or a five-digit ZIP code, then the control works well. If the user might enter either a seven- or ten-digit phone number, a five-digit ZIP code or a nine-digit ZIP+4 code, or an arbitrary e-mail address, the control is much less useful. In these cases, you might want to use regular expressions to validate the user’s input more precisely. For more information on regular expressions, see the “Regular Expressions” section in Chapter 32.




Visual Basic 2005 with  .NET 3.0 Programmer's Reference
Visual Basic 2005 with .NET 3.0 Programmer's Reference
ISBN: 470137053
EAN: N/A
Year: 2007
Pages: 417

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net