MaskedTextBox

The MaskedTextBox is a specialized text box that restricts and guides operator data entry according to a specific format.

Unlike a standard TextBox, it does not allow free-text entry. Instead, it ensures input is provided only in the allowed characters (e.g., digits only, letters only) and only in the positions defined by the mask.

Common Use Cases

IP Address Entry: Enforcing the ___.___.___.___ format.
Date/Time Entry: __/__/____ __:__ (If a DateTimePicker is not preferred).
Serial Numbers: Entering specific codes like SN-____-____.
Phone Numbers: Entering data in the (___) ___-____ format.

Basic Configuration and Operation

1. Defining the Mask (Advanced Panel) The object’s core logic begins with setting the Mask property in the Advanced panel. This is the most critical setting for this control.

2. Binding the Value (Properties Panel) The text entered by the operator in accordance with the mask is linked to a SCADA tag (usually a String) via the Value property in the Properties panel.

Properties Panel – Key Properties

Value

Tag
- Function: This is a two-way link connecting the text entered by the operator (formatted by the mask) to a tag.
- Read: If the linked tag (e.g., PLC_IP_Address_Tag) is changed to “192.168.001.010” by a script or the PLC, the MaskedTextBox automatically displays this value.
- Write: When the operator enters a valid IP address into the box, this text is written to the PLC_IP_Address_Tag.
- Note: Whether the text sent to the tag includes mask characters (like ., ,, /) depends on the TextMaskFormat property in the Advanced panel.

Advanced Panel – Key Properties

Mask
- Defines the data entry format. The mask consists of a combination of special identifier characters and fixed characters (literals).
- Key Identifiers:
  - 0: Required Digit (0-9).
  - 9: Optional Digit (0-9) or Space.
  - L: Required Letter (a-z, A-Z).
  - ?: Optional Letter.
  - A: Required Alphanumeric (Letter or Digit).
  - a: Optional Alphanumeric.
- Fixed Characters (Literals):
  - Characters like ., /, -, (, ) are written directly into the mask. They are automatically skipped over and do not need to be typed by the operator.
- Mask Examples:
  - IP Address: 099.099.099.099 (Allows each field to be up to 3 digits; using 9 permits entries like __1.168.__1.__5).
  - Date: 00/00/0000 (Required 2-digit day, 2-digit month, 4-digit year).
  - Phone: (999) 000-0000
  - Serial No: SN-L000-A (e.g., “SN-C123-4”).
PromptChar
- Determines which character appears in empty spots where the operator is expected to enter data (Usually _ underscore).
TextMaskFormat
- Determines the format of the Value (text) to be written to or read from the tag.
- IncludeLiterals (Recommended): The text includes both the characters entered by the operator and the fixed characters in the mask (e.g., (555) 123-4567).
- ExcludePromptAndLiterals: The text includes only the raw data entered by the operator (e.g., 5551234567), discarding prompt characters and literals.
PasswordChar
- If you set a character here (like *), the masked input behaves like a password field, hiding the characters entered by the user.
BeepOnError
- If set to True, the system plays a sound when the MaskInputRejected event is triggered (e.g., when the user presses an invalid key, such as typing a letter in a digit-only field).

Common Usage Examples

Example: IP Address Entry

Add a MaskedTextBox to the screen.
Go to the Advanced panel:
- Mask: 099.099.099.099
- PromptChar: _ (underscore)
- TextMaskFormat: IncludeLiterals
Go to the Properties panel:
- Bind Value -> Tag to the IP_Address (String) tag.

Result: When the operator enters a value like “192.168. 1. 10”, the _ (space) characters are accepted by 9 (optional digit). The tag receives the value “192.168. 1. 10” (including spaces) or “192.168.1.10” depending on the configuration. If the operator attempts to type a letter, the MaskInputRejected event is triggered.