Data Grid Enhancements

The WPF Data Grid control in WPF Elements 5.1 is a much improved beast when compared with the 5.0 release. We had a lot of feedback from developers and we have been listening. Improvements in the 5.1 Data grid include:

• Grouping support with support for multi-level grouping and the ability to expand and collapse groups
• Exporting support (CSV exporting built in)
• Custom column sorting is supported
• Additional cell editing modes (e.g. double click to edit, etc)
• Row selection mode when clicking on a row header
• Support for hierarchical data in the same way as a TreeView control
• Allow users to add new rows which adds items to the underlying collection
• Binding to DataTable and IBindingList data sources is now supported
• RowHeaderTemplate support added for custom row headers
• ColumnHeaderTemplate support for custom column headers
• DataGrid.DisplayMemberBinding support for more complex binding scenarios without needing custom cell templates
• Background and foreground colors can be set for rows, columns or even individual cells
• Programmatically control scroll position (e.g. scroll to selected row, or end, etc)
• Auto sizing and * (star) sizing support for column widths

Of course these are just the key new features on top of our already super fast virtualized data grid engine.

Charting Enhancements

Along with the new charts detailed below, we made many improvements to the existing charts. The key focus for this release with regards to charts: Speed. LOTS OF SPEED. We already had pretty good charting performance (one customer compared against 10 different WPF Charting options and found we provided the best speed + features offering. They’ll be impressed with this release then!).

We’ll be posted more about these improvements in the coming days. Improvements in performance are across all chart types – you don’t need to choose between features and performance with WPF Elements!

Other charting enhancements include:

• BarSeries, StackedBarSeries and ScatterSeries now support millions of data points.
• Setting ChartAxis.IsSliderVisible to true will display the built-in axis slider. This is an alternate way for the user to zoom and pan the chart.
• You can now specify the starting value of the logarithmic axis scale.
• MarkedStripeGrid supports both vertical and horizontal orientations.
• You can now specify the logical position of the baseline in bar charts.
• You can now specify the number of minor tick marks rendered between major tick marks.
• Setting the DataSeries.IsShownInLegend property can hide the legend item for that series.

New Chart: Boxplot

WPF Elements now includes the WPF Boxplot. It’s built on the same high performance core charting engine as all the other charts in WPF Elements.

New Chart: Candle Stick

WPF Elements users also get the WPF Candle Stick chart. A handy chart for financial data and, like all other charts, super fast as well!

New Chart: Stock Chart

The third new chart type added is the WPF Stock Chart. Guess what? It’s also super fast and built on the same engine as the other charts!

It’s not all charts and grids!

While the Data Grid and Charts got a good number of enhancements and performance boosts, we love all our controls the same. A few of the other changes found across the suite are:

• You can now template the various scheduler dialog boxes. This is useful for providing custom styles or for localizing the labels.
• Added a new IntegerUpDown control.
• Added PercentageTextBox control.
• Some more free WPF controls included in our free suite (we’ll post more about this later)

Dig in, build awesome apps

Last but not least is that we’ve added more samples to our sample explorer that’s included in all releases of WPF Elements. You can explore new functionality, examine the code used to make that sample and adjust the look and feel from within the sample explorer. Once you’ve installed WPF Elements you can find the Sample Explorer in the Start Menu. If you need a hand getting started, we would love to help.

Get the 60 day free trial of WPF Elements 5.1
Existing customers can download 5.1 from their account

Part 1: Getting Started
Part 2: Data Binding and Events
Part 3: More About Events and Parameters
Part 4: The Event Aggregator

Many of you who have played around with Caliburn Micro will know there is not much mentioned about the Window Manager. Due to this, I won’t be covering everything about the Window Manager, I’ll simply explain what I know about it. To demonstrate how to use the Window Manager, we will be extending the application we made in the first blog post of this series.

Using a Window Manager

You may remember from the getting started blog post that one of the first things we did was delete MainWindow.xaml from the project. Caliburn Micro takes care of initializing the window, setting its data context and displaying the appropriate view for us. The Window Manager is one of the mechanisms responsible for getting this done. When you run an application built with Caliburn Micro, the Window Manager is automatically used to create the startup window. For small applications, this is all you really need to know about the Window Manager. When you are building larger applications that need to display other windows or dialogs, it’s time to learn how to use the Window Manager. To demonstrate this we will add a button to the application which will open a new window when clicked. Start by adding a button to AppView.xaml and hooking the click event to a method in AppViewModel.cs. You can do this using Caliburn Micro conventions as explained in the previous tutorials. I have called this method “OpenWindow”. In the OpenWindow method we are going to need access to an instance of a Window Manager. Although we could simply create a new instance of WindowManager and use that, it is best practice to get a hold of the global Window Manager instance that Caliburn Micro makes available to the application. We can do this by making a constructor on AppViewModel.cs that takes in an IWindowManager and store it in a field. You may remember from part 4 of this blog series of what needs to be done when you create a constructor on a view model that has at least 1 parameter. Here is a recap in 3 easy step:

1. Update the bootstrapper as follows. Remember to add System.ComponentModel.Composition.dll as a reference in your project.

using Caliburn.Micro;
using System.ComponentModel.Composition;
using System.ComponentModel.Composition.Hosting;
using System.ComponentModel.Composition.Primitives;
 
