Font Management

Overview

The FontManagement subsystem provides application-wide font loading, caching, and discovery for every Beep WinForms control. It ships a large catalog of embedded font resources while remaining fully extensible — theme packs, plugins, and consuming projects can register their own fonts at any time without modifying the core library.

BeepFontManager

The top-level static API. All controls and painters use this class to obtain Font instances rather than creating fonts directly. Fonts are lazy-initialised and cached for the application lifetime.

Configuration Properties

Setting any configuration property calls ResetFonts() internally, which recreates all cached element font instances.

Element Font Properties (read-only)

Discovery Lists

Initialization

Call Initialize() once at application startup before any Beep controls are shown. It is idempotent — subsequent calls return immediately.

// Program.cs / Application startup
await BeepFontManager.Initialize();

// After init you can read element fonts immediately
Font btn = BeepFontManager.ButtonFont;      // "Segoe UI", 9pt
Font hdr = BeepFontManager.HeaderFont;     // "Segoe UI", 11pt Bold
Font code = BeepFontManager.MonospaceFont; // "Consolas", 9pt

Initialize() performs the following steps:

1. Builds a FontScanOptions from built-in namespaces plus anything registered in BeepFontRegistry.
2. Runs FontListHelper.LoadAllFonts(opt) on a background thread.
3. Creates all element font instances via CreateDefaultFonts().
4. Subscribes to BeepFontRegistry.Changed for incremental late-registration.

Registration API

Plugins and theme packs register their font-bearing assemblies through BeepFontManager (preferred) or directly on BeepFontRegistry.

// Register a single assembly (triggers immediate scan if already initialized)
BeepFontManager.Register(Assembly.GetExecutingAssembly());

// Register multiple assemblies at once
BeepFontManager.Register(new[] { asmA, asmB });

// Register a namespace prefix (embedded resources whose path contains this string)
BeepFontManager.Register("MyCompany.MyTheme.Fonts");

// Register a file-system directory for .ttf / .otf scanning
BeepFontManager.RegisterDirectory(@"C:\MyFonts");

BeepFontPaths

A static partial class spread across several files, each covering one font category. Every constant is the fully-qualified embedded resource name for use with Assembly.GetManifestResourceStream().

Base namespace: TheTechIdea.Beep.Winform.Controls.Fonts

Font Catalog by Category

The built-in catalog ships 300+ font variants across 30 families, organised into five categories:

Web Fonts

Monospace Fonts

Display Fonts

Accessibility Fonts

System / Miscellaneous Fonts

Lookup Methods

Families Inner Class

For convenient strongly-typed access each font family has a nested static class under BeepFontPaths.Families:

// Direct constant path
string path = BeepFontPaths.RobotoRegular;

// Via Families nested class (same value, grouped namespace)
string path = BeepFontPaths.Families.Roboto.Regular;

// All weights as a dictionary
var robotoWeights = BeepFontPaths.Families.Roboto.GetAllStyles();
// => { "Regular", "Bold", "Thin", "Medium", ... }

// Cairo (8 weights)
var cairoWeights = BeepFontPaths.Families.Cairo.GetAllWeights();

// Get lookup across all families
var all = BeepFontPaths.GetAllFamilies();
// => { "Roboto": {...}, "Cairo": {...}, "FiraCode": {...}, ... }

Runtime Registration

When an external assembly registers its fonts (e.g. a theme pack), call RegisterFamilyFromAssembly to make those fonts discoverable through normal path lookups:

// Scan an assembly's embedded resources under a specific namespace root
BeepFontPaths.RegisterFamilyFromAssembly(
    Assembly.GetExecutingAssembly(),
    "MyThemePack.Fonts");

// Omit namespaceRoot to accept all embedded .ttf/.otf resources
BeepFontPaths.RegisterFamilyFromAssembly(Assembly.GetExecutingAssembly());

After this call, GetAllFamilies() and GetFontPath() will include the new fonts from that assembly.

BeepFontRegistry

Thread-safe central registry that tracks which assemblies, namespace prefixes, and file-system directories should be scanned for font resources. Uses a ReaderWriterLockSlim for concurrent access.

Registration Methods

Convention Discovery

An assembly is considered to contain fonts if it has at least one embedded .ttf or .otf resource whose namespace prefix ends with .Fonts. Example resource name: MyApp.Fonts.Roboto-Regular.ttf

// Check if an assembly satisfies the convention
bool hasFonts = BeepFontRegistry.HasConventionFontResource(myAssembly);

// Scan entire AppDomain automatically (useful for plugin hosts)
BeepFontRegistry.RegisterFromAppDomain();

Read-only Views

Changed Event

BeepFontRegistry.Changed fires whenever a new assembly, namespace, or directory is added. BeepFontManager subscribes after Initialize() to trigger incremental scans for late-registered plugins:

// After BeepFontManager.Initialize(), this is done automatically.
// You can also subscribe manually:
BeepFontRegistry.Changed += (s, e) =>
{
    // Re-scan or update UI font lists
};

PrimaryAssembly Override

Set BeepFontRegistry.PrimaryAssembly to redirect BeepFontPaths.ResourceAssembly to a theme-pack assembly that ships its own font catalog and embedded fonts:

// In a theme-pack initializer
BeepFontRegistry.PrimaryAssembly = Assembly.GetExecutingAssembly();
// All BeepFontPaths resource lookups now query this assembly first

FontListHelper

The low-level engine responsible for scanning, loading, and caching fonts from all three sources: system, file-system, and embedded assembly resources.

