Class TableControl

Namespace

SharpConsoleUI.Controls

Assembly

SharpConsoleUI.dll

A table control that renders tabular data directly to CharacterBuffer. Supports both read-only display and interactive mode with selection, keyboard navigation, scrolling, sorting, multi-selection, column resizing, inline editing, draggable scrollbars, and virtual data binding.

public class TableControl : BaseControl, IDOMPaintable, INotifyPropertyChanged, IInteractiveControl, IFocusableControl, IMouseAwareControl, IWindowControl, IDisposable

Inheritance

object

BaseControl

TableControl

Implements

IDOMPaintable

INotifyPropertyChanged

IInteractiveControl

IFocusableControl

IMouseAwareControl

IWindowControl

IDisposable

Inherited Members

BaseControl.PropertyChanged

BaseControl.GotFocus

BaseControl.LostFocus

BaseControl.Bindings

BaseControl.OnPropertyChanged(string)

BaseControl.SubscribeToFocusManager()

BaseControl.SetProperty<T>(ref T, T, string)

BaseControl.SetProperty<T>(ref T, T, Func<T, T>, string)

BaseControl.ActualX

BaseControl.ActualY

BaseControl.ActualWidth

BaseControl.ActualHeight

BaseControl.HorizontalAlignment

BaseControl.VerticalAlignment

BaseControl.Container

BaseControl.Margin

BaseControl.StickyPosition

BaseControl.Name

BaseControl.Tag

BaseControl.Visible

BaseControl.Width

BaseControl.Invalidate()

BaseControl.SetActualBounds(LayoutRect)

BaseControl.Dispose()

BaseControl.ComputeHasFocus()

BaseControl.ComputeIsInFocusPath()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

WindowControlExtensions.RequestFocus(IFocusableControl, FocusReason)

WindowControlExtensions.GetParentWindow(IWindowControl)

WindowControlExtensions.GetPortalAncestor(IWindowControl)

BindingExtensions.BindTwoWay<TControl, TSource, TValue>(TControl, TSource, Expression<Func<TSource, TValue>>, Expression<Func<TControl, TValue>>)

BindingExtensions.BindTwoWay<TControl, TSource, TSrc, TTgt>(TControl, TSource, Expression<Func<TSource, TSrc>>, Expression<Func<TControl, TTgt>>, Func<TSrc, TTgt>, Func<TTgt, TSrc>)

BindingExtensions.BindTwoWay<TBuilder, TControl, TSource, TValue>(TBuilder, TSource, Expression<Func<TSource, TValue>>, Expression<Func<TControl, TValue>>)

BindingExtensions.BindTwoWay<TBuilder, TControl, TSource, TSrc, TTgt>(TBuilder, TSource, Expression<Func<TSource, TSrc>>, Expression<Func<TControl, TTgt>>, Func<TSrc, TTgt>, Func<TTgt, TSrc>)

BindingExtensions.Bind<TControl, TSource, TValue>(TControl, TSource, Expression<Func<TSource, TValue>>, Expression<Func<TControl, TValue>>)

BindingExtensions.Bind<TControl, TSource, TSrc, TTgt>(TControl, TSource, Expression<Func<TSource, TSrc>>, Expression<Func<TControl, TTgt>>, Func<TSrc, TTgt>)

BindingExtensions.Bind<TBuilder, TControl, TSource, TValue>(TBuilder, TSource, Expression<Func<TSource, TValue>>, Expression<Func<TControl, TValue>>)

BindingExtensions.Bind<TBuilder, TControl, TSource, TSrc, TTgt>(TBuilder, TSource, Expression<Func<TSource, TSrc>>, Expression<Func<TControl, TTgt>>, Func<TSrc, TTgt>)

Constructors

TableControl()

Initializes a new instance of the TableControl class.

public TableControl()

Properties

ActiveFilterText

Gets the active filter text, or null if no filter is active.

public string? ActiveFilterText { get; }

Property Value

string

AutoHighlightOnFocus

Gets or sets whether to auto-highlight the first row when the control gains focus. Default: true.

public bool AutoHighlightOnFocus { get; set; }

Property Value

bool

BackgroundColor

