Table of Contents

Class HorizontalGridControl

Namespace
SharpConsoleUI.Controls
Assembly
SharpConsoleUI.dll

A grid control that arranges child columns horizontally with optional splitters between them. Supports keyboard and mouse navigation, focus management, and dynamic column resizing.

SIMPLE USAGE (Factory Methods):

// Button row (common pattern)
var buttons = HorizontalGridControl.ButtonRow(
    new ButtonControl { Text = "OK" },
    new ButtonControl { Text = "Cancel" }
);

// Any controls
var grid = HorizontalGridControl.FromControls(control1, control2, control3);

FLUENT USAGE (For Complex Layouts):

var grid = HorizontalGridControl.Create()
    .Column(col => col.Width(48).Add(control1))
    .Column(col => col.Flex(2.0).Add(control2))
    .WithSplitterAfter(0)
    .WithAlignment(HorizontalAlignment.Stretch)
    .Build();

SPLITTER API:

// Add splitters using column references (more intuitive than indices)
grid.AddSplitterAfter(column1);  // Adds splitter between column1 and column2
grid.AddSplitterBefore(column2); // Same result as above

// Or add columns with automatic splitters
grid.AddColumn(column1);
grid.AddColumnWithSplitter(column2); // Creates splitter automatically

TRADITIONAL USAGE (Still Supported):

var grid = new HorizontalGridControl();
var column = new ColumnContainer(grid);
column.AddContent(control);
grid.AddColumn(column);
grid.AddSplitter(0, new SplitterControl()); // Add splitter by index

ARCHITECTURE NOTE:

This control is a single-row GridControl. Each ColumnContainer is translated into a grid column track via Sync(): an explicit Width becomes a Fixed track, a positive FlexFactor becomes a Star track, and otherwise the column is Auto-sized. Splitters are interleaved as fixed-width tracks. Alignment normalization: Sync() force-sets each column's HorizontalAlignment to Stretch and VerticalAlignment to Fill so that the column fills its grid cell exactly; reading these properties back after AddColumn(ColumnContainer) may therefore return Stretch/Fill regardless of the value originally set.

As a GridControl subclass, this control inherits IColorRoleableControl: it has a semantic ColorRole/Outline surface exactly like the grid it now is. 

public class HorizontalGridControl : GridControl, IDOMPaintable, INotifyPropertyChanged, IContainer, IControlHost, IColorRoleableControl, IGridSource, IFillReportsMinimumHeight, IColumnGridOwner, IInteractiveControl, IFocusableControl, ILogicalCursorProvider, IMouseAwareControl, IWindowControl, IDisposable, ICursorShapeProvider, IContainerControl, IFocusScope
Inheritance
HorizontalGridControl
Implements
Inherited Members
Extension Methods

Constructors

HorizontalGridControl()

Initializes a new instance of the HorizontalGridControl class.

public HorizontalGridControl()

Properties

BackgroundColor 

public Color? BackgroundColor { get; set; }

Property Value

Color?

Columns

Gets the list of columns contained in this grid.

public List<ColumnContainer> Columns { get; }

Property Value

List<ColumnContainer>

Container

Gets or sets the parent container that hosts this control.

public override IContainer? Container { get; set; }

Property Value

IContainer

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?

Remarks

The grid has no hard natural width before layout (column tracks resolve against available space), so this returns null to let the layout engine decide.

FocusedContent

Gets the currently focused child control within the grid.

public IInteractiveControl? FocusedContent { get; }

Property Value

IInteractiveControl

ForegroundColor

Gets the foreground color the owning grid contributes to its columns' color-resolution chain. Nullable so an owner may defer to its own container/theme (matches ForegroundColor).

public Color? ForegroundColor { get; set; }

Property Value

Color?

HorizontalAlignment

Gets or sets the horizontal alignment of the control within its container.

public override HorizontalAlignment HorizontalAlignment { get; set; }

Property Value

HorizontalAlignment

Splitters

Gets the list of splitters in this grid.

public IReadOnlyList<SplitterControl> Splitters { get; }

Property Value

IReadOnlyList<SplitterControl>

