The solution I published previously handles the WP7 back keypress in order to keep track of the back-stack depth. When the back-stack depth is just one, a back-button press exits the application. This works fine if backwards navigation is always controlled via the hardware back-button, however if your application has HTML anchor elements that navigate back to a previous page, or you use code such as javascript:history.go(-1), this back-stack handling code will not detect that a backwards navigation has occurred.

As an aside, WP7 applications really should use the hardware back-button for navigation. If you are writing a cross-platform PhoneGap application consider adapting your UI for each platform. This means removing the back-button you woudl have in your iOS version when ‘skinning’ for WP7.

In order to solve this issue I have updated the code to inspect the URL that the browser control is navigating to in order to detect backwards navigation. The class now maintains a list of URLs, which represent the navigation stack. This allows it to detect a backwards navigation.

/// <summary>
/// Handles the back-button for a PhoneGap application. When the back-button
/// is pressed, the browser history is navigated. If no history is present,
/// the application will exit.
/// </summary>
public class BackButtonHandler
{
  private WebBrowser _browser;
 
  private List<string> _backStack = new List<string>();
 
  public BackButtonHandler(PhoneApplicationPage page, PGView phoneGapView)
  {
    // subscribe to the hardware back-button
    page.BackKeyPress += Page_BackKeyPress;
 
    _browser = phoneGapView.Browser;
 
    // handle navigation events
    _browser.Navigated += Browser_Navigated;
 
  }
 
  /// <summary>
  /// Handle navigation in order to update our back-stack
  /// </summary>
  private void Browser_Navigated(object sender, NavigationEventArgs e)
  {
    string url = _browser.Source.OriginalString;
 
    // ensure all slashes are the same
    // app\www/index.html
    // see: https://issues.apache.org/jira/browse/CB-184
    url = url.Replace("\\", "/");
 
    if (_backStack.Count < 2)
    {
      _backStack.Add(url);
    }
    else
    {
      // check whether the URL represents a backwards navigation
      string previousPage = _backStack[_backStack.Count - 2];
      if (previousPage == url)
      {
        _backStack.RemoveAt(_backStack.Count - 1);
      }
    }
  }
 
  /// <summary>
  /// Handle the hardware back-button
  /// </summary>
  private void Page_BackKeyPress(object sender, CancelEventArgs e)
  {
    // if we have items in the back-stack, route this event
    // to the browser
    if (_backStack.Count > 1)
    {
      _browser.InvokeScript("eval", "history.go(-1)");
      e.Cancel = true;
    }
  }
}

Note: There use of url.Replace("\\", "/"), this is due to a minor issue with the PhoneGap WP7 native code, which I have raised in the Callback JIRA (CB-184).

To use this code simply create an instance of the class, passing the PGView (the PhoneGap user control) into teh constructor:

public MainPage()
{
  InitializeComponent();
 
  new BackButtonHandler(this, PGView);
}

Because back-button handling is a mandatory requirement for WP7 applications, hopefully Nitobi will incorporate this code (or similar) into the PhoneGap Build service (which I tried earlier this week – it is pretty amazing!)

You can download a working example here: HTML5SandwichFlow.zip

(The first three recipe pages have ‘back’ anchor elements, two use the URL, one uses JavaScript)

Regards,
Colin E.

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.

What I like about CodeProject is the fantastic quality of the articles submitted by the thousands of authors that participate in this site, with the only payment being their own please in the writing.

I have not written that many articles throughout the year, just four of them. However, I have put a lot of effort into each one of them – and thankfully they have been very well received. It is great that CodeProject favours quality over quantity. My articles for 2011 were:

• Declarative Codesnippet Automation with T4 Templates
• Developing a Windows Phone 7 JumpList Control
• From Silverlight to HTML5
• XAMLFinance – A Cross-platform WPF, Silverlight & WP7 Application

I do also circulate some of my blog posts via the CodeProject Associate program..

On that note, it is almost three months since I last wrote an article … fortunately I do have an idea for the next article, so I had better get on with writting it …

Regards, Colin E.

