Methods

This section describes members used to manipulate the widget.

beginUpdate()

Prevents the widget from refreshing until the endUpdate() method is called.

The beginUpdate() and endUpdate() methods prevent the widget from excessive updates when you are changing multiple widget settings at once. After the beginUpdate() method is called, the widget does not update its UI until the endUpdate() method is called.

See Also

clientHeight()

Returns the height of the widget in pixels.

Return Value:

Number

The value of the widget height in pixels.

See Also

collapseGroup(groupIndex)

Collapses the specified group.

Parameters:
groupIndex:

Number

The index of the group to be collapsed.

Return Value:

Promise (jQuery or native)

A Promise that is resolved if the group is collapsed and rejected otherwise. It is a native Promise or a jQuery.Promise when you use jQuery.

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<Object>

|

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"
    }
});

deleteItem(itemElement)

Removes the specified item from the list.

Parameters:
itemElement:

DOM Node

The item element node.

Return Value:

Promise (jQuery or native)

A Promise that is resolved if the item is deleted and rejected otherwise. It is a native Promise or a jQuery.Promise when you use jQuery.

deleteItem(itemIndex)

Removes the specified item from the list.

Parameters:
itemIndex:

Number

|

Object

The index of the list item to delete. If the list is grouped, pass an object with the required group and item indexes, e.g., { group: 0, item: 0 }.

Return Value:

Promise (jQuery or native)

A Promise that is resolved if the item is deleted and rejected otherwise. It is a native Promise or a jQuery.Promise when you use jQuery.

dispose()

Removes the widget from the DOM.

element()

Gets the root element of the widget.

Return Value:

Element (jQuery or HTML)

The widget's root element. An HTML element or a jQuery element when you use jQuery.

See Also

endUpdate()

Refreshes the widget after a call of the beginUpdate() method.

Main article: beginUpdate()

See Also

expandGroup(groupIndex)

Expands the specified group.

Parameters:
groupIndex:

Number

The index of the group to be expanded.

Return Value:

Promise (jQuery or native)

A Promise that is resolved if the group is expanded and rejected otherwise. It is a native Promise or a jQuery.Promise when you use jQuery.

focus()

Sets focus on the widget.

See Also

getDataSource()

Gets the DataSource instance.

Return Value:

DataSource

See Also

getInstance(element)

Gets the widget's instance using a DOM element.

Parameters:
element:

DOM Node

|

jQuery

An element containing the widget.

Return Value:

Object

The widget's instance.

instance()

Returns this widget's instance. Use it to access other methods of the widget.

Return Value:

Object

This widget's instance.

See Also

isItemSelected(itemElement)

Returns a Boolean value that indicates whether or not the specified item is selected.

Parameters:
itemElement:

DOM Node

The item element node.

Return Value:

Boolean

A Boolean value specifying whether or not the requested item is selected.

isItemSelected(itemIndex)

Returns a Boolean value that indicates whether or not the specified item is selected.

Parameters:
itemIndex:

Number

|

Object

The index number of the requested list item. If the list is grouped, pass an object with the required group and item indexes, e.g., { group: 0, item: 0 }.

Return Value:

Boolean

A Boolean value specifying whether or not the requested item is selected.

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.

See Also

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.

See Also

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.

Use this method to subscribe to one of the events listed in the Events section.

See Also

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.

Use this method to subscribe to several events with one method call. Available events are listed in the Events section.

See Also

option()

Gets the widget's options.

Return Value:

Object

The widget's options.

See Also

option(optionName)

Gets a specific option value.

Parameters:
optionName:

String

The option name or the full path to the option.

Return Value: any

This option value.

See Also

option(optionName, optionValue)

Assigns a new value to a specific option.

Parameters:
optionName:

String

The option name or the full path to the option.

optionValue: any

A new value for this option.

See Also

option(options)

Sets one or more options.

Parameters:
options:

Object

The options along with their new values.

See Also

registerKeyHandler(key, handler)

Registers a handler to be executed when a user presses a specific key.

Parameters:
key:

String

The key for which the handler should be registered.

handler:

function

A handler.

The key argument accepts one of the following values:

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

A custom handler for a key cancels the default handler for this key.

See Also
Show Example:
jQuery

reload()

Reloads list data.

You can also reload list data using the "pull down" gesture if the pullRefreshEnabled option is set to true.

See Also

