Paul Stovell

Magellan Installer

2009-11-15T15:05:07Z

Magellan now comes with a Visual Studio Project Template that you can use to get started with quickly. You will need Visual Studio 2008.

Magellan-Setup.msi

Setup

During the installer you will be prompted to install the Visual Studio project templates:

If Visual Studio is already running, your will be prompted to close it at this time. The project templates will be installed and Visual Studio updated.

Once the installer finishes, your installation directory will contain the Magellan assemblies (in the Public directory), plus supporting files for the project template:

Creating Projects

In Visual Studio under the Windows node, you will now have the ability to create a Magellan project:

Before the project is created, you will get a chance to decide whether to create unit tests, and how to handle the Magellan references. Magellan is not installed into the GAC. You can either reference the assemblies directly from the installation directory, which will mean other developers also need to install the MSI, or you can have the project wizard copy the assemblies locally (the default option):

When the project wizard has finished, you will have a new Magellan project - it should compile and run first try and the generated test should pass.

You can also set up the same project manually without using the MSI. See the manual quickstart page for more information.

Back to: Magellan Home

Magellan and the MVVM Light Toolkit

2009-11-13T07:13:39Z

Back to: Magellan Home

The MVVM Light Toolkit is an MVVM framework by WPF MVP Laurent Bugnion, the author of Silverlight 2 Unleashed. It works well alongside Magellan and makes it easy to put behaviors behind views. The integration model with Magellan is quite similar to using the Microsoft MVVM toolkit.

One difference is that the MVVM Light Toolkit typically uses resources to refer to the ViewModel, limiting the amount of code behind that is required. Since Magellan controllers typically create the model, this does need to change.

As with using the Microsoft MVVM toolkit, we use the controller to create the ViewModel:

public class HomeController : Controller
{
    public ActionResult Main()
    {
        Model = new MainViewModel();
        return View();
    }
}

MVVM Light views typically use a locator for creating the view model - this is a problem because our controller above will be creating the VM, and Magellan is taking care of assigning it.

<Window x:Class="MvvmLight1.MvvmView1"
    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" 
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    mc:Ignorable="d"
    DataContext="{Binding Main, Source={StaticResource Locator}}"
    >

To keep Blend support, change the XAML to use d:DataContext instead of DataContext.

<Window x:Class="MvvmLight1.MvvmView1"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:ViewModel="clr-namespace:MvvmLight1.ViewModel" 
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" 
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    mc:Ignorable="d"
    d:DataContext="{x:Type ViewModel:MainViewModel}"
    >

Back to: Magellan Home

Magellan Controllers

2009-11-12T10:11:38Z

Back to: Magellan Home

As an MVC framework, controllers are the most prominent object in Magellan. At their simplest, controllers are implemented as classes, and actions are implemented as methods on the class. Actions on a controller must be public methods, and must return ActionResult objects. Here is an example:

public class CustomerController : Controller
{
    public ActionResult Index()
    {
        Model = Customers.GetAll();
        return View();
    }

    public ActionResult Show(int customerId) 
    {
        Model = Customers.Get(customerId);
        return View();
    }
}

This page describes how controllers are executed.

Controller Factories

Navigation begins at the Navigator, either by using a command, behavior or calling it explicitly. The Navigator processes the request by resolving a controller from the controller factory, executing the request, and releasing the controller back to the factory:

public void Navigate(NavigationRequest request)
{
    Guard.ArgumentNotNull(request, "request");

    var controllerFactory = ControllerBuilder.Current.GetControllerFactory();
    var controller = controllerFactory.CreateController(request, request.Controller);
    try
    {
        controller.Execute(request);
    }
    finally
    {
        controllerFactory.ReleaseController(controller);
    }
}

The controller factory implements the IControllerFactory interface, and provides two methods to control the management of controllers:

public interface IControllerFactory
{
    IController CreateController(NavigationRequest request, string controllerName);
    void ReleaseController(IController controller);
}

