Skip to content

Commit b15a68e

Browse files
nickprotopnickprotop
committed
docs: add Desktop Background guide, update CONFIGURATION, THEMES, GRADIENTS, STATE-SERVICES, README
1 parent 4b2719f commit b15a68e

6 files changed

Lines changed: 318 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -279,6 +279,7 @@ dotnet run --project Examples/DemoApp
279279
| **[State Services](docs/STATE-SERVICES.md)** | Window state, focus, modal, notification services |
280280
| **[Registry](docs/REGISTRY.md)** | Persistent hierarchical key-value storage |
281281
| **[Plugins](docs/PLUGINS.md)** | Plugin architecture and development |
282+
| **[Desktop Background](docs/DESKTOP_BACKGROUND.md)** | Gradient, pattern, and animated desktop backgrounds |
282283
| **[Gradients & Alpha](docs/GRADIENTS.md)** | Gradient text, window backgrounds, transparent control compositing |
283284
| **[Video Playback](docs/VIDEO_PLAYBACK.md)** | Terminal video player — FFmpeg decode, half-block/ASCII/braille modes |
284285
| **[Compositor Effects](docs/COMPOSITOR_EFFECTS.md)** | Buffer manipulation and visual effects |

‎docs/CONFIGURATION.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ Main configuration for the console window system.
4747
| `BottomPanelConfig` | `Func<PanelBuilder, PanelBuilder>?` | `null` | Bottom panel element configuration |
4848
| `ShowTopPanel` | `bool` | `true` | Show/hide top panel |
4949
| `ShowBottomPanel` | `bool` | `true` | Show/hide bottom panel |
50+
| `DesktopBackground` | `DesktopBackgroundConfig?` | `null` | Desktop background (gradient, pattern, animated). See [Desktop Background](DESKTOP_BACKGROUND.md) |
5051

5152
### Computed Properties
5253

@@ -433,6 +434,7 @@ See the [Registry guide](REGISTRY.md) for full documentation.
433434
## See Also
434435

435436
- [Panel System](PANELS.md) - Full panel and element reference
437+
- [Desktop Background](DESKTOP_BACKGROUND.md) - Gradients, patterns, animated backgrounds
436438
- [State Services](STATE-SERVICES.md) - Runtime state management
437439
- [Registry](REGISTRY.md) - Persistent key-value storage
438440
- [Themes](THEMES.md) - Theme system and customization

‎docs/DESKTOP_BACKGROUND.md‎

