Methods

This section describes methods that you can use to manipulate the TreeList widget in code.

addColumn(columnOptions)

Adds a new column to the widget.

Parameters:
columnOptions: Object|String
The options that configure the column or name of the data field for which a column should be created.
See Also

addRow()

Adds a new data row.

See Also

beginCustomLoading(messageText)

Displays the load panel.

Parameters:
messageText: String
Text to be displayed in the load panel.

Normally, the load panel is invoked automatically while the widget is busy rendering or loading data. Additionally, you can invoke it by calling this method. If you call it without the argument, the load panel displays text specified by the loadPanel | text option. To specify the appearance of the load panel, use the loadPanel object. Once invoked from code, the load panel will not hide until you call the endCustomLoading() method.

NOTE
The load panel invoked from code does not replace the automatically invoked load panel. This circumstance might lead to a situation where the load panel invoked from code suddenly changes its text because it was overridden by the automatically invoked load panel. Therefore, be mindful when invoking the load panel with different text.
See Also

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

byKey(key)

Allows you to obtain a data object by its key.

Parameters:
The key value of the required data object.
Return Value: jQuery.Promise
A Promise of the jQuery.Deferred object resolved after the data object has been loaded.

The following code shows how to get a data object whose key is 15.

JavaScript
widgetInstance.byKey(15).done(function(dataObject) {
        // process "dataObject"
    }).fail(function(error) {
        // handle error
    });
See Also

cancelEditData()

Discards changes that a user made to data.

cellValue(rowIndex, dataField)

Gets the value of a cell found by the row index and data field.

Parameters:
rowIndex: Number
The index of the row to which the cell belongs.
dataField: String
The name of the data field in the data source.
Return Value: any
The value of the cell.
See Also

cellValue(rowIndex, dataField, value)

Assigns a new value to a cell found by the row index and data field.

Parameters:
rowIndex: Number
The index of the row to which the cell belongs.
dataField: String
The name of the data field in the dataSource.
value: any
A new value for the cell.
See Also

cellValue(rowIndex, visibleColumnIndex)

Gets the value of a cell found by the row index and column index.

Parameters:
rowIndex: Number
The index of the row to which the cell belongs.
visibleColumnIndex: Number
The visible index of the column to which the cell belongs.
Return Value: any
The value of the cell.
See Also

cellValue(rowIndex, visibleColumnIndex, value)

Assigns a new value to a cell found by the row index and column index.

Parameters:
rowIndex: Number
The index of the row to which the cell belongs.
visibleColumnIndex: Number
The visible index of the column to which the cell belongs.
value: any
A new value for the cell.
NOTE
In all editing modes different from "cell", save changes by calling the saveEditData() method afterwards.
See Also

clearFilter()

Clears all filters applied to widget rows.

See Also

clearFilter(filterName)

Clears all row filters of a specific type.

Parameters:
filterName: String
The type of the filter to be cleared.

The method's parameter specifies what type of filter should be cleared. The parameter can have one of the following values:

See Also

clearSelection()

Clears selection of all rows on all pages.

clearSorting()

Clears sorting settings of all columns at once.

See Also

closeEditCell()

Switches the cell being edited back to the normal state. Takes effect only if editing | mode is batch.

See Also

collapseAdaptiveDetailRow()

Collapses the currently expanded adaptive detail row (if there is one).

collapseRow(key)

Collapses a specific row.

Parameters:
key: any
The row key.
See Also

columnCount()

Returns the number of data columns in the widget including visible and hidden columns, but without command columns.

Return Value: Number
The number of data columns in the widget.
See Also

columnOption(id)

Gets the options of a column using its identifier.

Parameters:
The name, index, data field, or caption of the column.
Return Value: Object
The options of the column.

This method gets the options of the first column found by either of the below:

  • Name
    The unique name of the column.

  • Column Index
    The index of the column in the columns array.

  • Data Field
    The name of the data source field assigned to the column.

  • Caption
    The text displayed in the column header.

  • Service String
    One of the following values:

    • "command:edit"
      Gets the editing column.

    • "command:adaptive"
      Gets the adaptive column.

    • Any string matching the following format: "optionName:value"
      Here, the optionName is one of the column options.

See Also

columnOption(id, optionName)

Gets the value of a specific option set for a specific column.

