WPF Control Authoring Guide

A guide for decision-making when authoring WPF controls.

1. Do You Need a New Control?

Review alternatives first. Thanks to WPF's extensibility, most requirements can be solved without creating a new control.

Requirement Alternative Example

Change appearance only Style Unify TextBlock to red Arial 14pt

Change control structure ControlTemplate Make RadioButton look like traffic light

Change data display method DataTemplate Add checkbox to ListBox items

Change state-based behavior Trigger Make selected item bold red

Display composite content Rich Content Show image+text together in Button

When a new control is needed:

• New functionality/behavior not available in existing controls

• Reusable composite components

• Special input/interaction patterns

2. Base Class Selection

┌─────────────────────────────────────────────────────────────┐ │ Control Type Decision │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ │ │ UserControl │ │ Control │ │ FrameworkElement│ │ │ └──────┬──────┘ └──────┬──────┘ └────────┬────────┘ │ │ │ │ │ │ │ Combine existing ControlTemplate Direct rendering │ │ Quick development Customization Full control │ │ No template Theme support Performance │ │ optimization │ └─────────────────────────────────────────────────────────────┘

UserControl Selection Criteria

• ✅ Combining existing controls is sufficient

• ✅ Prefer application-like development approach

• ✅ ControlTemplate customization not needed

• ❌ Theme support not needed

Control Selection Criteria (Recommended)

• ✅ Need appearance customization via ControlTemplate

• ✅ Need various theme support

• ✅ Need WPF built-in control level extensibility

• ✅ Complete separation of UI and logic

FrameworkElement Selection Criteria

• ✅ Appearance not achievable by simple element composition

• ✅ Need direct rendering via OnRender

• ✅ Custom composition based on DrawingVisual

• ✅ Extreme performance optimization needed

3. Principles for Designing Stylable Controls

3.1 Don't Strictly Enforce Template Contract

// ❌ Wrong: Throws exception if Part is missing public override void OnApplyTemplate() { var button = GetTemplateChild("PART_Button") as Button; if (button == null) throw new InvalidOperationException("PART_Button required!"); }

// ✅ Correct: Works even if Part is missing public override void OnApplyTemplate() { base.OnApplyTemplate(); ButtonElement = GetTemplateChild("PART_Button") as Button; // If null, only that feature is disabled, control continues to work }

Core Principles:

• ControlTemplate may be incomplete at design time

• Panel doesn't throw exceptions for too many or too few children

• If required elements are missing, only disable that feature

3.2 Helper Element Patterns

Type Description Example

Standalone Independent, reusable Popup, ScrollViewer, TabPanel

Type-based Recognizes TemplatedParent, auto-binding ContentPresenter, ItemsPresenter

Named Referenced in code via x:Name PART_TextBox, PART_Button

// Type-based: ContentPresenter automatically binds to TemplatedParent.Content <ContentPresenter />

// Named: Direct reference needed in code <TextBox x:Name="PART_EditableTextBox" />

3.3 State/Behavior Expression Priority

Prefer higher items:

• Property Binding - ComboBox.IsDropDownOpen ↔ ToggleButton.IsChecked

• Trigger/Animation - Background color change on Hover state

• Command - ScrollBar.LineUpCommand

• Standalone Helper - TabPanel in TabControl

• Type-based Helper - ContentPresenter in Button

• Named Helper - TextBox in ComboBox

• Bubbled Event - Event bubbling from Named element

• Custom OnRender - ButtonChrome in Button

4. DependencyProperty Implementation

DependencyProperty is required to support styles, bindings, animations, and dynamic resources.

public static readonly DependencyProperty ValueProperty = DependencyProperty.Register( nameof(Value), typeof(int), typeof(NumericUpDown), new FrameworkPropertyMetadata( defaultValue: 0, propertyChangedCallback: OnValueChanged, coerceValueCallback: CoerceValue));

public int Value { get => (int)GetValue(ValueProperty); set => SetValue(ValueProperty, value); }

// ⚠️ Don't add logic to CLR wrapper! It's bypassed during binding // Use callbacks instead: private static void OnValueChanged(DependencyObject d, DependencyPropertyChangedEventArgs e) { }

private static object CoerceValue(DependencyObject d, object value) => Math.Clamp((int)value, 0, 100);

5. RoutedEvent Implementation

Use RoutedEvent to support bubbling, EventSetter, and EventTrigger.

public static readonly RoutedEvent ValueChangedEvent = EventManager.RegisterRoutedEvent( nameof(ValueChanged), RoutingStrategy.Bubble, typeof(RoutedPropertyChangedEventHandler<int>), typeof(NumericUpDown));

public event RoutedPropertyChangedEventHandler<int> ValueChanged { add => AddHandler(ValueChangedEvent, value); remove => RemoveHandler(ValueChangedEvent, value); }

protected virtual void OnValueChanged(RoutedPropertyChangedEventArgs<int> e) => RaiseEvent(e);

6. Customization Support Strategy

┌────────────────────────────────────────────────────────────┐ │ Exposure Strategy by Customization Frequency │ ├────────────────────────────────────────────────────────────┤ │ │ │ Very Frequent → Expose as DependencyProperty │ │ (Background, Foreground, etc.) │ │ │ │ Sometimes → Expose as Attached Property │ │ (Grid.Row, Canvas.Left, etc.) │ │ │ │ Rarely → Guide to redefine ControlTemplate │ │ (Documentation required) │ │ │ └────────────────────────────────────────────────────────────┘

7. Theme Resource Organization

📁 Themes/ ├── Generic.xaml ← Default (required) ├── Aero.NormalColor.xaml ← Windows Vista/7 ├── Luna.NormalColor.xaml ← Windows XP Blue ├── Luna.Homestead.xaml ← Windows XP Olive └── Luna.Metallic.xaml ← Windows XP Silver

Add ThemeInfo to AssemblyInfo.cs:

[assembly: ThemeInfo( ResourceDictionaryLocation.SourceAssembly, // Theme-specific resources ResourceDictionaryLocation.SourceAssembly)] // Generic resources

Set DefaultStyleKey in static constructor:

static NumericUpDown() { DefaultStyleKeyProperty.OverrideMetadata( typeof(NumericUpDown), new FrameworkPropertyMetadata(typeof(NumericUpDown))); }

Decision Checklist

Before Creating a New Control

• Can it be solved with Style?

• Can it be solved with ControlTemplate?

• Can it be solved with DataTemplate?

• Can it be solved with Trigger?

• Can it be solved with Rich Content?

Base Class Selection

• Need ControlTemplate customization? → Control

• Need theme support? → Control

• Combining existing controls is sufficient? → UserControl

• Need direct rendering? → FrameworkElement

Control Design

• Did you minimize Template Contract?

• Does it work even if Part is missing?

• Handling with feature disable instead of exception?

• Did you follow state expression priority?

Properties/Events

• Are style/binding supporting properties DependencyProperty?

• Is there no logic in CLR wrapper?

• Are events implemented as RoutedEvent?

Theme/Resources

• Is there a default style in Generic.xaml?

• Did you set ThemeInfo attribute?

• Did you set DefaultStyleKey?