SftMask.Mask Property

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);

Delphi

String := object.Mask   : WideString;

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);

Delphi

object.Mask := String   : WideString;

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.

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.

$

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:

$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.

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.

Example:

[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.

\char

An explicit literal character.

Example:

\$

the $ character

\\

the \ character

\A

the A character

\V\a\l\u\e

the string "Value"

any

Any other character not defined as a token is automatically treated as a literal.

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).

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

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.

Example:

<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.

<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.

Substitution Tokens

These tokens don’t represent input fields. They are placeholders for substituted text.

|

The currency symbols 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.

Example:

Please see the Contents.Value property.

!!

Ends the Value variable definition.

Example

See Masked Edit Control

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);
	Delphi	String := object.Mask : WideString;
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);
	Delphi	object.Mask := String : WideString;

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.
	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.
$	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:	$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.
	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.
	Example:	[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.
\char	An explicit literal character.
	Example:	\$	the $ character
		\\	the \ character
		\A	the A character
		\V\a\l\u\e	the string "Value"
any	Any other character not defined as a token is automatically treated as a literal.
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).
	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	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.
	Example:	<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.
<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.
Substitution Tokens
These tokens don’t represent input fields. They are placeholders for substituted text.
\|	The currency symbols 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.
	Example:	Please see the Contents.Value property.
!!	Ends the Value variable definition.


	SftMask.Mask Property	Softel vdm, Inc.