This blog post provides step-by-step instructions for creating a user control, which exposes bindable properties, in WPF and Silverlight. The post covers dependency properties, and how to manage DataContext inheritance.

When building user interfaces you will often find yourself repeating the same UI patterns across your application. After all, users like to be presented with a consistent interface, so re-use makes sense. The WPF and Silverlight frameworks provide custom controls and user controls as a mechanism for re-using blocks of UI elements. Custom controls are rather special, with the logic being de-coupled from the XAML in order to support templating. For most needs, the simpler user control is more appropriate.

From participating in sites like StackOverflow I have noticed that whilst most people understand how to create a user control, which allows them to ‘stamp out’ the same XAML in multiple places, many struggle with how to make their user controls flexible by exposing properties that configure how it looks or behaves. This blog post will walk through a simple example, showing you how to create a user control, add dependency properties, wire them to the user control XAML and make a truly re-useable control.

We’ll start with a very simple example, an application that displays a simple form field which consists of a name and a value:

<UserControl x:Class="UserControlExample.MainPage"
    ...>
 
  <Grid x:Name="LayoutRoot" Background="White">
 
    <StackPanel Orientation="Horizontal"
                VerticalAlignment="Top">
      <TextBlock Text="Shoesize:"
                 Width="100"
                 VerticalAlignment="Center"/>   
      <TextBox Text="{Binding Path=Shoesize}"
               Width="100"/>
    </StackPanel>
  </Grid>
</UserControl>

This UI is bound to a simple model object that implements INotifyPropertyChanged (not shown for the sake of brevity):

public class ModelObject : INotifyPropertyChanged
{
  public int Shoesize {...}
 
  public double Height {...}
}

The constructor instantiates the model object and sets it as the DataContext:

public MainPage()
{
  InitializeComponent();
 
  var model = new ModelObject()
  {
    Shoesize = 12,
    Height = 34.5
  };
 
  this.DataContext = model;
}

This produces the expected behaviour, a label and a text field that allows you to edit the Shoesize property:

Let’s say we want to allow the user to edit the Height property as well. We could cut and paste our current XAML, but this will only cause maintenance issues in future. Instead, the preferred approach would be to move the XAML into a user control, allowing it to be re-used.

The first step is to create a new user control, FieldUserControl, and move our XAML into there:

<UserControl x:Class="UserControlExample.FieldUserControl"
    ...>
  <StackPanel Orientation="Horizontal">
    <TextBlock Text="Shoesize:"
               Width="100"
               VerticalAlignment="Center"/>
    <TextBox Text="{Binding Path=Shoesize}"
             Width="100"/>
  </StackPanel>
</UserControl>

We can now replace the XAML we have moved with an instance of this user control:

<UserControl x:Class="UserControlExample.MainPage"
    xmlns:local="clr-namespace:UserControlExample"
    ...>
  <Grid x:Name="LayoutRoot">
    <local:FieldUserControl VerticalAlignment="Top"/>
  </Grid>
</UserControl>

Compiling and running this code proves that this still works; we can see the model property and edit it:

For trivial user controls this is all we need to do. However, in most cases, like this one, you will find that there are some elements of your user control that you wish to configure. In order to use this control for editing the Height property we need to make the label configurable. We do this by adding a Label property to our FieldUserControl.

This is where things get a bit tricky! Ideally this property should support binding, just like any other property of the framework UI controls. The WPF / Silverlight binding framework revolves around the concept of dependency properties, you can make any property the source of a binding, but the target must be a dependency property (DP). So let’s go ahead and add a Label dependency property to our user control:

public partial class FieldUserControl : UserControl
{
  #region Label DP
 
  /// <summary>
  /// Gets or sets the Label which is displayed next to the field
  /// </summary>
  public String Label
  {
    get { return (String)GetValue(LabelProperty); }
    set { SetValue(LabelProperty, value); }
  }
 
  /// <summary>
  /// Identified the Label dependency property
  /// </summary>
  public static readonly DependencyProperty LabelProperty =
      DependencyProperty.Register("Label", typeof(string),
        typeof(FieldUserControl), new PropertyMetadata(""));
 
  #endregion
 
  public FieldUserControl()
  {
    InitializeComponent();
  }
}

A lot of code isn’t it? It’s all boiler-plate stuff, you just have to live with it (I’d recommend either using code-snippets, or code generation for DPs)

We can now go ahead and bind the label text to this property:

<UserControl x:Class="UserControlExample.FieldUserControl"
    ...>
  <StackPanel Orientation="Horizontal" x:Name="LayoutRoot">
    <TextBlock Text="{Binding Path=Label}"
               Width="100"
               VerticalAlignment="Center"/>
    <TextBox Text="{Binding Path=Shoesize}"
             Width="100"/>
  </StackPanel>
</UserControl>

However, if you compile and run the above code, you’ll find that it doesn’t work. The model property value is still displayed but the label is not.

So why is this?

Bindings have both a source and a target; where the binding framework is responsible for handling change notifications from the source and (optionally) the target, keeping the two synchronized. The bindings in our FieldUserControl have a value for the Path, which specifies the target, but what is the source?

If you create a binding in XAML but do not specify the source (which is probably the most common use case), the source will be set to the DataContext of the control the binding has been specified on. The DataContext is inherited down the visual tree, from each control’s parent to child. The DataContext is most often set to a view model or business / model object, as in our case where the top level control, the MainPage, has its DataContext set to an instance of ModelObject.

As a result, the DataContext for FieldUserControl and all of its child elements is also ModelObject. This is why our Value binding is failing. Value is a property of FieldUserControl, not our model object.

So how do we go about fixing this? Most people’s first reaction is to set the DataContext of the user control to itself (I distinctly recall doing this myself the first time I encountered this problem!). We’ll find out later that this is a mistake – but for now let’s just go with it!

public FieldUserControl()
{
  InitializeComponent();
 
  this.DataContext = this;
}

With the DataContext of the control now set to itself, our label is now working:

However, now our value has disappeared! Again, this is a DataContext issue, the binding in our user control is on a Shoesize property, whilst the DataContext is now the FieldUserControl instance.

This is not such a big problem, we were going to have to change that anyway, a hard-coded binding to the Shoesize property means that we cannot re-use this control to edit other properties of the model object.

So we add another dependency property to our user control. We already have the Label dependency property, we now add a Value property:

public partial class FieldUserControl : UserControl
{
  #region Label DP
 
  ...
 
  #endregion
 
  #region Value DP
 
  /// <summary>
  /// Gets or sets the Value which is being displayed
  /// </summary>
  public object Value
  {
    get { return (object)GetValue(ValueProperty); }
    set { SetValue(ValueProperty, value); }
  }
 
  /// <summary>
  /// Identified the Label dependency property
  /// </summary>
  public static readonly DependencyProperty ValueProperty =
      DependencyProperty.Register("Value", typeof(object),
        typeof(FieldUserControl), new PropertyMetadata(null));
 
  #endregion
 
  public FieldUserControl()
  {
    InitializeComponent();
 
    this.DataContext = this;
  }
}

This value property is bound to the user control UI as follows:

<UserControl x:Class="UserControlExample.FieldUserControl"
    ...>
  <StackPanel Orientation="Horizontal" x:Name="LayoutRoot">
    <TextBlock Text="{Binding Path=Label}"
               Width="100"
               VerticalAlignment="Center"/>
    <TextBox Text="{Binding Path=Value}"
             Width="100"/>
  </StackPanel>
</UserControl>

The idea here is that the exposed Value property ‘relays’ the value of the binding in our MainPage.xaml, which now has a binding which tells us which model object property is being displayed in our user control:

<Grid>
  <StackPanel Orientation="Vertical"
              HorizontalAlignment="Left"
              Margin="10">
    <local:FieldUserControl VerticalAlignment="Top"
                            Label="Height:"
                            Value="{Binding Height}"/>
    <local:FieldUserControl VerticalAlignment="Top"
                            Label="Shoesize:"
                            Value="{Binding Height}"/>
  </StackPanel>
</Grid>

If you compile and run this code you will find that … it doesn’t work!

Remember earlier when I said that setting the user control’s DataContext to itself is a mistake? We have just found out why!

The source of a binding is the DataContext of the control it is defined upon. In our MainPage.xaml we have attempted to bind the Value property of the FieldUserControl to the Height property on our model object. However, the code within the FieldUserControl constructor means that it no longer inherits its parent’s DataContext (i.e. our model object), so this binding does not work.

This problem can be fixed by setting the DataContext of the FieldUserControl’s root element to itself.

Note that the user control has a StackPanel as its root element and that this is named LayoutRoot:

<UserControl x:Class="UserControlExample.FieldUserControl"
    ...>
  <StackPanel Orientation="Horizontal"
              x:Name="LayoutRoot">
    ...
  </StackPanel>
</UserControl>

We change the constructor so that it sets the LayoutRoot DataContext to itself.

public FieldUserControl()
{
  InitializeComponent();
 
  //this.DataContext = this;
  LayoutRoot.DataContext = this;
}

This means that the FieldUserControl still inherits its parent’s DataContext, so bindings to our model object will work. Furthermore, the FieldUserControl and its children all have the FieldUserControl as their DataContext, so their bindings work also:

Finally, we’re done!

If the technique of binding the layout root of the user control to itself is a bit confusing – the following diagram, which shows the visual tree of our simple application, might help:

Again, notice that the DataContext of FieldUserControl is inherited from its parent. This means that any bindings we add to FieldUserControl have the ModelObect as their source.

We can now create multiple instances of FieldUserControl to edit different properties:

<UserControl x:Class="UserControlExample.MainPage"
    xmlns:local="clr-namespace:UserControlExample"
    ...>
 
  <Grid>
    <StackPanel Orientation="Vertical"
                HorizontalAlignment="Left"
                Margin="10">
      <local:FieldUserControl VerticalAlignment="Top"
                              Label="Height:"
                              Value="{Binding Height}"/>
      <local:FieldUserControl VerticalAlignment="Top"
                              Label="Shoesize:"
                              Value="{Binding Shoesize}"/>
    </StackPanel>
  </Grid>
</UserControl>

With an update of the FieldUserControl styling, the result looks like this:

We now have a truly re-useable user control!

As an aside, for bonus points, you can bind the layout root DataContext without any code-behind by using an ElementName binding as follows:

<UserControl x:Class="UserControlExample.FieldUserControl"
             x:Name="parent" ...>
  <StackPanel Orientation="Horizontal"
              DataContext="{Binding ElementName=parent}">
    <TextBlock Text="{Binding Path=Label}"
               Width="100"
               VerticalAlignment="Center"/>
    <TextBox Text="{Binding Path=Shoesize}"
             Width="100"/>
  </StackPanel>
</UserControl>

Or, in WPF you could event use a RelativeSource FindAncestor binding, with AncestorType set to the type of FieldUserControl (but that would just be showing off!).

Hopefully this blog post will help anyone who is confused about how to create user controls which expose properties in WPF or Silverlight.

You can download the sourcecode for the example: UserControlExample.zip

Regards, Colin E.

The Windows Phone 7 camera gives you the option to record the location where a picture was taken (under Settings => applications => pictures+camera). With this feature turned on, each application has their latitude, longitude and altitude stored as part of the standard EXIF data. I thought it would be fun to combine the previous blog post I wrote on pushpin clustering with the photos on my camera, to allow me to explore them via a Bing Maps control. With not much more than 100 lines of code I came up with an application which I think is a lot of fun to use.

Here are all the photos on my phone, note the way the pushpins are clustered.	Here are a few pictures I took in New York, of the One World Trade Centre and the Stock Exchange.
Here are some pictures around Europe, including one of Gergely Orosz waiting for his turn in the Edinburgh Marathon Relay.	And finally, some pictures I took whilst running around Kielder Water during Kielder marathon.

Accessing the EXIF data

You can access the photos on a WP7 device via the XNA MediaLibrary class. The interface that this class provides gives you access to Picture instances which have properties that allow you to access the width / height and a few other basic attributes. They also have methods that return streams which can be used to read the thumbnail and image data, however, they do not expose the picture location. This is ‘hidden’ within the EXIF data.

Fortunately there is a C# implementation of an EXIF decoder available on codeproject, which, with a few tweaks by Tim Heuer works just fine within Silverlight for Windows Phone 7.

With this library, accessing the EXIF data is a one-liner:

JpegInfo info = ExifReader.ReadJpeg(picture.GetImage(), picture.Name);

The JpegInfo class exposes the raw EXIF geolocation data, which is detailed in the EXIF specification as being expressed as separate components of degrees, minutes and seconds together with a reference direction (North / South, East / West). We can convert from the sexagesimal numeric system used in EXIF, to the decimal system as follows:

private static double DecodeLatitude(JpegInfo info)
{
  double degrees = ToDegrees(info.GpsLatitude);
  return info.GpsLatitudeRef == ExifGpsLatitudeRef.North ? degrees : -degrees;
}
 
private static double DecodeLongitude(JpegInfo info)
{
  double degrees = ToDegrees(info.GpsLongitude);
  return info.GpsLongitudeRef == ExifGpsLongitudeRef.East ? degrees : -degrees;
}
 
public static double ToDegrees(double[] data)
{
  return data[0] + data[1] / 60.0 + data[2] / (60.0 * 60.0);
}

Analysing the images

When the application starts a BackgroundWorker is used to read the EXIF data for all of the pictures in the phone’s media library, with those that have geolocation data available being stored in a separate list:

BackgroundWorker bw = new BackgroundWorker();
bw.WorkerReportsProgress = true;
 
// analyse the pictures that reside in the Media Library in a background thread
bw.DoWork += (s, e) =>
{
  var ml = new MediaLibrary();
 
  using (var pics = ml.Pictures)
  {
    int total = pics.Count;
    int index = 0;
    foreach (Picture picture in pics)
    {
      // read the EXIF data for this image
      JpegInfo info = ExifReader.ReadJpeg(picture.GetImage(), picture.Name);
 
      // check if we have co-ordinates
      if (info.GpsLatitude.First() != 0.0)
      {
        _images.Add(new LocatedImage()
        {
          Picture = picture,
          Lat = DecodeLatitude(info),
          Long = DecodeLongitude(info)
        });
      }
 
      // report progress back to the UI thread
      string progress = string.Format("{0} / {1}", index, total);
      bw.ReportProgress((index * 100 / total), progress);
 
      index++;
    }
  }
};
 
// update progress on the UI thread
bw.ProgressChanged += (s, e) =>
  {
    string title = (string)e.UserState;
    ApplicationTitle.Text = title;
  };
 
bw.RunWorkerAsync();
 
// when analysis is complete, add the pushpins
bw.RunWorkerCompleted += (s, e) =>
  {
    ApplicationTitle.Text = "";
    AddPushpins();
  };

When the pictures have all been analysed, a pushpin is created for each image which is then added to the clusterer described in my previous blog post.

private void AddPushpins()
{
  List<Pushpin> pushPins = new List<Pushpin>();
 
  // create a pushpin for each picture
  foreach (var image in _images)
  {
    Location location = new Location()
    {
      Latitude = image.Lat,
      Longitude = image.Long
    };
 
    Pushpin myPushpin = new Pushpin()
    {
      Location = location,
      DataContext = image,
      Content = image,
      ContentTemplate = this.Resources["MarkerTemplate"] as DataTemplate
    };
 
    pushPins.Add(myPushpin);
  }
 
  // add them to the map via a clusterer
  var clusterer = new PushpinClusterer(map, pushPins, this.Resources["ClusterTemplate"] as DataTemplate);
}

The template used for the pushpins simply renders the image thumbnail:

<DataTemplate x:Key="MarkerTemplate">
  <Border BorderBrush="White" BorderThickness="1">
    <Image Source="{Binding Picture, Converter={StaticResource PictureThumbnailConverter}}"
            Width="80" Height="80"/>
  </Border>
</DataTemplate>

This makes use of a simple value converter which takes a Picture instance and converts it into a BitmapImage which is used as the Source for the image:

public class PictureThumbnailConverter : IValueConverter
{
  public object Convert(object value, Type targetType, object parameter, System.Globalization.CultureInfo culture)
  {
    Picture picture = value as Picture;
    BitmapImage src = new BitmapImage();
    src.SetSource(picture.GetThumbnail());
    return src;
  }
 
  public object ConvertBack(object value, Type targetType, object parameter, System.Globalization.CultureInfo culture)
  {
    return null;
  }
}

The puhspin clusterer allows you to specify a separate template for clustered pushpins. The DataContext for this template is a list of the DataContexts of the clustered pins that it represents. For this application I created a template which renders what looks like a ‘stack’ of images. The number of pictures in the cluster is rendered as a TextBlock and the last image in the cluster rendered.

