Infragistics(R) NetAdvantage(R) : Silverlight 2011.2
Masks
E-mail your feedback on this topic.

Glossary Item Box

Introduction

The xamMaskedInput™ and other input controls based on the xamMaskedInput™ control (e.g., xamCurrencyInput™, xamNumericInput™, and xamDateTimeInput™) expose the Mask Property. The following table lists all possible mask characters and tokens that the mask syntax supports.

Note: Not all masks are relevant for every input control. For instance, you wouldn’t normally use a mm:ss (minutes and seconds mask) in a xamCurrencyInput control. The “Use with” column of the table below maps the commonly used mask characters to the input controls. Also, the masks depend on the ValueType of the control. For example if you set the ValueType property of a xamNumericInput control to Int32, it’s unnecessary to use a mask containing decimal placeholder character.

Mask Character Title Use with: Description
# Digit placeholder xamCurrencyInput xamNumericInput xamMaskedInput Characters must be numeric (0-9) and entry is required. Example: (###)-###-####.
. Decimal placeholder xamCurrencyInput xamNumericInput xamMaskedInput Characters are required as specified as the decimal placeholder as defined by the system's international settings. Characters are treated as literals for masking purposes.
, Thousands separator xamCurrencyInput xamNumericInput xamMaskedInput Characters are delimited by the thousands separator as defined by the system's international settings. This character is treated as a literal for masking purposes.
: Time separator xamDateTimeInput xamMaskedInput Characters are delimited by the time separator as defined by the system's international settings. This character is treated as a literal for masking purposes.
/ Date separator xamDateTimeInput xamMaskedInput This character is also treated as a literal for masking purposes.
\ Escape next chatacter xamMaskedInput This character instructs the mask to 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 xamMaskednput Valid values for this placeholder are ANSI characters in the following ranges: 32-126 and 128-255 (keyboard and foreign symbol characters).
> xamMaskedInput Converts all characters that follow to uppercase
< xamMaskedInput Converts all characters that follow to lowercase
Note: If you use this character in a mask set in XAML you need to escape it using the &lt; character sequence.
A Alphanumeric character placeholder xamMaskedInput Represents an alphanumeric character. For example: a-z, A-Z, or 0-9. Character entry is required.
a Alphanumeric character placeholder xamMaskedInput For example: a-z, A-Z, or 0-9. Character entry is not required.
9 Digit placeholder xamCurrencyInput xamNumericInput xamMaskedInput Character must be numeric (0-9) but entry is not required.
h Hexadecimal digit placeholder xamNumericInput xamMaskedInput 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 Hexadecimal digit placeholder xamNumericInput xamMaskedInput Same as 'h' placeholder however the a-f digits are converted to upper case.
- Minus sign (optional) xamCurrencyInput xamNumericInput xamMaskedInput 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 is only shown when the number is actually negative.
+ Plus sign (optional) xamCurrencyInput xamNumericInput xamMaskedInput 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 always shows a '+' or a '-' sign depending on whether the number is positive or negative.
C Character or space placeholder xamMaskedInput Character entry is not required. This operates exactly like the '&' placeholder, and ensures compatibility with Microsoft Access.
? Letter placeholder xamMaskedInput For example: a-z or A-Z. Character entry is not required.
n Digit placeholder xamCurrencyInput xamNumericInput xamMaskedInput 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} Arbitrary set of accepted characters xamMaskedInput

The {char:n:s} mask allows you to define a placeholder with arbitrary set of acceptable characters. The 'n' in the mask specifies the number of character placeholders in the mask. The '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 is 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 Date characters xamDateTimeInput xamMaskedInput The combination of these three tokens is used to define a date mask. The mm is 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 Time characters xamDateTimeInput xamMaskedInput The combination of these tokens is used to define a time mask. The hh is for hour, mm for minute, ss for second, and tt for AM/PM. Examples: hh:mm, hh:mm tt, hh:mm:ss.
{date:s} Short date xamDateTimeInput xamMaskedInput The {date} token is a placeholder for short date input. The date mask is derived using the underlying culture settings.
{time} Short time xamDateTimeInput xamMaskedInput The {time} token is a placeholder for short time input. Short time typically does not include the seconds portion of time. The time mask is derived using the underlying culture settings.
{longtime} Long time xamDateTimeInput xamMaskedInput The {longtime} token is a placeholder for long time input. Long time typically includes the seconds portion of the time. The long time mask is derived using the underlying culture settings.
{double:-i.f:c} Customized floating poing input xamNumericInput xamMaskedInput The {double:i.f:c} token is a placeholder for a mask that allows floating point input where i and f specify the number of digits in the integer and fraction portions respectively. The :c portion of the mask is optional and specifies that the value must be 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 manually 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} Customized currency input xamCurrencyInput 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} Range of numbers xamCurrencyInput xamNumericInput xamMaskedInput The {number:min-max} placeholder is used for a number section that can accept values in the range from min to max. Examples: {number:0-255}, {number:-10-10}.
Literal All input controls 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. A code example is available below.

 

Mask Character Description
$ Currency symbol
/ Date separator
: Time separator
, Thousands separator
. Decimal separator
+ Positive sign
- Negative sign

Code Example: Using the {LOC} character sequence in a mask

The code below demonstrates an example use of the {LOC} character sequence, used to map special symbols from the table above to their corresponding symbols in the underlying culture settings:

If the date separator character in the system’s regional settings is ‘.’ and you use the following code:

In XAML:

<ig:XamDateTimeInput Mask="{}{LOC}dd/mm/yy"/>

Note: The escape sequence ({}) is used so an open brace ({) can be used as a literal character in XAML.

This is how the xamDateTimeInput control renders while using the {LOC} token:

If you don’t include the {LOC} token, the control’s mask string simply uses basic mask characters:

In XAML:

<ig:XamDateTimeInput Mask="dd/mm/yy"/>

When using plain mask characters, the control uses the forward slashes from the mask as date separators: