30 September 2010

Notifying the viewmodel of input errors using MVVMLight in Silverlight

I was creating a little application that had some input fields and a submit button. I wanted the submit button only to be enabled when the user input was valid. No a very unusual use case. So I set out to create a viewmodel the usual MVVMLight way, extending ViewModelBase and making properties using the snippets Laurent Bugnion provides with the MVVMLight toolkit. To validate them, I decorated them with attributes from System.ComponentModel.DataAnnotations, and validated them with using the Validator. A typical property looks like this:

/// 
/// The  property's name.
/// 
public const string SomecodePropertyName = "Somecode";

private int _somecode = 0;

[Range(0, 2000)]
public int Somecode
{
  get
  {
    return _someCode;
  }

  set
  {
    if (_someCode == value)
    {
      return;
    }
    Validator.ValidateProperty(value,
      new ValidationContext(this, null, null) 
      { MemberName = SomecodePropertyName });

    _someCode = value;

    // Update bindings, no broadcast
    RaisePropertyChanged(SomecodePropertyName);
  }
}

Then I thought I was smart, so I added the following code:

private void RaisePropertyChangedAndRevalidate(string propertyName)
{
  RaisePropertyChanged(propertyName);
  RaisePropertyChanged("IsValid");
}

public bool IsValid
{
  get
  {
    return Validator.TryValidateObject(this, 
                       new ValidationContext(this, null, null),
                       new List<ValidationResult>());
  }
}

and changed every other call to RaisePropertyChanged to RaisePropertyChangedAndRevalidate. Then I bound my button’s IsEnabled property to IsValid

<Button Content="subMit" x:Name="btnSave" 
  IsEnabled="{Binding IsValid,ValidatesOnExceptions=True,NotifyOnValidationError=True}">

and I turned out not be so very smart after all, for it did not work. When the user entered a value that was outside the range of 0-2000 or even plain nonsense – like “thisisnonumber”, the UI gave an error message, I even got the message in my ValidationSummary, but for some reason the viewmodel still found itself valid.

This puzzled me for a while, but it turned out to be perfectly logical. If the user inputs nonsense this throws an exception, and so does a call to Validator.ValidateProperty. So the invalid input never makes to the viewmodel property, and the viewmodel, if it was initially valid, stays valid en thus my button stays enabled. How to get around this?

Actually, it’s pretty simple: notify your viewmodel of input errors, so it can keep track of whatever nonsense the user has tried to cram down its throat. The way I chose to do it was like this:

  • Add a field int _fieldErrors;
  • Bind the event BindingValidationError to a command in the viewmodel, passing it’s parameters along
  • Add to or subtract 1 from_fieldErrors for every time the command was called depending on the parameter
  • Modify the IsValid property so it checks the _fieldErrors field to.

In code:

private void RaisePropertyChangedAndRevalidate(string propertyName)
{
  RaisePropertyChanged(propertyName);
  if (_fieldBindingErrors == 0)
  {
    RaisePropertyChanged("IsValid");
  }           
}
private int _fieldBindingErrors = 0;

public ICommand RegisterFieldBindingErrors
{
  get
  {
    return new RelayCommand<ValidationErrorEventArgs>(e =>
    {
      if (e.Action == ValidationErrorEventAction.Added)
      {
        _fieldBindingErrors++;
      }
      else
      {
        _fieldBindingErrors--;
      }
      RaisePropertyChanged("IsValid");
    });
  }
}

public bool IsValid
{
  get
  {
    return Validator.TryValidateObject(this, 
                       new ValidationContext(this, null, null),
                       new List<ValidationResult>()) 
                       && _fieldBindingErrors == 0;
  }
}

Binding the stuff in XAML goes like this:

<StackPanel
  DataContext="{Binding MyModel,Mode=TwoWay,ValidatesOnExceptions=True,NotifyOnValidationError=True}">
  <i:Interaction.Triggers>
    <i:EventTrigger EventName="BindingValidationError">
          <cmd:EventToCommand Command="{Binding RegisterFieldBindingErrors}" 
            PassEventArgsToCommand="true"/>
        </i:EventTrigger>
      </i:Interaction.Triggers>
