Map control

The Map control is designed to display geographic data from one or more resources provided by different data source types.   The Map control must be associated with a MapResourceManager to define the resources displayed within the map.  The MapResourceManager also provides a way to set the Transparency settings for the resources, each of which is treated as a separate layer within the map.   The Map control blends the resources together and renders a single image.  Advanced map tool functionality enables continuous panning and zooming capabilities without reloading the Web page that contains the map (in other words, a full postback is not required).  In addition, game style navigation provides scroll-wheel zoom and keyboard navigation options at runtime.  A number of other Web ADF controls buddy with the map control to enhance the user experience with the map, such as the Toolbar, Navigation, MapTips, and ZoomLevel controls. 

Assembly: ESRI.ArcGIS.ADF.Web.UI.WebControls.dll
Class: ESRI.ArcGIS.ADF.Web.UI.WebControls.Map

Using the Map control

1. Add the controls to the page
   
   Open or create a Web site within Visual Studio.NET.   Open a Web form in design mode, select the Toolbox, and expand the ArcGIS Web Controls tab.  Drag and drop a MapResourceManager and a Map control on the Web form.  Add one or more resources to the MapResourceManager.  See the Add Resources section in the MapResourceManager control topic for information on how to do this.  You should see the following in Visual Studio:
   
     
   
2. Set Map properties
   
   Select the Map control.  In the Properties page:
   1. Set the MapResourceManager property to the name of the MapResourceManager created and configured in the previous steps. 
   2. Set the PrimaryMapResource property to a ResourceItem in the MapResourceManager.  The ResourceItem cannot be a Graphics Layer.   See the discussion on defining a Primary Map Resource for more details.  
   3. Resize the map control to an acceptable size.  Left click and hold over a handle on a side or a corner of the control and drag the control to an acceptable size.   By default, the position of controls added in Visual Studio 2005 at design time is not set.  As a result, the controls are permitted to flow from left to right within a line, and from top to bottom within the page.  See the section about control positioning in the Visual Studio Integration topic for more information.
      
      Additional properties can be configured to change how the map behaves at runtime.  See the Properties section below for more detailed information.
      
3. Specify buddy Controls
   
   The map is usually the central control for any Web-based GIS application.  As a result, it is often buddied with other supplementary controls.  The Map itself does not specifically define a buddy control.  On the contrary, other controls included with the Web ADF buddy to the map.  This includes the Toc, MapTips, OverviewMap, ZoomLevel, Navigation, Toolbar, and task controls.  All are used to enhance map control interaction.     
   

Members

Properties

  The following table provides a list of properties and events of interest.  For complete reference information, see the Map control in the library reference section.

Property Name	Type	Description
EnableContinuousCallback	bool	Whether images will be fetched continuously during panning of the map or only when panning is complete.
EnableTileCaching	bool	Whether tiles that have been retrieved during panning of the map will be cached until the scale is changed.
EnableZoomAnimation	bool	Whether animation will happen for fixed zoom operations.
ImageBlendingMode	ImageBlendingMode	Whether images will be blended on the web server or on the browser.
ImageFormat		Format of output image.
InitialExtent	InitialExtent	The initial extent at which the Map first renders.
MapResourceManager	string	The ID of the MapResourceManager whose resources will be displayed on the map.
PreferredTileHeight	int	The preferred tile height to request if the resources are not bound to a tile caching scheme.
PreferredTileWidth	int	The preferred tile width to request if the resources are not bound to a tile caching scheme.
PrimaryMapResource	string	The primary MapResource whose properties other MapResources will adhere to for blending to take place.   This property cannot be a Graphics Layer.  If the property is empty the last resource item will be used.
Rotation	double	The rotation of the map in degrees. If value is a NaN, the primary map resource's rotation is used. Otherwise, the rotation is applied. 0 is a valid rotation value and can be used to change the default rotation of the primary map resource. When rotation is applied, all resources in the map should support map rotation.
ScrollWheelZoom	bool	Whether the map can be zoomed using the mouse scroll wheel.
ToolItems	MapToolItemCollection	Map Tool Item collection.
UseMimeData	bool	Set true to store output images in session and stream them to the client or to store them on the file system instead.
VirtualDirectory	string	The path to the virtual directory in which images can be written, for example, ~/output/.