public Color? BackgroundColor { get; set; }

Property Value

Color?

BorderColor

Gets or sets the border color. Null falls back to theme.

public Color? BorderColor { get; set; }

Property Value

Color?

BorderStyle

Gets or sets the border style.

public BorderStyle BorderStyle { get; set; }

Property Value

BorderStyle

CanFocusWithMouse

Whether this control can receive focus via mouse clicks

public bool CanFocusWithMouse { get; }

Property Value

bool

CanReceiveFocus

Whether this control can receive focus

public bool CanReceiveFocus { get; }

Property Value

bool

CellNavigationEnabled

Gets or sets whether cell-level navigation is enabled (Tab/Left/Right to move between cells).

public bool CellNavigationEnabled { get; set; }

Property Value

bool

CheckboxMode

Gets or sets whether checkbox mode is enabled (shows [x]/[ ] before each row). Requires MultiSelectEnabled = true.

public bool CheckboxMode { get; set; }

Property Value

bool

ClearSelectionOnEmptyClick

When true, a left-click in the data area that does not hit any row clears the current selection (SelectedRowIndex becomes -1 and any multi-selection is discarded). Default: false, to preserve the classic "click below the last row does nothing" behavior.

public bool ClearSelectionOnEmptyClick { get; set; }

Property Value

bool

ColumnCount

Gets the number of columns in the table.

public int ColumnCount { get; }

Property Value

int

ColumnResizeEnabled

Gets or sets whether column resizing by dragging column borders is enabled.

public bool ColumnResizeEnabled { get; set; }

Property Value

bool

ColumnSeparator

Optional character drawn between columns when borders are disabled.

public char? ColumnSeparator { get; set; }

Property Value

char?

ColumnSeparatorColor

Color for the column separator character. Falls back to border color if null.

public Color? ColumnSeparatorColor { get; set; }

Property Value

Color?

Columns

Gets the read-only list of columns.

public IReadOnlyList<TableColumn> Columns { get; }

Property Value

IReadOnlyList<TableColumn>

ContentHeight

Gets the content height.

public int? ContentHeight { get; }

Property Value

int?

ContentWidth

Gets the minimum width needed to display the control's content, including margins. Returns null if width cannot be determined. This is calculated based on content (text length, child controls, etc.) and represents the natural/intrinsic size.

public override int? ContentWidth { get; }

Property Value

int?

CurrentFilterMode

Gets the current filter mode.

public FilterMode CurrentFilterMode { get; }

Property Value

FilterMode

CurrentSortDirection

Gets the current sort direction.

public SortDirection CurrentSortDirection { get; }

Property Value

SortDirection

DataSource

Gets or sets the virtual data source. When set, the control ignores internal rows/columns and queries only visible rows from the source on demand. Mutually exclusive with in-memory rows.

public ITableDataSource? DataSource { get; set; }

Property Value

ITableDataSource

FilteringEnabled

Gets or sets whether filtering is enabled. Press '/' to enter filter mode.

public bool FilteringEnabled { get; set; }

Property Value

bool

ForegroundColor

public Color? ForegroundColor { get; set; }

Property Value

Color?

FuzzyFilterEnabled

Gets or sets whether fuzzy (character-subsequence) matching is enabled as a fallback.

public bool FuzzyFilterEnabled { get; set; }

Property Value

bool

HasActiveRowAnimations

Whether any row-level animations are currently active.

public bool HasActiveRowAnimations { get; }

Property Value

bool

HasFocus

public bool HasFocus { get; }

Property Value

bool

HeaderBackgroundColor

Gets or sets the header background color. Null falls back to theme.

public Color? HeaderBackgroundColor { get; set; }

Property Value

Color?

HeaderForegroundColor

Gets or sets the header foreground color. Null falls back to theme.

public Color? HeaderForegroundColor { get; set; }

Property Value

Color?

Height

Gets or sets the explicit height.

public override int? Height { get; set; }

Property Value

int?

HorizontalScrollOffset

Gets or sets the horizontal scroll offset (in character columns).

public int HorizontalScrollOffset { get; set; }

Property Value

int

HorizontalScrollbarVisibility

