How to display maps in the Map control

[アーティクル]
08/31/2015

Display customizable maps in your app by using the Map control.

The MapControl and most of the classes described in this topic belong to the Windows.UI.Xaml.Controls.Maps namespace.

Important

Your app has to be authenticated before it can use many features of the Map control and map services. For more info, see How to authenticate your Maps app.

Adding the Map control to a XAML page

Display a map on a XAML page by adding a MapControl.

The MapControl requires a namespace declaration for the Windows.UI.Xaml.Controls.Maps namespace in the XAML page or in your code.

If you drag the control from the Toolbox, this namespace declaration is added automatically.
If you add the MapControl to the XAML page manually, you have to add the namespace declaration manually at the top of the page.

xmlns:Maps="using:Windows.UI.Xaml.Controls.Maps"
If you add the MapControl in your code, you have to add the namespace declaration manually at the top of the code file.

using Windows.UI.Xaml.Controls.Maps;

If you want the MapControl to fill all the available space in the default Grid, clear the alignment and margin settings. To clear these settings quickly, right-click on the control, and then select Layout | Reset All.

Provide the authentication token for the MapControl by setting the value of its MapServiceToken property.

Here's a simple example of the MapControl on a page.

    <StackPanel HorizontalAlignment="Stretch"
                Margin="8,8,8,8" VerticalAlignment="Stretch" >
        <TextBlock TextWrapping="NoWrap" Text="Map control"
                   FontSize="36" Margin="8,0,0,16"/>
        <Maps:MapControl
            x:Name="MapControl1"
            MapServiceToken="<token>"
            Height="560"
            Margin="0,0,0,0" />
    </StackPanel>

Specifying the location to display on the map

Specify the location to display on the map by specifying the Center property of the MapControl in your code or by binding the property in your XAML markup.

Tip Since a string can't be converted to a Geopoint, you can't specify a value for the Center property in XAML markup unless you use data binding. (This limitation also applies to the MapControl.Location attached property.)

This example displays a map with the city of Seattle as its center.

using Windows.Devices.Geolocation;

        protected override void OnNavigatedTo(NavigationEventArgs e)
        {
            MapControl1.Center =
                new Geopoint(new BasicGeoposition() { Latitude = 47.604,
                    Longitude = -122.329 });
            MapControl1.ZoomLevel = 12;
            MapControl1.LandmarksVisible = true;
        }

void MainPage::OnNavigatedTo(NavigationEventArgs^ e)
{
       BasicGeoposition seattleBG = { 47.604, -122.329 };

       auto gp = ref new Geopoint(seattleBG);

       this->MapControl1->Center = gp;
       this->MapControl1->ZoomLevel = 12;
       this->MapControl1->LandmarksVisible = true;
}

This example displays the following map.

Configuring the map

Configure the map and its appearance by setting the values of the following properties of the MapControl.

Map settings

Set the center of the map to a geographic point by setting the Center property.
Set the zoom level of the map by setting the ZoomLevel property to a value between 1 and 20.
Set the rotation of the map by setting the Heading property, where 0 or 360 degrees = North, 90 = East, 180 = South, and 270 = West.
Set the tilt of the map by setting the DesiredPitch property to a value between 0 and 65 degrees.

Map appearance

Specify the type of map - for example, a road map or an aerial map - by setting the Style property with one of the MapStyle constants.
Set the color scheme of the map to light or dark by setting the ColorScheme property with one of the MapColorScheme constants.

Showing information on the map

Show information on the map by setting the values of the following properties of the MapControl.

Display buildings and landmarks on the map by enabling or disabling the LandmarksVisible property.
Display pedestrian features such as public stairs on the map by enabling or disabling the PedestrianFeaturesVisible property.
Display traffic on the map by enabling or disabling the TrafficFlowVisible property.
Specify whether the Nokia HERE watermark is displayed on the map by setting the WatermarkMode property with one of the MapWatermarkMode constants.
Display a driving or walking route on the map by adding a MapRouteView to the Routes collection of the Map control. For more info and an example, see How to get and display routes and directions.

For info about how to display pushpins, shapes, and XAML controls in the MapControl, see How to display pushpins, shapes, and controls on a map.

Changing the map

Call one of the overloads of the TrySetViewAsync method to move the Center of the map to a new location.

When you call the TrySetViewAsync method, you can also specify optional new values for the following properties of the MapControl:

You can also specify an optional animation to use when the view changes by providing a constant from the MapAnimationKind enumeration.

Call the TrySetViewBoundsAsync method to display the contents of a GeoboundingBox on the map. Use this method, for example, to display a route or a portion of a route on the map. For more info, see How to get and display routes and directions.

Display a route on the map by providing the BoundingBox of the MapRoute.
Display a portion of a route on the map by providing the BoundingBox of the MapRouteLeg.

Getting info about locations on the map

Get info about locations on the map by calling the following methods of the MapControl.

Call the GetLocationFromOffset method to get the geographic location that corresponds to the specified point in the viewport of the Map control.
Call the GetOffsetFromLocation method to get the point in the viewport of the Map control that corresponds to the specified geographic location.
Call the IsLocationInView method to determine whether the specified geographic location is currently visible in the viewport of the Map control.

Handling changes to the map

Determine whether the map is loading or completely loaded by handling the control's LoadingStatusChanged event.

Handle changes that happen when the user or the app changes the settings of the map by handling the following events of the MapControl.

Handling user interaction with the map

Handle user input gestures on the map by handling the following events of the MapControl. Check the values of the Location and Position properties of the MapInputEventArgs to get info about the geographic location on the map and the physical position in the viewport where the gesture occurred.