<DataTemplate x:Key="ClusterTemplate">
  <Grid Width="75" Height="75">
    <Canvas>
      <Border Style="{StaticResource FakePhoto}"
              Canvas.Left="0" Canvas.Top="0"/>
      <Border Style="{StaticResource FakePhoto}"
              Canvas.Left="5" Canvas.Top="5"/>
      <Border BorderBrush="White" BorderThickness="1"
              Canvas.Left="10" Canvas.Top="10"
              DataContext="{Binding Path=., Converter={StaticResource LastConverter}}">
        <Image Source="{Binding Picture, Converter={StaticResource PictureThumbnailConverter}}"
                Width="60" Height="60"/>
      </Border>
      <TextBlock Text="{Binding Count}"
                  Opacity="0.5"
                  Canvas.Left="25" Canvas.Top="15"
                  FontSize="35"/>
    </Canvas>
  </Grid>      
</DataTemplate>
 
<Style TargetType="Border" x:Key="FakePhoto">
  <Setter Property="Width" Value="60"/>
  <Setter Property="Height" Value="60"/>
  <Setter Property="BorderBrush" Value="White"/>
  <Setter Property="Background" Value="Black"/>
  <Setter Property="BorderThickness" Value="1"/>
</Style>

The code that renders the last image is a bit cunning, it uses a value converter that performs a Linq style ‘last’ operations, extracting the last items from a collection of objects:

public class LastConverter : IValueConverter
{
  public object Convert(object value, Type targetType, object parameter, System.Globalization.CultureInfo culture)
  {
    IList enumerable = value as IList;
    return enumerable.Cast<object>().Last();
  }
 
  public object ConvertBack(object value, Type targetType, object parameter, System.Globalization.CultureInfo culture)
  {
    return null;
  }
}

This feels quite neat to me

The clustered pins look like the following, which is a cluster of 5 images around Paris, with the stunning La Grande Arche de la Défense as the image at the top of the cluster:

Despite its simplicity, I have had a lot of fun playing with this application. It has certainly encouraged me to take as many photos as possible whenever I go travelling.

You can download the full sourcecode here: PhotoBrowser.zip

Regards, Colin E.

A popular user-interface in the iOS world is the UIPageControl which renders a small set of dots to indicate the number of pages, with the current page highlighted in some way. This is often used in conjunction with a UIScrollView to navigate between pages in a multi-page layout.

Windows Phone 7 has a Pivot control which allows you to swipe in order to navigate content across multiple screens. However, the Pivot control is most often used when each ‘page’ has some logic header – in some ways it is analogous to a desktop tab control. I decided to use this control, without specifying headers for each PivotItem, then add my own control to render the ‘pips’.

The control that displays the location pips is defined in XAML, with the relationship between this control and the Pivot created via an ElementName binding:

<local:PivotLocationView Source="{Binding ElementName=pivot}"
                          HorizontalAlignment="Center"
                          VerticalAlignment="Bottom"
                          Margin="0,0,0,10"/>
 
<controls:Pivot Margin="0,-30,0,40" 
                x:Name="pivot">
  <controls:PivotItem>
    ...
  </controls:PivotItem>
  <controls:PivotItem>
    ...
  </controls:PivotItem>
  <controls:PivotItem>
    ...
  </controls:PivotItem>
</controls:Pivot>

Note the negative top margin for the Pivot, this control still allocates some header space, even when no headers are defined.

The PivotLocationView user control is backed by a simple view model, with model-items for each pip. When the view model is associated with a Pivot control, it creates a child view model for each Pivot Item, then handles the SelectionChanged event in order to keep the selection state synchronized:

public class PivotLocationViewModel
{
  private Pivot _pivot;
 
  public PivotLocationViewModel()
  {
  }
 
  public PivotLocationViewModel(Pivot pivot)
  {
    PivotItems = new PivotItemViewModelCollection();
    SetPivot(pivot);
  }
 
  /// <summary>
  /// Gets or sets the collection of child view-models
  /// </summary>
  public PivotItemViewModelCollection PivotItems { get; set; }
 
  private void SetPivot(Pivot pivot)
  {
    _pivot = pivot;
 
    // handle selection changed
    pivot.SelectionChanged += Pivot_SelectionChanged;
 
    // create a view model for each pivot item.
    for(int i=0;i<pivot.Items.Count;i++)
    {
      PivotItems.Add(new PivotItemViewModel());
    }
 
    // set the initial selection
    PivotItems[_pivot.SelectedIndex].IsSelected = true;
  }
 
  /// <summary>
  /// Handle selection changes to update the view model
  /// </summary>
  private void  Pivot_SelectionChanged(object sender, SelectionChangedEventArgs e)
  {
 	  var selectedModel = PivotItems.SingleOrDefault(p => p.IsSelected);
    if (selectedModel != null)
      selectedModel.IsSelected = false;
 
    PivotItems[_pivot.SelectedIndex].IsSelected = true;
  }
 
}

The view model for each pivot item is a simple model that implements INotifyPropertyChanged. It has an IsSelected property that reflects the selection state of the Pivot, it also exposes a Color property that indicates the color for each ‘pip’. This could have been implemented as a value converter, but there is little point as we already have a view model:

/// <summary>
/// A view model for each 'pip'
/// </summary>
public class PivotItemViewModel : INotifyPropertyChanged
{
  // ... INotifyPropertyChanged implementation
 
  private bool _isSelected;
 
  public bool IsSelected
  {
    get { return _isSelected; }
    set
    {
      if (_isSelected == value)
        return;
 
      _isSelected = value;
      OnPropertyChanged("IsSelected");
 
      Color = IsSelected ? Colors.Black : Colors.White;
    }
  }
 
  private Color _color;
 
  public Color Color
  {
    get { return _color; }
    set
    {
      _color = value;
      OnPropertyChanged("Color");
    }
  }
}

The XAML for this control is very simple, using an ItemsControl to render an ellipse for each ‘pip’:

<UserControl ...
    d:DataContext="{d:DesignData Source=PivotLocationViewModel.xml}">
 
  <Grid x:Name="LayoutRoot">
    <ItemsControl ItemsSource="{Binding PivotItems}">
      <ItemsControl.ItemsPanel>
        <ItemsPanelTemplate>
          <StackPanel Orientation="Horizontal"/>
        </ItemsPanelTemplate>
      </ItemsControl.ItemsPanel>
      <ItemsControl.ItemTemplate>
        <DataTemplate>
          <Ellipse Width="12" Height="12" Margin="15,0,15,0"
                   Stroke="Black"
                   StrokeThickness="0.5">
            <Ellipse.Fill>
              <SolidColorBrush Color="{Binding Color}"/>
            </Ellipse.Fill>
          </Ellipse>
        </DataTemplate>
      </ItemsControl.ItemTemplate>
    </ItemsControl>
  </Grid>
</UserControl>

Note, the use of design-time data. The following file defines a view model instance:

<PivotLocationViewModel xmlns="clr-namespace:SlideView">
  <PivotLocationViewModel.PivotItems>
    <PivotItemViewModelCollection>
      <PivotItemViewModel IsSelected="False" Color="Red"/>
      <PivotItemViewModel IsSelected="True"  Color="Green"/>
      <PivotItemViewModel IsSelected="False"  Color="Red"/>
      <PivotItemViewModel IsSelected="False"  Color="Red"/>
    </PivotItemViewModelCollection>
  </PivotLocationViewModel.PivotItems>
</PivotLocationViewModel>

This makes creating the above user control much easier, because it can be visualised in the designer:

And there you have it, a simple user-control, which when used in conjunction with a Pivot, provides an interface where the user can swipe between pages.

You can download the full sourcecode: SlideView.zip

Regards, Colin E.

A few weeks back I wrote a blog post about how the recent announcement of PhoneGap support for Windows Phone 7 (WP7) which makes it possible to develop HTML5-based applications. In my previous blog post I showed the development of a simple HTML5 / JavaScript application which PhoneGap wraps up within a Silverlight application ‘shell’ allowing it to be deployed to your phone and potentially submitted to the Marketplace.

However, in order to pass the various Marketplace requirements and gain certification, your application must correctly handle the application lifecycle. With the recent Mango release, the lifecycle has become a little more complicated (although better! in that it adds multi-tasking / fast-app switching). I have also covered the lifecycle in a previous blog post and demonstrated how you can handle the various lifecycle events within an MVVM application.

The most tricky part of the application lifecycle that as a developer you need to handle is the tombstoned state, where your application is terminated (i.e. stopped and removed from memory). It is your responsibility to save enough state in order that when your tombstoned application is restarted, it looks to the user as if your application never stopped running, i.e. you restore your application UI to its original state.

The Mango application lifecycle is illustrated below:

The PhoneGap events API includes pause and resume events, which can be used to detect when the application transitions to and from the dormant state, however, for WP7 these events do not give us enough information. When resuming, we need to know whether it has resumed from a dormant or a tombstoned state. Considering that the tombstoned state is peculiar to WP7 (Android, and iPhone simply have a suspend / resume model), I don’t think it makes sense for the PhoneGap APIs to change in order to accommodate this. In this blog post I will show how the WP7 PhoneGap application host can be modified in order to support tombstoning.

