User Controls and Dependency Properties - Page 5
       by kirupa  |  19 November 2007

In the previous page, you were promised that you would learn how to use your user control. While technically you did learn how to use your control, realistically, because of the extra functionality our user control has, we didn't get to use our user control to its full potential.

Exposing our User Control's Properties
When editing your user control by having InfoRectangle.xaml open in Blend, you have access to all of your user control's nested controls and their properties. When you place your user control somewhere else - such as Window1.xaml - you no longer have direct access to edit the user control's children controls. For example, when you select your InfoRectangle instance in Window1.xaml, you have no direct ability to see inside your control and pick out your InfoLabel's Content property or adjust your rectangle's background color.

Accessing User Control Properties via Code

Because a user control can be considered a class, you can access any of your user control's properties using code itself. For example, to change the value of your InfoRectangle user control's InfoLabel label's content, you could just do the following:

InfoRectangle foo = new InfoRectangle;
foo.InfoLabel.Content = "New Content!";

Of course, this isn't the best way to do this, for the clean separation between visual properties and code is one of the advantages of WPF. You will learn the better dependency property approach for accomplishing the same thing in the following pages.

There seems to exist a barrier that prevents you from accessing those properties that you could easily access when editing the user control itself. Of course, because we want each instance of our user control to have different text and background colors, we cannot edit InfoRectangle.xaml directly. Like you saw described in the first page, any modification you make to your user control's XAML or code-behind file automatically gets applied to all instances of the user control that exist in your project.

Fortunately, this is something that the WPF designers thought about, and a formal (very formal) mechanism exists for registering any properties you are interested in exposing to a parent that will be hosting your user control. Those properties are known as Dependency Properties, and you'll be introduced to them in greater detail shortly.

Exposing our InfoLabel's Text
One thing we want to do is make our InfoLabel editable by a parent such as Window1.xaml. In Blend, open or navigate to our InfoRectangle.xaml file. The text that is currently displayed is located in our InfoLabel's Content property:

[ your label's Content property is what determines what gets displayed ]

Remember that piece of information, for it will come in handy real soon. What we need to do now (unfortunately?) is write some code. Click on the Project tab, right click on your UserControlSample C# solution, and from the menu that appears, select Edit in Visual Studio:

[ we will need to edit our project in Visual Studio (or C# Express) ]

After a few moments, Visual Studio will launch. Once Visual Studio has launched, find the Solution Explorer on the top-right corner of your screen. This view is very similar to the Project view you see in Blend.

From the Solution Explorer, expand the InfoRectangle.xaml node to display the InfoRectangle.xaml.cs file:

[ your Solution Explorer displays all of the files currently used by your project ]

Double click on the InfoRectangle.xaml.cs file to open it in Visual Studio. Currently, this file doesn't really have much content. Let's change that. What we are going to do is create a dependency property  that allows you to easily change our user control's text. Don't worry if you are not sure what dependency properties are or what the following snippets of code mean. I will cover that in greater detail in the next page.

Add the following lines of code below your InfoRectangle constructor:

public string InfoText

{

get

{

return (string) GetValue(InfoTextProperty);

}

set

{

SetValue(InfoTextProperty, value);

}

}

 

public static readonly DependencyProperty InfoTextProperty =

   DependencyProperty.Register(

      "InfoText",

      typeof(string),

      typeof(InfoRectangle),

      new FrameworkPropertyMetadata(
         new PropertyChangedCallback(ChangeText)));

 

private static void ChangeText(DependencyObject source, DependencyPropertyChangedEventArgs e)

{

(source as InfoRectangle).UpdateText(e.NewValue.ToString());

}

 

private void UpdateText(string NewText)

{

InfoLabel.Content = NewText;

}

Once you have copied and pasted the above code, press F6 to make sure you are not receiving any build errors. On the next page, let's take a look at what happens in Blend, and more importantly, let's backtrack and revisit in detail the code you copied and pasted.

Onwards to the next page!

1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10