# MaskedTextBox

The Wisej.NET `MaskedTextBox` enhances the `TextBox` control with declarative input validation. The `Mask` property enables specifying:

* Required input characters
* Optional input characters
* Input type expected at each mask position (digit, alphabetic, alphanumeric)
* Mask literals (characters appearing directly in the `MaskedTextBox`, like hyphens in phone numbers or currency symbols)
* Special character processing (e.g., converting to uppercase)

## Features

### Preset Masks

The custom mask property editor provides selection from predefined, commonly used masks.

![MaskedTextBox mask property editor](https://553579532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MF1D11gPs_az3xaKusw%2Fuploads%2Fgit-blob-be9f18c48a8d1cef8bcfbd269951f682771b2f59%2Fimage.png?alt=media)

### Custom Error Handling

The `InvalidMessage` property sets a tooltip message for invalid entries.

![MaskedTextBox showing invalid input message](https://553579532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MF1D11gPs_az3xaKusw%2Fuploads%2Fgit-blob-2eaaebc68a74cdd24c61fe615dedddfedd592048%2Fimage.png?alt=media)

The `TypeValidationCompleted` event handler enables custom validation behavior.

![MaskedTextBox with custom validation handling](https://553579532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MF1D11gPs_az3xaKusw%2Fuploads%2Fgit-blob-1e9fba10fbfca40d811502f7382ab4905941b43b%2FMaskedTextBox.gif?alt=media)

### Text Mask Format

The `TextMaskFormat` property determines literal and prompt character processing in the formatted string, controlling their inclusion in the `Text` property. Excluded prompt characters convert to spaces.

* `ExcludePromptAndLiterals`: Shows only user input text
* `IncludeLiterals`: Shows user input and mask literal characters
* `IncludePrompt`: Shows user input and prompt characters
* `IncludePromptAndLiterals`: Shows user input, literal characters, and prompt characters

## How To

### Customize the Appearance

Customize text color using the `ForeColor` property.

## Advanced

### JavaScript Widget

| Item                | Description                                                                                                              |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Class name          | "wisej.web.MaskedTextBox"                                                                                                |
| Theme Appearance    | "textbox"                                                                                                                |
| Child components    | "textfield" is the inner \<input> widget. See [JavaScript](https://docs.wisej.com/docs/concepts/javascript-object-model) |
| Toolcontainer state | "editor", see [Embedded Tools](https://docs.wisej.com/docs/controls/general/embedded-tools)                              |
| Source code         | [https://github.com/iceteagroup/wisej-js](https://github.com/iceteagroup/wisej-js/blob/master/wisej.web.TextBox.js)      |