28 May 2013

Workaround for selecting the last vertex of a Windows Phone MapPolyline

Fellow MVP - and fellow map maniac - Morten Nielsen brought me into contact with a Windows Phone developer called Jonathan Aghachi. He was struggling to select MapPolylines drawn on a Map using Map.GetMapElementsAt. For those not familiar with he concept of selecting stuff on a Wiindows Phone 8 map – you cannot select the shapes on the map directly like on Windows RT – they do not expose any events. In stead, you can trap the Tap event of the Map object, and retrieve all objects on that location like this:

private void Map_Tap(object sender, GestureEventArgs e)
{
  var selected = Map.GetMapElementsAt(e.GetPosition(Map));
}

selectbug

The problem

There is apparently a bug in Map.GetMapElementsAt when trying to select the line by using a point on the last vertex, i.e. that piece of the MapPolyline that runs between the 2nd to last point and the last point. If a MapPolyline has only one vertex (that is, only a start and an end point, with no points in between) you will not be able at all to select it using Map.GetMapElementsAt  This was exactly what Jonathan was experiencing. It can be clearly demonstrated by this very simple application, that looks like displayed on the right. It draws thee MapPolylines on the map, each with a different color. The Tap function of the map is a more extended version of the sample above and looks like displayed below:

 

private void Map_Tap(object sender, GestureEventArgs e)
{
  var selected = 
Map.GetMapElementsAt(e.GetPosition(Map)).FirstOrDefault() as MapPolyline; if (selected != null) { TitleText.Foreground = new SolidColorBrush( selected.StrokeColor); MessageBox.Show("MapPolyline selected"); } }

This should show the TitleText text (showing “MAPPOLYGON BUG") in the color of the selected MapPolyline, and show a message box as well. If you download the sample solution that goes with this post, you will notice:

  • You can tap on the red line as much as you want – but you will never get the message box
  • You can select the yellow line, but only if you tap on the horizontal part. The part that runs diagonally to the north-east will never get you a message box

The workaround

As you may have noticed, the green line, although it has only two points, can be selected by tapping on it. The reason for that is very simple – it does not have two points, but three. I have added the last point twice to the to the line, effectively creating a vertex of zero length. Then the first vertex isn’t the last anymore, and presto. See this little code excerpt:

var line1 = new MapPolyline();
line1.Path.Add(new GeoCoordinate(52.154346, 5.36974));
line1.Path.Add(new GeoCoordinate(52.154346, 5.411282));
line1.StrokeColor = Colors.Red;
line1.StrokeThickness = 10;
Map.MapElements.Add(line1);

var line3 = new MapPolyline();
line3.Path.Add(new GeoCoordinate(52.165509, 5.36974));
line3.Path.Add(new GeoCoordinate(52.165509, 5.411282));
line3.Path.Add(new GeoCoordinate(52.165509, 5.411282));
line3.StrokeColor = Colors.Green;
line3.StrokeThickness = 10;
Map.MapElements.Add(line3);

Some concluding remarks

My contacts at the Windows Phone team have confirmed this as a bug. I think this is very minor indeed, and using this simple work around makes circumventing it pretty easy. I know Jonathan is happily moving forward now with my workaround.

For the record: I actually wrote both code and blog post in Plön, in the north of Germany, during my holiday there. It was quite rainy that day, so what the heck ;-)

13 May 2013

Windows Phone 8 navigation part 4–updating the tests, fixing the final issues

Last time: so close, yet so far:

This series appears to have become a trilogy in four parts – at the end of the last episode everything worked, save for tombstoning, although we explicitly wrote test code for that. The app tombstoned, partially - two things were apparently missing:

  • The route
  • The locations to and from the route should run.

Making the tests fail

An important step when you have a bug in an app that passes all tests, is to make a test that fails because of the bug. In that case, you have reproduced the problem, and can start on fixing the bug. Logically, the bug is fixed when the test no longer fails – and should anyone start to mess around with your code an re-introduce the bug, the test will fail again, indicating something has gone wrong before you even ship. Your tests have become a smoke detector ;-)

Anyway, we observe there is no selected location, nor routes or waypoints after tombstoning. When we look at the comprehensive test for RoutingViewModel written in the 2nd post of this series, we see the following Assert statement with regard to the retrieved viewmodel:

Assert.IsTrue(vm.RouteCoordinates.Any());
Assert.IsTrue(vm.Maneuvers.Any());
Assert.IsTrue(retrievedVm.RouteCoordinates.Count == vm.RouteCoordinates.Count);
Assert.IsTrue(retrievedVm.FromViewModel.SearchText == "Springerstraat Amersfoort Netherlands");
Assert.IsTrue(retrievedVm.Maneuvers.Count == vm.Maneuvers.Count);

Shockingly, we learn two things:

  • We indeed don’t test the presence of either SelectedLocation or either FromViewModel and ToViewModel.
  • We do test the presence of both RouteCoordinates and Maneuvers. So our viewmodel works in that respect – so the error must have to do something with data binding.

First, we add test code for SelectedLocation

Assert.IsNotNull(retrievedVm.FromViewModel.SelectedLocation);
Assert.IsNotNull(retrievedVm.ToViewModel.SelectedLocation);

And sure enough:

image

Annoyingly, this does only say which test failed, but not what exactly failed in this test. You can of course follow the purist route and write a separate test method for every assert, or just be lazy like me and use the overload every Assert method has:

Assert.IsNotNull(retrievedVm.FromViewModel.SelectedLocation, 
  "No FromViewModel.SelectedLocation tombstoned");
Assert.IsNotNull(retrievedVm.ToViewModel.SelectedLocation, 
 "No ToViewModel.SelectedLocation tombstoned");

image

And there we are. A clear error message. There is no SelectedLocation after tombstoning

Fixing the SelectedLocation bug aka serialization under the hood

Let me introduce you to the wonderful world of serialization. Much as we move into the world of asynchronous and parallel programming, serialization is essentially a sequential process. First property A is written, then property B. When something is deserialized, things are also read from storage in a particular order, i.e. the order they are written.

Let’s get back to the RoutingViewModel. I’ve abbreviated the property implementation a bit, apart from the Model. There we see the following code:

public ManeuverViewModel SelectedManeuver

public GeocodeViewModel ToViewModel

public GeocodeViewModel FromViewModel

public ObservableCollection<RouteGeometryViewModel> RouteCoordinates { get; set; }