Events

Event Type	Description
Circle	Raised when the control processes a tool associated with the Circle Client Tool Action.
DragImage	Raised when the control processes a tool associated with the DragImage Client Tool Action.
DragRectangle	Raised when the control processes a tool associated with the DragRectangle Client Tool Action.
ExtentChanged	Occurs when the extent of this control has changed.
Line	Raised when the control processes a tool associated with the Line Client Tool Action.
MapClick	Occurs when the control is clicked.
Oval	Raised when the control processes a tool associated with the Oval Client Tool Action.
Point	Raised when the control processes a tool associated with the Point Client Tool Action.
Polygon	Raised when the control processes a tool associated with the Polygon Client Tool Action.
Polyline	Raised when the control processes a tool associated with the Polyline Client Tool Action.
Refreshed	Occurs when the Map is fully refreshed. Does not occur if only one resource is refreshed with browser blending.
Resized	Occurs when the Map control is resized.
ResourceRefreshed	Occurs when a map resource is refreshed. May be used to detect single-resource refreshing with browser blending.
RotationAngleChanged	Occurs when the rotation of the map has changed.
ScaleChanged	Occurs when the scale of the Map is changed.
TilingSchemeInitialized	Occurs when the Map is done initializing the TilingScheme.

Discussion
  

• Default Keyboard and Mouse Shortcuts
  
  

  Keyboard\Mouse Shortcut	Map Action
  SHIFT, left mouse click, hold, and drag box	Zoom In
  CTRL, left mouse click, hold, and drag box	Zoom Out
  Left mouse click, hold, and drag	Pan
  NumLock disabled, use keypad	Pan
  Arrow keys, Home, End, Page Up, Page Down	Pan
  NumLock enabled, +	Zoom In
  NumLock enabled, -	Zoom Out

• Refreshing Map Content
  
  When the content of a Map has changed—for example, the layer visibility was toggled, or custom graphics were added or removed— you can choose one of two methods to programmatically refresh the Map: Refresh or RefreshResource.   The Map.Refresh() method will trigger a complete redraw of all resources in the Map and can be quite time consuming, especially if only one resource changed.   Map.RefreshResource() will provide the most efficient means for refreshing map content.  When the Map control uses browser blending to combine map images, a call to RefreshResource() will only refresh the resource that requires it.   When the Map control uses web-tier blending, a call to RefreshResource() will actually call Refresh() on the Map and all contents will be rerendered.   In general, the RefreshResource() method contains internal logic to interrogate map blending mode and determine if an individual resource or all resources need to be redrawn.     
  

