Click or drag to resize
Setting Extents

There are several ways to set the viewable extent of layers in your map. This topic will discuss some of the options available to you and provide insights to help you better understand which option may be most appropriate for your application.

The Map.InitialViewpoint Property

In most circumstances to set the initial viewable extent of the layers in your application, you would use the MapInitialViewpoint Property. Setting this Property can be done in XAML and code-behind. See the following example code fragments:

XAML
<esri:MapView x:Name="MyMapView">
    <esri:Map x:Name="MyMap">
        <esri:Map.InitialViewpoint>
            <esri:ViewpointExtent XMin="-117.182686" YMin="32.695853" XMax="-117.133872" YMax="32.718530" SpatialReferenceID="4326" />
        </esri:Map.InitialViewpoint>
    </esri:Map>
</esri:MapView>

public void SetInitialExtent()
{

    // Set the initial extent.
    Esri.ArcGISRuntime.Geometry.SpatialReference mySpatialReference = Esri.ArcGISRuntime.Geometry.SpatialReferences.Wgs84;
    Esri.ArcGISRuntime.Geometry.Envelope myEnvelope = new Esri.ArcGISRuntime.Geometry.Envelope(-117.182686, 32.695853, -117.133872, 32.71853, mySpatialReference);
    MyMapView.Map.InitialViewpoint = new Esri.ArcGISRuntime.Controls.Viewpoint(myEnvelope);

}

Because the Map.InitialViewpoint is a Property, it can be set in in XAML. Unlike other options which will be discussed hereafter, they are based upon Method calls which cannot be used in XAML and can only be used via code-behind.

The Map.InitialViewpoint can be both get and set within your application. However, once you set the Map.InitialViewpoint you cannot use this Property again to reset the extent to another location. Once the Map.InitialViewpoint has been initially set and you try to set it again, it will be ignored.

The Map.InitialViewpoint is based on the Esri.ArcGISRuntime.ControlsViewpoint Class or one of its inherited children: Esri.ArcGISRuntime.ControlsViewpointCenter or Esri.ArcGISRuntime.ControlsViewpointExtent. Details of component parts of the ViewPoint object and how they can be used to set an extent are discussed in later sections of this document.

The MapView Methods (SetView, SetViewAsync, ZoomAsync, ZoomToScaleAsync)

There are numerous other options (23+) to set the viewable extent of the layers in your application and they are performed on the Esri.ArcGISRuntime.ControlsMapView Class. These Methods are listed here with a brief description:

Because these options are Methods, they can only set the viewable extent of the layers in your application. If you desire to get the extent of your map, you would need to use the read only MapViewExtent. Note: you cannot use the MapView.Extent Property to set the viewable extent of layer in your map; you must use one of the numerous MapView Methods (SetView, SetViewAsync, ZoomAsync, ZoomToScaleAsync) listed previously or the Map.InitialViewpoint Property.

Understanding the input options to the MapView Methods

