TableControl

Interactive data grid with virtual data support, sorting, inline editing, and multi-selection.

TableControl

Overview#

TableControl renders tabular data with full keyboard and mouse interaction. It supports two data modes: in-memory rows for simple tables, and ITableDataSource for virtual/lazy data binding that handles millions of rows by querying only visible rows on demand.

By default, ReadOnly = true preserves backward-compatible static table rendering. Set .Interactive() to enable selection, navigation, editing, and all interactive features.

Properties#

Events#

Creating Tables#

Static Table (ReadOnly)#

var table = Controls.Table()
    .AddColumn("Name")
    .AddColumn("Value", TextJustification.Right)
    .AddRow("CPU", "42%")
    .AddRow("Memory", "8.2 GB")
    .AddRow("Disk", "256 GB")
    .WithHeaderColors(Color.White, Color.DarkBlue)
    .Rounded()
    .Build();

Interactive Table#

var table = Controls.Table()
    .AddColumn("Name")
    .AddColumn("Status")
    .AddColumn("Priority", TextJustification.Right)
    .AddRow("Task 1", "[green]Done[/]", "High")
    .AddRow("Task 2", "[yellow]In Progress[/]", "Medium")
    .AddRow("Task 3", "[red]Blocked[/]", "Low")
    .Interactive()
    .WithCellNavigation()
    .WithSorting()
    .WithHeaderColors(Color.White, Color.DarkBlue)
    .Rounded()
    .OnRowActivated((sender, rowIdx) =>
    {
        // Handle row activation
    })
    .Build();

Interactive DataGrid with Virtual Data#

// Implement ITableDataSource for large datasets
public class ProductDataSource : ITableDataSource
{
    private readonly List<Product> _products;

    public int RowCount => _products.Count;
    public int ColumnCount => 4;

    public string GetColumnHeader(int col) => col switch
    {
        0 => "ID", 1 => "Name", 2 => "Price", 3 => "Status", _ => ""
    };

    public string GetCellValue(int row, int col) => col switch
    {
        0 => _products[row].Id.ToString(),
        1 => _products[row].Name,
        2 => $"${_products[row].Price:F2}",
        3 => _products[row].Status,
        _ => ""
    };

    public TextJustification GetColumnAlignment(int col) => col switch
    {
        0 => TextJustification.Right,
        2 => TextJustification.Right,
        _ => TextJustification.Left
    };

    // Optional: fixed column widths (null = auto)
    public int? GetColumnWidth(int col) => col switch
    {
        0 => 6, _ => null
    };

    // Optional: sorting support
    public bool CanSort(int col) => true;
    public void Sort(int col, SortDirection direction) { /* sort _products */ }

    public event EventHandler? DataChanged;
}

// Use it
var dataSource = new ProductDataSource(products);

var grid = Controls.Table()
    .WithTitle("Product Inventory (10,000 rows)")
    .WithDataSource(dataSource)
    .Interactive()
    .WithCellNavigation()
    .WithSorting()
    .WithColumnResize()
    .WithInlineEditing()
    .WithHeaderColors(Color.White, Color.DarkBlue)
    .Rounded()
    .WithVerticalAlignment(VerticalAlignment.Fill)
    .WithHorizontalAlignment(HorizontalAlignment.Stretch)
    .OnCellEditCompleted((sender, e) =>
    {
        dataSource.UpdateRecord(e.Row, e.Column, e.NewValue);
    })
    .Build();

Keyboard Support#

Row Navigation#

Cell Navigation (when enabled)#

Inline Editing (when enabled)#

Inline Filtering (when enabled)#

Multi-Select#

Mouse Support#

Column Widths#

A column is either fixed (an explicit Width) or auto (sized from its content). When the auto columns do not fit, they are shrunk proportionally — which means one column holding a very long value can squeeze its neighbors down to a couple of characters:

│St│Ti│Message
│RU│16│XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX...

MinWidth sets a floor for an auto column so that cannot happen:

var table = new TableControlBuilder()
    .AddColumn("Status",  TextJustification.Left, width: null, minWidth: 8)
    .AddColumn("Time",    TextJustification.Left, width: null, minWidth: 8)
    .AddColumn("Message", TextJustification.Left, width: null, minWidth: null)
    .WithHorizontalScrollbar(ScrollbarVisibility.Auto)
    .Build();

│Status  │Time    │Message
│RUNNING │16:29:00│XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX...

