The following user form components support edit masks:
The masks are typically used to control the user input: if the entered character does not match the mask, the component will not accept the character.
The mentioned user form components support standard edit masks and edit masks based on regular expressions. The mask type is specified by the component’s Properties.MaskKind property. This property can be one of the following values:
| Value | Description |
|---|---|
“emkStandard” |
The component uses the standard edit mask. |
“emkRegExpr” |
The component uses the mask based on regular expressions. |
“emkRegExprEx” |
The component uses the mask based on regular expressions and supports the auto-completion facility. |
The rest of this topic provides more information about specifying masks of different types.
Regular Expressions MasksRegular Expressions Masks
To specify the regular expressions mask type, assign the “emkRegExpr” value to the Properties.MaskKind property of the desired component.
This type of mask implies that the mask text is a string containing regular expressions. If a user types a character that does not match the character allowed by the regular expression, the component does not accept the character.
The user form components support the same regular expressions that are used by TestComplete dialogs and program objects. For more information on them, see Regular Expressions Syntax. Note that some specific regular expression tokens are not supported by the edit masks. For instance, the tokens ^ or $ are used to indicate the beginning and end of a text line correspondingly. Their use in edit masks is meaningless.
Extended Regular Expressions Mask
To specify this type of mask, assign the “emkRegExprEx” value to the Properties.MaskKind property of the desired component.
The extended regular expressions masks are similar to regular expression masks, but they also provide auto-completion support. This means that if a user has no alternative text to enter, the component will automatically complete text to the position that the alternative appears. For example, if the mask is --
[abc]\stest\s[0-9]
-- and a user types a and then presses space, the component will automatically complete the text to --
a test
-- and will position the insertion point after the word test to let the user input more text.
Except for the auto-completion feature, the extended regular expression masks are similar to regular expression masks. That is, to specify the mask you use the string that contains regular expressions. For more information, see Regular Expressions Syntax.
Standard Edit Masks
To specify this type of mask, assign the “emkStandard” value to the Properties.MaskKind property of the desired component.
A standard edit mask is an arbitrary string that may contain text and special masking characters (see the table below). The mask consists of three fields that are separated by semicolons in the EditMask property:
- The first field contains the mask string (literals and special masking characters, see below).
- The second field should contain 0 or any other character. 0 indicates that the component should only save those characters that were entered at positions of special characters, not all text as it is displayed in the edit field. A character different from 0 (for instance, 1) specifies that the component will save all characters displayed in the edit field.
For instance, the mask for a telephone number can be the following string:
(000)_000-0000;0;*0 in the second field indicates that the component will only save digits and will not save formatting characters (braces, underscore and hyphen).
- The character specified in the third field of the mask is used to indicate non-entered characters.
You can use the following mask characters:
| Character | Description |
|---|---|
| L | Requires an alphabetic character in this position. For the US, this is A..Z, a..z.
|
| l | Permits an alphabetic character in this position, but does not require it. |
| A | Requires an alphanumeric character in this position. For the US, this is A..Z, a..z or 0..9. |
| a | Permits an alphanumeric character in the position, but does not require it. |
| C | Requires an arbitrary character in the position. |
| c | Permits an arbitrary character, but does not require it. |
| 0 | Requires a numerical character in this position (0..9). |
| 9 | Permits a numerical character, but does not require it. |
| # | Permits a numerical character or a plus or minus character in this position, but does not require it. |
| > | All characters that will be entered after > will be converted to upper case, until the mask ends or until the < character is encountered. |
| < | All characters that will be entered after < will be converted to upper case, until the mask ends or until the > character is encountered. |
| <> | If these characters appear in the mask one after another, the component does not convert characters' cases that follow the <> in the mask. |
| / | Indicates a character that is used as a date separator. If the date separator specified by the Windows Regional Setting differs from /, that character is used instead of /. |
| : | Indicates the character that is used as time separator. If the time separator specified by the Windows Regional Setting differs from :, that character is used instead of :. |
| \ | The character that follows \ in the mask is treated as an ordinary character, not as mask character. For instance, if you use the string \L, the letter L will be treated as the character L in the mask, but not as a special character. |
| _ | The underscore character is used to insert spaces into the text. When a user enters text in the field, the cursor automatically skips the positions where the underscore characters reside. |
| ; | Separates parts of the mask (see below). |
Any character that is not mentioned in the table above can appear in the mask and will be treated as a literal character. These characters are inserted automatically in the edit field and the cursor skips over them during editing. To include special characters into the mask as literal characters, precede each of these special characters with a backslash (\).