There are several combinations of input parameter options that can be used by the various MapView Methods (listed in the prior section) to adjust the scale of the viewable extent of layers in the map. This section will discuss these options to help you better understand how they can be used in your application.

  • Geometry – When an input Geometry object is supplied for the various MapView Methods, the extent of that Geometry will be determined (this applies to Geometries of type: Envelope, Multipart, Polygon, Polyline, and Multipoint). The extent of that Geometry will then be applied to the maps viewable extent so that the entire Geometry’s extent will be viewable. In most cases, the ratio of the height/width of the map does not exactly match the ratio of the height/width of the Geometry’s extent and hence you will often find that there is more geographic area shown in the map beyond the Geometry’s extent. See the screen shot for a visual illustration.

    Map View Set View Polygon

    As a result of the trying to fit the extent of the Geometry within the physical height/width of the map causes the scale of the map to be adjusted. This scale adjustment issue becomes more pronounced as your application is deployed to various devices with the MapView/Map Controls having different screen form factors. To preserve the scale of the viewable layers in your application you should review the information in the next section of this document for suggestions.

    In the case of a MapPoint or Geometry with a zero-extent (ex: a MultiPoint with all MapPoints in the array having the exact same location), then a pan will occur using the current scale and center the map on that point.

  • MapPoint - Centers the extent of the map using the X and Y location of the MapPoint at the maps current scale.

  • Double - The scale at which the maps extent will be centered on. Scale is the ratio or relationship between a distance or area on a map and the corresponding distance or area on the ground, commonly expressed as a fraction or ratio. A map scale of 1/100,000 or 1:100,000 means that one unit of measure on the map equals 100,000 of the same unit on the earth.

  • TimeSpan - A duration of time for animation to occur while the map is adjusting to its new extent. This provides a smooth way for the map to transition from its original extent to its new one.

  • Thickness - A margin to leave around the bounding geometry in device independent pixels.

  • ViewPoint - A helper object that is used to specify either (1) the center of the map typically at a specified scale or (2) the extent of map using a bounding box of an Envelope. If it is desired to set the initial extent of a map via XAML, the only way this can be accomplished is via a Esri.ArcGISRuntime.ControlsViewpoint object or one of its inherited children: Esri.ArcGISRuntime.ControlsViewpointCenter or Esri.ArcGISRuntime.ControlsViewpointExtent. Defining a ViewPoint or one of its inherited children can be done via a constructor and/or setting some of the many Properties that are available. These constructor arguments or Properties typically use many of the other input arguments used by the MapView Method discussed in this section (for example: Geometry, MapPoint, Double (for scale)) as well as some other more specialized Properties such as: Rotation, SpatialRefernceID, X, Y, XMax, XMin, YMax, and YMin.

Setting the map extent to a specific scale

Setting the maps extent to a bounding box of a Geometry (examples: Map.InitialViewPoint(Viewpoint(Geometry)), Map.InitialViewPoint(Viewpoint(Envelope)) MapView.Viewpoint(Geometry), MapView.Viewpoint(Envelope), MapView.SetView(Geometry), MapView.SetViewAsync(Geometry), etc.) does not provide a consistent scale across devices; this was visually demonstrated in the prior visual illustration. To preserve the scale of viewable layers in your application (especially when deployed across different devices) you should specify a center location of the map and a scale factor to adjust the extent to. Some of the Properties and Methods to set a map to a specific scale include: Map.InitialViewPoint(Viewpoint(MapPoint, Double)), Map.InitialViewPoint(ViewpointCenter(MapPoint, Double)), MapView.SetView(MapPoint, Double), MapView.SetViewAsync(MapPoint, Double), etc. The following illustration shows how a polygon would appear at a specific scale across different forms factors of the MapView/Map Controls.

Map View Set Scale Polygon

The following are a few code examples for setting the map extent to a specific scale that would provide a consistent view of the layers across different form factors:

XAML
<esri:MapView x:Name="MyMapView">
    <esri:Map x:Name="MyMap">
        <esri:Map.InitialViewpoint>
            <esri:ViewpointCenter X="-117.15" Y="32.705" Scale="50000" SpatialReferenceID="4326" />
        </esri:Map.InitialViewpoint>
    </esri:Map>
</esri:MapView>

public void SetInitialExtent()
{

    // Set the initial extent to a specific scale.
    Esri.ArcGISRuntime.Geometry.SpatialReference mySpatialReference = Esri.ArcGISRuntime.Geometry.SpatialReferences.Wgs84;
    Esri.ArcGISRuntime.Geometry.MapPoint myMapPoint = new Esri.ArcGISRuntime.Geometry.MapPoint(-117.15, 32.705, mySpatialReference);
    System.Double myScale = 50000;
    MyMapView.Map.InitialViewpoint = new Esri.ArcGISRuntime.Controls.Viewpoint(myMapPoint, myScale);

}