StarTracksSelfSizeToContentInMeasure

HGC opts into Star-as-content sizing during MEASURE (see StarTracksSelfSizeToContentInMeasure): a flex (Star) column/row reports its CONTENT size as the grid's desired size, then ARRANGE distributes Star across the real allocation. This reproduces the retired HorizontalLayout's measure/arrange split: a content-tight parent (the window root for a Left/Center/Right grid, or any parent that measures unbounded) packs the grid to content; a parent that hands the grid a wider box (a ScrollablePanel, a Stretch slot) lets the flex columns fan out.

protected override bool StarTracksSelfSizeToContentInMeasure { get; }

Property Value

bool

VerticalAlignment

Gets or sets the vertical alignment of the control within its container.

public override VerticalAlignment VerticalAlignment { get; set; }

Property Value

VerticalAlignment

Visible

Gets or sets whether this control is visible.

public override bool Visible { get; set; }

Property Value

bool

Width

Gets or sets the explicit width of the control, or null for automatic sizing.

public override int? Width { get; set; }

Property Value

int?

Methods

AddColumn(ColumnContainer)

Adds a column to the grid.

public void AddColumn(ColumnContainer column)

Parameters

column ColumnContainer

The column container to add.

AddColumnWithSplitter(ColumnContainer)

Adds a column to the grid and automatically creates a splitter before it. Convenience method - equivalent to calling AddSplitter() then AddColumn(). If this is the first column, no splitter is added.

public SplitterControl? AddColumnWithSplitter(ColumnContainer column)

Parameters

column ColumnContainer

The column container to add.

Returns

SplitterControl

The created splitter control, or null if this is the first column.

Examples

var grid = new HorizontalGridControl();
grid.AddColumn(column1);  // First column - no splitter
grid.AddColumnWithSplitter(column2); // Adds splitter between column1 and column2
grid.AddColumnWithSplitter(column3); // Adds splitter between column2 and column3

AddSplitter(int, SplitterControl)

Adds a splitter control between two adjacent columns.

public bool AddSplitter(int leftColumnIndex, SplitterControl splitterControl)

Parameters

leftColumnIndex int

The index of the column to the left of the splitter.

splitterControl SplitterControl

The splitter control to add.

Returns

bool

True if the splitter was added successfully; false if the column index is invalid.

AddSplitterAfter(ColumnContainer, SplitterControl?)

Adds a splitter after the specified column. More intuitive than AddSplitter(index) - you specify the column, not an index.

public bool AddSplitterAfter(ColumnContainer column, SplitterControl? splitter = null)

Parameters

column ColumnContainer

The column after which to add the splitter.

splitter SplitterControl

The splitter control to add. If null, a new SplitterControl is created.

Returns

bool

True if the splitter was added successfully; false if the column is not found or is the last column.

Examples

var col1 = new ColumnContainer(grid);
grid.AddColumn(col1);
var col2 = new ColumnContainer(grid);
grid.AddColumn(col2);
grid.AddSplitterAfter(col1); // Adds splitter between col1 and col2

AddSplitterBefore(ColumnContainer, SplitterControl?)

Adds a splitter before the specified column. More intuitive than AddSplitter(index) - you specify the column, not an index.

public bool AddSplitterBefore(ColumnContainer column, SplitterControl? splitter = null)

Parameters

column ColumnContainer

The column before which to add the splitter.

splitter SplitterControl

The splitter control to add. If null, a new SplitterControl is created.

Returns

bool

True if the splitter was added successfully; false if the column is not found or is the first column.

Examples

var col1 = new ColumnContainer(grid);
grid.AddColumn(col1);
var col2 = new ColumnContainer(grid);
grid.AddColumn(col2);
grid.AddSplitterBefore(col2); // Adds splitter between col1 and col2

AnimateColumnWidth(int, int, TimeSpan, EasingFunction?)

Animates a column's width from its current value to targetWidth over the specified duration using an integer tween.

public IAnimation? AnimateColumnWidth(int columnIndex, int targetWidth, TimeSpan duration, EasingFunction? easing = null)