public ObservableCollection<ManeuverViewModel> Maneuvers { get; set; }

private NavigationModel model;
public NavigationModel Model
{
  get { return model; }
  set
  {
    model = value;
    if (model != null)
    {
      ToViewModel = new GeocodeViewModel(model.To) { Name = "To" };
      FromViewModel = new GeocodeViewModel(model.From) { Name = "From" };
    }
  }
}

Now let’s assume, for a moment, serialization simply reflects all public properties with both getter and setter, and writes them one by one to storage – and reads them in the same order. In no particular order – if this were a database that most probably means the order the in which records were put in. Could it be reflection works the same way? But then, deserializing would mean that first the SelectedManeuver would be deserialized, then ToViewModel and FromViewModeland, then the RouteCoordinates, then the Maneuvers, and finally the model. But smart Mr Me has implemented this clever method of initializing FromViewModel and ToViewModel upon calling of the setter. So whatever was deserialized into FromViewModel and ToViewModel  gets overwritten after Model is deserialized!

So let’s make the Model property the very first property of the viewmodel, right after the constructors, run the test and see what happens…

image

You can imagine with this kind of arcane stuff going on behind the curtains, (unit) test code can be a really great tool to track and fix this kind of obscure errors – and make sure they never, ever occur suddenly again, just because someone changed the order in the way things are implemented!

Fixing the MapShapeDrawBehavior bug

This is a bit of odd one – apparently the developer that made the MapShapeDrawBehavior – a knucklehead who names himself “LocalJoost” ;-) -  has made an error implementing data binding – while he implemented listening to all the collection events correctly, he never apparently anticipated the initial collection might have some values before data binding ensued. The advantage of open source is that we actually can see this. So, we either have to copy MapShapeDrawBehavior ‘s code and make a manual fix to make sure some event occurs that makes it go draw the stuff – or implement a band-aid that does not interfere with the existing code.

I pulled out the band, aid, and made the following class:

using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Collections.Specialized;

namespace Wp7nl.Utilities
{
  public class ResettableObservableCollection<T> : ObservableCollection<T>
  {
    public ResettableObservableCollection()
    {
    }

    public ResettableObservableCollection(List<T> list)
      : base(list)
    {
    }

    public ResettableObservableCollection(IEnumerable<T> list)
      : base(list)
    {
    }

    public void ForceReset()
    {
      OnCollectionChanged(
       new NotifyCollectionChangedEventArgs(NotifyCollectionChangedAction.Reset));
    }
  }
}

I changed both RouteCoordinates and Maneuvers in RoutingViewmodel into ResettableObservableCollection, added the following command to RoutingViewmodel:

[DoNotSerialize]
public ICommand MapLoadedCommand
{
  get
  {
    return new RelayCommand( ()=>
        {
          RouteCoordinates.ForceReset();
          Maneuvers.ForceReset();
        });
  }
}

and finally, the following piece of XAML to the map:

<i:Interaction.Triggers>
  <i:EventTrigger  EventName="Loaded">
    <Command:EventToCommand Command="{Binding MapLoadedCommand}"/>
  </i:EventTrigger>
</i:Interaction.Triggers

imageThis will fire the command directly after the map has loaded. Data binding has already occurred then. And sure enough, even after restarting the app, everything is reloaded from storage. The behavior is tricked into believing it should draw it’s stuff. Now I only need to publish my app, and inform this LocalJoost character that his library contains bugs and if he can fix them ASAP, thank you very much.

Concluding remarks

This series did not only show you the basics of Windows Phone 8 navigation, but also how to develop geo-applications on Windows Phone 8 using unit/integration test to explore and test functionality, as well as using test as a way to hunt down and fix bugs. It also showed that if your test are incomplete, you might get bitten. And finally it showed you that, in the end, you still need to test manually to catch bugs that are caused by dunderheads making errors in their published code ;-)

The final solution can be found here,

10 May 2013

Windows Phone 8 navigation part 3–assembling the MVVMLight app

Last time on, on Dotnetbyexample…

In the first post I described how to write the business logic to find a location by searching for an address by text, and in the second post I described how to do some actual routing – still, only business logic and viewmodels. And we kept in mind all the results should be tombstonable, and how to make sure this all worked by using simple unit/integration tests.

Today, it’s time for the actual app. Bear in mind this post will actually refer to a lot of earlier other posts – from even outside this series. In this post I am also going to show you that working with you designer sometimes means you need to make little tweaks to your viewmodels to make it work the way you want, or make life easier on the designer. Remember, you are the technician, the person who needs to make it finally work.

GUI and interaction design

So, after conferring with the designer we have agreed the app should work like this:

Windows Phone 8 navigate by MVVMLight

The route is displayed as a line, every maneuver as a star, and when you tap that star it should show a panel showing the maneuver description. For interested parties – this is a car route I could take to my home to my work at Vicrea ;-)

Well – the moving panels are easy to solve with some View States and DataTriggers – I’ve been down that road before. Showing a line and points on a map from the view model – been there done that, wrote behaviors for that and those are snugly in the wp7nl library which is, not quite coincidental, part of this solution already.

So, we need to do the following: 

  • Define the app user interface, that is:
    • Two panels enabling the user to input text and select a route, e.g. a user interface for both the GeocodeViewModels in RoutingViewmodel. We’ll make a user control from that
    • A panel with From/To info making showing the address from an to, and making it possible to let the From and To panel into view. This will be a user control as well
    • A button firing off the RoutingViewmodel’s DoRoutingCommand
    • A panel that’s shown as the user taps a maneuver. This, too, will be a user control.
    • A Map
  • A MainViewModel that’s acting as a kind of locator and a serialization root point, like I always do.
  • Something to handle the view state.

Adding ViewState management

Just like I did before in this post, I added a DisplayState enumeration in de NavigationDemo.Logic project, like this:

namespace NavigationDemo.Logic.States
{
  public enum DisplayState
  {
    Normal = 0,
    SearchFrom = 1,
    SearchTo = 2,
    ShowManeuver = 3
  }
}
one state for every panel, and a “Normal” state for every other panel. And then I decided to take the easy way out and add the state control to the RoutingViewmodel, basically to make data binding easier. Of course I could have made a separate view model for this, but what the heck, it’s only a few lines of code anyway:
[DoNotSerialize]
public ICommand DisplayPopupCommand
{
  get
  {
    return new RelayCommand<string>(
        p =>
        {
          DisplayState = (DisplayState)Enum.Parse(typeof(DisplayState), p);
        });
  }
}

