Mask Property, SftMask Object
Defines the mask for data entry.
Syntax
Get
| VB.NET | String = object.Mask As String |
| VB | String = object.Mask As String |
| C#.NET | string String = object.Mask; |
| VC++ | _bstr_t String = object->Mask;
_bstr_t String = object->GetMask(); |
| C | HRESULT object->get_Mask(BSTR* String); |
Put
| VB.NET | object.Mask = String As String |
| VB | object.Mask = String As String |
| C#.NET | string object.Mask = String; |
| VC++ | _bstr_t object->Mask = String;
void object->PutMask(_bstr_t String); |
| C | HRESULT object->put_Mask(BSTR String); |
object
A SftMask object.
String
Defines the mask used to validate data input. If an empty string is specified, the control acts as a simple edit control.
Comments
The Mask property defines the mask for data entry.
The mask consists of literal characters, tokens and subtokens which are used to validate data input.
The mask can use one or more of the following tokens and literal characters:
Numeric Input Field Tokens
The $ token represent a numeric input field. Multiple numeric fields are possible when defining a mask. Using value tokens (see below), the contents of this input field can be set and retrieved using the Contents.Value property. 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. |
| \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. |
| [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. |
| [Oabc] | Characters a, b, c are allowed. |
| [OabcDEF1-4] | Characters a, b, c, D, E, F, 1, 2, 3, 4 are allowed. |
| [OA-Z1-4] | Characters A through Z and 1 through 4 are allowed. |
| \$ | 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 the Contents.DateTime property. 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 Padding property. |
| $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 Padding property. |
| $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 Padding property. |
| 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.DateTime 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 the Contents.DateTime property. 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 Padding property. |
| $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 Padding property. |
| $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 Padding property. |
| 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.DateTime 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 PswdChar character, 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 PswdChar 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 character defined using PswdChar. |
| <l<p????#> | 4 characters and one digit, translated to lowercase on input, displayed using the character defined using PswdChar. |
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 the Contents.Value property. 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 the Contents.Value property. This allows manipulation of portions of the input data without the need to know the exact position. |
| !! | Ends the Value variable definition. |
See Masked Edit Control
See Also SftMask Object | Object Hierarchy
On
Off