FontScanOptions

Controls what is scanned during LoadAllFonts():

var options = new FontListHelper.FontScanOptions
{
    ScanSystemFonts = true,
    Directories = new List<string> { @"C:\MyApp\Fonts" },
    EmbeddedNamespaces = new[] { "MyCompany.Fonts" },
    AdditionalAssemblies = new List<Assembly> { myPluginAssembly },
    IncludeReferencedAssemblies = true,
    MaxReferenceDepth = 1,
    UseConventionDiscovery = true
};

FontListHelper.LoadAllFonts(options);

Font Caching

An application-lifetime Dictionary<string, Font> cache is keyed by "name|size|style". Paintings call these methods on every render; the cache prevents allocation spam.

// In a painter's OnPaint — zero allocation after first call
Font f = FontListHelper.GetCachedFont("Roboto", 11f, FontStyle.Regular);
g.DrawString(text, f, brush, rect);

DPI Scaling

DPI scaling is off by default for backward compatibility. Enable it globally or per-control:

// Enable DPI-aware fonts globally (do once at startup)
FontListHelper.EnableDpiFontScaling = true;
FontListHelper.UpdateDpiFromSystem();

// Per-control scaling in a custom form
protected override void OnDpiChanged(DpiChangedEventArgs e)
{
    base.OnDpiChanged(e);
    FontListHelper.UpdateDpiFromControl(this);
}

Discovery Methods

Usage Patterns

1. Basic Application Setup

// Program.cs
static async Task Main(string[] args)
{
    // Initialize font system before creating any controls
    await BeepFontManager.Initialize();

    // Optionally customise the app font
    BeepFontManager.AppFontName = "Roboto";
    BeepFontManager.AppFontSize = 10f;

    Application.Run(new MainForm());
}

2. Using Element Fonts in a Control

protected override void OnPaint(PaintEventArgs e)
{
    base.OnPaint(e);

    // Use pre-cached element fonts — no allocation
    e.Graphics.DrawString("Header", BeepFontManager.HeaderFont, Brushes.Black, headerRect);
    e.Graphics.DrawString("Label",  BeepFontManager.LabelFont,  Brushes.Gray,  labelRect);
    e.Graphics.DrawString("0x1A3F", BeepFontManager.MonospaceFont, Brushes.Navy, codeRect);
}

3. Loading an Embedded Font by Path

// Get the resource path constant
string path = BeepFontPaths.Families.Roboto.Bold; 
// => "TheTechIdea.Beep.Winform.Controls.Fonts.Roboto.Roboto-Bold.ttf"

// Create a font from the embedded resource using BeepFontPathsExtensions
Font robotoBold = BeepFontPathsExtensions.CreateFontFromResource(path, 14f, FontStyle.Bold);

4. Plugin / Theme Pack Registration

// In a theme pack assembly's static initializer
public static class MyThemeInitializer
{
    public static void Register()
    {
        // Preferred: register via BeepFontManager (handles both pre- and post-init)
        BeepFontManager.Register(Assembly.GetExecutingAssembly());

        // Optionally redirect the primary assembly so path lookups favour this pack
        BeepFontRegistry.PrimaryAssembly = Assembly.GetExecutingAssembly();
    }
}

// Consuming application startup:
MyThemeInitializer.Register();
await BeepFontManager.Initialize();

5. DPI-Aware Painter

// In a custom BeepControl override
protected override void OnDpiChanged(DpiChangedEventArgs e)
{
    base.OnDpiChanged(e);
    FontListHelper.UpdateDpiFromControl(this);
    Invalidate(); // repaint with new font sizes
}

protected override void OnPaint(PaintEventArgs e)
{
    // GetCachedFontForControl reads the control's current DPI
    Font scaled = FontListHelper.GetCachedFontForControl("Roboto", 10f, this);
    e.Graphics.DrawString(Text, scaled, Brushes.Black, ClientRectangle);
}

6. Querying Available Families

// List all family names (built-in + runtime-registered)
List<string> families = BeepFontPaths.GetFontFamilyNames();

// Get a specific path by family + style name
string path = BeepFontPaths.GetFontPath("JetBrainsMono", "SemiBold");

// Enumerate all system font names
List<string> system = BeepFontManager.SystemFontNames;

// Enumerate all loaded (private) font names
List<string> custom = BeepFontManager.CustomFontNames;

File Organisation

Best Practices

• Call Initialize() once at startup — preferably before any controls are created. It is asynchronous and safe to await in Main().
• Prefer element font properties — use BeepFontManager.HeaderFont rather than creating a new Font() inline; element fonts are cached and consistent across the whole application.
• Do not dispose fonts obtained from BeepFontManager or FontListHelper — they are owned by the caching layer and shared across all controls.
• Use GetCachedFont() in painters — avoids per-paint GDI object creation and eliminates GDI handle leaks.
• Call ClearFontCache() only on theme change — not on every resize or repaint; it is an expensive operation that forces re-creation of all cached fonts.
• Register plugins before Initialize() when possible — if a plugin must register after init, use BeepFontManager.Register() which handles the incremental scan automatically.
• Enable EnableDpiFontScaling for high-DPI apps — call UpdateDpiFromSystem() at startup and UpdateDpiFromControl() in OnDpiChanged overrides.
• Use the .Fonts namespace convention for embedded font resources in plugins — this enables auto-detection by RegisterFromAppDomain() with zero explicit registration code.