Notes on Dependency Objects

For the last several days ( yes – days! ) I have been trying to understand Dependency Objects as they relate to 3D graphics. I have been reading Ptezold’s 3D Programming for Windows as well as Applications = Code + Markup. I have also searched the internet for tutorials, the best of which was at: http://www.wpftutorial.net/DependencyProperties.html. I think the problem is that most discussions were overly complicated and perhaps not specific enough to what I was trying to do.

So here is my summary of what I learned relative to what I, myself, am trying to do right now! FYI – my current project is something that I call WoodCAD. It does a lot of 3D graphics and makes very heavy use of Dependency Objects.

 

Introduction to Dependency Objects

To a first approximation, just think of Dependency Objects as a way to define a property. They are fancy, but from the outside at least, they just look like a simple property. Once you have your head around that, understand that dependency properties also offer the following:

• Its data is stored not in the class that holds it, but rather in some sort of mysterious dictionary that you don’t really have to understand completely in order to use. Have some faith that the data is there somewhere.
• Dependency properties can only be used by a class that is descended from the Dependency Object class. That’s because its parent class provides a couple of methods that you need to use dependency properties
• Dependency Properties have a default value that is used if no other value has been explicitly assigned. Note that this is one value per class that does not need to be set in the instance can use the default value.
• You can specify a method that gets called whenever its value changes. This is the coolest thing about them and the main reason for using them here.
• You can specify a Coerce method that is applied to the value before you try to use it. A good example would be trimming a string to fit within a particular size. This is totally optional and I am not currently using it.
• You can specify a Validate method that tests the value and throws and error if it does not pass. The Validate method gets the new value after it has been processed by the Coerce method. Again, this is completely optional and I am not currently using it.
• · The last thing is that if the Dependency Property you are defining is itself a Dependency Object, then the Changed Method gets triggered if you change the entire object, or if you change any dependency objects within the Dependency Object. This is what hung me up and I will give an example so that you will wonder how it was ever confusing to me. See the section named Cascading Dependency Objects.

 

Setting up a simple Dependency Object

Let’s make up a Dependency Object named Length that will be a property of our class named MyClass.

Start with the property definition – sometimes called the CLR definition:

public double Length {
set {SetValue(LengthProperty, value);}
get {return (int)GetValue(LengthProperty);}
}

See – It’s just a simple property.

Get and Set Value are methods defined by Dependency Object from which the class you are working in must be extended. Length Property is defined as follows:

public static readonly DependencyProperty LengthProperty =
DependencyProperty.Register(
"Length",
typeof(double),
typeof(MyClass),
new PropertyMetadata(new Point3DCollection(), LengthPropertyChanged)
);

It seems to come from a kind of Property Factory. But no matter. You get it by registering it. It is an object instance in its own right and you feed it to the Get and Set Value methods.

The first parameter in the Register method is a string that must be the name of the property. Next is the type to be held in the Dependency Object. After that is the type of the class that is using it. Next is Property Metadata (more on that in the next paragraph.) I could also have included an optional Validation callback here, but did not.

Now, about Property Metadata: Property Metadata allows us to specify the default value (an empty Point 3D Collection) as well as the call back method. A third parameter of Property Metadata that we did not use here is the Coerce method which is a private static that returns object and expects a sender (Dependency Object) and a value (object) as parameters.

And more about the Validate Method: Note that this is an optional parameter of the Dependency Property Register method, rather than the Property Metadata constructor. This is a private static bool that expects a single object parameter holding the proposed new value. If this returns false, an exception is thrown.

This leaves the most interesting thing: the Length Property Changed method. First of all, this has to be static in order to access it from a static method. Fortunately, the callback sends us the object, so we can call the instance version of the method as follows:

static void LengthPropertyChanged(DependencyObject obj, DependencyPropertyChangedEventArgs args) {
(obj as MyClass).LengthPropertyChanged(args);
}

And Length Property Changed is just a regular old method that returns void. It is just that it gets called automatically whenever the Length changes.

Cascading Dependency Objects

This turns out to be incredibly easy to do. If the Dependency Object is of a type that is itself a Dependency Object, then the Change event gets triggered in either of two ways:

• If you reassign a new object instance to the Dependency Object, this triggers the changed method because the entire object has changed.
• If you change something within the dependency object, that triggers the changed method as well.

The example I tried was using a Point 3D Collection. Note that this is extended from Dependency Object. I used exactly the same patterns as for in the Length example above, except of course that the types are Point 3D Collection instead of double.

I found that the changed method was triggered if I assigned a completely new Point 3D Collection to the object. One would certainly expect that.

I also found that if I just added a point to the object, that too caused the changed method to run.

Note that changing an X, Y, or Z value on a particular point would not trigger the changed method because the Point 3D object is not a dependency object.

Setting up a Read-Only Dependency

Petzold’s book talks about Read Only Dependency Objects. An example of this is the Geometry property of the Shape Base class in my program. This is generated completely within each instance of the class and external programs simply read it. The constructor for the object initialized the value for the Geometry, but once this has been done, it is never changed. The collections within it are sometimes changed, but object holding the geometry is never changed. Therefore, there is no changed method defined for geometry; all the change methods are associated with the various parameters that can force an update to the geometry.

Why then should geometry even be a Dependency Object? The reason is that other 3D objects in the hierarchy are using this and watching it. If it changes, they have to run their own changed methods.

Here is the code that defines this read only Dependency Object:

public MeshGeometry3D Geometry {
protected set { SetValue(GeometryKey, value); }
get { return (MeshGeometry3D)GetValue(GeometryProperty); }
}

static DependencyPropertyKey GeometryKey =
DependencyProperty.RegisterReadOnly("Geometry",
typeof(MeshGeometry3D),
typeof(V3G_Shape_Base),
new PropertyMetadata(new MeshGeometry3D()));
public static readonly DependencyProperty GeometryProperty =
GeometryKey.DependencyProperty;

I got into trouble because I tried to use this pattern for a Point 3D Collection. It did not work. It turns out that I was making changes to the Collection, so this was not appropriate.

 

Applying Dependency Objects to Controls

The examples I found on this tend to involve their use with Controls. While these examples are interesting, they can also be a bit confusing since their emphasis is different. Here are some of the differences I found:

• The control examples tend to use Framework Property Metadata instead of just Property Metadata. This metadata has lots more information than the simple Property Metadata that I am using, including something called Inherits.
• Controls have a hierarchy that allows them to inherit values from higher level controls. For example, if a text block in a button has a font size property and the button has a font size property and the form has a font size, the font size that is actually used is selected from the most local control that actually has the property set. This is very important as regards controls and the Framework Property Metadata has some control over this, but I did not figure out whether this directly from Dependency Objects or from some fancy code somewhere in the classes between the controls and the Dependency Object class from which they are extended.