Navigating the map

The ArcGIS Runtime SDK for Windows Phone Map control includes options for defining and enhancing its navigation behavior at run time. This topic discusses design-time and run time solutions for navigating the map.

Change the extent with default gestures

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

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

Change the extent programmatically

You can also modify the 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	Sets the extent to an ESRI.ArcGIS.Client.Geometry.Envelope. The map extent changes to the defined extent without animation. See the following code: ESRI.ArcGIS.Client.Geometry.Envelope envelope = new ESRI.ArcGIS.Client.Geometry.Envelope(-120, 20, -100, 40); MyMap.Extent = envelope; 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.
Zoom(factor) method	Zooms in or out based on the factor (ratio) provided. > 1 = zoom in < 1 = zoom out See the following code: MyMap.Zoom(2); // Zooms in by a factor of 2.
ZoomTo(geometry) method	Zooms to an extent that includes the ESRI.ArcGIS.Client.Geometry passed to the method. The geometry cannot be of type MapPoint. Map animation operates during the extent change. See the following code: MyMap.ZoomTo(myPolygon);
ZoomToResolution(double) method	Zooms to a resolution defined as the number of map units per pixel. If you know the number of screen pixels per inch (for example, dots per inch [dpi] or pixels per inch [ppi]), you can accurately calculate the 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. See the following code: 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	Pans to an extent that centers on the ESRI.ArcGIS.Client.Geometry instance passed to the method. The map scale will not change. Map animation operates during the operation. See the following code: MyMap.PanTo(myPoint);

Get the initial extent at run time

You may not know the initial extent of the map until run time, 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 fire when the map extent is in the process of changing (affected by zoom or pan animation duration) and when the map extent has finished changing, respectively. When the initial map extent is set, it triggers the ExtentChanged event. You can listen for this event to discover the initial map extent. See the following code:

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

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.

Set the zoom and pan animation duration

The Silverlight platform provides rich animation capabilities while working with user interface (UI) content. The ArcGIS Runtime SDK 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 takes 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 quick, more responsive actions. The default Zoom duration is 1.5 seconds, the default Pan duration is 0.75 seconds. The following sample code 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 Silverlight platform includes efficient image resampling capabilities for a rich web client environment. The ArcGIS Runtime SDK for Windows Phone Map control utilizes the Silverlight resampling engine to render map images associated with a map service layer, such as cache tiles (for example, ArcGISTiledMapServiceLayer) or dynamic map images (for example, 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 map service layers 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 layers. See the following code:

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

A TiledMapServiceLayer has a TileInfo object that stores an array of valid LODs for a map service. Each LOD has a resolution that 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.