</StackPanel>

And thus the viewmodel maintains its own integrity, is notified by the UI of all problems playing around there, and can decide based upon the sum of this information whether or not the user can actually save.

Thanks to Mike Taulty for helping me out on the Validator in real-time on Twitter.

29 September 2010

Extension methods for tomb stoning the Windows Phone 7 model

As I was (and still am) playing with my MVVM-driven Windows Phone 7 map viewer, I started thinking about tomb stoning and/or serializing stuff into the Windows Phone 7 application state and/or isolated storage. I came up with four extension methods than can be used to store/serialize the complete model in both. Maybe not ideal in all cases, but it was a simple solution for me.

Getting started

I created an assembly LocalJoost.Utilities, in which I first defined a generic interface for the model, which I called – with a flash of inspiration – IModel ;-). It’s implementation is not interesting for the extension methods.

Save to phone application state

using System;
using System.IO;
using System.IO.IsolatedStorage;
using System.Runtime.Serialization;
using System.Windows;
using Microsoft.Phone.Shell;

namespace LocalJoost.Utilities
{
  /// <summary>
  /// Some extensions method that allow serializing and deserializing
  /// a model to and from phone state and/or isolated storage
  /// </summary>
  public static class ApplicationExtensions
  {
    private const string ModelKey = "model";
 
    public static IModel RetrieveFromPhoneState(this Application app) 
    {
      if (PhoneApplicationService.Current.State.ContainsKey(ModelKey))
      {
        return PhoneApplicationService.Current.State[ModelKey] as IModel;
      }
      return null;
    }

    public static void SaveToPhoneState(this Application app, IModel model)
    {
      if (PhoneApplicationService.Current.State.ContainsKey(ModelKey))
      {
        PhoneApplicationService.Current.State.Remove(ModelKey);
      }
      PhoneApplicationService.Current.State.Add(ModelKey, model);
    }
  }
}

Creating a Locator

I wanted my model to be bindable by XAML and be usable from code as well, so I created the following ‘Locator’:

using LocalJoost.Utilities;

namespace LocalJoost.Models
{
  public class Locator
  {
    private static IModel _model;
    private static Locator _locator;

    public IModel Model
    {
      get { return _model; }
      set { _model = value; }
    }

    public static Locator Instance
    {
      get { return _locator ?? (_locator = new Locator()); }
    }
  }
}

Using Locator and Model from XAML

First, add the namespace to the XAML

xmlns:Utilities="clr-namespace:LocalJoost.Utilities;assembly=LocalJoost.Utilities"

Then bind it to your Layout root or any other element of choice

 <Grid x:Name="LayoutRoot"
  DataContext="{Binding Source={StaticResource Locator}, Path=Model}">

Instantiating your model

Interesting caveat – the Locator is instantiated, not your model. When the application runs for the very first time, there will be no model to retrieve. Thus, in the constructor of App.Xaml.cs you need to add:

Locator.Instance.Model = new YourModel();

in which you replace "YourModel" for your own model type.

Storing in / retrieving from phone application state

Using the extension methods is pretty simple then: open your App.Xaml.cs, find two methods called “Application_Activated” and “Application_Deactivated” and modify them as follows:

// Code to execute when the application is activated (brought to foreground)
// This code will not execute when the application is first launched
private void Application_Activated(object sender, ActivatedEventArgs e)
{
  Locator.Instance.Model = this.RetrieveFromPhoneState();
}

// Code to execute when the application is deactivated (sent to background)
// This code will not execute when the application is closing
private void Application_Deactivated(object sender, DeactivatedEventArgs e)
{
  this.SaveToPhoneState(Locator.Instance.Model);
}

And that’s it. Your model now persists to the phone state and survives, for instance, a hit on the search button

Storing in Isolated Storage

This proves to be marginally more difficult. I expanded the class ApplicationExtensions with two more methods and a const:

private const string DataFile = "model.dat";

public static T RetrieveFromIsolatedStorage<T>(this Application app) 
  where T : class
{
  using (var appStorage = IsolatedStorageFile.GetUserStoreForApplication())
  {
    if (appStorage.FileExists(DataFile))
    {
      using (var iss = appStorage.OpenFile(DataFile, FileMode.Open))
      {
        try
        {
          var serializer = new DataContractSerializer(typeof(T));
          return serializer.ReadObject(iss) as T;
        }
        catch (Exception e)
        {
          System.Diagnostics.Debug.WriteLine(e);
        }
      }
    }
  }
  return null;
}

public static void SaveToIsolatedStorage(this Application app, IModel model)
{
  using (var appStorage = IsolatedStorageFile.GetUserStoreForApplication())
  {
    if (appStorage.FileExists(DataFile))
    {
      appStorage.DeleteFile(DataFile);
    }
    var serializer = new DataContractSerializer(model.GetType());
    using (var iss = appStorage.CreateFile(DataFile))
    {
      serializer.WriteObject(iss, model);
    }
  }
}

You now have to find Application_Launching and Application_Closing in App.Xaml.cs and modify them in a similar way:

// Code to execute when the application is launching (eg, from Start)
// This code will not execute when the application is reactivated
private void Application_Launching(object sender, LaunchingEventArgs e)
{
    Locator.Instance.Model = 
       this.RetrieveFromIsolatedStorage<YourModel>();
}

// Code to execute when the application is closing (eg, user hit Back)
// This code will not execute when the application is deactivated
private void Application_Closing(object sender, ClosingEventArgs e)
{
    this.SaveToIsolatedStorage(Locator.Instance.Model);
}

Some notes

  • In order to make this work, your need to mark your model class with the [DataContract] attribute, and every member you want to be serialized with [DataMember]
  • If you are using MVVMLight (which of course you are ;-) ) and if you are just making simple apps that don’t use separate models but just view models, be aware that your model cannot inherit from ViewModelBase, for the simple reason that this class is not serializable. Oops ;-)
  • If your model communicates with the view using attached dependency properties you may run into some timing difficulties. I will soon blog about a work-around for that.

10 September 2010

An animated swipe-enabled title control for Windows Phone 7

Updated for the RTM tools, included sample application to show how it’s used.

For my ongoing ‘research project’ on making the user experience for my MVVM-driven map viewer for Windows Phone 7 a bit better I wanted to make some changes to the header. Initially you could swipe the header which showed which map you show, but it gave no indication that you actually could make the swipe, or that other maps were available. I set out to create a behaviour, and ended up building a control. In my map viewer, it currently looks and works like this:

And, of course, it needed to play along nicely with MVVM. And therefore it has three bindable properties:

  • Items: an IList of basically anything
  • SelectedItem: the currently selected item in Items
  • DisplayText: (optional): the name property of the objects in Items which value should be used in de SwipeTitle. If skipped, the ToString() value of the objects is used as a display value.

It does not sport item or data templates (yet) – it’s just meant to be plug and play. For now.

Usage

You only have to do six things to use this thing:

  • Create an empty Windows Phone 7 application
  • Add the LocalJoost.Controls project included in the demo solution to your project.
  • Create some kind of model with a property containing a list of objects and a property containing a selected object and bind it to the layout root
  • Drag the SwipeTitle control on the design surface at the place of the TextBox called “PageTitle” (and remove PageTitle)
  • Bind property Items, SelectedItem and DisplayText as needed
  • Make sure the Width property of the StackPanel “TitlePanel” is some large width, e.g. 2000.

Below is a short walkthrough of the source. Those who just want to use it, can just grab the source. If you want a simple sample application showing the usage of the control, just grab this solution and see how it works. I sincerely apologize for the sheer silliness of the demo solution, it was all I could think of on short notice.

Walkthrough

The XAML is pretty simple: three TextBlocks in a horizontal StackPanel:

<UserControl x:Class="WP7Viewer.SwipeTitle"
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
  xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
  mc:Ignorable="d"
  FontFamily="{StaticResource PhoneFontFamilyNormal}"
  FontSize="{StaticResource PhoneFontSizeNormal}"
  Foreground="{StaticResource PhoneForegroundBrush}"
  d:DesignHeight="480" d:DesignWidth="480">
    <StackPanel Grid.Row="1" Orientation="Horizontal" x:Name="pnlSwipe">
      <TextBlock x:Name="tbPrevious"
          Foreground="Gray"
           Text="Previous" 
           Margin="0,0,0,0"
           Style="{StaticResource PhoneTextTitle1Style}">
      </TextBlock>
    <TextBlock x:Name="tbCurrent"
           Text="Current" 
           Margin="20,0,0,0"
           Style="{StaticResource PhoneTextTitle1Style}">
       </TextBlock>
    <TextBlock x:Name="tbNext"
          Foreground="Gray"
           Text="Next" 
           Margin="20,0,0,0"
           Style="{StaticResource PhoneTextTitle1Style}">
      </TextBlock>
    </StackPanel>
</UserControl>

You can swipe endlessly left or right, when it comes to the end or the start of the list it just adds the items from the start or the end again. The middle text is the selected object, and is always shown (in white). When you swipe the text to the left, it animates the swipe to completion: the text previously on the right, which you swiped into view, is now displayed in the middle TextBlock. The text that used to be in the middle block, is now in the left, and in the right TextBlock a new text from Items is displayed, as shown in the video.

Now how does this work? If you know how to do it, it is – as everything – pretty simple. First, some boring stuff, the class definition with some members and dependency properties:

using System;
using System.Collections;
using System.Collections.Generic;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Input;
using System.Windows.Media;
using System.Windows.Media.Animation;

namespace WP7Viewer
{
    public partial class SwipeTitle
    {
       /// <summary>
       /// An internal linked list to make searching easier
       /// </summary>
       private LinkedList<object> _displayItems;
       private TranslateTransform _transform;
       private int _currentDisplayItem = 1; 
     
      #region Items
      /// <summary>
      /// Dependency property holding the items selectable in this control
      /// </summary>
      public static readonly DependencyProperty ItemsProperty =
         DependencyProperty.Register("Items", typeof(IList),
         typeof(SwipeTitle), new PropertyMetadata(ItemsChanged));

      private static void ItemsChanged(object sender, 
        DependencyPropertyChangedEventArgs args)
      {
        var c = sender as SwipeTitle;
        if (c != null) {  c.ProcessItemsChanged(); }
      }

      public IList Items
      {
        get { return (IList)GetValue(ItemsProperty); }
        set { SetValue(ItemsProperty, value); }
      }

      public void ProcessItemsChanged()
      {
        _displayItems = new LinkedList<object>();
        foreach (var obj in Items) _displayItems.AddLast(obj);
        SelectedItem = Items[0];
      }
      #endregion

      #region SelectedItem
      /// <summary>
      /// Dependency property holding the currently selected object
      /// </summary>
      public static readonly DependencyProperty SelectedItemProperty =
         DependencyProperty.Register("SelectedItem", typeof(object),
         typeof(SwipeTitle), new PropertyMetadata(SelectedItemChanged));

      private static void SelectedItemChanged(object sender, 
        DependencyPropertyChangedEventArgs args)
      {
        var c = sender as SwipeTitle;
        if (c != null) { c.ProcessSelectedItemChanged(); }
      }

      // .NET Property wrapper
      public object SelectedItem
      {
        get { return (object)GetValue(SelectedItemProperty); }
        set { SetValue(SelectedItemProperty, value); }
      }

      public void ProcessSelectedItemChanged()
      {
        UpdateDisplayTexts();
        ScrollToDisplayItem(1, false);
      }
      #endregion
      
      #region DisplayField
      public string DisplayField
      {
        get { return (string)GetValue(DisplayFieldProperty); }
        set { SetValue(DisplayFieldProperty, value); }
      }

