MapsTask

The MapsTask has only three properties that you can set. You must set either the Center or SearchTerm (or both); otherwise, an InvalidOperationException will be thrown. Setting the ZoomLevel is optional. Table 8-2 describes the properties of the MapsTask.

Using the MapsTask is simple. Most commonly you will want to find something that is close by, so in Listing 8-2 we will just set the SearchTerm and ZoomLevel and then call the Show method.

Listing 8-2. Finding a Location Using the MapsTask

private void WhereIsIt(object sender, RoutedEventArgs e)
{
    if (string.IsNullOrEmpty(locationToFind.Text))
    {
        MessageBox.Show("Please enter a location.");
    }
    else
    {
        MapsTask mapTask = new MapsTask();
        mapTask.ZoomLevel = 15;
        mapTask.SearchTerm = locationToFind.Text;
        mapTask.Show();
    }
}

MapsDirectionsTask

Probably the most common use case for directions is the desire to be somewhere else. We’ve all had that feeling I’m sure. The MapsDirectionsTask makes it simple to plan your escape. The MapsDirectionsTask has only two properties, Start and End, both of which are of type LabeledMapLocation. See Table 8-3 for the specifics of the LabeledMapLocation class.

The End property will be set to the phone’s current location if it is not set to a valid LabeledMapLocation. The same applies to the Start property. The problem of both the Start and End properties being set to an invalid location is addressed by the task throwing an InvalidOperationException given that you are, in essence, asking it to route you from where you are currently located to your current location.¹

MapDownloaderTask and MapUpdaterTask

The last two tasks are very simple to use and have no properties to set. They rely completely on the built-in functionality. Listing 8-3 and Listing 8-4 show their use, while Figures 8-1 and 8-2 show the respective results.

Listing 8-3. Using the MapDownloaderTask

private void DownloadMaps(object sender, RoutedEventArgs e)
{
    MapDownloaderTask mapDownloaderTask = new MapDownloaderTask();
    mapDownloaderTask.Show();
 
}

Listing 8-4. Using the MapUpdaterTask

private void UpdateMaps(object sender, RoutedEventArgs e)
        {
            MapUpdaterTask mapUpdaterTask = new MapUpdaterTask();
            mapUpdaterTask.Show();
        }

Marking the Current Location

The Windows Phone Toolkit comes with a static class called MapExtensions that uses AttachedProperties to extend the functionality of the Map control. You can examine the source code that comes with the Windows Phone Toolkit to see how it works. The MapExtensions class basically takes each child item, wraps it in a MapOverlayItem, wraps that in a MapOverlay and then puts that into a MapLayer, and finally adds the item to the map. It’s an exercise in convolution to be sure, but it works.

To mark the current location of the phone, we’ll use the UserLocationMarker control that comes with the Toolkit. Create a new project using the Windows Phone App template and then use NuGet to add a reference to the Toolkit. As always, don’t forget to add the ID_CAP_MAP and ID_CAP_LOCATION to the capabilities required by your application. Add the following namespace declaration to the top of the MainPage XAML and then replace the ContentPanel Grid with the XAML in Listing 8-13:

xmlns:toolKit="clr-namespace:Microsoft.Phone.Maps.Toolkit;assembly=Microsoft.Phone.Controls.Toolkit"

Listing 8-13. XAML for the ContentPanel Grid

<Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
    <mapControls:Map x:Name="theMap">
        <toolKit:MapExtensions.Children>
            <toolKit:UserLocationMarker
                Visibility="Collapsed"
                x:Name="UserLocationMarker"/>
        </toolKit:MapExtensions.Children>
    </mapControls:Map>
</Grid>

Next we’ll add some code that you’ve probably already seen in the previous recipe that gets the current location of the device. We’ll also add code to override OnNavigatedTo and set the location of the UserLocationMarker. Listing 8-14 has everything you need.

Listing 8-14. Code to Get and Set the Current Location

private async Task<GeoCoordinate> GetCoordinate()
{
 
    Geolocator locator = new Geolocator();
    GeoCoordinate coordinate;
    locator.DesiredAccuracy = PositionAccuracy.High;
 
    Geoposition position = await locator.GetGeopositionAsync();
 
    coordinate = new GeoCoordinate(position.Coordinate.Latitude,
        position.Coordinate.Longitude);
    return coordinate;
}
 
