Navigating the map

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

Set the zoom and pan animation duration

The Silverlight platform provides rich animation capabilities while working with user interface (UI) content. The ArcGIS API for Silverlight leverages these capabilities to enhance the user experience during zoom or 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 a 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:

<esri:Map x:Name="MyMap" ZoomDuration="00:00:00" PanDuration="00:00:00">
    <esri:Map.Layers>
        <esri:ArcGISTiledMapServiceLayer ID="StreetMapLayer"
            Url="http://server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer" /> 
    </esri:Map.Layers> 
</esri:Map>

Snap to tile levels

The Silverlight platform includes efficient image resampling capabilities for a rich web client environment. The ArcGIS API for Silverlight Map control uses 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">
    <esri:Map.Layers>
        <esri:ArcGISTiledMapServiceLayer ID="StreetMapLayer"
            Url="http://server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer" /> 
    </esri:Map.Layers>
</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.

Get the initial extent at runtime

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 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. 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. See the following code:

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

Change the extent at runtime

A set of pre-defined keyboard and mouse shortcuts are enabled on a Map control by default. The following table lists the combination of key and mouse actions and the map actions that they trigger:

Key action	Mouse action	Map action
Press left, right, up, down arrow	None	Pan in the direction of the arrow key pressed.
+/-	None	Zoom in (+) or zoom out (-) one zoom factor. The zoom factor is defined by the Map.ZoomFactor property.
None	Left mouse button click	Zoom in one zoom factor.
None	Left mouse button click, then hold and drag	Pan the map (default map action).
Shift, press and hold	Left mouse button click, then hold and drag	Define an extent to zoom in.
Shift + Ctrl, press and hold	Left mouse button click, then hold and drag	Define an extent to zoom out.
None	Scroll wheel forward/backward	Zoom in (forward), zoom out (backward).

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	Set to an ESRI.ArcGIS.Client.Geometry.Envelope. The map extent changes 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. See the following code: 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 See the following code: MyMap.Zoom(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 operates during the extent change. See the following code: 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 (for example, dots per inch [dpi] or pixels per inch [ppi]), you can accurately calculate map scale for the respective client. See the following code: TiledMapServiceLayer tiledLayer = MyMap.Layers["StreetMapLayer"] as TiledMapServiceLayer; Lod lod = tiledLayer.TileInfo.Lods[5]; MyMap.ZoomToResolution(lod.Resolution);
PanTo(geometry) method	Pan 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);