Xojo Documentation Xojo Documentation

Property (As String )

aTextEdit.Mask = newStringValue
or
StringValue = aTextEdit.Mask

Supported for all project types and targets.

Use the Mask property to filter user input on a character-by-character basis and add formatting characters.

Notes

For example, a mask for a Telephone number field can add parentheses, spaces, and dashes as literals, that are used for formatting, and the digit mask symbol '#' to restrict entry to numbers only. It uses the same mask characters as Visual Basic. If the user enters a character that is prohibited by the mask, it causes the ValidationError event to occur.

You can use the Mask property in conjunction with the Format property. The Mask filters the entry, while the Format property applies a format to the entry. The formats are the same as for the Format function.

The TextField will autocomplete any literal mask characters for the user. If the user uses the Backspace key he/she can backup the autocompletion but only 1 character at a time.

To turn off the Mask, set it to the empty string, "".

You can set the Mask property in the Properties pane. If you use the "#" character as the first character of the mask, there is the remote possibility that it may be confused with the name of a constant. When you use a constant in the Properties pane, you precede its name with the "#" sign. If you want both a constant and a mask to be named "Example", then you should create a new constant named "poundExample" with its value set to "#Example" and assign that in the Properties pane.

The following table shows the characters that you can use to define a mask.

Mask Character	Description
#	The single digit placeholder. The user can type only a digit (numeric) character in this position. For example, the mask "(###) ###-####" accepts the entry 5551212121" and returns "(555) 121-2121".
.	Decimal placeholder. The decimal placeholder that is actually used is specified in the user's International settings. The character is treated as a literal (formatting) character for masking purposes. For example, the mask "##.##" accepts the entry "2344" and returns "23.44" (for US systems).
,	Thousands separator. The thousands separator that is actually used is specified in the user's International settings. The character is treated as a literal (formatting) character for masking purposes. For example, the mask "####,###" accepts the entry "123456" and returns "1234,56".
:	Time separator. The time separator that is actually used is specified in the user's International settings. The character is treated as a literal (formatting) character for masking purposes.
/	Date separator. The date separator that is actually used is specified in the user's International settings. The character is treated as a literal (formatting) character for masking purposes. For example, the mask "99/99/\2099" accepts the entry "123109" and returns "12/31/2009". The "\20" enters the default century and decade and only accepts the year in the first decade of the century.
\	Mask escape character. Treats the next character in the mask as a literal. The escape character enables you to use the '#', '&', 'A', '?' (and so on) characters in the mask. The escaped character is treated as a literal (formatting) character. For example, the mask "\C\C-9999" accepts the entry "1234" and returns "CC-1234".
&	Character or space placeholder. It accepts one character. Valid values are the ASCII characters 32-126 and the non-ASCII characters 128-255. For example, the mask "&&-99999" accepts "li20520" and returns "li-20520".
C	Character or space placeholder, where entry is optional. It operates like the '&' placeholder. For example, the mask "CCCC-CC" formats "1233ed" as "1233-ed".
>	Convert all the characters that follow to uppercase. Uppercasing works beyond the ASCII range where appropriate, e.g., ü becomes Ü. For example, the mask ">&&-#####" accepts the string "li20520" and returns "LI-20520".
<	Convert all the characters that follow to lowercase. Lowercasing works beyond the ASCII range where appropriate, e.g., Ü becomes ü.
A	Alphanumeric character placeholder, where entry is mandatory. For example, the spec "AAA" specifies three alphanumeric characters.
a	Alphanumeric character placeholder, where entry is optional.
0	The literal "0" (zero). For example, the mask "99.00" formats the entry "22" as "22.00". The mask "\C\C0-9999" accepts the entry "1234" and returns it as "CC0-1234". The mask "##,###.00" accepts the entry "12345" and returns "12,345.00". The mask "99.00" accepts "21" and returns "21.00".
9	A Single (numeric) digit, where entry is optional.
?	Alphabetic placeholder. Entry is optional. For example, the mask "???" accepts three alphabetic characters. It rejects numeric characters.
Any literal	All other symbols are displayed as literals for formatting purposes. For example, the mask "99[9]" accepts the entry "333" and returns "33[3]".
~	Reserved for future use. If you use "~" it will trigger an exception error. Use \~ instead.

Sample Code

Mask	Description
999,999.99	Formats 11122233 as "111,222.33" (Using the US thousands separator.)
99.00	Formats "22" as "22.00."
###-##-####	US Social Security number. Fomats "123456789" as 123-45-6789.

TextField1.Mask = "###-##-####"
TextField1.Mask = "(###) ###-####" // US Phone number, with area code

If the user tries to enter a character that is prohibited by the mask, a ValidationError event occurs. The character that the user attempted to enter and the character position is passed to the ValidationError event, where you can handle the keystroke as you like.

To cancel the Mask, set it to the empty string:

TextField1.Mask = ""

See Also

Format property.