Complete Reference of Map Control in Windows Phone 8.1 WinRT

Since Windows Phone has the Windows Phone 8.1 update last year it came up with 2 different platforms to work on, Silverlight and WinRT, thus making it a bit tough to keep up with the latest API documentation and Maps are not different.

As I have written before how to use Maps following MVVM on Windows Phone 8, I'm going to keep today's one as a bit of a reference to that and will just post segments that you can use as a code sample.

Instantiating a Map in Windows Phone 8.1

Quite frankly this is the easiest job here to do actually. Let's proceed and start taking things from screenshots. First we need to open a new project targeting Windows Phone 8.1 and name it MapTest. Then I went to my Toolbox and dragged a MapControl to the middle of the Main Grid. I have already changed my map controls HorizontalAlignment and VerticalAlignment to "stretch" thus allowing the MapControl to be stretched out to the fullest for the entire app.

<Maps:MapControl HorizontalAlignment="Stretch"  VerticalAlignment="Stretch"/>

Usually a map driven app needs an AuthenticationToken to authenticate the map services but we will focus on that later. Let's proceed to the Solution Explorer and open Package.appxmanifest and go to the Capabilities tab and make sure that both of the checkboxes for Location and Internet are checked just to make ensure your app is map capable.

Now we have a Green light to use Maps. If you are a fella from Windows Phone 8 development then you'll see now, you don't have ID_CAP_MAP here to enable the app to use maps. You only need it to have location capability.

Getting Your Own Location:

Getting your own location is still as straightforward as it was before in the Windows Phone 8 era. All you need to do is use the same Geolocator class and it looks as in the following:

Geolocator locator = new Geolocator();
Geoposition position = await locator.GetGeopositionAsync();

Now the question remains of how to show it on a Map. Now, Windows Phone 8.1 gives you many options to choose from actually here. You can use three specific things here:

1. MapIcon
2. XAML controls
3. Shapes

Using MapIcon

The first trial we will make is using the MapIcon since it is the most straight forward. MapIcon is essentially derived from the MapElement class, it can be configured by providing a new image to it or it provides a default one. And the declaration is pretty straightforward too.

MapIcon icon = new MapIcon();
icon.Location = position.Coordinate.Point;
icon.Title = "My Location";
MyMap.MapElements.Add(icon);

Now, if you want to provide a specific Image as your MapIcon, include the image in the Assets folder and let's assume the image name is MapIcon.png. All you need to do is change the Image property of your MapIcon object.

icon.Image = RandomAccessStreamReference.CreateFromUri(new Uri("ms-appx:///Assets/MapIcon.png"));

What people actually misinterpret here is usually they compare PushPin with MapIcon and they do have a valid reason to do so because you can achieve the same result by using both of them but in actuality it doesn't work like that. MapIcons are actually a set of Icons that define multiple purposes on the map. These are lightweight, so please choose one if you want to use these to show a specific purpose. Now our purpose was to show our current location.

Now let's put together a method named GetMyLocation() and put all these together and see what happens.

private async void GetMyLocation()
{
    Geolocator locator = new Geolocator();
    Geoposition position = await locator.GetGeopositionAsync();

    MapIcon icon = new MapIcon();
    icon.Location = position.Coordinate.Point;
    icon.Title = "My Location";
    icon.Image = RandomAccessStreamReference.CreateFromUri(new Uri("ms-appx:///Assets/ImageIcon.png"));
    MyMap.MapElements.Add(icon);

    MyMap.Center = position.Coordinate.Point;
    MyMap.DesiredPitch = 0;

    await MyMap.TrySetViewAsync(position.Coordinate.Point, 15);

}

