Custom Controls in WinUI

WinUI provides a rich set of built-in controls to build modern Windows applications. However, there are times when you need to create controls that are unique to your application's design or functionality. This document guides you through the process of creating custom controls in WinUI, leveraging its powerful templating and extensibility features.

Understanding Control Templating

At the heart of WinUI's customization lies the concept of Control Templates. A Control Template defines the visual structure and appearance of a control, allowing you to completely redefine how a control looks without changing its behavior.

When to Use Custom Controls

Unique visual branding requirements.
Combining multiple standard controls into a single reusable component.
Implementing entirely new interaction paradigms.
Optimizing performance for specific use cases.

Methods for Creating Custom Controls

1. Template Overrides

The simplest way to customize a control is to override its default template. This is useful when you want to alter the appearance of an existing control significantly.

For example, to change the appearance of a `Button`, you can define a new `ControlTemplate` for it:

XAML

<Page.Resources>
    <ControlTemplate x:Key="CustomButtonTemplate" TargetType="Button">
        <Border Background="{TemplateBinding Background}"
                BorderBrush="{TemplateBinding BorderBrush}"
                BorderThickness="{TemplateBinding BorderThickness}"
                CornerRadius="5"
                Padding="{TemplateBinding Padding}">
            <ContentPresenter HorizontalAlignment="Center"
                              VerticalAlignment="Center"
                              Content="{TemplateBinding Content}" />
        </Border>
    </ControlTemplate>
</Page.Resources>

<Button Template="{StaticResource CustomButtonTemplate}" Content="My Custom Button" />

2. Creating a New Control

For more complex scenarios, you might need to create a brand new control that inherits from existing WinUI base classes like `Control` or `UserControl`.

Inheriting from `Control`

This approach is ideal when you want to create a control with its own distinct properties, methods, and template. You define the control's logic in C# and its visual structure in XAML.

Note: When inheriting from `Control`, you are responsible for defining the control's default style and template.

Consider a simple `RatingControl` that displays a series of stars:

C# (RatingControl.cs)

using Microsoft.UI.Xaml;
using Microsoft.UI.Xaml.Controls;
using Microsoft.UI.Xaml.Media;
using System.Collections.Generic;
using System.Linq;

public class RatingControl : Control
{
    public static readonly DependencyProperty MaxRatingProperty =
        DependencyProperty.Register(nameof(MaxRating), typeof(int), typeof(RatingControl), new PropertyMetadata(5));

    public static readonly DependencyProperty CurrentRatingProperty =
        DependencyProperty.Register(nameof(CurrentRating), typeof(int), typeof(RatingControl), new PropertyMetadata(0, OnCurrentRatingChanged));

    private List<FontIcon> _starIcons;

    public int MaxRating
    {
        get { return (int)GetValue(MaxRatingProperty); }
        set { SetValue(MaxRatingProperty, value); }
    }

    public int CurrentRating
    {
        get { return (int)GetValue(CurrentRatingProperty); }
        set { SetValue(CurrentRatingProperty, value); }
    }

    public RatingControl()
    {
        this.DefaultStyleKey = typeof(RatingControl); // Points to generic.xaml
    }

    private static void OnCurrentRatingChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
    {
        var control = d as RatingControl;
        control?.UpdateStarAppearance();
    }

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

        // Find the container for stars in the template
        _starIcons = new List<FontIcon>();
        // Assuming you have a Grid or StackPanel with x:Name="StarContainer" in your template
        // You would typically find elements using GetTemplateChild or by iterating through visual tree.
        // For simplicity, let's assume we can directly access it if it's in the template.
        // In a real scenario, you'd use GetTemplateChild("StarContainer") and then populate it.

        // Placeholder for populating stars based on MaxRating
        // This part is usually done in the template XAML by defining the stars.
        // Let's simulate it here for demonstration if template doesn't auto-create.