public class AppBootstrapper : Bootstrapper<AppViewModel>
{
  private CompositionContainer container;
 
  protected override void Configure()
  {
    container = new CompositionContainer(new AggregateCatalog(AssemblySource.Instance.Select(x => new AssemblyCatalog(x)).OfType<ComposablePartCatalog>()));
 
    CompositionBatch batch = new CompositionBatch();
 
    batch.AddExportedValue<IWindowManager>(new WindowManager());
    batch.AddExportedValue<IEventAggregator>(new EventAggregator());
    batch.AddExportedValue(container);
 
    container.Compose(batch);
  }
 
  protected override object GetInstance(Type serviceType, string key)
  {
    string contract = string.IsNullOrEmpty(key) ? AttributedModelServices.GetContractName(serviceType) : key;
    var exports = container.GetExportedValues<object>(contract);
 
    if (exports.Count() > 0)
    {
      return exports.First();
    }
 
    throw new Exception(string.Format("Could not locate any instances of contract {0}.", contract));
  }
}

2. Use the Export attribute on the AppViewModel class:

[Export(typeof(AppViewModel))]
public class AppViewModel : PropertyChangedBase
{
  ...
}

3. Use the ImportingConstructor attribute on the AppViewModel constructor:

private readonly IWindowManager _windowManager;
 
[ImportingConstructor]
public AppViewModel(IWindowManager windowManager)
{
  _windowManager = windowManager;
}

Now we can use the Window Manager instance in our OpenWindow method to open a new window. To keep this tutorial simple, we will simply create a new window that also uses the AppViewModel as the data context. This is done using the following code:

public void OpenWindow()
{
  _windowManager.ShowWindow(new AppViewModel(_windowManager));
}

Run this up and press the button to see another window appear. All we needed to do was pass in an instance of a view model, then everything else from creating the window instance and displaying the appropriate view for our view model is done for us. Once again Caliburn Micro makes our life easier!

The Window Manager has all sorts of methods and method overloads for opening windows, dialogs and popups. All these methods are fairly straight forward and easy to use. You can see more usage of the Window Manager in the HelloWindowManager sample that comes with Caliburn Micro. One more thing I wanted to look at is the ‘settings’ parameter. Here you can pass in a dynamic object used to set properties on the new window. This gives you fine-grained control on the appearance of your application if you need it. Here is an example where I am setting the WindowStartupLocation to be manual rather than center-owner.

public void OpenWindow()
{
  dynamic settings = new ExpandoObject();
  settings.WindowStartupLocation = WindowStartupLocation.Manual;
 
  _windowManager.ShowWindow(new AppViewModel(_windowManager), null, settings);
}

Custom Window Managers

There are scenarios where it is useful to implement a custom Window Manager. This is good if you need to set properties on all Window instances to be common values. For example, properties could include the icon, the window state, window size and applying custom chrome. The most useful property that I have found to set on windows is the SizeToContent property. By default, Caliburn Micro sets this to be SizeToContent.WidthAndHeight. This means that the window automatically sizes itself based on its content. Although this can be convenient at times, I have found this to cause some issues with certain application layouts and seems to be buggy when setting the window to be maximized by default. Creating a custom Window Manager is very simple. Start by adding a class that extends WindowManager. Next, you can override the EnsureWindow method and do something like the following:

protected override Window EnsureWindow(object model, object view, bool isDialog)
{
  Window window = base.EnsureWindow(model, view, isDialog);
 
  window.SizeToContent = SizeToContent.Manual;
 
  return window;
}

In this method, we start by calling base.EnsureWindow() to create the window instance. Next you can set any properties on the window that you want, and then simply return the window instance. The last step is to set an instance of your custom Window Manager to be globally used by the application. In the first code snippet in this blog post we make modifications to the bootstrapper. Here you can see we are adding a WindowManager instance to the CompositionBatch. You can replace this to use an instance of your custom window manager instead which would look like this:

batch.AddExportedValue<IWindowManager>(new AppWindowManager());

That’s everything I wanted to cover with the Window Manager, I hope you found it useful in building great WPF applications powered by Caliburn Micro! I appreciate your comments and feedback on the series!

Download the full Visual Studio 2010 project for this tutorial.

Happy coding :)

Part 1: Getting Started
Part 2: Data Binding and Events
Part 3: More About Events and Parameters

In this week’s tutorial we will be learning about how to use the event aggregator included with Caliburn Micro. The event aggregator is a service that makes it easy for multiple parts of your application to send messages to each other. This is useful when your application is made up of several view-models that need to communicate. To do this, you subscribe objects (such as view models) to the event aggregator and specify what type of message they should listen for. You also define what the object does when it receives such messages. Then, when another part of the application publishes a message, the event aggregator makes sure the appropriate subscribed objects receive it and perform the appropriate action. Throughout this tutorial we will be extending the application we made in the getting started tutorial. (You can download the application here.)

Although the event aggregator is more useful for larger applications that have multiple view-models, we will be keeping our tutorial application rather small. Also be warned that this tutorial has a lot more to digest compared to the previous ones! By the end of this tutorial, we will have an application that displays two views, each with their own view-model. One of the views will be displaying some radio buttons, each representing a different color. When a radio button is clicked, we’ll publish a message that includes the appropriate color. The second view will listen for these messages and change the color of a Rectangle. We will do this in 4 steps: Adding another view to the application, implementing the IHandle<TMessage> interface, subscribe one of the view models to an event aggregator and finally publish events from the other view model.

