WPF CustomControl Development - Parts and States Model

Workflow for developing WPF CustomControls with appearance customization capability.

Development Flow

1. Control Inheritance Decision

UserControl Selection Criteria:
- Need rapid development
- ControlTemplate customization not required
- Complex theme support not required

Control Inheritance Selection Criteria:
- Need appearance customization via ControlTemplate
- Need various theme support
- Need same extensibility as WPF built-in controls

2. Define Control Contract

Declare TemplatePart and TemplateVisualState attributes on the class:

[TemplatePart(Name = PartUpButton, Type = typeof(RepeatButton))]
[TemplatePart(Name = PartDownButton, Type = typeof(RepeatButton))]
[TemplateVisualState(Name = StatePositive, GroupName = GroupValueStates)]
[TemplateVisualState(Name = StateNegative, GroupName = GroupValueStates)]
[TemplateVisualState(Name = StateFocused, GroupName = GroupFocusStates)]
[TemplateVisualState(Name = StateUnfocused, GroupName = GroupFocusStates)]
public class NumericUpDown : Control
{
    // Define Part/State names as const
    private const string PartUpButton = "PART_UpButton";
    private const string PartDownButton = "PART_DownButton";
    private const string GroupValueStates = "ValueStates";
    private const string GroupFocusStates = "FocusStates";
    private const string StatePositive = "Positive";
    private const string StateNegative = "Negative";
    private const string StateFocused = "Focused";
    private const string StateUnfocused = "Unfocused";
}

3. Template Part Property Pattern

Wrap Part elements as private properties, subscribe/unsubscribe events in setter:

private RepeatButton? _upButton;
private RepeatButton? UpButtonElement
{
    get => _upButton;
    set
    {
        // Unsubscribe from existing element's events
        if (_upButton is not null)
            _upButton.Click -= OnUpButtonClick;

        _upButton = value;

        // Subscribe to new element's events
        if (_upButton is not null)
            _upButton.Click += OnUpButtonClick;
    }
}

4. OnApplyTemplate Implementation

public override void OnApplyTemplate()
{
    base.OnApplyTemplate();

    // GetTemplateChild + as cast (null on type mismatch)
    UpButtonElement = GetTemplateChild(PartUpButton) as RepeatButton;
    DownButtonElement = GetTemplateChild(PartDownButton) as RepeatButton;

    // Set initial state (without transition)
    UpdateStates(useTransitions: false);
}

Core Principles:

• If Part is missing or type differs, it's null → don't cause errors
• Control must work even with incomplete ControlTemplate

5. UpdateStates Helper Method

Centralize state transition logic in a single method:

private void UpdateStates(bool useTransitions)
{
    // ValueStates group
    VisualStateManager.GoToState(this,
        Value >= 0 ? StatePositive : StateNegative,
        useTransitions);

    // FocusStates group
    VisualStateManager.GoToState(this,
        IsFocused ? StateFocused : StateUnfocused,
        useTransitions);
}

When to call UpdateStates:

• OnApplyTemplate - Initial state (useTransitions: false)
• Property changed callback - Reflect value change (useTransitions: true)
• OnGotFocus/OnLostFocus - Focus state (useTransitions: true)

6. Property Changed Callback

private static void OnValueChanged(DependencyObject d,
    DependencyPropertyChangedEventArgs e)
{
    var control = (NumericUpDown)d;
    control.UpdateStates(useTransitions: true);
    control.OnValueChanged(new ValueChangedEventArgs((int)e.NewValue));
}

7. ControlTemplate Structure (Generic.xaml)

<Style TargetType="{x:Type local:NumericUpDown}">
  <Setter Property="Template">
    <Setter.Value>
      <ControlTemplate TargetType="{x:Type local:NumericUpDown}">
        <Grid Background="{TemplateBinding Background}">

          <!-- Place VisualStateGroups on root element -->
          <VisualStateManager.VisualStateGroups>
            <VisualStateGroup x:Name="ValueStates">
              <VisualState x:Name="Positive"/>
              <VisualState x:Name="Negative">
                <Storyboard>
                  <ColorAnimation To="Red"
                    Storyboard.TargetName="ValueText"
                    Storyboard.TargetProperty="(Foreground).(SolidColorBrush.Color)"/>
                </Storyboard>
              </VisualState>
            </VisualStateGroup>

            <VisualStateGroup x:Name="FocusStates">
              <VisualState x:Name="Focused">
                <Storyboard>
                  <ObjectAnimationUsingKeyFrames
                    Storyboard.TargetName="FocusVisual"
                    Storyboard.TargetProperty="Visibility">
                    <DiscreteObjectKeyFrame KeyTime="0" Value="{x:Static Visibility.Visible}"/>
                  </ObjectAnimationUsingKeyFrames>
                </Storyboard>
              </VisualState>
              <VisualState x:Name="Unfocused"/>
            </VisualStateGroup>
          </VisualStateManager.VisualStateGroups>

          <!-- Define Part elements with x:Name -->
          <RepeatButton x:Name="PART_UpButton" Content="▲"/>
          <TextBlock x:Name="ValueText" Text="{TemplateBinding Value}"/>
          <RepeatButton x:Name="PART_DownButton" Content="▼"/>

        </Grid>
      </ControlTemplate>
    </Setter.Value>
  </Setter>
</Style>

Checklist

• [ ] Inherit from Control class (not UserControl)
• [ ] Add ThemeInfo attribute to AssemblyInfo.cs → See /configuring-wpf-themeinfo
• [ ] Declare required Parts with TemplatePart attribute
• [ ] Declare states with TemplateVisualState attribute
• [ ] Define Part/State names as const strings
• [ ] Subscribe/unsubscribe events in Part property setter
• [ ] Use GetTemplateChild + allow null in OnApplyTemplate
• [ ] Centralize state transitions with UpdateStates helper
• [ ] Place VisualStateManager.VisualStateGroups on ControlTemplate root
• [ ] Place default style in Themes/Generic.xaml
• [ ] Call DefaultStyleKeyProperty.OverrideMetadata in static constructor