Simplest WPF Dependency Property For Beginners On Background Color

Perhaps you know what a Dependency property is and how it is more advanced than native CLR properties. If not, let me know. I will try to explain.

FYI

The dependency property is not wrapped around any private members unlike CLR properties, and it is also stored in Key-Value pairs inside the DependencyObject host instance. You must use Dependency properties if you need to create and apply properties on custom user controls, or change properties based on external inputs like Theme, Style, animation etc., or while applying the data binding or set with a resource (static/dynamic).

Now, I will try to create a Dependency property which will help you begin the implementation of Dependency property and implementations in WPF.

First, create a project of type WPF Application in Visual Studio with name DependencyPropertyTutorial. As we haven't yet created any user control, so our next step is to create a custom User Control in WPF.

Add a new item of type User Control (WPF) to the project and give the name CustomButtonControl. We will now embed a button inside this control through code. Name of the button is btnCustom.

xaml code: CustomButtonControl.xaml

<UserControl x:Class="DependencyPropertyTutorial.CustomButtonControl" xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:d="http://schemas.microsoft.com/expression/blend/2008" xmlns:local="clr-namespace:DependencyPropertyTutorial" mc:Ignorable="d" d:DesignHeight="100" d:DesignWidth="100">
    <Grid>
        <Button x:Name="btnCustom" Content="Button" HorizontalAlignment="Left" Margin="10,10,0,0" VerticalAlignment="Top" Width="75" Height="52" Click="btnCustom_Click" /> </Grid>
</UserControl>

The basic essence of Dependency Property is that we can create these custom dependency properties for our custom user controls. That's why we have created this user control in order to test the dependency property in it.

So far, I haven't created any dependency property.

Now, I will.

In the code-behind: CustomButtonControl.xaml.cs

using...namespace DependencyPropertyTutorial {
    /// <summary>
    /// Interaction logic for CustomButtonControl.xaml
    /// </summary>
    public partial class CustomButtonControl: UserControl {
        public CustomButtonControl() {
            InitializeComponent();
        }
        public static readonly DependencyProperty btnDependencyProperty = DependencyProperty.Register("SetBackground", typeof(SolidColorBrush), typeof(CustomButtonControl), new PropertyMetadata(new SolidColorBrush(Colors.HotPink), new PropertyChangedCallback(OnSetColorChanged)));
        public SolidColorBrush SetBackground {
            set {
                SetValue(btnDependencyProperty, value);
            }
            get {
                return (SolidColorBrush) GetValue(btnDependencyProperty);
            }
        }
        private void btnCustom_Click(object sender, RoutedEventArgs e) {
            this.SetBackground = new SolidColorBrush(Colors.IndianRed);
        }
        private static void OnSetColorChanged(DependencyObject d, DependencyPropertyChangedEventArgs e) {
            CustomButtonControl mycontrol = d as CustomButtonControl;
            mycontrol.callmyInstanceMethod(e);
        }
        private void callmyInstanceMethod(DependencyPropertyChangedEventArgs e) {
            btnCustom.Background = (SolidColorBrush) e.NewValue;
        }
    }
}

Explanation

Custom Dependency property is created using the DependencyProperty.Register() method which takes few arguments --> Name of the property, Type of the values the property accepts,  Type of the owner that hosts the property, and a PropertyMetadata instance with DefaultValue, and PropertyChangedCallback parameters set. DefaultValue is the default value the porperty holds.

And PropertyChangedCallback represents the callback that is invoked when the effective property value of this dependency property changes.

Now, as explained earlier, the Dependency property is wrapped around the inner DependencyObject implementation using a set of getter & setter methods.

When the dependency property value is about to change,  OnSetColorChanged() is called. But as it's a static method, we need to create an instance of the UserControl and then call any of its Instance methods (here its callmyInstanceMethod) where we can reference its embedded Button and set its Background.

Notice how we cast the DependencyObject as CustomButtonControl, and how we used DependencyPropertyChangedEventArgs e.NewValue and cast it to SolidBrushColor which is the Type of the dependency property. 

Our UserControl along with the Dependency property is ready for use. Now, it's time to test it.

Let's come down to the MainWindow.xaml where we will include this User Control and set its Dependency Property with an appropriate value.

MainWindow.xaml

<Window x:Class="DependencyPropertyTutorial.MainWindow" 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:views="clr-namespace:DependencyPropertyTutorial" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:local="clr-namespace:DependencyPropertyTutorial" mc:Ignorable="d" Title="MainWindow" Height="350" Width="525">
    <Window.Resources>
        <SolidColorBrush x:Key="BG" Color="Green" /> </Window.Resources>
    <Grid>
        <views:CustomButtonControl SetBackground="{DynamicResource BG}"></views:CustomButtonControl>
    </Grid>
</Window>

Explanation

Pretty simple and self-explanatory! Just a thing for newbies - in WPF, if you are not so familiar with WPF resources, just read about Window.Resources. We set a SolidColorBrush with Color Green as this WPF Window resource. Now, we can access this resource throughout the XAML. In the Grid, we have put a CustomButtonControl and called the DependencyProperty SetBackground with value {DynamicsResource BG}. This is also known as WPF Binding and it gets the value dynamically (i.e. at runtime) from the resource we defined.

Now, guys, you can download the source code or copy-paste the source code given here and compile it. It will compile with no issues. Then, run it.

Start painting the buttons with your favorite colors.