The C1MaskedInput control uses a mask to distinguish between proper and improper user input. You can define the mask through the visual designers, for example, the C1MaskedInput Smart Tag or the C1MaskedInput Designer, or programmatically through the C1MaskedInput object.
For common C1MaskedInput tasks, see the C1MaskedInput Tasks topic.
C1MaskedInput Mask Types
The following table lists some examples of masks and their behaviors:
|
Mask |
Behavior |
|
00/00/0000 |
A date (day, numeric month, year) in international date format. The "/" character is a logical date separator, and will appear to the user as the date separator appropriate to the application's current culture. Note that to specify date patterns, you can use the C1DateInput control, which provides a much richer interface for entering dates and times. |
|
00->L<LL-0000 |
A date (day, month abbreviation, and year) in United States format in which the three-letter month abbreviation is displayed with an initial uppercase letter followed by two lowercase letters. |
|
(999) 000-0000 |
United States phone number, area code optional. If users do not want to enter the optional characters, they can either enter spaces or place the mouse pointer directly at the position in the mask represented by the first 0. |
|
$999,999.00 |
A currency value in the range of 0 to 999999. The currency, thousandth, and decimal characters will be replaced at run time with their culture-specific equivalents. |
Mask is a default property for the C1MaskedInput control. If you define an edit mask, each character position in the control maps to either a special placeholder or a literal character. Literal characters, or literals, can give visual cues about the type of data being used. For example, the parentheses surrounding the area code of a telephone number and dash are literals: (412) 123-4567. The edit mask prevents you from entering invalid characters into the control and provides other enhancements of the user interface.
C1MaskedInput Characters
To enable masked input, set the Mask property to a mask string composed of one or more placeholders and literals, the following table lists available placeholders:
|
Masking Element |
Description |
|
0 |
Digit, required. This element will accept any single digit between 0 and 9. |
|
9 |
Digit or space, optional. |
|
# |
Digit or space, optional. If this position is blank in the mask, it will be rendered as a space in the Text property. Plus (+) and minus (-) signs are allowed. |
|
L |
Letter, required. Restricts input to the ASCII letters a-z and A-Z. This mask element is equivalent to [a-zA-Z] in regular expressions. |
|
? |
Letter, optional. Restricts input to the ASCII letters a-z and A-Z. This mask element is equivalent to [a-zA-Z]? in regular expressions. |
|
& |
Character, required. |
|
C |
Character, optional. Any non-control character. |
|
A |
Alphanumeric, optional. |
|
. |
Decimal placeholder. The actual display character used will be the decimal placeholder appropriate to the Culture property. |
|
, |
Thousands placeholder. The actual display character used will be the thousands placeholder appropriate to the Culture property. |
|
: |
Time separator. The actual display character used will be the time placeholder appropriate to the Culture property. |
|
/ |
Date separator. The actual display character used will be the date placeholder appropriate to the Culture property. |
|
$ |
Currency symbol. The actual character displayed will be the currency symbol appropriate to the Culture property. |
|
< |
Shift down. Converts all characters that follow to lowercase. |
|
> |
Shift up. Converts all characters that follow to uppercase. |
|
| |
Disable a previous shift up or shift down. |
|
\ |
Escape. Escapes a mask character, turning it into a literal. "\\" is the escape sequence for a backslash. |
|
<<n...m>> |
Restricts the user input to the declared numeric range, for example, <<0...255>>. |
|
<<Value1|Value2|Value3>> |
Restricts the user input to one of the set options. Character ("|") serves as a separator between the option values, for example, <<Option One|Option Two|Option Three>>. |
|
All other characters |
Literals. All non-mask elements will appear as themselves within the C1MaskedInput. Literals always occupy a static position in the mask at run time, and cannot be moved or deleted by the user. |
If you change a mask when C1MaskedInput already contains user input filtered by a previous mask, C1MaskedInput will attempt to migrate that input into the new mask definition.
To set the C1MaskedInput.Mask property, follow these steps:
1. Select the C1MaskedInput control, and click its smart tag to open the C1MaskedInput Tasks menu.
2. Click the ellipsis button next to the Mask property. The Input Mask dialog box appears.
3. Select a Data Format and then define the mask in the Mask text box. Notice the Preview text box displays a preview of the mask.
4. Click OK to close the Input Mask dialog box.
|