Step 1: Adding Another View and View-Model

In order to demonstrate the event aggregator, we will need at least 2 view models in our application. We already have one (AppViewModel), so lets start by adding another one. Remember the naming convention described in the getting started tutorial? Add a new class called ColorViewModel, and a UserControl called ColorView. Lets also change the background of the ColorView so that we at least have something to see when we first add it to the application. In terms of the visual structure, we are going to get the existing AppView to contain the new ColorView. (Views do not need to be nested in order to use the event aggregator; a view-model can listen to messages being published from anywhere in the application.) To do this, AppViewModel will need a property of type ColorViewModel which we will set in the constructor like this:

public class AppViewModel : PropertyChangedBase
{
  public AppViewModel(ColorViewModel colorModel)
  {
    ColorModel = colorModel;
  }
 
  public ColorViewModel ColorModel { get; private set; }
}

In AppView.xaml, we will split the grid into 2 columns and display the ColorModelView in the first column. AppView.xaml will now look like this:

<Grid Width="300" Height="300" Background="LightBlue">
  <Grid.ColumnDefinitions>
    <ColumnDefinition Width="*" />
    <ColumnDefinition Width="*" />
  </Grid.ColumnDefinitions>
  <ContentControl Name="ColorModel" Margin="10" />
</Grid>

See what’s going to happen here? We have set the name of the ContentControl to be the same name as the property we just added to AppViewModel. From this, Caliburn Micro will kindly bind the Content property of the ContentControl to the ColorModel property for us. When we run this up later, Caliburn Micro will make sure that an instance of ColorView is displayed for the ColorViewModel.

If we were to run up the application now, we’d run into an exception saying that the default constructor of AppViewModel can’t be found. Hmm, that’s a good point: we have included a constructor on AppViewModel that requires a parameter – a ColorViewModel object. To resolve this, we’ll need to update our AppBootstrapper as seen below. (Make sure to include a reference to System.ComponentModel.Composition.dll to the application.)

using Caliburn.Micro;
using System.ComponentModel.Composition;
using System.ComponentModel.Composition.Hosting;
using System.ComponentModel.Composition.Primitives;
 
public class AppBootstrapper : Bootstrapper<AppViewModel>
{
  private CompositionContainer container;
 
  protected override void Configure()
  {
    container = new CompositionContainer(new AggregateCatalog(AssemblySource.Instance.Select(x => new AssemblyCatalog(x)).OfType<ComposablePartCatalog>()));
 
    CompositionBatch batch = new CompositionBatch();
 
    batch.AddExportedValue<IWindowManager>(new WindowManager());
    batch.AddExportedValue<IEventAggregator>(new EventAggregator());
    batch.AddExportedValue(container);
 
    container.Compose(batch);
  }
 
  protected override object GetInstance(Type serviceType, string key)
  {
    string contract = string.IsNullOrEmpty(key) ? AttributedModelServices.GetContractName(serviceType) : key;
    var exports = container.GetExportedValues<object>(contract);
 
    if (exports.Count() > 0)
    {
      return exports.First();
    }
 
    throw new Exception(string.Format("Could not locate any instances of contract {0}.", contract));
  }
}

This is similar to the bootstrappers used in the samples that come with the Caliburn Micro download. So as not to make this blog post too long, I won’t be diving into the details of what this code is doing (search for MEF or Managed Extensibility Framework if you need more details).

Next, we need to include an Export attribute on both our view-model classes. This is for the GetInstance method in the AppBootstrapper to work.

[Export(typeof(AppViewModel))]
public class AppViewModel : PropertyChangedBase
{
  ...
}
 
[Export(typeof(ColorViewModel))]
public class ColorViewModel
{
}

And finally, include the ImportingConstructor attribute on the AppViewModel constructor. This is to indicate that this constructor should be used since there is no default constructor. When Caliburn Micro creates the AppViewModel, it will also create an instance of the ColorViewModel to pass into the constructor for us.

[ImportingConstructor]
public AppViewModel(ColorViewModel colorModel)
{
  ColorModel = colorModel;
}

Now we can run the application and see that the ColorView is successfully being displayed within the AppView:

Let’s add a Rectangle into the second column. This will be the Rectangle that changes color when messages are handled, so its color will be controlled by a property on the AppViewModel like this:

private SolidColorBrush _Color;
 
public SolidColorBrush Color
{
  get { return _Color; }
  set
  {
    _Color = value;
    NotifyOfPropertyChange(() => Color);
  }
}

<Rectangle Grid.Column="1" Width="100" Height="100" Fill="{Binding Color}" />

Step 2: Implementing the IHandle<TMessage> Interface

We are going to be publishing messages from the ColorViewModel to be picked up by the AppViewModel. To do this we are going to need to implement a class that holds the message information. such a class is usually very small and simple. It mainly needs to have some properties that hold any information that we want to send. Here is the message class that we are going to use:

public class ColorEvent
{
  public ColorEvent(SolidColorBrush color)
  {
    Color = color;
  }
 
