Best Practices

1. Always Use BaseControl

When creating custom controls, always inherit from BaseControl to get automatic theming, styling, and the Beep lifecycle.

// Correct
public class MyCustomControl : BaseControl
{
    // Gets theming, painting, and lifecycle for free
}

// Avoid
public class MyCustomControl : UserControl
{
    // No automatic theming support
}

2. Use ImagePath Instead of Image

Beep Controls reference images by file path string. This allows the theming system to tint and style images consistently.

// Correct
button.ImagePath = "icons/save.svg";

// Avoid
button.Image = Image.FromFile("icons/save.svg");

3. Initialize Themes Early

Set up BeepThemesManager before creating any controls, ideally in Program.cs.

static void Main()
{
    ApplicationConfiguration.Initialize();
    BeepThemesManager.ApplyTheme("MaterialBlue"); // Before any form
    Application.Run(new MainForm());
}

4. Use BeepStyling for Custom Painting

When doing custom painting, use BeepStyling helpers and StyledImagePainter instead of raw GDI+ to stay consistent with the active theme.

5. Leverage Built-in Layout Controls

Use BeepPanel, BeepCard, and BeepTabControl for layout instead of bare panels. They automatically apply themed borders, backgrounds, and shadows.

6. Handle Theme Changes

If your control caches colors or brushes, listen for theme change events and refresh:

public class MyControl : BaseControl
{
    protected override void OnThemeChanged()
    {
        base.OnThemeChanged();
        // Rebuild cached resources using new theme colors
        _cachedBrush?.Dispose();
        _cachedBrush = new SolidBrush(CurrentTheme.AccentColor);
        Invalidate();
    }
}

7. Dispose Resources Properly

Beep Controls use GDI+ resources. Always dispose controls and forms when done:

// In your form's Dispose method
protected override void Dispose(bool disposing)
{
    if (disposing)
    {
        components?.Dispose();
        _myCustomBrush?.Dispose();
        _myCustomPen?.Dispose();
    }
    base.Dispose(disposing);
}

8. Keep README Files Updated

When creating or modifying controls, update the relevant README files:

• Project README for overall changes
• BaseControl README for base class changes
• Styling README for styling changes
• Theming README for theme management changes
• Per-control README for control-specific documentation