      public static readonly DependencyProperty DisplayFieldProperty =
        DependencyProperty.Register("DisplayField", typeof(string), 
          typeof(SwipeTitle), null);
      #endregion
    }
  }
}

The transformation is used in the animation and to make sure the middle TextBlock is displayed when idle. I tend to tuck dependency properties in regions to keep stuff a bit organized, but feel free to do otherwise. Note, however, that the objects in Items are immediately copied in a LinkedList _displayItems – I use this list to make it easier to find previous and next objects.

Then we need a little method to get the display text from the objects according to the value of “DisplayField”:

/// <summary>
/// Retrieve the display value of an object
/// </summary>
/// <param name="displayObject"></param>
/// <returns></returns>
private string GetDisplayValue( object displayObject)
{
  if (DisplayField != null)
  {
    var pinfo = displayObject.GetType().GetProperty(DisplayField);
    if (pinfo != null)
    {
      return pinfo.GetValue(displayObject, null).ToString();
    }
  }
  return displayObject.ToString();
}
To show or update the displayed texts, according the object that is selected (in SelectedItem), the UpdateDisplayTexts method is needed. This is fired when Items or SelectedItem is changed. It finds SelectedItem and puts it in the middle TextBlock, and finds the texts that need to be before and after it, using the LinkedList _displayItems.
/// <summary>
/// Shows (possible) new texts in the three text boxes
/// </summary>
private void UpdateDisplayTexts()
{
  if (_displayItems == null) return;
  if (SelectedItem == null)
  {
    SelectedItem = _displayItems.First.Value;
  }
  tbCurrent.Text = GetDisplayValue(SelectedItem);
  var currentNode = _displayItems.Find(SelectedItem);
  if (currentNode == null) return;
  tbNext.Text =
    GetDisplayValue(currentNode.Next != null ? 
     currentNode.Next.Value : _displayItems.First.Value);
  tbPrevious.Text =
    GetDisplayValue(currentNode.Previous != null ? 
     currentNode.Previous.Value : _displayItems.Last.Value);
}

Now I need to set up and implement some events in the control:

  • The items must be initially displayed, after the control is loaded
  • When the user swipes the title, it must follow his finger
  • When the user stops swiping, it must decide whether the user has swiped far enough to select the next item (and if not, revert the swipe), and if the swipe was far enough, select the next item
  • When the next item is selected, show the new selected text in the middle again.
public SwipeTitle()
{
    InitializeComponent();
    _transform = new TranslateTransform();

    pnlSwipe.Loaded += (sender, args) => ProcessSelectedItemChanged();
    pnlSwipe.ManipulationDelta += pnlSwipe_ManipulationDelta;
    pnlSwipe.ManipulationCompleted += pnlSwipe_ManipulationCompleted;
    pnlSwipe.RenderTransform = _transform;
    tbPrevious.SizeChanged += tbPrevious_SizeChanged;
}

void pnlSwipe_ManipulationDelta(object sender, ManipulationDeltaEventArgs e)
{
    _transform.X += e.DeltaManipulation.Translation.X;
}

/// <summary>
/// Caculates the screen width
/// </summary>
private static double ScreenWidth
{
    get
    {
        var appFrame = Application.Current.RootVisual as Frame;
        return null == appFrame ? 0.0 : appFrame.RenderSize.Width;
    }
}

/// <summary>
/// Fired after manipulation is completed. When the title has been moved over 25% of the
/// screen, the next or previous item is selected
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
void pnlSwipe_ManipulationCompleted(object sender, ManipulationCompletedEventArgs e)
{
    if (e.TotalManipulation.Translation.X > .25 * ScreenWidth)
    {
        ScrollToDisplayItem(_currentDisplayItem - 1, true);
    }
    else if (e.TotalManipulation.Translation.X < -.25 * ScreenWidth)
    {
        ScrollToDisplayItem(_currentDisplayItem + 1, true);
    }
    ScrollToDisplayItem(_currentDisplayItem, true);
}