  public SolidColorBrush Color { get; private set; }
}

In order for the AppViewModel to handle the appropriate events, it will need to implement the IHandle<TMessage> interface. In our case, we will be using ColorEvent as the generic type. The IHandle interface has a single method that we need to implement which is called Handle. In the Handle method of our AppViewModel, we will look at the SolidColorBrush sent in the ColorEvent and use it to set the Color property. This will in turn change the color of the Rectangle in the view.

public void Handle(ColorEvent message)
{
  Color = message.Color;
}

Step 3: Subscribe

Now we need to subscribe the AppViewModel to an event aggregator so that it can actually listen to published messages. We do this by adding another parameter to the constructor which will be an IEventAggregator. When the time comes to create the AppViewModel, Caliburn Micro will pass in the event aggregator that we set up in the bootstrapper. Now within the constructor, we simply call the Subscribe method like this:

[ImportingConstructor]
public AppViewModel(ColorViewModel colorModel, IEventAggregator events)
{
  ColorModel = colorModel;
 
  events.Subscribe(this);
}

Step 4: Publish

The ColorViewModel is also going to need the event aggregator so that it can publish messages. Add a constructor to the ColorViewModel which takes an IEventAggregator and stores it in a field. Remember to include the ImportingConstructor attribute:

private readonly IEventAggregator _events;
 
[ImportingConstructor]
public ColorViewModel(IEventAggregator events)
{
  _events = events;
}

Now we just need add the radio buttons to the ColorView, listen to their click event and then publish a message. You may remember from the second tutorial in this series about the quick way to listen to the click event. Simply set the name of the RadioButton to be the same as the method we want to be called. We could of course use event parameters rather than having an action method for every RadioButton, but I have done it like this so you can clearly see what’s going on:

<RadioButton Name="Red" Content="Red" Foreground="White"
             VerticalAlignment="Center" HorizontalAlignment="Center" />
<RadioButton Name="Green" Content="Green" Foreground="White"
             VerticalAlignment="Center" HorizontalAlignment="Center" Grid.Row="1" />
<RadioButton Name="Blue" Content="Blue" Foreground="White"
             VerticalAlignment="Center" HorizontalAlignment="Center" Grid.Row="2" />

public void Red()
{
  _events.Publish(new ColorEvent(new SolidColorBrush(Colors.Red)));
}
 
public void Green()
{
  _events.Publish(new ColorEvent(new SolidColorBrush(Colors.Green)));
}
 
public void Blue()
{
  _events.Publish(new ColorEvent(new SolidColorBrush(Colors.Blue)));
}

And that’s it. Run up the application now and click the radio buttons. See that the AppViewModel is successfully getting the messgaes from the ColorViewModel to change the color of the Rectangle.

One thing to note is that I have been passing around SolidColorBrushes in the messages to set the color of the Rectangle. In general you would pass around more primitive values and then use a converter in the UI to interpret the value as a SolidColorBrush or the like.

The full Visual Studio 2010 project for this tutorial can be downloaded from here. I hope you find the event aggregator useful for orchestrating communication across the various view-models in your application. Check out the documention for more information including how to do polymorphic event subscriptions, custom publication marshaling and unsubscribe from the event aggregator.

See you next time.

You may remember from the previous blog post that we hooked up events using the help of Caliburn Micro’s naming conventions. All we needed to do was set the name of a button in the view to be the same name as a method in the view-model. Then the Click event of the button will be automatically hooked up to call the appropriate method. Sometimes however you will need to explicitly hook up the events in order to provide event parameters or specify exactly which event you want to use. To do this, Caliburn Micro provides a long syntax and a short syntax. The advantage of the long syntax is its compatability with Microsoft Expression Blend. The short syntax is great if you’re not interested in using a designer and want to keep things short and sweet. Let’s start off with learning how to use the long syntax.

Long Syntax

The best way to begin is to modify the existing application to use the long syntax without changing the current behaviour. Open up AppView.xaml and include these 2 namespaces:

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

Then, simply replace the repeat button with this:

<RepeatButton Content="Up" Margin="15" VerticalAlignment="Top">
  <i:Interaction.Triggers>
    <i:EventTrigger EventName="Click">
      <cal:ActionMessage MethodName="IncrementCount" />
    </i:EventTrigger>
  </i:Interaction.Triggers>
</RepeatButton>

Run the application now and you will see it looks and behaves just as it did before. What we have done here is used System.Windows.Interactivity triggers to hook up an event to a method. In the EventTrigger we can specify which event we want to listen to, and using the Caliburn Micro ActionMessage we can specify which method should be called. Using this approach you can include any number of event triggers to listen to other events on the same control. So you could listen to MouseEnter and MouseLeave to perform additional actions.

Next let’s look at event parameters. To demonstrate this, we will add another button that increments the count by 2. In AppViewModel.cs we need to modify the IncrementCount method to include an integer parameter. This parameter will be used to change the Count property. The IncrementCount method will now look like this:

public void IncrementCount(int delta)
{
  Count += delta;
}

Back in AppView.xaml, update the existing repeat button by adding a Caliburn Micro Parameter to the ActionMessage like this:

<cal:ActionMessage MethodName="IncrementCount">
  <cal:Parameter Value="1" />