This application still exhibits a few UI quirks that make it fairly obvious that this is not a native application, the first is the gray box that appears whenever a link is clicked, the second is the overall responsiveness – there is a short delay between clicking on links / buttons and the application responding. It is this responsiveness that I would like to tackle in this blog post. This delay unfortunately gives the impression that your application is less responsive than it actually is!

So where does this delay come from?

Despite the rise in popularity of touch interfaces, much of the web is still designed for interaction with a mouse and keyboard, with the DOM exposing events for mouse-up, mouse-down and click user interactions. The Windows Phone 7 browser control captures touch interactions and translates these into the required mouse events, firing them on the DOM element being interacted with. However, the browser itself also needs to support gestures such as pan, pinch-zoom and double-tap zoom.

If we consider for example the pinch-zoom feature, where the user places two fingers on the screen and moves them apart in order to zoom in. It is highly unlikely they will place both fingers on the screen simultaneously. If, when the first finger was placed, a mouse-down event was fired on the relevant DOM element, there would be no way to ‘cancel’ this event when the user’s second finger made contact with the screen shortly afterwards. For this reason the WP7 mobile browser does not properly support mouse-down / mouse-up events. You will find that mousedown, mouseup then click are always fired immediately in that order regardless of how long you hold your finger on the screen for. Clearly the need to add gesture support to the browser interferes with the way in which native touch events are translated into JavaScript mouse events.

Now consider the double-tap zoom feature, where the user taps twice in quick succession to zoom the web page by some fixed amount. If the DOM click event were fired on the first tap, this would cause a navigation to occur if an anchor element were tapped. This is certainly not the desired behaviour! Again, there is no way to ‘cancel’ an event once it is fired, so the only solution to this problem is, when the user first taps the screen, pause for a few hundred milliseconds to see if they tap a second time. Only after this pause is it safe to pass the interaction onto the DOM, firing a click event on the relevant DOM element.

Stock image courtesy of lovetheson

The need to handle gestures in the native layer causes numerous issues for the browser event handling. Thankfully these issues are relatively minor for most websites, but if your aim is to create a HTML-based application with a native look and feel, these issues become quite major.

Improving responsiveness

The problem I want to tackle in this blog post is that of the click DOM event firing delay to support the double-tap gesture. With HTML5-based applications you will typically want to disable pinch zoom, double-tap zoom and (optionally) scrolling as I described in a previous blog post. As a result your application has no need for the double-tap and pinch gestures and we are safe to short-circuit this behaviour, immediately raising DOM click events when the user taps the screen.

My solution follows a similar approach to the utility class I wrote for suppressing pan / zoom, where event handlers are added to the Border that sits within the WebBrowser control visual tree:

\-WebBrowser
  \-Border
    \-Border
      \-PanZoomContainer
        \-Grid
          \-Border (*)
            \-ContentPresenter
              \-TileHost

In order to forward Tap gestures to the browser, we can add event handlers to the Border element, then use InvokeScript to pass this onto the DOM rendered within the TileHost.

The JavaScript code to achieve this is very simple, the DOM exposes an elementFromPoint function which allows you to hit test the DOM. The IE9 DOM interface also exposes a non-standard click function which invokes any click event handlers, this will cause an anchor element to navigate. Putting it together, if you have an anchor element at (x=100, y=100), you can cause it to navigate using the following simple code:

document.elementFromPoint(100, 100).click()

Calling this JavaScript from our native C# code in response to Tap events is very easy. I have wrapped it up into a simple utility class:

/// <summary>
/// Captures mouse left button up events, triggering an immediate
/// click event on the clicked DOM element.
/// </summary>
public class BrowserFastClick
{
  private WebBrowser _browser;
 
  private Border _border;
 
  public BrowserFastClick(WebBrowser browser)
  {
    _browser = browser;
    browser.Loaded += new RoutedEventHandler(Browser_Loaded);
  }
 
  private void Browser_Loaded(object sender, RoutedEventArgs e)
  {
    // locate the element used to capture mouse events
    _border = _browser.Descendants<Border>().Last() as Border;
    _border.Tap += Border_Tap;
  }
 