Lines changed: 287 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,287 @@
1+
# Desktop Background
2+
3+
SharpConsoleUI supports rich desktop backgrounds — the area behind all windows. Backgrounds can be solid colors (from the theme), gradients, repeating patterns, or fully animated via custom paint callbacks.
4+
5+
## Table of Contents
6+
7+
- [Overview](#overview)
8+
- [Configuration](#configuration)
9+
- [Gradient Backgrounds](#gradient-backgrounds)
10+
- [Pattern Backgrounds](#pattern-backgrounds)
11+
- [Combined (Gradient + Pattern)](#combined-gradient--pattern)
12+
- [Animated Backgrounds](#animated-backgrounds)
13+
- [Built-in Effects](#built-in-effects)
14+
- [Custom Paint Callbacks](#custom-paint-callbacks)
15+
- [Theme Integration](#theme-integration)
16+
- [Runtime Changes](#runtime-changes)
17+
18+
## Overview
19+
20+
The desktop background is managed by `DesktopBackgroundService`, which maintains a cached `CharacterBuffer`. The buffer is rendered once and blitted to exposed desktop regions each frame. It is only re-rendered when the configuration changes, the theme changes, the screen resizes, or an animation timer fires.
21+
22+
Three composable layers:
23+
1. **Base fill** — theme character + colors (`DesktopBackgroundChar`, `DesktopBackgroundColor`, `DesktopForegroundColor`)
24+
2. **Gradient overlay** — optional `GradientBackground` applied over the base fill
25+
3. **Pattern overlay** — optional `DesktopPattern` tiled over the gradient/base
26+
27+
When an animated `PaintCallback` is set, it takes full control of the buffer.
28+
29+
## Configuration
30+
31+
Set the desktop background at startup via `ConsoleWindowSystemOptions`:
32+
33+
```csharp
34+
using SharpConsoleUI.Rendering;
35+
36+
var options = new ConsoleWindowSystemOptions(
37+
DesktopBackground: DesktopBackgroundConfig.FromGradient(
38+
ColorGradient.FromColors(new Color(10, 15, 40), new Color(2, 3, 10)),
39+
GradientDirection.Vertical)
40+
);
41+
42+
var windowSystem = new ConsoleWindowSystem(
43+
new NetConsoleDriver(RenderMode.Buffer),
44+
options: options);
45+
```
46+
47+
Or change it at runtime:
48+
49+
```csharp
50+
windowSystem.DesktopBackground = DesktopBackgroundConfig.FromGradient(
51+
ColorGradient.FromColors(Color.DarkBlue, Color.Black),
52+
GradientDirection.Vertical);
53+
```
54+
55+
Setting to `null` reverts to theme defaults:
56+
57+
```csharp
58+
windowSystem.DesktopBackground = null;
59+
```
60+
61+
All changes are applied automatically on the next frame — no manual redraw needed.
62+
63+
## Gradient Backgrounds
64+
65+
Apply a color gradient across the entire desktop area:
66+
67+
```csharp
68+
windowSystem.DesktopBackground = DesktopBackgroundConfig.FromGradient(
69+
ColorGradient.FromColors(new Color(0, 30, 60), new Color(0, 5, 15)),
70+
GradientDirection.Vertical);
71+
```
72+
73+
All four gradient directions are supported:
74+
75+
| Direction | Effect |
76+
|-----------|--------|
77+
| `Vertical` | Top to bottom |
78+
| `Horizontal` | Left to right |
79+
| `DiagonalDown` | Top-left to bottom-right |
80+
| `DiagonalUp` | Bottom-left to top-right |
81+
82+
Multi-stop gradients work too:
83+
84+
```csharp
85+
var gradient = ColorGradient.FromColors(
86+
new Color(10, 10, 40),
87+
new Color(40, 10, 30),
88+
new Color(10, 10, 40));
89+
90+
windowSystem.DesktopBackground = DesktopBackgroundConfig.FromGradient(
91+
gradient, GradientDirection.Horizontal);
92+
```
93+
94+
## Pattern Backgrounds
95+
96+
Tile a repeating character pattern across the desktop:
97+
98+
```csharp
99+
windowSystem.DesktopBackground = DesktopBackgroundConfig.FromPattern(
100+
DesktopPatterns.Checkerboard);
101+
```
102+
103+
### Built-in Patterns
104+
105+
| Preset | Description | Size |
106+
|--------|-------------|------|
107+
| `DesktopPatterns.Checkerboard` | Alternating ░ and space | 2x2 |
108+
| `DesktopPatterns.Dots` | Sparse dots | 3x3 |
109+
| `DesktopPatterns.HatchDown` | Diagonal lines ╲ | 3x3 |
110+
| `DesktopPatterns.HatchUp` | Diagonal lines ╱ | 3x3 |
111+
| `DesktopPatterns.Crosshatch` | Cross-hatching ╳ | 3x3 |
112+
| `DesktopPatterns.LightShade` | Light shade ░ | 1x1 |
113+
| `DesktopPatterns.MediumShade` | Medium shade ▒ | 1x1 |
114+
| `DesktopPatterns.DenseShade` | Dense shade ▓ | 1x1 |
115+
| `DesktopPatterns.HorizontalLines` | Horizontal lines | 1x2 |
116+
| `DesktopPatterns.VerticalLines` | Vertical lines | 3x1 |
117+
| `DesktopPatterns.Grid` | Thin grid | 3x3 |
118+
119+
### Custom Patterns
120+
121+
Define your own tile with a `char[,]` grid:
122+
123+
```csharp
124+
var customPattern = new DesktopPattern(new char[,]
125+
{
126+
{ '╔', '═', '╗' },
127+
{ '║', ' ', '║' },
128+
{ '╚', '═', '╝' }
129+
});
130+
131+
windowSystem.DesktopBackground = DesktopBackgroundConfig.FromPattern(customPattern);
132+
```
133+
134+
Patterns support per-cell foreground and background colors:
135+
136+
```csharp
137+
var pattern = new DesktopPattern(new char[,] { { '●', ' ' }, { ' ', '●' } })
138+
{
139+
ForegroundColors = new Color?[,]
140+
{
141+
{ Color.Cyan1, null },
142+
{ null, Color.Green }
143+
}
144+
};
145+
```
146+
147+
## Combined (Gradient + Pattern)
148+
149+
Set both a gradient and a pattern. The gradient is rendered first, then the pattern characters are tiled on top (inheriting gradient colors where pattern colors are null):
150+
151+
```csharp
152+
windowSystem.DesktopBackground = new DesktopBackgroundConfig
153+
{
154+
Gradient = new GradientBackground(
155+
ColorGradient.FromColors(new Color(0, 20, 50), new Color(0, 5, 15)),
156+
GradientDirection.Vertical),
157+
Pattern = DesktopPatterns.Dots
158+
};
159+
```
160+
161+
This produces dots whose colors shift along the gradient.
162+
163+
## Animated Backgrounds
164+
165+
Animated backgrounds use a `PaintCallback` that receives the buffer, dimensions, and elapsed time. The callback is invoked on the render thread at `AnimationIntervalMs` intervals.
166+
167+
### Built-in Effects
168+
169+
Three built-in effects are available in `DesktopEffects`:
170+
171+
#### Color Cycling
172+
173+
Smoothly cycles through hues over time:
174+
175+
```csharp
176+
windowSystem.DesktopBackground = DesktopEffects.ColorCycling(
177+
cycleDurationSeconds: 12.0,
178+
direction: GradientDirection.Vertical,
179+
intervalMs: 100);
180+
```
181+
182+
#### Pulse
183+
184+
Subtle brightness pulsing on a base color:
185+
186+
```csharp
187+
windowSystem.DesktopBackground = DesktopEffects.Pulse(
188+
baseColor: new Color(15, 25, 60),
189+
pulseRange: 0.15,
190+
pulseDurationSeconds: 4.0);
191+
```
192+
193+
#### Drifting Gradient
194+
195+
Gradient that cycles through directions:
196+
197+
```csharp
198+
windowSystem.DesktopBackground = DesktopEffects.DriftingGradient(
199+
color1: new Color(20, 40, 80),
200+
color2: new Color(60, 20, 70),
201+
cycleDurationSeconds: 8.0);
202+
```
203+
204+
### Custom Paint Callbacks
205+
206+
For full control, provide a `PaintCallback`:
207+
208+
```csharp
209+
windowSystem.DesktopBackground = new DesktopBackgroundConfig
210+
{
211+
AnimationIntervalMs = 70,
212+
PaintCallback = (buffer, width, height, elapsed) =>
213+
{
214+
// Paint directly to the CharacterBuffer.
215+
// Called on the render thread at AnimationIntervalMs intervals.
216+
for (int y = 0; y < height; y++)
217+
for (int x = 0; x < width; x++)
218+
{
219+
double t = (Math.Sin(elapsed.TotalSeconds + x * 0.1 + y * 0.05) + 1.0) / 2.0;
220+
byte b = (byte)(t * 40);
221+
buffer.SetCell(x, y, new Cell(' ', Color.White, new Color(0, 0, b)));
222+
}
223+
}
224+
};
225+
```
226+
227+
**Performance notes:**
228+
- The callback runs on the render thread — keep it fast
229+
- `AnimationIntervalMs` controls how often the buffer is re-rendered (default: 100ms / 10 FPS)
230+
- Only exposed desktop regions (not covered by windows) are blitted to screen
231+
- When an animation is active during window drag, the buffer is re-rendered to keep the exposed area in sync
232+
233+
### Stopping Animation
234+
235+
Set the background to `null` or a static config:
236+
237+
```csharp
238+
windowSystem.DesktopBackground = null; // Revert to theme default
239+
```
240+
241+
## Theme Integration
242+
243+
Themes can provide a default desktop gradient via `DesktopBackgroundGradient`:
244+
245+
```csharp
246+
public class MyTheme : ITheme
247+
{
248+
// ... other theme properties ...
249+
250+
public GradientBackground? DesktopBackgroundGradient { get; set; }
251+
= new GradientBackground(
252+
ColorGradient.FromColors(new Color(10, 10, 30), Color.Black),
253+
GradientDirection.Vertical);
254+
}
255+
```
256+
257+
The priority is:
258+
1. `ConsoleWindowSystem.DesktopBackground` config gradient (if set)
259+
2. Theme's `DesktopBackgroundGradient` (if set)
260+
3. Theme's solid `DesktopBackgroundColor` + `DesktopBackgroundChar`
261+
262+
If `DesktopBackgroundGradient` returns `null` (the default), the solid color is used.
263+
264+
## Runtime Changes
265+
266+
All desktop background changes are applied automatically:
267+
268+
```csharp
269+
// These all take effect on the next frame — no manual action needed
270+
windowSystem.DesktopBackground = DesktopBackgroundConfig.FromGradient(...);
271+
windowSystem.DesktopBackground = DesktopBackgroundConfig.FromPattern(...);
272+
windowSystem.DesktopBackground = DesktopEffects.ColorCycling();
273+
windowSystem.DesktopBackground = null; // Reset to theme default
274+
```
275+
276+
The background correctly handles:
277+
- **Screen resize** — buffer is re-rendered at new dimensions
278+
- **Panel visibility changes** — background adapts to new desktop geometry
279+
- **Theme changes** — base colors and theme gradient update automatically
280+
- **Window move/close** — exposed desktop regions are restored from the cached buffer
281+
282+
## See Also
283+
284+
- [Configuration Guide](CONFIGURATION.md) — `DesktopBackground` option
285+
- [Gradients & Alpha](GRADIENTS.md) — `ColorGradient`, `GradientDirection`, window gradients
286+
- [Themes](THEMES.md) — `DesktopBackgroundGradient` theme property
287+
- [Compositor Effects](COMPOSITOR_EFFECTS.md) — `PreBufferPaint`/`PostBufferPaint` for per-window effects

‎docs/GRADIENTS.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,8 @@ window.BackgroundGradient = null;
7777

7878
Background gradients are rendered via `PreBufferPaint`, so all controls paint on top of the gradient.
7979

80+
> **Desktop backgrounds** also support gradients, patterns, and animations. See the [Desktop Background](DESKTOP_BACKGROUND.md) guide.
81+
8082
## CharacterBuffer Direct API
8183

8284
Apply gradients directly to any `CharacterBuffer` region:

‎docs/STATE-SERVICES.md‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ SharpConsoleUI includes built-in state management services for managing differen
66

77
- [Overview](#overview)
88
- [PanelStateService](#panelstateservice)
9+
- [DesktopBackgroundService](#desktopbackgroundservice)
910
- [WindowStateService](#windowstateservice)
1011
- [FocusManager](#focusmanager)
1112
- [ModalStateService](#modalstateservice)
@@ -24,7 +25,8 @@ All state services are accessible through the `ConsoleWindowSystem` instance:
2425
var windowSystem = new ConsoleWindowSystem(new NetConsoleDriver(RenderMode.Buffer));
2526

2627
// Access state services
27-
windowSystem.PanelStateService // Panel visibility, status text
28+
windowSystem.PanelStateService // Panel visibility, status text
29+
windowSystem.DesktopBackgroundService // Desktop background rendering
2830
windowSystem.WindowStateService
2931
window.FocusManager // Focus is per-window
3032
windowSystem.ModalStateService
@@ -101,6 +103,27 @@ windowSystem.PanelStateService.BottomPanel
101103
windowSystem.BottomPanel
102104
```
103105

106+
## DesktopBackgroundService
107+
108+
Manages the desktop background — a cached `CharacterBuffer` that is rendered once and blitted to exposed regions each frame. See the [Desktop Background](DESKTOP_BACKGROUND.md) guide for the full reference.
109+
110+
### Usage
111+
112+
```csharp
113+
// Set background via the convenience property (preferred)
114+
windowSystem.DesktopBackground = DesktopBackgroundConfig.FromGradient(
115+
ColorGradient.FromColors(Color.DarkBlue, Color.Black),
116+
GradientDirection.Vertical);
117+
118+
// Or access the service directly
119+
windowSystem.DesktopBackgroundService.Config = new DesktopBackgroundConfig { ... };
120+
121+
// Reset to theme default
122+
windowSystem.DesktopBackground = null;
123+
```
124+
125+
Changes are applied automatically on the next frame.
126+
104127
## WindowStateService
105128

106129
Manages window registration, z-order, and window lifecycle.

‎docs/THEMES.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -144,7 +144,8 @@ public class MyCustomTheme : ITheme
144144
| `InactiveTitleForegroundColor` | Title bar color for non-focused windows |
145145
| `DesktopBackgroundColor` | Background color for empty desktop space |
146146
| `DesktopForegroundColor` | Foreground color for desktop character |
147-
| `DesktopBackroundChar` | Character used to fill desktop background |
147+
| `DesktopBackgroundChar` | Character used to fill desktop background |
148+
| `DesktopBackgroundGradient` | Optional gradient for the desktop area (default: `null`). See [Desktop Background](DESKTOP_BACKGROUND.md) |
148149

149150
### Registering Custom Themes
150151

0 commit comments

Comments
 (0)