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 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.

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

This article show the step-by-step development of a Windows Phone 7 HTML5 application using PhoneGap. It also looks at how viable this approach is for cross-platform mobile development.

Introduction … and Why HTML5?

Windows Phone 7 allows native application development in both Silverlight and XNA, both of which are mature framework with excellent tool support. So why would you want to develop an application with HTML5 / JavaScript instead? Personally I think the only viable reason for doing this (other than just for fun!) is to develop a cross-platform mobile application. HTML5 / JavaScript applications are platform agnostics, running on Android, iPhone, BlackBerry and now with the Mango WP7 supporting IE9, WP7.
In this blog post I will describe how I implemented the application shown below, which allows you to search properties for sale, using the GPS and various webservices to find and geocode your current location:

The basic concept behind HTML5 applications is that your native application is simply a full-screen WebBrowser, which hosts your JavaScript application logic. In order to achieve this in practice, you need to package the HTML, JavaScript, CSS and other resources into a XAP file, then use the WebBrowser APIs to pass messages between your JavaScript code and the native APIs in order to access the phone features such as the camera, accelerometer etc …

A few people have developed frameworks to assist in development of HTML5 apps, for example the HTML App Host Framework. However, the one I would recommend is PhoneGap, as the name implies, this framework fills the gap between your JavaScript code and the native phone features. PhoneGap is an open source project that has been running for a couple of years now; currently a large range of phones are supported, meaning that you are guaranteed the same JavaScript APIs for accessing the phone features on Android, iPhone, BlackBerry and more.

PhoneGap support for Windows Phone 7 was initiated by Matt Lacey, who created an initial implementation of the PhoneGap APIs. More recently Nitobi (who run PhoneGap), announced an official beta release, which they have worked on in conjunction with Microsoft.

Getting Started With PhoneGap

PhoneGap has a project template which will help you create an initial “Hello World” style application. You can get started by following these steps:

1.  Download the WP7 PhoneGap from https://github.com/phonegap/phonegap-wp7
2.  Copy the file GapAppStarter.zip, which contains the project template, to the folder
•  \My Documents\Visual Studio 2010\Templates\ProjectTemplates\
3.  Create a new project using the GappAppStart project template. I could not locate this template within the tree of ‘Installed Templates’, so used the search function. See the image below.
4.  Add the framework\WP7GapClassLib.csproj project to your solution and add a reference to this project.
5. Build and run!

If you followed these steps correctly, you should see the following:

Dissecting the Example App

The example application is a bit more complex than an equivalent Silverlight ‘Hello World’ app, so we’ll look at it in some detail …

The www folder contains the HTML5 application sourcecode, here you place images, HTML, JavaScript, and CSS. These files are marked as ‘content’ and will be included within the XAP file with the same directory structure. The project contains a GapSourceDictionary.xml file, this XML file lists all the HTML application resources. When the application starts, this XML file is read, and each file is added to isolated storage so that it can be served by the WebBrowser control:

<GapSourceDictionary>
  <FilePath Value="www/index.html" /> 
  <FilePath Value="www/phonegap.1.0.js" /> 
  <FilePath Value="www/master.css" /> 
</GapSourceDictionary>

The MainPage.xaml, which is the Silverlight UI for the application contains an instance of PGView:

<phone:PhoneApplicationPage 
    ... xmlns:my="clr-namespace:WP7GapClassLib;assembly=WP7GapClassLib">
    <Grid>
      <my:PGView/>
    </Grid>
</phone:PhoneApplicationPage>

PGView is defined in the WP7GapClassLib, it is a UserControl which hosts a WebBrowser, and contains the code that bridges between the PhoneGap JavaScript APIs and the WP7 .NET APIs. On startup it will load your files into isolated storage and navigate the browser control to “www/index.html” (although this will probably be configurable in future).

The index.html file from the template project is shown below (minus a few un-important parts):

<!doctype html>
<html>
  <head>
    <meta name="viewport" content="width=320; user-scalable=no" />    
      <script type="text/javascript" charset="utf-8" src="phonegap.1.0.js"></script>       
      <script type="text/javascript">
        function init()
        {
          document.addEventListener("deviceready",onDeviceReady,false);
        }
 
        // once the device ready event fires, you can safely do your thing! -jm
        function onDeviceReady()
        {
          document.getElementById("welcomeMsg").innerHTML += "PhoneGap is ready!";
        }
      </script>
 </head>
 <body onLoad="init();">
  <h1>Hello PhoneGap</h1>
  <div id="welcomeMsg"></div>
 </body>
</html>

The important parts to note here are, firstly the viewport metadata, which relates to the complications that small mobile screens present to layout, resulting in the need for a separate layout viewport and visual viewport, as described in the article “a tale of two viewports“. Here the width is set to 320px, so each pixel-width in our HTML is two pixels on screen. I prefer one-to-one correlation, so would change this to the physical phone dimensions. The “user-scalable=no” should prevent the user from being able to pinch-zoom the page, unfortunately on my (mango) phone, this doesn’t seem to be working. This is a shame, because it really spoils the illusion of this being an application rather than a web-page.

When the DOM is loaded, the init function is invoked, which adds a handler for the deviceready event. When this has been fired, it is safe to use the PhoneGap APIs. This example does not actually use any of the APIs, but you can make a simple change to get the phone name via device.name for example to verify that PhoneGap really is working.
So how does the JavaScript / Silverlight bridge work? The PhoneGap.js file communicates via window.external.Notify, which raises the ScriptNotify event within the WebBrowser control. Encoded strings are sent to the PGView control which uses the command pattern to identify the class which performs the required function, and executes it.

Creating the Property Search Application

Following the principles of Unobtrusive JavaScript, where presentation is separated from logic, the I have moved application logic into a file propertySearch.js (adding this to GapSourceDictionary.xml of course). The HTML has the following markup, a simple form that can be used to input the string to search for:

<h1 id="welcomeMsg">Find A Home</h1>
<form id="form" action="#">
  <input type="text" id="searchText"/>
  <input type="submit" id="searchButton" value="Go" />
  <input type="button" id="getLocationButton" value="My Location"/>
</form>

The event handlers are wired up as follows:

$(document).ready(function () {
  document.addEventListener("deviceready", onDeviceReady, false);
});
 
// phonegap is initialised
function onDeviceReady() {
  // verify that the phone is ready!
  $("#welcomeMsg").append("...");
 
  $("#form").submit(searchProperties);
  $("#getLocationButton").click(getGeolocation);
}

Note, I have also added jQuery to the project. The code which appends an ellipsis (…) to the title is a subtle indication that the deviceready event has fired. I found when using the emulator that often the JavaScript code within the page was not being executed at all, this seems to have nothing to do with the PhoneGap JavaScript code. Fortunately the code is always executed when deployed to a real device.

The search properties function is a simple AJAX call to the Nestoria APIs, using the jQuery ajax() function, which manages the JSONP process of dynamically adding a script tag to the DOM which fetches the required data.

var propertyTemplate = $("#propertyTemplate").template();
 
// searches for properties based on the current search text
function searchProperties() {      
  var query = "http://api.nestoria.co.uk/api?" +
                  "country=uk&pretty=1&action=search_listings&encoding=json&listing_type=buy" +
                  "&place_name=" + $("#searchText").val();
  $.ajax({
    dataType: "jsonp",
    url: query,
    success: function (result) {
 
      var resultsContainer = $("#resultsContainer");
      resultsContainer.empty();
      $.each(result.response.listings, function (index, property) {
        var $itemNode = $.tmpl(propertyTemplate, property).data("propertyData", property);
        $itemNode.appendTo(resultsContainer);
      });
    }
  });
 
  return false;
}

NOTE: The application uses the Nestoria UK APIs, so if you are trying it out in your emulator, set your location to somewhere in the UK!

