Configuration
An object defining configuration options for the dxTextBox widget.
accessKey
Specifies a shortcut key that sets focus on the widget element.
The accessKey option value is passed to the accesskey attribute of the actual HTML element of the widget.
activeStateEnabled
A Boolean value specifying whether or not the widget changes its state when interacting with a user.
This option is used when the widget is displayed on a platform whose guidelines include the active state change for widgets.
disabled
A Boolean value specifying whether or not the widget can respond to user interaction.
Create an observable variable and assign it to this option to specify the availability of the widget at runtime.
height
Specifies the height of the widget.
The option can hold a value of the following types.
number
The height of the widget in pixelsstring
A CSS measurement of the widget height (e.g., "55px", "80%", "auto" and "inherit")function
A function returning the widget height (e.g., height:function(){ return baseHeight - 10 + "%"; })
hoverStateEnabled
A Boolean value specifying whether or not the widget changes its state when being hovered by an end user.
isValid
Specifies whether the editor's value is valid.
In Knockout approach, you may need to use an editor to inform end users that an error occurred during the validation of a ViewModel field. In this instance, set the editor's isValid option to the isValid property value of the dxValidator that validated the ViewModel's field. In addition, set the editor's validationError option to the validationError property value of the dxValidator object.
In the code below, the login specified by an end user is validated on the level of the ViewModel. If validation of the login value fails, a validation message is displayed on the Login editor.
<div data-bind="dxTextBox: { value: login, isValid: login.dxValidator.isValid, validationError: login.dxValidator.validationError, placeholder: 'Login' }"></div>
var viewModel = { login: ko.observable("").extend({ dxValidator: { validationRules: [{ type: 'required', message: 'Login is required' }] } }), //... }
See Also
mask
The editor mask that specifies the format of the entered string.
A mask can contain the following elements.
Masking Element | Description |
---|---|
0 | A digit. |
9 | A digit or a space. |
# | A digit, a space, "+" or "-" sign. |
L | A literal. |
C | Any character except space. |
c | Any character. |
A | An alphanumeric. |
a | An alphanumeric or a space. |
maskRules
Specifies custom mask rules.
Each field of an object passed to this option corresponds to a single rule. A field name is a character used in a mask enclosed in quotes. A field accepts the following values.
var CustomMaskRules = { // a single character 's': '$', // a regular expression 'h': /[0-9A-F]/, // an array of characters 'n': ['$', '%', '&', '@'], // a function 'f': function(char) { var allowedChars = ['a', 'b', 'c', '$', '_', '.']; for(var i = 0; i < allowedChars.length; i++) { if (char === allowedChars[i]) return true; } return false; } }
A function that specifies a custom rule accepts a character as an argument and returns a Boolean value that specifies whether or not the character is appropriate.
maxLength
Specifies the maximum number of characters you can enter into the textbox.
If the number of entered characters reaches the value assigned to this option, the widget does not allow you to enter any more characters.
mode
The "mode" attribute value of the actual HTML input element representing the text box.
The value of this option affects the set of keyboard buttons shown on the mobile device when the widget gets focus. In addition, the following mode values add visual features to the widget:
- 'search' - the text box contains the 'X' button, which clears the text box contents
- 'password' - the text box shows a password character instead of the actual characters typed
onChange
A handler for the change event.
Provides function parameters.
Provides access to the widget instance.
An HTML element of the widget.
Provides access to the data that is available for binding against the element. Available only in the Knockout and AngularJS approaches.
Specifies the jQuery event that caused action execution.
Assign a function to perform a custom action when a change within the widget's input element is committed by an end user. [note]The function assigned to this option is executed only if the widget looses focus.
onCopy
A handler for the copy event.
Provides function parameters.
Provides access to the widget instance.
An HTML element of the widget.
Provides access to the data that is available for binding against the element. Available only in the Knockout and AngularJS approaches.
Specifies the jQuery event that caused the action execution.
Assign a function to perform a custom action after the widget's input is copied.
onCut
A handler for the cut event.
Provides function parameters.
Provides access to the widget instance.
An HTML element of the widget.
Provides access to the data that is available for binding against the element. Available only in the Knockout and AngularJS approaches.
Specifies the jQuery event that caused the action execution.
Assign a function to perform a custom action after the widget's input is cut.
onDisposing
A handler for the disposing event.
Provides function parameters.
onEnterKey
A handler for the enterKey event.
Provides function parameters.
Provides access to the widget instance.
An HTML element of the widget.
Provides access to the data that is available for binding against the element. Available only in the Knockout and AngularJS approaches.
Specifies the jQuery event that caused the action execution.
Assign a function to perform a custom action after the Enter key is pressed within the widget's input element.
onFocusIn
A handler for the focusIn event.
Provides function parameters.
Provides access to the widget instance.
An HTML element of the widget.
Provides access to the data that is available for binding against the element. Available only in the Knockout and AngularJS approaches.
Specifies the jQuery event that caused the action execution.
Assign a function to perform a custom action after the widget's input is focused.
onFocusOut
A handler for the focusOut event.
Provides function parameters.
Provides access to the widget instance.
An HTML element of the widget.
Provides access to the data that is available for binding against the element. Available only in the Knockout and AngularJS approaches.
Specifies the jQuery event that caused the action execution.
Assign a function to perform a custom action after the widget's input element loses focus.
onInitialized
A handler for the initialized event.
Assign a function to perform a custom action when the widget is initialized.
onInput
A handler for the input event.
Provides function parameters.
Provides access to the widget instance.
An HTML element of the widget.
Provides access to the data that is available for binding against the element. Available only in the Knockout and AngularJS approaches.
Specifies the jQuery event that caused action execution.
Assign a function to perform a custom action when a value within the widget's input element is changed by an end user.
onKeyDown
A handler for the keyDown event.
Provides function parameters.
Provides access to the widget instance.
An HTML element of the widget.
Provides access to the data that is available for binding against the element. Available only in the Knockout and AngularJS approaches.
Specifies the jQuery event that caused action execution.
Assign a function to perform a custom action when a key is pressed down within the widget's input element.
onKeyPress
A handler for the keyPress event.
Provides function parameters.
Provides access to the widget instance.
An HTML element of the widget.
Provides access to the data that is available for binding against the element. Available only in the Knockout and AngularJS approaches.
Specifies the jQuery event that caused the action execution.
Assign a function to perform a custom action when the keypress DOM event is raised for the current input element.
onKeyUp
A handler for the keyUp event.
Provides function parameters.
Provides access to the widget instance.
An HTML element of the widget.
Provides access to the data that is available for binding against the element. Available only in the Knockout and AngularJS approaches.
Specifies the jQuery event that caused action execution.
Assign a function to perform a custom action when a key is released within the widget's input element.
onOptionChanged
A handler for the optionChanged event.
Provides function parameters.
Provides access to the widget instance.
Specifies the name of the option whose value is changed.
Specifies a full name of the option whose value is changed. The full name is formed by concatenating the names of the options that are presented in the hierarchy of the given option. The names are delimited by commas.
Specifies a new value for the option.
An HTML element of the widget.
Provides access to the data that is available for binding against the element. Available only in the Knockout and AngularJS approaches.
Assign a function to perform a custom action after an option of the component is changed.
onPaste
A handler for the paste event.
Provides function parameters.
Provides access to the widget instance.
An HTML element of the widget.
Provides access to the data that is available for binding against the element. Available only in the Knockout and AngularJS approaches.
Specifies the jQuery event that caused the action execution.
Assign a function to perform a custom action after the widget's input is pasted.
onValueChanged
A handler for the valueChanged event.
Provides function parameters.
Provides access to the widget instance.
An HTML element of the widget.
Provides access to the data that is available for binding against the element. Available only in the Knockout and AngularJS approaches.
The widget's new value.
The widget's previous value.
Specifies the jQuery event that caused action execution.
Assign a function to perform a custom action when the editor value changes.
rtlEnabled
Specifies whether or not the current component supports a right-to-left representation.
If you need to switch the display of this DevExtreme component to right-to-left, enable a specifically designed configuration option - rtlEnabled. When this option is set to true, the text flows from right to left, and the layout the component's elements is reversed. To switch the entire application/site to a right-to-left representation, use the static DevExpress.rtlEnabled field.
showClearButton
Specifies whether to display the Clear button in the widget.
The Clear button sets the widget value to null.
useMaskedValue
Specifies whether the value should contain mask characters or not.
If false, the value contains raw user input; if true, the value contains mask characters as well. This option applies only if a mask is specified.
validationError
Holds the object that defines the error that occurred during validation.
You may need to use an editor to inform end users that an error occurred during the validation of a ViewModel field. In this instance, set the editor's isValid option to the isValid property value of the dxValidator that validated the ViewModel's field. In addition, set the editor's validationError option to the validationError property value of the dxValidator object.
In the code, the login specified by an end user is validated on the level of the ViewModel. If validation of the login value fails, a validation message is displayed on the Login editor.
<div data-bind="dxTextBox: { value: login, isValid: login.dxValidator.isValid, validationError: login.dxValidator.validationError, placeholder: 'Login' }"></div>
var viewModel = { login: ko.observable("").extend({ dxValidator: { validationRules: [{ type: 'required', message: 'Login is required' }] } }), //... }
The editor's validationError option, as well as the isValid option, should also be specified when using a custom validation engine. In this instance, the validation result will be displayed for the editor by the means of the DevExtreme Validation UI.
See Also
validationMessageMode
Specifies how the message about the validation rules that are not satisfied by this editor's value is displayed.
The following option values are possible:
- auto
The tooltip with the message is displayed when the editor is in focus. - always
The tooltip with the message is not hidden when the editor loses focus.
valueChangeEvent
Specifies DOM event names that update a widget's value.
The option takes on a string value representing a DOM event name or several DOM event names separated by a space. It is recommended that you use the "keyup", "blur", "change" and "focusout" events. However, you can use other DOM events for your own discretion.
width
Specifies the width of the widget.
The option can hold a value of the following types.
- numeric
The widget width in pixels. - string
A CSS measurement of the widget width (e.g., "55px", "80%", "auto" and "inherit"). function
The function returning the widget width. For example, see the following code.JavaScriptwidth: function () { return baseWidth - 10 + "%"; }