Design-Time Infrastructure

Overview

Every Beep control participates in the Visual Studio design-time experience through a dedicated Control Designer class. Designers control what happens when you drag a control from the Toolbox, click the smart-tag glyph, set properties, or right-click for context menu commands.

The design-time infrastructure lives in TheTechIdea.Beep.Winform.Controls.Design.Server project and is organized into five layers:

Designer Hierarchy

Beep uses Microsoft.DotNet.DesignTools as the design-time platform. The hierarchy is:

// Abstract base for all leaf controls (buttons, labels, grids, charts...)
public abstract class BaseBeepControlDesigner : ControlDesigner, IBeepDesignerActionHost
{
    protected IComponentChangeService ChangeService;
    protected BaseControl BeepControl;
    public void SetProperty(string name, object value);
    public T GetProperty<T>(string name);
    public void ApplyTheme();
    protected abstract DesignerActionListCollection GetControlSpecificActionLists();
}

// Abstract base for container/parent controls (panels, tabs, DocumentHost...)
public abstract class BaseBeepParentControlDesigner : ControlDesigner, IBeepDesignerActionHost
{
    // Same pattern, separated for future ParentControlDesigner migration
    public void SetProperty(string name, object value);
    public T GetProperty<T>(string name);
    public void ApplyTheme();
}

Each concrete designer overrides GetControlSpecificActionLists() to add its smart-tag. The ActionLists property automatically combines control-specific lists with CommonBeepControlActionList (style/theme/schema for every control).

IBeepDesignerActionHost Interface

public interface IBeepDesignerActionHost
{
    IComponent Component { get; }
    void SetProperty(string propertyName, object value);
    T GetProperty<T>(string propertyName);
    void ApplyTheme();
}

Smart-Tag (Action List) System

Smart-tags are the property panel that opens when clicking the glyph (▼) on a selected control. They use DesignerActionList subclasses.

How It Works

1. The designer's ActionLists property returns a collection of action lists
2. Each action list exposes public properties (become editable items) and void methods (become clickable links)
3. The GetSortedActionItems() override organizes items into named categories

BeepGridProActionList — 47 Smart-Tag Items

The largest single-control action list in the library, organized into 7 sections:

DocumentHostActionList — 40+ Items, 18 Sections

The richest action list, covering document management, split views, tab configuration, theming, and session state.

Designer Verbs

Designer verbs appear in the right-click context menu at design time. Override the Verbs property.

BeepDockingManagerDesigner (15 verbs)

DockPanelDesigner (10 verbs)

IComponentChangeService & Serialization

All property mutations at design time must route through IComponentChangeService for proper .designer.cs code generation.

public void SetProperty(string propertyName, object value)
{
    PropertyDescriptor property =
        TypeDescriptor.GetProperties(Component)[propertyName];
    ChangeService?.OnComponentChanging(Component, property);  // undo
    property.SetValue(Component, value);                        // set
    ChangeService?.OnComponentChanged(Component, property,      // serialize
        null, value);
}

This three-step pattern ensures: Undo support (OnComponentChanging), property update, code generation (OnComponentChanged). Without it, changes made in designers would not persist to the .designer.cs file.

Docking Design-Time

The docking design-time system is the most sophisticated in the library, modeled after Krypton's KryptonDockingManager:

• BeepDockingManagerDesigner — Non-visual component designer (tray component). Auto-detects host form on drop.
• DockPanelDesigner — ParentControlDesigner for individual panels. Auto-generates unique Keys. Snap-to-edge when moved.
• BeepDockspaceDesigner — ParentControlDesigner for dockspace controls. Tab drag-drop within header.

All mutations route through BeepDockingDesignerWiring, a static helper that provides Panel CRUD, Move, Stack, Resize, and host-layout-refresh operations with proper IComponentChangeService notifications.

DocumentHost Design-Time

The DocumentHost design-time experience (DevExpress parity) includes:

• BeepDocumentHostDesigner — Accepts any control via CanParent, routes drops to active document area
• DocumentHostActionList — 40+ smart-tag items across 18 organized sections
• BeepDocumentPanelDesigner — Filters Properties window to 5 meaningful properties
• Tab click → Properties window updates for selected document panel
• Smart-tag verbs: Add/Clear Documents, Apply Layout Presets, Edit Design-Time Documents, Setup Wizard

Creating Custom Designers

For a Leaf Control

[Designer(typeof(MyControlDesigner))]
public class MyControl : BaseControl
{
    public string CustomProp { get; set; } = "Default";
}

public class MyControlDesigner : BaseBeepControlDesigner
{
    public MyControl MyCtrl => (MyControl)Component;

    protected override DesignerActionListCollection GetControlSpecificActionLists()
    {
        return new DesignerActionListCollection
        {
            new MyActionList(Component)
        };
    }
}

internal class MyActionList : DesignerActionList
{
    private MyControlDesigner Designer =>
        (MyControlDesigner)Component.Designer;

    public string CustomProp
    {
        get => Designer.GetProperty<string>(nameof(customProp));
        set => Designer.SetProperty(nameof(customProp), value);
    }

    public override DesignerActionItemCollection GetSortedActionItems()
    {
        var items = new DesignerActionItemCollection();
        items.Add(new DesignerActionHeaderItem("Custom"));
        items.Add(new DesignerActionPropertyItem(
            nameof(CustomProp), "Custom Property", "Custom"));
        return items;
    }
}

Class Reference