ToolbarControl

March 15, 2026 · View on GitHub

Horizontal toolbar with buttons, separators, and other controls. Supports wrapping, auto-height, separator lines, and content padding.

Overview

ToolbarControl arranges child controls (typically buttons) in a horizontal strip. When wrapping is enabled, items that exceed the available width flow to the next row. Each row auto-sizes to the height of its tallest item, allowing bordered buttons and plain controls to coexist naturally.

Separator lines can be rendered above and/or below the toolbar content, and inner content padding offsets items from the toolbar edges. Tab and arrow key navigation moves focus between items.

See also: StatusBarControl — for non-focusable status display

Quick Start

var toolbar = Controls.Toolbar()
    .AddButton("New", (s, btn) => CreateNew())
    .AddButton("Open", (s, btn) => OpenFile())
    .AddButton("Save", (s, btn) => SaveFile())
    .AddSeparator()
    .AddButton("Settings", (s, btn) => ShowSettings())
    .WithSpacing(1)
    .WithBackgroundColor(Color.Grey11)
    .WithBelowLine()
    .StickyTop()
    .Build();

window.AddControl(toolbar);

Builder API

Create a ToolbarBuilder through the Controls factory:

var builder = Controls.Toolbar();

Adding Items

.AddButton(string text, EventHandler<ButtonControl> onClick)
.AddButton(string text, WindowEventHandler<ButtonControl> onClick)
.AddButton(ButtonBuilder builder)
.AddButton(ButtonControl button)
.AddSeparator()
.AddSeparator(int horizontalMargin)
.Add(IWindowControl control)                // Add any control

Spacing and Layout

.WithSpacing(int spacing)                   // Space between items (default: 0)
.WithWrap(bool wrap = true)                 // Enable item wrapping to next row
.WithHeight(int height)                     // Fixed row height (default: auto)
.WithWidth(int width)                       // Fixed width

Separator Lines

.WithAboveLine(bool show = true)            // Horizontal line above content
.WithBelowLine(bool show = true)            // Horizontal line below content
.WithAboveLineColor(Color color)            // Line color (also enables line)
.WithBelowLineColor(Color color)            // Line color (also enables line)

Content Padding

.WithContentPadding(int left, int top, int right, int bottom)
.WithContentPadding(int horizontal, int vertical)
.WithContentPadding(int all)

Style

.WithBackgroundColor(Color? color)          // Toolbar background (null = inherit)
.WithForegroundColor(Color? color)          // Toolbar foreground (null = inherit)

Layout and Position

.WithMargin(int left, int top, int right, int bottom)
.WithMargin(int margin)
.WithMargin(Margin margin)
.WithAlignment(HorizontalAlignment alignment)
.WithVerticalAlignment(VerticalAlignment alignment)
.WithStickyPosition(StickyPosition position)
.StickyTop()
.StickyBottom()

Identity

.WithName(string name)
.WithTag(object tag)
.Visible(bool visible)

Events

.OnGotFocus(EventHandler handler)
.OnGotFocus(WindowEventHandler<EventArgs> handler)
.OnLostFocus(EventHandler handler)
.OnLostFocus(WindowEventHandler<EventArgs> handler)

Building

ToolbarControl control = builder.Build();

// Implicit conversion is also supported:
ToolbarControl control = Controls.Toolbar()
    .AddButton("OK", (s, btn) => { });

Properties

Property	Type	Default	Description
`BackgroundColor`	`Color`	theme/container	Toolbar background color
`ForegroundColor`	`Color`	theme/container	Toolbar foreground color
`ItemSpacing`	`int`	`0`	Space between items in characters
`Wrap`	`bool`	`false`	Wrap items to next row when they exceed available width
`Height`	`int?`	`null`	Fixed row height (null = auto-size from tallest item)
`ShowAboveLine`	`bool`	`false`	Render horizontal separator line above content
`ShowBelowLine`	`bool`	`false`	Render horizontal separator line below content
`AboveLineColor`	`Color?`	`null`	Above line color (null uses foreground)
`BelowLineColor`	`Color?`	`null`	Below line color (null uses foreground)
`ContentPadding`	`Padding`	`(0,0,0,0)`	Inner padding between toolbar edge and items
`IsEnabled`	`bool`	`true`	Enable/disable all toolbar interaction
`Items`	`IReadOnlyList<IWindowControl>`	—	The toolbar's child controls

Events

Event	Arguments	Description
`GotFocus`	`EventArgs`	Fired when the toolbar receives focus
`LostFocus`	`EventArgs`	Fired when the toolbar loses focus
`MouseClick`	`MouseEventArgs`	Fired when the toolbar area is clicked

Keyboard Support