/// <summary>
/// Fired when new data is put into the last object. 
/// Rendering is then finished - the middle text is showed in the middle again
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
void tbPrevious_SizeChanged(object sender, SizeChangedEventArgs e)
{
    ScrollToDisplayItem(1, false);
}

In the constructor the members are initialized – particularly the transform – which is set to the StackPanel surrounding the three TextBlocks. When the user now swipes, the texts appear to follow him. When, in pnlSwipe_ManipulationCompleted, the user has dragged the text over more than 25% of the screen, it scrolls the text further until the newly selected items is fully into view. If the text value of the last box is changed, we need to reset the middle TextBlock in the center again – but now without animation, and so it will seem if the scrolling text suddenly changes in color and appears to be selected.

Notice a little gem in here – the ScreenWidth property. It turns out you can determine the actual screensize by trying to cast the RootVisual to a Frame, and then check it’s RenderSize.

All that is left now, basically, is the implementation of ScrollToDisplayItem – and a companion method, as shown below:

/// <summary>
/// Scrolls to one of the 3 display items
/// </summary>
/// <param name="item">0,1 or 2</param>
/// <param name="animate">Animate the transition</param>
void ScrollToDisplayItem(int item, bool animate)
{
  _currentDisplayItem = item;
  if (_currentDisplayItem < 0) _currentDisplayItem = 0;
  if (_currentDisplayItem >= pnlSwipe.Children.Count)
  {
    _currentDisplayItem = pnlSwipe.Children.Count - 1;
  }
  var totalTransform = 0.0;
  for (var counter = 0; counter < _currentDisplayItem; counter++)
  {
    double leftMargin = 0;
    if (counter + 1 < pnlSwipe.Children.Count)
    {
      leftMargin = 
        ((Thickness)(pnlSwipe.Children[counter + 1].GetValue(MarginProperty))).Left;
    }
    totalTransform += 
      pnlSwipe.Children[counter].RenderSize.Width + leftMargin;
  }
  var whereDoWeGo = -1 * totalTransform;

  if (animate)
  {
    //Set up the storyboard and animate the transition
    var sb = new Storyboard();
    var anim = 
      new DoubleAnimation
      {
        From = _transform.X,
        To = whereDoWeGo,
        Duration = new Duration(
          TimeSpan.FromMilliseconds(Math.Abs(_transform.X - whereDoWeGo)))
      };
    Storyboard.SetTarget(anim, _transform);
    Storyboard.SetTargetProperty(anim, new PropertyPath(TranslateTransform.XProperty));
    sb.Children.Add(anim);
    sb.Completed += sb_Completed;
    sb.Begin();
  }
  else
  {
    _transform.X = whereDoWeGo;
  }
}

/// <summary>
/// Fired when an animation is completed. Then a new items must be selected
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
void sb_Completed(object sender, EventArgs e)
{
  if (SelectedItem != null)
  {
    var currentNode = _displayItems.Find(SelectedItem);
    if (_currentDisplayItem == 0)
    {
      SelectedItem = (currentNode.Previous != null ? 
                       currentNode.Previous.Value : _displayItems.Last.Value);
    }
    if (_currentDisplayItem == 2)
    {
      SelectedItem = (currentNode.Next != null ? 
                       currentNode.Next.Value : _displayItems.First.Value);
    }
    UpdateDisplayTexts();
  }
}

In ScrollToDisplayItem the text is either moved or animated in the right direction, and when the animation is finished, the TextBlocks are updated with values according to the swipe direction. If no animation is needed – which occurs initially, or after the texts are updated – the transform is simply applied in stead of animated.

Credits

Important parts of the code came into being during a joint hacking evening at Sevensteps in Amersfoort, Netherlands, at August 31 2010. My sincere thanks to Bart Rozendaal, Kees Kleimeer and Pieter-Bas IJdens, all of Sevensteps, who basically coded the method pnlSwipe_ManipulationCompleted and the property ScreenWidth, almost all of the ScrollToDisplayItem method, and in addition supported me with wine, snacks and enjoyable company during that memorable evening.