protected async override void OnNavigatedTo(NavigationEventArgs e)
{
    try
    {
        GeoCoordinate coordinate = await GetCoordinate();
        theMap.Center = coordinate;
        theMap.ZoomLevel = 15;
 
        this.UserLocationMarker =
                      (UserLocationMarker)this.FindName("UserLocationMarker");
        this.UserLocationMarker.GeoCoordinate = coordinate;
        this.UserLocationMarker.Visibility = System.Windows.Visibility.Visible;
         
    }
    catch (Exception)
    {
        MessageBoxResult result = MessageBox.Show("Location services is not enabled.  Would you like to go to the settings page to enable it?", "Error", MessageBoxButton.OKCancel);
        if (result == MessageBoxResult.OK)
        {
            Launcher.LaunchUriAsync(new Uri("ms-settings-location:"));
        }
    }
}

You should now be able to run the application and see a marker at the current location of your phone or the current location of the emulator if you are using one. Figure 8-8 shows the results.

Adding Dynamic Overlays

For the sake of simplicity, let’s imagine that you want to be able to mark some favorite places on the Map by tapping them. The process for doing this is straightforward. You can add pretty much anything you want as an overlay, but it’s advisable to keep it simple.

We’ll add our code in an event handler for the Tap event of the Map. The code in Listing 8-15 is well-commented to describe each step of the process. Add this code to the code-behind of the MainPage and then wire up the handler in XAML. In addition to the code in the listing, also add a private class-level variable to hold a MapLayer.  Figure 8-9 shows the results of tapping on the Map.

private MapLayer layer;

Listing 8-15. Code to Add an Overlay to the Map at the Location Tapped by the User

private void TheMapTap(object sender, System.Windows.Input.GestureEventArgs e)
{
    // create an image using the favs icon
    // that comes with the SDK and add it to
    // a new MapOverlay
    Image image = new Image();
    image.Source = new BitmapImage(new Uri("Assets/footprint.png",
                             UriKind.RelativeOrAbsolute));
     
    MapOverlay overlay = new MapOverlay();
    overlay.Content = image;
 
    // get the position that the user tapped
    Point point = e.GetPosition(theMap);
 
    // the favs icon is 76 x 76 and we want to
    // center it on the point the user tapped
    // so we'll shift the point
    point.X -= 38;
    point.Y -= 38;
 
    // convert the ViewPort point into an actual GeoCoordinate value
    GeoCoordinate coordinate = theMap.ConvertViewportPointToGeoCoordinate(point);
    overlay.GeoCoordinate = coordinate;
 
    // the one and only layer that we
    // add all of the overlays to
    if (layer == null)
    {
        layer = new MapLayer();
        theMap.Layers.Add(layer);
    }
    layer.Add(overlay);
}

Geocoding

Geocoding is the process of discovering the geographic coordinates of a location, commonly expressed as latitude and longitude, based on other geographic data such as street addresses and postal/ZIP codes. This information is premapped in what is generically referred to as a Geographic Information System (GIS). These systems aren’t always about street addresses; in fact, the first operational GIS was developed in the early 1960s by Dr. Roger Tomlinson in Ottawa, Canada, for the Canadian Land Inventory. It mapped things such as soils, recreation, wildlife, forestry, and land use. In the late 1980s CGIS was slowly being rendered obsolete by the emergence of commercial GISs. In the early 1990s, a team of volunteers was successful in extracting all of the CGIS information from tapes, and it’s been made available for free on GeoGratis at http://geogratis.cgdi.gc.ca.

The best way to ensure good results with the GeocodeQuery is to give it as much information about the location you are seeking as possible. An exact and detailed address including a postal code will provide the best results. The other thing to note is that the search needs to be centered on a specific location. The results of the query will change depending on the location because it returns matches based on how close they are to that location. Notice also that I said “matches.” The GeocodeQuery, at least in my experience, will return up to ten possible matches. There is also a MaxResultCount property that you can use to limit the number of results further if you so choose. The first result in the list may or may not be the one you are looking for if a possible match is found that is geographically closer to the GeoCoordinate you set as the center of the search.

Route

A route is the lists of waypoints, legs, and maneuvers that describe how to navigate between two or more locations. A route in Windows Phone 8 is represented by the Microsoft.Phone.Maps.Services.Route class. A Route is returned as the Result of a RouteQuery. A MapRoute instance is constructed by passing a Route to the constructor, and that is added to a Map control for display.

Waypoints

Most commonly we want to be somewhere else. We want to start “here” and go “there.” Other times you may have more than one point along the way that you want to visit. Your starting point is included as a waypoint when configuring the RouteQuery, and the route is constructed based on the order in which the waypoints are added. It’s up to you to determine the most efficient order in which to visit all of the waypoints given specific start and end points. There are advanced routing programs available that, given a start point, an end point, and a list of points in between, will calculate the optimal route through all waypoints. That is not the case with the RouteQuery.

A waypoint is represented by a System.Device.Location.GeoCoordinate. The RouteQuery.Waypoints property takes an IEnumerable<GeoCoordinate>.