But before we get there, I want to digress a while and look at using the MVVM pattern with JavaScript …

Using the MVVM pattern in JavaScript

Handling tombstoning is much easier if you have a good separation between your view and your logic, with the MVVM pattern being a sensible choice for achieving this. When your application is tombstoned (and your application terminated), then re-activated, it is your responsibility to recreate the original state. Your view-model, is a model-of-a-view, so technically should provide all the information required to fulfil this requirement. See my previous blog post for details.

There are numerous JavaScript UI frameworks available (MVC, MVP, MVVM), however, because I feel tombstoning lends itself particularly well to the MVVM pattern, I decided to give KnockoutJS a try. When reading about this framework you will find references to WPF and Silverlight, it is clear that it has been heavily inspired by the Microsoft XAML frameworks.

The application I have built to demonstrate tombstoning is a very simple, single page twitter search application.

The Knockout view model is a JavaScript object where the properties are defined as ‘observables’. These are JavaScript functions which provide change notification, much like CLR properties with INotifyPropergtyChanged within Silverlight / WPF.

The View-Model

The view model for my twitter search application is shown below:

/// <summary>
/// A view model for searching twitter for a given term
/// </summary>
function TwitterSearchViewModel() {
 
  var that = this;
 
  // --- properties
 
  this.isSearching = ko.observable(false);
 
  this.searchTerm = ko.observable("#wp7dev");
 
  this.tweets = ko.observableArray();
 
  // --- functions
 
  // search twitter for the given string
  this.search = function () {
    if (that.searchTerm() != "") {
 
      that.isSearching(true);
      var url = "http://search.twitter.com/search.json?q=" +
            encodeURIComponent(that.searchTerm());
 
      $.ajax({
        dataType: "jsonp",
        url: url,
        success: function (response) {
          // clear the results
          that.tweets.removeAll();
          // add the new items
          $.each(response.results, function () {
            var tweet = new TweetViewModel(this);
            that.tweets.push(tweet);
          });
 
          that.isSearching(false);
        }
      });
    }
  }
}

It comprises a few simple properties and a search function. Note, the items property is an observableArray, this is analogous to the WPF / Silverlight ObservableCollection, which raises events when its contents are modified, allowing the UI to update automatically. The search function queries the twitter APIs to find matching tweets, updating the observable items array with the results.

The TwitterSearchViewModel items collection is populated with TweetViewModel instances:

/// <summary>
/// A view model that represents a single tweet
/// </summary>
function TweetViewModel(tweet) {
 
    // --- properties
 
    this.author = tweet.from_user,
    this.text = tweet.text,
    this.time = parseDate(tweet.created_at);
    this.thumbnail = tweet.profile_image_url;
 
    // --- functions
 
    // parses the tweet date to give a more readable format
    function parseDate(date) {
      var diff = (new Date() - new Date(date)) / 1000;
 
      if (diff < 60) {
        return diff.toFixed(0) + " seconds ago";
      }
 
      diff = diff / 60;
      if (diff < 60) {
        return diff.toFixed(0) + " minutes ago";
      }
 
      diff = diff / 60;
      if (diff < 10) {
        return diff.toFixed(0) + " hours ago";
      }
 
      diff = diff / 24;
      return diff.toFixed(0) + " days ago";
    }
};

Note, here the properties are not observables, again much like WPF / Silverlight you can bind to a property that does not notify of changes if this is not required.

Also, the Knockout documentation typically defines view-models as literal objects. I prefer to use constructor functions, allowing the creation of multiple instances of the same view model.

The View

With Knockout the view is defined in HTML, you can create it directly, or via a template. I have created the following templates:

<script type=text/x-jquery-tmpl" charset="utf-8" id="twitterSearchView">
  <form data-bind="submit: search">
      <input data-bind="value: searchTerm, valueUpdate: 'afterkeydown'" />
      <button type="submit" data-bind="enable: searchTerm().length > 0 &amp;&amp; isSearching() == false">Go</button>  
  </form>    
  <ul data-bind="template: {name: 'tweetView', foreach: tweets}"> </ul>
</script>

<script type="text/x-jquery-tmpl" charset="utf-8" id="tweetView">
  <li class="tweet">
    <div class="thumbnailColumn">
      <img data-bind="attr: { src: thumbnail }" class="thumbnail"/>
    </div>
    <div class="detailsColumn">
      <div class="author" data-bind="text: author"/> 
      <div class="text" data-bind="text: text"/> 
      <div class="time" data-bind="text: time"/> 
    </div>
  </li>
</script>

The data-bind attribute is used by Knockout to set up the various bindings, connecting your view model properties and observables to the UI.It also defines functions to invoke when DOM events are raised, in much the same way as commands do in WPF / Silverlight.

The application code

Instantiating the view-model and the view is as simple as the following:

$(document).ready(function () {
  document.addEventListener("deviceready", onDeviceReady, false);
});
 
// phonegap is initialised
function onDeviceReady() {
 
  // create the view model
  twitterSearchViewModel = new TwitterSearchViewModel();
 
  // create an instance of the view
  $("#twitterSearchView").tmpl("").appendTo("#app");
 
  // wire-up
  ko.applyBindings(twitterSearchViewModel)
}

Originally I wanted to have the HTML for each view within a separate file, loading them via jQuery as described in this blog post. However, I just couldn’t get this to work within the embedded WP7 browser.

The tweetView tempate is used via the template / foreach Knockout binding, mimicking the Silverlight / WPF ItemsControl.ItemTemplate concept.

The application, after a bit of styling, looks like this:

Tombstoning

Now that the application has a decent structure, we can tackle the application-lifecycle. We need a way to store the view model state when the application transitions into a dormant state. Fortunately Knockout makes this very easy by supplying a toJSON function, which can create a JSON representation of your view-model graph (minus the observables). I have added a getState function to the TwitterSearchViewModel as follows:

// gets the view model state as a JSON string
this.getState = function () {
  return ko.toJSON(this);
}

Now we need a way to invoke this function when the application pauses. PhoneGap provides a pause lifecycle event, however, we need to store the output of this function in the WP7 PhoneApplicationService.Current.State dictionary. Because this is a very much WP7 specific feature, I decided to do this outside of the PhoneGap lifecycle events.

My handler for the Deactivated event simply invokes the above method, storing the state in the application state dictionary:

private void Application_Deactivated(object sender, DeactivatedEventArgs e)
{
  var viewModelState = PhoneGapView.Browser.InvokeScript("getState") as string;
  PhoneApplicationService.Current.State[ModelKey] = viewModelState;
}

Note, to do this I have had to modify the current PhoneGap WP7 library to provide access to the underlying WebBrowser control, I have raised an issue requesting this change to the PhoenGap library.

The application now stores it state when it becomes dormant, the next step is to use this state when an application is activated from a tombstoned state. Within the Activated handler we can read this state as follows:

/// <summary>
/// Gets the state that has been retrieved from isolated storage
/// in order to re-activated after tombstoning.
/// </summary>
public string TombstoneState { get; private set; }
 
private void Application_Activated(object sender, ActivatedEventArgs e)
{
  if (!e.IsApplicationInstancePreserved)
  {
    if (PhoneApplicationService.Current.State.ContainsKey(ModelKey))
    {
      var viewModelState = PhoneApplicationService.Current.State[ModelKey] as string;
      TombstoneState = viewModelState;
    }
  }
}

Note, we check IsApplicationInstancePreserved, if this is true, we do not need to use the state that was saved during deactivation, this allows for fast-application switching.

Unfortunately as this point our UI has not been created and our JavaScript application code is not running, which is why the tombstoned state is simply stored in a public property of our application. To pick this state up, we add a new step to our JavaScript view model creation code:

// phonegap is initialised
function onDeviceReady() {
 
  // create the view model
  twitterSearchViewModel = new TwitterSearchViewModel();
 
  // ---> check for tombstoned state
  window.external.Notify("getState");
 
  // instantiate the view an bind
  $("#twitterSearchView").tmpl("").appendTo("#app");
  ko.applyBindings(twitterSearchViewModel)
}

When the PhoneGap view is created, we add a handler to the ScriptNotify event, allowing us to handle this getState notification:

// Constructor
public MainPage()
{
  InitializeComponent();
 
  phoneGapView.Browser.ScriptNotify += Browser_ScriptNotify;
}
 
 
private void Browser_ScriptNotify(object sender, NotifyEventArgs e)
{
  string commandStr = e.Value;
 
  if (commandStr == "getState" && App.Current.TombstoneState != null)
  {
    phoneGapView.Browser.InvokeScript("setState", new string[] { App.Current.TombstoneState });
  }
}

