Introduction To Dependency Properties of WPF

http://www.switchonthecode.com/tutorials/wpf-tutorial-introduction-to-dependency-properties
So I was going to dive right in and do a part 2 on the WPF ListView tutorial
from last week, but as I was writing the code I realized that a lot of
it relies on some new and very different constructs that WPF provides to
developers. Two of these are deep enough topics on their own that I
thought it would be a good idea to give an introduction to them before I
dove back into the ListView stuff. So today we are going to talk about
Dependency Properties, and in a future tutorial I will talk about how
binding works in WPF.

What are dependency properties? The quick definition from the MSDN docs
says that a dependency property is a "property that is backed by the
WPF property system." Not really a great one-line explanation, but
really, I can't blame them. I can't come up with a good one line
explanation either. But essentially, it gives you a bunch of
infrastructure to do all the things that you often want to do with a
normal property - validate it, coerce it into a proper range, give out
change notifications, and a number of other aspects. We aren't going to
touch on everything that a dependency property can do today - because
there is a lot. But we will be talking about how to use them, how to
create them, and how to set up validation/coercion/change notification.

So one of the first things I thought was weird about the definition
of a dependency property is that it is a static. This didn't make sense
to me at first - this property needs to store info relevant to a
particular instance of a class, how is it going to do that if it is
static? But then, as I read more about them, I realized that a
dependency property definition was exactly that - a definition. You are
essentially saying that class A will have a property B - and it makes
sense that that definition would be static. The actual storage of a
value for a dependency property is deep inside the WPF property system -
you never have to worry about it.

One thing you do have to note, though, is that for a class to contain dependency properties, it has to in some way derive from DependencyObject. In deriving from this class, you get all the infrastructure needed to participate in the WPF dependency property system.

So at first glance, all the properties on the new WPF controls seem
to be regular old properties. But don't be fooled - this is often just a
simple wrapper around a dependency property (and the documentation will
usually say this). So what does it mean for a property to be a simple
wrapper around a dependency property? Lets look at the FrameworkElement.Height property as an example:

public double Height

{

get

{

return (double)GetValue(HeightProperty);

}

set

{

SetValue(HeightProperty, value);

}

}
Your first two questions are probably "What are these

GetValue

and

SetValue

functions?" and "What is this

HeightProperty

?", and those are very good questions indeed. Well,

GetValue

and

SetValue

are functions you get by deriving from

DependencyObject

. They allow you, as you might have guessed, to get and set the values of dependency properties. The

HeightProperty

is the dependency property itself - the static definition part of the

FrameworkElement

class.

So far, this is just added complexity, and you're wondering why there
is yet another level of indirection on things. But here is where
things get interesting. In the "old ways", to set up some sort of
change notification on the

Height

property here, you would have had to override it in a new class deriving from this

FrameworkElement

class and added whatever you needed in the 'set' part of the property
here. However, you no longer have to do things like that. Instead, you
can:

FrameworkElement myElement;

//

// myElement gets set to an element

//

DependencyPropertyDescriptor dpd;

dpd = DependencyPropertyDescriptor.FromProperty(

FrameworkElement.HeightProperty, typeof(FrameworkElement))

dpd.AddValueChanged(myElement, myHeightChangedFunction);
And now you have a function that will get called any time the height changes on

myElement

! I think that is pretty handy. You can detach the hook just as easily:

DependencyPropertyDescriptor dpd;

dpd = DependencyPropertyDescriptor.FromProperty(

FrameworkElement.HeightProperty, typeof(FrameworkElement))

dpd.RemoveValueChanged(myElement, myHeightChangedFunction);
Ok, enough about other people's dependency properties - lets go make
our own! Below we have a extremely simple class with a dependency
property for "LastName", as well as a property wrapper around it:

public class Person : DependencyObject

{

public static readonly DependencyProperty LastNameProperty =

DependencyProperty.Register("LastName", typeof(string), typeof(Person));

public string LastName

{

get

{

return (string)GetValue(LastNameProperty);

}

set

{

SetValue(LastNameProperty, value);

}

}

}
The

Register

call is pretty simple - you give the
property a name (in this case "LastName"), you say what type of
information the property will hold (in this case a string), and you say
what type of object this property is attached to (in this case Person).
A little verbose, especially when you add in the property wrapper, but
not too bad. And I'm sure Microsoft will find a way to streamline the
syntax in the next version of C#.

A little bit of a side note here - don't ever put anything but the

GetValue

and

SetValue

calls inside the property wrapper. This is because you never know if
someone will set the property through the wrapper, or straight through a

SetValue

call - so you don't want to put any extra logic
in the property wrapper. For example, when you set the value of a
dependency property in XAML, it will not use the property wrapper - it
will hit the

SetValue

call directly, bypassing anything that you happened to put in the property wrapper.

Back to creating dependency properties. The constructor for

Register

has a couple more optional arguments. And we are going to jump right in and use them all!

public class Person : DependencyObject

{

public static readonly DependencyProperty LastNameProperty =

DependencyProperty.Register("LastName", typeof(string), typeof(Person),

new PropertyMetadata("No Name", LastNameChangedCallback, LastNameCoerceCallback),

LastNameValidateCallback);

private static void LastNameChangedCallback(

DependencyObject obj, DependencyPropertyChangedEventArgs e)

{

Console.WriteLine(e.OldValue + " " + e.NewValue);

}

private static object LastNameCoerceCallback(DependencyObject obj, object o)

{

string s = o as string;

if (s.Length > 8)

s = s.Substring(0, 8);

return s;

}

private static bool LastNameValidateCallback(object value)

{

return value != null;

}

public string LastName

{

get

{

return (string)GetValue(LastNameProperty);

}

set

{

SetValue(LastNameProperty, value);

}

}

}
The two other arguments to

Register

are a

PropertyMetadata

instance and a

validateValueCallback

. There are a couple different classes that derive from

PropertyMetadata

, but today we are just using the base one. The

PropertyMetadata

instance allows us to set a default value (in this case "No Name"), a property changed callback (

LastNameChangedCallback

), and a coerce value callback (

LastNameCoerceCallback

).
The default value does exactly what you might expect. The change
callback can do whatever you want it to do, and you have plenty of
information with which to do it. The

DependencyPropertyChangedEventArgs

contain both the old and the new values of the property, as well as a reference to what property was changed. And the

DependencyObject

passed in is the object on which the property was changed. This is
needed because, as you can see, this method is static. So every time
the "LastName" property is changed on any object, this function will get
called.

The same goes for the coerce callback - we get the object on which
the property is being changed, and the possible new value. Here we get
the opportunity to change the value - in this case, apparently last
names are forced to be 8 characters or less.

And finally, we have the

LastNameValidateCallback

. This
just gets the possible new value, and returns true or false. If it
returns false, an exception is blown - so in this case, if anyone ever
tries to set a null last name, they better watch out.

So there you go, the basics on dependency property usage and
creation. There are a couple areas I haven't covered - inheritance,
attached properties, and overriding metadata to name a few. But
hopefully this gets off on the right foot with respect to dependency
properties, and I'll probably write a tutorial in the next few weeks on
those other areas. As always, questions and comments are welcome.