I am using a jQuery templates to render each item. You can render an array of items via the tmpl() function, however, here I render each one individually, so that I can associate the raw JSON data for each property with the generated element via the jQuery data() function. This is rather like defining the DataContext for a Silverlight FrameworkElement.

<script id="propertyTemplate" type="text/x-jquery-tmpl">
  <li class="property" onClick="propertyClick(this); return false;">
    <div class="propertyContainer">
      <div class="thumbnailColumn">
        <img src="${thumb_url}" class="thumbnail"/>
      </div>
      <div class="detailsColumn">
        <div class="title">${title}</div>
        <div class="price">${price_formatted}</div>
      </div>
    </div>
  </li>
</script>

When a property is clicked, the following function is invoked, which locates the clicked DOM element, then extract the JSON property details via the data() function described above. This is used in conjunction with another template to render the property details:

// handle clicks on properties
function propertyClick(propertyNode) {
 
  // get the property
  var property = $(propertyNode).data("propertyData");
 
  // render the template
  $("#detailsContainer").empty();
  $.tmpl(propertyDetailsTemplate, property).appendTo("#detailsContainer");
 
  // switch pages
  showDetailsPage();
}

The template is shown here:

<script id="propertyDetailsTemplate" type="text/x-jquery-tmpl">
  <div>
    <h1>${price_formatted}</h1>
    <img src="${img_url}" class="propertyImage"/>			  
    <h2>${title}</h2>
    <div class="bedrooms">bedrooms: ${bedroom_number}</div>
    <div class="bathrooms">bathrooms: ${bathroom_number}</div>
    <div class="summary">${summary}</div>
  </div>
</script>

The navigation between pages is achieved by having the markup for both pages present in the DOM:

<body>
  <div class="page searchPage">
     ...
  </div>
  <div class="page detailsPage">
    ...
  </div>
</body>

The pages are styled to use absolute positioning:

div.page 
{
  position: absolute;
  width: 480px;  
}

We can then show / hide these pages by simply animating their CSS left property:

function showSearchPage() {
  $(".detailsPage").animate({ left: 480 }, 300, function () {
    $(this).hide();
  });
  $(".searchPage").show().animate({ left: 0 }, 300);
};
 
function showDetailsPage() {
  $(".detailsPage").show().animate({ left: 0 }, 300);
  $(".searchPage").animate({ left: -480 }, 300, function () {
    $(this).hide();
  });
};

It is worth noting that if the IE9 browser supported CSS3 transitions all of the above could have been done declaratively within CSS, unfortunately animations are not in the list of supported features. There is nothing wrong with jQuery animations, they have a very concise and simple syntax. However, CSS3 animation give the browser the option to use GPU acceleration, greatly improving performance. The webkit browsers on Android and iOS support this feature (using the –webkit prefix on the required CSS properties).

The current location is identified via navigator.geolocation.getCurrentPosition, using the Bing Maps REST APIs to geocode from a lat / long coordinate to a postcode:

// gets the current phone location
function getGeolocation() {
  navigator.geolocation.getCurrentPosition(function (position) {
    // geocode via Bing Maps
    var apiKey = "Ai9-KNy6Al-r_ueyLuLXFYB_GlPl-c-_iYtu16byW86qBx9uGbsdJpwvrP4ZUdgD";
    var query = "http://dev.virtualearth.net/REST/v1/Locations/" + position.coords.latitude +
                    "," + position.coords.longitude + "?jsonp=onGeocode&key=" + apiKey
 
    $.ajax({
      dataType: "jsonp",
      url: query
    });
  });
}
 
// handle the geocode results
function onGeocode(result) {
  // extract the 'outward' part of the postcode
  var postalCode = result.resourceSets[0].resources[0].address.postalCode;
  var codeSplit = postalCode.split(" ");
  if (codeSplit.length > 0) {
    $("#searchText").val(codeSplit[0]);
  }
}

Metro-style

