Navigating the map

The ArcGIS API for Windows Phone Map control includes options for defining and enhancing its navigation behavior at runtime. This document will discuss design-time and run-time solutions for navigating the map.

Changing the extent with default gestures

A set of pre-defined gestures are enabled on a Map control by default. The following table lists the gesetures and related map actions.

Gesture	Map action
Pan/drag	Pan in the direction the finger is moved.
Pinch	Zoom in.
Stretch	Zoom out.
Double-tap	Zoom in one zoom factor. The zoom factor is defined by the Map.ZoomFactor property.
Flick	Pan in the direction of the flick and slowly come to a stop.

Changing the extent programmatically

You can also modify map extent by setting the Extent property or calling the Zoom(), ZoomTo(), ZoomToResolution(), or PanTo() method on the Map control. The following table defines the characteristics of each operation.

Map member	Map action
Extent property	Set to an ESRI.ArcGIS.Client.Geometry.Envelope. The map extent will change to the defined extent without animation. The actual extent of the map may not match the Envelope defined because the aspect ratio of the map must be preserved. To discover the actual extent, handle the ExtentChanged event on the map and use the NewExtent property on the event arguments. ESRI.ArcGIS.Client.Geometry.Envelope envelope = new ESRI.ArcGIS.Client.Geometry.Envelope(-120, 20, -100, 40); MyMap.Extent = envelope;
Zoom(factor) method	Zoom in or out based on the factor (ratio) provided. > 1 = zoom in < 1 = zoom out MyMap.Zoom(2); // will zoom in by a factor of 2
ZoomTo(geometry) method	Zoom to an extent that includes the ESRI.ArcGIS.Client.Geometry passed to the method. The geometry cannot be of type MapPoint. Map animation will operate during the extent change. MyMap.ZoomTo(myPolygon);
ZoomToResolution(double) method	Zoom to a resolution defined as the number of map units per pixel. If you know the number of screen pixels per inch (e.g. DPI or PPI) you can accurately calculate map scale for the respective client. The levels of detail (LODs) available on a TiledMapServiceLayer are available through the Lods property and can be used to select the resolution to zoom to. TiledMapServiceLayer tiledLayer = MyMap.Layers["StreetMapLayer"] as TiledMapServiceLayer; Lod lod = tiledLayer.TileInfo.Lods[5]; MyMap.ZoomToResolution(lod.Resolution); Note: The TileInfo for a layer is not available until after the layer is initialized, and a Map cannot zoom to a resolution until all its layers are initialized.
PanTo(geometry) method	Pan to an extent that centers on the ESRI.ArcGIS.Client.Geometry instance passed to the method. Map scale will not change. Map animation will operate during the operation. MyMap.PanTo(myPoint);

Get the initial extent at run-time

You may not know the initial extent of the map until runtime, so if you need to work with the initial map extent you must discover it when the application first loads. The Map control provides two event handlers to listen for extent changes. The ExtentChanging and ExtentChanged events will be fired when map extent is in the process of changing (affected by zoom or pan animation duration) and when map extent has finished changing, respectively. When the initial map extent is set it will trigger the ExtentChanged event. You can listen for this event to discover the initial map extent. To get the initial physical size of the Map control (in pixels) listen for the first SizeChanged event. You may not know the initial physical size if it is not set on the Map or its container.

void MyMap_ExtentChanged(object sender, ExtentEventArgs e)
{
    if (e.OldExtent == null)
        ESRI.ArcGIS.Client.Geometry.Envelope initialExtent = e.NewExtent;
}

Set the zoom and pan animation duration

The Windows Phone platform provides rich animation capabilities while working with UI content. The ArcGIS API for Windows Phone leverages these capabilities to enhance the user experience during zoom and pan operations on the Map control. You can choose the level to which animation is applied to map content. The ZoomDuration and PanDuration properties on the Map control define the amount of time (duration) it will take to complete the respective operation. The value is a TimeSpan and can be represented in XAML as a string using the format "d.hh:mm:ss.ff", where the d component is days, hh is hours as measured on a 24-hour clock, mm is minutes, ss is seconds, and ff is fractions of a second. For Zoom and Pan durations higher values result in slower, smoother actions, while lower values result in a quick, more responsive actions. The default Zoom duration is 1.5 seconds, the default Pan duration is 0.75 seconds. The sample code below illustrates how to disable map animation during a zoom or pan operation by setting their durations to 0.

<esri:Map x:Name="MyMap" ZoomDuration="00:00:00" PanDuration="00:00:00">
    <!-- set layers and other properties for the map here -->
</esri:Map>

Snap to tile levels

The Windows Phone platform includes efficient image resampling capabilities for a rich Web client environment. The ArcGIS API for Windows Phone Map control utilizes the Windows Phone resampling engine to render map images associated with a map service layer such as cache tiles (e.g. ArcGISTiledMapServiceLayer) or dynamic map images (e.g. ArcGISDynamicMapServiceLayer). This provides a smooth flexible user experience and permits a client to view cached tiles at a scale of choice. You can choose to force the map to snap to a level of detail (LOD) in the first tiled map service layer using the SnapToLevels property. Once you set it to true the map can only be viewed at a scale (LOD) defined by the tiled map service layer.

<esri:Map x:Name="MyMap" SnapToLevels="True">
    <!-- set layers and other properties for the map here -->
</esri:Map>

A TiledMapServiceLayer has a TileInfo object which stores an array of valid LODs for a map service. Each LOD has a resolution which represents the number of map units per image pixel. To zoom to a specific level, interrogate the LOD array, retrieve the level of interest and its resolution, and pass it to the Map.ZoomToResolution() method, as seen in the section above.