VirtualTree

ic.VirtualTree is the virtualized counterpart of ic.Tree, designed for trees with thousands or tens of thousands of nodes. It shares the same selection model, expand/collapse controls, and context menu support, but only renders the rows currently visible in the viewport. The full tree stays in MATLAB and nodes are fetched on demand as the user expands folders and scrolls, so the frontend never holds the entire hierarchy in memory.

For tree construction, node management, and general tree features, see the Tree documentation. The same ic.tree.Node API applies here.

How it works

Unlike ic.Tree (which sends the entire hierarchy to the frontend at once), VirtualTree keeps the full tree in MATLAB and only sends what is currently visible. When the component loads, it fetches the root nodes. When the user expands a folder, it fetches that folder’s children. As the user scrolls, additional batches are pre-fetched so the experience stays smooth.

Row heights are fixed per size level (sm: 24px, md: 28px, lg: 32px), which lets the component calculate scroll positions without measuring the DOM. Only the rows in the viewport (plus a small buffer) are rendered at any time.

Basic usage

% Build a large tree in MATLAB
root = ic.tree.Node("Project");
for i = 1:500
    folder = root.add(sprintf("Module %d", i));
    for j = 1:50
        folder.add(sprintf("File %d.m", j), Icon="file-code");
    end
end

vt = ic.VirtualTree();
vt.Items = root;
vt.Height = 400;

The tree above has 500 folders with 50 files each (25,000 nodes total), but the frontend only ever holds the visible slice. Height is important because VirtualTree uses it to calculate how many rows fit in the viewport.

Selection and events

Selection works identically to ic.Tree: Selectable enables checkboxes, MaxSelectedItems caps the count, and ValueChanged / SelectionChanged fire when the user toggles nodes.

vt = ic.VirtualTree();
vt.Items = root;
vt.Selectable = true;
vt.MaxSelectedItems = 10;

addlistener(vt, "ValueChanged", @(~, evt) ...
    disp(evt.Data.value));

% SelectionChanged gives resolved ic.tree.Node handles
addlistener(vt, "SelectionChanged", @(~, evt) ...
    disp(evt.Data.Selection));

Appearance

Size, ShowLine, and Height behave the same as in Tree. Placeholder controls the text shown while the initial root nodes are being loaded.

vt = ic.VirtualTree();
vt.Items = root;

vt.Size = "sm";         % "sm", "md" (default), "lg"
vt.ShowLine = true;     % tree connector lines
vt.Height = 500;        % pixels or CSS string
vt.Placeholder = "Loading nodes...";

Context menus

VirtualTree supports separate context menus for leaf and folder nodes, just like Tree.

vt = ic.VirtualTree();
vt.Items = root;

% Different menus for leaves vs folders
vt.LeafContextMenu = [
    ic.menu.Item("open", Label="Open")
    ic.menu.Item("delete", Label="Delete")
];

vt.FolderContextMenu = [
    ic.menu.Item("expand_all", Label="Expand All")
    ic.menu.Item("collapse", Label="Collapse")
    ic.menu.Separator()
    ic.menu.Item("new_file", Label="New File")
];

Methods

VirtualTree exposes the same programmatic controls as Tree for expand/collapse, selection, and focus.

% Programmatic expand/collapse
vt.expandAll();
vt.collapseAll();
vt.expandNode(someFolder);
vt.collapseNode(someFolder);

% Clear selection
vt.clearSelection();

% Focus the tree container
vt.focus();