Or on an existing column:

table.Columns[0].MinWidth = 8;

Behavior worth knowing:

• Fixed columns ignore MinWidth. An explicit Width is already a decision; its floor stays 1.
• null, 0 or a negative value all mean no floor — the column can shrink to 1 character, which is how the table behaved before floors existed.
• Floors can overflow the viewport. When honoring every floor needs more room than there is, the table lets its total content width exceed the viewport and relies on the horizontal scrollbar to pan, rather than crushing a column below a usable width. Pair MinWidth with WithHorizontalScrollbar(ScrollbarVisibility.Auto) so the overflow is reachable.

For a virtual data source, return the floor from GetColumnMinWidth instead:

public int? GetColumnMinWidth(int columnIndex) => columnIndex switch
{
    0 => 8,     // Status
    1 => 8,     // Time
    _ => null,  // no floor
};

ITableDataSource#

The ITableDataSource interface enables virtual data binding for large datasets. Only visible rows are queried — the control never loads all data into memory.

public interface ITableDataSource : INotifyCollectionChanged
{
    int RowCount { get; }
    int ColumnCount { get; }
    string GetColumnHeader(int columnIndex);
    string GetCellValue(int rowIndex, int columnIndex);

    // Optional (default interface methods):
    TextJustification GetColumnAlignment(int columnIndex) => TextJustification.Left;
    int? GetColumnWidth(int columnIndex) => null;
    int? GetColumnMinWidth(int columnIndex) => null;
    Color? GetRowBackgroundColor(int rowIndex) => null;
    Color? GetRowForegroundColor(int rowIndex) => null;
    bool IsRowEnabled(int rowIndex) => true;
    object? GetRowTag(int rowIndex) => null;
    bool CanSort(int columnIndex) => false;
    void Sort(int columnIndex, SortDirection direction) { }
    void ClearSort() { }
    bool CanFilter => false;
    void ApplyFilter(string filterText, string? columnName, FilterOperator op) { }
    void ClearFilter() { }
}

When DataSource is set:

• Internal _rows/_columns lists are ignored
• Only visible rows are queried via GetCellValue()
• Column widths auto-measure from visible rows
• Sorting delegates to DataSource.Sort() if CanSort() returns true; clearing the sort calls DataSource.ClearSort() so the source can restore its own order
• Filtering is handed to the source when CanFilter is true — see Letting the data source filter
• Raising CollectionChanged triggers re-measure and re-render; Reset also returns the selection to the first row
• A filter over the source follows its changes: a client-side filter is scanned again, and display rows supplied through TryApplyFilterToDataSource are asked for again, also after the source sorts itself
• AddRow()/ClearRows() throw if DataSource is set

Builder Methods#

Data#

Interactive Features#

Appearance#

Events#

Examples#

File Explorer Table#

var table = Controls.Table()
    .AddColumn("Name")
    .AddColumn("Size", TextJustification.Right, 10)
    .AddColumn("Modified", TextJustification.Right, 20)
    .Interactive()
    .WithSorting()
    .Rounded()
    .WithHeaderColors(Color.White, Color.DarkBlue)
    .WithVerticalAlignment(VerticalAlignment.Fill)
    .WithHorizontalAlignment(HorizontalAlignment.Stretch)
    .OnRowActivated((sender, rowIdx) =>
    {
        var row = sender.GetRow(rowIdx);
        var path = row?.Tag as string;
        if (path != null && Directory.Exists(path))
            NavigateTo(path);
    })
    .OnRightClick((sender, args) =>
    {
        ShowContextMenu(sender, args);
    })
    .Build();

Editable Spreadsheet#

var table = Controls.Table()
    .AddColumn("A")
    .AddColumn("B")
    .AddColumn("C")
    .AddRow("1", "2", "3")
    .AddRow("4", "5", "6")
    .Interactive()
    .WithCellNavigation()
    .WithInlineEditing()
    .WithColumnResize()
    .OnCellEditCompleted((sender, e) =>
    {
        // e.Row, e.Column, e.OldValue, e.NewValue
        RecalculateFormulas();
    })
    .Build();

Multi-Select with Checkboxes#

var table = Controls.Table()
    .AddColumn("Task")
    .AddColumn("Status")
    .AddRow("Write tests", "[yellow]Pending[/]")
    .AddRow("Code review", "[green]Done[/]")
    .AddRow("Deploy", "[red]Blocked[/]")
    .Interactive()
    .WithCheckboxMode()
    .Build();

// Later: get checked rows
var checked = table.GetCheckedRows();

Gradient Background#

TableControl preserves gradient backgrounds from parent windows when no explicit background color is set:

var gradient = ColorGradient.FromColors(
    new Color(10, 10, 50),
    new Color(0, 50, 80),
    new Color(40, 10, 60));

var window = new WindowBuilder(ws)
    .WithBackgroundGradient(gradient, GradientDirection.Vertical)
    .AddControls(table)
    .BuildAndShow();

Filtering#

When FilteringEnabled = true, press / to enter filter mode. Type a filter expression and press Enter to confirm, or Escape to cancel.

Filter Syntax#

Compound Expressions#

Space-separated terms are combined with AND (all must match). Pipe-separated alternatives within a term are combined with OR (any must match).

category:electronics price>500          → category contains "electronics" AND price > 500
category:electronics|clothing           → category contains "electronics" OR "clothing"
category:electronics|clothing price>500 → (electronics OR clothing) AND price > 500

When using | with a column prefix, subsequent alternatives without their own prefix inherit the column and operator from the first:

• category:fruit|vegetable → both target "category" column
• category:fruit|warehouse:NYC → first targets "category", second targets "warehouse"

Programmatic API#

// Simple text filter
table.ApplyFilter("fruit");

// Column-specific filter
table.FilterByColumn(1, "fruit");

// Compound expression
table.ApplyFilter("category:fruit|vegetable price>1.00");

// Clear filter
table.ClearFilter();

// Check filter state
bool isFiltering = table.IsFiltering;
string? filterText = table.ActiveFilterText;

Letting the data source filter#

An ITableDataSource that sets CanFilter is handed single-expression filters through ApplyFilter(text, column, op), and narrows itself rather than being scanned row by row. That hook takes one condition, so compound AND/OR filters are applied by the table instead — correct, but it means a source that could evaluate the whole expression never sees it.

Override TryApplyFilterToDataSource to receive the parsed filter whole:

protected override TableFilterResult TryApplyFilterToDataSource(
    ITableDataSource dataSource, CompoundFilterExpression compound)

Return one of three answers:

SourceNarrowed is what to use for large, remote or virtualized sources: nothing is materialized, the table holds no map, and cells are read only for rows about to be painted.

WithDisplayRows is for a source whose visible set its own RowCount cannot express — a hierarchy keeping a non-matching parent visible because a child matched, or any source wanting a display order of its own. It costs one int per matching row, and the source must enumerate its complete match set before the table paints, since the row count comes from the list length. Cell reads stay lazy either way.

Everything after the hand-off — display map, selection, scroll position, the FilterApplied event — stays with the control, so an override cannot skip it. Sorting a table whose source supplied display rows asks the source to sort, rather than rebuilding the map and discarding its choice.

protected override TableFilterResult TryApplyFilterToDataSource(
    ITableDataSource dataSource, CompoundFilterExpression compound)
{
    if (dataSource is not TreeSource tree)
        return base.TryApplyFilterToDataSource(dataSource, compound);

    // One value per term; each FilterExpression also carries ColumnName and Operator
    // when the user typed a "col:value" prefix.
    var needles = compound.Terms.Select(t => t.Alternatives[0].Value);
    return TableFilterResult.WithDisplayRows(tree.MatchesKeepingParents(needles));
}

Builder Methods#

Events#

Sorting#

When SortingEnabled = true, clicking a column header cycles through: Ascending -> Descending -> None. A sort indicator (up/down triangle) appears in the header.

For in-memory rows, sorting creates an internal index map. For ITableDataSource, sorting delegates to DataSource.Sort() if CanSort() returns true, and clearing the sort, by a header click, ClearSort() or SortingEnabled = false, calls DataSource.ClearSort() on a source that sorted itself.

How in-memory rows are ordered:

• A column's CustomRowComparer wins, then its CustomComparer (given the raw cell text), then an ordinal, case-insensitive comparison of the text the cell displays — markup is ignored, so [red]Apple[/] sorts under A.
• The sort is stable: rows that compare equal keep the order they were added in, ascending and descending alike.
• The same rules apply whether or not a filter is active.
• Rows added, inserted, removed or replaced while sorted take their sorted place; the sort stays on. Editing a cell does not re-sort, so an edited row does not jump away under the cursor.
• The selection stays on its rows when the order changes, and when the sort or a filter is cleared.

Hit Testing#

HitTest(x, y) says what part of the table a position falls on, in the same control-relative coordinates MouseEventArgs.Position reports:

table.MouseRightClick += (_, e) =>
{
    var hit = table.HitTest(e.Position.X, e.Position.Y);
    if (hit.Zone == TableHitZone.Cell)
        ShowCellMenu(table.GetRow(hit.DataRowIndex), hit.ColumnIndex);
};

Zone is one of None, Title, Header, Cell, Row (a data row's borders or gutter), Checkbox, EmptyDataArea, FilterBar, VerticalScrollbar and HorizontalScrollbar. A hit on a row reports it twice: DisplayRowIndex, as the selection counts rows, and DataRowIndex, as GetRow counts them — they differ under a sort or a filter. CellOffset counts cells from the column's left edge as laid out, so horizontal scrolling does not change it. Before the first paint every position is None.

Extending TableControl#

TableControl can be subclassed. A derived table — one that nests rows, say — reuses the table's painting, scrolling, selection, sorting and filtering, and supplies only what it knows that the table cannot. Every member below is protected, and runs on the UI thread. TreeTableControl is built on these members alone.

Deciding which rows are displayed#

RowCount counts displayed rows; DataRowCount counts every row, and data indices — GetRow, the cell accessors — run up to it.

Changing rows#

Changing the rows, or calling RefreshDisplayRows, from inside ComputeDisplayRows, ResolveHiddenSelectedRow or ResolveRemovedSelectedRow throws InvalidOperationException rather than recursing.

Drawing and input#

The hooks are never called while SyncRoot is held, and none of them should block.

// A table that hides rows tagged "draft" unless asked to show them, marks them with a
// glyph, and toggles them with D.
public sealed class DraftAwareTable : TableControl
{
    private bool _showDrafts;

    protected override int[]? ComputeDisplayRows(TableDisplayQuery query)
    {
        int[] rows = base.ComputeDisplayRows(query) ?? Enumerable.Range(0, DataRowCount).ToArray();
        return _showDrafts ? rows : rows.Where(r => GetRow(r).Tag is not "draft").ToArray();
    }

    protected override string? GetCellPrefixMarkup(int dataRowIndex, int columnIndex)
        => columnIndex == 0 && GetRow(dataRowIndex).Tag is "draft" ? "[dim]~ [/]" : null;

    protected override bool TryHandleKey(ConsoleKeyInfo key)
    {
        if (key.Key != ConsoleKey.D) return false;

        _showDrafts = !_showDrafts;
        RefreshDisplayRows();
        return true;
    }
}

Virtual Rendering#

Regardless of data mode or ReadOnly state, TableControl always uses virtual rendering: only visible rows are measured and painted. This means 10,000+ row tables render instantly with no performance penalty.

Column widths are computed using sample-based measurement (header + visible rows + a small buffer), cached and invalidated on significant scroll or data changes. Auto columns are shrunk proportionally to fit, subject to any MinWidth floor — see Column Widths.

Scrollbars#

• Vertical scrollbar: Appears when rows exceed viewport. Shows up/down arrows, draggable thumb, and clickable track for page scrolling.
• Horizontal scrollbar: Appears when total column width exceeds viewport. Same interaction model.
• Both support ScrollbarVisibility.Auto (default), Always, or Never.
• On a table with very many rows the proportional vertical thumb shrinks to a single row and becomes hard to grab. MinScrollbarThumbSize sets a floor for it.
• MouseWheelScrollSpeed sets how many rows (or columns, with Shift+wheel) move per wheel notch — it drives both scroll axes. It defaults to ControlDefaults.DefaultScrollWheelLines, so setting that once at startup changes the wheel step for every table that hasn't overridden it:

// Change the wheel step everywhere, once at startup:
ControlDefaults.DefaultScrollWheelLines = 3;

// Or override it for just this table:
var table = Controls.Table()
    .WithMouseWheelScrollSpeed(5)
    .Build();

• A table whose columns carry MinWidth floors may deliberately overflow its viewport rather than crush a column — see Column Widths. The horizontal scrollbar is how that overflow is reached, so leave it on Auto.

See Also#

• ListControl - For simple item lists
• TreeTableControl - A table whose rows nest
• Controls Reference - All controls overview

Back to Controls | Back to Main Documentation