Styling System

System Architecture

Three independent layers cooperate to paint everything on screen:

How BaseControl fits in

BaseControl is the root for every Beep UI control. Its painting pipeline:

1. OnPaint → DrawContent(g)
2. EnsurePainter() — selects an IBaseControlPainter based on PainterKind
3. Painter calls BeepStyling.PaintStyleBackground / PaintStyleBorder / PaintStyleText using the control's current BeepControlStyle
4. Derived control overrides DrawContent to add specific content inside DrawingRect

How BeepiFormPro fits in

BeepiFormPro is the themed borderless form host. Its pipeline is parallel but separate from the control pipeline:

1. FormStyle property changes → ApplyFormStyle()
2. BeepStyling.GetControlStyle(FormStyle) → syncs BeepStyling.CurrentControlStyle so controls inside the form automatically pick up the same style
3. PaintersFactory.GetPainter(FormStyle) → returns a cached IFormPainter
4. IFormPainter.CalculateLayoutAndHitAreas() positions caption bar, buttons, title; IFormPainter.PaintBackground / PaintCaptionBar / PaintBorder render each layer

BeepStyling — The Coordinator

Static class in TheTechIdea.Beep.Winform.Controls.Styling. Single source of truth for which design system is currently active.

Global State

Style Management Methods

Paint Entry Points

Style Value Shortcuts

Painter Subsystems (7 Folders)

Each folder contains style-specific painter classes. All painters are static and stateless; they receive all context via parameters.

Factory Classes

Each painter folder has a companion factory for lookup and caching:

Style Helper Systems (5 Systems)

All helpers are static classes that accept BeepControlStyle and return design-system-specific values via switch expressions. No base classes — every value is explicit.

BaseControl Painting Pipeline

Every Beep control inherits from BaseControl (ContainerControl). Understanding this pipeline is essential for creating custom controls.

File Structure

Render Sequence

protected override void OnPaint(PaintEventArgs e)
{
    if (!IsReadyForDrawing) return;        // 1. Guard
    if (AllowBaseControlClear) e.Graphics.Clear(BackColor);

    DrawContent(e.Graphics);              // 2. Entry
}

protected virtual void DrawContent(Graphics g)
{
    EnsurePainter();                      // 3. Select painter
    _painter?.UpdateLayout(this);         // 4. Compute rects
    _painter?.Paint(g, this);             // 5. Render outer chrome
    _painter?.UpdateHitAreas(this);       // 6. Register hit zones
    // DrawingRect is now ready — derived control paints content here
}

Painter Kinds

Border Painter Style (independent)

Separate from PainterKind. The BorderPainterStyle property selects a BeepControlStyle-specific border painter that is applied after the main painter renders the background:

// In a custom control constructor
PainterKind         = BaseControlPainterKind.Classic;   // outer chrome
BorderPainterStyle  = BeepControlStyle.Fluent2;          // border look

UpdateBorderPainter() calls BorderPainterFactory.CreatePainter(style) and also syncs BorderRadius, BorderThickness, and BorderColor from the style defaults.

Theme Subscription Pattern

// BaseControl automatically subscribes in its constructor:
BeepThemesManager.ThemeChanged += (s, e) => {
    _currentTheme = e.NewTheme;
    ApplyTheme();
    Invalidate();
};

// ApplyTheme() copies theme tokens to control properties:
public virtual void ApplyTheme()
{
    ForeColor    = _currentTheme.ForeColor;
    BorderColor  = _currentTheme.BorderColor;
    BackColor    = IsChild ? Parent.BackColor : _currentTheme.BackColor;
    _textFont    = BeepThemesManager.ToFont(_currentTheme.BodyMedium);
    // ...
}

Creating a Custom Control

public class MyBeepLabel : BaseControl
{
    public MyBeepLabel()
    {
        PainterKind        = BaseControlPainterKind.Classic;
        BorderPainterStyle = BeepControlStyle.Minimal;
        IsChild            = true;  // transparent background
    }

    protected override void DrawContent(Graphics g)
    {
        base.DrawContent(g);   // paints chrome into DrawingRect

        // DrawingRect is the inner content area after padding/border
        using var sf = new StringFormat { Alignment = StringAlignment.Center,
                                          LineAlignment = StringAlignment.Center };
        g.DrawString(Text, _textFont, new SolidBrush(ForeColor), DrawingRect, sf);
    }
}

BeepiFormPro Painting Pipeline

BeepiFormPro is a borderless Form subclass. Unlike controls, it has its own separate painter contract (IFormPainter) and factory.