The standard style for HTML controls doesn’t look that great, however, with a simple bit of CSS it is possible to re-create something similar to the WP7 Metro styles. Here I have copied some of the properties that are present in the Silverlight resource dictionaries:

body, input, div
{
  font-size: 22.667px; /* PhoneFontSizeMedium */
}
 
h2
{
  font-weight: normal;
  font-size: 32px; /* PhoneFontSizeLarge */
}
 
h1
{
  font-weight: normal;
  font-size: 42.667px; /* PhoneFontSizeExtraLarge */
}
 
input[type="button"], input[type="submit"]
{
  background: black;
  color: white;
  border-color: white;
  border-style: solid;
  padding: 4px 10px;
  border-width: 3px; /* PhoneBorderThickness */
  font-size: 25.333px; /* PhoneFontSizeMediumLarge */
}
 
input[type="button"]:active, input[type="submit"]:active
{
  background: white;
  color: black;
}
 
input[type="text"]
{
  width: 150px;
  padding: 4px;
}

ProgressBar

For a bit of fun I thought I’d try and create a HTML equivalent of the ‘trailing dots’ WP7 ProgressBar. With a simple bit of markup / CSS:

<div class="progress">
  <div class="pip"></div>
  <div class="pip"></div>
  <div class="pip"></div>
  <div class="pip"></div>
  <div class="pip"></div>
</div>

.progress div
{
  width: 5px;
  height: 5px;
  overflow: hidden;
  position: absolute;  
  background: green;
}
 
.progress
{
  position: relative;
  height:10px;
}

And some further jQuery animations, this time making use of the easing plugin:

function onDeviceReady() {
  ...
 
  // create an animation loop for the progress bar;
  startAnimation();
  var tid = setInterval(startAnimation, 3500);
}
 
function startAnimation() {
  var delay = 200;
  $(".pip").each(function () {
    animatePip($(this), delay);
    delay += 200;
  });
}
 
function animatePip(element, delay) {
  element.css("left", 0)
        .hide()
        .delay(delay)
        .show()
        .animate({ left: 240 }, { duration: 1000, easing: "easeOutSine" })
        .animate({ left: 480 }, { duration: 1000, easing: "easeInSine" });
}

We get something which approximates the WP7 progress bar:

(Note, sometimes the animation goes a bit crazy, try refreshing your browser to reset it!)

Again, my comments regarding CSS3 animations and GPU acceleration apply here also.

Tombstoning

As I have discussed in a previous blog post, tombstoning is a tricky task for WP7 developers. When your application is tombstoned you can save application state, page state – and the framework stores your back-stack URIs. It is your responsibility to re-start your application in the same state. Contrary to the belief of some developers I have talked to, Mango does not remove the need to tombstone, it just means that your application is likely to be tombstoned less often, with the suspended state being used to park your application while application switching.

So, how does tombstoning work with a PhoneGap HTML5 application? Good question! Implanting tombstoning would probably require some custom communication, outside of the PhoneGap APIs, that allows the JavaScript application to provide its current state to the Silverlight application that hosts this.

I would be very interested to hear from anyone who has solved this issue!

The Development Process

Attempting to develop JavaScript applications with the browser within the WP7 emulator is not a pleasant process. Any JavaScript errors, including simple parsing errors, typically result in the HTML being rendered but the scripts ignored. A much better approach is to run your HTML / JavaScript within a browser, this gives you access to the usual developer tools such as Firebug, or the built in Chrome / IE tools.

However, to do this, you need to mock the PhoneGap APIs. For my application, I found the following did the trick:

document.addEventListener = function (evt, handler, capture) {
  $("body").bind(evt, handler);
};
 
$(document).ready(function () {
  setTimeout(function () {
    $("body").trigger("deviceready");
  }, 100);
});

OK, I know what you are thinking, what about the geolocation code? Where is the mock for these PhoneGap APIs? The answer is that a number of the PhoneGap APIs are designed to exactly match the corresponding HTML5 specification. So for example, the PhoneGap geolocation API is exactly the same as the HTML5 geolocation APIs. For phones such as WP7 where the browser supports this HTML5 feature, PhoneGap does nothing, for phones that do not, PhoneGap provides an implementation (using the native APIs).