Gets or sets when the horizontal scrollbar should be displayed.

public ScrollbarVisibility HorizontalScrollbarVisibility { get; set; }

Property Value

ScrollbarVisibility

HoverEnabled

Gets or sets whether mouse hover highlighting is enabled. Default: true.

public bool HoverEnabled { get; set; }

Property Value

bool

InlineEditingEnabled

Gets or sets whether inline cell editing is enabled (F2 to edit, Enter to commit, Escape to cancel). Requires CellNavigationEnabled = true.

public bool InlineEditingEnabled { get; set; }

Property Value

bool

IsEditing

Gets whether the control is currently in cell editing mode.

public bool IsEditing { get; }

Property Value

bool

IsEnabled

Gets or sets whether this control is enabled and can receive input.

public bool IsEnabled { get; set; }

Property Value

bool

IsFiltering

Gets whether a filter is currently active (typing or confirmed).

public bool IsFiltering { get; }

Property Value

bool

MultiSelectEnabled

Gets or sets whether multi-selection is enabled.

public bool MultiSelectEnabled { get; set; }

Property Value

bool

ReadOnly

Gets or sets whether the table is read-only. When true (default), the table behaves as a static display with no selection or interaction. When false, enables selection, keyboard navigation, scrolling, and other interactive features.

public bool ReadOnly { get; set; }

Property Value

bool

RowCount

Gets the number of rows in the table.

public int RowCount { get; }

Property Value

int

Rows

Gets the read-only list of rows.

public IReadOnlyList<TableRow> Rows { get; }

Property Value

IReadOnlyList<TableRow>

ScrollOffset

Gets or sets the vertical scroll offset (first visible row index).

public int ScrollOffset { get; set; }

Property Value

int

SelectedColumnIndex

Gets or sets the selected column index for cell navigation. -1 means no column selected.

public int SelectedColumnIndex { get; set; }

Property Value

int

SelectedRow

Gets the currently selected row, or null if no selection.

public TableRow? SelectedRow { get; }

Property Value

TableRow

SelectedRowIndex

Gets or sets the selected row index. -1 means no selection.

public int SelectedRowIndex { get; set; }

Property Value

int

ShowHeader

Gets or sets whether to show the header row.

public bool ShowHeader { get; set; }

Property Value

bool

ShowRowSeparators

Gets or sets whether to show row separators.

public bool ShowRowSeparators { get; set; }

Property Value

bool

SortColumnIndex

Gets the current sort column index, or -1 if no sort is applied.

public int SortColumnIndex { get; }

Property Value

int

SortingEnabled

Gets or sets whether sorting is enabled. When enabled, clicking a header column cycles through Ascending → Descending → None.

public bool SortingEnabled { get; set; }

Property Value

bool

Title

Gets or sets the table title.

public string? Title { get; set; }

Property Value

string

TitleAlignment

Gets or sets the title alignment.

public TextJustification TitleAlignment { get; set; }

Property Value

TextJustification

TruncationFade

Gets or sets whether truncated cell text fades out instead of hard-cutting. When enabled, the last 4 characters of truncated cells blend toward the background. Default: false.

public bool TruncationFade { get; set; }

Property Value

bool

UseSafeBorder

Gets or sets whether to use safe border characters.

public bool UseSafeBorder { get; set; }

Property Value

bool

VerticalScrollbarVisibility

Gets or sets when the vertical scrollbar should be displayed.

public ScrollbarVisibility VerticalScrollbarVisibility { get; set; }

Property Value

ScrollbarVisibility

WantsMouseEvents

Whether this control wants to receive mouse events

public bool WantsMouseEvents { get; set; }

Property Value

bool

Methods

AddColumn(TableColumn)

Adds a column to the table.

public void AddColumn(TableColumn column)

Parameters

column TableColumn

AddColumn(string, TextJustification, int?)

Adds a column with the specified header.

public void AddColumn(string header, TextJustification alignment = TextJustification.Left, int? width = null)

Parameters

header string

alignment TextJustification

width int?

AddRow(TableRow)

Adds a row to the table.

public void AddRow(TableRow row)

Parameters

row TableRow

AddRow(params string[])

Adds a row with the specified cells.