private DisplayState displayState;
public DisplayState DisplayState
{
  get { return displayState; }
  set
  {
    if (displayState != value)
    {
      displayState = value;
      RaisePropertyChanged(() => DisplayState);
    }
  }
}    

It makes life easier on the designer, he does not have mess around with data context so much. The property is the actual storage for the DisplayState, and the command sets the display state to it's parameter. All described before. The final piece is a little adaption in the SelectedManeuver property, there we need to add in the setter:

DisplayState = SelectedManeuver != null ? DisplayState.ShowManeuver : DisplayState.Normal;
directly behind the RaisePropertyChanged. This will have the panel showed automatically when a non-null value is detected after the setter has been accessed. 

imageGeocodeViewModel ui

I tend to put user controls into a separate folder UserControls (never been one for original naming conventions anyway). The design of the GeocodeControl looks like this:

And I’ve put it in XAML like this:

<UserControl.Resources>
  <DataTemplate x:Key="AddressTemplate">
    <Grid>
      <TextBlock HorizontalAlignment="Left" TextWrapping="Wrap" Text="{Binding Address}"
VerticalAlignment="Top"/> </Grid> </DataTemplate> </UserControl.Resources> <Grid x:Name="LayoutRoot" Background="{StaticResource PhoneChromeBrush}"> <Grid Margin="12,0" > <!-- Definitions omitted --> <Button Grid.Column="2" Style="{StaticResource RoundButton}" Command="{Binding SearchLocationCommand, Mode=OneWay}" VerticalAlignment="Bottom" HorizontalAlignment="Left" Height="72" Width="72"
Margin="0,0,-5,0" > <Rectangle Fill="{StaticResource PhoneForegroundBrush}" Width="44" Height="44" > <Rectangle.OpacityMask> <ImageBrush ImageSource="/images/feature.search.png" Stretch="Fill"/> </Rectangle.OpacityMask> </Rectangle> </Button> <TextBlock TextWrapping="Wrap" Text="Search" VerticalAlignment="Center"
Height="27" Margin="0,23,0,22" /> <TextBlock TextWrapping="Wrap" Text="Found" Grid.Row="1"
VerticalAlignment="Center" Height="27"/> <TextBox Grid.Column="1" TextWrapping="NoWrap"
Text="{Binding SearchText, Mode=TwoWay}"> <i:Interaction.Behaviors> <Behaviors:TextBoxChangeModelUpdateBehavior/> </i:Interaction.Behaviors> </TextBox> <ListBox Grid.Column="1" Grid.Row="1" Margin="12" ItemsSource="{Binding MapLocations}" SelectedItem="{Binding SelectedLocation,Mode=TwoWay}" ItemTemplate="{StaticResource AddressTemplate}"/> <Button Content="Done" Grid.Row="2" Grid.Column="1" VerticalAlignment="Center" Margin="0,23,0,22" Height="71" Command="{Binding DoneCommand}"/> </Grid> </Grid>

There will be two instances of this user control – one to determine the “From” address, and one for the “”To” address.

There are some things to note here, all underlined in red:

  • I am using a RoundButton style to get a round button, to show an standard image feature_search.png. I pulled this ages ago from this post by Alex Yakhnin if I am not mistaken.
  • There is no data context set, therefore, the data context – a GeocodeViewModel – should be set in the parent element. No problem. But the DoneCommand, which should dismiss the panel, is therefore also in the GeocodeViewModel, and there is no code for that. Worse, the actual state control logic is in a totally different view model – in this case the RoutingViewmodel. Two view models, having no real knowledge of each other, yet needing to get some data across – that spells m-e-s-s-e-n-g-e-r.

Adding some Messenger magic

We define a simple message “DoneMessage” that, when received by the RoutingViewmodel (that also keeps the view state) will dismiss all popups. It’s pretty easy to implement:

namespace NavigationDemo.Logic.Messages
{
  public class DoneMessage{ }
}

And in the RoutingViewmodel, in the constructor, just one line:

Messenger.Default.Register<DoneMessage>(this, 
msg => DisplayState = DisplayState.Normal);

Well, okay, one line split in two ;). But anyway, this allows to add a DoneCommand in GeocodeViewModel simply like this:

[DoNotSerialize]
public ICommand DoneCommand
{
  get
  {
    return new RelayCommand(() => Messenger.Default.Send(new DoneMessage()));
  }
}

And boom – executing the DoneCommand in RoutingViewmodel will reset the DisplayState to Normal, dismissing all popups. That is, as soon as we have implemented the DataTriggers and the ViewStates ;-)

imageLocationPanel

This is the thing used to scroll the GeocodeControls into view, looking like this

<Grid Height="144" VerticalAlignment="Top" Background="#7F000000">
  <Grid Margin="12,0">
    <Grid >
      <!-- Definitions omitted -->
      <TextBlock TextWrapping="Wrap" Text="From" VerticalAlignment="Top"
Margin="0,12,0,0" Height="27" /> <TextBlock TextWrapping="Wrap" Text="To" Grid.Row="1" VerticalAlignment="Top"
Margin="0,12,0,0" Height="27"/> <TextBlock TextWrapping="Wrap" Text="{Binding FromViewModel.SelectedLocation.Address, Mode=TwoWay}" Grid.Column="1" VerticalAlignment="Top" Margin="0,12,0,0" /> <TextBlock TextWrapping="Wrap" Text="{Binding ToViewModel.SelectedLocation.Address, Mode=TwoWay}" Grid.Row="1" Grid.Column="1" VerticalAlignment="Top" Margin="0,12,0,0" /> <Button Grid.Column="2" Style="{StaticResource RoundButton}" Command="{Binding DisplayPopupCommand, Mode=OneWay}" CommandParameter="SearchFrom" VerticalAlignment="Center" HorizontalAlignment="Left" Height="72"
Width="72" Margin="0,0,-10,0" > <!-- Rounded button stuff omitted --> </Button> <Button Grid.Column="2" Grid.Row="1" Style="{StaticResource RoundButton}" Command="{Binding DisplayPopupCommand, Mode=OneWay}" CommandParameter="SearchTo" VerticalAlignment="Center" HorizontalAlignment="Left" Height="72" Width="72"
Margin="0,0,-10,0"> <!-- Rounded button stuff omitted --> </Button> </Grid> </Grid> </Grid>

