Lesson 20.2 – Binding a custom object’s properties to UI controls

Lesson Objectives

At the end of this lesson, you will know…

• How to use databinding to automatically update an object’s properties’ values to UI controls (labels)

Using databinding to connect values of an object’s properties to the UI

Right now, we have a lot of code in SuperAdventure.cs that reads from the Player object and modifies the labels, buttons, and datagrids in the UI. If we want to add more features to the program, we’ll need to copy that code in more places.

But, duplicating code is a bad programming habit.

If you have a lot of duplicated code, and you ever need to make a change, there’s a good chance you’ll miss one (or more) place. So we’ll use a technique that automatically handles updates, after writing a few lines of code – in one place.

We’ll do this with databinding.

Whenever a property is changed in the player object, the UI will be notified, and the UI will update the appropriate control (labels, for this lesson). Think of this as a “publish/subscribe” technique. The UI will “subscribe” to any changes of the properties, and the Player object will “publish” a notification/event when one of the values changes.

For this lesson, we’ll work with the integer properties: CurrentHitPoints, Gold, ExperiencePoints, and Level.

Step 1: Open the SuperAdventure solution in Visual Studio.

Step 2: For the UI to know when a value has changed, we need to send a notification from the player object.

Open the LivingCreature.cs class (since it’s the base class for Player, and holds the CurrentHitPoints property).

Change this line:

public class LivingCreature

To this:

public class LivingCreature : INotifyPropertyChanged

This change means that the LivingCreature class needs to implement the INotifyPropertyChanged interface. The INotifyPropertyChanged interface is what the .NET Framework uses for databinding notifications, when a property value changes.

Add this code to the LivingCreature class, to do the notification:

using System.ComponentModel;

and:

public event PropertyChangedEventHandler PropertyChanged;
protected void OnPropertyChanged(string name)
{
    if(PropertyChanged != null)
    {
        PropertyChanged(this, new PropertyChangedEventArgs(name));
    }
}

The PropertyChanged event is what the UI will “subscribe” to.

The OnPropertyChanged function checks if anything is subscribed to the event. If nothing is subscribed, then PropertyChanged will be null. If PropertyChanged is not null, then another class wants to be notified of changes, so the next line will run, and a PropertyChanged event will “be raised” (the notification will be sent out).

The final step in this class is to “raise the event”, when the CurrentHitPoints value changes. In order to do this, we need to call the OnPropertyChanged() function whenever the CurrentHitPoints value is set.

However, since CurrentHitPoints is an auto-property, we don’t have any place where we can stick in the code to call that function. So, we need to change it to a property with a backing variable.

Change, this:

public int CurrentHitPoints { get; set; }

To this:

private int _currentHitPoints;
public int CurrentHitPoints
{
    get { return _currentHitPoints; }
    set
    {
        _currentHitPoints = value;
        OnPropertyChanged("CurrentHitPoints");
    }
}

Now, the CurrentHitPoints property is a wrapper for the private variable “_currentHitPoints”. When the property is set to a value, the OnPropertyChanged() function will be run, the PropertyChanged event will be raised, and the UI will update the label.

Step 3: Now we need to make the changes to the other properties that will use databinding – the ones in the Player class. Open Player.cs and change the Gold and ExperiencePoints auto-properties to this:

private int _gold;
private int _experiencePoints;
public int Gold
{
    get { return _gold; }
    set
    {
        _gold = value;
        OnPropertyChanged("Gold");
    }
}
public int ExperiencePoints
{
    get { return _experiencePoints; }
    private set
    {
        _experiencePoints = value;
        OnPropertyChanged("ExperiencePoints");
        OnPropertyChanged("Level");
    }
}

Notice that the ExperiencePoints property raises a PropertyChanged event for both ExperiencePoints and Level. That’s because we never set the Level value. It’s always calculated from ExperiencePoints.

So, every time the ExperiencePoints property value changes, we’ll also send a notification to update the Level. We could change this to only send a notification when the level changes, but this extra notification won’t hurt us in a small program.

Also, the Player class is using the OnPropertyChanged() function in LivingCreature. That’s because Player inherits from the LivingCreature class. So, it can use any functions (and properties, and events) from LivingCreature – as long as they are scoped (visible) as “public”, “internal”, or “protected”.

Step 4: Open SuperAdventure.cs and change the constructor function to this:

public SuperAdventure()
{
    InitializeComponent();
    if(File.Exists(PLAYER_DATA_FILE_NAME))
    {
        _player = Player.CreatePlayerFromXmlString(File.ReadAllText(PLAYER_DATA_FILE_NAME));
    }
    else
    {
        _player = Player.CreateDefaultPlayer();
    }
    lblHitPoints.DataBindings.Add("Text", _player, "CurrentHitPoints");
    lblGold.DataBindings.Add("Text", _player, "Gold");
    lblExperience.DataBindings.Add("Text", _player, "ExperiencePoints");
    lblLevel.DataBindings.Add("Text", _player, "Level");
    MoveTo(_player.CurrentLocation);
}

The four new lines bind the labels to the properties.

To break down what’s happening, the first new line means this: For the lblHitPoints control, add a databinding – a “subscription” to a property’s “notifications”. The databinding will connect to the “Text” property of lblHitPoints to the “CurrentHitPoints” property of the “_player” object.

Notice that we added the databindings after we created the object. The object needs to be instantiated before you can bind to it.

We also removed the line that called the UpdatePlayerStats() function. We don’t need to call that method anymore. The databinding will automatically do that for us.

Remove the other lines where we call the UpdatePlayerStats() function. You can find all those places doing a search (Crtl-F).

Also remove any place where we set the “lblHitPoints.Text” property. We don’t need to manually set that value any more.

Step 5: Compile your program, run it, and make sure the labels in the UI update when you fight monsters.

Summary

Before, the UI would “push” values to the player object’s properties, then it would “pull” values from it, to update the UI.

Now, it still pushes values to the player object, but the player object “pushes” notifications of changes to the UI (and anything else that might be listening). This is one way of “decoupling” – making your program so the classes are more independent.

When your classes are more independent, it’s easier to make changes. You usually need to make fewer changes, in fewer places, when your code is not highly-coupled.

Source code for this lesson

Source code on GitHub

Source code on Dropbox

Next lesson: Lesson 20.3 – Binding list properties to datagridviews

Previous lesson: Lesson 20.1 – Refactoring the SuperAdventure program

All lessons: Learn C# by Building a Simple RPG Index