C1Input controls support masked input when you set the EditMask property to a mask string. 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 dashes 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.
To enable masked input, set the EditMask property to a mask string composed of placeholders and literals, see the table of available placeholders below. You can also define your own placeholders, using the CustomPlaceholders collection.
Although setting EditMask is enough in simple cases, there is also a MaskInfo property containing sub-properties controlling various important aspects of masked input. One of them is the CustomPlaceholders collection mentioned above. Some of the others are:
| Property | Description |
|---|---|
| AutoTabWhenFilled | If True, focus automatically moves to the next control when the mask is filled. Default: False. |
| PromptChar | Character displayed on empty positions. Default: '_'. |
| SaveBlanks | If True, the stored text includes blank positions as StoredEmptyChar. Default: False. |
| SaveLiterals | If True (default), the stored text (StoredContent) includes literals. |
| ShowLiterals | Enumeration controlling the way in which literals appear while the user types. They can appear always, or never, or as the user reaches a literal while typing. |
| SkipOptional | If True (default), optional mask positions are automatically skipped until the first position allowing the typed character. |
| StoredEmptyChar | Character stored in empty mask positions. Default: '_'. |
See the MaskInfo class for the complete list of mask-related properties.
If ShowLiterals property is set to FreeFormatEntry, optional mask positions can be completely omitted; there is no need to fill them with blank characters.
Mask characters (placeholders) used in C1Input are similar to those used in Microsoft Access and Microsoft ActiveX MaskedEdit control (and more placeholders can be defined using the using the CustomPlaceholders collection):
| Placeholder | Description |
|---|---|
| # | Digit placeholder permits a numeric character or a plus or minus sign in this position (entry optional). |
| . | Decimal placeholder. The actual character used is the one specified as the decimal placeholder in your 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 in your 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 in your 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 in your 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, … characters in the mask. This character is treated as a literal for masking purposes. |
| & | Character placeholder (entry required). Any character is permitted. |
| > | Convert all the characters that follow to uppercase. |
| < | Convert all the characters that follow to lowercase. |
| ~ | Turns off the previous < or >. |
| ! | Causes the optional characters that follow in the edit mask to display from right to left, rather than from left to right. So, blanks appear on the left. |
| ^ | Turns off the previous ! character. After ^, blanks appear on the right. |
| A | Alphanumeric character placeholder (entry required). For example: a – z, A – Z, or 0 – 9. |
| a | Alphanumeric character placeholder (entry optional). |
| 0 | Digit placeholder (entry required). For example: 0 – 9. |
| 9 | Digit placeholder (entry optional). |
| C | Character or space placeholder (entry optional). Any character is permitted. |
| L | Letter placeholder (entry required). For example: a – z or A – Z. |
| ? | Letter placeholder (entry optional). |
| \n | New line literal. It is applicable when Multiline property is set to True. |
| " | All characters in a string enclosed in double quotes are considered as literals. |
| Literal | All other symbols are displayed as literals; that is, as themselves. |
The telephone number mentioned above, (412) 123-4567 can be represented with a mask EditMask set to (000) 000-0000.