The controller factory is set via the ControllerBuilder.Current.SetControllerFactory method. See the topic on using an IOC container for an example on creating your own controller factory.

Controllers

The controllers returned by the controller factory must implement the IController interface, which is quite simple:

public interface IController
{
    void Execute(NavigationRequest request);
}

The NavigationRequest passed to the controller contains information about the controller name, action name, and any parameters for the request. It is up to the controller to decide how to handle the request given this information. If the class/method convention used by Magellan isn't enough, your controller can use different mechanisms to prosecute the request. Magellan's navigator, behaviors, and commands can still be used.

Controllers will usually derive from the Controller base class. When this controller executes a request, it will work with an action invoker to resolve the action, call any action filters, execute the action, and evaluate the result.

The Execute method on the Controller base class is quite simple:

public void Execute(NavigationRequest request)
{
    Request = request;
    ActionInvoker.ExecuteAction(ControllerContext, request.Action, ModelBinders);
}

To make writing controllers easy, a number of helper methods exist for creating the action results, such as View(), Cancel() and Redirect(). You can read more about them in the action results section.

Action Invoker

The action invoker is used by the controller to handle the details of executing the action. This allows you to continue to derive from the Controller class while executing actions in a very different way. By default, the controller's ActionInvoker property is set to the DefaultActionInvoker.

The default action invoker uses reflection to map the requests Action property to a method on the controller. It then performs the following steps:

Executes all pre-action filters
Executes the action
Executes all post-action filters
Executes the action result

Action filters provide a way for you to implement cross-cutting concerns on controllers, such as authorization, logging, state management, and other examples.

When the action has been executed, it will return an Action Result. This is an important point - controllers do not show views directly, they simply return an object which is responsible for resolving and showing the view. This allows you handle the navigation request in a very different way without altering controllers.

Model Binders

One of the tasks the action invoker takes care of is mapping parameters from the current NavigationRequest to arguments passed to the action method on the controller. Rather than putting this logic in the action invoker, it instead calls through to objects known as Model Binders.

The ModelBinders.Binders static property is a registry of active model binders, associated with a type. By default there is only one binder - a DefaultModelBinder which uses type descriptors and casting to perform the conversion. If you wish to customize how request parameters are mapped to action method parameters, you can do so through implementing the IModelBinder interface and registering it with the ModelBinders.Binders collection.

See also:

Back to: Magellan Home

Magellan and the Microsoft MVVM Toolkit

2009-11-11T06:38:49Z

Back to: Magellan Home

Magellan's MVC framework is designed to handle navigation between views. However, the views themselves, and how they are implemented, is outside of Magellan's concern. Views can be simple XAML pages, or they can be driven by an MVVM or MVP pattern, or any other way you might like.

Microsoft provide a Visual Studio project template known as the MVVM Toolkit, which makes it easy to get started using the MVVM pattern.

To use Magellan with the MVVM toolkit, you can set up a new MVVM project using the MVVM project template. Then configure it the same way as described in the Magellan quickstart.

By default with the MVVM toolkit, you typically create the ViewModel and View and assign them yourself, as shown in the project template:

Views.MainView view = new Views.MainView();
view.DataContext = new ViewModels.MainViewModel();
view.Show();

Instead, with Magellan, you can assign the controller's Model property to you ViewModel:

public class HomeController : Controller
{
    public ActionResult Main()
    {
        Model = new MainViewModel();
        return View();
    }
}

The view engines will create the page or Window, and set the DataContext to the Model for you. It will then navigate to the page or show the Window.

Your ViewModels can make use of commands, event managers, data binding, and all the other common MVVM patterns. MVVM would typically handle:

Local interaction with the view
Validation
Control state, such as whether a button should be enabled based on data

While Magellan would be used for:

Navigating to another page or window