Parameters:
The name, index, data field or caption of the column.
optionName: String
The name of the required option.
Return Value: any
The value of this option.

This method gets the value of an option of the first column found by either of the below:

  • Name
    The unique name of the column.

  • Column Index
    The index of the column in the columns array.

  • Data Field
    The name of the data source field assigned to the column.

  • Caption
    The text displayed in the column header.

  • Service String
    One of the following values:

    • "command:edit"
      Gets the editing column.

    • "command:adaptive"
      Gets the adaptive column.

    • Any string matching the following format: "optionName:value"
      Here, the optionName is one of the column options.

See Also

columnOption(id, optionName, optionValue)

Assigns a new value to a single option of a specific column.

Parameters:
The name, index, data field, or caption of the column.
optionName: String
The name of the option to change.
optionValue: any
A new value for this option.

This method sets an option of the first column found by either of the below:

  • Name
    The unique name of the column.

  • Column Index
    The index of the column in the columns array.

  • Data Field
    The name of the data source field assigned to the column.

  • Caption
    The text displayed in the column header.

  • Service String
    One of the following values:

    • "command:edit"
      Gets the editing column.

    • "command:adaptive"
      Gets the adaptive column.

    • Any string matching the following format: "optionName:value"
      Here, optionName is one of the column options.

    NOTE
    In command columns, you can change only the width and the visibleIndex.
See Also

columnOption(id, options)

Assigns new values to several options of a specific column at once.

Parameters:
The name, index, data field, or caption of the column.
options: Object
The options with their new values.

This method changes options of the first column found by either of the below:

  • Name
    The unique name of the column.

  • Column Index
    The index of the column in the columns array.

  • Data Field
    The name of the data source field assigned to the column.

  • Caption
    The text displayed in the column header.

  • Service String
    One of the following values:

    • "command:edit"
      Gets the editing column.

    • "command:adaptive"
      Gets the adaptive column.

    • Any string matching the following format: "optionName:value"
      Here, optionName is one of the column options.

    NOTE
    In command columns, you can change only the width and the visibleIndex.
See Also

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

deleteColumn(id)

Removes a specific column from the widget.

Parameters:
The name, index, data field, or caption of the column.

This method removes the first column found by either of the below:

  • Name
    The unique name of the column.

  • Column Index
    The index of the column in the columns array.

  • Data Field
    The name of the data source field assigned to the column.

  • Caption
    The text displayed in the column header.

See Also

deleteRow(rowIndex)

Removes a specific row from the widget.

Parameters:
rowIndex: Number
The index of the row to be removed.
See Also

deselectAll()

Clears selection of all rows that meet filtering conditions when a filter is applied.

Return Value: jQuery.Promise
A Promise of the jQuery.Deferred object resolved after selection is cleared.
See Also

deselectRows(keys)

Clears selection of specific rows.

Parameters:
keys: Array
The keys of rows whose selection should be cleared.
Return Value: jQuery.Promise
A Promise of the jQuery.Deferred object resolved after selection is cleared.

To access a row by its key, you should specify the field that provides keys in the data source. If no key was specified, the whole data object is considered the key.

See Also

editCell(rowIndex, dataField)

Switches a specific cell into the editing state. The cell is found by the row index and data field. Takes effect only if the editing mode is 'batch' or 'cell'.

Parameters:
rowIndex: Number
The index of the row that owns the cell.
dataField: String
The name of the data field in the data source.
See Also

editCell(rowIndex, visibleColumnIndex)

Switches a specific cell into the editing state. The cell is found by the row index and column index. Takes effect only if the editing mode is 'batch' or 'cell'.

Parameters:
rowIndex: Number
The index of the row that owns the cell.
visibleColumnIndex: Number
The visible index of the column that owns the cell.
See Also

editRow(rowIndex)

Switches a specific row into the editing state. Takes effect only if the editing mode is 'row', 'popup' or 'form'.

Parameters:
rowIndex: Number
The index of the row.
See Also

element()

Gets the root element of the widget.

Return Value: jQuery
The root element of the widget.
See Also

endCustomLoading()

Hides the load panel.

Normally, the widget hides the load panel automatically once data is ready. But if you have invoked the load panel from code using the beginCustomLoading(messageText) method, you must call the endCustomLoading() method to hide it.

See Also

endUpdate()

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

