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 : IInteractiveControl, IFocusableControl, ILogicalCursorProvider, IMouseAwareControl, IWindowControl, IDisposable, ICursorShapeProvider, IDirectionalFocusControl, IDOMPaintable

Inheritance

object

HorizontalGridControl

Implements

IInteractiveControl

IFocusableControl

ILogicalCursorProvider

IMouseAwareControl

IWindowControl

IDisposable

ICursorShapeProvider

IDirectionalFocusControl

IDOMPaintable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

WindowControlExtensions.NotifyParentWindowOfFocusChange(IFocusableControl, bool)

WindowControlExtensions.GetParentWindow(IWindowControl)

Constructors

HorizontalGridControl()

Initializes a new instance of the HorizontalGridControl class.

public HorizontalGridControl()

Properties

ActualWidth

Gets the actual rendered width of the control, or null if not yet rendered.

public int? ActualWidth { get; }

Property Value

int?

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 IContainer? Container { get; set; }

Property Value

IContainer

ForegroundColor

public Color? ForegroundColor { get; set; }

Property Value

Color?

HasFocus

Gets or sets whether this control currently has keyboard focus.

public bool HasFocus { get; set; }

Property Value

bool

HorizontalAlignment

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

public 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

Margin

Gets or sets the margin (spacing) around the control.

public Margin Margin { get; set; }

Property Value

Margin

Name

Gets or sets the unique name identifier for this control, used for lookup.

public string? Name { get; set; }

Property Value

string

PreferredCursorShape

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

public CursorShape? PreferredCursorShape { get; }

Property Value

CursorShape?

Splitters

Gets the list of splitters in this grid.

public IReadOnlyList<SplitterControl> Splitters { get; }

Property Value

IReadOnlyList<SplitterControl>

StickyPosition

Gets or sets whether this control should stick to the top or bottom during scrolling.

public StickyPosition StickyPosition { get; set; }

Property Value

StickyPosition

Tag

Gets or sets an arbitrary object value that can be used to store custom data.

public object? Tag { get; set; }

Property Value

object

VerticalAlignment

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

public VerticalAlignment VerticalAlignment { get; set; }

Property Value

VerticalAlignment

Visible

Gets or sets whether this control is visible.

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

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

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.

GetLogicalContentSize()

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

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

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

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

Paints the control's content directly to a CharacterBuffer.

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

SetFocus(bool, FocusReason)

Sets focus to this control

public void SetFocus(bool focus, FocusReason reason = FocusReason.Programmatic)

Parameters

focus bool

Whether to give or remove focus

reason FocusReason

The reason for the focus change

SetFocusWithDirection(bool, bool)

Sets focus with direction information for proper child control selection.

public void SetFocusWithDirection(bool focus, bool backward)

Parameters

focus bool

Whether to set or remove focus.

backward bool

If true, focus last child; if false, focus first child.

SetLogicalCursorPosition(Point)

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

public void SetLogicalCursorPosition(Point position)

Parameters

position Point

Events

GotFocus

Event fired when the control gains focus

public event EventHandler? GotFocus

Event Type

EventHandler

LostFocus

Event fired when the control loses focus

public event EventHandler? LostFocus

Event Type

EventHandler

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>