If the PhoneGap mock is so simple, you might be wondering, why use PhoneGap at all? Well, PhoenGap is still giving us a mechanism for packaging files into a XAP file in such a way that they can be rendered by the browser.

How cross-platform is this approach?

I would say that this approach is probably about as cross-platform as any HTML5 / JavaScript browser based application. There are always going to be cross-browser differences to overcome. As a test, I ran this code on an iPod Touch without any modification. The results are pretty good, although there are some quirks visible:

How viable are HTML5 applications?

It is clear that there is a growing trend towards cross-platform HTML5 applications, and Microsoft seem to be in support of this concept (even though the JavaScript / HTML5 Metro applications within Win8 are not cross-platform!). Microsoft has worked with Nitobi to create the PhoneGap for WP7, it was also announced at the //build/ conference that Microsoft would be working with jQuery Mobile to create a Metro theme for their mobile controls.

Currently, PhoneGap for WP7 is in beta, and it is certainly a little rough around the edges. This will no doubt improve in time. The large list of applications written with PhoneGap, certainly indicate that this is a viable solution for application development.

A larger obstacle for WP7 HTML5 applications is the IE9 browser that runs in the Mango phone. Whilst it has a pretty impressive list of HTML5 features supported, there are a couple of browser features / issues that I cannot resolve. These make it obvious to any user that this is in fact a browser application, totally spoiling the ‘illusion’

1. user-scalable=no – currently this setting seems to be ignored. This means that the user can pinch your application, which makes it feel like a web page. UPDATE Roy, in a comment below pointed out that the viewport parameters should be comma-separated. This almost solves the issue. The user can still pinch the view, which causes it to zoom, but when the pinch finishes, the viewport returns to the original scale. Not perfect, but better than nothing!
2. There doesn’t seem to be any way to turn of the gray shaded rectangle that appears over links when you click them. With applications that have dynamic content, this can look pretty ridiculous, with a gray rectangle lingering on screen while the page content changes underneath it. With the Android / iPhone browsers this can be turned off in CSS via -webkit-tap-highlight-color

Hopefully these limitations will be resolved. When they do, I am quite sure that HTML5 will be a viable technology for creating quality phone applications.

You can download the project sourcecode here: PhoneGapExample.zip

Regards, Colin E.

I have just published a new article on codeproject which describes the development of XAMLFinance, a cross-platform application for the desktop (WPF), web (Silverlight) and phone (WP7).

Head over to codeproject to read about the development of this application and download the sourcecode.

Regards, Colin E.

This blog post describes how to implement a conversation / messaging style application with Windows Phone 7. It covers how to style the speech bubbles and the scrolling of the conversation list view when the phone keyboard is shown.

A couple of weeks ago I wrote a blog post which described the creation of a Windows Phone 7 ConversationView, a view which renders a list of messages so that they look like a conversation. In this blog post I am going to extend the concept further, by adding an input text field allowing you to have a conversation with ELIZA, an A.I. chatterbot. This blog post will look at some of the tricky issue regarding scrolling the list of messages so that the most recent is always visible when responding.

You can see a video of this code in action below:

I hoped that I could find a decent C# ELIZA (a classic chatter application that takes on the role of a therapist) implementation on the internet, however, the only one I found was rather basic. If you know of any alternatives, pleas let me know!

In my previous blog post I created a UserControl which renders each Message instance, where the template used to render the message is dependant on which side of the conversation it relates to. Refer to my previous blog post for implementation details.

The layout for my simple chat application uses an instance of the ConversationView user control, with a text input located at the bottom of the screen:

<Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
  <Grid contribControls:GridUtils.RowDefinitions=",Auto">
 
    <ScrollViewer x:Name="ConversationScrollViewer">
        <!-- conversation view -->
        <local:ConversationView x:Name="conversationView"/>
      </StackPanel>
    </ScrollViewer>
 
    <!-- the text input field -->
    <Grid Grid.Row="1"
          contribControls:GridUtils.RowDefinitions=",,"
          Margin="0,10,0,0">
      <Rectangle Fill="White"
                  Grid.RowSpan="2"/>
      <txt:WatermarkedTextBox Watermark="type a message"
                              TextWrapping="Wrap"
                              AcceptsReturn="True"
                              Padding="0"
                              x:Name="TextInput"
                              GotFocus="TextInput_GotFocus"
                              LostFocus="TextInput_LostFocus"/>            
      <Path Data="m 0,0 l 16,0 l 0,16 l -16,-16"
            Fill="White"
            Margin="0,0,5,0"
            HorizontalAlignment="Right"
            Grid.Row="2"/>
    </Grid>
  </Grid>      
</Grid>

Note the simplified Grid markup from the WP7Contrib codeplex project, where the string ",Auto" is used in place of the more verbose RowDefinition XAML elements.

The WatermarkedTextBox is from an article by WindowsPhoneGeek (and it works like a charm – thanks!). A simple Path and Rectangle are added to the layout so that the input field looks like a speech bubble.

When the user clicks on the input TextBlock the phone keyboard will be revealed, allowing them to enter their message. This is where we stumble upon our first major problem!

When the phone keyboard is displayed, your application content is ‘pushed’ upwards to make space for the keyboard. Unfortunately, this results in the message which the user is replying to being pushed off the top of the screen …

Because our ConversationView sits within a ScrollViewer we can scroll to push the message further down the screen, however, this would require a negative scroll offset, which isn’t possible!

To circumnavigate this issue, we can add an element which is used to ‘push’ the top message downwards so that it is located at the bottom of the ScrollViewer. The following markup adds a Rectangle which sits above the ConversationView, with two Storyboards that expand / collapse the Rectangle allowing us to push the messages down when we need them:

<ScrollViewer x:Name="ConversationScrollViewer">
  <StackPanel Orientation="Vertical"
              x:Name="ConversationContentContainer"
              VerticalAlignment="Top">
    <!-- padding element -->
    <Rectangle Width="100"
                Height="0"
                x:Name="PaddingRectangle">
      <Rectangle.Resources>
        <Storyboard x:Name="PaddingRectangleShowAnim">
          <DoubleAnimation Storyboard.TargetName="PaddingRectangle" 
                Storyboard.TargetProperty="(Height)"
                To="400"  Duration="00:00:00.3"/>
        </Storyboard>
        <Storyboard x:Name="PaddingRectangleHideAnim">
          <DoubleAnimation Storyboard.TargetName="PaddingRectangle" 
                Storyboard.TargetProperty="(Height)"
                To="0"  Duration="00:00:00.3"/>
        </Storyboard>
      </Rectangle.Resources>
    </Rectangle>
 
    <!-- conversation view -->
    <local:ConversationView x:Name="conversationView"/>
  </StackPanel>
</ScrollViewer>

We can detect when the input TextBlock receives focus to determine when the keyboard will be revealed. Using the Show / Hide extension methods I blogged about a while back, we can fire the animations which make this padding rectangle grow or shrink when the keyboard is shown or hidden:

private void TextInput_GotFocus(object sender, RoutedEventArgs e)
{
  PaddingRectangle.Show();
  ApplicationBar.IsVisible = true;
}
 
private void TextInput_LostFocus(object sender, RoutedEventArgs e)
{
  PaddingRectangle.Hide();
  ApplicationBar.IsVisible = false;
}

If we fill the rectangle so that it is visible, you can see how it pushes down the content as shown below:

The next step is to ensure that the ConversationView is always scrolled so that the most recent message is visible. The ScrollViewer has a ScrollToVerticalOffset method which can be used to programmatically scroll the content, however, because this is not a dependency property it cannot be animated via Storyboard.

