List Methods

This section describes members used to manipulate the 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.

clientHeight()

Returns the height of the widget in pixels.

Return Value: Number
The value of the widget height in pixels.

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

deleteItem(itemElement)

Removes the specified item from the list.

Parameters:
itemElement: DOM Node
The item element of the list item to delete.
Return Value: Object
A Promise of the jQuery Deferred object resolved if the item is deleted and rejected if it is not.

This method deletes the specified item if the editEnabled option is set to true.

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: Object
A Promise of the jQuery Deferred object resolved if the item is deleted and rejected if it is not.

This method deletes the specified item if the editEnabled option is set to true.

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.

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.

isItemSelected(itemElement)

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

Parameters:
itemElement: DOM Node
The item element of the requested list item.
Return Value: Boolean
A Boolean value specifying whether or not the requested item is selected.

To determine which items are currently selected, use the widget's option method, passing the selectedItems as a parameter.

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.

To determine which items are currently selected, use the widget's option method, passing the selectedItems as a parameter.

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.

refresh()

Deprecated

Use the reload() method instead.

Reloads list data.

reload()

Reloads list data.

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

reorderItem(itemElement, toItemElement)

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

Parameters:
itemElement: DOM Node
A node element of the item to be moved.
toItemElement: DOM Node
A node element of the item after which the specified item is placed.
Return Value: Object
A Promise of the jQuery Deferred object resolved if the item is moved and rejected if it is not.

This method reorders items in the widget inner array accessed via the items option, but it does not affect the data source associated with the widget.

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: Object
A Promise of the jQuery Deferred object resolved if the item is moved and rejected if it is not.

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.

This method reorders items in the widget's inner array accessed by using the items option, but it does not affect the data source associated with the widget.

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.

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).

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.

selectItem(index)

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 }.

This method selects the specified item if the editEnabled option is set to true.

selectItem(itemElement)

Selects the specified item from the list.

Parameters:
itemElement: DOM Node
The item element node of the list item to select.

This method selects the specified item if the editEnabled option is set to true.

unselectItem(itemElement)

Deselects the specified item from the list.

Parameters:
itemElement: DOM Node
The item element node of the list item to deselect.

This method deselects the specified item if the editEnabled option is set to true.

unselectItem(itemIndex)

Deselects the specified item from the list.

Parameters:
itemIndex: Number|Object
The index number of the list item to deselect. If the list is grouped, pass an object with the required group and item indexes, e.g., { group: 0, index: 0 }.

This method deselects the specified item if the editEnabled option is set to true.

update()

Deprecated

Use the updateDimensions() method instead.

Updates the widget scrollbar according to widget content size.

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

updateDimensions()

Updates the widget scrollbar according to widget content size.

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

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