TreeTableControl

A table whose rows nest: rows hold rows of their own, shown indented under them in the tree column and expanded or collapsed in place.

TreeTableControl

Overview#

TreeTableControl is a TableControl whose rows form a hierarchy: features with their stories and tasks, folders with their files, accounts with their sub-accounts. Each row is a TreeTableRow, which has cells like any TableRow plus a parent, children and an expansion state. The tree column draws, in front of each value, the guide lines to the row's parent and an expander, [-] or [+], in the same guide styles as TreeControl.

Because it is a TableControl, everything a table does it does too: columns and their widths, selection, multi-select, checkboxes, cell navigation, inline editing, scrollbars, colors, the builder settings. Sorting and filtering follow the hierarchy: a sort orders each row's children among themselves, and a filter shows each match together with the rows above it.

┌──────────────────────┬─────┐
│Title                 │Owner│
├──────────────────────┼─────┤
│[-] Feature: Login    │Pat  │
│├─ [-] Story: Form    │Bo   │
││  ├─     Task: Layout│Bo   │
││  └─     Task: Checks│Cy   │
│└─     Story: Reset   │Pat  │
│[+] Feature: Reports  │Di   │
└──────────────────────┴─────┘

See also: TableControl, TreeControl

Quick Start#

var builder = Controls.TreeTable()
    .AddColumn("Title")
    .AddColumn("Owner")
    .Interactive()
    .WithSorting()
    .WithFiltering();

var login = builder.AddRootRow("Feature: Login", "Pat");
var form = login.AddChild("Story: Form", "Bo");
form.AddChild("Task: Layout", "Bo");
form.AddChild("Task: Checks", "Cy");
login.AddChild("Story: Reset", "Pat");

var table = builder.Build();
window.AddControl(table);

AddRootRow with cell text returns the new row, and AddChild returns the new child, so a hierarchy is built by capturing the rows to nest under.

Rows and the Hierarchy#

A TreeTableRow belongs to one parent and one table at a time. Rows can be built up detached, a whole subtree at a time, and added to a table in one step; once in a table, changes made through the row are applied to the table at once.

// Build a subtree detached, then add it
var reports = new TreeTableRow("Feature: Reports", "Di");
reports.AddChild("Story: Export", "Di");
table.AddRootRow(reports);           // or InsertRootRow(index, reports)

// Change it in place
var export = reports.Children[0];
export.AddChild("Task: CSV", "Eve");
reports.InsertChild(0, new TreeTableRow("Story: Charts", "Cy"));
reports.RemoveChild(export);          // removes its subtree too

// Move a row, keeping it the same row: its selection, expansion and tag go with it
table.MoveRow(form, newParent: reports, index: 0);
table.MoveRow(form, newParent: null, index: 0);  // make it a root

Adding a row that already has a parent or is already in a table throws InvalidOperationException, and so does nesting a row under itself or one of its descendants.

Batching#

Every change recomputes the displayed rows once, which is right for one change and wasteful for a thousand. BatchUpdate makes any number of changes one recompute:

table.BatchUpdate(() =>
{
    foreach (var item in workItems)
        AddWithChildren(table, item);
});

Batches nest; only the outermost one ends the batch. Until it ends, Rows, RowCount and the display show the table as it was before. Building a subtree detached and adding it in one step is cheaper still.

The Inherited Table API#

Code written against a TableControl works on a tree table. Its inherited members keep their meaning, read in terms of the hierarchy:

A tree table without nested rows draws, sorts, filters and selects exactly as a TableControl.

Expanding and Collapsing#

table.Expand(row);            // true when it changed
table.Collapse(row);
table.Toggle(row);
table.ExpandSubtree(row);     // the row and every row under it
table.ExpandAll();
table.CollapseAll();
row.IsExpanded = false;       // the same, through the row

table.EnsureRowVisible(row);  // opens the rows above it and scrolls to it
table.SelectRow(row);         // the same, and selects it

Rows start expanded, as TreeNodes do. TreeTableRow.IsExpanded is the row's own, lasting state. IsRowExpanded(row) says whether the row is open in what is displayed, which differs only while filtered.

A cursor whose row a collapse hides moves to the nearest row above it still displayed.

Sorting#

Sorting a hierarchy as a flat list would tear rows away from their parents. SortByColumn instead orders each row's children among themselves, and the roots among themselves, so every row stays under its parent. Siblings are compared by the table's own rules, so a column's CustomComparer and the table's CustomRowComparer mean what they mean to a table; rows that compare equal keep the order they were added in, in either direction. ClearSort restores that order, and a row added while sorted takes its sorted place among its siblings.

Filtering#

Filtering a hierarchy as a flat list would show matches out of context, and miss the rows inside collapsed parents. A tree table searches every row, collapsed or not, with the table's own filter syntax, and shows each match together with every row above it:

table.ApplyFilter("checks");

┌──────────────────────┬─────┐
│Title                 │Owner│
├──────────────────────┼─────┤
│[-] Feature: Login    │Pat  │
│└─ [-] Story: Form    │Bo   │
│   └─     Task: Checks│Cy   │
└──────────────────────┴─────┘

• The rows above a match are open in the filtered view, whatever their own state.
• A match's children that do not match stay hidden. Set FilterIncludesDescendants to show every row under a match, matching or not: finding a feature then shows all its stories.
• A row whose children are all filtered out shows no expander.
• Sorting a filtered table orders the siblings shown.