  private void Border_Tap(object sender, GestureEventArgs e)
  {
    //determine the click location
    var pos = e.GetPosition(_border);
 
    // forward to the browser
    _browser.InvokeScript("eval",
      string.Format("document.elementFromPoint({0},{1}).click()", pos.X, pos.Y));      
  }
}

To use it within a PhoneGap application, simply create an instance as follows:

new BrowserFastClick(PGView.Browser);

The net result is that your application becomes more responsive, with the browser immediately navigating links when they are first tapped.

I have updated the HTML5 SandwichFlow application I blogged about a few weeks ago to use this FastClick code. You can download the complete example here: HTML5SandwichFlow.zip

Regards, Colin E.

Ever since I first started writing code for Windows Phone 7 I have wanted to do something involving physics and the accelerometer. I finally found a few hours to spare to give it a go. This blog post doesn’t go into too much detail about Farseer, the Physics Engine that I used, I didn’t really have time to learn it in any great detail. This post is more about how quickly you can put together something really quite cool in quite a short space of time using libraries and code grabbed from the internet.

The simple app I created renders a maze that you ‘roll’ a small ball around by tilting your phone:

This works well in the new 7.1 emulator where you can tilt the emulator via the extended controls. However, it works best on a real device, where you can control tilt far more easily. See the video below:

Farseer Physics Engine

The game makes use of the popular Farseer Physics Engine. This library allows you to create a world populated with physics bodies, supporting features such as friction, joints, motors and much much more. As I am a Silverlight developer I made use of the Physics Helper library which allows you to use the Farseer engine within a Silvelight application with very little effort. With the Physics Helper you simply make the Physics Engine ‘aware’ of the objects you wish it to control and it does the rest, animating them as they are subjected to gravity and other interactions.

The simplest way to use Physics Helper is via behaviours, this allows you to create a fully functioning ‘world’ without writing a single line of C# code. For example, you can create a ball and a surface that it will fall towards, eventually coming to rest, with just a few lines of XAML:

<Canvas x:Name="canvas">
  <!-- create our 'world' -->
  <i:Interaction.Behaviors>
    <pb:PhysicsControllerBehavior/>
  </i:Interaction.Behaviors>
 
  <Ellipse Width="100" Height="100" Fill="Red"
            Canvas.Left="80" Canvas.Top="100">
    <!-- make the engine aware of this element -->
    <i:Interaction.Behaviors>
      <pb:PhysicsObjectBehavior />
    </i:Interaction.Behaviors>
  </Ellipse>
 
 
  <Rectangle Width="500" Height="10" Fill="Blue"
              Canvas.Top="500">
    <!-- make the engine aware of this STATIC element -->
    <i:Interaction.Behaviors>
      <pb:PhysicsObjectBehavior IsStatic="True"/>
    </i:Interaction.Behaviors>
  </Rectangle>
</Canvas>

I find this pretty amazing!

Physics Helper will do much more, it can handle complex paths and geometries, explosions and collisions with minimal effort. For a greater insight into just how much is possible, I would recommend Andy Beaulieu’s Channel 9 article. Andy is the creator of Farseer, so really knows his stuff!

My maze is generated in C# code, so despite the elegance of using Physics Helper via behaviours, I need to add elements to my canvas programmatically. This means that I have to make the physics engine aware of their existence in code also. To achieve this, I add the behaviour in code as follows:

/// <summary>
/// Uses Physics Helper to create a physics body for the given element
/// </summary>
private void AddPhysicsBody(FrameworkElement element, bool isStatic)
{
  var behaviorCollection = Interaction.GetBehaviors(element);
  behaviorCollection.Add(new PhysicsObjectBehavior()
  {
    IsStatic = isStatic
  });
 
  var physicsObject = element.GetValue(PhysicsObjectMain.PhysicsObjectProperty) as PhysicsObjectMain;
  _physicsController.AddPhysicsBody(physicsObject);
}

Creating a Maze