public void AddRow(params string[] cells)

Parameters

cells string[]

AddRows(IEnumerable<TableRow>)

Adds multiple rows to the table.

public void AddRows(IEnumerable<TableRow> rows)

Parameters

rows IEnumerable<TableRow>

AnimateRowRemoval(int, TimeSpan, EasingFunction?)

Animates a row fading to black, then removes it from the table.

public IAnimation? AnimateRowRemoval(int rowIndex, TimeSpan duration, EasingFunction? easing = null)

Parameters

rowIndex int

The data row index to remove.

duration TimeSpan

Duration of the fade-out animation.

easing EasingFunction

Easing function. Defaults to EaseOut.

Returns

IAnimation

The animation, or null if rowIndex is invalid or no AnimationManager.

AnimateRowsRemoval(int[], TimeSpan, EasingFunction?)

Bulk variant: all specified rows fade to black simultaneously, then are all removed in one frame (in reverse index order to preserve indices during removal).

public IAnimation? AnimateRowsRemoval(int[] rowIndices, TimeSpan duration, EasingFunction? easing = null)

Parameters

rowIndices int[]

The data row indices to remove.

duration TimeSpan

Duration of the fade-out animation.

easing EasingFunction

Easing function. Defaults to EaseOut.

Returns

IAnimation

The animation, or null if no valid indices or no AnimationManager.

ApplyFilter(CompoundFilterExpression)

Applies a compound filter expression. Sets mode to Confirmed.

public void ApplyFilter(CompoundFilterExpression compound)

Parameters

compound CompoundFilterExpression

ApplyFilter(FilterExpression)

Applies a pre-built filter expression. Wraps it into a compound expression.

public void ApplyFilter(FilterExpression expression)

Parameters

expression FilterExpression

ApplyFilter(string)

Applies a filter programmatically. Sets mode to Confirmed.

public void ApplyFilter(string filterText)

Parameters

filterText string

ApplyRowAnimationOverlays(CharacterBuffer)

Iterates active row animations and applies color overlays to the buffer. Should be called from a PostBufferPaint handler externally.

public void ApplyRowAnimationOverlays(CharacterBuffer buffer)

Parameters

buffer CharacterBuffer

The character buffer to apply overlays to.

ClearColumns()

Clears all columns.

public void ClearColumns()

ClearFilter()

Clears any active filter, restoring all rows.

public void ClearFilter()

ClearRows()

Clears all rows.

public void ClearRows()

ClearSelection()

Clears all selection (multi-select mode).

public void ClearSelection()

ClearSort()

Clears any active sort, restoring original order.

public void ClearSort()

Create()

Creates a new TableControlBuilder for fluent configuration.

public static TableControlBuilder Create()

Returns

TableControlBuilder

FilterByColumn(int, string, FilterOperator)

Filters by a specific column programmatically.

public void FilterByColumn(int columnIndex, string value, FilterOperator op = FilterOperator.Contains)

Parameters

columnIndex int

value string

op FilterOperator

FlashCell(int, int, Color, TimeSpan, EasingFunction?)

Applies a color overlay to a single cell using SinePulse easing by default.

public IAnimation? FlashCell(int rowIndex, int columnIndex, Color color, TimeSpan duration, EasingFunction? easing = null)

Parameters

rowIndex int

The data row index.

columnIndex int

The column index.

color Color

The overlay color.

duration TimeSpan

How long the flash lasts.

easing EasingFunction

Easing function. Defaults to SinePulse.

Returns

IAnimation

The animation, or null if indices are invalid or no AnimationManager.

FlashRow(int, Color, TimeSpan, EasingFunction?)

Applies a color overlay to an entire row using SinePulse easing by default. The overlay peaks at the midpoint then decays back to zero.

public IAnimation? FlashRow(int rowIndex, Color color, TimeSpan duration, EasingFunction? easing = null)

Parameters

rowIndex int

The data row index to flash.

color Color

The overlay color.

duration TimeSpan

How long the flash lasts.

easing EasingFunction

Easing function. Defaults to SinePulse.

Returns

IAnimation

The animation, or null if rowIndex is invalid or no AnimationManager.

GetCell(int, int)

Gets a cell value.

public string GetCell(int row, int column)

Parameters

row int

column int

Returns

string

GetCheckedRows()

Gets all checked rows (checkbox mode).

public List<TableRow> GetCheckedRows()

Returns

List<TableRow>

GetLogicalContentSize()

Gets the logical size of the control's content without rendering.

public override Size GetLogicalContentSize()

Returns

Size

The size representing the content's natural dimensions.

GetRow(int)

Gets a row.

public TableRow GetRow(int index)

Parameters

index int

Returns

TableRow

GetSelectedIndices()

Gets the display indices of all selected/checked rows in multi-select mode. Works in both row-based and DataSource modes.

public List<int> GetSelectedIndices()

Returns

List<int>

GetSelectedRows()

Gets all selected rows in multi-select mode.

public List<TableRow> GetSelectedRows()

Returns

List<TableRow>

GetVisibleRowCount()

Gets the number of visible rows based on the current rendering area.

public int GetVisibleRowCount()

Returns

int

HighlightRow(int, Color, TimeSpan, EasingFunction?)

Highlights a row starting at full overlay intensity, decaying to zero. Useful for new row insertion highlights. Uses EaseOut by default.

public IAnimation? HighlightRow(int rowIndex, Color color, TimeSpan duration, EasingFunction? easing = null)

Parameters

rowIndex int

The data row index to highlight.

color Color

The overlay color.

duration TimeSpan

How long the highlight lasts.

easing EasingFunction

Easing function. Defaults to EaseOut.

Returns

IAnimation

The animation, or null if rowIndex is invalid or no AnimationManager.

InsertRow(int, TableRow)

Inserts a row at the given index. Index is clamped to [0, RowCount].

public void InsertRow(int index, TableRow row)

Parameters

index int

The zero-based index at which to insert.

row TableRow

The row to insert.

InsertRow(int, params string[])

Inserts a row with the specified cells at the given index. Index is clamped to [0, RowCount].

public void InsertRow(int index, params string[] cells)

Parameters

index int

The zero-based index at which to insert.

cells string[]

The cell values for the new row.

InsertRows(int, IEnumerable<TableRow>)

Inserts multiple rows starting at the given index. Index is clamped to [0, RowCount].

public void InsertRows(int index, IEnumerable<TableRow> rows)

Parameters

index int

The zero-based index at which to begin inserting.

rows IEnumerable<TableRow>

The rows to insert.

IsRowSelected(int)

Returns whether a display row index is selected (in multi-select mode) or is the current selected row.

public bool IsRowSelected(int displayIndex)

Parameters

displayIndex int

Returns

bool

MeasureDOM(LayoutConstraints)

Measures the control's desired size given the available constraints.

public override LayoutSize MeasureDOM(LayoutConstraints constraints)

Parameters

constraints LayoutConstraints

The layout constraints (min/max width/height).

Returns

LayoutSize

The desired size of the control.

OnDisposing()

Called during Dispose() before Container is set to null. Override to perform control-specific cleanup (null events, close portals, clear data, etc.).

protected override void OnDisposing()

PaintDOM(CharacterBuffer, LayoutRect, LayoutRect, Color, Color)

Paints the control's content directly to a CharacterBuffer.

public override void PaintDOM(CharacterBuffer buffer, LayoutRect bounds, LayoutRect clipRect, Color defaultFg, Color defaultBg)

Parameters

buffer CharacterBuffer

The buffer to paint to.

bounds LayoutRect

The absolute bounds where the control should paint.

clipRect LayoutRect

The clipping rectangle (visible area).

defaultFg Color

defaultBg Color

ProcessKey(ConsoleKeyInfo)

Processes a keyboard input event.

public bool ProcessKey(ConsoleKeyInfo key)

Parameters

key ConsoleKeyInfo

The key information for the pressed key.

Returns

bool

True if the key was handled by this control; otherwise, false.

ProcessMouseEvent(MouseEventArgs)

Processes a mouse event for this control

public bool ProcessMouseEvent(MouseEventArgs args)

Parameters

args MouseEventArgs

Mouse event arguments with control-relative coordinates

Returns

bool