</cal:ActionMessage>

Now when the button is pressed, it will pass a value of 1 as a parameter to the IncrementCount method. Add another button to the application with a parameter of 2 and then run up the application. Clicking on the different buttons will increment the count value according to their different parameters. The Value property of the Caliburn Micro Parameter is a dependency property, which means it also supports the usual WPF data binding. This allows you to use it in all sorts of different scenarios you come across.

Pro Tip: Because of the flexibity of using data binding to set the parameter value, it is possible to pass UI elements from the view into the view-model. You should try to avoid doing this as hard as you possibly can! UI elements in the view-model can fracture your MVVM archetecture and can cause maintenance issues in the future.

Short Syntax

Now to learn how to use the short syntax to do the same thing. To look into this, let’s start off with a fresh copy of the application that doesn’t have our recent long syntax experiments in it. Again we will start by modifying the application without changing its current behaviour. This time we only need to add the Caliburn Micro namespace, and replace the repeat button with this new one:

<RepeatButton Content="Up" Margin="15" VerticalAlignment="Top"
              cal:Message.Attach="[Event Click] = [Action IncrementCount]" />

All we have done this time is use one of Caliburn Micro’s attached properties (Message.Attach) to specify which event we are interested in, and which method to call.

Next we look at event parameters using this short syntax. Modify the IncrementCount method in same way we did for the long syntax. Including an event parameter using Message.Attach will look like this:

cal:Message.Attach="[Event Click] = [Action IncrementCount(1)]"

The event parameter is written in the brackets after the method name. I’m sure you can work out how to add a button that increments the value by 2.

The short syntax even supports a special form of data binding. To demonstrate this, let’s add a button that increments the count by the count value itself. In other words, a button that doubles the count value. You can remove the CanIncrementCount event guard mentioned in the previous blog post to make the value go higher than 100. The repeat button code would look something like this:

<RepeatButton Content="Double" Margin="15"
              cal:Message.Attach="[Event Click] = [Action IncrementCount(Count.Text)]" />

Here I have set the parameter to be Count.Text. This sets up a binding to the Text property of the TextBlock (named Count) which is displaying the current value. Notice that Caliburn Micro automatically converts string values that we want to pass into a method that takes a numerical value. Another shortcut that Caliburn Micro provides here is that it will automatically use an appropriate property on a user control if we do not specify a property. In the example above, we could just write the name of the TextBlock (“Count”) as the parameter and Caliburn Micro will bind to the Text property by default. Here is the what the application looks like so far:

Automatically Finding Parameters

To finish off this tutorial I’ll mention that Caliburn Micro even has conventions for automatically picking up parameters when you don’t explicitly set them. If you do not explicitly specify a parameter, Caliburn Micro will look at the parameter name in the method signiture and try find any user control in the view that matches this name (ignoring the case). If a matching user control is found, an appropriate property on the control will be used to provide the parameter. For example, if the user control is a TextBlock, the Text property value will be used as the parameter. Again, Caliburn Micro can automatically convert strings to ints and so on if necessary.

To understand this convention more easily, lets try this out in the application. Add a slider to the application and call it “Delta”. Then add another button called “IncrementCount”. As explained in the previous blog post, the button is going to automatically call the IncrementCount method when it is clicked. This time however, the method has a parameter, but we havn’t specified what value the button should use. Notice that the slider we added is the same name as the parameter (delta). Thus Caliburn Micro will automatically use the Value property of the slider as the parameter to the method whenever the button is clicked. Here is all the code we needed to add to do this:

<UniformGrid Columns="2" VerticalAlignment="Bottom">
  <Slider Name="Delta" Minimum="0" Maximum="5" Margin="15" />
  <Button Name="IncrementCount" Content="Increment" Margin="15" />
</UniformGrid>

Extra for Experts

Here I’ve only covered some of the support that Caliburn Micro provides for hooking up events. Some other topics of intrest include:

• Setting action targets
• Special parameter values for data binding
• Action bubbling
• Action guards with parameters

You can find more information about hooking up events using Caliburn Micro from the online documentation. I recommend reading through the documentation so you can better choose which approaches to use for the various event scenarios in your application. You’ll find there is a lot of helpful support that Caliburn Micro provides, and a lot of convenient conventions that will take work off your shoulders. The Cheat Sheet is a useful page to bookmark. You’ll also find that the HelloExplicitAction, HelloParameters and BubblingAction samples are a good source of knowledge.

You can download the application from this tutorial used to demonstrate the long syntax from here, and the short syntax from here.

Next let’s take a look at the Event Aggregator.

Until next time, Happy Coding!

Data binding

We’ll start by getting the application to display a numerical value that is stored in the model. In the AppViewModel class created in the previous blog post, add a property called Count as seen in the code snippet below. The property value is stored in the _count field which we have given a default value of 50. You may recall from last time that we made the AppViewModel class extend the PropertyChangedBase provided by Caliburn Micro to preform property change notifications. Rather than implementing INotifyPropertyChanged in all of your models, you can simply call the NotifyOfPropertyChange method within the setter of your properties.

public class AppViewModel : PropertyChangedBase
{
  private int _count = 50;
 