Parameters

columnIndex int

Zero-based index of the column to animate.

targetWidth int

The desired final width.

duration TimeSpan

How long the transition should take.

easing EasingFunction

Easing function. Defaults to EaseOut(double).

Returns

IAnimation

An IAnimation handle for the running animation, or null if the column index is invalid or no AnimationManager is available (in which case the width is set immediately).

ButtonRow(params ButtonControl[])

Creates a horizontal grid with buttons, commonly used for dialog button rows. Each button is automatically wrapped in a column.

public static HorizontalGridControl ButtonRow(params ButtonControl[] buttons)

Parameters

buttons ButtonControl[]

The buttons to add to the grid.

Returns

HorizontalGridControl

A new HorizontalGridControl containing the buttons, centered horizontally.

ButtonRow(IEnumerable<ButtonControl>, HorizontalAlignment)

Creates a horizontal grid with buttons. Each button is automatically wrapped in a column.

public static HorizontalGridControl ButtonRow(IEnumerable<ButtonControl> buttons, HorizontalAlignment alignment = HorizontalAlignment.Center)

Parameters

buttons IEnumerable<ButtonControl>

The buttons to add to the grid.

alignment HorizontalAlignment

The horizontal alignment of the grid.

Returns

HorizontalGridControl

A new HorizontalGridControl containing the buttons.

ClearColumns()

Removes all columns and splitters from the grid.

public void ClearColumns()

Create()

Creates a fluent builder for constructing a HorizontalGridControl. Provides a concise, chainable API for complex grid layouts.

public static HorizontalGridBuilder Create()

Returns

HorizontalGridBuilder

A new HorizontalGridBuilder instance.

Examples

var grid = HorizontalGridControl.Create()
    .Column(col => col.Width(48).Add(control1))
    .Column(col => col.Flex(2.0).Add(control2))
    .WithSplitterAfter(0)
    .WithAlignment(HorizontalAlignment.Stretch)
    .Build();

FromControls(params IWindowControl[])

Creates a horizontal grid from controls using params syntax. Each control is automatically wrapped in a column.

public static HorizontalGridControl FromControls(params IWindowControl[] controls)

Parameters

controls IWindowControl[]

The controls to add to the grid.

Returns

HorizontalGridControl

A new HorizontalGridControl containing the controls.

FromControls(IEnumerable<IWindowControl>, HorizontalAlignment)

Creates a horizontal grid with arbitrary controls. Each control is automatically wrapped in a column.

public static HorizontalGridControl FromControls(IEnumerable<IWindowControl> controls, HorizontalAlignment alignment = HorizontalAlignment.Left)

Parameters

controls IEnumerable<IWindowControl>

The controls to add to the grid.

alignment HorizontalAlignment

The horizontal alignment of the grid.

Returns

HorizontalGridControl

A new HorizontalGridControl containing the controls.

GetChildren()

Gets the children of this container for Tab navigation traversal. Required by IContainerControl interface.

public IReadOnlyList<IWindowControl> GetChildren()

Returns

IReadOnlyList<IWindowControl>

GetFocusableChildren()

Builds the flat, ordered list of focusable controls for Tab navigation. ColumnContainers are transparent (CanReceiveFocus=false) — their focusable children are promoted into the list. SplitterControls are leaf focusable Tab stops. Ordering: [col0 focusables..., splitter0, col1 focusables..., splitter1, col2 focusables..., ...]

protected override List<IFocusableControl> GetFocusableChildren()

Returns

List<IFocusableControl>

GetFocusedChildFromCoordinator()

Gets the currently focused child using FocusManager. Returns null if no child is focused. Uses FocusPath for ancestry detection to correctly handle nested scopes.

protected override IInteractiveControl? GetFocusedChildFromCoordinator()

Returns

IInteractiveControl

Remarks

OVERRIDE (kept in Task 6): HGC's columns are transparent ColumnContainer cell children, and FocusManager collapses a column out of the focus path (a column never appears in it). GridControl's base coordinator only matches a cell child that is itself focused or present in the path, so it cannot attribute a focused column-content to its column. This override walks HGC's column model directly to find the focused leaf, which the inherited ProcessKey / cursor / Tab logic then route through correctly.