for the sake of brevity I cut some things out of the XAML. Most interesting to note here, once again red and underlined:

  • The 3nd and the 4th TextBlock show the Address of the Selected location of the From and the To GeocodeViewModel
  • The buttons both call the same command, but with a parameter – this will determine which popup appears. Or actually, the viewstate which will be selected, but that amounts to the same

imageManeuverPopup

This is the popup that appears from the side, as the user has tapped on a start.

It’s a pretty simple piece, both how it looks and in XAML:

<Grid x:Name="LayoutRoot" Background="{StaticResource PhoneChromeBrush}" Opacity="0.9">
  <Grid Margin="12,0" >
    <Grid.RowDefinitions>
      <RowDefinition Height="*"/>
      <RowDefinition Height="76"/>
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
    </Grid.ColumnDefinitions>
    <TextBlock Grid.Row="0" TextWrapping="Wrap" Text="{Binding Description}" 
      HorizontalAlignment="Center"/>
    <Button Content="Close" Grid.Row="1" VerticalAlignment="Center"     
      Height="71" Width="313" Command="{Binding DoneCommand}" />
  </Grid>
</Grid>

With only one thing really to note – this popup needs to be able to be dismissed to – so we can implement the exact same DoneCommand as in GeocodeViewModel and put it into ManeuverViewModel. Copy – paste – done. Of course you can also make a base class for both viewmodels and making both GeocodeViewModel ManeuverViewModel child classes of it. This won’t save you much code in this case though.

MainViewModel

This is kinda not very interesting – see for an explanation on usage this post, that’s quite old already. MainViewModel is the root for all view model, used as a starting point for data binding and tomb stoning But this is what we are going to use a binding root. How the initialization and tombstoning from App.xaml.cs is working is described in the same post, some I am not going to repeat that. This particular MainViewModel looks like this:

using GalaSoft.MvvmLight;
using NavigationDemo.Logic.Models;

namespace NavigationDemo.Logic.ViewModels
{
  public class MainViewModel : ViewModelBase
  {
    public NavigationModel Model { get; set; }

    public MainViewModel()
    {
    }

    public MainViewModel(NavigationModel model)
    {
      Model = model;
    }

    private RoutingViewmodel routingViewModel;
    public RoutingViewmodel RoutingViewModel
    {
      get
      {
        if (routingViewModel == null)
        {
          routingViewModel = new RoutingViewmodel(Model);
        }
        return routingViewModel;
      }
      set
      {
        if (routingViewModel != value)
        {
          routingViewModel = value;
          RaisePropertyChanged(() => RoutingViewModel);
        }
      }
    }

    private static MainViewModel instance;
    public static MainViewModel Instance
    {
      get
      {
        return instance;
      }
      set { instance = value; }
    }

    public static MainViewModel CreateNew()
    {
      if (instance == null)
      {
        instance = new MainViewModel(new NavigationModel());
      }
      return instance;
    }
  }
}

We define it as a data source in App.Xaml

<ViewModels:MainViewModel x:Key="MainViewModelDataSource"/>
Which requires the following definition in your App.xaml header:
xmlns:ViewModels="clr-namespace:NavigationDemo.Logic.ViewModels;assembly=NavigationDemo.Logic"

MainPage.xaml – the main gui

Initially, this has four major parts:

  • The header
  • The Map
  • The three routing panels (2x GeocodeControl + 1x  LocationPanel)
  • The ManeuverPopup
  • The search button.

Now the header is simple enough:

<Grid x:Name="LayoutRoot" Background="Transparent" 
  DataContext="{Binding Instance, Source={StaticResource MainViewModelDataSource}}">
  <Grid.RowDefinitions>
    <RowDefinition Height="Auto"/>
    <RowDefinition Height="*"/>
  </Grid.RowDefinitions>

  <StackPanel x:Name="TitlePanel" Grid.Row="0" Margin="12,17,0,28">
    <TextBlock Text="NAVIGATE BY MVVMLIGHT" 
      Style="{StaticResource PhoneTextNormalStyle}" Margin="12,0"/>
  </StackPanel>

The only more or less interesting part is the data binding. Then comes the map. This uses my MapShapeDrawBehavior to bind the shapes to map:

<Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0" 
   DataContext="{Binding RoutingViewModel}">
  <maps:Map Wp8nl_MapBinding:MapBindingHelpers.MapArea="{Binding ViewArea}"
              Center="{Binding MapCenter, Mode=TwoWay}"
              ZoomLevel="{Binding ZoomLevel, Mode=TwoWay}">
    <i:Interaction.Behaviors>
      <MapBinding:MapShapeDrawBehavior LayerName="Route" ItemsSource="{Binding RouteCoordinates}" 
        PathPropertyName="Geometry">
        <MapBinding:MapShapeDrawBehavior.ShapeDrawer>
          <MapBinding:MapPolylineDrawer Color="Green" Width="10"/>
        </MapBinding:MapShapeDrawBehavior.ShapeDrawer>
      </MapBinding:MapShapeDrawBehavior>
      <MapBinding:MapShapeDrawBehavior LayerName="Maneuvers" ItemsSource="{Binding Maneuvers}" 
        PathPropertyName="Location">
        <MapBinding:MapShapeDrawBehavior.ShapeDrawer>
          <MapBinding:MapStarDrawer Color="Red" Arms="8" InnerRadius="25" OuterRadius="50"/>
        </MapBinding:MapShapeDrawBehavior.ShapeDrawer>
        <MapBinding:MapShapeDrawBehavior.EventToCommandMappers>
          <MapBinding:EventToCommandMapper EventName="Tap" CommandName="SelectCommand"/>
        </MapBinding:MapShapeDrawBehavior.EventToCommandMappers>
      </MapBinding:MapShapeDrawBehavior>
  </maps:Map>