reorderItem(itemElement, toItemElement)

Moves the specified item to the specified position in the list.

Parameters:
itemElement:

DOM Node

The DOM node of the item to be moved.

toItemElement:

DOM Node

The DOM node of the item after which the specified item should be placed.

Return Value:

Promise (jQuery or native)

A Promise that is resolved if the item is moved and rejected otherwise. It is a native Promise or a jQuery.Promise when you use jQuery.

NOTE
This method reorders items in the items array, but it does not affect the dataSource.
See Also

reorderItem(itemIndex, toItemIndex)

Moves the specified item to the specified position in the list.

Parameters:
itemIndex:

Number

|

Object

The index number of the item to be moved.

toItemIndex:

Number

|

Object

The index of the item after which the specified item is placed.

Return Value:

Promise (jQuery or native)

A Promise that is resolved if the item is moved and rejected otherwise. It is a native Promise or a jQuery.Promise when you use jQuery.

If the widget displays a grouped list, the item index should be specified like the following.

JavaScript
{
    group: 1,
    index: 1
}

Where the group property specifies the group index, and the index property specifies the index of the required item within the group.

JavaScript
$("#myList").dxList("instance").reorderItem({
    group: 1,
    index: 4
},
{
    group: 3,
    index: 2
});

This code will move the 4th item of the 1st group to the 3rd position in the 3rd group.

NOTE
This method reorders items in the items array, but it does not affect the dataSource.
See Also

repaint()

Repaints the widget. Call it if you made modifications that changed the widget's state to invalid.

See Also

scrollBy(distance)

Scrolls the list content by the specified number of pixels.

Parameters:
distance:

Number

A distance to be scrolled in pixels.

scrollHeight()

Returns the height of the list content in pixels.

Return Value:

Number

The value of the content height in pixels.

scrollTo(location)

Scrolls list content to the specified position.

Parameters:
location:

Number

The position to scroll to (in pixels).

scrollToItem(itemElement)

Scrolls the list to the specified item.

Parameters:
itemElement:

DOM Node

The target element node.

scrollToItem(itemIndex)

Scrolls the list to the specified item.

Parameters:
itemIndex:

Number

|

Object

The target element index.

If the widget displays a grouped list, specify the target item index using an object containing the following fields.

  • group
    Specifies the index of the group containing the target item.

  • item
    Specifies the item index within the specified group.

JavaScript
var list = $("#myList").dxList("instance");
list.scrollToItem({
    group: 3,
    item: 8
});
See Also

scrollTop()

Returns how far the list content is scrolled from the top.

Return Value:

Number

The value of the current scroll position from the top in pixels.

selectAll()

Selects all items.

Depending on the value of the selectAllMode option, this method selects all items on all pages or on the currently rendered pages only. If a filter is applied, this method selects only those items that meet the filtering conditions.

See Also

selectItem(itemElement)

Selects the specified item.

Parameters:
itemElement:

DOM Node

The DOM node of the item to be selected.

selectItem(itemIndex)

Selects the specified item from the list.

Parameters:
itemIndex:

Number

|

Object

The index number of the list item to select. If the list is grouped, pass an object with the required group and item indexes, e.g., { group: 0, item: 0 }.

Note that the result of the method execution depends on the current value of the selectionMode option that accepts the following values.

  • none
    The method does nothing.

  • single
    The method selects the specified item while the previously selected item becomes unselected.

  • multi and all The method adds the specified item to the list of currently selected items.

See Also

unselectAll()

Clears selection of all items.

Depending on the value of the selectAllMode option, this method clears selection of all items on all pages or on the currently rendered pages only. If a filter is applied, this method clears selection only of those items that meet the filtering conditions.

See Also

unselectItem(itemElement)

Clears selection of the specified item.

Parameters:
itemElement:

DOM Node

The DOM node of the item whose selection should be cleared.

unselectItem(itemIndex)

Clears selection of the specified item from the list.

Parameters:
itemIndex:

Number

|

Object

The index of the list item whose selection should be cleared. If the list is grouped, pass an object with the required group and item indexes, e.g., { group: 0, index: 0 }.

updateDimensions()

Updates the widget scrollbar according to widget content size.

Return Value:

Promise (jQuery or native)

A Promise that is resolved after the update process is completed. It is a native Promise or a jQuery.Promise when you use jQuery.

Use this method to update the position of list items after the widget element was resized.

See Also