Edit Masks
The edit mask, defined using the lpszMask field of the SFTMASK_CONTROL structure, controls input validation and formatting. The mask consists of literal characters, tokens and subtokens which are used to validate data input. If an empty string is specified, the control acts as a Simple Edit Control.
Literal characters are displayed by the masked edit control, but the user cannot modify them. Only input fields and input positions allow data entry. Input fields can be underlined using the fPromptUnderline and fPromptUnderlineNoFocus fields; unfilled input positions display the prompt character (chPromptChar) while the control has the input focus.
The mask can use one or more of the following tokens and literal characters:
Numeric Input Field Tokens
The $ token represents a numeric input field. Multiple numeric fields are possible when defining a mask. Using value tokens (see below), the contents of individual input fields can be set and retrieved using Contents_GetValue and Contents_SetValue. If a numeric input field is used, the autocomplete feature is not available for the control.
| $I | | | Numeric field (integer, allows entry of leading 0), additional subtokens define the numeric format, which appear in the following order (some are optional): |
| ^ | (optional) | Field allows up-down buttons (spin buttons). |
| - | (optional) | Field allows negative numbers. |
| , | (optional) | Use group formatting. |
| 0 | (optional) | Format with leading zeros (affects formatted display only). |
| digits | | Defines the allowable number of digits. |
| ( min , max ) | (optional) | Minimum/maximum range. Min and max must be between -999,999 and 999,999. Cannot be used with fractional digits. |
| $ | | | Numeric field (integer or floating point, with optional popup calculator, does not allow entry of leading 0), additional subtokens define the numeric format, which appear in the following order (some are optional): |
| ^ | (optional) | Field allows up-down buttons (spin buttons). |
| C | (optional) | Field supports the popup calculator. |
| ( | (optional) | Field allows negative numbers and displays negative numbers using (number), cannot be used with -. |
| - | (optional) | Field allows negative numbers, cannot be used with (. |
| , | (optional) | Use group formatting. |
| 0 | (optional) | Format with leading zeros (affects formatted display only). |
| digits | | Defines the allowable number of digits. |
| . fracdigits | (optional) | Defines the allowable number of fractional digits. |
| ( min , max ) | (optional) | Minimum/maximum range. Min and max must be between -999,999 and 999,999. Cannot be used with fractional digits. |
| Example: | $I4 | 4 digit numeric input |
| $I^4 | 4 digit numeric input with up-down buttons |
| $I^2(10,49) | 2 digit numeric input with up-down buttons and a minimum, maximum range 10-49. |
| $4 | 4 digit numeric input |
| $^4 | 4 digit numeric input with up-down buttons |
| $^2(10,49) | 2 digit numeric input with up-down buttons and a minimum, maximum range 10-49. |
| $C(,8.2 | 8 digits, 2 fractional digits, signed input with popup calculator. |
| $C(,8.2(100,10000) | 8 digits, 2 fractional digits, signed input with popup calculator, and minimum, maximum range 100-10000. |
Single Position Tokens
The following tokens represent one single input position (i.e., one character).
| # | Mandatory digit (0-9). |
| 9 | Optional digit (0-9). |
| ? | Mandatory letter (A-Z or a-z). |
| @ | Optional letter (A-Z or a-z). |
| & | Mandatory character (any). |
| ~ | Optional character (any). |
| A | Mandatory digit (0-9) or letter (A-Z or a-z). |
| a | Optional digit (0-9) or letter (A-Z or a-z). |
| [Mchars] | Defines one mandatory character using a character list or a character range. chars consists of one or multiple individual characters and/or one or multiple character ranges. Use \ to use a reserved character. |
| [Ochars] | Defines one optional character using a character list or a character range. chars consists of one or multiple individual characters and/or one or multiple character ranges. |
| \char | An explicit literal character. |
| any | Any other character not defined as a token is automatically treated as a literal. |
| Example: | [Mabc] | Characters a, b, c are allowed. |
| [MabcDEF1-4] | Characters a, b, c, D, E, F, 1, 2, 3, 4 are allowed. |
| [MA-Z1-4] | Characters A through Z and 1 through 4 are allowed. |
| [M$%\-\]] | Characters $, %, - and ] are allowed. |
| [OA-Z1-4] | Characters A through Z and 1 through 4 are allowed (optional position). |
| \$ | the $ character |
| \\ | the \ character |
| \A | the A character |
| \V\a\l\u\e | the string "Value" |
Time Field Tokens
The following tokens represent input fields related to time values. The contents of these input fields can be set and retrieved using Contents_GetDateTime and Contents_SetDateTime. Each time field token can only be used once when defining a mask. If a time field token is used, the autocomplete feature is not available for the control.
| $t | Time input (without seconds) using the default user locale, cannot be used with hours, minutes or seconds fields. If a time separator is used (as defined by the user locale), extra spaces may be added around the separator based on the fPadding field. |
| $T | Time input (with seconds) using the default user locale, cannot be used with hours, minutes or seconds fields. If a time separator is used (as defined by the user locale), extra spaces may be added around the separator based on the fPadding field. |
| $p | AM/PM input, used with user defined time fields. |
| $h | Hours field (1-12), used with user defined time fields. Only one hours token can be used per mask. |
| $hh | Hours field (1-12), displayed with a leading 0, used with user defined time fields. Only one hours token can be used per mask. |
| $H | Hours field (0-23), used with user defined time fields. Only one hours token can be used per mask. |
| $HH | Hours field (0-23), displayed with a leading 0, used with user defined time fields. Only one hours token can be used per mask. |
| $m | Minutes field (0-59), used with user defined time fields. Only one minutes token can be used per mask. |
| $mm | Minutes field (0-59), displayed with a leading 0, used with user defined time fields. Only one minutes token can be used per mask. |
| $s | Seconds field (0-59), used with user defined time fields. Only one seconds token can be used per mask. |
| $ss | Seconds field (0-59), displayed with a leading 0, used with user defined time fields. Only one seconds token can be used per mask. |
| : | The time separator defined by the default user locale. Extra spaces may be added around the separator based on the fPadding field. |
| Example: | $d $t | Date and time using user locale. |
| $hh : $mm $p | User defined time format with hours, minutes, AM/PM. |
| | In the above examples, Contents_GetDateTime and Contents_SetDateTime can be used to retrieve and set the time values. |
Date Field Tokens
The following tokens represent input fields related to date values. The contents of these input fields can be set and retrieved using Contents_GetDateTime and Contents_SetDateTime. Each date field token can only be used once when defining a mask. If a date field token is used, the autocomplete feature is not available for the control.
| $d | Date input (with two digit year) using the default user locale, cannot be used with year, month or days fields. If a date separator is used (as defined by the user locale), extra spaces may be added around the separator based on the fPadding field. |
| $D | Date input (with four digit year) using the default user locale, cannot be used with year, month or days fields. If a date separator is used (as defined by the user locale), extra spaces may be added around the separator based on the fPadding field. |
| $yy | Year field (0-99), used with user defined date fields. Only one year token can be used per mask. |
| $yyyy | Year field (0-9999), used with user defined date fields. Only one year token can be used per mask. |
| $o | Month field (1-12), used with user defined date fields. Only one month token can be used per mask. |
| $oo | Month field (1-12), displayed with a leading 0, used with user defined date fields. Only one month token can be used per mask. |
| $a | Day field (1-31), used with user defined date fields. Only one day token can be used per mask. |
| $aa | Day field (1-31), displayed with a leading 0, used with user defined date fields. Only one day token can be used per mask. |
| / | The date separator defined by the default user locale. Extra spaces may be added around the separator based on the fPadding field. |
| Example: | $D $T | Date and time using user locale. |
| $yyyy / $oo $aa | User defined date format with year, month, day. |
| | In the above examples, Contents_GetDateTime and Contents_SetDateTime can be used to retrieve and set the date values. |
Special Handling Tokens
These tokens don't represent input fields or positions, but affect the surrounding input positions:
| = | Shift break (inserting or deleting doesn't shift characters beyond this point). |
| <p | The following input positions display the password character (chPswdChar), used to prevent the display of input data. <p must be ended by a matching >. Any input positions or input fields between <p and > will display the password character instead of the actual input data. |
| <l | The following input positions are translated to lowercase on input. <l must be ended by a matching >. Any input positions or input fields between <l and > will be translated to lowercase on input. |
| <u | The following input positions are translated to uppercase on input. <u must be ended by a matching >. Any input positions or input fields between <u and > will be translated to uppercase on input. |
| > | Ends <p, <l and <u. When combining <p, <l and <u, one single > terminates <p, <l and <u. |
| Example: | (###)= ###-#### | A phone number. If the Delete key is used in the area code field, no digits are shifted from the following fields. When inserting digits into the area code field, extra digits do not overflow. |
| <p????#> | 4 characters and one digit, displayed using the password character. |
| <l<p????#> | 4 characters and one digit, translated to lowercase on input, displayed using the password character. |
Substitution Tokens
These tokens don't represent input fields. They are placeholders for substituted text.
| | | The currency symbol defined by the default user locale. |
Value Tokens
| !number | Defines a variable which can be retrieved and set using Contents_GetValue and Contents_SetValue. Number is in the range 0 through 9. The input fields or positions between the !number token and the matching !! token can be retrieved or set using Contents_GetValue and Contents_SetValue. This allows manipulation of portions of the input data without the need to know the exact position. |
| !! | Ends the Value variable definition. |
| Example: | Please see Contents_GetValue. |
See Also Masked Edit Control | Simple Edit Control | SFTMASK_CONTROL | Input Validation
On
Off