        UpdateStarAppearance();
    }

    private void UpdateStarAppearance()
    {
        // This method would update the visual state of stars (e.g., change glyph or color)
        // based on CurrentRating and MaxRating. This logic is often driven by the template itself
        // using VisualStateManager and triggers bound to CurrentRating.
        // For example, if you have star elements in your template, you'd iterate and set their properties.
        // For simplicity, this is a conceptual representation.
        System.Diagnostics.Debug.WriteLine($"Rating updated to: {CurrentRating}");
    }
}

And its generic template in Themes/Generic.xaml:

XAML (Themes/Generic.xaml)

<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:YourAppNamespace"> <!-- Replace YourAppNamespace -->

    <Style TargetType="local:RatingControl">
        <Setter Property="Template">
            <Setter.Value>
                <ControlTemplate TargetType="local:RatingControl">
                    <StackPanel Orientation="Horizontal" Spacing="5">
                        <!--
                            In a real scenario, you would generate these FontIcons programmatically
                            or define them statically if the number of stars is fixed and known.
                            For dynamic generation, you'd typically have a code-behind method
                            to populate this panel based on MaxRating.
                        -->
                        <!-- Example for 5 stars -->
                        <FontIcon Glyph="" FontSize="20" Foreground="Gray" />
                        <FontIcon Glyph="" FontSize="20" Foreground="Gray" />
                        <FontIcon Glyph="" FontSize="20" Foreground="Gray" />
                        <FontIcon Glyph="" FontSize="20" Foreground="Gray" />
                        <FontIcon Glyph="" FontSize="20" Foreground="Gray" />
                    </StackPanel>
                </Setter.Value>
            </Setter>
        </Style>
</ResourceDictionary>

Inheriting from `UserControl`

Use `UserControl` when your custom control is essentially a composition of existing WinUI controls, and you want to encapsulate them with their own properties and events.

XAML (MyCompositeControl.xaml)

<UserControl x:Class="YourAppNamespace.MyCompositeControl"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
             xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
             mc:Ignorable="d"
             d:DesignHeight="50" d:DesignWidth="200"
             Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">

    <Grid Height="50">
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="Auto"/>
            <ColumnDefinition Width="*"/>
        </Grid.ColumnDefinitions>

        <TextBlock Text="{x:Bind LabelText}" VerticalAlignment="Center" Margin="0,0,10,0"/>
        <TextBox Grid.Column="1" Text="{x:Bind ValueText, Mode=TwoWay}" VerticalAlignment="Center"/>
    </Grid>
</UserControl>

C# (MyCompositeControl.xaml.cs)

using Microsoft.UI.Xaml.Controls;

namespace YourAppNamespace
{
    public sealed partial class MyCompositeControl : UserControl
    {
        public static readonly DependencyProperty LabelTextProperty =
            DependencyProperty.Register(nameof(LabelText), typeof(string), typeof(MyCompositeControl), null);

        public static readonly DependencyProperty ValueTextProperty =
            DependencyProperty.Register(nameof(ValueText), typeof(string), typeof(MyCompositeControl), null);

        public string LabelText
        {
            get { return (string)GetValue(LabelTextProperty); }
            set { SetValue(LabelTextProperty, value); }
        }

        public string ValueText
        {
            get { return (string)GetValue(ValueTextProperty); }
            set { SetValue(ValueTextProperty, value); }
        }

        public MyCompositeControl()
        {
            this.InitializeComponent();
        }
    }
}

Best Practices for Custom Controls

Follow WinUI Naming Conventions: Use PascalCase for properties and methods.
Use Dependency Properties: For properties that should be bindable, animatable, or styleable.
Leverage VisualStateManager: To define different visual states for your control (e.g., hover, pressed, disabled).
Keep Templates Clean: Separate concerns between control logic (C#) and presentation (XAML template).
Provide Clear Documentation: Explain how to use your custom control, its properties, and any special requirements.

Creating custom controls is a powerful way to tailor your WinUI applications. Experiment with templates and inheritance to build unique and engaging user experiences.