This checks for the presence of tombstone state, and if found, invokes setState back on our JavaScript view model:

// sets the view model state based on the given JSON string.
this.setState = function (stateString) {
  var state = $.parseJSON(stateString),
      that = this;
 
  this.isSearching(state.isSearching);
  this.searchTerm(state.searchTerm);
 
  this.tweets.removeAll();
  $.each(state.tweets, function () {
    that.tweets.push(this);
  });
}

Note, re-creating our view-model form JSON data is a little more involved than the opposite. I have also cheated a little here, rather than re-creating each TweetViewModel I am using the JSON representation, because this view model has no public functions (i.e. commands).

Conclusions

With the above code the PhoneGap application now successfully handles all of the WP7 lifecycle states and transitions. There are a couple of things to note if you try to run this code yourself:

1. You can force tombstoning via the Debug properties, “Tombstone upon deactiviation while debugging”.
2. I have fund that the WebBrowser on the emulator does not tombstone correctly, when your application resumes the WebBrowser control fails to execute any JavaScript! Fortunately on a real device it works just fine.

Now that I can tombstone a PhoneGap application, I feel that it is one step closer to be a viable solution for application development. The final thing that I still haven’t quite worked out yet is navigation and back-button support. Fortunately Knockout has a lot to offer in this area as well, but more on that later …

You can download the full sourcecode (including PhoneGap library mods) here: PhoneGapExample.zip

Regards, Colin E.

Having spent a number of years studying Physics at university, I have had the importance of error bars well and truly drummed into me! Within physics, or any experimental science, there are always going to be errors in the measurements you make. The more repeat measurements you make, the more confident you can be in the mean value, however you cannot remove the errors altogether. Error bars provide a way to represent the spread of experimental observations graphically, without them, it is hard to have any confidence in the conclusions drawn from the observations!

In this blog post I will show how to implement a custom Visiblox chart series to render error bars:

(The data in the above chart is from a page which details how to calculate the standard error from experimental results).

Creating a Custom Series

As described in my previous blog post on creating a spline series, to create a new series type, you sub-class one of the Visiblox base-classes, in this case MultiValueSeriesBase is a suitable starting point:

public class ErrorBarSeries : MultiValueSeriesBase
{ 
  protected override FrameworkElement CreatePoint(IDataPoint dataPoint)
  {
    throw new NotImplementedException();
  }
 
  protected override void RenderDataLabels()
  {
    throw new NotImplementedException();
  }
}

I don’t want data labels, so the only method I need to implement is CreatePoint, which takes the (multi-valued) point to be rendered as its only argument. The lifecycle of point creating and destruction is taken care of by the base-class.

The IDataPoint has a string indexer which is used to retrieve multiple Y values for multi-valued series. It is a good idea to define these in a single place, here we define the three y-values required for an error-bar series:

public static readonly string ErrorUp = "ErrorUp";
 
public static readonly string ErrorDown = "ErrorDown";
 
public static readonly string Value = "Value";

The CreatePoint implementation for this series creates a Path as follows:

protected override FrameworkElement CreatePoint(IDataPoint dataPoint)
{
  var lineGeometry = BuildGeometry(dataPoint);
 
  Path line = new Path();
  line.Stroke = new SolidColorBrush(Colors.Black);
  line.Fill = new SolidColorBrush(Colors.Gray);
  line.StrokeThickness = 1.0;
  line.StrokeLineJoin = PenLineJoin.Bevel;
  line.Data = lineGeometry;
  line.SetValue(ZoomCanvas.IsScaledPathProperty, true);
 
  return line;
}

The BuildGeometry method does most of the work, extracting the values from the IDataPoint, transforming them (via the axis) to the required coordinate system, then creating a suitable geometry:

/// <summary>
/// Creates the geometry for the given datapoint
/// </summary>
private PathGeometry BuildGeometry(IDataPoint dataPoint)
{
  var halfWidth = SuggestedPointWidth * WidthFactor;
 
  // obtain the data values
  var topDataValue = dataPoint[ErrorUp] as IComparable;
  var middleDataValue = dataPoint[Value] as IComparable;
  var bottomDataValue = dataPoint[ErrorDown] as IComparable;
 
  // convert to a the required render coordinates
  double topRenderPos = YAxis.GetDataValueAsRenderPositionWithoutZoom(topDataValue);
  double middleRenderPos = YAxis.GetDataValueAsRenderPositionWithoutZoom(middleDataValue);
  double bottomRenderPos = YAxis.GetDataValueAsRenderPositionWithoutZoom(bottomDataValue);
 
  double xMiddleRenderPos = XAxis.GetDataValueAsRenderPositionWithoutZoom(dataPoint.X);
  double xRightRenderPos = xMiddleRenderPos - halfWidth;
  double xLeftRenderPos = xMiddleRenderPos + halfWidth;
 
  // build a suitable gemoetry
  PathGeometry lineGeometry = new PathGeometry();
 
  PathFigure upperVerticalLine = CreateLineFigure(
    new Point(xMiddleRenderPos, middleRenderPos - halfWidth),
    new Point(xMiddleRenderPos, topRenderPos));
  lineGeometry.Figures.Add(upperVerticalLine);
 
  PathFigure lowerVerticalLine = CreateLineFigure(
    new Point(xMiddleRenderPos, bottomRenderPos),
    new Point(xMiddleRenderPos, middleRenderPos + halfWidth));
  lineGeometry.Figures.Add(lowerVerticalLine);
 
  PathFigure upperBar = CreateLineFigure(
    new Point(xLeftRenderPos, topRenderPos),
    new Point(xRightRenderPos, topRenderPos));
  lineGeometry.Figures.Add(upperBar);
 
  PathFigure lowerBar = CreateLineFigure(
    new Point(xLeftRenderPos, bottomRenderPos),
    new Point(xRightRenderPos, bottomRenderPos));
  lineGeometry.Figures.Add(lowerBar);
 
  PathFigure center = CreateLineFigure(
    new Point(xMiddleRenderPos - halfWidth, middleRenderPos),
    new Point(xMiddleRenderPos, middleRenderPos + halfWidth),
    new Point(xMiddleRenderPos + halfWidth, middleRenderPos),
    new Point(xMiddleRenderPos, middleRenderPos - halfWidth)
  );
  lineGeometry.Figures.Add(center);
 
  return lineGeometry;
}
 
/// <summary>
/// Create a line figure that connects the given points
/// </summary>
private PathFigure CreateLineFigure(params Point[] points)
{
  // add all the points (except the first)
  var pointCollection = new PointCollection();
  foreach (var point in points.Skip(1))
  {
    pointCollection.Add(point);
  }
 
  // create a figure, using the first point as the StartPoint.
  return new PathFigure()
  {
    IsClosed = true,
    StartPoint = points.First(),
    Segments = new PathSegmentCollection()
    {
      new PolyLineSegment
      {
        Points = pointCollection
      }
    }
  };
}

We can now create an instance of this series in XAML:

<vis:Chart x:Name="chart">
  <vis:Chart.Series>
    <local:ErrorBarSeries/>
  </vis:Chart.Series>
</vis:Chart>

Supplying data to the chart via MultiValuedDataPoint as follows:

public MainPage()
{
  InitializeComponent();
 
  var data = new DataSeries<double, double>();
  data.Add(CreatePoint(-195, 1.4, 0.2));
  data.Add(CreatePoint(0, 62.2, 9.3));
  data.Add(CreatePoint(20, 70.4, 6.5));
  data.Add(CreatePoint(100, 77.4, 1.9));
 
  chart.Series[0].DataSeries = data;
}
 
private MultiValuedDataPoint<double, double> CreatePoint(double x, double y, double error)
{
  var point = new MultiValuedDataPoint<double, double>(x,
    new Dictionary<object, double>()
    {
      { ErrorBarSeries.ErrorUp, y + error },
      { ErrorBarSeries.ErrorDown, y - error },
      { ErrorBarSeries.Value, y }
    });
  return point;
}

This results in the following chart:

Binding to a Multi-valued Series

In the previous example we created instances of MultiValuedDataPoint, a Visiblox type for representing multi-valued points. As an alternative, we can create model objects to represent each point, rendering them in the chart via databinding.

We first modify the code to create a collection of Measurement instances (a simple model object that implements INotifyPropertyChanged):