GetInitialFocus(bool)

Returns the first child to focus when Tab enters this scope. backward=true means Shift+Tab entered from the right — return last child.

public override IFocusableControl? GetInitialFocus(bool backward)

Parameters

backward bool

Returns

IFocusableControl

Remarks

Returns the first focusable cell child in Tab order (row-major), or the last when backward is true. For forward re-entry, honours SavedFocus so focus resumes where it left off — unless using it would skip a nested focus-scope cell that appears earlier in Tab order, in which case the saved value is discarded. The grid has no scroll mode, so there is no self-sentinel branch.

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.

GetLogicalCursorPosition()

Gets the logical cursor position within the control's content coordinate system. This should be the raw position without any visual adjustments for margins, scrolling, etc.

public override Point? GetLogicalCursorPosition()

Returns

Point?

Logical cursor position or null if no cursor.

Remarks

Returns the focused cell child's cursor translated into the grid's own coordinate space by adding that child's cell origin (the child node's top-left relative to the grid's top-left). There is no scroll offset to subtract and no viewport to clip against, so this is a plain translation. Returns null when no cell child is focused or the child reports no cursor.

GetNextFocus(IFocusableControl, bool)

Returns the next child to focus after Tab from 'current'. Returns null when Tab should exit this scope.

public override IFocusableControl? GetNextFocus(IFocusableControl current, bool backward)

Parameters

current IFocusableControl
backward bool

Returns

IFocusableControl

GetSplitterLeftColumnIndex(SplitterControl)

Gets the index of the column to the left of the specified splitter.

public int GetSplitterLeftColumnIndex(SplitterControl splitter)

Parameters

splitter SplitterControl

The splitter to look up.

Returns

int

The index of the left column, or -1 if not found.

Invalidate(Invalidation)

Marks this control as needing the specified work on the next frame.

public void Invalidate(Invalidation work)

Parameters

work Invalidation

Repaint (appearance-only) or Relayout (size/position-affecting).

MeasureDOM(LayoutConstraints)

Content-summing measure for callers that invoke HorizontalGridControl.MeasureDOM DIRECTLY as a sizing helper — most notably NavigationView, which calls _grid.MeasureDOM(...).Height to size its content area. This is NOT the render-path measure: when the grid is wired into the layout tree it has a GridLayout and children, so Measure(LayoutConstraints) uses GridLayout.MeasureChildren and never calls this method (it is only reached for a Layout-less/childless node). Returning the column content sum here preserves the natural-size contract those direct callers relied on under the old HorizontalLayout path, while the actual rendering still flows through GridLayout.

public override LayoutSize MeasureDOM(LayoutConstraints constraints)

Parameters

constraints LayoutConstraints

Returns

LayoutSize

OnDisposing()

Disposes the grid's child controls so their own cleanup (event unsubscription, resource release) runs. Child Dispose() is idempotent, so this is safe even if a child is shared or already disposed.

protected override void OnDisposing()

ProcessKey(ConsoleKeyInfo)

Processes a keyboard input event.

public override 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.

Remarks

OVERRIDE (kept in Task 6): HGC delegates a non-Tab key to the focused column child via its own column-walking GetFocusedChildFromCoordinator() (the inherited Grid coordinator cannot see a focused control nested inside a transparent ColumnContainer because FocusManager collapses the column out of the focus path). Tab/Shift+Tab then advance through HGC's column-ordered focusable list (the overridden GetNextFocus/GetInitialFocus).

RemoveColumn(ColumnContainer)

Removes a column from the grid along with any associated splitters.

public void RemoveColumn(ColumnContainer column)

Parameters

column ColumnContainer

The column container to remove.

SetLogicalCursorPosition(Point)

Sets the logical cursor position within the control's content coordinate system.

public override void SetLogicalCursorPosition(Point position)

Parameters

position Point

Remarks

The inverse of GetLogicalCursorPosition(): removes the cell origin and forwards the child-relative position to the focused cell child.

Edit this page