Uses a mask to distinguish between proper and improper user input.
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 specify the following input 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.
The custom mask property editor allows user to select a value from a list of predefined masks. The predefined lists shows the most commonly used masks.
The InvalidMessage property gets or sets a tooltip message that is shown for an invalid entry.
Using the MaskedTextBox's TypeValidationCompleted event handler, any custom behavior can be defined for success or failure of the mask's validation.
The TextMaskFormat property determines how the literal and prompt characters in the mask are processed when the generating the formatted string. More specifically, it determines whether literal characters, prompt characters, or both are included in the Text property. When prompt characters are excluded, they are transformed into spaces in the formatted string.
ExcludePromptAndLiterals: Return only text input by the user.
IncludeLiterals: Return text input by the user as well as any literal characters defined in the mask.
IncludePrompt: Return text input by the user as well as any instances of the prompt character.
IncludePromptAndLiterals: Return text input by the user as well as any literal characters defined in the mask and any instances of the prompt character.
The color of the text in the MaskedTextBox control can be customized by setting the ForeColor property.
| Item | Description |
|---|---|
Class name
"wisej.web.MaskedTextBox"
Theme Appearance
"textbox"
Child components
"textfield" is the inner <input> widget. See JavaScript.
Toolcontainer state
"editor", see Embedded Tools.
Source code
Represents an <input> element that can be used to edit unformatted text.
The Wisej.Web.TextBox control allows the user to enter unformatted text in an application.
Usually a TextBox control accepts a single line of text. You can use the Multiline property to allow the control to display and accept text on more than one line.
For a full list of properties, methods and events see the API documentation.
The TextBox control supports the inline Label property. This allows an application to set a label in relation to a TextBox control without having to create an additional Label control.
Data binding is fully supported, including formatting and conversion of the value, through the default data binding infrastructure. For the TextBox, the default data property is Text.
You can enable the browser's built-in spell checking by setting the SpellCheck property to true.
This functionality is entirely based on the browser's current language and spell checking support. If you need to use a third party spell checking you can, but it's outside of the Wisej functionality.
This is one of the most useful feature that Wisej adds to most controls. The Tools property allows the application to add internal buttons aligned left or right and handle user clicks through the ToolClicked event.
Some events exposed by the TextBox control are fired only when there is a handler attached to the event. This features prevents the browser from sending frequent events unless the application has explicitly subscribed to the event.
For example, the KeyDown event is a Lazy Event, otherwise the browser would fire an ajax request every time the user typed a character in the TextBox.
If you extend a control class and override the On[EventName] method to handle a lazy event without attaching a handler, your code will not be called unless there is an handler attached to the event.
All editable controls in Wisej expose the Watermark property. It displays background text in the field when it's empty.
Wisej renders the watermark property to the placeholder HTML attribute, if it's supported by the browser, otherwise it creates an overlaid label entirely managed by the Wisej JavaScript library.
Set the PasswordChar property to any character or the InputType property to Password to display a password input field in the browser. The character that you assign to the PasswordChar property is irrelevant (Wisej will always convert it to "*") because you cannot change what the browser displays in password fields. This property exists for compatibility with WinForms migrations.
To implement the common "eye" button that shows or hides the password, simply use the Tools to add an icon and change the InputType to Text and Password.
Use the CharacterCasing property to force the browser and the server to change the casing of the text entered by the user. Wisej performs the transformation on the client when typing and on the server when assigning the Text property.
When typing in a TextBox, pressing the Tab key will move the focus to the next control and pressing the Enter key will do nothing. If your application needs to include tabs and new lines in the text, set the Multiline property to true and the AcceptsTab or the AcceptsReturn properties to true.
To limit the characters that are accepted by a TextBox you have to handle the browser's keydown event on the client in JavaScript.
It is not possible to stop the <input> element from accepting a character by handling the KeyDown event on the server side - the event has already happened and it has already been processed by the browser by the time it reaches the server.
There are two ways to filter the keyboard input: set the Filter property to a regular expression or handle the keydown event on the client with JavaScript.
For example, setting the Filter property to "[a-zA-Z]" will allow the user to only type alphabetical characters in the range a-z or A-Z. To achieve the same with JavaScript on a client event, add an handler for the keydown event.
There are several ways to customize the appearance of a TextBox: use the available properties, customize the theme, or adding custom styles.
The properties that can change the appearance of a TextBox (and most controls) are usually limited to BackColor, ForeColor, BorderStyle, and Font properties.
If you need to achieve some very special UI design, like the Material-3 animated underline when the TextBox gains the focus, you will have to either create a custom theme, or a theme mixin or add custom styles to the control.
You can see in the image above a TextBox with "border-radius:20px" assigned to the CssStyle property. To apply a shared style, set the CssClass property instead and add a StyleSheet file (.css) to the application either in Default.html or using the StyleSheet extender.
A TextBox is usually just a text box where the user can type. However, browsers expanded the "type" attribute of the <input> element considerably to use native custom editors.
Wisej supports setting most of the input types through the InputType property.
The appearance of the native input types can be styled to a very limited extent using a CSS style sheet and some browser-specific properties. It is entirely outside of the Wisej theming system.
The value that is returned to the Text property is always (obviously) a string that represents the value in the native input control. Some input types have some special requirements:
Radio
When the user clicks the checkbox, it flips the Checked property and fires the CheckedChanged event. It does not fire the TextChanged event. The text value when checked in "on".
Browsers do not fire any event on the <input type=radio> elements.
Content cannot be localized, it depends always on the browser's language.
Checkbox
When the user clicks the checkbox, it flips the Checked property and fires the CheckedChanged event. It does not fire the TextChanged event. The text value when checked in "on".
You can use the AutoCompleteList property to assign a string array to the TextBox control and take advantage of the browser's native autocomplete functionality.
As the user starts typing, the browser will provide a filtered list of the texts in the AutoCompleteList array_._
You use the AutoComplete_ _property to turn this functionality on or off. When AutoComplete is on (or default which is off in Wisej), the browser may also build its own autocomplete list.
You can also find preset AutoComplete options within the property, here are a few:
You can find a full list of AutoComplete options on the Mozilla Developer Site.
This functionality is entirely dependent on the browser. Including when to use its own autocomplete list from previously entered values.
Wisej selects the full text in the TextBox when tabbing from field to field. However, when the user clicks (or taps) into a TextBox, the cursor is placed at the tap location.
You can force the automatic full selection of the text every time the TextBox is focused by setting the SelectOnEnter property to true.
The property EnableNativeContextMenu (default: true) allows the browser to display its native context menu when the user right clicks on the text in the TextBox. If you set this property to false, right clicking (or long tapping) will not display the native context menu.
If the TextBox has been assigned a ContextMenu, it always suppresses the native context menu and uses the one assigned by the application.
Represents a data field that displays a list of selectable and removable tags. The control recognizes tags as the user types and adds in front of the editable field.
The TagTextBox is an easy way for users to select a range of values.
By default, the TagTextBox control will automatically resize to fit its contents. This includes font size changes and tag overflow.
To get the TagTextBox control to grow horizontally, set the MaximumSize property of the control.
The TagTextBox control allows selecting from a list of preset items defined in the AutoCompleteList property.
The drop down is showing using an <input> element with a specified <datalist>.
The MaxLength, MaxTagCount, MaxTagWidth, and MinFieldLength properties provide options to configure the maximum tag length and count.
MaxLength: Specifies the maximum number of characters that can be entered into the edit control.
MaxTagCount: Returns or sets the maximum number of tags allowed in the control.
MaxTagWidth: Returns or sets the maximum width in pixels of the tag widgets.
MinFieldLength: Returns or sets the minimum number of characters that should fit in the editable portion of the control before it wraps to a new line.
The colors of the tags in the TagTextBox control can be customized using the Theme Builder, a mixin, or applied directly in code.
The tagtextbox appearance has a child component, tag, which can be customized based on any of it's given states.
The custom TagTextBox appearance can be applied using a mixin in the project.
Add the mixin definition above to the /Themes directory in your project.
The theme can be modified at runtime to include the custom TagTextBox appearance.
Allows the user to enter a typed value
You can use the TypedTextBox to define the type of Value property to which the text should be parsed, a.NET format string (standard or custom), and whether the formatted string should be preserved when editing or removed when entering the editor.
For a full list of properties, methods and events see the
You can take over the parsing and formatting using the CustomFormatChanged, Format and Parse events.
CustomFormat can be set to a .NET format string. For examples, consult the .NET documentation in the following links:
ValueType determines the Type of the Value of the TypedTextBox- ie System.String, System.DateTime, System.int32, System.Int64, System.Boolean, System.Decimal, System.Double or System.Single.
If KeepFormatOnEnter is true, the format will be kept when the user presses enter or clicks to move the cursor within the TypedTextBox. If false, the format is not shown while the user is editing the contents of the TypedTextBox. When working with currencies, you may want to set KeepFormatOnEnter to false so the user is not confused by the currency symbol in the text as they are typing.
| Option | Description |
|---|---|
| Item | Description |
|---|---|
| Item | Description |
|---|---|
An email address.
Username
A username or account name.
NewPassword
A new password.
When creating a new account or changing passwords, this should be used for an "Enter your new password" or "Confirm new password" field, as opposed to a general "Enter your current password" field that might be present.
CurrentPassword
The user's current password.
OneTimeCode
A one-time code used for verifying user identity.
Class name
"wisej.web.TextBox" or "wisej.web.TextArea" when Multiline is true.
Theme appearance
"textbox", see Themes.
Child components
"textfield" is the inner <input> widget. See JavaScript.
Toolcontainer state
"editor", see Embedded Tools.
Source code
Class name
"wisej.web.TagTextBox"
Theme Appearance
"tagtextbox", inherited from "textbox".
Child components
"textfield" is the inner <input> widget. See JavaScript.
Toolcontainer state
"editor", see Embedded Tools.
Source code