Things of notice here:

  • The grid where the map is in (and incidentally, almost the whole user interface, has the RoutingViewModel as it’s data context.
  • Map view area is not bindable so that’s bound using a simple attached dependency property, I will include this in the coming version for the wp7nl library on codeplex but skip it for now. Center and ZoomLevel are simple direct property bindings
  • The actual route is a green line, bound to RouteCoordinates. TheMapShapeDrawBehavior actually expects a list of objects, so we gave it a list, remember from the previous post?
  • The Maneuvers are display as red stars, by binding a MapShapeDrawBehavior to the Maneuvers list. If one is tapped, the SelectCommand on the ManeuverViewModel is fired, causing the the selected maneuver to be sent over the Messenger

Next, are the three panels:

<UserControls:LocationsPanel VerticalAlignment="Top"/>
<UserControls:GeocodeControl x:Name="GeocodeFrom" VerticalAlignment="Top" 
        RenderTransformOrigin="0.5,0.5" 
        DataContext="{Binding FromViewModel}">
  <UserControls:GeocodeControl.RenderTransform>
    <CompositeTransform TranslateY="-326"/>
  </UserControls:GeocodeControl.RenderTransform>
</UserControls:GeocodeControl>
<UserControls:GeocodeControl x:Name="GeocodeTo" VerticalAlignment="Top" 
       RenderTransformOrigin="0.5,0.5"
       DataContext="{Binding ToViewModel}">
  <UserControls:GeocodeControl.RenderTransform>
    <CompositeTransform TranslateY="-326"/>
  </UserControls:GeocodeControl.RenderTransform>
</UserControls:GeocodeControl>
<UserControls:ManeuverPopup x:Name="maneuverPopup" VerticalAlignment="Bottom" 
     Height="151" RenderTransformOrigin="0.5,0.5" Margin="0,0,0,72"
     DataContext="{Binding SelectedManeuver}">
  <UserControls:ManeuverPopup.RenderTransform>
    <CompositeTransform TranslateX="470"/>
  </UserControls:ManeuverPopup.RenderTransform>
</UserControls:ManeuverPopup>

Actually rather straightforward. From panel binds to FromViewModel, To panel to ToViewModel, and the maneuverPopup to SelectedManeuver.

The last part ain’t rocket sciece: just a simple BindableApplicationBar with one button executing the actual routing command:

<phone7Fx:BindableApplicationBar BarOpacity="0.9" >
  <phone7Fx:BindableApplicationBarIconButton Command="{Binding RoutingViewModel.DoRoutingCommand}"
                                             IconUri="/images/feature.search.png"
                                             Text="Route" />
</phone7Fx:BindableApplicationBar>

The only thing to notice is that since it’s sitting outside the content panel, in the main grid, it’s data content is het MainViewModel to I have to prepend the RoutingViewModel again.

DataTrigger Animation Magic

I am going to keep this simple: if you want to know how to create this, I suggest you read my article on ViewModel driven multi-state animations using DataTriggers and Blend on Windows Phone. I have created the following visual states:

<VisualStateManager.CustomVisualStateManager>
  <ei:ExtendedVisualStateManager/>
</VisualStateManager.CustomVisualStateManager>
<VisualStateManager.VisualStateGroups>
  <VisualState x:Name="Normal"/>
  <VisualStateGroup x:Name="Search">
    <VisualStateGroup.Transitions>
      <VisualTransition GeneratedDuration="0:0:0.5"/>
    </VisualStateGroup.Transitions>
    <VisualState x:Name="SearchFrom">
      <Storyboard>
        <DoubleAnimation To="0" 
          Storyboard.TargetProperty="(UIElement.RenderTransform).(CompositeTransform.TranslateY)" 
          Storyboard.TargetName="GeocodeFrom"/>
      </Storyboard>
    </VisualState>
    <VisualState x:Name="SearchTo">
      <Storyboard>
        <DoubleAnimation To="0" 
          Storyboard.TargetProperty="(UIElement.RenderTransform).(CompositeTransform.TranslateY)" 
          Storyboard.TargetName="GeocodeTo"/>
      </Storyboard>
    </VisualState>
     <VisualState x:Name="ShowManeuver">
      <Storyboard>
        <DoubleAnimation Duration="0" To="0" 
          Storyboard.TargetProperty="(UIElement.RenderTransform).(CompositeTransform.TranslateX)" 
          Storyboard.TargetName="maneuverPopup" />
      </Storyboard>
    </VisualState>
  </VisualStateGroup>
</VisualStateManager.VisualStateGroups>
You can see “Search” moves “GeocodeFrom”  into view, “SearchTo” moves GeocodeTo into view, and “ShowManeuver”  shows the maneuverPopup. And Normal is the base state, basically moving everything back to it’s base place, i.e. out of the screen. I also created these data triggers.
 <i:Interaction.Triggers>
  <ei:DataTrigger Binding="{Binding DisplayState}" Value="0">
    <ei:GoToStateAction StateName="Normal" />
  </ei:DataTrigger>
  <ei:DataTrigger Binding="{Binding DisplayState}" Value="1">
    <ei:GoToStateAction StateName="SearchFrom" />
  </ei:DataTrigger>
  <ei:DataTrigger Binding="{Binding DisplayState}" Value="2">
    <ei:GoToStateAction StateName="SearchTo" />
  </ei:DataTrigger>
  <ei:DataTrigger Binding="{Binding DisplayState}" Value="3">
    <ei:GoToStateAction StateName="ShowManeuver" />
  </ei:DataTrigger>
</i:Interaction.Triggers>

These are all sitting inside the contentpanel, right above the map.

And finally… well… not really

If you run the app now – or download the sample solution, lo and behold – the app works as designed. That is … until you press the start button and start the app anew. You will notice the fact that although the right location is displayed, the route is not, the LocationPanel is empty again, but the search text is not. How the hell is this possible? We have written test till the cows came home!

Well, I can tell you we have run in some very subtle serialization bugs. Fixing those bugs is what we are going to do in the next and last episode. Like I said in the previous episode, no amount of unit and/or integration testing is going to free you from manually testing your app – is just a tool to increase, maintain and guarantee the quality of some parts of your app.

Anyway – the solution so far can be downloaded here.

01 May 2013

Windows Phone 8 navigation part 2–routing, route details,tombstoning–and testing

What happened last time on this show

In the previous post I described to how to write the business logic to find a location by searching for an address by text, how to be able to tombstone the results, and how to make sure this all worked by using simple tests. Fine, but the purpose was routing, that is, actually making the app finding instructions to get from A to B. As a GIS buff, being used to complex algorithms and stuff, this is almost embarrassingly easy in Windows Phone 8. You basically need an object of type RouteQuery, plonk in any number of waypoints (at least two, of course, being the start and the end) and a method of transport (drive or walk). And that’s basically it.

But we still have to honor the other two requirements – in needs to be testable and serializable so we can support tombstoning

Find the route, Luke phone

So in the solution I created last time I add another business class that does the actual finding of the route:

using System.Collections.Generic;
using System.Device.Location;
using System.Threading.Tasks;
using Microsoft.Phone.Maps.Services;
using Wp7nl.Utilities;

namespace NavigationDemo.Logic.Models
{
  public class NavigationModel
  {
    public NavigationModel()
    {
      From = new GeocodeModel();
      To = new GeocodeModel();
    }

    public async Task DoRouting()
    {
      await DoRouting(From.SelectedLocation.GeoCoordinate, 
                      To.SelectedLocation.GeoCoordinate);
    }

    public async Task DoRouting(GeoCoordinate from, GeoCoordinate to)
    {
      var wayPoints = new List<GeoCoordinate>(new[] { from, to });
      var routeQuery = new RouteQuery 
        { TravelMode = TravelMode.Driving, Waypoints = wayPoints };
      FoundRoute = await routeQuery.GetRouteAsync();
    }

    public Route FoundRoute { get; set; }   

    public GeocodeModel From { get; set; }

    public GeocodeModel To { get; set; }
  }
}

This comes in the NavigationDemo.Logic project, in the Models folder, next to GeocodeModel. Here you can see what I just mentioned – the actual navigation logic is very simple. This whole model comes down to three lines (red, bold and underlined). But, does this work?

Testing the routing

In the unit test app I added a NavigationModelTest class. To ease testing, I created public overload method where I can directly supply the waypoints. We already know the GeocodeModel works. We have tested that before.

using System;
using System.Device.Location;
using System.Linq;
using System.Threading;
using System.Windows;
using Microsoft.VisualStudio.TestPlatform.UnitTestFramework;
using NavigationDemo.Logic.Models;

using Wp7nl.Utilities;
namespace NavigationDemo.Logic.Test { [TestClass] public class NavigationModelTest { [TestMethod] public void TestPointRouting() { var m = new NavigationModel(); var waitHandle = new AutoResetEvent(false); Deployment.Current.Dispatcher.BeginInvoke(async () => { await m.DoRouting( new GeoCoordinate(52.182679977268, 5.39752000942826), new GeoCoordinate(52.1061999723315, 5.03457002341747)); waitHandle.Set(); }); waitHandle.WaitOne(TimeSpan.FromSeconds(25)); Assert.IsTrue(m.FoundRoute.Geometry.Any()); } } }

Route finding is async as well and needs to run on the UI thread, hence the hoopla with the AutoResetEvent and the Dispatcher. Basically I ask the the RouteQuery to find some route from one place to another in the Netherlands. For those interested: it’s a road I drove for many a hackathon – from my street to the street where our former Dutch DPE Matthijs Hoekstra used to live before he decided to go upstream to Seattle to join the Windows Phone team. I actually seem to recall I wrote this very code in his house at the last ‘kitchen table’ hackathon :-)

There are two things to wonder at at this point:

  1. Will this serialize to support tombstoning? (remember from the previous post the MapLocation that came back from GeocodeQuery did not)
  2. What the hell is it that we find?

Does this serialize?

I added a second test to NavigationModelTest  which is basically an extended version of the first.

[TestMethod]
public void TestStoreNavigationModel()
{
  var m = new NavigationModel();

  var waitHandle = new AutoResetEvent(false);

  Deployment.Current.Dispatcher.BeginInvoke(async () =>
  {
    await m.DoRouting(
        new GeoCoordinate(52.182679977268, 5.39752000942826),
        new GeoCoordinate(52.1061999723315, 5.03457002341747));
    waitHandle.Set();
  });

  waitHandle.WaitOne(TimeSpan.FromSeconds(25));

  var h = new IsolatedStorageHelper<NavigationModel>();
  if (h.ExistsInStorage())
  {
    h.DeletedFromStorage();
  }
  h.SaveToStorage(m);

  var retrieved = h.RetrieveFromStorage();

  Assert.IsTrue(retrieved.FoundRoute.Geometry.Any());
}

And here we go again: the test fails with SilverlightSerializer complaining that “Could not construct an object of type 'Microsoft.Phone.Maps.Services.Route', it must be creatable in this scope and have a default parameterless constructor”. So we basically have the same problem we had in the previous post. The way to make this test work is to adorn FoundRoute in NavigationModel

[DoNotSerialize]
public Route FoundRoute { get; set; }
and change the last line of test a little
Assert.IsNotNull(retrieved);

The test now succeeds, but the route you found is now of course still not serialized. You can wonder (or gripe on twitter) why Microsoft have implemented it this way, but that won’t get your app any closer to shipping. It simply means we have to defer tombstoning of the found route to the viewmodel again, just like in the previous post.

What DO we get back?

Actually, quite a lot. The routing information is very detailed. The main Route class has the following properties and methods:

public class Route : IRoutePath
{
  public LocationRectangle BoundingBox { get; internal set; }
  public TimeSpan EstimatedDuration { get; internal set; }
  public ReadOnlyCollection<Device.Location.GeoCoordinate> Geometry 
{ get; internal set; } public ReadOnlyCollection<RouteLeg> Legs { get; internal set; } public int LengthInMeters { get; internal set; } }

