Version

Masks

xamMaskedEditor™ and editors based on the xamMaskedEditor control (e.g., xamCurrencyEditor™, xamNumericEditor™, and xamDateTimeEditor™) expose the Mask property. The following table lists all possible mask characters and tokens that the mask syntax supports.

Note
Note

Only a subset of these masks are relevant for a specific editor. Also, the masks that you would use depends on the ValueType of the editor.

Mask Character Description

#

Digit placeholder. Character must be numeric (0-9) and entry is required. Example: (###)-###-####.

.

Decimal placeholder. The actual character used is the one specified as the decimal placeholder by the system’s international settings. This character is treated as a literal for masking purposes.

,

Thousands separator. The actual character used is the one specified as the thousands separator by the system’s international settings. This character is treated as a literal for masking purposes.

:

Time separator. The actual character used is the one specified as the time separator by the system’s international settings. This character is treated as a literal for masking purposes.

/

Date separator. The actual character used is the one specified as the date separator by the system’s international settings. This character is treated as a literal for masking purposes.

\

Treat the next character in the mask string as a literal. This allows you to include the '#', '&', 'A', and '?' as well as other characters with special meanings in the mask. This character is treated as a literal for masking purposes.

&

Character placeholder. Valid values for this placeholder are ANSI characters in the following ranges: 32-126 and 128-255 (keyboard and foreign symbol characters).

>

Convert all the characters that follow to uppercase.

<

Convert all the characters that follow to lowercase.

A

Alphanumeric character placeholder. For example: a-z, A-Z, or 0-9. Character entry is required.

a

Alphanumeric character placeholder. For example: a-z, A-Z, or 0-9. Character entry is not required.

9

Digit placeholder. Character must be numeric (0-9) but entry is not required.

h

Hexadecimal digit placeholder. Character must be a hexadecimal digit (0-9 or a-f). The entry is required. A-F digits will be converted to lower case.

H

Same as 'h' placeholder however the a-f digits will be converted to upper case.

-

Minus sign when followed by a number section defined by series of 'n’s (like in "-nn,nnn.nn") indicates that negative numbers are allowed. When not followed by a series of 'n’s, it’s taken as a literal. Minus sign will only be shown when the number is actually negative.

+

Plus sign when followed by a number section defined by series of 'n’s (like in "nn,nnn.nn") indicates that negative numbers are allowed. However, it differs from '-' in the respect that it will always show a '' or a '-' sign depending on whether the number is positive or negative.

C

Character or space placeholder. Character entry is not required. This operates exactly like the '&' placeholder, and ensures compatibility with Microsoft Access.

?

Letter placeholder. For example: a-z or A-Z. Character entry is not required.

n

Digit placeholder. A group of n’s can be used to create a numeric section where numbers are entered from right to left. Character must be numeric (0-9) but entry is not required.

{char:n:s}

{char:n:s} mask allows you to define a placeholder with arbitrary set of characters that will be accepted. 'n' in the mask specifies the number of character placeholders in the mask. 's' specifies the set of acceptable characters.

The following are some examples of this mask:

  • {char:1:abc} - This mask will have single character placeholder that will accept 'a', 'b' or 'c' characters only.

  • {char:4:abc} - Same as above except 4 character placeholders will be created.

  • {char:8:0-9a-f} - 8 character placeholders where each will allow 0-9 and a-f characters (in effect hexadecimal characters).

mm, dd, yy

Combination of these three special tokens can be used to define a date mask. mm for month, dd for day, yy for two-digit years and yyyy for four-digit years. Examples: mm/dd/yyyy, yyyy/mm/dd, mm/yy.

hh, mm, ss, tt

Combination of these three special tokens can be used to define a time mask. hh for hour, mm for minute, ss for second, and tt for AP/PM. Examples: hh:mm, hh:mm tt, hh:mm:ss.

{date:s}

{date} token is a placeholder for short date input. The date mask is derived using the underlying culture settings.

{time}

{time} token is a placeholder for short time input. Short time typically does not include the seconds portion. The time mask is derived using the underlying culture settings.

{longtime}

{longtime} token is a place holder for long time input. Long time typically includes the seconds portion. The long time mask is derived using the underlying culture settings.

{double:-i.f:c}

{double:i.f:c} is a placeholder for a mask that allows floating point input where i and f in i.f specify the number of digits in the integer and fraction portions respectively. The :c portion of the mask is optional and it specifies that the inputting of the value should be done continuous across fraction and integer portions. For example, with :c in the mask, in order to enter 12.34 the user types in "1234". Notice that the decimal separator character is missing. This alleviates the user from having to type in the decimal separator. The "-" (minus) symbol before i.f is also optional. Presence of ‘-‘ symbol indicates that the negative values are allowed. If ‘-‘ symbol is not included then only non-negative values will be allowed.

{currency:-i.f:c}

Same as {double:i.f:c} except the mask is constructed based on currency formatting information of the underlying format provider or the culture. It typically has the currency symbol and also displays the group characters.

{number:min-max}

{number:min-max} is a place holder for a number section that can accept values in the range from min to max. Examples: {number:0-255}, {number:-10-10}.

Literal

All other symbols are displayed as literals; that is, they appear as themselves.

You can also escape the mask with {LOC} character sequence to indicate that symbols in the following table should be mapped to the associated symbols in the underlying culture settings.

Mask Character Description

$

Currency symbol.

/

Date separator.

:

Time separator.

,

Thousands separator.

.

Decimal separator.

+

Positive sign.

-

Negative sign.