Now, as this goes, you'll see I've done some more work too. I've changed the center property of the map control because after adding the MapIcon you need your map to focus on that point and this is how you change the center of your map. And the next thing I did is set the DesiredPitch to 0. We will see more about this property later. You definitely have noticed by now that the method is an asynchronous method because the process of locating your position is asynchronous and we're using our favourite await keyword to make locator.GetGeopositionAsync() to work synchronously inside the method. The last thing you want is to focus to the selected location (My Location) on the map. So I'm setting the map view asynchronously using the MyMap.TrySetViewAsync function and it takes two parameters, the first one being the point (the geolocation of you) you want to set your view into and the second is a zoom level of the map. It is actually setting the MyMap.ZoomLevel property in the range 1 - 20. A higher number means a greater zoom thus closer to the ground. I've also used a custom MapIcon.png with a size of 65x65 pixels. Please be careful on this one since the size you choose is the size you get on the Map. Please choose a size that looks good for your purpose. Now let's put the GetMyLocation() method OnNavigatedTo method and thus you get a smooth zooming animation.

Now, a couple of things that are missing here is a progress bar showing that the location is being detected and a try/catch that detects any exception detecting the location. Plus we need to put our location detection invocation in a button so we can tap it anytime to load our current location anytime. For that we can use an Application Bar.

Now Let's add an app bar in the bottom as in the following:

<Page.BottomAppBar>
   <CommandBar ClosedDisplayMode="Minimal" Opacity="0.7">
      <AppBarButton Label="Find Me!" Icon="Target" />
   </CommandBar>
</Page.BottomAppBar>

Now on the AppBarButton_Tapped event handler use a GetMyLocation call. It would possibly look like the following:

private void AppBarButton_Tapped(object sender, TappedRoutedEventArgs e)
{
   GetMyLocation();

}

Now, let' wrap up the location detection process under a try-catch just to ensure that if anything goes wrong, you're covered. And as we'd need to show progress please put the following method in MainPage.xaml too.

private async void ToggleProgressBar( bool toggle, string message="")
{
   StatusBarProgressIndicator progressbar = StatusBar.GetForCurrentView().ProgressIndicator;
   if(toggle)
   {
      progressbar.Text = message;
      await progressbar.ShowAsync();
   }
   else
   {
      await progressbar.HideAsync();
   }

}

Now all you need to do is call it to show ProgressIndicator in StatusBar, you can even provide the message in the method call.

Now GetMyLocation will look like the following:

private async void GetMyLocation()
{
    ToggleProgressBar(true,"Getting your location...");

    try
    {
        Geolocator locator = new Geolocator();
        Geoposition position = await locator.GetGeopositionAsync();

        MapIcon icon = new MapIcon();
        icon.Location = position.Coordinate.Point;
        icon.Title = "My Location";
        icon.Image = RandomAccessStreamReference.CreateFromUri(new Uri("ms-appx:///Assets/ImageIcon.png"));
        MyMap.MapElements.Add(icon);

        MyMap.Center = position.Coordinate.Point;
        MyMap.DesiredPitch = 0;

        await MyMap.TrySetViewAsync(position.Coordinate.Point, 15);
    }
    catch (Exception ex)
    {
        MessageDialog ErrorDialog = new MessageDialog(ex.Message);
        ErrorDialog.ShowAsync();
    }

    ToggleProgressBar(false);
}

Using XAML controls over Map is something I really love because I was pretty fond of the PushPin control provided in Windows Phone Toolkit for Windows Phone 8. Usually this approach is more suitable for MVVM approached apps though. And as per this tutorial goes, we'd not got over MVVM just yet (we will cover that too). So, let's see how you add XAML controls or shapes in a map from code behind.

Instead of using MapIcon all you need to do know is how to generate a XAML control/Shape in the background and add it on the children list of the map control rather than the MapElements list.

So, just take off the MapIcon Segment and use this instead:

private async void GetMyLocation()
{
    ToggleProgressBar(true,"Loading");

    try
    {
        Geolocator locator = new Geolocator();
        Geoposition position = await locator.GetGeopositionAsync();

        var pushpin = new Windows.UI.Xaml.Shapes.Ellipse();
        pushpin.Fill=new SolidColorBrush(Colors.Red);
        pushpin.Height=50;
        pushpin.Width=50;

        MyMap.Children.Add(pushpin);

        MyMap.DesiredPitch = 0;

        MapControl.SetLocation(pushpin,position.Coordinate.Point);
        MapControl.SetNormalizedAnchorPoint(pushpin, new Point(0.5, 0.5));

        await MyMap.TrySetViewAsync(position.Coordinate.Point, 15,0,0,MapAnimationKind.Bow);
    }
    catch (Exception ex)
    {
        MessageDialog ErrorDialog = new MessageDialog(ex.Message);
        ErrorDialog.ShowAsync();
    }

    ToggleProgressBar(false);

}

Now, before moving to the next topic, I'd like to address some points in this approach.

1. You can create your control in code behind as you want to build it, you can use possibly any XAML control starting from containers like a Grid or a StackPanel to a Shape like rectangle and Ellipse.
   
   
2. Select a proper size of the shape if you want to use it and it's better than MapIcons in the sense that MapIcons are not guaranteed to be viewed.
   
   
3. MapIcon objects are usually added to the MapElements list but this is added to the Map Children collection.
   
   
4. You can define your datatemplate behind and even hook events (we will see this in the MVVM approach)

You need to select a proper anchor point for your XAML/Shape pushpin too. It's actually nothing but a point object in a 2D space. I want my anchor point to be in the center of the sphere. So if I put my sphere in a 2D space and 1 is the max limit in both the X and Y axis, you'd determine that (0.5, 0.5) is the center of the sphere. But this 2D co-ordinate system is actually a tad different. Kindly allow me to show in the following picture:

So, according to this rule, now you can set your anchor point properly depending on your XAML control. Just put it on an imaginary 2D grid and find your desired point. The left bottom would be (0,1) and the right bottom would be (1,1).

If you look closely you will also see we have changed our TrySetViewAsync invocation with some more parameters. Those are heading, pitch (we kept both of them at 0) and the last one is MapAnimationKind that allows you to define what kind of animation you want when setting the view. I personally love the Bow one thus I used that one and it looks as in the following:

Changing The Map Properties

The map control itself comes with many properties equipped, let's see how to change these for a chance. The first two things we'd love to change is the pitch/tilt and the rotation/heading. For that we'd need to change our layout a bit. Let's keep the map in the background and put 2 sliders (one horizontal and one vertical) for changing the rotation and pitch of the map.

We have introduced 3 rows and columns in the main grid just to keep the entire map in the background and the sliders floating in the top. The horizontal slider would change the Maps rotation and the Vertical Slider would change the Maps pitch. Now the main grid looks as in the following:

<Grid>
   <Grid.RowDefinitions>
      <RowDefinition Height="Auto"></RowDefinition>
      <RowDefinition Height="*"></RowDefinition>
      <RowDefinition Height="50"></RowDefinition>
   </Grid.RowDefinitions>

   <Grid.ColumnDefinitions>
      <ColumnDefinition Width="25"></ColumnDefinition>
      <ColumnDefinition Width="*"></ColumnDefinition>
      <ColumnDefinition Width="Auto"></ColumnDefinition>

   </Grid.ColumnDefinitions>
   <Maps:MapControl Grid.RowSpan="3" Grid.ColumnSpan="3" x:Name="MyMap"  HorizontalAlignment="Stretch" VerticalAlignment="Stretch">

   </Maps:MapControl>

   <Slider x:Name="RotationSlider" Grid.Row="0" Grid.Column="1" Maximum="360"></Slider>
   <Slider x:Name="PitchSlider" Grid.Row="1" Grid.Column="2" Orientation="Vertical" Maximum="65"  ></Slider>
</Grid>

And it looks in the emulator like this:

Now the first thing you'll notice here is that I've named the sliders accordingly. The horizontal one is called RotationSlider and the vertical one is called PitchSlider. Now, usually what we do is invoke the ValueChanged event and change the Heading or the DesiredPitch of the map. But there is a smarter way to do that. You can create two element bindings to the MyMap and bind the value of the sliders to the specific properties. If you watch carefully you will see that I have set the RotationSlider maximum value to 360 since that is the maximum rotation value and PitchSlider Maximum to 65 since that is the maximum tilt the MapControl allows. Now replace your sliders with the following binding:

<Slider x:Name="RotationSlider" Grid.Row="0" Grid.Column="1" Maximum="360" Value="{Binding Heading, ElementName=MyMap, Mode=TwoWay}" ></Slider>
<Slider x:Name="PitchSlider" Grid.Row="1" Grid.Column="2" Orientation="Vertical" Maximum="65" Value="{Binding DesiredPitch, ElementName=MyMap, Mode=TwoWay}" ></Slider>

Please make sure the Binding Mode is set to TwoWay so when the map updates the sliders update too. And without even writing a single line of backend code the feature is done!

So, that's a creative use of element binding. Now you could've done it even from the code backend. All you need to do is go to the properties of PitchSlider and RotationSlider and create the ValueChanged method stub. The methods you would have would look like the following:

private void PitchSlider_ValueChanged(object sender, RangeBaseValueChangedEventArgs e)
{
   MyMap.DesiredPitch = PitchSlider.Value;
}

private void RotationSlider_ValueChanged(object sender, RangeBaseValueChangedEventArgs e)
{
   MyMap.Heading = RotationSlider.Value;
}

Let's move on and see some of the other features we'd like to test too. Let's add two checkboxes to the bottom of the map to enable Traffic Flow and Land Marks. We added a horizontal stackpanel and added two checkboxes along with it.

<StackPanel Grid.Row="2" Grid.Column="1" Orientation="Horizontal">
   <CheckBox x:Name="TrafficCheck" Content="Traffic Flow" Foreground="Green"></CheckBox>
   <CheckBox x:Name="LandmarksCheck" Content="Land Marks" Foreground="Green"></CheckBox>
</StackPanel>

Now, we can use a bit more of a creative element binding or use Checked and Unchecked events to change the respective map control properties. Let's see how to bind it using element binding again.

<Maps:MapControl TrafficFlowVisible="{Binding IsChecked, ElementName=TrafficCheck, Mode=TwoWay}"
LandmarksVisible="{Binding IsChecked, ElementName=LandmarksCheck, Mode=TwoWay}"
Grid.RowSpan="3" Grid.ColumnSpan="3" x:Name="MyMap"
HorizontalAlignment="Stretch" VerticalAlignment="Stretch">

Now, watch carefully the binding written in the TrafficFlowVisible and LandMarksVisible properties. All I did here is to bind them with the appropriate checkbox IsChecked property and kept the binding mode two-way. So, anytime these properties change, even from code behind, we'll see the change on the checkbox and vice versa. Traffic Flow is a cool feature actually. See the next GIF to get an idea:

Pretty cool, huh?!

Now you can even write it on the code behind. You need to go to the properties of any of the checkbox and create the checked and unchecked property stub so you can toggle the map's TrafficFlowVisible feature. From code behind it will look like this:

private void TrafficCheck_Checked(object sender, RoutedEventArgs e)
{
   MyMap.TrafficFlowVisible = true;
}

private void TrafficCheck_Unchecked(object sender, RoutedEventArgs e)
{
   MyMap.TrafficFlowVisible = false;
}

And from the XAML:

<CheckBox x:Name="TrafficCheck" Content="Traffic Flow" Foreground="Green" Checked="TrafficCheck_Checked" Unchecked="TrafficCheck_Unchecked"></CheckBox>

I still prefer the Element binding because that is extremely easy. There's one more property named PedestrianFeaturesVisible. You can try that following the same way here.

Map Appearance

The Map Control is even cool enough to let you select the Map Appearance too! Let's modify the bottom stackpanel so it can hold more buttons and add a grid with two columns. We added one combobox in each column so we can change the map color scheme and map style.

So the bottom stackpanel looks as in this now:

<StackPanel Grid.Row="2" Grid.Column="1">
   <StackPanel  Orientation="Horizontal">
      <CheckBox x:Name="TrafficCheck" Content="Traffic Flow" Foreground="Green"></CheckBox>
      <CheckBox x:Name="LandmarksCheck" Content="Land Marks" Foreground="Green"></CheckBox>
   </StackPanel>
   <Grid Background="#00F9F9F9" >
      <Grid.ColumnDefinitions>
         <ColumnDefinition></ColumnDefinition>
         <ColumnDefinition></ColumnDefinition>
         </Grid.ColumnDefinitions>
         <ComboBox Grid.Column="0" PlaceholderText="Map Color" x:Name="MapColorBox" Width="150"  Background="#FF23D1B1" SelectionChanged="MapColorBox_SelectionChanged" >
            <ComboBoxItem  IsSelected="True" Content="Light" ></ComboBoxItem>
            <ComboBoxItem Content="Dark" ></ComboBoxItem>
         </ComboBox>
         <ComboBox Grid.Column="1" PlaceholderText="Map Style" x:Name="MapStyleBox" Width="150"  Background="#FF23D1B1" HorizontalAlignment="Right" SelectionChanged="MapStyleBox_SelectionChanged" >
            <ComboBoxItem  IsSelected="True" Content="None" ></ComboBoxItem>
            <ComboBoxItem Content="Road" ></ComboBoxItem>
            <ComboBoxItem Content="Aerial" ></ComboBoxItem>
            <ComboBoxItem Content="AerialWithRoads" ></ComboBoxItem>
            <ComboBoxItem Content="Terrain" ></ComboBoxItem>
         </ComboBox>
   </Grid>
</StackPanel>

We have added light and dark as the Map Color Scheme in the MapColorBox combobox and we have added 5 Map Styles in the MapStyleBox combobox. Each of the comboboxes have a SelectionChanged event handler hooked up. Let's see how MapColorBox_SelectionChanged looks as in the following MainPage.xaml.cs:

private void MapColorBox_SelectionChanged(object sender, SelectionChangedEventArgs e)
{
    if (MapColorBox!=null)
    {
        string selectedColor = ((ComboBoxItem)MapColorBox.SelectedItem).Content.ToString();

        switch (selectedColor)
        {
            case "Light":
                MyMap.ColorScheme = MapColorScheme.Light;
                break;
            case "Dark":
                MyMap.ColorScheme = MapColorScheme.Dark;
                break;
            default:
                MyMap.ColorScheme = MapColorScheme.Light;
                break;
        }
    }

}

You can see that based on the SelectedItem on MapColorBox combobox we have assigned MapColorScheme of MyMap to MapColorScheme.Light or MapColorScheme.Dark.

Now, let's focus on the MapStyleBox_SelectionChanged in the MainPage.xaml.cs

private void MapStyleBox_SelectionChanged(object sender, SelectionChangedEventArgs e)
        {
            if (MapStyleBox != null)
            {
                string selectedStyle = ((ComboBoxItem)MapStyleBox.SelectedItem).Content.ToString();

                switch (selectedStyle)
                {
                    case "None":
                        MyMap.Style = MapStyle.None;
                        break;
                    case "Road":
                        MyMap.Style = MapStyle.Road;
                        break;
                    case "Aerial":
                        MyMap.Style = MapStyle.Aerial;
                        break;
                    case "AerialWithRoads":
                        MyMap.Style = MapStyle.AerialWithRoads;
                        break;
                    case "Terrain":
                        MyMap.Style = MapStyle.Terrain;
                        break;
                    default:
                        MyMap.Style = MapStyle.None;
                        break;
                }
            }
        }

This looks like the previous one too. All we did here is based on the MapStyleBox SelectedItem we have assigned MyMap.Style to appropriate MapStyle.

Change Map Tile Source

Now usually what we see is either Bing or here Maps on the Windows Phone 8.1 Map Control. In some cases people might need to access different tile source like an Openstreet map. For those that don't understand what a tilesource is, every map system is nothing but a series of square shaped images/tiles shown for a range of geocoordinate boundaries. It's a grid of images shown based on the maps zoom level. When you zoom out or zoom in or roam around in the map, based on your X,Y and zoom level the map requests tiles of images to show you.