public MainPage()
{
  InitializeComponent();
 
  var data = new ObservableCollection<Measurement>();
  data.Add(CreateMeasurement(-195, 1.4, 0.2));
  data.Add(CreateMeasurement(0, 62.2, 9.3));
  data.Add(CreateMeasurement(20, 70.4, 6.5));
  data.Add(CreateMeasurement(100, 77.4, 1.9));
  this.DataContext = data;    
}
 
private Measurement CreateMeasurement(double x, double y, double error)
{
  return new Measurement()
    {
      XValue = x,
      YValue = y,
      YValueErrorUp = y + error,
      YValueErrorDown = y - error
    };
}

The markup for the chart is modified to use a BindableDataSeries, with bindings specified for the various component of the error bar series. Also, the ItemsSource of the BindableDataSeries is bound to the inherited DataContext:

<local:ErrorBarSeries>
  <local:ErrorBarSeries.DataSeries>
    <vis:BindableDataSeries ItemsSource="{Binding}"
                            XValueBinding="{Binding XValue}">
      <vis:BindableDataSeries.YValueBindings>
        <vis:YValueBinding YValueKey="Value" Binding="{Binding YValue}"/>
        <vis:YValueBinding YValueKey="ErrorUp" Binding="{Binding YValueErrorUp}"/>
        <vis:YValueBinding YValueKey="ErrorDown"  Binding="{Binding YValueErrorDown}"/>
      </vis:BindableDataSeries.YValueBindings>              
    </vis:BindableDataSeries>
  </local:ErrorBarSeries.DataSeries>
</local:ErrorBarSeries>

We can also display our data in a DataGrid, allowing us to manipulate the values (not that I condone manipulation of scientific data!), with the changes being reflected in the chart:

<sdk:DataGrid Grid.Row="1"
              x:Name="grid"
              ItemsSource="{Binding}"/>

This gives us the following application:

You can edit the values, with the changes reflected immediately in the chart above.

You can download the sourcecode for the above example here: VisibloxErrorBarSeries.zip

Regards, Colin E.

This blog post provides an implementation of IPagedCollectionView which allows paging of data from the server. An IPagedDataSource is introduced that allows any paged data source to be plugged in, with the standard controls such as DataPager making it easy to create paging applications.

With web-based applications, bandwidth constraints often mean that when querying large datasets, the results must be paged, i.e. split into discrete pages each containing a small number of results, with an API available for moving forwards / backwards or to a specific page. There are numerous APIs available on the web that expose this type of interface, for example:

• Twitter Search API
• Nestoria API for searching houses for sale
• Any of the OData producers

With paging being a common application requirement, Silverlight has the functionality to deal with this scenario built-in. The System.Windows.Data assembly contains the IPagedCollectionView interface, which defines the following methods, properties and events, allowing navigation of paged data:

The System.Windows.Controls assembly contains a DataPager control, that collaborates with this interface to provide a UI for paging the dataset. Simply set the Source property of this control to an instance of IPagedCollectionView and your user can page through the data:

NOTE: The Source property of DataPager is of type IEnumerable, which is a little odd, because it doesn’t really need to enumerate the collection of items being displayed. Internally it probes the object you supply as the Source to see if it implements IPagedCollectionView, and if it does, the control becomes ‘active’.

This control gives you quite a bit of functionality for free, the buttons become enabled / disabled based on whether navigation forwards / backwards is possible. It respects the CanChangePage property, computes the total number of pages etc …

So, how do you make use of this interface and control?

The System.Windows.Data assembly also contains a concrete implementation of the paging interface, PagedCollectionView. This class gives much more than just paging, it also implements grouping, sorting and filtering of a source collection (IEnumerable). To make use of this class simply construct an instance based on your collection of data and use that as your DataContext:

List<MyDataObject> sourceCollection = ParseData(serverResponse);
var collectionView = new PagedCollectionView(sourceCollection);
this.DataContext = collectionView;

The problem is PagedCollectionView allows you to sort, group and page a collection of data that is already held in memory. What I want to do, and what I think is a more common use-case, is page data that is supplied by the server. I don’t want to have to fetch all the data up-front then page it on the client, this would defeat the object of paging in the first place … to improve performance!

I discovered that there is an IPagedCollectionView implementation as part of RIA Services that provides this functionality, the DomainCollectionView. However, if I want to page data form a simple JSON formatted web service, adding a dependency to RIA Services seems like overkill. So I decided to create my own simple implementation of this interface.

In order to make a generic/ re-useable implementation of this paging interface, I first created an interface that would act as the source of the data:

/// <summary>
/// Defines a source of data that can be paged.
/// </summary>
public interface IPagedDataSource<TDataType>
{
  /// <summary>
  /// Asynchronously returns the data for the given page
  /// </summary>
  void FetchData(int pageNumber, Action<PagedDataResponse<TDataType>> responseCallback);
}
 
/// <summary>
/// The items returned as a result of a paged data request.
/// </summary>
public class PagedDataResponse<TDataType>
{
  /// <summary>
  /// The items contained within the requested page
  /// </summary>
  public List<TDataType> Items { get; set; }
 
  /// <summary>
  /// The total count of all available items
  /// </summary>
  public int TotalItemCount { get; set; }
}

This interface is very simple, having a single method that fetches data for the given page. The result is returned asynchronously, providing both the items within the given page and the total item count.

My paging collection view extends ObservableCollection and takes an instance of IPagedDataSource in its constructor:

public class ServerSidePagedCollectionView<T> : ObservableCollection<T>,
  IPagedCollectionView
{
  IPagedDataSource<T> _pagedDataSource;
 
  public ServerSidePagedCollectionView(IPagedDataSource<T> pagedDataSource)
  {
    _pagedDataSource = pagedDataSource;
  }
 
  ...
}

As an aside, aren’t generics great?

The various properties defined in IPagedCollectionView (CanChangePage, TotalPages, etc …) are implemented as standard field-backed properties that notify changes via INotifyPropertyChanged which is inherited via ObservableCollection, I am not going to show them here.

The various methods that permit navigation are all implemented using the same pattern:

public bool MoveToFirstPage()
{
  RefreshData(0);
  return true;
}
 
public bool MoveToLastPage()
{
  RefreshData(TotalPages - 1);
  return true;
}    
 
public bool MoveToNextPage()
{
  RefreshData(PageIndex + 1);
  return true;
}
 
public bool MoveToPage(int pageIndex)
{
  RefreshData(pageIndex);
  return true;
}
 
public bool MoveToPreviousPage()
{
  RefreshData(PageIndex - 1);
  return true;
}

With the RefreshData method doing all the work, it is the only method that uses the supplied IPagedDataSource interface and is shown below:

/// <summary>
/// Fetches the data for the given page
/// </summary>
private void RefreshData(int newPageIndex)
{
  // set the pre-fetch state
  CanChangePage = false;
  OnPageChanging(newPageIndex);
 
  _pagedDataSource.FetchData(newPageIndex, response =>
    {
      // process the received data
      DataReceived(response);
 
      // set the post-fetch state
      PageIndex = newPageIndex;
      OnPageChanged();
      CanChangePage = true;
    });
}

With the simple implementation of IPagedCollectionView given above I can now page data from a range of web services by simply implementing IPagedDataSource. For example, to page data from NetFlix you can use the following implementation:

/// <summary>
/// A paged NetFlix movies search datasource.
/// </summary>
public class NetFlixDataSource : IPagedDataSource<SyndicationItem>
{
  private string _searchString;
 
  private int _pageSize = 10;
 
  public NetFlixDataSource(string searchString)
  {
    _searchString = searchString;
  }
 
  public void FetchData(int pageNumber, Action<PagedDataResponse<SyndicationItem>> responseCallback)
  {
    WebClient client = new WebClient();
 
    // create a url for fetching movies with a name that contains the search string
    string url = string.Format("http://odata.netflix.com/Catalog/Titles?"
      + "$top={0}&$orderby=Name&$select=Name&$inlinecount=allpages&$skip={1}&$filter=indexof(Name,'{2}') ne -1",
      _pageSize, pageNumber * _pageSize, _searchString);
 
    client.DownloadStringCompleted += (s, e) =>
    {
      // parse the response using SyndaicationFeed
      XmlReader reader = XmlReader.Create(new StringReader(e.Result));
      SyndicationFeed feed = SyndicationFeed.Load(reader);
 
      // locate the item count 
      var itemCount = feed.ElementExtensions[0].GetObject<XElement>().Value;
 
      // invoke the response callback
      responseCallback(new PagedDataResponse<SyndicationItem>()
      {
        Items = feed.Items.ToList(),
        TotalItemCount = int.Parse(itemCount)
      });
    };
    client.DownloadStringAsync(new Uri(url));
  }
}

As you can see, this simple implementation of our paging data source constructs the required URL based on the search string and request page number. It also uses the ‘syndication’ APIs which are able to parse the response from the NetFlix OData APIs.

To test out this implementation of the paged search interface I have created a very simple movie search application. The view model for this application has a SearchString property, exposes the results as SearchResults property and has a single command which initiates a new search. The important parts of this class are shown below:

/// <summary>
/// Gets the paged search results
/// </summary>
public ServerSidePagedCollectionView<SyndicationItem> SearchResults
{
  get
  {
    return _searchResults;
  }
  private set
  {
    SetField(ref _searchResults, value, "SearchResults");
  }
}
 
/// <summary>
/// Gets a command which executes the search
/// </summary>
public ICommand ExecuteSearchCommand
{
  get
  {
    return new DelegateCommand(() =>
    {
      SearchResults = new ServerSidePagedCollectionView<SyndicationItem>(
        new NetFlixDataSource(SearchText));
    });
  }
}

When ExecuteSearchCommand is invoked, we create a new ServerSidePagedCollectionView, providing it with the NetFlix data source. From here on, the ServerSidePagedCollectionView is responsible for the paging of data.

The view is as follows:

<Grid x:Name="LayoutRoot" Background="LightGray"
      Width="400" Height="360">
  <Grid.RowDefinitions>
    <RowDefinition Height="Auto"/>
    <RowDefinition Height="Auto"/>
    <RowDefinition Height="Auto"/>
  </Grid.RowDefinitions>
 
  <StackPanel Orientation="Horizontal"
              Margin="4">
    <TextBox Text="{Binding SearchText, Mode=TwoWay}"
                Width="150"/>
    <Button Command="{Binding ExecuteSearchCommand}"
            Content=" Search Movies ..."
            Margin="5,0,0,0"/>
  </StackPanel>
 
  <ItemsControl ItemsSource="{Binding SearchResults}"
                Grid.Row="1"
                Height="300"
                ItemTemplate="{StaticResource MovieTemplate}">
    <ItemsControl.ItemsPanel>
      <ItemsPanelTemplate>
        <StackPanel Orientation="Vertical"/>
      </ItemsPanelTemplate>
    </ItemsControl.ItemsPanel>
  </ItemsControl>
  <Rectangle Fill="White" Grid.Row="1"
            Opacity="0.5"
            Visibility="{Binding Path=SearchResults.CanChangePage, Converter={StaticResource BoolToVisibilityConverter}}"/>
 
  <sdk:DataPager  PageSize="10" 
                  Source="{Binding SearchResults}"
                  Grid.Row="2"/>
 
</Grid>

The DataPager simply binds to the SearchResults as does the ItemsControl. I have also added a Rectangle element which grays-out the current search results when a new page is being fetched.

You can see the application in action below:

So in summary, by implementing IPagedCollectionView with a pluggable datasource, IPagedDataSource, it is possible to very quickly and easily create an application that pages data from the server.

You can download the full sourcecode here: PagedCollectionViewExample.zip

Regards, Colin E.

This blog post looks at the new concept of ‘transitions’ that WinRT, within Windows 8, introduces. This concept makes it very easy for you to create a fluid and interactive UI without going anywhere near storyboards!

I have to admit it, I am a big fan of the Metro Design Language; the clean chrome-free graphics, combined with typography inspired by signage and designed for maximum legibility, has given Windows Phone 7 an instantly recognisable style. However, whilst Silvelight applications developed for Windows Phone 7 look like the native metro phone apps, they do not move like them. Motion is an important part of metro, with one of the tenants being that it is “Alive In Motion”. This lead me to publish a multi-part blog series, called Metro In Motion, which provided implementations of the various native animations and transitions (1, 2, 3, 4, 5, 6 & 7).

Windows 8 again is built using the Metro Design Language, and again the tools make it easy for you to create an application which has the Metro look. However, where Windows 8 differs from Windows Phone 7 is that developer APIs make it very easy for you to create applications that move like a Metro application. WinRT introduces a new XAML concept, transitions, which is the focus of this blog post.

I was inspired to explore transitions after watching John Papa’s excellent //build/ session “Stand out with styling and animation in your XAML app”, I would thoroughly encourage you to watch it!

I have a (very shaky) video of the demo code included with this blog post below:

With WinRT UIElement, the base class for any element that is added to the visual tree (UI), has a Transitions property. You can use this to specify a collection of transitions for an individual element:

<Rectangle>
    <Rectangle.Transitions>
        <TransitionCollection>
            <RepositionThemeTransition/>
            <EntranceThemeTransition/>
        </TransitionCollection>
    </Rectangle.Transitions>
</Rectangle>

Each transitions is an animation that the WinRT framework plays in response to certain ‘events’. We’ll take a look at the various transitions in turn…

EntranceThemeTransition

When elements are added to the UI they appear instantly (as you might expect), however, with the EntranceThemeTransition elements gracefully fade and slide into location. This animation will fire whenever your element is added to the UI, this could be as a result of:

• The application first loading, any element with this transitions specified will animate when the application starts.
• The element being added programatically or as a result of binding (e.g. within a bound list)
• The element being added as a child of another element

Basically, you can rely on this animation being fired whene your element is first visible to the user.

ChildrenTransitions

If you add multiple elements to the UI at the same time, or a UserControl is loaded that contains a number of animated elements, their EntranceThemeTransition animations will fire at the same time. However, if you have a panel that contains a number of elements, you can make them appear in sequence by adding the EntranceThemeTransition to the ChildrenTransitions property of the panel. For example, any element added to the WrapGrid defined below, will animate as it appears:

<WrapGrid>
    <WrapGrid.ChildrenTransitions>
        <TransitionCollection>
            <EntranceThemeTransition/>
        </TransitionCollection>
    </WrapGrid.ChildrenTransitions>
</WrapGrid>

Here we can see nine rectangles being animated as they slide into location:

The animations are fired in sequence, no matter how the elements are added to the panel. For example, if you add a couple of elements in code-behind, they will appear in sequence.

(As an aside, this is really quite cool, I can imagine how I might implement the animations on individual elements in WPF / Silverlight, however, the child-transitions concept would be vary hard to implement!)

One thing to note is that the framework fires the animations in the order that elements appear in the Panel.Children collection, this is not necissarily the order they appear in the UI. For example, the following example shows elements added in a Grid, where the elements are defined in a random order within XAML:

This doesn’t look quite so good!

RepositionThemeTransition

When you change the positions of an element, either directly or as a result of its parent layout changing, it will move into its new location instantly. By adding a RepositionsThemeTransition, the WinRT framework will animate the element as its moves location.

A few things I have observed:

• The RepositionThemeTransition is not fired when you apply a RenderTransform to an element, possibly because transitions are applied via render transforms
• The RepositionThemeTransition is not fired when an elements position within a Canvas changes. This is probably because Canvas.Left and Canvas.Top do not have any impact on layout.
• This transition, and none of the others discussed in this blog post, work when the elements are hosted within a FlipView (not sure why, this feels like a bug)

Again, if you add a RepositionThemeTransition to the children of a panel via ChildrenTransitions, the animations are fired in sequence. In the below image an element has been removed from the top of a WrapGrid:

(Trust me – this looks much better in action! try running the sample code with this blog-post)

One point of interest, you can simplify the XAML for adding ChildrenTransitions when using an ItemsControl (Or ListBox, GridView or other subclasses) from the following:

<ItemsControl Grid.Row="1"
                x:Name="itemsTwo">
    <ItemsControl.ItemsPanel>
        <ItemsPanelTemplate>
            <WrapGrid>
                <WrapGrid.ChildrenTransitions>
                    <TransitionCollection>
                        <RepositionThemeTransition/>
                    </TransitionCollection>
                </WrapGrid.ChildrenTransitions>
            </WrapGrid>
        </ItemsPanelTemplate>
    </ItemsControl.ItemsPanel>
</ItemsControl>

By using the ItemContainerTransitions property as follows:

<ItemsControl Grid.Row="1"
                x:Name="itemsTwo">
    <ItemsControl.ItemContainerTransitions>
        <TransitionCollection>
            <RepositionThemeTransition/>
        </TransitionCollection>
    </ItemsControl.ItemContainerTransitions>
    <ItemsControl.ItemsPanel>
        <ItemsPanelTemplate>
            <WrapGrid/>
        </ItemsPanelTemplate>
    </ItemsControl.ItemsPanel>
</ItemsControl>

This property specifies a collection of transitions that will be set on the item-container.

AddDeleteThemeTransition