I found numerous C# maze algorithms on the internet, most of them based on the same random-walk concept. There is a great description of this approach, with animated examples on this blog. Unfortunately every C# implementation I came across was tightly coupled to a specific UI framework, often WinForms or XNA (tut-tut remember to separate your concerns!). So, I took a simple maze algorithm from a software forum and ripped-out the WinForms / GDI rendering code. A new maze is constructed simply by creating an instance of the Maze class, passing it the number of rows and columns.

In order to render the maze using Silverlight elements, I simply took the original maze graphics code:

private void CreateMaze()
{
  // compute the number of rows / cols
  double ratio = mazeContainer.ActualHeight / mazeContainer.ActualWidth;
  int cols = _mazeSize;
  int rows = (int)((double)cols * ratio);
  double cellWidth = mazeContainer.ActualWidth / cols;
 
  // create the maze
  Maze maze = new Maze(rows, cols);
 
  // render the maze
  for (int i = 0; i < cols; ++i)
  {
    for (int j = 0; j < rows; ++j)
    {
      var room = maze.cells[i, j];
      if ((room & Maze.UP) != 0)
        DrawLine(i * cellWidth + cellWidth / 2,
                j * cellWidth,
                i * cellWidth + cellWidth / 2,
                j * cellWidth + cellWidth / 2 - 1);
      if ((room & Maze.DOWN) != 0)
        DrawLine(i * cellWidth + cellWidth / 2,
              j * cellWidth + cellWidth / 2,
              i * cellWidth + cellWidth / 2,
              j * cellWidth + cellWidth - 1);
      if ((room & Maze.RIGHT) != 0)
        DrawLine(i * cellWidth + cellWidth / 2,
              j * cellWidth + cellWidth / 2,
              i * cellWidth + cellWidth - 1,
              j * cellWidth + cellWidth / 2);
      if ((room & Maze.LEFT) != 0)
        DrawLine(i * cellWidth,
              j * cellWidth + cellWidth / 2,
              i * cellWidth + cellWidth / 2 - 1,
              j * cellWidth + cellWidth / 2);
    }
  }
}

And created a method that mimics the behaviour of the System.Drawing.Graphics.DrawLine method which the original maze code depended on:

private void DrawLine(double x1, double y1, double x2, double y2)
{
  double width = x2 - x1 + 2.0;
  if (width == 0.0) width = 2.0;
 
  double height =  y2 - y1+ 2.0;
  if (height == 0.0) height = 2.0;
 
  var rec = new System.Windows.Shapes.Rectangle()
  {
    Fill = new SolidColorBrush(Colors.Red),
    Width = width,
    Height = height
  };
  Canvas.SetLeft(rec, x1);
  Canvas.SetTop(rec, y1);
  mazeContainer.Children.Add(rec);
 
  AddPhysicsBody(rec, true);
}

A bit messy, but gets the job done!

The above code creates a maze comprised of static physics objects, where the _mazeSize field dictates the scale of the maze:

Adding a Rolling Ball

Adding a ball to the maze is simply a matter of creating an ellipse and adding it at the maze entrance. Note, this physics-body is not static, so will move under the influence of gravity:

Ellipse ball = new Ellipse()
{
  Width = cellWidth * 0.7,
  Height = cellWidth * 0.7,
  Fill = this.Resources["brush"] as Brush
};
Canvas.SetLeft(ball, ((cols / 2) + 0.7) * cellWidth);
Canvas.SetTop(ball, 0);
mazeContainer.Children.Add(ball);
 
AddPhysicsBody(ball, false);

By default, the ‘world’ has gravity with a fixed Y component and no X component. This causes all non-static bodies to fall downwards as you might expect. In order to guide the ball around the maze by tilting the phone, we need to adjust gravity based on accelerometer readings. This is achieved by the following code:

private void HandleAccelerometer()
{
  _sensor = new Accelerometer();
  _sensor.Start();
 
  // 10 times a second, update the gravity
  var gtimer = new DispatcherTimer();
  gtimer.Interval = TimeSpan.FromSeconds(0.1);
  gtimer.Tick += (s, e) =>
  {
    if (_physicsController.Simulator != null)
    {
      _physicsController.Simulator.Gravity.Y = 5 * -_sensor.CurrentValue.Acceleration.Y;
      _physicsController.Simulator.Gravity.X = 5 * _sensor.CurrentValue.Acceleration.X;
    }
  };
  gtimer.Start();
}