Legs

A leg consists of a list of maneuvers that are taken between one waypoint and the next. The number of legs is equal to the number of waypoints minus one. A trip from your home to the bank, the grocery store, and home again would have three legs because there are four waypoints. One of them, your home, is counted at the start and end points even though they are the same geographic location.

1. Home Bank
2. Bank Grocery store
3. Grocery store Home

A leg is represented in code by the Microsoft.Phone.Maps.Services.RouteLeg class.

Maneuvers

Maneuvers are the actions that make up each leg of a route and are represented by the RouteManeuver class in the Microsoft.Phone.Maps.Services namespace. A maneuver contains the list of actions to be taken by a traveler for each leg of the route to get to the next waypoint. Table 8-6 describes the various properties of the RouteManeuver.

Bringing It All Together

Now that we know what all the moving parts are and how they relate to each other, let’s take a look at how to tie them all together into something useful. The first step is to find your current location and set that as the first item in our list of waypoints. This will be the start of our route. We’ll do this in the override of OnNavigatedTo in our MainPage.xaml.cs file, as shown in Listing 8-16.

Listing 8-16. Code to Determine and Set the Current Location of the Device

protected async override void OnNavigatedTo(NavigationEventArgs e)
{
    try
    {
        currentLocation = await GetCurrentLocation();
        App.ViewModel.WayPoints.Clear();
        App.ViewModel.WayPoints.Add(new LocationItem
        {
            Address = "My Location",
            Coordinate = currentLocation
        });
 
    }
    catch (Exception)
    {
        MessageBoxResult result = MessageBox.Show("Location services is not enabled.  Would you like to go to the settings page to enable it?", "Error", MessageBoxButton.OKCancel);
        if (result == MessageBoxResult.OK)
        {
            Launcher.LaunchUriAsync(new Uri("ms-settings-location:"));
        }
    }
}
 
private async Task<GeoCoordinate> GetCurrentLocation()
{
    Geolocator locator = new Geolocator();
    GeoCoordinate coordinate;
    locator.DesiredAccuracy = PositionAccuracy.High;
 
    Geoposition position = await locator.GetGeopositionAsync();
 
    coordinate = new GeoCoordinate(position.Coordinate.Latitude,
        position.Coordinate.Longitude);
 
    return coordinate;
}

The next step, now that we have our starting point, is to look up the GeoCoordinate of each of the destinations we want to add to our route. We do that by using the GeocodeQuery. Setting up and executing the GeocodeQuery is simple, as shown in Listing 8-17; dealing with the results, not so much.

Listing 8-17. Configuring and Executing a GeocodeQuery

codeQuery = new GeocodeQuery();
codeQuery.SearchTerm = App.ViewModel.SearchText;
codeQuery.GeoCoordinate = currentLocation;
codeQuery.QueryCompleted += GeocodeQueryQueryCompleted;
codeQuery.QueryAsync();

As discussed earlier, the more specific the information is that you pass in for the SearchTerm, the more accurate your results are going to be. Including a postal or ZIP code will almost guarantee a match. The GeocodeQuery uses an event-based asynchronous programming model and doesn’t provide an awaitable version of the QueryAsync method. This is a shame since it makes our code more complicated. Listing 8-18 contains the code for our QueryCompleted handler.

Listing 8-18. QueryCompleted Event Handler for Our GeocodeQuery

void GeocodeQueryQueryCompleted(object sender,
    QueryCompletedEventArgs<IList<MapLocation>> e)
{
    App.ViewModel.LocationItems.Clear();
    if (e.Error != null || e.Result.Count == 0)
    {
        string errorText = string.Empty;
        if (e.Error != null)
        {
            GeocodeQueryHresult hresult = (GeocodeQueryHresult)e.Error.HResult;
            errorText = hresult.GetGeocodeQueryHresultDescription();
 
        }
        else
        {
            errorText = "Location not found";
        }
 
        App.ViewModel.LocationItems.Add(new LocationItem { Address = errorText });
    }
    else
    {
        App.ViewModel.LocationItems.Clear();
        foreach (var result in e.Result)
        {
            MapAddress address = result.Information.Address;
            string addressText = string.Format("{0} {1}, {2}",
                address.HouseNumber, address.Street, address.City);
            LocationItem item = new LocationItem
            {
                Address = addressText,
                Coordinate = result.GeoCoordinate
            };
            App.ViewModel.LocationItems.Add(item);
            App.ViewModel.SearchControlsEnabled = true;
        }
    }
    App.ViewModel.SearchControlsEnabled = true;
}