Key	Action
Tab	Move focus to next item
Shift+Tab	Move focus to previous item
Left Arrow	Move focus to previous item
Right Arrow	Move focus to next item
Up Arrow	Move focus to item above (wrapping mode)
Down Arrow	Move focus to item below (wrapping mode)
Enter/Space	Activate focused item (e.g. click button)

Mouse Support

Action	Result
Click on item	Focus and activate the item
Right-click	Fires `MouseRightClick` event

Auto-Height

When Height is null (default), each row sizes to its tallest item. This means bordered buttons (height 3) and plain buttons (height 1) coexist — plain items are vertically aligned within the taller row.

var toolbar = Controls.Toolbar()
    .AddButton(Controls.Button()
        .WithText("  Compile  ")
        .WithBorder(ButtonBorderStyle.Rounded)
        .OnClick((s, btn) => Compile()))
    .AddButton("Cancel", (s, btn) => Cancel())  // plain, height 1
    .WithSpacing(1)
    .Build();
// Row auto-sizes to height 3 from the bordered button
// "Cancel" is vertically aligned within the row

Control vertical alignment within a row:

var label = new MarkupControl(new List<string> { "[dim]Ready[/]" })
{
    VerticalAlignment = VerticalAlignment.Center  // Center in row
};
toolbar.AddItem(label);

Examples

var toolbar = Controls.Toolbar()
    .AddButton("New", (s, btn) => NewFile())
    .AddButton("Open", (s, btn) => OpenFile())
    .AddButton("Save", (s, btn) => SaveFile())
    .WithSpacing(1)
    .WithBackgroundColor(Color.Grey11)
    .WithBelowLine()
    .StickyTop()
    .Build();

Bordered Buttons with Full Polish

var toolbar = Controls.Toolbar()
    .AddButton(Controls.Button()
        .WithText("  Compile  ")
        .WithBorder(ButtonBorderStyle.Rounded)
        .OnClick((s, btn) => Compile()))
    .AddButton(Controls.Button()
        .WithText("  Run  ")
        .WithBorder(ButtonBorderStyle.Rounded)
        .OnClick((s, btn) => Run()))
    .AddButton(Controls.Button()
        .WithText("  Debug  ")
        .WithBorder(ButtonBorderStyle.Rounded)
        .OnClick((s, btn) => Debug()))
    .WithSpacing(1)
    .WithBackgroundColor(Color.Grey15)
    .WithAboveLine()
    .WithBelowLine()
    .WithContentPadding(1, 0, 1, 0)
    .Build();

var toolbar = Controls.Toolbar()
    .WithSpacing(1)
    .WithWrap()
    .WithBackgroundColor(Color.Grey11)
    .WithAboveLine()
    .WithBelowLine()
    .WithContentPadding(1, 0, 1, 0)
    .WithMargin(0, 1, 0, 0)
    .Build();

toolbar.AddItem(addBtn);
toolbar.AddItem(removeBtn);
toolbar.AddItem(updateBtn);
toolbar.AddItem(toggleBtn);
// Items wrap to next row if they don't fit

Adding Items Dynamically

var toolbar = Controls.Toolbar()
    .WithSpacing(1)
    .Build();

// Add items after creation
toolbar.AddItem(Controls.Button("Action 1")
    .OnClick((s, btn) => DoAction1())
    .Build());

toolbar.AddItem(new SeparatorControl());

toolbar.AddItem(Controls.Button("Action 2")
    .OnClick((s, btn) => DoAction2())
    .Build());

// Remove and clear
toolbar.RemoveItem(someItem);
toolbar.Clear();

Mixed Controls

var toolbar = Controls.Toolbar()
    .WithSpacing(1)
    .WithBackgroundColor(Color.Grey19)
    .WithAboveLine()
    .WithBelowLine()
    .Build();

var borderedBtn = Controls.Button()
    .WithText("  Apply  ")
    .WithBorder(ButtonBorderStyle.Rounded)
    .OnClick((s, btn) => Apply())
    .Build();

var label = new MarkupControl(new List<string> { "[dim]Ready[/]" })
{
    VerticalAlignment = VerticalAlignment.Center
};

var plainBtn = Controls.Button()
    .WithText("Cancel")
    .OnClick((s, btn) => Cancel())
    .Build();
plainBtn.VerticalAlignment = VerticalAlignment.Center;

toolbar.AddItem(borderedBtn);
toolbar.AddItem(label);
toolbar.AddItem(plainBtn);

Best Practices

Use WithSpacing(1) to add visual breathing room between items
Enable WithWrap() when the toolbar may contain many items or the window may be narrow
Use separator lines (WithAboveLine(), WithBelowLine()) to visually separate the toolbar from surrounding content
Use WithContentPadding(1, 0, 1, 0) to offset items from the toolbar edges
Stick to top (StickyTop()) for primary action toolbars
Set VerticalAlignment.Center on plain controls when mixing with bordered buttons