Main article: beginUpdate()

See Also

expandAdaptiveDetailRow(key)

Expands an adaptive detail row found by the key of its parent data row.

Parameters:
key: any
The key of the data row.

To access a data row by its key, you should specify the field that provides keys in the data source. If no key was specified, the whole data object is considered the key.

See Also

expandRow(key)

Expands a specific row.

Parameters:
key: any
The row key.
See Also

filter()

Returns a filter expression applied to the widget's data source using the filter(filterExpr) method.

Return Value: any
See Also

filter(filterExpr)

Applies a filter to the widget's data source.

Parameters:
filterExpr: any

Pass an array with the following members to this method.

  1. The data source field by which data items are filtered.
  2. The comparison operator. The following operators are available: "=", "<>", ">", ">=", "<", "<=", "startswith", "endswith", "contains", "notcontains".
  3. The value with which data source field values should be compared.

This method applies a filter before the filter row, search panel, or header filter does. To clear all filters applied both from code and the UI, call the clearFilter() method.

See Also

focus()

Sets focus on the widget.

See Also

focus(element)

Sets focus on a specific cell.

Parameters:
element: jQuery
The element of the cell.

getCellElement(rowIndex, dataField)

Gets a cell by the row index and data field.

Parameters:
rowIndex: Number
The index of the row that owns the cell.
dataField: String
The name of the data field in the data source.
Return Value: jQuery|undefined
The element of the cell; provides access to element-related jQuery operations.
See Also

getCellElement(rowIndex, visibleColumnIndex)

Gets a cell by the row index and column index.

Parameters:
rowIndex: Number
The index of the row that owns the cell.
visibleColumnIndex: Number
The visible index of the column that owns the cell.
Return Value: jQuery|undefined
The element of the cell; provides access to element-related jQuery operations.
See Also

getCombinedFilter()

Returns the total filter that combines all the filters applied.

Return Value: any

Use this method to get the total filter, which combines filters applied using the filter(filterExpr) method, filter row, header filter and the search panel. Note that the total filter contains getters. To get the total filter with data fields, call the getCombinedFilter(returnDataField) method.

See Also

getCombinedFilter(returnDataField)

Returns the total filter that combines all the filters applied.

Parameters:
returnDataField: Boolean
Specifies whether the total filter should contain data fields instead of getters.
Return Value: any

Use this method to get the total filter, which combines filters applied using the filter(filterExpr) method, filter row, header filter and the search panel.

See Also

getDataSource()

Gets the DataSource instance.

Return Value: DataSource
See Also

getKeyByRowIndex(rowIndex)

Gets the key of a row by its index.

Parameters:
rowIndex: Number
The visible index of the row.
Return Value: any
The key of the row. If nothing is found, returns undefined.

getRootNode()

Gets the root node.

Return Value: TreeList Node
The root node.
See Also

getRowElement(rowIndex)

Gets the element of a row by its index.

Parameters:
rowIndex: Number
The visible index of the row.
Return Value: jQuery|undefined
The element of the row; provides access to element-related jQuery operations.

Note that if the widget has fixed columns, the method returns an array of two separate elements: with unfixed and with fixed columns.

See Also

getRowIndexByKey(key)

Gets the index of a row by its key.

Parameters:
The key of the row.
Return Value: Number
The visible index of the row. If nothing is found, returns -1.

getScrollable()

Gets the instance of the scrollable part of the widget.

Return Value: Scrollable
The instance of the scrollable part of the widget.

For information on API members of the scrollable part, refer to the ScrollView section, but bear in mind that several members described there are unavailable. Those are the following.

Options:

  • pullingDownText
  • pulledDownText
  • refreshingText
  • reachBottomText
  • onPullDown
  • onReachBottom

Methods:

  • release(preventScrollBottom)
  • refresh()
See Also

getSelectedRowKeys()

Gets the keys of the currently selected rows.

Return Value: Array|jQuery.Promise
The keys of the currently selected rows or a Promise of the jQuery.Deferred object.

If a field providing keys is not specified in the data source, the whole data object is considered the key. In this case, this method returns data objects, that is, operates exactly like the getSelectedRowsData() method.

Note that when selection is deferred, the method returns a Promise of the jQuery.Deferred object that should be resolved with an array of keys.

See Also

getSelectedRowsData()