Note: this uses a timer, rather than updating the simulator every time the accelerometer reading changes. I found that without the timer, I was repeatedly seeing the generic “Element is already a child of another element” exception. You will also notice in the code that the maze is built after a pause of a couple of seconds, again in order to avoid this issue. There’s something funny going on inside the Physics Helper!

Finally, we handle collisions in order to play a simple sounds effect a the ball bounces off each wall:

// locate the physics controller
_physicsController = mazeContainer.GetValue(PhysicsControllerMain.PhysicsControllerProperty) as PhysicsControllerMain;
 
// load the WAV file
Stream stream = TitleContainer.OpenStream("boing1.wav");
_effect = SoundEffect.FromStream(stream);
FrameworkDispatcher.Update();
 
// play on each collision
_physicsController.Collision += (s,e) => _effect.Play();

And there we have it, a simple maze game powered by the Farseer Physics engine. The whole thing only took about an hour to create, with code grabbed from the internet – a bit rough and ready, but I was impressed with how easy it was to create this game. There is much more that could be done, for example detecting when the ball reaches the end of the maze, advancing to a more difficult level, however, my time has run out on this bit of fun … Also, if I were to take this idea further, I would probably use XNA rather than Silverlight. The Physics Helper is great for simple XAML-only physics models, but I feel that it wasn’t really built for programmatic creation of bodies.

You can download the code here: WP7MazeGame.zip

Note, you will have to download and install Physics Helper to run this code.

On another note, Farseer is clearly the result of hundreds of hours of development effort, which makes it easy to create realistic physics-based applications and games. Farseer is free to use under the MS-PL licence. However, I would urge anyone who has used this great library to create a WP7 game to donate via the Farseer codeplex site (scroll to the bottom).

Regards, Colin E.

So why create a Metro-style PowerPoint presentation? A couple of reasons, firstly, the templates that come with PowerPoint are absolutely awful!

They look very dated (to put it politely). Secondly, with the Metro Design Language, which was introduced with Windows Phone 7, Microsoft have come up with something surprisingly stylish. Metro is about clarity, readability, simplicity – concepts that map very well to presentations.

The ‘classic’ Metro look, which I have tried to re-produce with this template, includes highly legible san-serif fonts (from the Segoe family), a lack of chrome (i.e. shadows, gradient) and fluid motions. Many metro applications do include background imagery to add ‘warmth’, as I have done here also.

I have created a template with a master and a number of layouts. Each layout includes a number of sequenced animations, mimicking the ‘fast and fluid’ Metro interface:

PowerPoint can be used to create some rather neat sequenced animations, if you ignore the rather garish defaults.

To get a better feel for this template, have a look at it in motion (the quality here is rather poor, I haven’t managed to find a screen capture tool that works well for subtle colours):

If you want to use this template, you might want to change the background image. You can do this via the ‘slide master view’. The background I included is one I found on the free stock imagery site stock.xcnhg, by the user fangol. There are numerous other free images on that site. Please remember to attribute your usage of free stock images.

You might also find that you need to add new layouts based on your content. Again, this is easy to do via the master view.

Anyhow, here is the template, enjoy: MetroStyle.pptx

NOTE: Until I get the mime-types sorted out you might have to right click and select “save as” to save the above PowerPoint file.

Regards, Colin E.

Readers of my blog will know that I have been working on, and writing about, the use of PhoneGap to create HTML5-based Windows Phone 7 applications. Along the way I have solved problems such as back-button support, tombstoning and suppressing browser pan and zoom. So far the applications I have discussed have all been single-page JavaScript applications, i.e. the WebBrowser control loads a single HTML page which links to the application JavaScript. All subsequent navigation involves updating the DOM dynamically rather than navigating to a new URL. However, I have had numerous questions to my previous blog posts from people who are using PhoneGap to create simple navigation-based applications. In this context PhoneGap is being used as a mechanism for packaging up a collection of relatively static HTML pages.

