MaskedTextBox

Wisej.Web.MaskedTextBox

Namespace: Wisej.Web

Assembly: Wisej.Framework (3.1.0.0)

Control
- TextBoxBase
  - MaskedTextBox

Uses a mask to distinguish between proper and improper user input.

public class MaskedTextBox : TextBoxBase

Public Class MaskedTextBox
    Inherits TextBoxBase

The MaskedTextBox class is an enhanced TextBox control that supports a declarative syntax for accepting or rejecting user input. Using the Mask property, you can enforce the following input types without writing any custom validation logic in your application:

Required input characters.
Optional input characters.
The type of input expected at a given position in the mask; for example, a digit, or an alphabetic or alphanumeric character.
Mask literals, or characters that should appear directly in the MaskedTextBox; for example, the hyphens(-) in a phone number, or the currency symbol in a price.
Special processing for input characters; for example, to convert alphabetic characters to uppercase.
Special processing for input characters; for example, to convert alphabetic characters to uppercase.

When a MaskedTextBox control is displayed at run time, it represents the mask as a series of prompt characters and optional literal characters. Each editable mask position, representing a required or optional input, is shown with a single prompt character. For example, the number sign (#) is often used as a placeholder for a numeric character input. You can use the PromptChar property to specify a custom prompt character. The HidePromptOnLeave property determines if the user sees the prompt characters when the control loses input focus

Constructors

MaskedTextBox()

Initializes a new instance of the MaskedTextBox class using defaults.

MaskedTextBox(mask)

Initializes a new instance of the MaskedTextBox class using the specified input mask.

Name	Type	Description
mask	String	A String representing the input mask.

Name

Type

Description

mask

String

A String representing the input mask.

Throws:

ArgumentNullException mask is null.

Properties

CharacterCasing

CharacterCasing: Returns or sets whether the MaskedTextBox control modifies the case of characters as they are typed. (Default: Normal)

Culture

CultureInfo: Returns or sets the culture information associated with the masked text box.

HidePromptOnLeave

Boolean: Returns or sets whether the prompt characters in the input mask are hidden when the masked text box loses focus. (Default: False)

InputType

InputType: Specifies the type, min, max and step properties to associate to the <input> element. (Default: null)

Mask

String: Returns or sets the input mask. (Default: "")

The Mask is a string that defines the masking characters and the literals to display and process during user input and when reading the Text property. Server side masking is processed by an instance of the MaskedTextProvider class exposed by the MaskedTextProvider property. On the client side, the mask processing is performed by the "wisej.utils.MaskProvider.js" class while the user edits the input field.

Masking Character	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. This element behaves like the "L" element.
C	Character, optional. Any non-control character. This element behaves like the "?" element.
A	Alphanumeric, required. The only characters it will accept are the ASCII letters a-z and A-Z. This mask element behaves like the "a" element.
a	Alphanumeric, optional. The only characters it will accept are the ASCII letters a-z and A-Z. This mask element behaves like the "A" element.
.	Decimal placeholder. The actual display character used will be the decimal symbol appropriate to the format provider, as determined by the control's FormatProvider property.
,	Thousands placeholder. The actual display character used will be the thousands placeholder appropriate to the format provider, as determined by the control's FormatProvider property.
:	Time separator. The actual display character used will be the time symbol appropriate to the format provider, as determined by the control's FormatProvider property.
/	Date separator. The actual display character used will be the date symbol appropriate to the format provider, as determined by the control's FormatProvider property.
$	Currency symbol. The actual character displayed will be the currency symbol appropriate to the format provider, as determined by the control's FormatProvider property.
<	Shift down. Converts all characters that follow to lowercase.
>	Shift up. Converts all characters that follow to uppercase.

\	Escape. Escapes a mask character, turning it into a literal. "\" is the escape sequence for a backslash.
Others	Literals. All non-mask elements will appear as themselves within MaskedTextBox. Literals always occupy a static position in the mask at run time, and cannot be moved or deleted by the user.

Masking Character

Description

Digit, required. This element will accept any single digit between 0 and 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.

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. This element behaves like the "L" element.

Character, optional. Any non-control character. This element behaves like the "?" element.

Alphanumeric, required. The only characters it will accept are the ASCII letters a-z and A-Z. This mask element behaves like the "a" element.

Alphanumeric, optional. The only characters it will accept are the ASCII letters a-z and A-Z. This mask element behaves like the "A" element.

Decimal placeholder. The actual display character used will be the decimal symbol appropriate to the format provider, as determined by the control's FormatProvider property.

Thousands placeholder. The actual display character used will be the thousands placeholder appropriate to the format provider, as determined by the control's FormatProvider property.

Time separator. The actual display character used will be the time symbol appropriate to the format provider, as determined by the control's FormatProvider property.

Date separator. The actual display character used will be the date symbol appropriate to the format provider, as determined by the control's FormatProvider property.

Currency symbol. The actual character displayed will be the currency symbol appropriate to the format provider, as determined by the control's FormatProvider property.

Shift down. Converts all characters that follow to lowercase.

Shift up. Converts all characters that follow to uppercase.

Escape. Escapes a mask character, turning it into a literal. "\" is the escape sequence for a backslash.

Others

Literals. All non-mask elements will appear as themselves within MaskedTextBox. Literals always occupy a static position in the mask at run time, and cannot be moved or deleted by the user.

If you change the Mask when the control already contains a value, it will apply the new mask to the existing text. The decimal (.), thousand (,), time (:), date (/), and currency ($) symbols default to displaying those symbols as defined by the application's culture. You can force a specific MaskedTextBox to display symbols for another culture by using the Culture property. Otherwise you can set the application-wide culture by setting the CurrentCulture property.

MaskedTextProvider

MaskedTextProvider: Returns the mask provider associated with this instance of the masked text box control.

PasswordChar

Char: Returns or sets the character used to mask characters of a password in a single-line MaskedTextBox control. (Default: "\0")

This property only enables/disables the password mode for the textbox. It doesn't change the password masking character used by the browser.

PromptChar

Char: Returns or sets the character used to represent the absence of user input in the MaskedTextBox control. (Default: _)

Throws:

ArgumentException The character specified when setting this property is not a valid prompt character.

RejectInputOnFirstFailure

Boolean: Returns or sets whether the parsing of input text should stop after the first invalid character is reached. (Default: False)

SpellCheck

Boolean: Returns or sets whether the text in the MaskedTextBox is spell checked by the browser. (Default: False)

Text

String: Returns or sets the current text in the text box. (Default: "")

TextAlign

HorizontalAlignment: Returns or sets how text is aligned in a TextBox control. (Default: Left)

TextLength

Int32: Returns the length of text in the control.

TextMaskFormat

MaskFormat: Returns or sets a value that determines whether literals and prompt characters are included in the formatted string. (Default: IncludeLiterals)

ValidatingType

Type: Returns or sets the data type used to verify the data input by the user. (Default: null)

Methods

ValidateText()

Converts the user input string to an instance of the validating type.

Returns: Object. If successful, an Object of the type specified by the ValidatingType property; otherwise, null to indicate conversion failure.

Throws:

Exception A critical exception occurred during the parsing of the input string.

Events

CultureChanged

EventHandler Fired when the value of the Culture property has changed.

MaskChanged

EventHandler Fired when the value of the Mask property has changed.

TextAlignChanged

EventHandler Fired when the value of the TextAlign property has changed.

TypeValidationCompleted

TypeValidationEventHandler Occurs when MaskedTextBox has finished parsing the current value using the ValidatingType property.

Inherited By

Name	Description
DataGridViewMaskedTextBoxEditingControl	Represents a MaskedTextBox control that can be hosted in a DataGridViewMaskedTextBoxCell cell.

Name

Description

DataGridViewMaskedTextBoxEditingControl

Represents a MaskedTextBox control that can be hosted in a DataGridViewMaskedTextBoxCell cell.

Implements

Name	Description
IBindableComponent	Bindable components implement this interface.
IDropTarget	Controls that support drag & drop operations implement this interface.
ILabel	Provides access to the LabelWrapper associated with the controls that implement this interface.
IReadOnly	Provides access to the ReadOnly property for coontrols that support the read-only mode.
IModified	Provides access to the Modified property and ModifiedChanged event for controls that implement this interface.
IWisejComponent	All wisej components implement this interface.
IWisejControl	All wisej controls derived from the Control class must implement this interface.
IWisejSerializable	Allows an object to serialize itself.

Name

Description

IBindableComponent

Bindable components implement this interface.

IDropTarget

Controls that support drag & drop operations implement this interface.

ILabel

Provides access to the LabelWrapper associated with the controls that implement this interface.

IReadOnly

Provides access to the ReadOnly property for coontrols that support the read-only mode.

IModified

Provides access to the Modified property and ModifiedChanged event for controls that implement this interface.

IWisejComponent

All wisej components implement this interface.

IWisejControl

All wisej controls derived from the Control class must implement this interface.

IWisejSerializable

Allows an object to serialize itself.

Last updated 1 year ago