The first thing to do in our handler is to check the Error property of the returned event arguments, and if it’s not null, something has gone wrong.  Another thing that complicates our code is the fact that the Error is returned as an Exception—not as a specific exception cast to the base type, mind you, but just a plain old exception. You know, it’s the one that you are never supposed to throw or catch. Adding injury to the insult is the fact that the only useful information that gets returned to you is an HResult. In other words, “Something bad happened. Please decode this cryptic value to find out what.” Table 8-7 lists the possible HResult codes and their meaning. I suppose it’s better than nothing but only just.

Assuming that nothing has gone wrong and our search returned some results, we can now add each result to a list of items and allow the user to pick the one that corresponds to the destination that they are searching for. The Result property of the argument is of type MapLocation. The MapLocation class has a property of type LocationInformation, and from that we can access the Address property that is of type MapAddress.

I created my own LocationItem class that exposes a string used to display the address of the result and a property of type GeoCoordinate since that is all we need for our RouteQuery later. I simply create a new instance and add it a list of locations from which the user can pick the correct match.

MapAddress address = result.Information.Address;
string addressText = string.Format("{0} {1}, {2}",
address.HouseNumber, address.Street, address.City);
LocationItem item = new LocationItem
{
    Address = addressText,
    Coordinate = result.GeoCoordinate
};
App.ViewModel.LocationItems.Add(item);

The item selected by the user is then added to a list of waypoints that will be used in the RouteQuery. The RouteQuery, like the GeocodeQuery, is very simple to use. Listing 8-19 has the details.

Listing 8-19. Setting Up and Executing a RouteQuery

RouteQuery routeQuery = new RouteQuery();
coordinates = (from point in App.ViewModel.WayPoints
               select point.Coordinate).ToList();
 
routeQuery.Waypoints = coordinates;
routeQuery.QueryCompleted += RouteQueryQueryCompleted;
routeQuery.QueryAsync();

The QueryCompleted handler for the RouteQuery follows the same pattern as the GeocodeQuery right down to the use of the Exception and HResult. On the upside, there are quite a few result codes, and each has a fairly descriptive meaning. Table 8-8 lists the codes and their meaning. The sample code for this recipe contains a couple of enumerations I created to wrap up these HResult codes. I also created a couple of extension methods that allow you to get the description text for a particular code.

We’ll use the LongListSelecor to display the results and use its grouping capability to display the maneuver list for each leg of the journey in a separate group. The features of the LongListSelector are covered in depth in Recipe 2-5 in Chapter 2. We’ll make use of the ObservableLongListGroup class from that chapter to display our results.

The Result property of the QueryCompletedEventArgs is of type Route. The Legs property of Route contains one RouteLeg for each of the waypoints we provided to our query, and each RouteLeg contains the collection of RouteManeuver objects that direct us to that waypoint. The RouteLeg doesn’t contain the address information, but since the Legs are in the same order as our list of waypoints, we can index into that list to retrieve the address for display in our group header. Listing 8-20 shows the code to create the ObservableLongListGroup items, and Listing 8-21 shows the XAML used to create the necessary templates and LongListSelector to display the directions.

Listing 8-20. Generating the ObservableLongListGroup Items

Route route = e.Result;
for (int j = 0; j < route.Legs.Count; j++)
{
 
    string wayPoint = App.ViewModel.WayPoints[j].Address;
    List<string> manuvers = (from man in route.Legs[j].Maneuvers
                             select man.InstructionText).ToList();
 
    App.ViewModel.Maneuvers.Add(
    new ObservableLongListGroup<string>(manuvers, wayPoint));
}

Listing 8-21. XAML for the LongListSelector and Related Templates

<phone:JumpListItemBackgroundConverter x:Key="BackgroundConverter"/>
<phone:JumpListItemForegroundConverter x:Key="ForegroundConverter"/>
 
<DataTemplate x:Name="ManeuverHeaderTemplate">
    <Border
        BorderThickness="1"
        Background="{Binding Converter={StaticResource BackgroundConverter}}">
        <TextBlock
            Foreground="{Binding Converter={StaticResource ForegroundConverter}}"
            Text="{Binding Key}"
            Style="{StaticResource LongListSelectorGroupHeaderStyle}"/>
    </Border>
</DataTemplate>
 
<DataTemplate x:Name="MaueverItemTemplate">
    <TextBlock
        Style="{StaticResource PhoneTextNormalStyle}"
        Text="{Binding}"/>
</DataTemplate>
 
    <phone:LongListSelector
        Grid.Row="3"
        IsGroupingEnabled="True"
        ItemTemplate="{StaticResource MaueverItemTemplate}"
        ItemsSource="{Binding Path=Maneuvers}"
        GroupHeaderTemplate="{StaticResource ManeuverHeaderTemplate}">
    </phone:LongListSelector>

Figure 8-10 shows the results of our efforts.