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 uses HorizontalLayout internally for measuring and arranging columns. The layout algorithm is assigned automatically by Window.cs during tree building. Users don't interact with HorizontalLayout directly.

public class HorizontalGridControl : BaseControl, IDOMPaintable, INotifyPropertyChanged, IInteractiveControl, IFocusableControl, ILogicalCursorProvider, IMouseAwareControl, IWindowControl, IDisposable, ICursorShapeProvider, IContainerControl, IFocusScope

Inheritance

object

BaseControl

HorizontalGridControl

Implements

IDOMPaintable

INotifyPropertyChanged

IInteractiveControl

IFocusableControl

ILogicalCursorProvider

IMouseAwareControl

IWindowControl

IDisposable

ICursorShapeProvider

IContainerControl

IFocusScope

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.Margin

BaseControl.StickyPosition

BaseControl.Name

BaseControl.Tag

BaseControl.Height

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

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>)

WindowControlExtensions.RequestFocus(IFocusableControl, FocusReason)

WindowControlExtensions.GetParentWindow(IWindowControl)

WindowControlExtensions.GetPortalAncestor(IWindowControl)

Constructors

HorizontalGridControl()

Initializes a new instance of the HorizontalGridControl class.

public HorizontalGridControl()

Properties

BackgroundColor

public Color? BackgroundColor { get; set; }

Property Value

Color?

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

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?

FocusedContent

Gets the currently focused child control within the grid.

public IInteractiveControl? FocusedContent { get; }

Property Value

IInteractiveControl

ForegroundColor

public Color? ForegroundColor { get; set; }

Property Value

Color?

HasFocus

public bool HasFocus { get; }

Property Value

bool

HorizontalAlignment

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

public override HorizontalAlignment HorizontalAlignment { get; set; }

Property Value

HorizontalAlignment

IsEnabled

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

public bool IsEnabled { get; set; }

Property Value

bool

PreferredCursorShape

Gets the preferred cursor shape for this control. Return null to use the default cursor shape.

public CursorShape? PreferredCursorShape { get; }

Property Value

CursorShape?

SavedFocus

Saved focus position. FocusManager sets this before exiting the scope (if scope opts in). GetInitialFocus should return this when set, then clear it.

public IFocusableControl? SavedFocus { get; set; }

Property Value

IFocusableControl

Remarks

HorizontalGridControl does not restore a saved focus position when re-entered. This property is required by the IFocusScope interface but is intentionally ignored by GetInitialFocus(bool). The grid always returns the first or last focusable child based on the backward parameter.

Splitters

Gets the list of splitters in this grid.

public IReadOnlyList<SplitterControl> Splitters { get; }

Property Value

IReadOnlyList<SplitterControl>

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

WantsMouseEvents

Whether this control wants to receive mouse events

public bool WantsMouseEvents { get; }

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

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>

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 IFocusableControl? GetInitialFocus(bool backward)

Parameters

backward bool

Returns

IFocusableControl

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 Point? GetLogicalCursorPosition()

Returns

Point?

Logical cursor position or null if no cursor.

GetNextFocus(IFocusableControl, bool)

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

public 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()

Marks this control as needing to be re-rendered.

public void Invalidate()

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.

Remarks

This method measures content-based size (sum of actual child sizes), consistent with how HorizontalLayout.MeasureChildren works in the DOM system. Space distribution happens during arrangement, not measurement.

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(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 void SetLogicalCursorPosition(Point position)

Parameters

position Point

Events

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>