Methods

This section describes members used to manipulate a widget.

beginUpdate()

Prevents the component from refreshing until the endUpdate method is called.

The beginUpdate and endUpdate methods allow you to apply several modifications to the component. After the beginUpdate method is called, the component does not update the UI until the endUpdate method is called. The usage of these methods prevents excessive component updating when you are changing multiple component settings at once.

defaultOptions(rule)

Specifies the device-dependent default configuration options for this component.

Parameters:
rule: Object
An object specifying default options for the component and the device for which the options must be applied.
Object structure:
device: Object|Array|function
An object representing device parameters, or an array of objects representing device parameters, or a function that provides information on the current device as an input parameter and returning a Boolean value.
options: Object
A configuration object with specified options.

The defaultOptions method is a static method supported by the widget class. The following code demonstrates how to specify default options for all buttons in the application executed on the iOS platform.

JavaScript
DevExpress.ui.dxButton.defaultOptions({ 
    device: { platform: "ios" },
    options: {
        text: "Click me"
    }
});

element()

Returns the root HTML element of the widget.

Return Value: jQuery
The root element of the widget.

endUpdate()

Enables the component to refresh after the beginUpdate method call.

The beginUpdate and endUpdate methods allow you to apply several modifications to the component. After the beginUpdate method is called, the component does not update the UI until the endUpdate method is called. The usage of these methods prevents excessive component updating when you change multiple component setting at once.

focus()

Sets focus on the widget.

getEditor(field)

Returns an editor instance associated with the specified formData field or name of a form item.

Parameters:
field: String
The path to the required formData field or name of the form item.
Return Value: Object
An instance of the required editor.

NOTE: The method returns an editor instance only if a form item is visible.

instance()

Returns an instance of this component class.

Return Value: Object
An instance of this component class

Use this method to access other methods of the component.

itemOption(field, option, value)

Updates the value of a form item option.

Parameters:
field: String
Specifies the path to the required formData field, or the name of the required editor.
option: String
The name of the option to be updated.
value: any
The new option value.

If the required item is contained in a group or tabbed item, add the group or tab title followed by a dot before the required item name and pass this value to the field argument.

JavaScript
$("#myForm").dxForm("instance").itemOption("MyGroup.MyItem", "visible", false);

itemOption(field, options)

Updates the values of form item options.

Parameters:
field: String
Specifies the path to the required formData field, or the name of the required item.
options: Object
A configuration object containing options to be updated and their values.

Use this method to update several options of a form item.

If the required item is contained in a group or tabbed item, add the group or tab title followed by a dot before the required item name and pass this value to the field argument.

JavaScript
$("#myForm").dxForm("instance").itemOption("MyGroup.MyItem", {. . .});

off(eventName)

Detaches all event handlers from the specified event.

Parameters:
eventName: String
The name of the event to unsubscribe from.
Return Value: Object
The object for which this method is called.

off(eventName, eventHandler)

Detaches a particular event handler from the specified event.

Parameters:
eventName: String
The name of the event to unsubscribe from.
eventHandler: function
The handler to be detached from the specified event.
Return Value: Object
The object for which this method is called.

on(eventName, eventHandler)

Subscribes to a specified event.

Parameters:
eventName: String
The name of the event to be subscribed.
eventHandler: function
An event handler for the specified event.
Return Value: Object
The object for which this method is called.

on(events)

Subscribes to the specified events.

Parameters:
events: Object
An object of the following structure: { "eventName1": handler1, "eventName2": handler2, ...}
Return Value: Object
The object for which this method is called.

option()

Returns the configuration options of this component.

Return Value: Object
An object representing the configuration options of this component.

option(optionName)

Gets the value of the specified configuration option of this component.

Parameters:
optionName: String
The name of the option to get.
Return Value: any
The value of the specified option.

If you need to get the value of a configuration option field, specify the path to the required field.

option(optionName, optionValue)

Sets a value to the specified configuration option of this component.

Parameters:
optionName: String
The name of the required option.
optionValue: any
The value you wish to assign to the required option.

To set a value to the configuration option field, specify the path to the required field.

option(options)

Sets one or more options of this component.

Parameters:
options: Object
An object containing the required configuration options.

registerKeyHandler(key, handler)

Registers a handler when a specified key is pressed.

Parameters:
key: String
Specifies the key for which to register a handler.
handler: function
A handler function.

The handler function is called when the specified key is pressed if the widget is focused.

The key argument accepts the following values.

  • "backspace"
  • "tab"
  • "enter"
  • "escape"
  • "pageUp"
  • "pageDown"
  • "end"
  • "home"
  • "leftArrow"
  • "upArrow"
  • "rightArrow"
  • "downArrow"
  • "del"
  • "space"
  • "F"
  • "A"
  • "asterisk"
  • "minus"

NOTE: If you specify a custom handler for a key, the default handler for this key is canceled.

repaint()

Redraws the widget.

After performing some external modifications that lead to a change of the widget container's size or visibility, the widget's state may become invalid. In this instance, use the repaint() method to redraw the widget.

resetValues()

Resets the editor's value to undefined.

updateData(data)

Updates the specified fields of the formData object and the corresponding editors on the form.

Parameters:
data: Object
An object containing the fields to be updated and their new values.

updateData(dataField, value)

Updates the specified field of the formData object and the corresponding editor on the form.

Parameters:
dataField: String
Specifies the path to the required formData field.
value: Object
The new field value.

updateDimensions()

Updates the dimensions of the widget contents.

Return Value: jQuery.Promise
A promise of the jQuery Deferred object resolved when the update is complete.

Use this method to fit the widget contents to the widget size after it (size) has been changed.

validate()

Validates the values of all editors on the form against the list of the validation rules specified for each form item.

Return Value: Object
An object defining the result of validation.