I cannot count how many times people have requested the source code to the ATAPI.NET or ITAPI3 projects.  My response has always been that I was unable to release it due to ownership issues (it was developed under contract for a client).  I am pleased to announce this morning that I have worked through those issues and have been granted permission to release the project in it’s entirety as source code on CodePlex!

Here’s their new homes:  http://atapi.codeplex.com/ and http://itapi3.codeplex.com

I’ll open up discussion board access there as well for Q&A.  If you would like to contribute to the project, shoot me an email and we’ll see about getting you access!

In the last post, I referred to the DragPositionBehavior in the JulMar MVVM library.  This behavior allows any UIElement to be dragged and repositioned using the mouse without requiring any code logic on your part.  It’s easy to apply – using the traditional Blend syntax (easiest done by dragging the behavior onto an element):

This is the simplest way to use this, however it doesn’t work when the behavior is to be applied with a Style – in my example in the prior post, we need to drag around the ListBoxItem container, not just the content.  So I showed an alternative syntax to apply the same behavior:

Here, the behavior is being applied by setting the IsEnabled attached property onto the ListBoxItem.  Here’s the implementation for that:

This is a boilerplate example of an attached property – nothing to see here.  The magic happens in the PropertyChange callback:

Let’s break this down a little.  When we have the IsEnabled property set onto an element, first we verify it’s a UIElement (we cannot drag it on anything that isn’t because the mouse events are defined at this level).  Next, we check the behaviors collection on that element – if an existing behavior is there and we are setting the property to “false”, then we remove the existing behavior from the collection.  If there is no behavior, and we are setting the property to “true”, then we add a new DragPositionBehavior instance to the collection here.  This, in effect, is exactly what the first block of XAML is doing, and it’s what we do as well here in code – so the Style setter works as expected.

This isn’t really a trick – I’m sure others have thought of it as well, but it’s a useful thing to add into your behaviors so they can be universally used, both by Blend as well as by developers directly wanting to apply it in places where Blend cannot today.

In this post, we will look at the IUIVisualizer, and bring together some of the concepts we’ve talked about already through a new sample – a simple picture viewer:

The application grabs all the images from the user’s photo folder and then displays each one onto the surface of a corkboard.  You can change the properties of an image, remove an image or add additional images.  It’s not designed to be a true image application ala photoSuru, it’s really more of a sample of MVVM practices with the helper library.  Here’s some of the coding examples present in the sample:

• It registers a ISelectFile service and implements it as an OpenFileDialog.
• It displays a “Picture Properties” dialog using the IUIVisualizer service.
• It maps mouse DoubleClick on an image into a command in the ViewModel to display the properties.
• It provides drag support through a behavior on the style.

Let’s look at this four features in particular.  Download the sample from here:

PictureViewer

Open the project in Visual Studio 2008 SP1, it should build and run without any issues.  The project structure is pretty much like all the other samples I’ve blogged about – I’m trying to keep to a consistent model:

Service Registration

If you look at the App.xaml.cs code behind, you’ll find the registration work being done in the constructor:

First, note that it registers the standard services – that’s something I always do, even if I don’t anticipate needing them all, it doesn’t hurt to have them there. Next, it adds the file selector service by calling ServiceProvider.Add on the ViewModel class.  The interface is defined as a single method:

The registration ties this interface to an implementation that displays the OpenFileDialog, for testing purposes, that would be replaced with a minimum of two implementations: one that returns null/empty and one that returns a valid filename to test both cases.

The final line in the app.xaml.cs file registers a UI dialog to display the properties of the image.  This is done through the IUIVisualizer interface which is defined in the helper library:

Notice the Register and Unregister methods take a string defined as a “key”.  This is the key that invokers will use to display the UI visually; I often use the typename of the View, but you can use any string here as long as you are consistent in registration vs. invocation.  In this sample, I’ve used the key “ShowElementProperties” – we’ll see in a moment how it is displayed.  The second parameter for the Register method takes the Type to display.  The type must be a WPF Window-derived type (i.e. NavigationWindow or Window) and will represent the View in our MVVM pattern.

Displaying a UI with IUIVisualizer

In the PictureViewModel type, there is an ICommand that is used to drive the Property window:

The default constructor fills that in with a DelegatingCommand to jump to a method of the ViewModel:

The handler method is marked as internal because the MainViewModel forwards it’s own command to this same method handler (from the menu and toolbar).  Notice that the method first gets the IUIVisualizer service; you must use the same service instance where you registered the UI view.  Next, it calls ShowDialog to display a modal view.  It takes two parameters – the view key, and the view model.

A modal view is one that forces the user to interact and dismiss the dialog before they can continue working with the other elements in the application.  It is what, as an example, applications often use for Options dialogs.  ShowDialog will display the View associated with the given string key (“ShowElementProperties”).  The second parameter is the ViewModel you want to associate to it – in this case we are passing the associated picture we want to work with.  The dialog is then displayed and allows the user to edit the picture properties:

The XAML code for this view is contained in the PropertyWindow.xaml file – it has a couple of interesting elements to it which you will see when you interact with this dialog:

1. Watermarked Text display: if you remove the title, it will display some grayed out text in it’s place “Enter the Title Here”:

2. Numeric TextBox:  if you move your mouse cursor over the X/Y/Width/Height boxes you will see a sizing arrow that allows you to drag and change the values without typing.  You can also double-click to change the values and it enforces numeric text box behavior.

Both of these are accomplished with Blend Behaviors. There are plenty of resources on the web about these so I won’t go into detail on their creation – check the library source code if you want to see how they work, but using them involves taking a dependency on two assemblies:

1. System.Windows.Interactivity.dll
2. JulMar.Wpf.Behaviors.dll

Both of these are included in the Dependencies folder.  The first comes from the Blend SDK and is freely redistributable with your project.  To use them, you add the behavior to the visual element in question, for example, the watermarked textbox behavior gets applied like this:

I’ve also applied a Trigger to change the font/colors when the TextBox is watermarked.

The numeric behavior looks like this:

Notice that I’ve changed the Binding.UpdateSourceTrigger to be PropertyChanged – this is so the dragging effect works properly and updates the value in the underlying view model.

Ways to invoke commands in the view

So let’s look now at how we get the command executed.  Switching to the MainWindow.xaml you will find three places where the Show Properties command is wired up.

First, it can be invoked using a keyboard accelerator. This requires using a BindableCommand from the library, placing it into resources and then binding against that.  The command we will be executing is the one on the MainViewModel so it requires the actual picture element as a parameter:

The MainViewModel simply forwards this command onto the PictureViewModel using a typed DelegatingCommand:

Next, we can invoke the command using the menu and toolbar:

Note that here we are also binding to the MainViewModel command – so we must supply the parameter using the CommandParameter.  The final invocation place is when you double-click on the picture itself.  This is done a little differently if you’ve not done much WPF work. 

A quick segway – View code behind vs. View Models

First, the display of images is actually housed in a ListBox.  It turns out that anytime you need to display multiple things grouped somehow, and allow the user to select one or more of those things, a ListBox is almost always the way to go.  WPF allows us to customize the visuals however we like, so here the panel has been replaced with a Canvas (allowing pixel positioning), and each item is drawn as a DataTemplate.  The template decides how to render each item in the ListBox – the PictureViewModel in this case.  In the sample, it is rendering an image and an optional TextBlock that is turned on and off through a property (and can be changed through the tool bar).  I encourage you to look at the code to see how all that is done. 

One of the core things necessary in MVVM is the ability to interact with visuals and then sometimes push notifications of that interaction back to the view model.  I say “sometimes” because it’s perfectly acceptable to place code into the code behind for the XAML as well. Where you put the logic depends on whether it is view-specific and whether you want to test it independently of the view.  If it’s not view specific OR you want to test it, then move it into the view model.  An example of something that we probably don’t care about is closing the application – I’ve wired it up to a command here just to show that you can, but it’s completely unnecessary to do that.  The view model isn’t doing any closing logic, so it would be fine to wire a handler into the MainWindow.xaml.cs and just call “this.Close()” in there.

Ok, so back to the double-click implementation.  In the DataTemplate assigned to the ListBox.ItemTemplate property you will find the definition for the image itself:

Note the use of the Interaction.Triggers tag – this is also part of the Blend behavior implementation.  In this case, we are triggering off something (property change, event, etc.) and then performance some action.  In the JulMar.Wpf.Behaviors assembly you will find a whole bunch of triggers, behaviors and actions.  In this case, I am using the DoubleClickTrigger which monitors for a quick double tap of the left mouse button.  When that happens, it runs the list of actions associated with it – in this case, it invokes the ShowPropertiesCommand.  Now, here we are defining the trigger behavior on the UI that is bound to an actual PictureViewModel (note the property bindings on the image and you will see that I’m telling you the truth!) So here the command being invoked is the PictureViewModel command – so no parameter is necessary.

Drag/Position Behavior

The last thing I want to point out is the dragging behavior.  This is also done through a Blend behavior, but it is being applied in a slightly different way: through a Style. 

...

