BeepThemesManager

Overview

BeepThemesManager is a static class — no instantiation required. At startup it:

1. Scans all loaded assemblies for types implementing IBeepTheme.
2. Loads the fixed list of 55+ predefined themes from TheTechIdea.Beep.Vis.Modules2.0.
3. Ensures a fallback DefaultBeepTheme always exists.
4. Exposes static events (ThemeChanged, FormStyleChanged, DpiChanged) that every control subscribes to.

Events

ThemeChangeEventArgs

StyleChangeEventArgs

Static Properties

Theme Selection

DPI Scaling

Static Methods

Theme Lifecycle

Theme Retrieval

Theme Switching

FormStyle to Theme Mapping

Font Helpers

DPI Management

Persistence

Misc

FormStyle → Theme Name Mapping

Setting CurrentStyle automatically resolves and activates the paired theme via this mapping:

Built-in Predefined Themes

All themes below are auto-discovered and registered at startup from TheTechIdea.Beep.Vis.Modules2.0. They are also dynamically loaded by AddPredefinedThemes() via reflection:

Creating a Custom Theme

Implement IBeepTheme (or inherit from BeepTheme) and register it once at startup:

public class MyBrandTheme : BeepTheme
{
    public MyBrandTheme()
    {
        ThemeName      = "MyBrandTheme";
        IsDarkTheme    = false;
        BackColor      = Color.FromArgb(245, 248, 255);
        ForeColor      = Color.FromArgb(20, 20, 40);
        PrimaryColor   = Color.FromArgb(0, 85, 200);    // brand blue
        SecondaryColor = Color.FromArgb(0, 150, 130);   // brand teal
        AccentColor    = Color.FromArgb(255, 120, 30);  // brand orange
        BorderRadius   = 8;
        PaddingSmall   = 4;
        PaddingMedium  = 8;
        PaddingLarge   = 16;
    }
}

// Register once at application startup (before Application.Run)
BeepThemesManager.AddTheme(new MyBrandTheme());

// Activate it - all subscribed controls repaint automatically
BeepThemesManager.SetCurrentTheme("MyBrandTheme");

Subscribing to Theme Events in Custom Controls

public class MyCustomControl : BeepControl
{
    public MyCustomControl()
    {
        BeepThemesManager.ThemeChanged     += OnThemeChanged;
        BeepThemesManager.DpiChanged       += OnDpiChanged;
        BeepThemesManager.FormStyleChanged += OnFormStyleChanged;
    }

    private void OnThemeChanged(object sender, ThemeChangeEventArgs e)
    {
        // e.NewTheme is the ready-to-use IBeepTheme
        ApplyTheme(e.NewTheme);
        Invalidate();
    }

    private void OnDpiChanged(object sender, EventArgs e)
    {
        // DPI changed - update layout metrics but do NOT call ApplyTheme()
        UpdateLayout();
        Invalidate();
    }

    private void OnFormStyleChanged(object sender, StyleChangeEventArgs e)
    {
        // Optional: adjust chrome for the new style
        UpdateBorderForStyle(e.NewStyle);
    }

    protected override void Dispose(bool disposing)
    {
        if (disposing)
        {
            // CRITICAL: always unsubscribe - static events hold strong references
            BeepThemesManager.ThemeChanged     -= OnThemeChanged;
            BeepThemesManager.DpiChanged       -= OnDpiChanged;
            BeepThemesManager.FormStyleChanged -= OnFormStyleChanged;
        }
        base.Dispose(disposing);
    }
}

DPI Handling

Beep uses WinForms automatic Point-font DPI scaling for all standard text. Custom GDI painters that need absolute pixel measurements must call ToFontForControl instead of ToFont.

Application startup

// Program.cs - before Application.Run()
Application.SetHighDpiMode(HighDpiMode.PerMonitorV2);
BeepThemesManager.UpdateDpiFromSystem();

Forms that can move between monitors

protected override void OnDpiChanged(DpiChangedEventArgs e)
{
    base.OnDpiChanged(e);
    // Updates DpiScaleX/Y and fires BeepThemesManager.DpiChanged automatically
    BeepThemesManager.UpdateDpiFromControl(this);
}

Font in a custom GDI painter

protected override void OnPaint(PaintEventArgs e)
{
    // Use ToFontForControl for physical pixel accuracy in custom GDI drawing
    using var bodyFont = BeepThemesManager.ToFontForControl(
        BeepThemesManager.CurrentTheme.Body1Typography, this);

    e.Graphics.DrawString("Hello", bodyFont, Brushes.Black, ClientRectangle);
}

Switching Themes at Runtime

// By name
BeepThemesManager.SetCurrentTheme("DraculaTheme");

// By FormStyle - sets both form chrome and theme palette in one call
BeepThemesManager.SetCurrentStyle(FormStyle.Dracula);

// By object reference
IBeepTheme night = BeepThemesManager.GetTheme("MidnightTheme");
BeepThemesManager.SetCurrentTheme(night);

// Populate a ComboBox with all available themes
var names = BeepThemesManager.GetThemeNames();
cmbTheme.DataSource = names;
cmbTheme.SelectedIndexChanged += (s, e) =>
    BeepThemesManager.SetCurrentTheme((string)cmbTheme.SelectedItem);

Theme Persistence

// Save a custom theme to an XML file
IBeepTheme custom = BeepThemesManager.GetTheme("MyBrandTheme");
BeepThemesManager.SaveTheme(custom, @"themes\mybrand.xml");

// Load it back (also registers it automatically)
IBeepTheme loaded = BeepThemesManager.LoadTheme(@"themes\mybrand.xml");
BeepThemesManager.SetCurrentTheme(loaded);

Best Practices

• Never call ApplyTheme() inside the DpiChanged handler. DPI change and theme change are intentionally separate events. Calling ApplyTheme() on DPI change causes unnecessary font re-creation, multiple repaints, and potential double-scaling.
• Always unsubscribe in Dispose(). Static event subscriptions prevent controls from being garbage-collected.
• Use ToFont() for normal WinForms text, ToFontForControl() for custom GDI painters. ToFont() returns a logical Point font that WinForms auto-scales. ToFontForControl() returns a physical pixel font for raw GDI measurements.
• Leave EnableDpiFontScaling = false (the default). Enabling it on a WinForms app causes double-scaling (WinForms + manual) resulting in oversized text on high-DPI monitors.
• Call UpdateDpiFromSystem() once at startup. For forms that can move between monitors also call UpdateDpiFromControl(this) inside OnDpiChanged.
• Register custom themes before calling Application.Run(). Controls are created first and may miss a ThemeChanged event if the theme is added after the window is shown.
• Use ConfigureDefaultTheme() as a quick baseline. It sets sensible dark/light colors and padding so you only override the properties your brand needs.
• Prefer SetCurrentStyle(FormStyle) over SetCurrentTheme(name) when you want the form chrome and control palette to stay visually consistent — both change together in one call.