  public int Count
  {
    get { return _count; }
    set
    {
      _count = value;
      NotifyOfPropertyChange(() => Count);
    }
  }
}

Next we modify the view to display this property value. In AppView.xaml, add a TextBox to the grid as follows:

<Grid MinWidth="300" MinHeight="300" Background="LightBlue">
  <TextBlock Name="Count" Margin="20" FontSize="150" VerticalAlignment="Center" HorizontalAlignment="Center" />
</Grid>

Now run up the application and see that the TextBlock is displaying the default value of the Count property.

Wait… what? I don’t remember setting any binding on the TextBlock to get the Count property, and yet the TextBlock is displaying the correct data!

Notice that I’ve set the name of the TextBlock to be the same as the property we want to bind to. This is a convenient short cut that Caliburn Micro provides. For elements that display data such as TextBlock or TextBox, setting their name to match a property on the data model will automatically hook it up for you.

Handling events

Next, let’s work on adding a button that increments the displayed value. The quick and dirty way of doing this is to hook up the Click event of a button to an event handler in the code behind. However, when using the MVVM pattern it’s usually best (but not absolutely necessary) to avoid using the code behind where you can. So let’s look at how to handle the events Caliburn Micro style. First, add a method to the AppViewModel for incrementing the Count property like this:

public void IncrementCount()
{
  Count++;
}

Now add a button to the grid in AppView.xaml as follows:

<Grid MinWidth="300" MinHeight="300" Background="LightBlue">
  <RepeatButton Name="IncrementCount" Content="Up" Margin="15" VerticalAlignment="Top" />
  <TextBlock Name="Count" FontSize="150" VerticalAlignment="Center" HorizontalAlignment="Center" />
</Grid>

Running the application now and clicking the button will increment the count value as advertised. Once again you’ll notice that we don’t need to do much work to hook the click event of the button to the IncrementCount method. For certain user interface controls such as buttons, you can simply set the name of the control to be the name of the method you want it to be hooked to. Caliburn Micro will hook the appropriate event of the user control to the specified method in the model. In the case of buttons, Caliburn Micro deals with the Click event. (You can also manually specifying which event to hook up to which method which we’ll look at next time).

Event guards

When Caliburn Micro automatically hooks up the Click event to the IncrementCount method, it also looks for a method or property called CanIncrementCount. By adding a CanIncrementCount method or property, you can include additional logic that determines whether the event is allowed to be handled based on the current state of the model. Let’s do this now by adding the following property to the AppViewModel:

public bool CanIncrementCount
{
  get { return Count < 100; }
}

Since this logic is based on the value of the Count property, we also need to raise property change notification for the CanIncrementCount property whenever the Count value changes. This is done by adding this line of code on the Count property setter:

NotifyOfPropertyChange(() => CanIncrementCount);

Run up the application once more and increment the value to 100. Once the limit has been reached, the button will become disabled and prevent the user from further incrementing the value.

In this tutorial we have looked at a few ways that Caliburn Micro takes some of the work off our shoulders. Now you can more quickly use data binding, property change notifications, event handlers and event guards, while at the same time implementing a sturdy MVVM application that is easier to test and maintain.

You can download the full Visual Studio 2010 solution for this tutorial here. Use it to practice your new skills by adding a button to decrement the value.

In the next instalment of this blog series, we’ll take a look at more advanced scenarios of event handling with Caliburn Micro, specifically with passing event parameters. See you then.

Step 1: Getting Started

Caliburn Micro targets .NET framework 4.0, so you’ll need Visual Studio 2010 to create the application. Start by creating a new WPF Application and add a reference to Caliburn.Micro.dll and System.Windows.Interactivity.dll which come with the Caliburn Micro download. Since Caliburn Micro is going to take care of creating the window for you, delete MainWindow.xaml and remove the StartupUri attribute from App.xaml. App.xaml will now look like this:

<Application x:Class="CaliburnMicroApp.App"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
  <Application.Resources>
 
  </Application.Resources>
</Application>

Step 2: The View Model

Caliburn Micro promotes a View-Model-First approach, so the next step is to add a class to represent the view model. Large applications can have many view models, each of which provides the logic for a different view. Below is a code example of an empty view model. Since this tutorial is focused on simply getting started with incorporating Caliburn Micro into a WPF application, we are not going to make the view model do anything for now.

using Caliburn.Micro;
 
namespace CaliburnMicroApp
{
  public class AppViewModel : PropertyChangedBase
  {
 
  }
}

The first thing to notice here is the name of the class. Caliburn Micro expects a particular naming convention so it can hook up the view model to the appropriate view. The class name of a view model should end with “ViewModel”. What you put in front of “ViewModel” is up to you. The other thing to notice here is that this class extends the PropertyChangedBase. This is provided by Caliburn Micro and makes it easy to raise property change notifications without needing to implement INotifyPropertyChanged in all your view models. Although this example view model doesn’t do anything, I’ve included the PropertyChangedBase as good practice. When adding properties to the view model, it will come in handy.

Step 3: The View

In order to display something in the window, you’ll need to create a view for the view model created in the previous step. This is as simple as adding a new UserControl to the project as seen below. I should point out again that Caliburn Micro expects a particular naming convention so it can hook up the view to the appropriate view model. View names should end with “View” and start with the same name you used for the view model. So for my example here, “AppView” is the view for rendering the “AppViewModel”. In the code below I have also set the width, height and background of the grid so that when you run this application you can see that it is working correctly.