A route can exist out of multiple RouteLeg objects (if you give the RouteQuery more than two waypoints. RouteLeg is defined as follows:

public class RouteLeg : IRoutePath
{
  public LocationRectangle BoundingBox { get; internal set; }
  public TimeSpan EstimatedDuration { get; internal set; }
  public ReadOnlyCollection<Device.Location.GeoCoordinate> Geometry 
        { get; internal set; }
  public int LengthInMeters { get; internal set; }
  public ReadOnlyCollection<RouteManeuver> Maneuvers 
       { get; internal set; }
}

Which makes me feel that a RouteLeg and a Route are nearly the same object and there might have been some code re-use possibilities, but I digress. A RouteLeg consists, apart from a geometry, out of various RouteManeuvers, which look like this:

public class RouteManeuver
{
  public RouteManeuverInstructionKind InstructionKind { get; internal set; }
  public string InstructionText { get; internal set; }
  public int LengthInMeters { get; internal set; }
  public GeoCoordinate StartGeoCoordinate { get; internal set; }
}

The InstructionText literally contains stuff like “Turn left on xyz street” and a location where this should happen. RouteManeuverInstructionKind is an enum describing the kind of instruction and really is so comprehensive it’s actually a bit hilarious, so go and have a look on it. But you can very much use this to depict what you the driver needs to do, and I am pretty sure this is what Nokia’s “Here Drive”  uses under the hood. So here we have a full fledged routing API under the hood – but there’s no way in Hades we are ever going to serialize that will all those internal sets, as we already ascertained.

In real life, at this point you really need to confer with the stakeholder and the designer – what is it what we are going to show and how we are going to show it? Since I am both and developer at this point, I decided I want to show the route on the map as a line, the maneuvers (being the point where you actually need to do something) as symbols you can tap on, and having a window with the InstructionText to pop up as you do. Basically we’ll end up with a simple routing system in stead of a full fledged navigation app, but we have to start somewhere. And being the lazy *** I am, I am going to re-use the map binding behavior I wrote last year for Windows 8 and Windows Phone 8. But that’s later. First the view models.

Enter the viewmodels – again

The first, and most simple viewmodel is for handling the maneuver we are going to show in the popup

using System.Windows.Input;
using GalaSoft.MvvmLight;
using GalaSoft.MvvmLight.Command;
using GalaSoft.MvvmLight.Messaging;
using Microsoft.Phone.Maps.Controls;
using Wp7nl.Utilities;

namespace NavigationDemo.Logic.ViewModels
{
  public class ManeuverViewModel: ViewModelBase
  {
    private GeoCoordinateCollection location;
    public GeoCoordinateCollection Location
    {
      get { return location; }
      set
      {
        if (location != value)
        {
          location = value;
          RaisePropertyChanged(() => Location);
        }
      }
    }

    private string description;
    public string Description
    {
      get { return description; }
      set
      {
        if (description != value)
        {
          description = value;
          RaisePropertyChanged(() => Description);
        }
      }
    }

    [DoNotSerialize]
    public ICommand SelectCommand
    {
      get
      {
        return new RelayCommand(
            () => Messenger.Default.Send(this),
            () => true);
      }
    }
  }
}

The command firing of the object itself over the Messenger is a time-tested and tried method I use – if a user selects an object from a list, let a viewmodel that has the actual list of these objects as a property – I call that the ‘parent’ - handle the select. This prevents a whole lot who messing around with data contexts. Be nice to your designer ;-). Also note the geometry in this class is a GeoCoordinateCollection – although the maneuver is a point, my MapShapeDrawBehavior needs a GeoCoordinateCollection, because it does not know in advance if it needs to draw a point or a shape.

The next one is a bit awkward and also direct result of the way my MapShapeDrawBehavior behavior works – it needs a list of objects with a property that’s a GeoCoordinateCollection – this being the geometry. But the RouteLeg gives me a ReadOnlyCollection<GeoCoordinate> and we have only one object – one route. So I write a simple wrapper viewmodel to make sure that it has:

using System.Collections.Generic;
using System.Device.Location;
using GalaSoft.MvvmLight;
using Microsoft.Phone.Maps.Controls;
using Wp7nl.Utilities;

namespace NavigationDemo.Logic.ViewModels
{
  public class RouteGeometryViewModel : ViewModelBase
  {
    public RouteGeometryViewModel()
    {
    }

    public RouteGeometryViewModel(IEnumerable<GeoCoordinate> coordinates)
    {
      Geometry = new GeoCoordinateCollection();
      Geometry.AddRange(coordinates);
    }

    private GeoCoordinateCollection geometry;
    public GeoCoordinateCollection Geometry
    {
      get { return geometry; }
      set
      {
        if (geometry != value)
        {
          geometry = value;
          RaisePropertyChanged(() => Geometry);
        }
      }
    }
  }
}

… and make sure the viewmodel holding this object has a list of these.

And finally, the RoutingViewModel itself, that starts like this:

using System.Collections.ObjectModel;
using System.Device.Location;
using System.Linq;
using System.Threading.Tasks;
using System.Windows.Input;
using GalaSoft.MvvmLight;
using GalaSoft.MvvmLight.Command;
using GalaSoft.MvvmLight.Messaging;
using Microsoft.Phone.Maps.Controls;
using NavigationDemo.Logic.Models;
using Wp7nl.Utilities;

namespace NavigationDemo.Logic.ViewModels
{
  public class RoutingViewmodel : ViewModelBase
  {
    public RoutingViewmodel()
    {
      Maneuvers = new ObservableCollection<ManeuverViewModel>();
      RouteCoordinates = new ObservableCollection<RouteGeometryViewModel>();

      Messenger.Default.Register<ManeuverViewModel>(this, 
                                                    p => SelectedManeuver = p);
    }

    public RoutingViewmodel(NavigationModel model)
      : this()
    {
      Model = model;
    }

    private ManeuverViewModel selectedManeuver;
    public ManeuverViewModel SelectedManeuver
    {
      get { return selectedManeuver; }
      set
      {
        selectedManeuver = value;
        RaisePropertyChanged(() => SelectedManeuver);
      }
    }

    public ObservableCollection<RouteGeometryViewModel> RouteCoordinates 
{ get; set; } public ObservableCollection<ManeuverViewModel> Maneuvers { get; set; } } }

In the default constructor sits the standard initialization of the ObservableCollection types, as well as the setup for ManeuverViewModel select interception. Further below another constructor to make initialization from code easier, and the SelectedManeuver property. Nothing special here yet. We add two viewmodels for both to and from searching:

private GeocodeViewModel toViewModel;
public GeocodeViewModel ToViewModel
{
  get { return toViewModel; }
  set
  {
    if (toViewModel != value)
    {
      toViewModel = value;
      RaisePropertyChanged(() => ToViewModel);
    }
  }
}

private GeocodeViewModel fromViewModel;
public GeocodeViewModel FromViewModel
{
  get { return fromViewModel; }
  set
  {
    if (fromViewModel != value)
    {
      fromViewModel = value;
      RaisePropertyChanged(() => FromViewModel);
    }
  }
}

And then the public model property as well, with some clever skullduggery here:

private NavigationModel model;
public NavigationModel Model
{
  get { return model; }
  set
  {
    model = value;
    if (model != null)
    {
      ToViewModel = new GeocodeViewModel(model.To) { Name = "To" };
      FromViewModel = new GeocodeViewModel(model.From) { Name = "From" };
    }
  }
}

The “Name” property has no function whatsoever in the code, but I assure you – if you have two identical viewmodels in your app, having them easily distinguishable by a simple property that you can see in a breakpoint helps a ton!

Finally, the piece that does the actual routing:

public async Task DoRouting()
{
  await DoRouting(
   FromViewModel.SelectedLocation.Location,
   ToViewModel.SelectedLocation.Location);
}

public async Task DoRouting(GeoCoordinate from, GeoCoordinate to)
{
  RouteCoordinates.Clear();
  Maneuvers.Clear();
  await Model.DoRouting(from, to);
  RouteCoordinates.Add(new RouteGeometryViewModel(Model.FoundRoute.Geometry));
  ViewArea = Model.FoundRoute.BoundingBox;
  Model.FoundRoute.Legs.ForEach(r =>
  Maneuvers.AddRange(
    r.Maneuvers.Select(
      p => new ManeuverViewModel { 
Description = p.InstructionText,
Location =
new GeoCoordinateCollection { p.StartGeoCoordinate }}))); } [DoNotSerialize] public ICommand DoRoutingCommand { get { return new RelayCommand( async () => { await DoRouting(); }); } }

Once again I have a public overload with just coordinates to make testing easier. The line with all the Lambdas basically iterates over all legs of the route, gets all maneuvers per leg, and creates ManeuverViewModel types of every maneuver, using the StartGeoCoordinate of said maneuver to create location. Also note I put the route’s bounding box into a ViewArea property of the RoutingViewModel (code omitted) to enable the designer to let the map zoom to the extent of the new-found route. In the RoutingViewModel are two more properties I omitted – ZoomLevel and MapCenter, they are with ViewArea taken from the map binding sample I wrote last year.

Well… that’s quite some code. And now the proof of the pudding…

Testing the RoutingViewModel

I added a class RoutingViewModelTest and a simple test method to see if coordinates and maneuvers are duly filled when I call the DoRouting method with coordinates

using System;
using System.Device.Location;
using System.Linq;
using System.Threading;
using System.Windows;
using Microsoft.VisualStudio.TestPlatform.UnitTestFramework;
using NavigationDemo.Logic.Models;
using NavigationDemo.Logic.ViewModels;
using Wp7nl.Utilities;


namespace NavigationDemo.Logic.Test
{
  [TestClass]
  public class RoutingViewModelTest
  {
    [TestMethod]
    public void TestSimpleRoutingViewModel()
    {
      var vm = new RoutingViewmodel(new NavigationModel());

      var waitHandle = new AutoResetEvent(false);

      Deployment.Current.Dispatcher.BeginInvoke(async () =>
      {
        await vm.DoRouting(
            new GeoCoordinate(52.182679977268, 5.39752000942826),
            new GeoCoordinate(52.1061999723315, 5.03457002341747));
        waitHandle.Set();
      });

      waitHandle.WaitOne(TimeSpan.FromSeconds(25));

      Assert.IsTrue(vm.RouteCoordinates.Any());
      Assert.IsTrue(vm.Maneuvers.Any());
    }
  }
}

Which, not entirely surprising, is the case. Now if you follow the TDD pattern correctly, you should add all kinds of mocks and interfaces between these classes and also test every method separately. I decided to go more for the integration test like route – so I made a big test which basically emulates a complete routing request, tombstones it and checks the result.

[TestMethod]
public void TestSearchRoutingViewModelAndTombstoning()
{
  var waitHandle = new AutoResetEvent(false);

  var vm = new RoutingViewmodel(new NavigationModel());
  vm.FromViewModel.SearchText = "Springerstraat Amersfoort Netherlands";
  vm.ToViewModel.SearchText = "Heinrich Bertestraat Utrecht";
  Deployment.Current.Dispatcher.BeginInvoke(async () =>
  {
    await vm.FromViewModel.SearchLocations();
    await vm.ToViewModel.SearchLocations();
    waitHandle.Set();
  });
  waitHandle.WaitOne(TimeSpan.FromSeconds(5));

  Assert.IsTrue(vm.FromViewModel.MapLocations.Any());
  Assert.IsTrue(vm.ToViewModel.MapLocations.Any());

  vm.FromViewModel.SelectedLocation = vm.FromViewModel.MapLocations[0];
  vm.ToViewModel.SelectedLocation = vm.ToViewModel.MapLocations[0];
  Deployment.Current.Dispatcher.BeginInvoke(async () =>
  {
    await vm.DoRouting();
    waitHandle.Set();
  });

  waitHandle.WaitOne(TimeSpan.FromSeconds(5));

  var h = new IsolatedStorageHelper();
  if (h.ExistsInStorage())
  {
    h.DeletedFromStorage();
  }
  h.SaveToStorage(vm);

  var retrievedVm = h.RetrieveFromStorage();

  Assert.IsTrue(vm.RouteCoordinates.Any());
  Assert.IsTrue(vm.Maneuvers.Any());
  Assert.IsTrue(retrievedVm.RouteCoordinates.Count == vm.RouteCoordinates.Count);
  Assert.IsTrue(retrievedVm.FromViewModel.SearchText == 
    "Springerstraat Amersfoort Netherlands");
  Assert.IsTrue(retrievedVm.Maneuvers.Count == vm.Maneuvers.Count);
}

So, I first setup a complete new RoutingViewModel with NavigationModel, simulate the user input two streets and let them search locations. Then I test if there are any locations found at all. I can safely assume they are, since the previous tests worked as well, but still. Then I actually let the app perform routing, ‘tombstone’ the whole viewmodel and retrieve it again.

And then I do a number of tests to check if anything is found at all, and if whatever comes back from storage matches what went into it. It will not surprise you – it does. This test is far from comprehensive – you could test all the properties one by one, but at least you now can have a reasonable confidence in the basic workings of your app. What’s more – if you start changing things and test start failing, you know your app will probably fail too somewhere down the line.

Conclusion (so far)

By using unit/integration testing we have been able to make and test a working model of the app, finding out how stuff work and tackling serialization problems head on before we actually made a user interface at all – therefore eliminating potential double work by both you and your designer. Next time we will actually start assembling the app, and we will learn that no amount of unit testing will eliminate you from the fact that you still need to test your app manually ;-)

Once again, before I get flamed: technically I showed you how to do integration tests, not unit tests, because I tested multiple classes interacting with each other, in stead of single methods and/or properties

As always, a finished solution (if you can call this finished) is available for download here.