A good way to think about this is to think in terms of the web. On the web, JavaScript is typically the "view model" - it handles the logic for a particular page. The server processes requests for many pages and navigation between pages - that's the job of Magellan.

There is also a NavigateCommand that can be used in ViewModels, instead of the need to use a DelegateCommand/RelayCommand for common navigation events.

Back to: Magellan Home

Magellan and Composite WPF

2009-11-10T13:07:43Z

Back to: Magellan Home

Magellan was designed to work with Composite WPF from day one. Composite WPF provides support for multiple modules, loosely coupled pub/sub eventing, and regions for sub-dividing zones in the UI. However, Composite WPF does not enforce any particular UI pattern - MVVM, MVP and MVC could all work.

Magellan and Composite WPF can work well together to create a composite navigation-oriented application using the MVC pattern. Here are some examples:

Composite WPF modules could contain views and controllers
Composite WPF events could be used for navigation - i.e., a Navigate event that could be raised by different modules and services
Instead of pages, Magellan view results could return UserControls that are added to regions

Region Support

For region support, Magellan.Composite.dll contains some extensions that can be used. A controller may look like this:

public class ShellController: Controller 
{
    public ActionResult Explorer()
    {
        return View().InRegion("LeftRegion");
    }
}

On application startup, the view can be navigated to via:

Navigator.Primary.Navigate("Shell", "Explorer");

Lastly, an additional Region View Engine needs to be registered. As discussed in the IOC topic, you can also use a custom view activator to control how views are instantiated, if you want to use IOC. In this case we'll use the Microsoft common ServiceLocator:

ViewEngines.Engines.Clear();
ViewEngines.Engines.Add(new PageViewEngine(new ServiceLocatorViewActivator()));
ViewEngines.Engines.Add(new WindowViewEngine(new ServiceLocatorViewActivator()));
ViewEngines.Engines.Add(new RegionViewEngine(new ServiceLocatorViewActivator()));

When the InRegion extension method is used, and the view class derives from UIElement, the region view engine will use the service locator to resolve the default RegionManager, and then add the view to the region.

Controller Factory

There is also a new controller factory that can be used with the Common Service Locator. It will automatically back onto ServiceLocator.Current to resolve controllers, so you just have to register them in the container:

ControllerBuilder.Current.SetControllerFactory(new ServiceLocatorControllerFactory());

See also:

Back to: Magellan Home

Magellan and IOC/DI Containers

2009-11-09T11:37:38Z

Back to: Magellan Home

Magellan was designed to work without an Inversion of Control or Dependency Injection container, to keep it simple and accessible. However, as applications become more complicated, modern WPF applications can benefit immensely from IOC containers.

Magellan's extensibility points make using a container easy. Magellan resolves and instantiates two main types of objects - controllers and views. The out of the box implementation uses conventions, but they can be overridden.

To take control of resolving controllers, implement the IControllerFactory interface. Here is an example using Ninject:

public class NinjectControllerFactory : IControllerFactory
{
    private readonly IKernel _container;

    public NinjectControllerFactory(IKernel container)
    {
        _container = container;
    }

    public IController CreateController(NavigationRequest request, string controllerName)
    {
        return _container.Get<IController>(controllerName);
    }

    public void ReleaseController(IController controller)
    {
    }
}

Then assign it as the default controller factory:

var container = new StandardKernel();
container.Bind<IController>().To<HomeController>().Named("Home");
container.Bind<IController>().To<SettingsController>().Named("Settings");
ControllerBuilder.Current.SetControllerFactory(new NinjectControllerFactory(container));

When a navigation request is processed, the Navigator will consult the ControllerBuilder.Current for the controller factory. It will use this to ask the factory for a controller, then execute the controller. The ReleaseController method will be called as soon as the navigation request has completed.

Typically, each navigation will create a new controller - if you want to use the same controller, you could have your controller factory recycle the objects, or make them singletons.

The second object that Magellan creates is views. This is done through the IViewActivator implementation. The default implementation looks for a public, parameterless constructor.

Again, let's use Ninject to control view instantiation.

public class NinjectViewActivator : IViewActivator
{
    private readonly IKernel _container;

    public NinjectViewActivator(IKernel container)
    {
        _container = container;
    }

    public object Instantiate(Type viewType)
    {
        return _container.Get(viewType);        
    }
}

We then need to tell the view engines that it is available. Since the view engines are automatically registered, we need to manually re-register them:

var activator = new NinjectViewActivator(container);
ViewEngines.Engines.Clear();
ViewEngines.Engines.Add(new PageViewEngine(activator));
ViewEngines.Engines.Add(new WindowViewEngine(activator));

If you are using Magellan with Composite WPF, you will also need to register the region view engine:

ViewEngines.Engines.Add(new RegionViewEngine(activator));

Back to: Magellan Home

Magellan Quickstart

2009-11-14T14:13:41Z

Back to: Magellan Home

This guide will walk you through getting started with Magellan. You will need a copy of Visual Studio 2008 with Service Pack 1.

Project Setup

Download the Magellan library. Unzip it to a known location.
Create a new WPF Application project using Visual Studio 2008.
Add references to Magellan.dll and System.Windows.Interactivity.dll from the ZIP file that you downloaded.
Create the following folder structure:

Create a model

In the Views/Home folder, add a class named AddModel. This will represent the view model of an addition action:

public class AddModel
{
    public int A { get; set; }
    public int B { get; set; }
    public int Result { get; set; }
}

Create a controller

Create a new class in the Controllers folder named HomeController. It will contain two actions - Index, which will be the input page, and Add, which will show the results:

using Magellan.Framework;

namespace MagellanHelloWorld.Controllers
{
    public class HomeController : Controller
    {
        public ActionResult Index()
        {
            return View();
        }

        public ActionResult Add(int a, int b)
        {
            Model = new AddModel
            {
                A = a,
                B = b,
                Result = a + b
            };
            return View();
        }
    }
}

Now wire up the controller in App.xaml.cs:

using System.Windows;
using Magellan.Framework;
using MagellanHelloWorld.Controllers;

namespace MagellanHelloWorld
{
    public partial class App : Application
    {
        protected override void OnStartup(StartupEventArgs e)
        {
            var controllerFactory = new ControllerFactory();
            controllerFactory.Register("Home", () => new HomeController());
            ControllerBuilder.Current.SetControllerFactory(controllerFactory);

            base.OnStartup(e);
        }
    }
}

Set up the shell

In Window1.xaml, add a Frame element to the content:

<Window 
    x:Class="MagellanHelloWorld.Window1"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    Title="Window1" Height="300" Width="300"
    >
    <Grid>
        <Frame Name="mainFrame" />
    </Grid>
</Window>

In the Window1 constructor, navigate the mainFrame to the Index action on your controller.

using System.Windows;
using Magellan;

namespace MagellanHelloWorld
{
    public partial class Window1 : Window
    {
        public Window1()
        {
            InitializeComponent();

            Navigator.For(mainFrame).Navigate("Home", "Index");
        }
    }
}

Create the views

In the Views/Home folder, create two new Page files: Index.xaml and Add.xaml.

Index.xaml will be used to capture the inputs, and send them to the Add action on the controller. Notice how the Parameters are defined as part of the Navigation behavior:

<Page 
    x:Class="MagellanHelloWorld.Views.Home.Index"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
    xmlns:i="clr-namespace:System.Windows.Interactivity;assembly=System.Windows.Interactivity" 
    xmlns:magellan="http://xamlforge.com/magellan" 
    Title="Index"
    >
    <StackPanel>
        <TextBox Name="parameterA" />
        <TextBlock Text="+" />
        <TextBox Name="parameterB" />

        <Button Content="Calculate">
            <i:Interaction.Behaviors>
                <magellan:NavigateBehavior Controller="Home" Action="Add">
                    <magellan:NavigateBehavior.Parameters>
                        <magellan:Parameter ParameterName="a" Value="{Binding ElementName=parameterA, Path=Text}" />
                        <magellan:Parameter ParameterName="b" Value="{Binding ElementName=parameterB, Path=Text}" />
                    </magellan:NavigateBehavior.Parameters>
                </magellan:NavigateBehavior>
            </i:Interaction.Behaviors>
        </Button>
    </StackPanel>
</Page>

The Add.xaml will show the output of the calculation. Note how it assumes the use of DataContext in the bindings.

<Page 
    x:Class="MagellanHelloWorld.Views.Home.Add"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:i="clr-namespace:System.Windows.Interactivity;assembly=System.Windows.Interactivity" 
    xmlns:magellan="http://xamlforge.com/magellan" 
    Title="Add"
    >
    <StackPanel>
        <WrapPanel>
            <TextBlock Text="{Binding Path=A}" />
            <TextBlock Text="+" />
            <TextBlock Text="{Binding Path=B}" />
            <TextBlock Text="=" />
            <TextBlock Text="{Binding Path=Result}" />
        </WrapPanel>

        <Button Content="Try Again">
            <i:Interaction.Behaviors>
                <magellan:NavigateBehavior Controller="Home" Action="Index" />
            </i:Interaction.Behaviors>
        </Button>
    </StackPanel>
</Page>

The Magellan view engine will take care of setting the Page's DataContext to the Model from the controller.

Done

That's all there is to it - just hit F5 and admire the results of your handywork! At this point you should be able to enter the values, and they will appear on the next page. Wasn't that easy?

Magellan took care of:

Locating the controller
Invoking the actions
Mapping the strings from the text boxes to integer parameters on the action (using Model Binders)
Locating the view
Connecting the model with the view

Tests

Of course, it wouldn't be complete without a test. Here's what the unit test for our Add action might look like:

[Test]
public void AddTest()
{
    var controller = new HomeController();
    controller.Add(1, 4);
    var model = (AddModel)controller.Model;

    Assert.AreEqual(1, model.A);
    Assert.AreEqual(4, model.B);
    Assert.AreEqual(5, model.Result);
}

What next?

Back to: Magellan Home

Magellan Introduction

2009-11-15T12:41:30Z

Back to: Magellan Home

Magellan is a lightweight framework that makes it easy to build WPF navigation applications. It is inspired by the ASP.NET MVC framework. The main features are:

Model-View-Controller support
Action filters for cross-cutting concerns such as authorization and redirection
Blend behaviors to make navigation easy
Transitions between pages

Magellan was drawn from a number of samples I had put together early this year and some work done on a client project.

The source download includes an "iPhone" application for demonstrating the features.

We start with a simple project structure:

A controller implementation typically looks like this:

public class PhoneController : Controller
{
    public ActionResult Group(Group group)
    {
        var contacts = _contactRepository.GetContacts(group);

        Model = new GroupViewModel(group.Name, contacts);
        return View();
    }

Views are XAML Page objects, and can optionally have a model. Here's an example:

The idea is that upon navigation, a controller is created, the action is executed, and the view and view model are created. The view then becomes the focus of the frame. Put simply, the view and viewmodel are stateful, and the controller is stateless.

Navigation between views (with nice transitions) can be done either programatically:

Navigator.For(Frame).NavigateWithTransition("Home", "Main", "ZoomOut");

Or through Blend behaviors:

The framework supports the ASP.NET MVC concepts of Action Filters, Model Binders, View Engines and more - I'll cover them in a later post.

Back to: Magellan Home

Enforced Strings

2009-10-09T13:02:24Z

Enterprise applications typically deal with many categories of strings. Human names, reference codes, SKU identifiers, email addresses - the list is huge. There are subtle rules that apply to many of them:

Whitespace at the start and end of many strings should probably be ignored
Human names probably shouldn't contain newlines, tab characters, the percentage symbol, or 27 dashes in a row
For some strings, casing makes no difference when deciding equality, and sometimes it does

It's common to litter our code with these assumptions, which leads to inconsistency. Sometimes we assume that the UI will handle all of these issues, and the domain layer will simply use what it's given.

Recently I have started experimenting with creating custom strings to encapsulate a lot of these subtle things. On my blog, when you browse to a URL like /enforced-strings, instead of the page name being passed around as a string, it's passed as a PageName object. PageName supports implicit conversion operators, so it can be dealt with as a regular string too. Here is part of a unit test:

PageName expected = "hello-world";

// When cast to a PageName, each of these should be converted into the above
var logicallySameAsExpected = new string[] {
    "hello-world",
    "hello-worLD",
    " hello -world ",
    " hello$-world ",
    " hello $-world ",
    " hello-$-world ",
    " hello world ",
    " -   hello   world   - ",
    " -   HeLLo  WoRLD  - ",
    " -   HeLLo  %^@#@#*()[]WoRLD  - ",
    " -   HeLLo  %^@#@#*()[]WoRLD  - $%",
    "@# -   HeLLo  %^@#@#*()[]WoRLD  - $%"
};

foreach (var match in logicallySameAsExpected)
{
    var castMatch = (PageName) match;
    Assert.AreEqual(expected, castMatch);
}

The assumption I make with PageName is that while it may be instantiated with dirty input (a malformed URL, for example), I can probably infer what was meant. PageName is used throughout my domain model and even at the data access layer - in my case, I use a custom IUserType with NHibernate to treat strings from the database as page names.

To build your own enforced strings, here are the key things to consider doing:

Create a class to wrap a real string
Make it immutable, and ideally sealed
In the constructor, massage the input string
Override all of the equality operators, GetHashCode, etc., and implement IEquatable, and IComparable
Override ToString (obviously)
Add an implicit cast operator to automatically convert from your string to real strings and back

You can see an example of this in PaulPad - first I setup a base class with most of the overloads, then I inherit from that to setup the specific string type.

jQueryPad

2009-10-08T15:19:11Z

jQueryPad is a fast JavaScript and HTML editor. Just start it, enter the HTML you want to work with, bash in your jQuery code, and hit F5 to see the results. Say goodbye to ALT+TAB.

Download

jQueryPad is xcopy deployable. It's written in WPF and uses the Web Browser Control to embed Internet Explorer for testing the script. When you press F5, the HTML and JavaScript are combined into one file and rendered. The template also references jQuery, so the jQuery functions are available.

If you want to use a different version of jQuery or reference other files, just replace the files in the Templates directory.

Hope you find it useful - feature suggestions are welcome.

Sheldon

2009-10-07T12:16:53Z

Sheldon is a WPF command line control, and code to integrate it with IronPython. It's designed as a sample that demonstrates how a WPF application might be made scriptable:

This sample was created to pitch an idea to a client about enabling a macro system in their application. Users might be able to make use of functions like OpenAccount("ACME"), ExecuteJob("SalesForecast2009"), and so on. Using the Command Pattern, commands could be written to an Output window in the application while the user uses the UI - that could be used as a learning tool for learning the command line.

The demo application shows how object models can be shared between your application and scripting environment. In C#, I set up an AutomationContext, which is made available to IronPython:

public class AutomationContext
{
    public ApplicationDefinition Application { get; set; }
    public IScriptingContext ScriptingContext { get; set; }

    public void Exit()
    {
        Environment.Exit(0);
    }
}

Then in IronPython, I create a friendly "API" that users can consume:

def GetWindow(name):
    return automation_context.Application.MainWindow
def Clear():
    automation_context.ScriptingContext.Clear()
def Exit():
    automation_context.Exit()

The ScriptingContext is an object that manages the execution and rendering of scripts, which the command line control can hook into. Multiple controls can talk to a single scripting context - here's a custom shell (I simply overrode the style and control template of the Shell control):

You can download the code here:

ZIP: Sheldon.zip
SVN: /svn/Samples/Sheldon

Editable Collection Adapter for WPF

2009-10-02T07:15:06Z

The screenshot below is of a sample WPF application that deals with editing a collection of items:

A few features:

You can make a batch of changes to the screen and hit "Save".
If you deleted items, you can click "Show deleted items" to make them visible again, then click Undo to rollback the deletion
The list on the left is bound to the same collection as the list on the right - the changes aren't written to the source until you click Save
If you change an item, it highlights in bold
If you change an item, you can undo the changes via the Undo button
If you add items to the original collection, they will appear on screen (the Remote Update button)

The object representing an individual row is just a simple POCO object with INotifyPropertyChanged support - it has no HasChanges property or similar. Likewise, the collection is just an ObservableCollection<T>.

This is all implemented with a mix of BindableLINQ and the Editable Object Adapter.

Download

Note: This sample uses the Xceed WPF DataGrid control. If you have a license, you can use your license key when running the sample (just set it in App.xaml.cs). Alternatively, you can download a 45 day trial from the Xceed website.

DelayBinding: a custom WPF Binding

2009-10-02T01:58:18Z

When you use the Outlook 2007 search, Vista's start search, or the Search bar in Explorer, there's often a short delay between when you press a key, and when the search begins.

In WPF, we could simulate this through a series of event handlers, timers and code-behind directly on controls, but we usually want to be able to use this alongside WPF's data binding capabilities. To use WPF data binding in a delayed fashion, I created a simple markup extension which creates a binding and manages the timer delay between commits.

Here's how you can use it:

<TextBox Text="{z:DelayBinding Path=SearchText}" />

You can also set an explicit delay. By default, it uses 0.5 seconds, which felt consistent with Outlook, though I didn't spend that much time working out exactly how long Outlook waits. I did look to see if there was a SystemParameters class for something like "SearchDelay", but couldn't find one. Suggestions for a better default are welcome.

<TextBox Text="{z:DelayBinding Path=SearchText, Delay='00:00:01'}" />

Instead of creating a new type of Binding, I'm using the standard WPF Binding, but setting the UpdateSourceTrigger to Explicit. As the text changes, the timer is reset, and when it ticks the value is pushed to the source.

After the short delay:

First, the code to the markup extension (XML-doc comments removed):

[MarkupExtensionReturnType(typeof(object))]
public class DelayBindingExtension : MarkupExtension
{
    public DelayBindingExtension()
    {
        Delay = TimeSpan.FromSeconds(0.5);
    }

    public DelayBindingExtension(PropertyPath path) 
        : this()
    {
        Path = path;
    }

    public IValueConverter Converter { get; set; }
    public object ConverterParamter { get; set; }
    public string ElementName { get; set; }
    public RelativeSource RelativeSource { get; set; }
    public object Source { get; set; }
    public bool ValidatesOnDataErrors { get; set; }
    public bool ValidatesOnExceptions { get; set; }
    public TimeSpan Delay { get; set; }
    [ConstructorArgument("path")]
    public PropertyPath Path { get; set; }
    [TypeConverter(typeof(CultureInfoIetfLanguageTagConverter))]
    public CultureInfo ConverterCulture { get; set; }

    public override object ProvideValue(IServiceProvider serviceProvider)
    {
        var valueProvider = serviceProvider.GetService(typeof (IProvideValueTarget)) as IProvideValueTarget;
        if (valueProvider != null)
        {
            var bindingTarget = valueProvider.TargetObject as DependencyObject;
            var bindingProperty = valueProvider.TargetProperty as DependencyProperty;
            if (bindingProperty == null || bindingTarget == null)
            {
                throw new NotSupportedException(string.Format(
                    "The property '{0}' on target '{1}' is not valid for a DelayBinding. The DelayBinding target must be a DependencyObject, "
                    + "and the target property must be a DependencyProperty.", 
                    valueProvider.TargetProperty, 
                    valueProvider.TargetObject));
            }

            var binding = new Binding();
            binding.Path = Path;
            binding.Converter = Converter;
            binding.ConverterCulture = ConverterCulture;
            binding.ConverterParameter = ConverterParamter;
            if (ElementName != null) binding.ElementName = ElementName;
            if (RelativeSource != null) binding.RelativeSource = RelativeSource;
            if (Source != null) binding.Source = Source;
            binding.ValidatesOnDataErrors = ValidatesOnDataErrors;
            binding.ValidatesOnExceptions = ValidatesOnExceptions;

            return DelayBinding.SetBinding(bindingTarget, bindingProperty, Delay, binding);
        }
        return null;
    }
}

Now the DelayBinding class, which as you can see above is being instantiated by the DelayBindingExtension. You could also create it manually in code:

public class DelayBinding
{
    private readonly BindingExpressionBase _bindingExpression;
    private readonly DispatcherTimer _timer;

    protected DelayBinding(BindingExpressionBase bindingExpression, DependencyObject bindingTarget, DependencyProperty bindingTargetProperty, TimeSpan delay)
    {
        _bindingExpression = bindingExpression;

        // Subscribe to notifications for when the target property changes. This event handler will be 
        // invoked when the user types, clicks, or anything else which changes the target property
        var descriptor = DependencyPropertyDescriptor.FromProperty(bindingTargetProperty, bindingTarget.GetType());
        descriptor.AddValueChanged(bindingTarget, BindingTarget_TargetPropertyChanged);

        // Add support so that the Enter key causes an immediate commit
        var frameworkElement = bindingTarget as FrameworkElement;
        if (frameworkElement != null)
        {
            frameworkElement.KeyUp += BindingTarget_KeyUp;
        }

        // Setup the timer, but it won't be started until changes are detected
        _timer = new DispatcherTimer();
        _timer.Tick += Timer_Tick;
        _timer.Interval = delay;
    }

    private void BindingTarget_KeyUp(object sender, KeyEventArgs e)
    {
        _timer.Stop();
        if (e.Key == Key.Enter) _bindingExpression.UpdateSource();
    }

    private void BindingTarget_TargetPropertyChanged(object sender, EventArgs e)
    {
        _timer.Stop();
        _timer.Start();
    }

    private void Timer_Tick(object sender, EventArgs e)
    {
        _timer.Stop();
        _bindingExpression.UpdateSource();
    }

    public static object SetBinding(DependencyObject bindingTarget, DependencyProperty bindingTargetProperty, TimeSpan delay, Binding binding)
    {
        // Override some specific settings to enable the behavior of delay binding
        binding.Mode = BindingMode.TwoWay;
        binding.UpdateSourceTrigger = UpdateSourceTrigger.Explicit;

        // Apply and evaluate the binding
        var bindingExpression = BindingOperations.SetBinding(bindingTarget, bindingTargetProperty, binding);

        // Setup the delay timer around the binding. This object will live as long as the target element lives, since it subscribes to the changing event, 
        // and will be garbage collected as soon as the element isn't required (e.g., when it's Window closes) and the timer has stopped.
        new DelayBinding(bindingExpression, bindingTarget, bindingTargetProperty, delay);

        // Return the current value of the binding (since it will have been evaluated because of the binding above)
        return bindingTarget.GetValue(bindingTargetProperty);
    }
}

I imagine this would be useful for Silverlight, but since Silverlight does not support custom MarkupExtensions, and since Silverlight Binding's can't have an UpdateSourceTrigger (to set it to Explicit), I expect you would end up creating it through an attached dependency property and triggering the binding to push manually. Let me know if you write one.