<UserControl x:Class="CaliburnMicroApp.AppView"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006">
  <Grid Width="300" Height="300" Background="LightBlue">
 
  </Grid>
</UserControl>

Step 4: The Bootstrapper

The bootstrapper is the mechanism used to incorporate Caliburn Micro into your application. It is also a place where you can configure the framework for the needs of your application. For the purposes of this tutorial, I have used a very simple bootstrapper implementation seen here:

using Caliburn.Micro;
 
namespace CaliburnMicroApp
{
  public class AppBootstrapper : Bootstrapper<AppViewModel>
  {
  }
}

Caliburn Micro has 2 different bootstrappers available. The one used above lets you set the generic type to be the view model that you want to be used at startup. The last step is to tell the application to use the bootstrapper. This is done by adding your bootstrapper to a resource dictionary in App.xaml. After doing this, App.xaml will now look something like this:

<Application x:Class="CaliburnMicroApp.App"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:local="clr-namespace:CaliburnMicroApp"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
  <Application.Resources>
    <ResourceDictionary>
      <ResourceDictionary.MergedDictionaries>
        <ResourceDictionary>
          <local:AppBootstrapper x:Key="bootstrapper" />
        </ResourceDictionary>
      </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
  </Application.Resources>
</Application>

And that’s it

Now when you run up the application, you’ll see a small window with a light blue background. Your application is now primed and ready to take advantage of all the great support provided by Caliburn Micro. It’s easy to get help for using this framework due to its growing community. You can also look through the documentation on CodePlex.

You can grab the full Visual Studio 2010 solution I made for this tutorial here.

In the next part of this blog series we will look at adding some interactivity using events and data binding with the help of Caliburn Micro.

Until next time, Happy Coding!

User interaction

First lets have a look at what this dashboard provides in the user interface. Along the top of the dashboard is the time explorer control. This allows the user to select a time range by dragging or clicking the mouse. By zooming in with the mouse wheel, the time explorer will display shorter time intervals such as weeks and days. Within the time explorer is a line chart displaying some summary data for the overall dashboard. This makes it easy for the user to select a time range around any interesting points in the data. Every time the user selects a new time range, the data displayed in the charts, gauges and data grid are updated to only include the data in the selected time range.

Data drill down

The stacked bar chart below the time explorer is plotting a category breakdown of the data for each point displayed on the X axis. An individual bar shows the data for either a month, day, or 2 hour time slot based on the magnitude of the selected time range. Clicking on one of the bars will drill down to the next time interval.

Category filtering

Selecting one of the segments in the doughnut chart will filter the data grid by the selected category, and emphasise the appropriate points in the stacked bar chart and the equivalent gauge.

Along the bottom of the dashboard is a text block displaying the total sales value, animated linear gauges, and our WPF data grid. Users can reorder, resize and sort the columns in the data grid to display the current data however they would prefer.

MVVM architecture

The MVVM design pattern is commonly used to create robust WPF applications that are easy to maintain. The main idea behind this pattern is to cleanly separate the data model from the user interface. The only things linking these two parts together should be bindings, commands and event handlers. The data model of the dashboard application listens to changes made to the various controls based on the user interaction. These changes are analysed and the displayed data held within the model is updated to reflect the selected time ranges or filters. The controls within the user interface listen to the changes made to the data model and then updates the visuals for the user to see.

You can download the trial version of the latest nightly build from here, or go to your account page if you are already a customer. The smaller data model classes can be found in the Model folder. The main data model class is called DashboardViewModel, and the UI is built up in the DashboardView.xaml file. The SimpleLinearGauge extends our AnimatedValueDisplay, and the remaining class files are for hooking into the Caliburn Micro framework.

Have any questions about WPF Elements? We’d love to hear from you in the forum!

Rows & Columns

• ShowColumnHeaders- will hide the row of column labels if False. Defaults to True
• ShowRowHeaders- as above
• AllowColumnReorder – allows the user to change the order of columns by dragging and dropping
• RowHeaderWidth – sets the width of the row header block
• AutoGenerateColumns – will create the columns based on the properties in the bound collection

Frozen Columns

• FrozenColumnCount – the specified number of columns will remain stationary when the Data Grid is scrolled horizontally
• ShowFirstFrozenLine – if True if frozen column shadow line will be displayed on the left when FrozenColumnCount is set to 0

Selection & Editing

• HighlightedCell – gets or sets the cell that has focus (black border)
• SelectedCell & SelectedCells – gets or sets the cell, or collection of cells that have been selected (yellow highlight). Both highlighted and selected cells can be set programmatically
• SelectionType – sets a user’s click to highlight either a Row or Cell
• SelectionMode – Single allows one cell/row to be selected at a time; Multiple adds a single cell/row to the current selection with a click; Extended allows a block of cells/rows to be highlighted through click and drag functionality
• AllowEditing – if set to True the user will be able to double-click a cell to edit its contents (if False the Data Grid is read-only). Once in editing mode the user can tab across the row
• SetAllowEditing() – when called on a DataGrid, can set either a cell or a row to be read-only. Can be passed a row or a DataGridCell

