Tag Archives: Actions

Caliburn Micro Part 3: Actions

1 Reply

Welcome to the third part of this tutorial on the basics of Caliburn Micro, in the previous part we saw how to do some basic databinding and eventing. In this next part we will go through the basics of actions.

Long Syntax

Last time we saw how to bind the click event of a button to a function in the associated View Model, by setting the name of the button to the name of the function. This works well if you only want to bind to the default event but what if you wanted to bind to a different event or even pass parameters?

Lets start by changing out previous example to use the long syntax. Edit the xaml in ShellView to look as follows.

<Grid>
    <Button Content="Press Me" VerticalAlignment="Top">
        <i:Interaction.Triggers>
            <i:EventTrigger EventName="Click">
                <cal:ActionMessage MethodName="ChangeMessage" />
            </i:EventTrigger>
        </i:Interaction.Triggers>
    </Button>
    <TextBlock x:Name="Message" VerticalAlignment="Center" HorizontalAlignment="Center" />
</Grid>

You’ll need to add these two namespace references as well.

xmlns:cal="http://www.caliburnproject.org"
xmlns:i="clr-namespace:System.Windows.Interactivity;assembly=System.Windows.Interactivity"

If you run the app now you should see that it runs exactly the same as before. All we have done here is explicitly say which event we are listening for and which function in the View Model should be called.

Next lets look at how we can pass parameters with the action message, modify ShellView as follows so that it passes a parameter when the button is clicked.

<Button Content="Press Me" VerticalAlignment="Top">
    <i:Interaction.Triggers>
        <i:EventTrigger EventName="Click">
            <cal:ActionMessage MethodName="ChangeMessage">
                <cal:Parameter Value="2" />
            </cal:ActionMessage>
        </i:EventTrigger>
    </i:Interaction.Triggers>
</Button>

Next edit the ChangeMessage function in ShellViewModel so that it takes an integer parameter.

public void ChangeMessage(int incrementBy)
{
    _pressCount += incrementBy;

    Message = "Presses = " + _pressCount;
}

If you run the app again you should notice that the count is now increased by two, this is because when the button is clicked it sends the action message to the View Model with the specified parameter which is then added to the count.

Short Syntax

If the above seemed like a quite a lot of xaml it can be shorted by using the short action message syntax. We can achieve what we did before by modifying ShellView like below.

<Button Content="Press Me" VerticalAlignment="Top" cal:Message.Attach="[Event Click] = [Action ChangeMessage(2)]" />

What we have done here is use one of Caliburn Micros attached properties to achieve the same as we did before but with much less xaml. I like this method as it simplifies the code somewhat, but in more complex cases it may be clearer to use the longer syntax.

In addition to passing literal values and binding expressions as parameters it is also possible to pass some special values that allow you access to some convenient information. These are as follows:

$eventArgs
Passes the EventArgs or input parameter to your Action.
$dataContext
Passes the DataContext of the element that the ActionMessage is attached to.
$source
The actual FrameworkElement that triggered the ActionMessage to be sent.
$view
The view (usually a UserControl or Window) that is bound to the ViewModel.
$executionContext
The action’s execution context, which contains all the above information and more.
$this
The actual UI element to which the action is attached. In this case, the element itself won’t be passed as a parameter, but rather its default property.

That’s it for this tutorial join us next time for a look at the Event Aggregator.