If you want to add/change a tiles layer, you need to change the TileSources collection of the map control. You can set the Zindex, tile pixel size and visibility. You can even forbid/allow stretching of the tiles while a higher resolution tile is being downloaded. You can define the layer type of the tile source like BackgroundReplacement, BackgroundOverlay and RoadOverlay.

Let's replace our default map tiles with Openstreetmap tiles.

private void SetTileSourceToOSM()
{
   var httpsource = new HttpMapTileDataSource("http://a.tile.openstreetmap.org/{zoomlevel}/{x}/{y}.png");
   var tilesource = new MapTileSource(httpsource)
      {
         Layer = MapTileLayer.BackgroundReplacement
      };
   MyMap.Style = MapStyle.None;
   MyMap.TileSources.Add(tilesource);
}

Now all we must do is call this on our OnNavigatedTo method as in the following:

protected override void OnNavigatedTo(NavigationEventArgs e)
{
   SetTileSourceToOSM();
   GetMyLocation();

}

And after the app is loaded, your map will look like this. But remember as we set our layer to BackgroundReplacement we will not have any kind of map styles or other features like TrafficFlow anymore.

You will also observe the loading of the map is pretty slow since the tiles are loaded from one source. So, we can balance the load by pointing to each of three domains so the maps may load faster. All we must do is rotate the subdomain of Openstreet map between a, b and c.

private void SetTileSourceToOSM()
{
   var next = "a";
   var httpsource = new HttpMapTileDataSource("http://a.tile.openstreetmap.org/{zoomlevel}/{x}/{y}.png");

   httpsource.UriRequested += (src, args) => {
      next = GetNextDomain(next);
      args.Request.Uri = new Uri("http://" + next + ".tile.openstreetmap.org/" +
      args.ZoomLevel + "/" + args.X + "/" + args.Y + ".png");

      };

   var tilesource = new MapTileSource(httpsource)
   {
      Layer = MapTileLayer.BackgroundOverlay
   };

   MyMap.Style = MapStyle.None;
   MyMap.TileSources.Add(tilesource);
}

private string GetNextDomain(string next)
{
   string[] domains={"a", "b", "c"};

   for(int count=0; count<domains.Length; count++)
   {
      if (domains[count] == next)
      return domains[(count + 1) % domains.Length];
   }

   return next;
}

Here in the GetNextDomain method you will see that all it's doing is it is actually rotating among the three subdomains of Openstreet map.

Map Events

Maps in Windows Phone 8.1 comes with much easier touch events. Touch events now comes along with GeoPoint and local UI coordinates related to the touch point. All these come along with MapTapped, MapDoubleTapped and MapHolding events. To check if a location is visible on the current map window you can use IsLocationInView().

We will try the MapTapped event for now. Select the MapControl, go over properties, go to the event handlers and double-click on the MapTapped event handler to create the method stub for that.

Now let's go ahead and write the method down:

private async void MyMap_MapTapped(MapControl sender, MapInputEventArgs args)
{
   Geopoint point = new Geopoint(args.Location.Position);

   MapLocationFinderResult FinderResult =
   await MapLocationFinder.FindLocationsAtAsync(point);

   String format = "{0}, {1}, {2}";

   if (FinderResult.Status == MapLocationFinderStatus.Success)
   {
      var selectedLocation=FinderResult.Locations.First();

     string message= String.Format(format, selectedLocation.Address.Town, selectedLocation.Address.District, selectedLocation.Address.Country);
      await ShowMessage(message);
   }

}

Now here we have a sample reverse geocode query. And you can definitely see this is much easier here. You need to use the MapLocationFinder class and it has a FindLocationsAtAsync method to get back with a geocoordinate based on your tap on the map. Actually it usually returns a list and we chose the first on the list and printed out the town, district and country on a messagedialog.

You can definitely check how the thing works on the phone.

Authenticating a Maps App

The last thing that is left to do is authenticating a map app. You will see unless you provide a map control a map service AuthenticationToken it keeps asking it in the bottom of the map.

The details on that process is available here.

Our next tutorial will be on Routing, GeoFencing and Maps using MVVM.

Stay frosty!