This transitions is intended for use with panels, it animates the process of adding / removing elements. This transitions is added to the ChildrenTransitions (or ItemContainerTransitions) just like the others. As items are added, they fade into place, and as they are removed they slide out and the other elements reposition themselves. One thing that is really cool about this transitions is that it ‘understand’ the layout of the panel.

Here you can see elements being repositioned within a WrapGrid when the first element is being removed. You can see that the elements are moved in batches based on their row / column:

Very cool!

ContentThemeTransition

The final transition I want to look at is the ContentThemeTransition. For those of you who have worked with Silverlight or WP7, this provides the same functionality as the popular TransitioningContentControl from the Slverlight toolkit – now this feature is delivered by the framework itself (at last!)

To enable this, add a ContentThemeTransition to the ContentTransitions property (note, not, the Transitions property!).

<ContentControl x:Name="contentCtrl>
    <ContentControl.ContentTransitions>
        <TransitionCollection>
            <ContentThemeTransition HorizontalOffset="200"/>
        </TransitionCollection>
    </ContentControl.ContentTransitions>
</ContentControl>

Whenever the content of this control is changed, either by setting the Content property directly, or as a result on the databound content changing, the new content gracefully slides into place.

Conclusions

Whilst WinRT borrows much from Silverlight and WPF, it brings some great new controls and features and transitions are probably one of my favourite new features. They really help you create fluid applications with minimum effort.

I have covered all the theme-transitions except one, ReorderThemeTransition, I have not yet found out how to use this transition, I think this might be because of a lack of sorting / filtering of collections in WinRT. This is probably functionality that will be added at a later date.

You can download the full sourcecode for this blog post: WinRTTransitions.zip

Regards, Colin E

In this blog post I look at the new application lifecycle model that Windows Phone 7.1 (Mango) introduces, and show how to handle the various lifecycle events in a simple MVVM application.

In a previous blog post I described the development of a simple Windows Phone 7 application using the Model-View-ViewModel (MVVM) pattern and how to handle application lifecycle events, specifically tombstoning. In this blog post I will look at updating this sample for Windows Phone 7.1 (Mango) to handle fast-app switching and the new Dormant state.

As an aside, I have bumped into a number of developers who were under the impression that Mango removes the need to tombstone. I’m afraid that this is not the case!

Introduction and a Recap

The WP7 application lifecycle model is designed to allow the user to move fluidly between applications whilst minimising the memory that these applications consume. Neither WP7 or WP7.1 (Mango) allow true multi-tasking, where more than one application is running at the same time. Instead, they employ a number of techniques to give the illusion of multi-tasking. As a developer you are exposed to this via the application lifecycle.

The WP7 (pre-Mango) application lifecycle, with the events that are fired for each transition, is illustrated below:

You can see the tasks that you must perform under each state transition.

When the user pressed the Start button, your application stops running and becomes tombstoned. It is your responsibility to save your application state such that when the user pressed the back-button (navigating the back-stack) to return to your application, it is in the same state as when they left it. This involves saving both the state of your application logic, within the application PhoneApplicationService.State dictionary and the UI state (e.g list scroll position) within the PhoneApplicationPage.State dictionary for each page. I described how you can achieve this in my previous blog post. I also want to point out that the rather tricky task of saving UI state can be made much simpler by using things like Matt Lacey’s popular Tombstoning Helper utilities.

One other thing that the Execution Model Overview on MSDN does not make terribly clear is that the back-stack has a limited size. What this means is that your tombstoned application state will not necessarily be re-activated. You can test this by running your application with the debugger attached, if you create a long enough back-stack (by repeatedly hitting the Start button and starting a new application), your debugging session will eventually terminate. This occurs when your application state has been pushed off the back-stack.

The upshot of this is that when your application is tombstoned you must save your state to isolated storage as well as the State dictionary (because your application might never get closed). Although, as it is recommended that your application tombstones swiftly, you might want to store application state to isolated storage at more regular intervals.

Windows Phone 7.1 Lifecycle

Windows Phone 7.1 (Mango) introduces a much more convincing illusion of multi-tasking, where the user can press and hold the back-button to rapidly switch between a small number of apparently concurrently running applications. However, again this is not true multitasking.

To achieve this, WP7.1 introduces a new state in the application lifecycle, the Dormant state:

When you application is in a Dormant state it is still in memory, however it is not executing. This allows the phone to re-start your application much more rapidly than when it is in a tombstoned state.

The phone can only store a limited number of dormant applications, as a result it might choose to move your application from a dormant to a tombstoned state. You do not receive any notification that this has occurred. However, the tombstoning and re-activiation process is the same as that for WP7.0, where you re-activate your application from the data saved in the State dictionary.

Again, there is always the possibility that your tombstoned data will be pushed out of the back-stack and lost.

Notice that there have not been any new events added to indicate that your application has returned from a Dormant state, your application will always receive Activated event when it is restarted regardless of whether it was dormant or tombstoned. This is good news, because it is backwards compatible with WP7.0.

Handling the Dormant State

So how do you handle this new state in your application? In order to maintain backwards compatibility you don’t strictly have to, however it is actually very simple to do.

The event arguments passed to the Activated event now have a new IsApplicationInstancePreserved argument which is true if your application has been re-started from a dormant state and false if it has been restarted from a tombstoned state. If this argument returns true, you simply do nothing! This ensures that you do not perform any redundant actions and helps your application restart faster.

The code below is all of the lifecycle code (apart from per-page UI state) that my MVVM example application contains. You can see that the code for a re-activated dormant state does nothing.

// 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)
{
  Debug.WriteLine("Launching");
 
  LoadViewModelFromIsolatedStorage();
 
  // if the view model is not loaded, create a new one
  if (ViewModel == null)
  {
    ViewModel = new FeedViewModel();
    ViewModel.Update();
  }
 
  // set the frame DataContext
  RootFrame.DataContext = ViewModel;
}
 
// 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)
{
  if (e.IsApplicationInstancePreserved)
  {
    Debug.WriteLine("Activated From Dormant State");
  }
  else
  {
    Debug.WriteLine("Activated From Tombstoned State");
 
    LoadViewModelFromAppState();
 
    RootFrame.DataContext = ViewModel;
  }      
}
 
// 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)
{
  Debug.WriteLine("Deactivated");
  SaveViewModelToAppState();
  SaveViewModelToIsolatedStorage();
}
 
// 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)
{
  Debug.WriteLine("Closing");
  SaveViewModelToIsolatedStorage();
}
 
private void SaveViewModelToAppState()
{
  PhoneApplicationService.Current.State[ModelKey] = ViewModel;
}
 
private void LoadViewModelFromAppState()
{
  if (PhoneApplicationService.Current.State.ContainsKey(ModelKey))
  {
    ViewModel = PhoneApplicationService.Current.State[ModelKey] as FeedViewModel;
  }
}
 
private void LoadViewModelFromIsolatedStorage()
{
  // load the view model from isolated storage
  using (var store = IsolatedStorageFile.GetUserStoreForApplication())
  using (var stream = new IsolatedStorageFileStream("data.txt", FileMode.OpenOrCreate, FileAccess.Read, store))
  using (var reader = new StreamReader(stream))
  {
    if (!reader.EndOfStream)
    {
      var serializer = new XmlSerializer(typeof(FeedViewModel));
      ViewModel = (FeedViewModel)serializer.Deserialize(reader);
    }
  }
}
 
private void SaveViewModelToIsolatedStorage()
{
  // persist the data using isolated storage
  using (var store = IsolatedStorageFile.GetUserStoreForApplication())
  using (var stream = new IsolatedStorageFileStream("data.txt",
                                                    FileMode.Create,
                                                    FileAccess.Write,
                                                    store))
  {
    var serializer = new XmlSerializer(typeof(FeedViewModel));
    serializer.Serialize(stream, ViewModel);
  }
}

Debugging Dormant and Tombstoned state

Because the application now has a couple of states that it can be in when it is not running, you need to employ a few tricks to be able to force the application into these states while developing. Typically the emulator will always place your application into a dormant state when you hit the Start button.
The fast-app switch UI is not enabled on the emulator by default, however you can enable it with a bit of hackery as described on this forum thread.

So, if your application always moves into a dormant state, how do you test your tombstoning code? Fortunately there is a build setting which you can enable which will ensure that your application is always tombstoned rather than placed in a dormant state:

You should test your application with this setting enabled and disabled to ensure that it accommodates tombstoning and dormant state.

I hope this blog post has helps understand the slightly complex application lifecycle that Mango introduces. It is clear that this delivers the best performance to the user, however it is a little complex for the developer!

You can download my updated MVVM example here: WindowsPhoneMVVMExample.zip

Regards, Colin E.