• Set Initial Extent of a Map during Application Startup
  
  At design time, the InitialExtent property of a Map control can be set to Default or Full.   Default uses the extent of the primary map resource.  Full uses an extent that includes all resources in the map.  To explicitly set the extent of the map control upon application initialization, you will need to add the appropriate code to the PreRender event of the page or map.  The following example uses a custom Web ADF envelope to define the initial extent of the map.  Note that the initial extent only needs to be set on the initial request to the application, not on every subsequent postback:
  
  [C#]

  protected void Page_PreRender(object sender, EventArgs ea){
    if (!Page.IsPostBack){
      ESRI.ArcGIS.ADF.Web.Geometry.Envelope initextent = new ESRI.ArcGIS.ADF.Web.Geometry.Envelope(-110, 30,-100, 40);
      Map1.Extent = initextent;
    }
  }
  

  
  [VB]

  Protected Sub Page_PreRender(sender As object, ea As EventArgs)
    If Not Page.IsPostBack Then
      Dim initextent As New ESRI.ArcGIS.ADF.Web.Geometry.Envelope(-110, 30,-100, 40)
      Map1.Extent = initextent
    EndIf
  End Sub
  

    

• Create a Single Blended Map Image
  
  On Microsoft Windows platforms, GDI (Graphics Device Interface) is used to draw graphics on windows, form and other displayed media.  GDI consists of a set of C++ classes.  The Microsoft .NET Framework provides access to GDI capabilities via GDI+ which consists of a set of .NET classes designed to enhance rendering and manipulation of graphics and images.   GDI+ can also be used to merge (or blend) multiple images into a single image.  
  
  A Web ADF Map control uses one map functionality for each map resource to generate a map image, so a Map that works with multiple resources generates multiple images.  For each map extent, all generated map images are either blended in the browser or the Web-tier.  In either case the end user sees what appears to be one map when in fact it may consist of many overlapping images.  In some cases, it may be necessary to blend all map images into a single image for use outside of the Map control.  For example, generating a printable map from a Map control that contains multiple map resources will often require programmatically merging all map images into one.  In .NET you can use GDI+ to generate a single blended image.     The following code sample iterates through the MapFunctionality instances in a Map to generate a single blended map image.  The imgwidth and imgheight determine the size of the map image in pixels. When finished, the GDI+ System.Drawing.Bitmap referenced by variable newimg contains the blended map.
  
  [C#]

  ArrayList bitmaps = new ArrayList();
  
  foreach (IMapFunctionality mf in Map1.GetFunctionalities()){
      mf.DisplaySettings.ImageDescriptor.Height = imgheight;
      mf.DisplaySettings.ImageDescriptor.Width = imgwidth;
      mf.DisplaySettings.ImageDescriptor.TransparentBackground = true;
      mf.DisplaySettings.ImageDescriptor.ImageFormat = ESRI.ArcGIS.ADF.Web.ImageFormat.PNG8;
      ESRI.ArcGIS.ADF.Web.MapImage mi = mf.DrawExtent(Map1.Extent);
      bitmaps.Add(mi.GetImage());
  }
  
  System.Drawing.Bitmap newimg = new System.Drawing.Bitmap(imgwidth, imgheight);
  System.Drawing.Graphics imggraphics = System.Drawing.Graphics.FromImage(newimg);
  imggraphics.FillRectangle(new System.Drawing.SolidBrush(System.Drawing.Color.LightGray), 0, 0, imgwidth, imgheight);
  
  for (int j = bitmaps.Count-1; j >=0; j--){
      System.Drawing.Bitmap bmp = (System.Drawing.Bitmap)bitmaps[j];
      imggraphics.DrawImage(bmp, 0, 0, imgwidth, imgheight);
  }
  

• Set a Spatial Reference
  
  The spatial reference of a map control is set during application initialization and cannot be changed at runtime.  The primary resource of a map control determines the spatial reference of the map.  Thus to set the spatial reference of the map, define the appropriate coordinate system for the primary map resource.   Secondary map resources will be reprojected into the map's spatial reference, if the data source supports reprojecting on the fly. 
  
• Defining a Primary Map Resource
            
  A Map's primary map resource is used to define the spatial reference, rotation (if present), initial extent, scale, and zoom levels.   The PrimaryMapResource property can be explicitly set to a map resource item or left blank.  If blank, the following logic is used to determine the primary map resource for you:
  
  

  Map Resources	Primary Map Resource
  1 dynamic or 1 cached resource	If only one resource is present, it is the primary map resource.
  2 dynamic resources	The last resource in the resource items collection.
  2 cached resources	The first cached resource in the resource items collection.
  1 dynamic and 1 cached resource	The first cached resource in the resource items collection.

  
  

  If you are overlaying multiple cached services with the same spatial reference and matching scales, choose either cached service as the primary map resource. In this scenario, the Zoom Level control will include the scale levels from all cached services.

  If you are overlaying multiple cached services with different spatial references or scales, choose as the Primary Map Resource the service whose spatial reference you want used in the map. The Zoom Level control will only include the scale levels from this service.  Images from the other cached service will be drawn dynamically to match the coordinate system and scales of the Primary Map Resource. In other words, the cache from the non-Primary Map Resource will not be used. 
  
  If you are overlaying a cached service with a dynamic service, you should generally choose the cached service as the Primary Map Resource.  If the dynamic service is the Primary Map Resource, the cached service will be treated as a dynamic service, thus sacrificing the performance benefit of the cache.
  
  Do not set the Primary Map Resource to a Graphics Layer map resource item.  Graphics Layers represent Web ADF Graphics Datasets which are designed to be utilized programmatically at runtime.  As a result, a Graphics Layer does not have the spatial properties (e.g. spatial reference, scale, etc.) the Map needs to initialize and function properly.   Also, if you have not explicitly defined a Primary Map Resource, make sure the last resource item is not a Graphics Layer.      
  

• Rotate Map Content
  
  The Rotation property of the Map control can be used to specify, in degrees, the rotation of resources in the Map. A value of NaN means that the rotation of the PrimaryMapResource will be applied; 0 will unrotate rotated resources and leave other resources alone; values greater or less than 0 will rotate resources, throwing an exception if unrotatable resources are present. Map rotation is supported for ArcGIS Server (both Internet and Local) and Web ADF Graphics data sources.
  
  If the Map control has a rotation value greater or less than 0:
  • The presence of non-rotatable resources will return an exception in the Web page at runtime. The exception will indicate which resource does not support rotation.
  • The ContinuousCallback and EnableTileCaching properties on the Map control will be disabled.
  If the Map Rotation property is NaN, the rotation of the PrimaryMapResource (PMR) can be used. Since a Web ADF Graphics resource cannot be a PMR, only a rotation value specified for a data frame in an ArcGIS Server map service can be used. Map rotation can also be set on the fly at runtime.
  
  As long as the resources in the Map control support rotation, Map contents will be updated. Again, if a resource does not support rotation, an exception will returned in the Web page indicating which resource.  The following code snippet which illustrates how to change the Rotation property programmatically on a Map control:

  Map1.Reset();
  Map1.Rotation = 45;

  Rotating an ArcGIS Server cached map service requires that dynamic map images are generated - the cached map tiles will not be used. As a result, many of the performance benefits of a cached map service are negated.  Web ADF controls that work with the Map also support rotation, such as the Navigation, Magnifier, and OverviewMap controls.
  
• Image Blending Mode
  
  The ImageBlendingMode property on a Map control determines how map images from each resource are drawn. This property only has an effect when multiple resources (services) are used in a Map. A graphics layer counts as a resource for drawing purposes.
  
  Two options are available for ImageBlendingMode: Browser and WebTier. The Browser option, which is the default, causes the browser to retrieve the map images separately for each resource. The images might be retrieved via static URLs or as streamed MIME data. The browser then draws the images for each resource (service), one on top of the other. The advantage of browser blending is that a resource can be refreshed without refreshing other resources. For example, feature selection highlights can be drawn on a graphics layer without refreshing the underlying map.
  
  The image below illustrates browser blending. In this case, the web application uses map services on two different servers. The browser retrieves each map separately, and superimposes them together so that they appear as a single map to the user.
  
  
  
  The second option,  WebTier blending, causes the Web ADF on the server to retrieves all the map images from map services used in the website. The web application merges the images for all resources into a single image. The merged image is then sent to the browser. The following graphic illustrates web-tier blending.
  
  
  
  It is recommended to use Browser blending unless you have a specific reason to have the server blend map images.
  
• Resource centric tiling scheme
  
  To display map data within a Map control, map resources either generate an image on the fly or retrieve a cached image tile.  Each resource can define and utilize a tiling scheme to provide more effective and efficient interaction with the resource in the map.     
  
  Non-cached (dynamic) map resources have the option of using a dynamic tiling scheme or not.  A dynamic tiling scheme is constructed on the fly at runtime using the extent, size and scale of the map.  As long as the scale remains the same, the tiling scheme remains valid and continues to manage the retrieval of dynamic map images.   This benefits resources that generate map images relatively quickly and application scenarios in which end-user will pan frequently.  Browser cache will be used to render dynamic images already generated for a tile in the scheme.  If a non-cached resource does not enable dynamic tiling, each extent change in the map will generate a new dynamic map image and browser cache will not be utilized.   You choose to enable or disable dynamic tiling when you create a map resource item (e.g. at design-time using the MapResourceManager control).  The table below lists the default tiling scheme settings for each data source type:
  
  

  Data Source Type	Dynamic Tiling Default
  ArcGIS Server Local	Disabled
  ArcGIS Server Internet	Disabled
  ArcIMS	Enabled
  ArcWeb	Disabled
  OGC\WMS	Disabled
  Graphics	Enabled

  
  Cached (tiled) map resources always utilize the tiling scheme defined by the map service host.   The scheme information provided by the service includes the spatial reference, full extent, tile image properties, and cached levels of detail, each of which defines a scale and number of rows and columns.  The map resource item uses this information along with the Map control extent to determine which cache tiles need to be retrieved.  Since the number of levels remains the same regardless of the map extent, map tiles can be cached by the browser in multiple levels.  This enhances the performance of cached services in the Map because once a map tile is cached by the browser it can be reused.  
  
  The diagram below illustrates the runtime behavior of resource items with different tiling schemes during a simple pan operation on the map.  The pre and post pan extent of the map view is displayed as orange boxes at the bottom of the diagram.  Each resource item type shows the pre (gray) and post (green) map images retrieved from a remote server.  For non-cached (dynamic) resources that have dynamic tiling enabled, the pre pan map view establishes the tiling scheme for th resource and requests one map image (gray).   After the pan event, three map image are generated because the map view extent intersects three tiles in the scheme.    For non-cached resources that do not  have tiling enabled, each map view extent will generate one new map image.  For cached resources, cached map tiles that intersect the map view extent will be retrieved.  In this example, four tiles are requested before the pan.  Two tiles are requested after the pan event.                     
  
  
  
  
  

• Cached Tile Retrieval
  
  The Map control may obtain map images from an ArcGIS Server map service as pre-created tiles, rather than dynamically drawing the map on the server. See Map Caches in Server Help for information on map caching. How the tile is retrieved depends on four factors:
  • Whether the Map control's ImageBlendingMode property is set to browser blending or web-tier blending. Note that if only one resource (service) is added the to the map, or only one resource is currently visible, then the browser-blending approach is used even if web-tier blending is enabled.
  • Whether a cache virtual directory was configured for the service in ArcCatalog or Manager.
  • Connection method to the service: ArcGIS Server Local or ArcGIS Server Internet.
  • Security settings. If a cache virtual directory is configured, tile retrieval differs depending on whether the virtual directory is secured to require authentication. If security is applied, the web application can get tiles whether it provides credentials or not, but the way it retrieves tiles differs. If no cache virtual directory is configured, and if using an ArcGIS Server Internet connection, retrieval differs depending on whether the web service is secured to require authentication. If authentication is required, but the web application or browser fail to provide correct credentials for the tile virtual directory, then the tile can still be retrieved, but through a different and typically less efficient mechanism.
  The following graphic shows how the browser and web application retrieve map tiles based on these factors. Some retrieval approaches are more efficient than others. See the tables that follow for details on each tile-retrieval mechanism.
  
  
  
  • JAVASCRIPT: indicates that the browser retrieves the map tile directly from the Web server, without interacting with the Web application.
  • TILE HANDLER: indicates that the browser requests the tile from an HTTP Handler (TileHandler.ashx) within the Web application. The handler retrieves the tile using the information in the request query string. It also accesses information in the user session.
  
  In each table below, access methods are listed in decreasing order of expected efficiency.
  

  Tile retrieval: Browser blending
  JAVASCRIPT: Virtual Directory	Browser retrieves the image directly by its URL using JavaScript. This is probably the most common scenario when defaults are used to set up the map service and web application, and no security is applied to the map service. It is also typically the fastest way to retrieve map tiles.
  JAVASCRIPT: Tile Web Service	Browser calls an HTTP handler on the Web service running on the ArcGIS Server machine that reads the image from disk and sends back the image as a stream of bytes.
  TILE HANDLER: Virtual Directory	Browser calls an HTTP handler (TileHandler.ashx) on the Web ADF server that uses credentials to access a secured virtual directory and sends back the image as a stream of bytes.
  TILE HANDLER: Tile Web Service	Browser calls an HTTP handler (TileHandler.ashx) on ADF server that uses credentials to access an HTTP handler on ArcGIS Server machine. The handler on The ArcGIS Server machine reads the image from disk and streams back the image as a series of bytes.
  TILE HANDLER: GetMapTile	Browser calls an HTTP handler (TileHandler.ashx) on ADF server that in turn calls a web service method that returns image bytes. The HTTP handler streams back the bytes of the image. In this case, the ArcGIS Server Object Manager and Server Object Container are used to retrieve the tile.

  
  
  

  Tile retrieval: Web tier blending
  WEB TIER: Virtual directory	During page life cycle, the image is read from the virtual directory and is blended to overlay with other resources (layers) in the map. The blended image is then sent to the browser.
  WEB TIER: Tile Web service	During page life cycle, the image is retrieved from an HTTP handler on the ArcGIS Server machine. The handler on the ArcGIS Server machine reads the image from disk and streams back the bytes. The image is blended to overlay with other resources (layers) in the map. The blended image is then sent to the browser.
  WEB TIER: GetMapTile	During page life cycle, the image is retrieved through a Web service method that returns image bytes. The image is blended to overlay with other resources (layers) in the map. The blended image is then sent to the browser.

  
   
• Using the MapHandler
  
  By default, map draw operations do not iterate through the page lifecycle.  Instead an HTTP handler, ESRI.ArcGIS.ADF.Web.UI.WebControls.MapHandler, is solely responsible for managing map draw operations.  Other actions, such as those initiated from map tools, commands, map events, or toc changes, still iterate through the page lifecycle.   The MapHandler enhances map draw performance by skipping the page lifecycle when drawing the map, which reduces the amount of processing overhead.   The EnableMapHandler property on the Map control enables you to choose whether you use the MapHandler or iterate through the page lifecycle for map draw operations.  
     
  One scenario where you may choose to iterate through the page lifecycle is when using pre-9.3 patterns for managing shallowly stateful operations.  For example, in 9.2, managing stateful changes to a pooled server object (shallowly stateful) was possible, given the ability to access server context at the appropriate time to modify and reset the server object.  Since all Web requests associated with Web ADF components in a Web application traversed the page lifecycle (including map draw, queries, toc changes) managing server object merely involved managing when to modify the server object in the lifecycle.  Setting the EnableMapHandler property to false will enable this pattern to function in 9.3.  
  
  In this scenario, you may choose to take advantage of the performance enhancement offered by the MapHandler.   The MapHandler offers a set of events to override and modify resources before and after map draw.   To override the events, create a new class, derive from the MapHandler class, define the events to override, and add a reference to the custom MapHandler in the Web.config file.  Changes to server object state will need to be duplicated or shared for map draw and all other Web requests.  If the code used to manage shallowly stateful operations is packaged in a single class or assembly, events in both the custom MapHandler and page lifecycle can share the same code logic.  See the ArcGIS_AddDynamicData sample for an example of this technique.