Caliburn Micro Part 2: The Basics of Databinding

Welcome to the second part of this tutorial on the basics of Caliburn Micro, in the previous part we saw how to setup a new project from scratch and display a window to the user. In this next part we will go through the basics of databinding which is where the true power of Caliburn Micro comes into play. We will be building upon the example shown in the previous part of this tutorial by adding some new functionality to it.

Databinding

Lets start simple by showing some text to the user. Extend ShellViewModel as shown below by adding a string property and setting it to HelloWorld in the constructor. Notice that we are now inheriting from PropertyChangedBase and we’ve added a call to NotifyOfPropertyChange in the setter of the property. PropertyChangedBase gives us access to NotifyOfPropertyChange which tells the view that it should display the new value every time the Message property is changed. This saves us from having to implement the INotifyPropertyChanged interface in all of our ViewModels.

using Caliburn.Micro;

namespace CaliburnMicroExample
{
    public class ShellViewModel : PropertyChangedBase
    {
        private string _message;

        public string Message
        {
            get { return _message; }
            set
            {
                _message = value;
                NotifyOfPropertyChange(() => Message);
            }
        }

        public ShellViewModel()
        {
            Message = "Hello World";
        }
    }
}

Next lets add a TextBlock to ShellView so that it can display our message to the user.

<Grid>
    <TextBlock x:Name="Message" VerticalAlignment="Center" HorizontalAlignment="Center" />
</Grid>

Now if you run up the application you should see a small windows with the text Hello World in the centre. By just giving the TextBlock the same name as out property Caliburn Micro automatically binds them together for us. This is not the only way to do it however, you could do it the traditional way by binding to the Text property of the TextBlock.

<Grid>
    <TextBlock Text="{Binding Message}" VerticalAlignment="Center" HorizontalAlignment="Center" />
</Grid>

Events

Now lets look at how Caliburn Micro handles events, in order to do this we will add a button to our application that lets us change the current text. First add a new function to ShellViewModel that changes the message as shown below.

using Caliburn.Micro;

namespace CaliburnMicroExample
{
    public class ShellViewModel : PropertyChangedBase
    {
        private string _message;

        public string Message
        {
            get { return _message; }
            set
            {
                _message = value;
                NotifyOfPropertyChange(() => Message);
            }
        }

        private int _pressCount;

        public ShellViewModel()
        {
            Message = "Hello World";
            _pressCount = 0;
        }

        public void ChangeMessage()
        {
            _pressCount++;

            Message = "Presses = " + _pressCount;
        }
    }
}

Now add a button to ShellView as shown below.

<Grid>
    <Button x:Name="ChangeMessage" Content="Press Me" VerticalAlignment="Top" />
    <TextBlock x:Name="Message" VerticalAlignment="Center" HorizontalAlignment="Center" />
</Grid>

That’s all there is to it, if you run the application now you should see that pressing the button changes the message displayed. The binding is achieved in pretty much the same way as with the TextBlock, Caliburn Micro looks for a function in the ViewModel with the same name as the Button and binds the two together so that the function is called on the button press. There are additional ways to do this which give you more control but we’ll look at those in a future tutorial.

Event Guards

The last thing we are going to cover in this tutorial is event guards. Event guards are used to only allow the handling of an event if a certain condition is met. To demonstrate this we will prevent the user from pressing the button more than 10 times. Add a new property to ShellViewModel called CanChangeMessage and also add a new NotifyOfPropertyChange to the Message setter.

public string Message
{
    get { return _message; }
    set
    {
        _message = value;
        NotifyOfPropertyChange(() => Message);
        NotifyOfPropertyChange(() => CanChangeMessage);
    }
}

public bool CanChangeMessage
{
    get { return _pressCount < 10; }
}

Now when you run the code you should see that the button becomes disabled after it has been pressed 10 times. Every time Caliburn Micro hooks up an event is also looks for a property with the same name plus the word can before it. It then uses the Boolean result of the property to determine whether the event should be handled or not. So in this case once the press count has reached 10 the property will always return false meaning no new click events will be handled and Caliburn Micro automatically disables the button for us.

In the next part of this blog series I will go through how Actions work in Caliburn Micro.