Opening and closing rows while filtered changes only the filtered view: TreeTableRow.IsExpanded keeps the row's own state, and clearing or changing the filter brings the hierarchy back as it was.

Loading Children on Demand#

A row with HasUnrealizedChildren shows an expander before it has children. Add them from RowExpansionChanging when the row is first expanded; children added there are displayed together with the expansion, in the same recompute:

var table = Controls.TreeTable()
    .AddColumn("Folder")
    .OnRowExpansionChanging((sender, e) =>
    {
        if (!e.IsExpanded || !e.Row.HasUnrealizedChildren || e.Row.Tag is not string path)
            return;

        foreach (var dir in Directory.GetDirectories(path))
        {
            e.Row.AddChild(new TreeTableRow(MarkupParser.Escape(Path.GetFileName(dir)))
            {
                Tag = dir,
                IsExpanded = false,
                HasUnrealizedChildren = true,
            });
        }
        e.Row.HasUnrealizedChildren = false;
    })
    .Build();

table.AddRootRow(new TreeTableRow("Projects")
{
    Tag = projectsPath,
    IsExpanded = false,
    HasUnrealizedChildren = true,
});

Selection#

The selection stays on its rows across every change: a sort, a filter cleared, rows added, moved or removed elsewhere.

When the selected row is removed, the cursor goes to its next sibling still displayed, else the previous one, else the nearest row above it, rather than to whatever row followed the removed subtree. Siblings are taken in the order they were displayed, so in a sorted view the cursor goes to the row shown below.

Keyboard Support#

Every other key is the table's, see TableControl. The table keeps the keys it already gives a meaning to: with CellNavigationEnabled, Left and Right move between cells; with MultiSelectEnabled, Space selects rows. Keys held with Ctrl or Alt are left to the application.

Mouse Support#

Two quick clicks on an expander toggle the row twice rather than activating it. Everything else is the table's, see TableControl.

Properties#

Every TableControl property applies as well.

TreeTableRow#

Methods#

Events#

The arguments name the Row, whether it IsExpanded after the change, and whether the change IsFilteredView: made while filtered, to the filtered view only. Every way of opening and closing a row raises them: the methods, setting IsExpanded, the keys and the expander. A bulk change raises them for each row and leaves a cancelled row out; in a BatchUpdate, RowExpansionChanged waits for the batch to end. RowExpansionChanged follows the selection events the change caused.

Selection and activation come from the table: SelectedRowChanged, SelectedRowItemChanged, RowActivated and the rest.

Builder API#

Create a builder with Controls.TreeTable() or TreeTableControl.Create(). Every TableControl builder method is available in the same chain; the rows it adds are roots.

.AddRootRow(TreeTableRow row)              // Add a row with its subtree (returns builder)
.AddRootRow("cell", "cell")                // Create + add a row (returns the TreeTableRow)
.WithGuide(TreeGuide.Line)                 // Guide line style
.WithIndent("  ")                          // Text after each ancestor level's guide
.WithTreeColumn(1)                         // Column the hierarchy is drawn in
.WithFilterIncludingDescendants()          // Show every row under a filter match
.OnRowExpansionChanging((sender, e) => { ... })
.OnRowExpansionChanged((sender, e) => { ... })

Binding to Items#

BindItems (namespace SharpConsoleUI.DataBinding) shows a hierarchy of view models, one row per item, and keeps the rows in step as the items and their ObservableCollections change: added, removed, moved and replaced items, item property changes, and expansion in both directions. See Data Binding.

table.BindItems(backlog.Roots,
    childrenOf: item => item.Children,
    cellsOf: item => [item.Title, item.Owner]);

Extending TreeTableControl#

TreeTableControl is built on the extension points of TableControl and adds its own. Each is protected and runs on the UI thread.

TreeTableRowContext describes a row as displayed: Row, DataRowIndex, Depth, HasChildren, IsExpanded, IsLastSibling, ShowsExpanderGutter, Guide, Indent, and IsLastSiblingAtDepth(depth) for drawing an ancestor's continuation line.

// Folders before files, then by name
class FileTable : TreeTableControl
{
    protected override int CompareSiblings(TableRow x, TableRow y, int column, SortDirection direction)
    {
        bool xFolder = x is TreeTableRow { HasUnrealizedChildren: true } or TreeTableRow { Children.Count: > 0 };
        bool yFolder = y is TreeTableRow { HasUnrealizedChildren: true } or TreeTableRow { Children.Count: > 0 };
        if (xFolder != yFolder)
            return xFolder ? -1 : 1;
        return base.CompareSiblings(x, y, column, direction);
    }

    // A two-cell expander instead of [-] and [+]; a click on it still toggles the row
    protected override string GetExpanderMarkup(in TreeTableRowContext context)
    {
        if (context.HasChildren)
            return context.IsExpanded ? "v " : "> ";
        return context.ShowsExpanderGutter ? "  " : string.Empty;
    }
}

Threading#

Change the hierarchy on the UI thread, as with any control; from a background thread, marshal through windowSystem.EnqueueOnUIThread. The display is computed from a snapshot of the hierarchy taken when it was last handed to the table, so painting never shows a batch half done, and the events are raised outside the table's lock, so a handler can change the table.

See Also#

• TableControl - The table it extends: columns, selection, editing, filtering
• TreeControl - For a hierarchy shown in a single column
• Controls Reference - All controls overview

Back to Controls | Back to Main Documentation