Virtual Mode - Load Data Using Events

• Mar 07, 2025
• 3 minutes to read

The TreeList introduces virtual mode events that allow you to manage tree structure on demand and process user modifications. Dynamic data loading optimizes memory usage and efficiently handles large data sets. Instead of storing all data in memory, the TreeList requests and processes only the necessary portions when needed.

Run Demo: File Explorer

Implementation Details

Create Columns

Create TreeList columns at design time or in code:

C#

myTreeList.Columns.Add(new TreeListColumn() { FieldName = "Value", Visible = true });

Refer to the following help topic for more information: TreeList Columns.

Assign a Data Source

Set the TreeList.DataSource property to assign a data source. Virtual mode does not support the following data types:

Object Type	Behavior
IList	The TreeList switches to bound mode and populates nodes automatically.
IVirtualTreeListData	The TreeList fetches data dynamically from the assigned object.

C#

myTreeList.DataSource = new MyDataObject();

Configure Dynamic Loading

The TreeList creates nodes dynamically as they expand (the default setting). To load the entire hierarchy simultaneously, set the TreeList.EnableDynamicLoading property to false:

C#

// Create the entire hierarchy
myTreeList.EnableDynamicLoading = false;

Handle Virtual Mode Events

Create Child Nodes

Handle the TreeList.VirtualTreeGetChildNodes event to create child nodes dynamically. This event fires when a parent node expands.

The e.Node event parameter identifies the parent node. Assign a list of nested objects to the e.Children event parameter to create child nodes:

C#

void treeList_VirtualTreeGetChildNodes(object sender, VirtualTreeGetChildNodesInfo e) {
    if (e.Node is MyDataObject parentObject) {
        // Create child nodes
        e.Children = parentObject.GetChildNodes();
    }
}

Tip

The VirtualTreeGetChildNodes event also fires when the TreeList creates root nodes. If the e.Node parameter refers to the object assigned to the TreeList.DataSource property, return top-level (root) objects.

Specify Cell Values

Handle the TreeList.VirtualTreeGetCellValue event to specify cell values (e.CellData).

Use the following event parameters to identify the processed cell:

• The e.Node event parameter identifies the underlying data object.
• The e.Column event parameter specifies the processed TreeList column.

C#

void treeList_VirtualTreeGetCellValue(object sender, VirtualTreeGetCellValueInfo e) {
    if (e.Node is MyDataObject dataObject) {
        if (e.Column.FieldName == "Name")
            e.CellData = dataObject.Name;
        else if (e.Column.FieldName == "Value")
            e.CellData = dataObject.Value;
    }
}

Handle User Modifications

Handle the TreeList.VirtualTreeGetCellValue event to process changes made by users.

The e.NewCellData event parameter contains the modified cell value. Set the e.Cancel event parameter to true to discard the change.

The following example updates the data object when the user modifies a value in the ‘Value’ column:

C#

void treeList_VirtualTreeSetCellValue(object sender, VirtualTreeSetCellValueInfo e) {
    if (e.Node is MyDataObject dataObject) {
        if (e.Column.FieldName == "Value") {
            // Update the underlying object
            dataObject.Value = (int)e.NewCellData;
        }
    }
}

Manage Node Check States

Tip

Nodes can display check boxes. Refer to the following help topic for more information: Check Boxes and Radio Buttons.

Supply Check States

If the TreeList.OptionsBehavior.AllowBoundCheckBoxesInVirtualMode option is enabled, the VirtualTreeGetCellValue event allows you to retrieve node check states.

Use the e.IsCheckState event parameter to identify whether the VirtualTreeGetCellValue event queries a check state. Assign the check state to the e.CellData event parameter:

C#

void treeList_VirtualTreeGetCellValue(object sender, VirtualTreeGetCellValueInfo e) {
    if (e.IsCheckState && e.Node is MyDataObject dataObject) {
        e.CellData = dataObject.IsChecked;
    }
}

Handle Check State Changes

When a user modifies a check state, the TreeList fires the VirtualTreeSetCellValue event. Check whether the e.IsCheckState event parameter is set to true. Use the e.NewCellData event parameter to obtain the new check state:

C#

void treeList_VirtualTreeSetCellValue(object sender, VirtualTreeSetCellValueInfo e) {
    if (e.IsCheckState && e.Node is MyDataObject dataObject) {
        // Save the new check state
        dataObject.IsChecked = (bool)e.NewCellData;
    }
}