Here I am using the same trick I employed for the Windows Phone 7 Jump List control, where a private dependency property that sets the scroll offset value in its change handler is used as a target for the scrolling Storyboard:

/// <summary>
/// VerticalOffset, a private DP used to animate the scrollviewer
/// </summary>
private DependencyProperty VerticalOffsetProperty = DependencyProperty.Register("VerticalOffset",
  typeof(double), typeof(MainPage), new PropertyMetadata(0.0, OnVerticalOffsetChanged));
 
private static void OnVerticalOffsetChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
{
  MainPage app = d as MainPage;
  app.OnVerticalOffsetChanged(e);
}
 
private void OnVerticalOffsetChanged(DependencyPropertyChangedEventArgs e)
{
  ConversationScrollViewer.ScrollToVerticalOffset((double)e.NewValue);
}

Using this dependency property we can create a simple Storyboard and DoubleAnimation that scrolls to reveal the latest message:

private void ScrollConvesationToEnd()
{
  // start from the current position
  scrollViewerScrollToEndAnim.From = ConversationScrollViewer.VerticalOffset;
 
  // set the scroll position to the the height of the contained content
  scrollViewerScrollToEndAnim.To = ConversationContentContainer.ActualHeight;
 
  // go!
  scrollViewerStoryboard.Begin();
}

And there you have it, a fully functional conversation application. Enjoy!

You can download the complete sourcecode: WP7ConversationView.zip

Regards, Colin E.

The Windows Phone 7 Panorama control is widely used in applications and to many has come to symbolise the Metro Design Language. Search for panorama images and you will find numerous promo-shots of Windows Phone 7 applications which display the panoramic contents of the application hub, with an image of a phone above it illustrating how the panorama slides through your viewport.

The image below shows a promo-shot for XAMLFinance, an application I have been working on:

Creating images like the one above takes a bit of work, fortunately you can turn off the parallax scrolling effect of the control (as described in this blog post), allowing for easier image stitching, however the process is still quite manual.

For a bit of fun I thought it would be nice to template the Panorama control itself in order to display the full panorama contents on the emulator within a single screen, so that I can create my promo-shot with a single screengrab.

Unfortunately, the Panorama control is a little too tightly coupled to its template to allow this kind of radical re-design, so the next best options is to create a new page that hosts my PanoramaItems within an ItemsControl and style that.

So, we’ll start with a page which hosts our items within an ItemsControl:

<ItemsControl Style="{StaticResource ItemsControlStyle}">
    <ItemsControl.Background>
        <ImageBrush ImageSource="PanoramaBackground.jpg" Opacity="0.5"/>
    </ItemsControl.Background>
 
    <!--Panorama item one-->
    <controls:PanoramaItem Header="item1" Style="{StaticResource PanoramaItemStyle}">
        <Grid>
            ...
        </Grid>
    </controls:PanoramaItem>
 
    <!--Panorama item two-->
    <controls:PanoramaItem Header="item2"  Style="{StaticResource PanoramaItemStyle}">
        <Grid>
            ...
        </Grid>
    </controls:PanoramaItem>
 
    <!--Panorama item three-->
    <controls:PanoramaItem Header="item3"  Style="{StaticResource PanoramaItemStyle}">
        <Grid>
            ...
        </Grid>
    </controls:PanoramaItem>
</ItemsControl>

We need to shrink each of those PanoramaItem instances so that they all fit on a single screen. We can easily shrink them with a ScaleTransform, however Silverlight only supports render transforms, what we really need here is a transform that affects layout also (for a brief overview of the difference see this blog post). Fortunately the Silverlight Toolkit has a LayoutTransformer class which emulates this behaviour, and whilst it is not available in the WP7 release, copying the code across I found it to be entirely compatible with the Silverlight WP7 version.

We can shrink our PanoramaItems as follows:

<system:Double x:Key="Scale">0.5</system:Double>
 