Gets data objects of currently selected rows.

Return Value: Array
Data objects of currently selected rows.
NOTE
Calculated values cannot be obtained because this method gets data objects from the data source.
See Also

getVisibleColumns()

Gets all visible columns.

Return Value: Array
Visible columns; may include command columns.

getVisibleColumns(headerLevel)

Gets all visible columns at a specific hierarchical level of column headers. Use it to access banded columns.

Parameters:
headerLevel: Number
The level of column headers.
Return Value: Array
Visible columns; may include command columns.

getVisibleRows()

Gets all visible rows.

Return Value: Array
Visible rows.

hasEditData()

Checks whether the widget has unsaved changes.

Return Value: Boolean
true if the widget has unsaved changes; otherwise - false.

hideColumnChooser()

Hides the column chooser.

instance()

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

Return Value: Object
This widget's instance.
See Also

isAdaptiveDetailRowExpanded(key)

Checks whether a specific adaptive detail row is expanded or collapsed.

Parameters:
key: any
The key of a data row.

To access a data row by its key, specify the field that provides keys in the data source. If no key was specified, the whole data object is considered the key.

See Also

isRowExpanded(key)

Checks whether a row is expanded or collapsed.

Parameters:
key: any
The row key.
Return Value: Boolean
true if the row is expanded; false if collapsed.
See Also

isRowSelected(key)

Checks whether the row with a specific key is selected.

Parameters:
key: any
The row's key.
Return Value: Boolean
true if the row is selected; false otherwise.

keyOf(obj)

Gets a data object's key.

Parameters:
obj: Object
A data object.
Return Value: any
The data object's key.

If a field providing key values is not specified in the data source, the whole data object is considered the key. In this case, this method returns its argument.

See Also

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

refresh()

Reloads data in the widget.

Return Value: jQuery.Promise
A Promise of the jQuery.Deferred object resolved after data is loaded.

The widget cannot track changes made in the data source by a third party. To bring data in the widget up to date in this case, call this method. Data sources of lookup columns will be updated along with the main data source.

NOTE
Calling the refresh() method ends the editing process. In batch editing mode, changes are saved in a buffer waiting to be saved in the data source. In other modes, all unsaved changes vanish.
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

repaint()

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

See Also

repaintRows(rowIndexes)

Repaints specific rows.

Parameters:
rowIndexes: Array
Row indexes.

This method updates the row objects and their visual representation.

See Also

saveEditData()

Saves changes that a user made to data.

Return Value: jQuery.Promise
A Promise of the jQuery.Deferred object resolved after changes are saved in the data source.

searchByText(text)

Seeks a search string in the columns whose allowSearch option is true.

Parameters:
text: String
A search string. Pass an empty string to clear search results.

selectAll()

Selects all rows.

Return Value: jQuery.Promise
A Promise of the jQuery.Deferred object resolved after all rows are selected.

If a filter is applied, this method selects only those rows that meet the filtering conditions.

See Also

selectRows(keys, preserve)

Selects rows by keys.

Parameters:
keys: Array
The keys of the rows to be selected.
preserve: Boolean
Specifies whether previously selected rows should stay selected.
Return Value: jQuery.Promise
A Promise of the jQuery.Deferred object resolved after the rows are selected.

By default, this method call clears selection of previously selected rows. To keep these rows selected, call this method with true as the second argument.

JavaScript
widgetInstance.selectRows([5, 10, 12], true);

To access a row by its key, specify the field that provides keys. For this, use the key option of the Store that underlies the dataSource. If no key was specified, the whole data object is considered the key. However, we recommend specifying the key option to prevent selection from being duplicated.

See Also

selectRowsByIndexes(indexes)

Selects rows by indexes.

Parameters:
indexes: Array
The indexes of the rows to be selected.
Return Value: jQuery.Promise
A Promise of the jQuery.Deferred object resolved after the rows are selected.

This method has the following specifics:

  • A call of this method clears selection of all previously selected rows.
  • When calculating row indexes, the widget ignores the hierarchy of rows.
See Also

showColumnChooser()

Shows the column chooser.

undeleteRow(rowIndex)

Recovers a row deleted in batch editing mode.

Parameters:
rowIndex: Number
The index of the row to recover.

updateDimensions()

Updates the widget's content after resizing.

See Also