Input Mask property

Use the Input Mask property to specify a mask to apply to text entered into a component (such as a telephone number). A mask serves as a template or pattern for text.

Mask characters

Character Description
> Digit placeholder (0-9). Prompt character is blank. Applies to numeric data types.
9 Digit placeholder (0-9). Prompt character is 0. Applies to numeric data types. Masks with 9 do not support Null values (see Usage Notes).
Z Digit placeholder (0-9). Prompt character is blank, and the thousands separator is not applied. Applies to numeric data types.
< Digit placeholder for decimal positions (0-9). Prompt character is blank. Removes non-meaningful trailing zeros. Applies to numeric data types.
# Digit placeholder (0-9). Prompt character is blank. Applies to numeric data types.
Note: This is available only for backward compatibility and generally is not used.
- Negative sign placeholder. Applies to numeric data types.
. Decimal placeholder. This character is treated as a literal in the mask. Applies to numeric data types.

The actual character used is the one specified in your regional settings (see Usage Notes).

, Thousands separator. This character is treated as a literal in the mask. Applies to numeric data types.

The actual character used is the one specified in your regional settings. You do not need to specify a thousands separator.

: Time separator. This character is treated as a literal in the mask. Applies to the DATE data type.

The actual character used is the one specified as a separator in your regional settings.

A Alphanumeric character placeholder (0-9 and a-Z). Applies to the CHAR data type.
? Alphabetic placeholder (a-Z). Applies to the CHAR data type.
X Alphabetic placeholder that forces characters to capital letters (A-Z). Applies to the CHAR data type.
x Alphabetic placeholder that forces characters to lowercase letters (a-z). Applies to the CHAR data type.
& Character placeholder. Valid values for this placeholder are ANSI characters in the following ranges: 32-126 and 128-255. Applies to the CHAR data type.
\ Literal escape.

To treat any of the above characters as literals, use a backslash preceding the character.

[NONE] Do not apply a mask.

Usage notes

  • Null: A numeric mask containing 9 does not support Null values; you must pass some value to the component. The mask queries Null as 0. Deleting or backspacing a value in a component produces 0. Pasting from the clipboard produces 0. If a component with the mask is not required and has no default, the component value in a new row initially shows 0 and can be saved as 0 if no value is entered.

    A numeric mask that does not contain 9 supports Null values; you can update the component with a Null or a blank value. The mask queries Null as an empty string. Deleting or backspacing a value or pasting from the clipboard produces an empty string. If a component with the mask is not required and has no default, the component value in a new row in which no value is entered in the component can be saved as Null.

  • [NONE]: The [NONE] setting removes any mask inherited from a component class, a property class extension, or other object in the inheritance hierarchy.
  • Thousands separators: Mask definitions do not have to specify thousands separators (for example, commas). These separators are set up automatically using the decimal symbol and digit-grouping symbol definitions in the Windows Control Panel Regional Options dialog box.
  • Currency: The classes that represent currency data in the system use as defaults the values in the Windows Control Panel Regional Options dialog box specified for numbers, not the values specified for currency.
  • Rounding: If the Round property is True, WinStudio rounds using the mask definition of decimal places.
  • Suppressing Trailing Zeros: For decimal values whose mask includes the < character, the value displays with non-meaningful trailing zeros removed.

Example

If the mask is set to >>>>>9.99<<< and the user enters 12345.125000, the value displays as 12,345.125. This formatting takes place after the cursor leaves the field.