<Style x:Key="PanoramaItemStyle" TargetType="controls:PanoramaItem">
  <Setter Property="Width" Value="260"/>
  <Setter Property="Height" Value="290"/>
  <Setter Property="Template">
    <Setter.Value>
      <ControlTemplate TargetType="controls:PanoramaItem">
        <!-- apply a LayoutTransform to the content in order to scale it -->
        <local:LayoutTransformer>
          <local:LayoutTransformer.LayoutTransform>
            <ScaleTransform ScaleX="{StaticResource Scale}"
                                            ScaleY="{StaticResource Scale}"/>
          </local:LayoutTransformer.LayoutTransform>
 
          <!-- the original content of the template follows -->
          <Grid Background="{TemplateBinding Background}" Margin="12,0,0,0">
            <Grid.RowDefinitions>
              <RowDefinition Height="auto"/>
              <RowDefinition Height="*"/>
            </Grid.RowDefinitions>
            <ContentControl x:Name="header"
                            ContentTemplate="{TemplateBinding HeaderTemplate}"
                            Content="{TemplateBinding Header}"
                            FontSize="{StaticResource PhoneFontSizeExtraExtraLarge}"
                            FontFamily="{StaticResource PhoneFontFamilySemiLight}"
                            HorizontalAlignment="Left" Margin="10,-2,0,26">
              <ContentControl.RenderTransform>
                <TranslateTransform x:Name="headerTransform"/>
              </ContentControl.RenderTransform>
            </ContentControl>
            <ContentPresenter Content="{TemplateBinding Content}"
                              HorizontalAlignment="{TemplateBinding HorizontalContentAlignment}"
                              Margin="{TemplateBinding Padding}" Grid.Row="1"
                              VerticalAlignment="{TemplateBinding VerticalContentAlignment}"/>
          </Grid>
        </local:LayoutTransformer>
      </ControlTemplate>
    </Setter.Value>
  </Setter>
</Style>

Now we need to styles and template the ItemsControl so that it looks like a Panorama. This is done as follows:

<Style TargetType="ItemsControl" x:Key="ItemsControlStyle">
  <Setter Property="VerticalAlignment" Value="Center"/>
  <Setter Property="HorizontalAlignment" Value="Center"/>
  <Setter Property="ItemsPanel">
    <Setter.Value>
      <ItemsPanelTemplate>
        <tk:WrapPanel Orientation="Horizontal"/>
      </ItemsPanelTemplate>
    </Setter.Value>
  </Setter>
  <Setter Property="Template">
    <Setter.Value>
      <!-- create a template for the ItemControl that makes it look like a panorama-->
      <ControlTemplate>
        <!-- the grid which displays the  panorama background -->
        <Grid Background="{TemplateBinding Background}">
          <Grid.RowDefinitions>
            <RowDefinition Height="auto"/>
            <RowDefinition Height="*"/>
          </Grid.RowDefinitions>
 
          <!-- the title, scaled to match the PanoramatItems-->
          <local:LayoutTransformer>
            <local:LayoutTransformer.LayoutTransform>
              <ScaleTransform ScaleX="{StaticResource Scale}"
                              ScaleY="{StaticResource Scale}"/>
            </local:LayoutTransformer.LayoutTransform>
            <TextBlock Text="{TemplateBinding Tag}"
                       FontSize="180"
                       FontFamily="{StaticResource PhoneFontFamilySemiLight}"
                       HorizontalAlignment="Left" Margin="10,-2,0,26"/>
          </local:LayoutTransformer>
 
          <!-- the rendered items -->
          <ItemsPresenter Grid.Row="1"/>
        </Grid>
      </ControlTemplate>
    </Setter.Value>
  </Setter>
</Style>

The end result is that we can see the entire panorama contents in a screen-shot ready state:

The big advantage of this approach is that any changes to the application can be reflected in the promo-shot very swiftly. It is also quite good fun having a fully functioning version of your panoramic hub in miniature!

You can download the sourcecode here: PanoramaShot.zip

Regards, Colin E.