Skip to content

Commit 510f09d

Browse files
nickprotopnickprotop
committed
Add ToolbarControl and StatusBarControl documentation
1 parent 95d1027 commit 510f09d

4 files changed

Lines changed: 612 additions & 1 deletion

File tree

‎docs/CONTROLS.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,8 @@ Controls for organizing other controls.
8787
| **SplitterControl** | Resizable divider | Drag to resize adjacent columns |
8888
| **[TabControl](controls/TabControl.md)** | Multi-page tab container | Tab headers, keyboard/mouse switching, state preservation |
8989
| **[NavigationView](controls/NavigationView.md)** | Sidebar navigation + content area | WinUI-inspired nav pane, content factories, gradient-transparent |
90-
| **ToolbarControl** | Horizontal button toolbar | Quick access buttons, separators |
90+
| **[ToolbarControl](controls/ToolbarControl.md)** | Horizontal button toolbar | Auto-height, wrapping, separator lines, content padding, Tab navigation |
91+
| **[StatusBarControl](controls/StatusBarControl.md)** | Three-zone status bar | Left/center/right zones, clickable items, shortcut hints, above line separator |
9192
| **SeparatorControl** | Visual separator | Simple horizontal line |
9293
| **PortalContentContainer** | Portal overlay container | Host child controls in [portal overlays](PORTAL_SYSTEM.md), mouse/keyboard routing, focus tracking |
9394

@@ -302,6 +303,10 @@ Browse detailed documentation for specific controls:
302303
- [DatePickerControl](controls/DatePickerControl.md) - Date picker with calendar popup
303304
- [TimePickerControl](controls/TimePickerControl.md) - Time picker with 12h/24h modes
304305

306+
### Layout & Status Controls
307+
- [ToolbarControl](controls/ToolbarControl.md) - Horizontal button toolbar with wrapping
308+
- [StatusBarControl](controls/StatusBarControl.md) - Three-zone status bar with clickable items
309+
305310
### Advanced Controls
306311
- [TableControl](controls/TableControl.md) - Interactive data grid with virtual data
307312
- [TabControl](controls/TabControl.md) - Multi-page tab container

‎docs/STATUS_SYSTEM.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ The status system provides:
2323
- **Top Status Bar**: Application title, branding, performance metrics
2424
- **Bottom Status Bar**: Status messages, window list, Start button
2525
- **Window Task Bar**: Quick access to open windows (Alt+1-9)
26+
27+
> **Note:** For the in-window `StatusBarControl` (three-zone bar with clickable items and shortcut hints), see the [StatusBarControl documentation](controls/StatusBarControl.md).
2628
- **Start Menu**: Centralized access to actions, windows, and system features
2729

2830
## Status Bars

‎docs/controls/StatusBarControl.md‎