Now, for those who have used Blend behaviors a lot, you may now that it is currently not possible to apply behaviors through Styles.  This is a restriction of the Attached Property definition being used – the collection cannot be associated on a style.  This is a very unfortunate problem because it makes my scenario very hard: I want to drag and reposition these items around through the mouse.  If I put the behavior onto the DataTemplate then I move the content but not the item container itself (the thing that provides selection and focus rendering)  So I would end up with a very weird visualization where you click on an item and the focus rectangle is drawn in a completely different place than the item itself!

So, in my set of behaviors, many of them allow you to setup the behavior both through Blend and through Style setters (or directly on an element without the full Blend syntax).  I do this by adding an attached property onto the behavior class and then injecting my behavior into the element where the attached property is set.  I’ll show this in a future blog post to give an example for those who’d like to do the same for their own behaviors.

Another question I’ve fielded is why did I even create this behavior at all when the Blend sample already exists to do this?  Well, the short answer is because I had a specific goal in mind here – this behavior knows about Canvas panels.  If the behavior is attached to an element in a Canvas, it changes the position by changing the Canvas.Left and Canvas.Top properties.  If not, it uses a RenderTransform.  The supplied blend sample only uses RenderTransform (at least when I last looked at it).

That about covers it, if you have any questions or comments, then contact me!

In this post, I will go over the simple message visualizers available in the MVVM Helpers toolkit.  Essentially the idea is that it is fairly common to want to display a simple message from the ViewModel to the user.  Since the VM is supposed to be testable, we encapsulate this ability into four services, three of which I’ll focus on here:

To demonstrate the first three visualizer types, we’ll build a very simple MVVM application to display messages.  I start with the project template and remove all the ViewModel and View code to have a blank solution.  Each of the three visualizers we are going to look at take a string Title and Message as their parameters – we’ll drive it from a unique command for each.  To start with, let’s define a simple data structure that wraps an ICommand and a textual title:

Next, in the MainViewModel.cs file, we need a Title string property – this will be the title for each of the visualziations.  It’s just a simple field-backed INPC property, we’ll bind it to something in the view:

Now we can create a collection of the TitledCommand objects and display them to the user for execution.  We will place this collection into the MainViewModel.cs.  Let’s populate it with a set of delegating commands for each type of visualization we want to create.  We will use the DelegatingCommand<T> version which allows us to type the parameter being passed.  We will assume the inbound parameter is always the message to display and there a string:

The CanExecute handler for each of them will test the Title property – ensure there is a value there, and the inbound parameter (the Message) and make sure there is a value there as well.

IMessageVisualizer

The IMessageVisualizer is used to show a simple message to the user – it takes a title, message and an enumeration to decide which buttons to display.  The default implementation of the service displays a MessageBox.  

The buttons you can display include:

The result from the service is which button was used to dismiss the dialog:

Using the visualizer is very easy – request the service from the service locator using the Resolve method (this requires you derive from the JulMar.Windows.Mvvm.ViewModel base class, or hit the service locator using the static property):

Notice that I test to ensure the visualizer is available – remember that services can be replaced or removed – I might do this in my unit tests for example (I actually mock the interface rather than replace it, but you get the point – test to make sure it’s there).

We want to see the result, so I take the resulting enum and convert it to a string and assign it to a new Result property on the ViewModel.  This, like Title, is just a field-backed string that does a property change notification.

IErrorVisualizer

The error visualizer is for cases where you want to display an error dialog to the user with a title and message.  The default implementation displays a MessageBox with an OK button

It returns a boolean response indicating that the user clicked the OK button (versus dismissing using the Close “X” button).   It has a similar interface to the message visualizer:

We will assign the boolean result to the string Result property as well.

INotificationVisualizer

This visualizer is for cases where you are doing something in the ViewModel logic, on the UI thread that takes a moment to process.  Sorting a list, or searching an in-memory list might be an example.  True long-running operations should always be on a separate thread and use properties or the message mediator to coordinate with the UI thread.  That said, there are times when you want to do the logic inline with the request and you know it’s going to take a second or two to process it.  Enter the INotificationVisualizer.  It takes the same title and message as it’s cousin visualizers but the default implementation does not use them – instead, the default implementation simply changes the cursor to an hourglass (the defacto standard for “please wait”).  This is a service that I often replace with a custom visualzation – a progress bar, thumbar progress on Windows 7, or even a dialog overlay.  Invoking it is simple:

The BeginWait() method kicks off the notification visual (hourglass cursor in this case).  It returns a disposable object that you invoke Dispose on to return to the normal cursor.  Again, let me stress this is not optimal for a true long-running operation – this locks the UI up until the thread returns so only use this for very short operations.

Creating the View

The View for this application will be simple – let’s use an ItemsControl to generate a button for each of the exposed commands, two TextBoxes to hold the Title and Message, and then a TextBlock for the result, here’s what I want it to look like:

I’ll let you go through the XAML – it’s straightforward and should be pretty easy to follow.  The only new thing might be that we’ll set focus to the first focusable element using the FirstFocusedElement markup extension:

That should do it – if you’d like to just download the project and play with it, it’s available here: VisualizerTest.zip.  In the next post we’ll take a look at the grand-daddy of the message visualizers in the MVVM Helper toolkit: the IUIVisualizer!

A question I got recently was how to manage Radio Buttons with bindings – in this instance, the sample code was trying to map a single value to a set of Radio Buttons based on an enumeration set.  The original implementation was using a Value Converter to compare the “bound” value with the enumeration value expected for that radio button choice – if it was equal then the converter returned true, otherwise false.  Something like this:

Initially this seemed to work, but as you changed the current enumeration value, the radio buttons would “lose” the binding – and after a few times you would end up with none of them selected.

Ultimately, this problem is really an expected behavior from WPF – when a set of Radio Buttons are placed together, they act as a group – where only one is expected to be checked and all the others are unchecked.  This happens because the selected Radio Button itself tells the group to uncheck all the others.  This has the effect of replacing the binding value for IsChecked with a local value of false.  See the problem?  Eventually, all of the buttons in the group have their value replaced and so we end up with all of them unchecked.  The solution was very easy – put each one into a separate group by defining a unique GroupName for each Radio Button. 

This solves the problem and required no real code changes, but of course, I didn’t want to stop there – I just had to whip up a quick MVVM version to show how I’d do this if I were responsible for the application!

Sample Application Description

Our goal will be to display a list of children and their details to track their favorite games.  I started by sketching it out with SketchFlow to get a sense of what I wanted to visually create:

The top list is a ListBox, showing each child and the bottom pane shows the details.  Note the RadioButtons used to represent Gender and Favorite Game.  Our goal will be to use a ListBox there as well – showing the list of Radio Buttons and bound to a ViewModel collection of data.  As a secondary goal, we want to separate the RadioButton value from the text displayed. 

It turns out that anytime you need to display a list or sequence of something, a ListBox (or ItemsControl if you don’t need the selection capability) is almost always a good choice.  Let’s see if we can make it work here with the MVVM pattern.

Now that I have an idea of what I want to build, I created a blank Windows WPF application and added the JulMar MVVM Helper library and created the directory structure I prefer (Views, ViewModels and Dependencies).  I moved the Window1.xaml and corresponding code behind into the Views folder and renamed it MainWindow.xaml.  This also required I adjust App.xaml to point to the correct StartupUri (Views\MainWindow.xaml).  As a quick start you could also just use the JulMar MVVM project template and delete the XAML and view models.  Here’s what I ended up with in the solution:

Now, we’re ready to begin our data modeling.  In this case, I don’t have a real data model – I’m not going to store or manage any of the children in a persistent way so I’m just going to define the View Model definitions for the children and collection.  We’ll start with the child definition.  I created a class to manage the properties of the child I want to display: Name, Dob, Gender, and FavoriteGame.  For the Gender and Favorite Game, I will use Enums to model those as a known list.  I could have used a Boolean for Gender as well, but this serves my underlying goal so we’ll go with an enumeration.  Here’s what I came up with:

Pretty standard stuff – we have field backed properties and raise the PropertyChange notification on each one.  For this case I don’t think we’ll need any additional services so I derive from the JulMar.Windows.Mvvm.SimpleViewModel class which just provides INotifyPropertyChanged support.  The one extra thing I’ve added here is a Details property which is a concatenation of all the other properties – we’ll use this to verify that the data binding is working properly as a secondary display of the same data.  We need to be sure to include that property invalidation when any of the other properties it depends on changes.  The OnPropertyChanged implementation allows you to pass multiple strings for this very purpose.

Moving on, I want to display the generated Enumerations above as a list, so we need a way to encapsulate a value and the text used to represent the value together.  If I were using .NET4 I could use the uber-cool new Tuple<K,V> class but I want to target .NET 3.5 here so we’ll define a new ValueAndText class to hold this:

Now, let’s turn to the actual glue – the MainViewModel that pulls it all together. 

Let’s use a SimpleViewModel here as well.  The first property we need is a collection for the children – we won’t be modifying the list (i.e. no adding or deleting) so the backing storage can just be a List<T>, as part of the constructor we’ll populate it with some sample data:

Next, we want a single child to be the “current” selected child.  This is just a property of type ChildViewModel exposed by the parent view model.

We’ll also set the first child as the current child in the MainViewModel constructor after we populate the collection:

We want to have a bindable list of the gender values (and text) and a bindable list of the game types.  In this case, let’s take advantage of the ability to bind to any IEnumerable data source and just generate the list using the C# 2.0 iterator support:

That should do it for our logic and data requirements, now let’s turn to the visualization for it.  We have the following properties defined on the MainViewModel to drive the view:

Using the SketchFlow prototype as an example, we’ll start with a DockPanel as the root element – locking a StatusBar at the bottom, a ListBox at the top and a Border (which will contain our details pane) as the fill content.  We’ll use the JulMar ViewModelCreator markup extension to tie this to the MainViewModel, and let’s push the initial focus into the children ListBox using the FocusManager.FocusedElement attached property on the window.

Next, let’s fill in the top ListBox details.  We need to populate it with the list of children – this is the Children property off our ViewModel, so we’ll bind the ItemsSource property to that collection.  Next, we’ll set the SelectedItem to the CurrentChild property – making sure to use a two-way binding:

This will generate a list of items, but won’t have any decent visualization – so we’ll use a DataTemplate to give us a basic visual, at the same time, let’s replace the default panel with a WrapPanel so it looks more like our SketchFlow:

Now, let’s turn our attention to displaying the current child details.  Remember the properties we created on the ChildViewModel:

So let’s first use the details – we can bind a TextBlock in the StatusBar to the CurrentChild.Details property to display the selected child details:

Now, let’s turn our attention to the details – we’ll use a Grid to lay it out within the Border, the Name and Date Of Birth are pretty easy to just drop in a set of Labels and TextBox/DatePicker – we’ll need the WPF Toolkit for this.  We’ll drop in two ListBox elements for the Radio Button list.

Let’s focus on the Gender list first – the same concepts will apply to the game list.  We have an IEnumerable list of ValueAndText objects – each object has a Value property (corresponding to the underlying enum value tracked in the ChildViewModel) and a Text property which is what we want displayed in the RadioButton choice.  First, let’s set it up so we get a list of RadioButtons – we can do this by changing the ControlTemplate for each item in the list itself – that is, change the ListBoxItem control template. 

As a bit of background, anytime you add an element to an ItemsControl (ListBox, ComboBox, TreeView, Menu, etc.) a special wrapper is internally created around your data to provide the special UI properties necessary to drive the functionality – things like focus, selection, mouse-over, etc. are all provided by this wrapper.  In the case of the ListBox, the created wrapper is a ListBoxItem class and we can control it’s properties by overriding the ItemContainerStyle on the ListBox itself.  So, to start off, we’ll create a new Style for the ListBox, set some basic properties and then override the ListBoxItem style inside that:

Since this is going to list a group of radio buttons, we’ll drop the border off the ListBox and the Background color as well so that our parent’s background shows through.  We’ll throw a Margin on there to give it a little spacing. Next, to change the visualization of the ListBoxItem, we’ll override it’s ControlTemplate (the thing that generates the visual tree for the item).  This, like all Controls in WPF, is done by overriding the Template property. What we want is put a Radio Button in there:

In order to get the IsChecked state properly setup, we’ll bind it to the ListBoxItem.IsSelected property – so if the item is selected according to the ListBox, then the Radio Button will be checked.  We also drop a ContentPresenter into the RadioButton so it displays whatever the data bound value is – this will provide for any DataTemplate visualization if one is present.  This will achieve the visualization we desire, but it won’t work properly as we interact with it.  The problem is that the Radio button will override this state when it is clicked – exactly the problem we had originally!

To fix this, let’s make the radio button invisible to the mouse and keyboard.. we can do this by setting the Focusable and IsHitTestable properties to false – however this makes them non-interactive and now we can’t select the ListBoxItem with the mouse.. so, let’s wrap it in something that is selectable – anything should work, so we’ll just throw it into a Grid.  Set the Grid.Background to transparent so you can click on it and we end up with:

This does exactly what we want – clicking on the radio button changes the selection in the ListBox and, in turn, checks or unchecks the radio button in question.  Now, let’s wire it up to our data – remember we have a Value and Text.  We want to bind to the Value but display the Text.  It turns out the ListBox already has this feature backed in – there is a SelectedItem property we normally use, but there is also a SelectedValue property that makes the distinction between the item in the collection and the value used to select it.  There is also a DisplayMemberPath and SelectedValuePath property used for data binding purposes when generating the content from an ItemsSource supplied value.  Pulling these things together we can do this:

Testing this, it works perfectly!  Since the DisplayMemberPath/SelectedValuePath are the same for the two lists, we can move that to our radioListBox style, leaving us with the two ListBox definitions being:

And the completed application looks like:

You can download the completed project here: RadioButtonBinding Test

The main project I’ve been working on the past few months has been a rRNA sequencing application.  It’s a joint project involving Microsoft Research and the University of Texas in Austin.  The goal being to produce lightning fast visualizations (nucleotide, 2D and 3D) with very large (100,000 sequence) data sets on WPF.  It’s been a big learning experience for me in many ways because the traditional mechanisms for dealing with things in WPF just flat out fail when we load big datasets and start scrolling them around.  So, we’ve had to invent data virtualization schemes, our own UI virtualization for scrolling, several custom controls and a variety of other elements to pull it off so far.  rCAT 4.0 (coming in March) is even more ambitious with editing support for the sequences!

All that said, our current effort is now online with full source code – it’s interesting stuff to browse through even if you aren’t into molecular biology – check it out at http://rcat.codeplex.com/

Here’s a nice screen shot showing some of the elements – dockable tabs and sidebar items, birds-eye viewer, taxonomy viewer and custom colorization of nucelotide data.  And it, of course, is all MVVM.  Fun stuff!

I know I said I was going to cover some services next, but I got a request last night to show how to rename TreeView nodes (ala Explorer) using the MVVM pattern in WPF.  The solution is quite easy and elegant and I thought I’d share it here.

First, the idea is we want to be able to double-click on the text portion of the TreeViewItem and have it allow us to type in a new name, replacing the current text.  This involves changing the visual template out (from a TextBlock to a TextBox) and then detecting that the edit is complete.

I started with the MVVM project template, creating the default File Explorer view.  The TreeView on the left is displaying folders – so I opened the DirectoryViewModel.cs that drives the data.

First, let’s add a property to indicate whether we are in “editing” mode or not.  This is a simple field-backed property that raises the PropertyChange notification:

I also added the private field (_isEditingName) into the class.  Next, locate the Name property that is being used to display the name.  Here we need to add a setter that renames the directory.  We want it to be robust, so we do some upfront checks and make sure to catch any I/O exceptions that occur:

Notice how changes the editing flag at the end – we assume that once the rename has occurred we are out of editing mode.  Finally, we need a way to transition from “normal” to “edit” mode and back.  In the VM these kinds of things are driven with commands – so, let’s define an ICommand that takes us in and out of edit mode:

And then finally initialize it in the default constructor – we also now need to chain to that constructor from the parameterized version since we always want this initialization to happen (you could also do the initialization in both, but I prefer this approach):

That’s all the code changes we need for this – now let’s switch to the View and see how we will wire this up!  Open the MainWindow.xaml file and look at the DataTemplate used by the TreeView.  All of our changes will go into this template. First, we need to add a TextBox into the template that sits in the same space as the TextBlock that displays the name.  Then we need some way to switch between these two elements – I use Visibility here, you could also swap out the entire template.  We’ll use a DataTrigger and drive it off our new IsEditingName property:

The other thing we need to do is set the TextBox binding (which also uses the Name property) to apply any changes when the control loses focus – that way we don’t rename as the user types!  This is done by changing the UpdateSourceTrigger on the binding to “LostFocus”. This happens to be the default setting for WPF – but not for Silverlight, so I tend to be deliberate when I want to ensure a specific behavior.  I’ve also added a converter onto the binding above – the RefreshValueConverter.  This is a no-op converter, but it forces WPF to re-read the property value after the setter is called, without it, the TextBox will have stale data if the rename fails.  Note that this is unnecessary in WPF4 which now always re-reads the property values automatically.  Since this targets WPF3.5, this converter will ensure proper behavior.

The final thing we need to do is somehow get in and out of editing mode.  We want this to happen when we double-click on the text element – so let’s add a JulMar behavior and action to the TextBlock:

This also requires you define the proper namespace on the Window element:

I’d also like to drop out of editing mode when you press ENTER in the TextBox. To accomplish this, let’s add an InputBinding to the TextBox for the ENTER key that invokes our SwitchToEditingMode command – in WPF 3.5 we need to go through a resource-based binding helper to get access to the ViewModel (which is our DataContext).  So, let’s defined a BindableCommand in the Grid resources (so we get the DirectoryViewModel as the DataContext) and then bind the input command to that:

…

And that’s it!  If you run the app and double-click on a directory name (except the root) you can rename it!

Here’s the finished solution: RenameTreeNode.zip

In the previous post, I provided a link to the project template you can use to start a new MVVM project using the JulMar MVVM library. Here's the two links in case you didn't get them before:

MVVM Helpers Distribution
Project Template

Copy the project template into your Visual Studio 2008 templates directory located off your user documents - mine is at %UserProfile%\Documents\Visual Studio 2008\Templates\ProjectTemplates\Visual C#\Windows.

Ok, so once you have these installed, what can you do with them? Well, for starters, you can now generate a starter project that provides a nice template for an MVVM application. The starter template creates a simple "Explorer" like program - it looks like this:

Notice there are two sections - a TreeView listing all the directories, and a ListView showing all the files in the selected directory. Let's look a little closer at the project structure. There are four directories in the solution:

Views

Let's start with the last folder - the Views. Views are the UI presentation of data - in the case of a WPF/Silverlight application this is most commonly the XAML and XAML code behind files (they are considered a single element together). We want to have UI-specific code and designer elements present in these files. Generally we prefer to place business logic and testable elements into the ViewModel area.

In this starter project, we have a single view MainWindow.xaml. This is what presents the main UI shown above. The code behind file contains the required boilerplate code (essentially a constructor and call to InitializeComponent).

If you open the view (note that the designer will choke on it until you compile the project), you will find fairly straightforward XAML that creates the UI, let’s break it down as we go:

<Window x:Class="WpfMVVMApplication1.Views.MainWindow"

    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

    xmlns:julmar="http://www.julmar.com/wpfhelpers"

    xmlns:ViewModels="clr-namespace:WpfMVVMApplication1.ViewModels"

    xmlns:Converters="clr-namespace:WpfMVVMApplication1.Converters"

    DataContext="{julmar:ViewModelCreator {x:Type ViewModels:MainViewModel}}"

    Title="File Explorer" Height="400" Width="500">

First, notice how the DataContext is established – through a custom MarkupExtension called ViewModelCreator.  This extension is responsible for creating an associated ViewModel for this view (where our testable business logic should go) and also wiring up a couple of special event handlers that will allow the ViewModel to activate the view and close the view respectively.

Next, let’s check out the resources:

Here we find three defined resources – first we have a JulMar MVVM BindableCommand.  This is a special ICommand instance that can be data bound and forwards to the specified binding.  We use this a bit later in the keyboard accelerator to close the application.  Next, there is the converter that takes a filename and converts it to an icon – that’s the source code in the Converters folder mentioned earlier.  I use a converter here because this is very UI-centric and not very testable – so the converter will data bind to a string (filename) property of the ViewModel and retrieve the icon for the UI to display.  That way, my ViewModel sticks with base (non-WPF) types.  This isn’t a hard rule – but it’s a good one to try to follow.

Finally, there is a DataTemplate that is used to display the directory structure – this is what the TreeView uses to display it’s data.  Notice it data binds to a couple of properties – FullName, Name and IsSelected.  All of these, as you will see, exist in our ViewModel definition.  The View takes the data from the ViewModel and displays it onto the UI for the user to interact with.

Next in the XAML is the input bindings – this is where we define keyboard and mouse gesture accelerators, and it’s where I use the bindable command I defined earlier:

Here you can see that instead of trying to bind to the command, we use {StaticResource} to get it from the resources.  This is necessary under WPF 3.5 because the KeyBinding will not inherit the DataContext and so cannot bind directly to the command – but resources can, and specifically Freezable resources can – that’s what the BindableCommand provides – a Freezable resource that forwards the ICommand implementation onto a command defined in the DataContext ViewModel.  This is not necessary under WPF4 – this is actually one of the new features they’ve added: to inherit the DataContext in your input bindings! 

The remainder of the view is fairly traditional – we use bindings to connect the UI up to the ViewModel definitions, so let’s go look at what those are.

ViewModels

The ViewModel folder contains three source code files – DirectoryViewModel.cs, FileViewModel.cs, and MainViewModel.cs.  If you recall from above, MainViewModel is the primary ViewModel that is data bound to the view.  The other two are child view models used to represent the files and folders respectively.  Let’s look at FileViewModel as an example:

As you can see, it is very simple – it is simply a wrapper around a piece of data, a FileInfo that represents a file on disk.  It exposes properties that are data bindable.  There is one element (MarkerFile) that I want you to ignore for a moment – we’ll get to it in a second.  Notice that it extends SimpleViewModel.  This is one of three primary VM classes in the MVVM helper library.  SimpleViewModel is intended for cases where you need the bare minimum support – specifically support for INotifyPropertyChanged.  No other services are provided by this base class, and as such it is very light.  Let’s look at the directory class next:

This file is a bit more complicated – like the FileViewModel, this wraps a simple data object (a DirectoryInfo in this case).  Notice that it too exposes properties to provide access to various bits of information.  Here you can see that it is creating new properties such as TotalFileSize which is the sum of all the files sizes in this directory.  That’s one of the jobs of the ViewModel – to provide easily bindable properties for the bits of information we want to display.  In this case, the TotalFiles and TotalFileSize gets displayed in the StatusBar of the window when the directory has files.

Notice that the directory exposes files and subdirectories in ObservableCollections – but they are delay populated.  This is done so that the TreeView comes up quickly and we don’t have to enumerate the entire disk to retrieve the directories and files!  When you expand and collapse the nodes in the tree, it is populating the data.  This is done through the IsExpanded property – if you look back in the View, you will see that the TreeView actually binds the TreeViewItem.IsExpanded to this property:

Notice it also binds up the IsSelected property – this is when we populate the files collection.  Since they are observable, they will force the UI to update when new items are added or removed and we see the Explorer effect we desire.

Lastly, before we leave this file, notice that when a directory is selected, it makes a method call to a function called SendMessage:

SendMessage(SelectedDirectoryChangedMessage, this);

It passes a string (the key) and an object (the data).  This is a built-in service of the ViewModel base class and it’s the reason why this ViewModel does not derive from SimpleViewModel, but instead from ViewModel which is the full version.  One of the services provided is a Message Mediator.  This service basically allows you to loosely couple various objects together – we’ll see how the target registers, but for now, just notice the sender – it passes a string key and an object.  Any target registered for the given key will receive the object.  There are several overrides for the message mediator which I’ll detail in a later post.

Ok, let’s switch to the final file – the MainViewModel:

Here you can see the same basic principle – it exposes properties the UI binds to.  In particular here we see Commands being exposed as properties.  Commands is what drives a UI – it allows a UI to trigger actions in the ViewModel.  We are using two basic commands here – CloseAppCommand and DisplayAboutCommand.  If you look at the constructor, you will see they are backed by a DelegatingCommand object.  This is a common pattern found in almost every MVVM framework out there, but it’s essentially a pair of delegates that are called when the command is checked and when it is invoked.  In our cases here, we always allow the command to execute so we only provide the execution handler (a second parameter would define the typical CanExecute handler).  There are a couple of overrides for this object as well – one that provides type safety for the parameter and one that always uses object and allows for any object as data.  Again here we are being simple and not using any parameters so our bound methods are both no-parameter methods.

The CloseAppCommand command invokes the OnCloseApp method – which in turn calls RaiseCloseRequest.  This JulMar ViewModel method will close the view associated with the ViewModel if you associated the two using the ViewModelCreator.

The OnShowAbout method is called by the DisplayAboutCommand.  It uses another registered service in the library called IMessageVisualizer.  The message visualizer is used to display a simple message box from the ViewModel.  Here we use it to display an about box.  There are several other services I’ll talk about in the next post.

Notice that the RootDirectory property which is data bound to the TreeView.ItemsSource is exposes as an array – this is because the TreeView always expects a collection of items even though we always have a single root item.  So we wrap a single DirectoryViewModel into a collection and return it as the property.

If you look at the end of the file you will find our message mediator target – OnCurrentDirectoryChanged.  We use this as a way to see when a new directory has been selected in the tree.  For a ListBox, we could  have just data bound the SelectedItem to the property, but TreeView isn’t a selector and doesn’t expose a SelectedItem property.  Instead you either have to catch an event (I’ll show how you can do that in a future blog entry about the MVVM helpers library) or use this little mediator trick.

The [MessageMediatorTarget] attribute is the secret sauce here – it tells the message mediator to wire this method up to the passed string key.  When that key is used in a SendMessage call and the parameter type is a DirectoryViewModel (or derived type), the mediator will invoke this method.  This all happens without any direct linkage between the DirectoryViewModel and the MainViewModel.  The delegate instance is held in a weak reference so there’s no concern for memory leaks.

The second part of the magic is in the constructor – the message mediator is an opt-in service, so notice the call to RegisterWithMessageMediator().  This is what causes this instance to be noticed by the mediator.  There is a balancing UnregisterWithMessageMediator if you ever want to unhook the instance.  You can also use methods to directly wire up handlers (without attributes).  This is useful when you are dynamically linking things together at runtime vs. compile time.

Well, that covers the basics of the framework Views + ViewModels.  In the next post, I will detail the service registration and basic service mechanism that’s built into the framework for you to use.  Until then, ciao!

With that in place you should be able to fire up Visual Studio 2008 and create a sample MVVM project:

Let it generate a project and the build it -- running the program will give you a simple file explorer using the MVVM design pattern and WPF:

In tomorrow's post, we'll break the sample down and see how I built it. See you then!

With this post I am starting a new series - I hope to be more consistent in posting at least once or twice a week. To that end, I am going to focus on the WPF/MVVM helper library I use daily. I released an earlier version of it onto the web and have gotten a lot of comments which has been great, so I am releasing the latest version which has a lot of changes. So, without further ado, here's the code for you to download and play with, this compiles with Visual Studio 2008 SP1, or with Visual Studio 2010 Beta 2.

mvvmhelpers.zip

Read on for the basics of the project structure and files.

Project Structure

Building and Usage There are pre-built assemblies included in the distribution, but you are free to build the source on your own - I don't include the certificate file (so I can tell versions that I have built) but you are free to delete the certificate from the solution or replace it with your own and build your own binaries from the source code. Or you can take any of the source code, modify it however you like and add it directly to your project. Credits As with most projects, this library has benefited significantly from the community. The WPF Disciples list on has been a particular source for ideas and even source code. There are some source files in the project that I did not author, or where I took a bit of code and modified it to suit my purposes. I have tried to make sure people get credit where appropriate in the source code itself, if I missed anyone I am truly sorry. Documentation As I mentioned earlier, my goal is to produce a set of blog posts that detail how to use the library, but there is also some documentation on each class included in the distribution in the form of a .CHM (Windows Help File). I encourage anyone who wants to use this library to check that out.

One of the new features added to WPF 3.5 SP1 was the ScrollViewer.IsDeferredScrollingEnabled property which allows you to scroll through large amounts of data without taking the actual scrolling hit until the user stops moving the scroll thumb.  This is essential when you have complex visualizations, or if the data itself is virtualized and the load time is expensive.  You can get information on this feature here:

http://msdn.microsoft.com/en-us/library/system.windows.controls.scrollviewer.isdeferredscrollingenabled.aspx

Recently, I was working on a project where I have a Slider that is controlling a grouping option.  When the user changes the slider value, the visuals are regrouped based on the position of the slider itself.  The problem I ran into was it's an expensive operation to do the grouping and if the user tries to quickly drag the slider I ended up doing a whole bunch of non-essential groupings of my data for no reason.  They are expensive enough that the actual drag of the slider was impacted by it - not to mention the CPU and rendering!  So, my initial response in these situations is to turn on asynchronous data binding - that's as simple as throwing the Binding.IsAsync flag.  This essentially causes the binding transfer to occur on a background thread and will often improve responsiveness in situations like this.

In this case, however, it didn't really help because I was still doing all the intermediate calculations.  What I really need is some way to defer the binding transfer until the slider stops. There's no option for that however so I whipped up a simple class which allows me to bind two properties together and place a timer between them to indicate how long it should wait before transferring the Source to the Target.  I could have done it in the code - it's just a timer solution after all, but I wanted something reuseable.

Here's an example usage:

<StackPanel>
   <StackPanel.Resources>
      <DeferredBinder:DeferredBinding x:Key="dbTest" Timeout="1" />
   </StackPanel.Resources>
   <TextBlock x:Name="tb" Text="{Binding Source={StaticResource dbTest}, Path=Target}" FontSize="48pt" HorizontalAlignment="Center" />
   <Slider x:Name="slider" Margin="10" HorizontalAlignment="Center" Width="200" Minimum="0" Maximum="100" Value="{Binding Source={StaticResource dbTest}, Path=Source, Mode=OneWayToSource}" />
</StackPanel>

In this case, the slider's value is transferred 1 second after the final update (i.e. it waits 1 second for the user to stop sliding).

Here's a sample project to try out:

DeferredBindingSample.zip

I'm a big fan of themes in WPF -- and I think it's great that Microsoft has released a whole set of themes for Silverlight and WPF at www.codeplex.com/wpf

