Control Architecture

The control contract

Every control in TheTechIdea.Beep.WPF.Controls obeys the same seven rules. They are not style preferences — a control that breaks one of them will not theme, will not skin, or will not compile against the modernized library.

Canonical control skeleton

This is the shape to mirror when adding or modernizing a control. Only the DPs that add value are declared; Background, Foreground, Padding, FontSize, Command, etc. come from the native base.

namespace TheTechIdea.Beep.WPF.Controls;

/// <summary>
/// WPF-modern BeepName — thin subclass of the native primitive, implementing
/// only the capability interfaces it needs. All chrome lives in
/// Themes/Controls/BeepName.xaml via BeepChrome tokens + DynamicResource.
/// </summary>
[ToolboxItem(true)]
[Category("Beep Controls")]
public partial class BeepName : System.Windows.Controls.NativeBase, IBeepThemeable
{
    static BeepName()
    {
        DefaultStyleKeyProperty.OverrideMetadata(typeof(BeepName),
            new FrameworkPropertyMetadata(typeof(BeepName)));
    }

    // BeepChrome CLR wrappers — theme + control-style opt-in
    public string Theme
    {
        get => BeepChrome.GetTheme(this);
        set => BeepChrome.SetTheme(this, value);
    }

    public BeepControlStyle ControlStyle
    {
        get => BeepChrome.GetControlStyle(this);
        set => BeepChrome.SetControlStyle(this, value);
    }

    public BeepName() { /* no code-built visual tree; the template renders it */ }
}

The static constructor is the load-bearing line: DefaultStyleKeyProperty.OverrideMetadata tells WPF to look for a Style TargetType="{x:Type beep:BeepName}" — which is resolved against Themes/Generic.xaml (declared by [assembly: ThemeInfo]).

Forbidden patterns

These are the exact signals of pre-modernization code. If you see one while modernizing a legacy stub, it must go.

Native-primitive base reference

Picking the base is the single most important decision when adding a control — it determines which events, properties and automation you inherit. Choose the closest native primitive; fall back to ContentControl only when none fits, and UserControl only for genuine multi-element composites.

Where the files live

A control is spread across a small, fixed set of locations. Learn them once and every control is predictable.

Recipe: add or modernize a control

The end-to-end procedure. When modernizing a legacy stub, steps 1–2 are the demolition; steps 3–8 are the rebuild.

1. Read the existing file (if modernizing). Find the legacy override kinds (ApplyTheme/OnControlStyleApplied/SetValue/GetValue), every BaseControl reference, WinForms-typed DPs, and System.Drawing. All go.
2. Pick the native primitive base from the reference table — the most important decision.
3. Add the static ctor with DefaultStyleKeyProperty.OverrideMetadata(typeof(BeepName), …), plus [ToolboxItem(true)] / [Category("Beep Controls")].
4. Implement IBeepThemeable and any other capability interface the control needs; add the BeepChrome CLR wrappers. Use public members for IBeepIconHost so it is satisfied implicitly.
5. Add chrome tokens to Themes/ControlDefaults.xaml matching the keys the template will reference (SolidColorBrush for colours, Thickness for paddings, CornerRadius for radii, Double for sizes).
6. Write Themes/Controls/BeepName.xaml — a Style TargetType="{x:Type beep:BeepName}" with a ControlTemplate. All chrome via DynamicResource; icons inside the themed RootBorder, never as siblings; PART_-name anything code-behind wires in OnApplyTemplate.
7. Add per-skin styles (recommended, separate commit) in Themes/Styles/{skin}.xaml as {Skin}BeepNameStyle, reusing the same token key names. Validate the default works before shadowing it with a per-skin override.
8. Drop the code-built visual tree (if modernizing) and build: dotnet build … -c Debug ⇒ 0 errors. Then verify live in a consumer app that the control renders and re-skins on ControlStyle change.

<!-- Themes/Controls/BeepName.xaml — the default style -->
<Style TargetType="{x:Type beep:BeepName}">
    <Setter Property="Background" Value="{DynamicResource BeepName.Background}"/>
    <Setter Property="Foreground" Value="{DynamicResource BeepName.Foreground}"/>
    <Setter Property="Padding"    Value="{DynamicResource BeepName.Padding}"/>
    <Setter Property="Template">
        <Setter.Value>
            <ControlTemplate TargetType="{x:Type beep:BeepName}">
                <Border x:Name="RootBorder"
                        Background="{TemplateBinding Background}"
                        BorderBrush="{DynamicResource BeepName.BorderBrush}"
                        BorderThickness="{DynamicResource BeepName.BorderThickness}"
                        CornerRadius="{DynamicResource BeepName.CornerRadius}"
                        Padding="{TemplateBinding Padding}">
                    <ContentPresenter VerticalAlignment="Center"/>
                </Border>
            </ControlTemplate>
        </Setter.Value>
    </Setter>
</Style>