Lines changed: 277 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,277 @@
1+
# StatusBarControl
2+
3+
Single-row status bar with three alignment zones, clickable items, and shortcut key hints.
4+
5+
## Overview
6+
7+
`StatusBarControl` renders a horizontal bar with left, center, and right zones for displaying status information, keyboard shortcuts, and clickable items. Items consist of an optional shortcut hint (rendered with an accent color) and a label. The control does not receive keyboard focus — it is display and click only.
8+
9+
By default the status bar sticks to the bottom of the window (`StickyPosition.Bottom`). An optional horizontal separator line can be rendered above the content.
10+
11+
See also: [ToolbarControl](ToolbarControl.md) — for interactive button toolbars
12+
13+
## Quick Start
14+
15+
```csharp
16+
var statusBar = Controls.StatusBar()
17+
.AddLeft("↑↓", "Navigate")
18+
.AddLeft("Enter", "Select")
19+
.AddLeftSeparator()
20+
.AddLeft("Esc", "Exit")
21+
.AddCenterText("[dim]My Application[/]")
22+
.AddRight("Ctrl+S", "Save")
23+
.WithAboveLine()
24+
.WithBackgroundColor(Color.Grey15)
25+
.WithShortcutForegroundColor(Color.Cyan1)
26+
.StickyBottom()
27+
.Build();
28+
29+
window.AddControl(statusBar);
30+
```
31+
32+
## Builder API
33+
34+
Create a `StatusBarBuilder` through the `Controls` factory:
35+
36+
```csharp
37+
var builder = Controls.StatusBar();
38+
```
39+
40+
### Adding Items
41+
42+
Items can be added to three zones. Each method returns the builder for chaining.
43+
44+
```csharp
45+
// Left zone
46+
.AddLeft(string shortcut, string label, Action? onClick = null)
47+
.AddLeftText(string text, Action? onClick = null)
48+
.AddLeft(StatusBarItem item)
49+
.AddLeftSeparator()
50+
51+
// Center zone
52+
.AddCenter(string shortcut, string label, Action? onClick = null)
53+
.AddCenterText(string text, Action? onClick = null)
54+
.AddCenter(StatusBarItem item)
55+
.AddCenterSeparator()
56+
57+
// Right zone
58+
.AddRight(string shortcut, string label, Action? onClick = null)
59+
.AddRightText(string text, Action? onClick = null)
60+
.AddRight(StatusBarItem item)
61+
.AddRightSeparator()
62+
```
63+
64+
### Style Methods
65+
66+
```csharp
67+
.WithBackgroundColor(Color color) // Status bar background
68+
.WithForegroundColor(Color color) // Label text color
69+
.WithShortcutForegroundColor(Color color) // Shortcut hint accent color
70+
.WithAboveLine(bool show = true) // Horizontal separator line above content
71+
.WithAboveLineColor(Color color) // Separator line color (also enables line)
72+
.WithItemSpacing(int spacing) // Space between items (default: 2)
73+
.WithSeparatorChar(string separator) // Section separator character (default: "|")
74+
.WithShortcutLabelSeparator(string sep) // Shortcut-label separator (default: ":")
75+
```
76+
77+
### Layout Methods
78+
79+
```csharp
80+
.WithMargin(int left, int top, int right, int bottom)
81+
.WithMargin(int margin)
82+
.WithMargin(Margin margin)
83+
.WithAlignment(HorizontalAlignment align)
84+
.WithStickyPosition(StickyPosition pos)
85+
.StickyTop()
86+
.StickyBottom()
87+
```
88+
89+
### Identity Methods
90+
91+
```csharp
92+
.WithName(string name)
93+
.WithTag(object tag)
94+
```
95+
96+
### Event Methods
97+
98+
```csharp
99+
.OnItemClicked(EventHandler<StatusBarItemClickedEventArgs> handler)
100+
```
101+
102+
### Building
103+
104+
```csharp
105+
StatusBarControl control = builder.Build();
106+
107+
// Implicit conversion is also supported:
108+
StatusBarControl control = Controls.StatusBar()
109+
.AddLeft("Esc", "Close");
110+
```
111+
112+
## Properties
113+
114+
| Property | Type | Default | Description |
115+
|----------|------|---------|-------------|
116+
| `BackgroundColor` | `Color` | theme/container | Status bar background color |
117+
| `ForegroundColor` | `Color` | theme/container | Label text color |
118+
| `ShortcutForegroundColor` | `Color` | theme/Cyan1 | Accent color for shortcut hints |
119+
| `ItemSpacing` | `int` | `2` | Space between adjacent items |
120+
| `SeparatorChar` | `string` | `"\|"` | Character rendered for separator items |
121+
| `ShortcutLabelSeparator` | `string` | `":"` | Text between shortcut and label (e.g. "Ctrl+S:Save") |
122+
| `ShowAboveLine` | `bool` | `false` | Render horizontal line above content |
123+
| `AboveLineColor` | `Color?` | `null` | Line color (null uses foreground) |
124+
| `LeftItems` | `IReadOnlyList<StatusBarItem>` | — | Items in the left zone |
125+
| `CenterItems` | `IReadOnlyList<StatusBarItem>` | — | Items in the center zone |
126+
| `RightItems` | `IReadOnlyList<StatusBarItem>` | — | Items in the right zone |
127+
128+
## StatusBarItem Properties
129+
130+
Each item in the status bar is a `StatusBarItem` with these properties:
131+
132+
| Property | Type | Default | Description |
133+
|----------|------|---------|-------------|
134+
| `Shortcut` | `string?` | `null` | Key hint text rendered with accent color |
135+
| `Label` | `string` | `""` | Label text (supports markup) |
136+
| `IsVisible` | `bool` | `true` | Whether the item is rendered |
137+
| `IsSeparator` | `bool` | `false` | Render as separator character |
138+
| `OnClick` | `Action?` | `null` | Click handler for this item |
139+
| `ShortcutForeground` | `Color?` | `null` | Override shortcut color for this item |
140+
| `ShortcutBackground` | `Color?` | `null` | Override shortcut background for this item |
141+
| `LabelForeground` | `Color?` | `null` | Override label color for this item |
142+
| `LabelBackground` | `Color?` | `null` | Override label background for this item |
143+
144+
## Events
145+
146+
| Event | Arguments | Description |
147+
|-------|-----------|-------------|
148+
| `ItemClicked` | `StatusBarItemClickedEventArgs` | Fired when any non-separator item is clicked |
149+
| `MouseClick` | `MouseEventArgs` | Fired on any mouse click on the status bar |
150+
151+
## Mouse Interaction
152+
153+
- **Click on an item** fires the item's `OnClick` handler and the `ItemClicked` event
154+
- **Click on a separator** has no effect
155+
- The status bar does not receive keyboard focus
156+
157+
## Dynamic Updates
158+
159+
Items can be modified at runtime. Changes trigger automatic re-rendering.
160+
161+
```csharp
162+
// Update an item's text
163+
var counterItem = statusBar.RightItems[0];
164+
counterItem.Label = "[yellow]5 outdated[/]";
165+
166+
// Add items at runtime
167+
statusBar.AddLeft("F5", "Refresh");
168+
169+
// Remove items
170+
var items = statusBar.LeftItems;
171+
if (items.Count > 0)
172+
statusBar.RemoveLeft(items[items.Count - 1]);
173+
174+
// Batch updates for performance
175+
statusBar.BatchUpdate(() =>
176+
{
177+
statusBar.AddLeft("A", "Action1");
178+
statusBar.AddLeft("B", "Action2");
179+
statusBar.AddLeft("C", "Action3");
180+
});
181+
```
182+
183+
## Examples
184+
185+
### Application Status Bar
186+
187+
```csharp
188+
var statusBar = Controls.StatusBar()
189+
.AddLeft("↑↓", "Navigate")
190+
.AddLeft("Enter", "View")
191+
.AddLeftSeparator()
192+
.AddLeft("Esc", "Exit")
193+
.AddCenterText("[dim]StatusBar Demo[/]")
194+
.AddRightText("[yellow]3 outdated[/]")
195+
.AddRight("Ctrl+S", "Search")
196+
.WithAboveLine()
197+
.WithBackgroundColor(Color.Grey15)
198+
.WithShortcutForegroundColor(Color.Cyan1)
199+
.StickyBottom()
200+
.Build();
201+
```
202+
203+
### Status Bar with Click Handlers
204+
205+
```csharp
206+
var statusBar = Controls.StatusBar()
207+
.AddLeft("F5", "Refresh", () => RefreshData())
208+
.AddLeft("F2", "Edit", () => StartEditing())
209+
.AddRight("Ctrl+Q", "Quit", () => windowSystem.Stop())
210+
.OnItemClicked((sender, args) =>
211+
{
212+
var display = args.Item.Shortcut != null
213+
? $"{args.Item.Shortcut}:{args.Item.Label}"
214+
: args.Item.Label;
215+
// Log which item was clicked
216+
})
217+
.StickyBottom()
218+
.Build();
219+
```
220+
221+
### Status Bar at Top
222+
223+
```csharp
224+
var topBar = Controls.StatusBar()
225+
.AddLeftText("[bold cyan]My App[/]")
226+
.AddRightText($"[dim]v{version}[/]")
227+
.StickyTop()
228+
.WithBackgroundColor(Color.Grey11)
229+
.Build();
230+
```
231+
232+
### Per-Item Color Overrides
233+
234+
```csharp
235+
var errorItem = new StatusBarItem
236+
{
237+
Label = "3 errors",
238+
LabelForeground = Color.Red,
239+
OnClick = () => ShowErrors()
240+
};
241+
242+
var statusBar = Controls.StatusBar()
243+
.AddRight(errorItem)
244+
.StickyBottom()
245+
.Build();
246+
```
247+
248+
### Toggling Item Visibility
249+
250+
```csharp
251+
bool centerVisible = true;
252+
toggleBtn.Click += (_, _) =>
253+
{
254+
centerVisible = !centerVisible;
255+
var centerItems = statusBar.CenterItems;
256+
if (centerItems.Count > 0)
257+
centerItems[0].IsVisible = centerVisible;
258+
};
259+
```
260+
261+
## Best Practices
262+
263+
1. **Use shortcut+label pairs** for keyboard-driven items — the accent color makes shortcuts discoverable
264+
2. **Use `AddLeftText`/`AddCenterText`/`AddRightText`** for display-only items without keyboard hints
265+
3. **Batch updates** when adding multiple items at once to avoid redundant re-renders
266+
4. **Use markup in labels** for dynamic coloring (e.g. `[yellow]3 warnings[/]`)
267+
5. **Stick to bottom** (default) for traditional status bars; use `StickyTop()` for header bars
268+
6. **Enable `WithAboveLine()`** to visually separate the status bar from content above
269+
270+
## See Also
271+
272+
- [ToolbarControl](ToolbarControl.md) - Interactive button toolbar with wrapping
273+
- [Status System](../STATUS_SYSTEM.md) - System-level status bars and taskbar
274+
275+
---
276+
277+
[Back to Controls](../CONTROLS.md) | [Back to Main Documentation](../../README.md)

0 commit comments

Comments
 (0)