However, in using some of those themes, I've run into an annoying bug in the RadioButton template - specifically, the checked state doesn't always show up initially.  Looking at the template, it turns out to be an easy fix.  The "CheckIcon" is set to an opacity of zero initially (so it's not shown) and then a trigger is used to apply an animation to change the value.  Unfortunately, it looks like the animation is switched - it applies when the checkbox is UNCHECKED vs. CHECKED.  So, two ways to fix it -- either change the initial opacity to "1" for the "CheckIcon" element in the control template, or go to the triggers in the control template for the RadioButton and swap the states so it looks like this:

<Trigger Property="IsChecked" Value="false" />
<Trigger Property="IsChecked" Value="True">
   <Trigger.EnterActions>
      <BeginStoryboard x:Name="CheckedOn_BeginStoryboard" Storyboard="{StaticResource CheckedOn}"/>
   </Trigger.EnterActions>
   <Trigger.ExitActions>
      <BeginStoryboard x:Name="CheckedOff_BeginStoryboard" Storyboard="{StaticResource CheckedOff}"/>
   </Trigger.ExitActions>
</Trigger>

I just put the latest version of the MVVM helpers online - mvvmhelpers.zip

There's a bunch of new stuff in it - check the release notes for the highlights.  There's a set of breaking changes in it as well, specifically I've moved several of the attached behaviors into the new Blend model.  Originally in my local version I did it to the JulMar.Wpf.Helpers.dll and got a dependency against System.Windows.Interactivity.dll.

I decided that for this release I didn't want to force that dependency so I created a secondary assembly JulMar.Wpf.Behaviors.dll which has all those behaviors in it.  The breaking change is I removed the original attached behaviors from the library (DoubleClickBehavior, NumericTextBehavior, MouseDragBehavior) in favor of using these new versions.  I did update the sample to show how they get used.

In a recent Essential WPF class, one of the students wanted an ObservableDictionary which we whipped up there - I cleaned up that implementation somewhat and added it into this library along with some unit tests for it.

Again, please check the readme included in the .zip file -- as always you are free to do whatever you like with this code.  If you do anything interesting or fun, let me know!

A recent series of blog entries at http://themechanicalbride.blogspot.com/ introduced the Rx framework (System.Reactive.dll) which is an assembly used in the Silverlight toolkit for UI testing purposes.  It essentially provides a mechanism to do event driven programming through LINQ.  I'll refer you to the blog referenced above for all the gory details - frankly I'm still trying to wrap my mind around it!

Silverlight isn't my favorite technology however, I much prefer working in WPF and so I spent some time rebuilding Rx for the desktop CLR!  My original approach was to take my favorite exploration tool, reflector (available for free from www.redgate.com), and disassemble all the classes into C#, placing them into a project file.  I found however that Reflector choked on some of the more complicated structures - requiring me to go and hand-edit a bunch of the code.  I realized while I was doing this that there was a much easier way to convert a Silverlight assembly to a WPF assembly.

As you probably already know, Silverlight shares the same assembly format as the desktop CLR - there is no difference in the IL or structure of the assembly itself.  The difference is in the dependency on mscorlib and other references.  Specifically, when you add an assembly via VS2008, it looks at the version of the referenced mscorlib to determine whether it's a desktop CLR assembly or Silverlight assembly. 

Here's the header of a Silverlight assembly examined through ILDASM:

One of the coolest new features of Blend 3 is the inclusion of behaviors. This new feature formalizes the "attached behavior" model that has become so prevelant in WPF (and Silverlight) development.  I won't go into details on the architecture - instead I'll refer you to a nice reference:

http://blogs.msdn.com/expression/archive/2009/05/19/link-round-up-behaviors-related-posts.aspx

To play with this new support, I built a WatermarkTextBehavior which places a watermark into a TextBox when it has no entered data.  I've included this new behavior into the current build of my MVVM toolkit which I'll release soon, but for now, let's look at the behavior:

First, we derive from System.Windows.Interactivity.Behavior<T> - the placeholder parameter is the Visual type you want the behavior to act on.  This can be UIElement for anything WPF, or more restrictive if necessary based on the events you intend to hook up.  For our purposes here, we will set the restricted type to TextBox.

public class WatermarkTextBehavior : Behavior<TextBox>

Next, you override the OnAttached() and OnDetaching() methods to hook up your event behaviors you desire.  Call the base implementation first, and then the AssociatedObject property will be the element you've been attached to (the TextBox in this case).  In our case we want to hook the GotFocus and LostFocus events - this is where we trigger our behavior.

protected override void OnAttached()
{
   base.OnAttached();
   AssociatedObject.GotFocus += OnGotFocus;
   AssociatedObject.LostFocus += OnLostFocus;
   ...
}

Finally, we can provide any properties necessary to drive our behavior.  These should be done in the form of Dependency Properties so they are bindable and interact nicely with WPF.  The base Behavior<T> derives from Freezable and inherits the DataContext automatically to enable this support.  In our implementation we will have a Text property to indicate the watermark, and an attached property which we will place onto the TextBox so it can be styled when the watermark is being used.

public static readonly DependencyProperty TextProperty =
   DependencyProperty.Register("Text", typeof (string), typeof (WatermarkTextBehavior),
                      new FrameworkPropertyMetadata(string.Empty));

Next we can hook it up in Blend through the Asset panel - all known assets are shown here (either registered, in the Blend directory, or project references).  Drag our WatermarkTextBehavior onto any TextBox and set the Text property and it will generate the following XAML:

<TextBox>
   <TextBox.Style>
      <Style TargetType="TextBox" BasedOn="{StaticResource {x:Type TextBox}}">
         <Style.Triggers>
            <Trigger Property="julmar:WatermarkTextBehavior.IsWatermarked" Value="True">
               <Setter Property="Foreground" Value="Gray" /> 
               <Setter Property="FontStyle" Value="Italic" />
            </Trigger>
         </Style.Triggers>
      </Style>
   </TextBox.Style>
   <i:Interaction.Behaviors>
      <julmar:WatermarkTextBehavior Text="Enter a name here" />
   </i:Interaction.Behaviors>
</TextBox>

Here is the complete source code to the behavior:

using System;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Interactivity;

namespace JulMar.Windows.Interactivity
{
    /// <summary>
    /// This behavior associates a watermark onto a TextBox indicating what the user should
    /// provide as input.
    /// </summary>
    public class WatermarkTextBehavior : Behavior<TextBox>
    {
        /// <summary>
        /// The watermark text
        /// </summary>
        public static readonly DependencyProperty TextProperty =
            DependencyProperty.Register("Text", typeof (string), typeof (WatermarkTextBehavior),
                                        new FrameworkPropertyMetadata(string.Empty));

        static readonly DependencyPropertyKey IsWatermarkedPropertyKey =
            DependencyProperty.RegisterAttachedReadOnly("IsWatermarked", typeof(bool), typeof(WatermarkTextBehavior), 
                                        new FrameworkPropertyMetadata(false));

        /// <summary>
        /// This readonly property is applied to the TextBox and indicates whether the watermark
        /// is currently being displayed.  It allows a style to change the visual appearanve of the
        /// TextBox.
        /// </summary>
        public static readonly DependencyProperty IsWatermarkedProperty = IsWatermarkedPropertyKey.DependencyProperty;

        /// <summary>
        /// Retrieves the current watermarked state of the TextBox.
        /// </summary>
        /// <param name="tb"></param>
        /// <returns></returns>
        public static bool GetIsWatermarked(TextBox tb)
        {
            return (bool) tb.GetValue(IsWatermarkedProperty);
        }

        /// <summary>
        /// Retrieves the current watermarked state of the TextBox.
        /// </summary>
        public bool IsWatermarked
        {
            get { return GetIsWatermarked(AssociatedObject);  }    
            private set { AssociatedObject.SetValue(IsWatermarkedPropertyKey, value);}
        }

        /// <summary>
        /// The watermark text
        /// </summary>
        public string Text
        {
            get { return (string) base.GetValue(TextProperty); }
            set { base.SetValue(TextProperty, value); }
        }

        /// <summary>
        /// Called after the behavior is attached to an AssociatedObject.
        /// </summary>
        /// <remarks>
        /// Override this to hook up functionality to the AssociatedObject.
        /// </remarks>
        protected override void OnAttached()
        {
            base.OnAttached();
            AssociatedObject.GotFocus += OnGotFocus;
            AssociatedObject.LostFocus += OnLostFocus;

            OnLostFocus(null, null);
        }

        /// <summary>
        /// Called when the behavior is being detached from its AssociatedObject, but before it has actually occurred.
        /// </summary>
        /// <remarks>
        /// Override this to unhook functionality from the AssociatedObject.
        /// </remarks>
        protected override void OnDetaching()
        {
            base.OnDetaching();
            AssociatedObject.GotFocus -= OnGotFocus;
            AssociatedObject.LostFocus -= OnLostFocus;
        }

        /// <summary>
        /// This method is called when the textbox gains focus.  It removes the watermark.
        /// </summary>
        /// <param name="sender"></param>
        /// <param name="e"></param>
        private void OnGotFocus(object sender, RoutedEventArgs e)
        {
            if (string.Compare(AssociatedObject.Text, this.Text, StringComparison.OrdinalIgnoreCase) == 0)
            {
                AssociatedObject.Text = string.Empty;
                IsWatermarked = false;
            }
        }

        /// <summary>
        /// This method is called when focus is lost from the TextBox.  It puts the watermark
        /// into place if no text is in the textbox.
        /// </summary>
        /// <param name="sender"></param>
        /// <param name="e"></param>
        private void OnLostFocus(object sender, RoutedEventArgs e)
        {
            if (string.IsNullOrEmpty(AssociatedObject.Text))
            {
                AssociatedObject.Text = this.Text;
                IsWatermarked = true;
            }
        }
    }
}

A project I've been working on for the last two months is finally online in beta form - check out

http://rcat.codeplex.com/

It's essentially a biological alignment viewer for RNA sequences.  Here's a couple of screen shots:

Alignment Viewer

2D Structure Viewer

2D Circle relationship Viewer

You can download the source code from the above link to play with it - it's a MVVM implementation and has quite a bit of interesting optimizations in it for performance purposes, including a read-only data virtualization for large sequence manipulation.  The next release will include a full read/write implementation so watch the project if you are interested!

In the previous post, I wrote about using the MVVM pattern with Context Menus, but you can use it with top-level menus too -- for example, perhaps I'd like to manage a set of options through a set of checkboxes.  First, let's start with my list of options - for simplicity, we'll just make it an enumeration:

public enum Test
{
   A,
   B,
   C,
   D,
   E,
   F
}

Next, let's define a ViewModel to wrap this - each entry should support a single value and a boolean binding to determine whether it is checked:

Finally, in the XAML itself we want to databind to the collection of CheckValues, supplying the appropriate support for each MenuItem to bind the menu checks to the collection:

That gives us our nice "checkable" menu - when the user clicks a checkmark, it sets the appropriate boolean in the code behind which could trigger logic, set values, etc.

But wait!  Often with checkboxes you want mutual exclusive choices - like the RadioButton groups.  This was a feature of Windows Forms which unfortunately did not make it into WPF, but we can make it work that way.  We could use the above logic and have the selection of a specific CheckValue unselect any others, or we could take advantage of RadioButtons to do this -- unfortunately I've not found a way that doesn't invoice a little code behind so it's not quite as clean as I'd like it to be, but it is possible.

First, let's define an exclusive ViewModel object, here we will track the "current" selection:

Next, we populate it into a bindable collection just as before and then we create some slightly more complex XAML for our menu items.  The trick here is to put a RadioButton into the menu item and associate it with a group.  I have to give a shout out to Dr. WPF from the wpf-disciples list some kudos here - he posted this trick on the MSDN forums (http://social.msdn.microsoft.com/Forums/en-US/wpf/thread/76c14163-9462-44d6-b0eb-6f22a006b423).  It turns out the MenuItem.Icon is positioned just where the normal check mark would be so if we place a styled RadioButton as the MenuItem.Icon we can make it look just like the checkmark:

Here, we've placed the RadioButton into our resources - but marked it as non-shareable.  The issue is that Styles always share property setters - and if you tried to do this:

<Style TargetType="MenuItem">
   <Setter Property="Icon">
     <Setter.Value>
       <RadioButton ... />
     </Setter.Value>
   </Setter>

You will get a very strange error message: "Cannot assigned type 'RadioButton' to type 'object'".  Which makes absolutely no sense until you realize the XAML parser is trying to assign the same RadioButton to every MenuItem.Icon.  The non-shareable resource fixes that issue.  The last step is to set the check -- this is done through the EventSetter in the above template.  It's wired to the little bit of code behind:

This then sets the IsChecked property which will, in turn, select that item.  Now you can look at ExclusiveCheckValue.SelectedValue to get the current item.  This isn't the most elegant solution, nor is it the only solution but it's an interesting one to think on.  If I were truly building this into a production application, I'd probably look at controlling the selection in the ModelView (i.e. enumerate through my other choices and deliberately turn them off).  But this does illustrate how powerful WPF is!

Here's the example project with both styles.

One question I've fielded a couple of times is how to manage menus, primarily context menus, with the MVVM pattern.  It turns out to be pretty easy once you know the "trick".  The key thing to keep in mind is that menus are just ItemsControls - they support data templating and binding like any other ItemsControl.  However, the part where people get lost is in hooking up the commands.  Here's the trick:

Step 1: Define some code behind construct to manage each menu item in a hiearchial fashion.  Here's one I've used:

public class MenuItem
{
   public string Text { get; set; }
   public List<MenuItem> Children { get; private set; }
   public ICommand Command { get; set; }
  
   public MenuItem(string item)
   {
       Text = item;
       Children = new List<MenuItem>();
   }
}

There's been a lot of talk about the Model-View-ViewModel pattern recently and it's usage around the WPF and Silverlight technology stack.  When teaching WPF, I always introduce students to MVVM as part of the Essential WPF class, it's an incredibly useful pattern that really separates the UI from the code behind behavior.  One of the things I give the students is a library to do MVVM - I also use it in my consulting work.  With all the focus on it lately, I figured maybe it's time to release it to the public.

A bit of history -- the library is really just a place where I dump all kinds of useful utility classes, helpers, wrappers, etc. that I tend to use a lot.  I started it about 3 years ago and it wasn't originally intended to be just an MVVM implementation so you'll find it's got all kinds of stuff in it, not all of which is MVVM specific.  It's evolution owes a lot to various blog posts, WPF Disciples, and other WPF leaders; I certainly didn't invent anything radically new but borrowed heavily from all kinds of places as I built various classes I needed for my own work.  These classes tended to evolve with new functionality (either due to necessity, or because a good idea occurred to me or someone else). For example, there was a recent thread on the Mediator pattern (initiated by Marlon Grech and added on by Josh Smith, Laurent Bugnion and others); I already had a message mediator in place but the idea of using an attribute to hook it up was a great one that I adopted into my library just because I like the idea.  The Delegating command pattern is one you see in a lot of places - including the Prism implementation.  The event routing attached behavior was made possible by a couple of blog posts by Mike Hilberg and John Gossman. So, be aware that as you use this code, it owes a lot to a variety of people.  That said, any bugs or issues are completely mine and I take full credit for them.

So, what all is here?  Well, quite a bit.  As I said, this is a collection of helpers I've built and reused over the years doing WPF consulting and instruction.  When MVVM came to my notice I worked on trying to completely separate the XAML side so I'll focus on those classes here. 

The basic idea is to derive your ViewModel classes from one of three base classes depending on what you need:

JulMar.Windows.Mvvm.ViewModel - supports basic INotifyPropertyChanged and Close/Activate eventing to the view.
JulMar.Windows.Mvvm.ValidatingViewModel - supports everything above, adds Validation through IDataErrorInfo support
JulMar.Windows.Mvvm.EditingViewModel - supports basic + validation + IEditableObject

Next, in each view (XAML) you set the DataContext property to your view model, the library has a MarkupExtension to do the work for you -

<Window x:Class="TestMvvm.MainWindow"
   xmlns:julmar="http://www.julmar.com/wpfhelpers"  xmlns:me="clr-namespace:TestMvvm"
   DataContext="{julmar:ViewModelCreator ViewModelType={x:Type me:WinViewModel}}">

This creates the view and also wires up support for closing the view and activating the view through the ViewModel class (using the RaiseCloseRequest and RaiseActivateRequest methods).

Everything is driven off ICommand - you can bind commands to the lifetime of the view (so you can detect activation, deactivation, loading, closing) through the LifetimeEvents attached behavior:

<Window x:Class="TestMvvm.MainWindow"
   julmar:LifetimeEvent.Activated="{Binding ActivatedCommand}"
   julmar:LifetimeEvent.Close="{Binding CloseCommand}"
   julmar:LifetimeEvent.Loaded="{Binding LoadedCommand}"
   julmar:LifetimeEvent.Deactivated="{Binding DeactivatedCommand}" >

These execute the bound command in the ViewModel when those events occur in the view.  If you need other events styles you can use the EventCommander attached behavior which allows any arbitrary event to be wired to a command.  This can be placed on any UIElement:

<julmar:EventCommander.Mappings>
   <julmar:CommandEvent Command="{Binding MouseEnterCommand}" Event="MouseEnter" />
   <julmar:CommandEvent Command="{Binding MouseLeaveCommand}" Event="MouseLeave" />
julmar:EventCommander.Mappings>

One annoying thing about ObservableCollection<T> is that it doesn't support modifications from background threads.  That is to say, the CollectionChanged notification doesn't marshal to the proper thread when it is raised and it causes the exception "This type of CollectionView does not support changes to its SourceCollection from a thread different from the Dispatcher thread". 

I ran into this problem a while back and searched out to see if someone else had solved it. I found a solution from Tamir Khason (a fellow WPF disciple), he wrote a thread-safe version (http://blogs.microsoft.co.il/blogs/tamir/archive/2007/04/22/Thread-safe-observable-collection.aspx), but I didn't want to add the locking into the collection itself (I want to manage it at a higher level myself).  Really, all I want is to do the notification on the proper (Dispatcher) thread. 

It turns out to be pretty easy, here's my solution:

public class MTObservableCollection<T> : ObservableCollection<T>
{
   public override event NotifyCollectionChangedEventHandler CollectionChanged;
   protected override void OnCollectionChanged(NotifyCollectionChangedEventArgs e)
   {
      var eh = CollectionChanged;
      if (eh != null)
      {
         Dispatcher dispatcher = (from NotifyCollectionChangedEventHandler nh in eh.GetInvocationList()
                 let dpo = nh.Target as DispatcherObject
                 where dpo != null
                 select dpo.Dispatcher).FirstOrDefault();

        if (dispatcher != null && dispatcher.CheckAccess() == false)
        {
           dispatcher.Invoke(DispatcherPriority.DataBind, (Action)(() => OnCollectionChanged(e)));
        }
        else
        {
           foreach (NotifyCollectionChangedEventHandler nh in eh.GetInvocationList())
              nh.Invoke(this, e);
        }
     }
  }
}

A couple of weeks ago, Jason Whittington (a fellow instructor at Developmentor) and I were doing a talk on asynchronous programming and we started with a very simple example of the APM -- using two loops to create and then consume the IAsyncResult work:

static void TwoLoopMain(string[] args)
{
   Queue<IAsyncResult> ars = new Queue<IAsyncResult>();
   Func<int,int,int> mathProc = Multiply;

   for (int i = 1; i <= 20; i++)
   {
      for (int j = 1; j <= 20; j++)
         ars.Enqueue(mathProc.BeginInvoke(i, j, null, null));
   }
   for (int i = 1; i <= 20; i++)
   {
      for (int j = 1; j <= 20; j++)
      {
         int result = mathProc.EndInvoke(ars.Dequeue());
         Console.SetCursorPosition(i * 3, j);
         Console.Write(result);
     }
  }
}

We had already presented a talk on LINQ earlier in the week and so I thought we might be able to do the above in a single expression with LINQ - kind of a challenge .. here's what we came up with:

static void LinqTest()
{
   Func<int,int,int> mathProc = Multiply;

   (from i in Enumerable.Range(1, 20)
    from j in Enumerable.Range(1, 20)
    select new { i, j, ar = mathProc.BeginInvoke(i, j, null, null) })
      .ToList()
      .ForEach(e => {
        int result = mathProc.EndInvoke(e.ar);
        Console.SetCursorPosition(e.i * 3, e.j);
        Console.Write(result);
     });
}

It's not easily readable (and so I wouldn't promote this for production code), but it's way cool and an example of how LINQ (and functional programming in general) is really changing the way programmers think about code.. just freaking cool..

• Scenic Ribbon (native Win32 ribbon) in Windows Forms
•  Native WM_TOUCH and WM_GESTURE messages
•  Sensor API
•  Shell APIs (jump lists, thumbnail buttons, libraries)

I've been playing with the Silverlight toolkit (released at PDC) this week and ran across a pretty nasty edge case related to HeaderedContentControl and the implicit style manager.  If you create something like this, where the Header is set to a Visual of some kind:

<UserControl x:Class="SilverlightPrototype.Page"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:sys="clr-namespace:System;assembly=mscorlib"
    xmlns:Controls="clr-namespace:Microsoft.Windows.Controls;assembly=Microsoft.Windows.Controls">

<StackPanel x:Name="LayoutRoot" Background="White">
   <Button Click="Button_Click" Content="Change Style" />
   <Controls:HeaderedContentControl>
      <Controls:HeaderedContentControl.Header>
         <TextBlock Text="Header" Foreground="DarkBlue" FontWeight="Bold" />
      </Controls:HeaderedContentControl.Header>
      <TextBlock Text="Body" />
   </Controls:HeaderedContentControl>
</StackPanel>

</UserControl>

And then you change the style of the headered control when the button is clicked:

Where the style is just a simple ContentPresenter or ContentControl for the header and the body:

Silverlight will crash deep in the DependencyProperty.SetValue code with an ArgumentException indicating that the TextBlock for the header is invalid.  The issue appears to be that the TextBlock defined as the header content is already part of the visual tree and therefore cannot be bound to the new control template.  Content works fine so there is some other path being taken for that property.

The workaround is pretty easy, just use a non-visual in the header and then supply a DataTemplate to give it the appropriate visual tree.  Silverlight will re-create the visual tree each time from the data template so we don't have the reuse issue:

If you need more than a string, then just define an object and assign that instead - for example:

One thing that's kind of cool in WPF is that you can use brushes to fill almost anything and that there are some really cool brushes in the toolkit.  It always blows people away when you show them a piece of text filled with a live video complements of a Visual Brush.

But, unfortunately text doesn't have a stroke property - only a fill so you can't add an edge to it.  You can layer another piece of text under it, but often it doesn't quite match up size-wise when you do this.  The solution is to convert the text to a Path which has both a fill and stroke and it turns out it's pretty easy to do.

If you just have one piece of text you are better off using Blend's "Convert to Path" option -- it will do the one-time conversion for you and you can just insert the shape into your UI.  If you have more than one element though it can be tedious, and it doesn't work at all for dynamic pieces of text - that's where this TextPath class comes in handy.   With it you can create text like this:

Notice how the text is outlined in a different color -- any brush could be used so you could do wacky things like have the "WPF" part be ringed in fire (using the Dreamscene fire video for example). 

The class is dead simple to use, it's a Shape class so you can simply insert it right into your XAML and set the font properties and text:

<StackPanel Orientation="Horizontal" TextElement.FontWeight="Bold" TextElement.FontSize="72pt">
        <me:TextPath FontFamily="Consolas,Courier New" Margin="5" Text="WPF"
                       StrokeThickness="3" Fill="Gold" Stroke="Red" /> 
        <me:TextPath FontFamily="Balloon" Margin="5" Text="Rocks" StrokeThickness="3" Stroke="Black">
           <me:TextPath.Fill>
              <ImageBrush ImageSource="rocks.jpg" />
            </me:TextPath.Fill>
        </me:TextPath>
</StackPanel>

Notice it uses the same font dependency properties as all other text-based framework elements - that allows us to inherit the property values which is useful. 

Here's the sample project which full source code:  OutlineTextTest.zip (1.54 MB)

We've seen how to programatically control focus and that's all great stuff, but one thing I like to do with WPF is see how much of the repetitive or UI-specific code I can move into the XAML and keep out of the code behind.  We can use the FocusManager.FocusedElement property to shift focus in XAML but it only works when the element exists in the main XAML file.  If you use UserControls it turns out that the approach doesn't work because that element is loaded separately and not available when the initial focus is being determined.

In my specific case, I have a wizard-style application which utilizes a TabControl to move between the pages.  The first page looks like this:

The XAML layout for window1.xaml looks something like this:

<TabControl x:Name="Pages" SelectedIndex="0">
   <FocusTest:Page1 />
   <FocusTest:Page2 />
   <FocusTest:FinalPage />
</TabControl>

What I want is to have focus immediately positioned within the first text box but it turns out that you can't get WPF to do this directly from XAML - because the TextBox isn't a direct descendent of Window - it's part of the Page1 user control.  You can try putting the focus shift into the user control but it turns out that it won't work there either - it's got to be assigned to the focus scope which is the window.

So it might seem we are stuck with adding code behind logic (blech!) but all is not lost!  When I hit situations like this, I try to think about how to solve the problem generically so I can reuse my solution.  In this case, I decided to build a MarkupExtension to locate the first focusable element descendent.

If you are not familiar with markup extensions, they are a corner piece in the XAML extensibility story.  They allow for dynamic property assignment - where the value is determined at runtime vs. XAML compile time.  That's exactly what I need here - I want to find that TextBox at runtime and shift focus to it - just like I would have done in the code behind.

Creating a markup extension is trivial - you just extend the MarkupExtension base class and implement the ProvideValue method.  In this case, when provide value is called, I have to do several steps:

1. If the element we are bound to is not loaded yet, we need to wait for it.  We won't be able to find the child in the visual tree if the parent isn't yet loaded.
2. Once it is loaded, search the children and find the first control we can give focus to.  That means, the control is visible, focusable and enabled.
3. Assign logical focus to the new control in the closest focus scope parent, or just return the value if the property being assigned to is not FocusManager.FocusedElement.

I decided to try to make a generic markup extension that could be used outside my scenario so I added a little bit of code to see if we are assigning to FocusManager.FocusedElement and act differently in that specific case - otherwise the extension just returns the value.

With this new extension, I can now add a single line of code to each user control:

Now, when I run the application, focus is always assigned to the first control it can be assigned to.  It turns out that I can go one step better and always assign focus when the page becomes visible in my wizard - remember we have to wait for the control to finish loading to find the element.. this is done by hooking the FrameworkElement.Loaded event.  This event is raised each time the TabControl shifts to a new tab - so if we never unhook our handler, our focus management code is called each time the tab page becomes visible.  This might not be the required behavior so I added a simple property to the markup extension called OneTime to control that behavior.

There's a bit too much code to blog here, but if you want to try this out yourself, here's the test project.. feel free to use this however you like.  FocusTest.zip (17.88 KB)

Update: Andrew Smith pointed out that the code would assign focus to a focus scope if it ran across one - which could happen if you have a toolbar or menu present in the UI.  I didn't in the sample (or in my production app) but I could certainly see that being a common reality.  I changed the above code to deliberately skip focus scopes and their children and keep going down the tree until it finds the first child.  Thanks Andrew!

In the last post, I wrote about how focus is generally managed in WPF - we have focus scopes to track a single element within that scope for logical focus, and then one of those elements is given physical, or keyboard focus.

Now, let's talk a little about how you can influence that programatically.  First, you can always determine which element has logical focus in your application through the FocusManager.GetFocusedElement method -- pass it the window in question and it will return which element has logical focus in that window.  Remember that logical focus != keyboard focus at all times -- toolbars and menus track their own focus so if you are currently interacting with a menu then the menu has physical focus.  But in general, the following code will tell you which element WPF thinks has focus in the window:

IInputElement focusedElement = FocusManager.GetFocusedElement(thisWindow);

To determine whether this element has keyboard focus, we can check the IsKeyboardFocused property - if it's set to true, then that element currently has the keyboard focus (as well as being the logical focus for that focus scope).

Keyboard focus is most often set through runtime activity - the user clicks on an element, or uses the TAB key to move around the UI.  You can also set it programatically a couple of ways.  First, there is a Keyboard class in WPF which exposes several methods and properties.  There is a Keyboard.FocusedElement read-only property which returns the current keyboard focused element, and there is a Keyboard.Focus method which attempts to change keyboard focus.  It returns the element that now has focus - so you can check to see if your request was fulfilled or ignored.  So, for example, you can change focus during your application initialization:

Notice that we uses the Loaded event - this is because no focus requests will be accepted prior to the element being initialized and loaded.  That's the first place in the application where you can make focus changes.

When would setting focus fail?  Well, it can fail for a lot of reasons, but the most common are:

1. The element has Focusable = false
2. The element has Enabled = false
3. The element has IsVisible = false
4. The element has not been loaded yet
5. The currently focused element will not release focus.

That final one is important, changing focus involves potentially taking it away from an existing element - they receive a PreviewLostKeyboardFocus and LostKeyboardFocus event.  If they handle the preview event, focus will not change.

You can also manipulate focus through programatic keyboard navigation - simulating the user pressing TAB to cycle through the focusable elements.  This is controlled through the KeyboardNavigation class which is used when the user presses a key that changes focus (TAB, SHIFT+TAB, Up, Down, etc.).

Controls can set a TabIndex property assignment which determines the tabbing order.  The default is to tab through them in order of declaration.  You can also use the KeyboardNavigation.TabIndex attached property which works for any element - not just controls.

To control navigation, the KeyboardNavigation class has an attached property TabNavigation allowing you to change how navigation occurs within a container.  You can set it to:

1. Continue - each focusable element receives focus and the container is exited when the edge is reached.
2. Cycle - focus does not leave the container but wraps around the edges
3. Once - the container itself is treated as a single focusable element where only the first child receives focus
4. Local - uses TabIndex locally within the container - independant of any outside elements.
5. Contained - focus statys in the container but does not wrap (stays at edges when top/bottom are reached)
6. None - no keyboard navigation allowed in the container

The default is Continue, but you can set the attached property on any element to change it for that element and any children. To see this in action, paste the following into your XAML editor of choice and change the ComboBox while tabbing through the TextBlock elements.

You can have the system ignore specific elements (but still allow them to have focus) by setting the KeyboardNavigation.IsTabStop="false" attached property.  This will cause keyboard navigation to "jump" over the control as if it were not present.

Three methods are exposed by UIElement and FrameworkElement to programatically shift focus: Focus, MoveFocus and PredictFocus.

To force focus to a specific element, you can call Focus on it.  For example, above we set the keyboard focus by calling Keyboard.Focus(), but the same effect can be achieved like this:

This method attempts to set focus using Keyboard.Focus().  If that fails, but the element is Focusable and enabled, it finds the focus scope for the element and sets logical focus there (so that keyboard focus will eventually end up on the control).

FrameworkElement.MoveFocus is used to change the keyboard focus in the application using the same algorithm as the TAB traversal.  You pass in the direction (specified through a TraversalRequest object) and the method returns true/false to indicate success.   Under the covers it actually uses the KeyboardNavigation class, but it's an easy way to push focus around the window:

PredictFocus works the same way, but instead of actually shifting focus, it returns what would be the focused item if you were to execute MoveFocus.

So, up to this point, we've seen a lot of code to change focus.  However, the most common request is to set initial focus to a specific control - remember that WPF doesn't do that by default.  You can do it in code, just like the above example where we use the Loaded event.  Or, it turns out you can do it in XAML too.  The key to remember is that the FocusedElement of the main focus scope (the Window) is the one that will get initial focus.  That is (by default) null, but you can set it in XAML using the attached property syntax.  Using the above XAML example, we can supply a name for one of the TextBox controls and then a little data binding magic to set that onto the Window: