Jeff Handley - Binding Converters

One of the reasons why the ViewModel pattern is so powerful in Silverlight and WPF is because Binding Converters can do so much. As we saw in HelloWorld.ViewModel, a ViewModel can expose a boolean property that is consumed as a Visibility value for controls. This requires some glue to convert the boolean to the necessary enum, and that’s where our VisibilityConverter comes in. If you want to see this in action, go check out the sample code, but here’s how the VisibilityConverter works.

In order to create any binding converter, you can start off by creating a class that implements System.Windows.Data.IValueConverter. This is the interface that defines how we will convert data and optionally convert it back. Not surprisingly, IValueConverter defines two methods, Convert and ConvertBack. Here’s the metadata from the class, which explains how they’re used pretty well.

using System;

using System.Globalization;

  

namespace System.Windows.Data

{

  // Summary:

  //     Exposes methods that allow modifying the data as it passes through the binding

  //     engine.

  public interface IValueConverter

    {

  // Summary:

  //     Modifies the source data before passing it to the target for display in the

  //     UI.

  //

  // Parameters:

  //   value:

  //     The source data being passed to the target.

  //

  //   targetType:

  //     The System.Type of data expected by the target dependency property.

  //

  //   parameter:

  //     An optional parameter to be used in the converter logic.

  //

  //   culture:

  //     The culture of the conversion.

  //

  // Returns:

  //     The value to be passed to the target dependency property.

  object Convert(object value, Type targetType, object parameter, CultureInfo culture);

  //

  // Summary:

  //     Modifies the target data before passing it to the source object. This method

  //     is called only in System.Windows.Data.BindingMode.TwoWay bindings.

  //

  // Parameters:

  //   value:

  //     The target data being passed to the source.

  //

  //   targetType:

  //     The System.Type of data expected by the source object.

  //

  //   parameter:

  //     An optional parameter to be used in the converter logic.

  //

  //   culture:

  //     The culture of the conversion.

  //

  // Returns:

  //     The value to be passed to the source object.

  object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture);

    }

}

When using one-way binding from your ViewModel to your View, like we did with our Visibility on our images, you only need to implement the Convert method. But if you need to support two-way binding where the View can call the setter on your ViewModel, then you need to also implement the ConvertBack method. The VisibilityConverter that I created supports two-way binding.

The first time I wrote VisibilityConverter, I simply checked the boolean value specified, and if it was true, I returned Visibility.Visible; if false, I returned Visibility.Collapsed. But it wasn’t long before I realized that wouldn’t do. As we saw in HelloWorld, I need to be able to reverse the behavior. That’s where our ConverterParameter is used.

Your ConverterParameter is passed in as an object but for the most part, you’ll get the value as a string. If you programmatically set up a binding, I suppose you could get the value as something else, but through declarative binding, you’ll get the value as string. This allows you to pass extra data to your binding converter though, so that the converter can make decisions based on this parameter. As used in the VisibilityConverter, I am specifying what Visibility value to use when the bound value is true.

Let’s take a look at the code for Convert.

/// <summary>

/// Convert a boolean value to a Visibility value

/// </summary>

/// <param name="value"></param>

/// <param name="targetType"></param>

/// <param name="parameter">ConverterParameter is of type Visibility</param>

/// <param name="culture"></param>

/// <returns></returns>

public object Convert(object value, Type targetType, object parameter, System.Globalization.CultureInfo culture)

{

  bool isVisible = (bool)value;

  

  // If visibility is inverted by the converter parameter, then invert our value

  if (IsVisibilityInverted(parameter))

        isVisible = !isVisible;

  

  return (isVisible ? Visibility.Visible : Visibility.Collapsed);

}

I’m making use of a private method called IsVisibilityInverted, which is defined here:

/// <summary>

/// Determine the visibility mode based on a converter parameter.  This parameter is of type Visibility,

/// and specifies what visibility value to return when the boolean value is true.

/// </summary>

/// <param name="parameter"></param>

/// <returns></returns>

private static Visibility GetVisibilityMode(object parameter)

{

  // Default to Visible

    Visibility mode = Visibility.Visible;

  

  // If a parameter is specified, then we'll try to understand it as a Visibility value

  if (parameter != null)

    {

  // If it's already a Visibility value, then just use it

  if (parameter is Visibility)

        {

            mode = (Visibility)parameter;

        }

  else

        {

  // Let's try to parse the parameter as a Visibility value, throwing an exception when the parsing fails

  try

            {

                mode = (Visibility)Enum.Parse(typeof(Visibility), parameter.ToString(), true);

            }

  catch (FormatException e)

            {

  throw new FormatException("Invalid Visibility specified as the ConverterParameter.  Use Visible or Collapsed.", e);

            }

        }

    }

  

  // Return the detected mode

  return mode;

}

  

/// <summary>

/// Determine whether or not visibility is inverted based on a converter parameter.

/// When the parameter is specified as Collapsed, that means that when the boolean value

/// is true, we should return Collapsed, which is inverted.

/// </summary>

/// <param name="parameter"></param>

/// <returns></returns>

private static bool IsVisibilityInverted(object parameter)

{

  return (GetVisibilityMode(parameter) == Visibility.Collapsed);

}

As you see, I actually have 2 methods; one for GetVisibilityMode and one for IsVisibilityInverted. GetVisibilityMode is where I parse the ConverterParameter and return the Visibility value to use for true values. IsVisibilityInverted checks to see if this is set to Collapsed.

I mentioned that I also implemented the ConvertBack method to support two-way binding. I’m not using this yet anywhere, but as an exercise for implementing a converter, we can the see the code here:

/// <summary>

/// Support 2-way databinding of the VisibilityConverter, converting Visibility to a boolean

/// </summary>

/// <param name="value"></param>

/// <param name="targetType"></param>

/// <param name="parameter"></param>

/// <param name="culture"></param>

/// <returns></returns>

public object ConvertBack(object value, Type targetType, object parameter, System.Globalization.CultureInfo culture)

{

  bool isVisible = ((Visibility)value == Visibility.Visible);

  

  // If visibility is inverted by the converter parameter, then invert our value

  if (IsVisibilityInverted(parameter))

        isVisible = !isVisible;

  

  return isVisible;

}

We deal with our ConverterParameter in the same fashion here, and we basically reverse the code from the Convert method.

Again, you can see this converter in action in HelloWorld.ViewModel. And if you’re using the ViewModel pattern, you might find yourself using binding converters pretty liberally, and that’s a good thing. Keep your view-specific implementations out of your ViewModel by converting values during binding. This allows your view to still have empty code-behind files, provides testability of the standalone converters, and it keeps your ViewModel separated from your View logic—all good things.

One last note too… don’t get stuck thinking that converters can only convert from one scalar value to another. You can do all sorts of cool things with converters. Just like with the ViewModel pattern in general, once you start to use converters, you’ll be hooked, and you’ll come up with all kinds of out-of-the-box ways of using them.