True if the event was handled and should not propagate further

RemoveColumn(int)

Removes the column at the specified index.

public void RemoveColumn(int index)

Parameters

index int

RemoveRow(int)

Removes the row at the specified index.

public void RemoveRow(int index)

Parameters

index int

SelectAll()

Selects all rows (multi-select mode).

public void SelectAll()

SetColumnAlignment(int, TextJustification)

Sets the alignment of a column.

public void SetColumnAlignment(int index, TextJustification alignment)

Parameters

index int

alignment TextJustification

SetColumnWidth(int, int?)

Sets the width of a column.

public void SetColumnWidth(int index, int? width)

Parameters

index int

width int?

SetData(IEnumerable<TableRow>)

Sets all rows at once.

public void SetData(IEnumerable<TableRow> rows)

Parameters

rows IEnumerable<TableRow>

SortByColumn(int)

Sorts the table by the specified column. Cycles: None → Ascending → Descending → None.

public void SortByColumn(int columnIndex)

Parameters

columnIndex int

ToggleRowSelection(int)

Toggles selection of a row in multi-select mode (Ctrl+Click).

public void ToggleRowSelection(int displayIndex)

Parameters

displayIndex int

UpdateCell(int, int, string)

Updates a cell value.

public void UpdateCell(int row, int column, string value)

Parameters

row int

column int

value string

Events

CellActivated

Occurs when a cell is activated (Enter key in cell navigation mode).

public event EventHandler<(int Row, int Column)>? CellActivated

Event Type

EventHandler<(int Line, int Column)>

CellEditCancelled

Occurs when a cell edit is cancelled (Escape key).

public event EventHandler<(int Row, int Column)>? CellEditCancelled

Event Type

EventHandler<(int Line, int Column)>

CellEditCompleted

Occurs when a cell edit is committed (Enter key).

public event EventHandler<(int Row, int Column, string OldValue, string NewValue)>? CellEditCompleted

Event Type

EventHandler<(int Row, int Column, string OldValue, string NewValue)>

FilterApplied

Occurs when a filter is applied (confirmed).

public event EventHandler<string>? FilterApplied

Event Type

EventHandler<string>

FilterCleared

Occurs when the filter is cleared.

public event EventHandler? FilterCleared

Event Type

EventHandler

FilterTextChanged

Occurs when the filter text changes during typing.

public event EventHandler<string>? FilterTextChanged

Event Type

EventHandler<string>

MouseClick

Event fired when the control is clicked

public event EventHandler<MouseEventArgs>? MouseClick

Event Type

EventHandler<MouseEventArgs>

MouseDoubleClick

Event fired when the control is double-clicked

public event EventHandler<MouseEventArgs>? MouseDoubleClick

Event Type

EventHandler<MouseEventArgs>

MouseEnter

Event fired when the mouse enters the control area

public event EventHandler<MouseEventArgs>? MouseEnter

Event Type

EventHandler<MouseEventArgs>

MouseLeave

Event fired when the mouse leaves the control area

public event EventHandler<MouseEventArgs>? MouseLeave

Event Type

EventHandler<MouseEventArgs>

MouseMove

Event fired when the mouse moves over the control

public event EventHandler<MouseEventArgs>? MouseMove

Event Type

EventHandler<MouseEventArgs>

MouseRightClick

Event fired when the control is right-clicked (Button3)

public event EventHandler<MouseEventArgs>? MouseRightClick

Event Type

EventHandler<MouseEventArgs>

MultiSelectionChanged

Fired when multi-selection changes (checkbox toggled, selection cleared, select all). Argument is the current count of selected rows.

public event EventHandler<int>? MultiSelectionChanged

Event Type

EventHandler<int>

RowActivated

Occurs when a row is activated (Enter key or double-click).

public event EventHandler<int>? RowActivated

Event Type

EventHandler<int>

SelectedRowChanged

Occurs when the selected row index changes.

public event EventHandler<int>? SelectedRowChanged

Event Type

EventHandler<int>

SelectedRowItemChanged

Occurs when the selected row item changes.

public event EventHandler<TableRow?>? SelectedRowItemChanged

Event Type

EventHandler<TableRow>