Methods

This section describes members used to manipulate the widget.

baseZIndex(zIndex)

A static method that specifies the base z-index for all overlay widgets.

Parameters:
zIndex: Number

The z-index value.

The z-index of all overlay widgets located on a page is calculated based on the value passed to this method. Since an overlay widget is added, its z-index is increased by one relative to a previously added overlay widget.

The following example demonstrates how to call the method.

JavaScript
$(function(){
    DevExpress.ui.dxOverlay.baseZIndex(2000);
});
NOTE
Base z-index for dxToast widgets is greater than the value specified by this method by 8000. dxTooltips' z-index is less than the specified value by 500. For example, if you pass 2000 to the baseZIndex method, the dxToast base z-index is 10000, the dxTooltip base z-index is 1500.

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.

content()

An HTML element of the widget.

Return Value: jQuery

An element representing the widget.

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:

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.

hide()

Hides the widget.

Return Value: jQuery.Promise

A Promise of the jQuery.Deferred object resolved after the widget is hidden.

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.

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.

repaint()

Recalculates the overlay's size and position.

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

show()

Shows the widget.

Return Value: jQuery.Promise

A Promise of the jQuery.Deferred object resolved after the widget is shown.

show(target)

Displays the widget for the specified target element.

Parameters:

Specifies the target element the widget points to.

Return Value: jQuery.Promise

A Promise of the jQuery Deferred object resolved if the widget is displayed and rejected if it is not.

toggle(showing)

Toggles the visibility of the widget.

Parameters:
showing: Boolean

A Boolean value specifying whether to show or hide the widget.

Return Value: jQuery.Promise

A Deferred jQuery object.

You can use the toggle(showing) method instead of show() and hide() methods. The only difference is that you specify whether to show or hide the widget passing true or false to the method parameter.