Paging

• IsPagerVisible – shows the pager control if is True (defaults to False)
• PageSize – sets number of items on a page. Default is 0 (all items on one page)
• PageIndex – sets the current page to be displayed
• PagerStyle – allows you to set a custom style for the pager control
• MaxPagerButtonCount – sets the maximum amount of page buttons to display (including the ellipsis)
• EllipsisMode – place an ellipsis button (indicating further pages) at positions After, Before, None or Both

For example the following code:

<ms:DataGrid Name="DataGrid" ItemsSource="{Binding Data}" RowHeaderWidth="15" SelectionMode="Extended"
                 SelectionType="Cell" IsPagerVisible="True" PageSize="16" EllipsisMode="Both" MaxPagerButtonCount="5" 
                 AllowColumnReorder="False" FrozenColumnCount="1" >

produces this result:

There is also a whole set of properties for the columns themselves. Naturally you can set Widths & MinWidths, alongside setting the Header (which can be any object, just like a cell). Other properties include AllowSort, AllowResize, AllowEditing, SortDirection and most importantly the DisplayTemplate and EditorTemplate properties, for completely customizing the look and feel of a particular column.

Next time we’ll look at styling the DataGrid, then adding in a custom editor. Download the 60 day trial of WPF Elements now to explore this control plus dozens more. Until next time!

5 superbly crafted themes
We have poured months of effort into creating pixel perfect themes both for the standard WPF controls and the WPF Elements controls. There’s Office Blue, Office Black, Office Silver, Expression (Alloy) and Expression Light (Alloy Light). You’ll be impressed by how easy these themes are to add to your project and your users will be really impressed at how great the application looks.

Autocomplete Text Box for WPF

Autocomplete text boxes are great. We’ve made some great additions to this control recently and it will really help bring your applications up a level. Check out the new multi-value autocomplete box support that was included recently.

Coverflow for WPF

Popularised in iTunes, Coverflow is a unique way of presenting data to your users. Beyond just static images and thanks to the power of WPF you will find you can set any arbitrary content as your covers — images, videos, other WPF controls, whatever you want! We’ve seen some imaginative uses of the Coverflow control over the years. You will be pleased to find everything you need in the box to configure the display exactly as you want it to be.

Prompt Decorator for WPF

This control adds a polish to your applications. Want to have hint text on your text box and drop down lists? Say “Search” appearing in your search box but disappearing when the user clicks in it? It couldn’t be easier with the Prompt Decorator control.

Get the free controls with the WPF Elements 5 installer. You’re welcome to use the controls and themes listed here at no charge, with no royalties.

Happy coding!

You might like to check out the demos of the Data Grid in the Sample Explorer that comes bundled with the 60 day trial of WPF Elements. Alongside being able to see the Data Grid in action XAML and code samples are included, ready to inspire your own applications.

But for now we shall build one from scratch! Where to begin?

Setting up the references

The easiest way is to add a reference to WpfElements.dll and then drag a Data Grid control from the toolbox onto your Window or Page. This will add the licenses.licx file to your properties folder and also add the following namespace to your XAML:

xmlns:ms="http://namespaces.mindscape.co.nz/wpf"

Our Data Grid is going to be fairly uninteresting without binding it to a model. To save time I’ve made the following simple example to populate the grid; you can download the source code here and put it in the code-behind (the archive also includes the finished XAML).

We’re ready to go! Here’s the code:

<Grid>
  <ms:DataGrid ItemsSource="{Binding Data}" />
</Grid>

The Data Grid was designed following WPF best practices therefore setting its model is like any other WPF control – just bind the ItemsSource property to a collection of data. Run it, edit cell data, rearrange column order by dragging and dropping, click on a column header to sort – all behave as expected. All with one line of XAML!

You’ll notice that some of the column widths are a little small for many of the records. Also, while the Generic theme is perfectly serviceable, we’ve got five other theme options so we could apply one of those too. Column widths are set inside the DataGrid control as follows:

<ms:DataGrid ItemsSource="{Binding Data}">
  <ms:DataGrid.Columns>
    <ms:DataGridColumn PropertyName="Name" Width="120" />
    <ms:DataGridColumn PropertyName="Address" Width="140" />
    <ms:DataGridColumn PropertyName="Balance" Width="60" />
  </ms:DataGrid.Columns>      
</ms:DataGrid>

As for the theme, I’ll be setting the entire window theme, but if you just want to set the Data Grid control that’s available by setting the ResourceDictionary inside ms:DataGrid.Resources.

<Window.Resources>
  <ResourceDictionary>
    <ResourceDictionary.MergedDictionaries>
      <ms:OfficeBlue />
    </ResourceDictionary.MergedDictionaries>
  </ResourceDictionary>
</Window.Resources>

Feel free to check out how OfficeSilver, OfficeBlack, Alloy and AlloyLight look too. The finished result:

As you can see it’s fairly easy to get the Data Grid up and running! In future posts we’ll look at some of the properties we can set on the Data Grid, to control sorting, column reordering, selection modes and of course the editors, both built-in and custom. Finally we’ll apply a custom colored template to the Balance column!

Head on over and grab the 60 day trial of WPF Elements to try out the Data Grid and over 50 other controls here:
Download WPF Elements