File Structure

IFormPainter Contract

public interface IFormPainter
{
    void CalculateLayoutAndHitAreas(BeepiFormPro owner);
    void PaintBackground(Graphics g, BeepiFormPro owner);
    void PaintCaptionBar(Graphics g, BeepiFormPro owner);
    void PaintBorder(Graphics g, BeepiFormPro owner);
}

Each FormStyle has exactly one painter class (e.g., DraculaFormPainter, MacOSFormPainter). The painter owns everything: corner radius, caption height, window button positions, and visual effects for that style.

Layout Caching

To avoid recalculating hit areas on every paint, BeepiFormPro.Core.cs tracks a dirty flag. Layout only recalculates when:

• Form size changes
• FormStyle changes
• Caption/button visibility changes
• InvalidateLayout() is called explicitly

Available FormStyle Painters (40+)

StyledImagePainter

Static class in Styling/ImagePainters/. Handles all image rendering across the system with built-in caching, shape clipping, tinting, and opacity.

Caching

All caches are ConcurrentDictionary — thread-safe for background pre-rendering.

Core Paint Methods

Shape Clip Methods

Usage Example

protected override void DrawContent(Graphics g)
{
    base.DrawContent(g);

    // Paint avatar image clipped to a circle
    float cx = DrawingRect.X + DrawingRect.Width  / 2f;
    float cy = DrawingRect.Y + DrawingRect.Height / 2f;
    float r  = Math.Min(DrawingRect.Width, DrawingRect.Height) / 2f - 2f;

    StyledImagePainter.PaintInCircle(g, cx, cy, r, ImagePath);

    // Or paint with a blue tint at 80% opacity:
    StyledImagePainter.PaintWithTint(g, _clipPath, ImagePath,
        Color.FromArgb(100, 0, 120, 215), opacity: 0.8f, cornerRadius: 8);
}

FormStyle ↔ BeepControlStyle Mapping

When BeepiFormPro.FormStyle changes, BeepStyling.ApplyFormStyle() calls GetControlStyle(formStyle) to sync all controls inside the form to the same visual system:

BeepControlStyle Enum

60+ styles grouped by origin:

Web Frameworks & Design Systems

Material3, AntDesign, Fluent2, MaterialYou, Windows11Mica, MacOSBigSur, ChakraUI, TailwindCard, NotionMinimal, VercelClean, StripeDashboard, Bootstrap, FigmaCard, PillRail, Apple, Shadcn, RadixUI, NextJS, Linear

Dark / Atmospheric

DarkGlow, DiscordStyle, GradientModern, GlassAcrylic, Neumorphism, Glassmorphism, NeoMorphism, Neon, NeonGlow, DarkGlow, Holographic, Cyberpunk

Desktop OS

Minimal, Modern, Fluent, Material, Metro, Metro2, MacOS, iOS15, Ubuntu, Gnome, Kde, Cinnamon, Elementary, ArcLinux, Nordic, Nord

Editor / Terminal Themes

Dracula, Solarized, OneDark, GruvBox, Tokyo, Terminal, Paper

Visual Aesthetics

Cartoon, ChatBubble, Retro, Brutalist, NeoBrutalist, Gaming, HighContrast, Office, FinSet, WebFramework, Effect

Best Practices

• Never copy-paste style values into a control. Always ask StyleColors, StyleBorders, etc. so the control automatically stays correct when the design system evolves.
• Let BeepStyling route painter calls; don't call individual painters directly from controls. The routing switch in BeepStyling.PaintStyleBackground() is the single maintenance point for adding new styles.
• Always set BeepStyling.CurrentTheme whenever BeepThemesManager.CurrentTheme changes. BeepiFormPro.ApplyTheme() does this automatically; your custom root forms must do the same.
• Use PainterKind = BaseControlPainterKind.None only when the control is doing fully custom rendering. Anything set to None bypasses the shadow, border, and background system entirely.
• Keep painters stateless. All context (style, theme, focus state) must come in as method parameters. Painters must not cache mutable state between calls.
• Use StyledImagePainter for every image draw operation. It handles icon loading, SVG fallback paths, DPI-aware sizing, and the shared cache. Do not call g.DrawImage() with an unconditional Image.FromFile() inside OnPaint.
• Call InvalidateLayout() after property changes that affect size. For BeepiFormPro, this clears the cached border path and hit areas so the painter recalculates on the next paint cycle.
• Implement IFormPainter for custom form skins. Register it in PaintersFactory.CreatePainter() under a new FormStyle value. That is the only change required system-wide.