So why would you want to do this? This is a perfectly valid question! If you have static HTML based content why not simply put it on the web? There are a few reasons, one is to ensure that the content is always available, whether the phone is connected to a network or not. Another is monetization, the app-store model provides an easy way to charge for this content. Regardless of the pros and cons, based on the feedback my previous articles have received, people are very interested in using PhoneGap as a model for packaging static content.

In this blog post I will show how to solve the problems of back-button support and pan / zoom for a simple navigation-based HTML application. As an example, I have chosen a subject which I have a lot of interest in … sandwiches! I have previously blogged about SandwichFlow, an example application which showcased my metro-in-motion series, here I have transformed the sandwich recipe HTML into a collection of static HTML pages.

Packaging the HTML

My first PhoneGap blog post detailed how to get up-and-running with PhoneGap, if you have never used this framework before I would recommend that you read that first. Packaging my sandwich recipe content into an application was simply a matter of copying the files (HTML and CSS) into the ‘www’ directory, running the T4 template that auto-generates the GapSourceDictionary.xml, building and running. The resulting application is as follows:

PhoneGap does a great job of making it very easy to package HTML content into an application, loading the files into isolates storage etc … However, there are a few Windows Phone 7 specific concepts that have to be supported in order to ensure certification on submission to the marketplace.

Back-button Support

UPDATE: There are a few issues with the code below. See my more recent blogpost for an improved solution.

Correct back-button support is a mandatory requirement for marketplace certification. Hitting the back button should navigate back through the various screens of an application. Hitting the back-button on the first screen should terminate the application. The standard PhoneGap Visual Studio template does not support the back-button by default, this no-doubt reflects the fact that the other PhoneGap platforms (iPhone, Android, BlackBerry) do not share this same requirement, or lack a back-button altogether.

In my previous blog post on back-button support I described how a single-page JavaScript application can manage its own back-stack. This approach does not work for navingation-based HTML applications.

The WebBrowser control which PhoneGap uses to render its contents stores its navigation history in the same way that a desktop browser does. This history can be accessed via the JavaScript ‘history’ object. If the back-button is pressed after navigating to one of the packaged HTML pages, invoking history.go(-1) will cause the WebBrowser control to navigate backwards. All we need to do is to keep track of navigation events to determine whether to route the back-button too our HTML application or not.

The following utility class does just that:

/// <summary>
/// Handles the back-button for a PhoneGap application. When the back-button
/// is pressed, the browser history is navigated. If no history is present,
/// the application will exit.
/// </summary>
public class BackButtonHandler
{
  private int _browserHistoryLength = 0;
  private PGView _phoneGapView;
 
  public BackButtonHandler(PhoneApplicationPage page, PGView phoneGapView)
  {
    // subscribe to the hardware back-button
    page.BackKeyPress += Page_BackKeyPress;
 
    // handle navigation events
    phoneGapView.Browser.Navigated += Browser_Navigated;
 
    _phoneGapView = phoneGapView;
  }
 
  private void Browser_Navigated(object sender, NavigationEventArgs e)
  {
    if (e.NavigationMode == NavigationMode.New)
    {
      _browserHistoryLength++;
    }
  }
 
  private void Page_BackKeyPress(object sender, CancelEventArgs e)
  {
    if (_browserHistoryLength > 1)
    {
      _phoneGapView.Browser.InvokeScript("eval", "history.go(-1)");
      _browserHistoryLength -= 2;
      e.Cancel = true;
    }
  }
}

Note: I have had a number of requests from readers who do not have any C# / Silverlight experience, so are unsure how to use code snippets like the one above. In this blog post I have included the full sourcecode. Just grab the code and replace the contents of the ‘www’ directory with your own content, and you are good to go!

With the above code in place the application now supports the back-button

With this feature in place you should be able to successfully submit a PhoneGap based application to the Windows Phone 7 marketplace. The other bits of code that follow are all about improving the cosmetics.

Suppressing Pan and Zoom

