VirtualFilterTree

ic.VirtualFilterTree combines the virtualized rendering of ic.VirtualTree with the tag-based search bar from ic.FilterTree. It is designed for large trees where you need both on-demand loading and client-initiated filtering. The tree stays in MATLAB, nodes are fetched as folders are expanded or scrolled into view, and when the user types a filter, MATLAB walks the full tree server-side to find matches and sends back only the results.

For filter operators and tag syntax, see the FilterTree documentation. For general tree construction and the ic.tree.Node API, see the Tree documentation.

How it works

VirtualFilterTree renders a search bar above a virtualized tree. Without an active filter, it behaves exactly like ic.VirtualTree: root nodes are loaded on mount, children are fetched when folders expand, and scrolling pre-fetches upcoming rows. When the user types a filter (debounced at 200ms), the component sends the filter groups to MATLAB, which walks the full Items tree, finds all matching nodes, and caches the filtered result. The frontend then re-renders the tree from that cached subset, auto-expanding ancestor folders of matching nodes if AutoExpand is on.

This means filtering works on the entire tree regardless of which folders the user has expanded, since MATLAB has the complete hierarchy.

Basic usage

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

vft = ic.VirtualFilterTree();
vft.Items = root;
vft.Height = 400;

Filtering

The search bar supports the same 8 tag-based operators as FilterTree (contains, OR, NOT, folder, leaf, exact, path, starts-with). CaseSensitive controls whether filtering respects letter case. AutoExpand opens ancestor folders of matching nodes so results are immediately visible. Clearable shows a button to clear all filter tags.

vft = ic.VirtualFilterTree();
vft.Items = root;

vft.CaseSensitive = false;   % default
vft.AutoExpand = true;       % auto-open ancestor folders
vft.Clearable = true;        % show clear button
vft.SearchPlaceholder = "Filter nodes...";

addlistener(vft, "SearchChanged", @(~, evt) ...
    disp(evt.Data.value));

Selection and events

Selection works identically to the other tree components. Selectable enables checkboxes, MaxSelectedItems caps the count, and ValueChanged / SelectionChanged fire when the user toggles nodes.

vft = ic.VirtualFilterTree();
vft.Items = root;
vft.Selectable = true;
vft.MaxSelectedItems = 5;

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

addlistener(vft, "SelectionChanged", @(~, evt) ...
    disp(evt.Data.Selection));

Context menus

Separate context menus for leaf and folder nodes, same as the other tree components.

vft = ic.VirtualFilterTree();
vft.Items = root;

vft.LeafContextMenu = [
    ic.menu.Item("open", Label="Open")
    ic.menu.Item("delete", Label="Delete")
];

vft.FolderContextMenu = [
    ic.menu.Item("new_file", Label="New File")
    ic.menu.Item("rename", Label="Rename")
];

Methods

VirtualFilterTree exposes clearSearch() in addition to the standard tree methods.

% Expand/collapse
vft.expandAll();
vft.collapseAll();
vft.expandNode(someFolder);

% Clear filter and selection
vft.clearSearch();
vft.clearSelection();

% Focus the search bar
vft.focus();