Whilst the viewport metadata settings can be used to prevent scaling, the cosmetics of this feature are not terribly good with Windows Phone 7, the user can still ‘pinch’ your HTML page, however, it snaps back to its original scale when the manipulation ends. I previously published a simple class which can intercept manipulation events in order to suppress the pinch zoom behaviour.

This class can also ‘lock’ the browser windows entirely, supressing scroll as well as zoom. However, this is only appropriate for use on pages where you can be sure the content fits entirely within a single page. In order to ‘activate’ this behaviour we need to send a message from the HTML / JavaScript to the C# utility class. The ’about’ page of this application does just that. When it is loaded the following JavaScript is executed:

<script type="text/javascript" charset="utf-8">
  // ensure that this page does not scroll
  window.external.Notify("noScroll");
</script>

The utility class (described in the earlier blog post) is instantiated in code-behind, with the above Notify being used to ‘lock’ the page:

private WebBrowserHelper _browserHelper;
 
// Constructor
public MainPage()
{
  InitializeComponent();
 
  new BackButtonHandler(this, PGView);
  _browserHelper = new WebBrowserHelper(PGView.Browser);
 
  PGView.Browser.ScriptNotify += Browser_ScriptNotify;
  PGView.Browser.Navigated += Browser_Navigated;
}
 
private void Browser_Navigated(object sender, NavigationEventArgs e)
{
  // when we first navigate to a page, we assume that it can be scrolled
  _browserHelper.ScrollDisabled = false;
}
 
private void Browser_ScriptNotify(object sender, NotifyEventArgs e)
{
  // if a page notifies that it should not be scrollable, disable
  // scrolling.
  if (e.Value == "noScroll")
  {
    _browserHelper.ScrollDisabled = true;
  }
}

Again, the code above is included in the download at the end of this article. To ‘lock’ the scroll on any of your HTML pages, simply add the JavaScript ‘Notify’ above.

Splashscreen

One final cosmetic issue is the application startup. The application splashcreen is hidden automatically when your application starts up. This is fine for a native application, however a PhoneGap application isn’t quite ready at this point. After the native wrapper starts, the code is loaded into the WebBrwoser control and the HTML / JavaScript application starts. This results in a rather ugly white screen appearing for ~ 0.5 second when the application starts up.

The start screen duration is not configurable, however, there is a simple solution to this problem, when the application first starts, render the splashscreen as the application content, then hide this image when the PhoneGap application starts.

To do this, create an image and position it in front of the PhoneGap browser control:

<Grid x:Name="LayoutRoot" Background="Transparent">
 
  <my:PGView HorizontalAlignment="Stretch" 
                  Margin="0,0,0,0"  
                  Name="PGView" 
                  VerticalAlignment="Stretch"/>
 
  <Image Source="/SplashScreenImage.jpg"
          x:Name="splashImage">
    <Image.Resources>
      <Storyboard x:Name="fadeOut"
                  BeginTime="0:0:0.5"
                  Completed="fadeOut_Completed">
        <DoubleAnimation
                Storyboard.TargetName="splashImage"
                Storyboard.TargetProperty="Opacity"
                From="1.0" To="0.0" Duration="0:0:0.3"/>
      </Storyboard>
    </Image.Resources>
  </Image>
</Grid>

This image has a storyboard that fades-out the image.

This animation is triggered when the browser navigates to the first age of the application:

EventHandler<NavigationEventArgs> hideSplashScreen = null;
hideSplashScreen = (s, e ) =>
  {
    fadeOut.Begin();
    PGView.Browser.Navigated -= hideSplashScreen;
  };
PGView.Browser.Navigated += hideSplashScreen;

Finally, the Completed event handler removes the image altogether when the animation ends:

private void fadeOut_Completed(object sender, EventArgs e)
{
  splashImage.Visibility = Visibility.Collapsed;
}

Conclusions

Hopefully this blog post will help people who are new to WP7 and wish to release PhoneGap applications comprised of multiple HTML pages.

You can download the sourcecode: HTML5SandwichFlow.zip

Regards, Colin E.

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.