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
JavaScript libraries: display_common.js, display_dotnetadf.js, display_map.js, display_vector.js

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.  You should see the following in Visual Studio.NET:
   
     
   
   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.
   
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.  
   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		Fromat 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.
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	ZoomIn
  ALT, left mouse click, hold, and drag box	ZoomOut
  Left mouse click, hold, and move (default mouse action>	Pan
  Num Lock disabled, use keypad	Pan
  Arrow keys, Home, End, Page Up, Page Down	Pan
  CTRL, left mouse click	Identify in the Web Mapping Application template
  Mouse Wheel Up	ZoomIn
  Mouse Wheel Down	ZoomOut

• Refresh 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 the optimum method to programmatically refresh the Map.  Note that if the scale of a map has not changed, the entire map may not need to be explicitly refreshed.
  
  By default, the Map control uses browser blending of map resource images (see Image Blending Mode, below). In this case, you should refresh only the resource that requires it. The new map image for the refreshed resource will be returned to the browser without requiring a new map image for other resources.  Use the following code to determine how to refresh map content.  The variable MyMapResource is the MapResource instance whose content has changed:
   
  [C#]

  if (map.ImageBlendingMode == ImageBlendingMode.WebTier) 
  { map.Refresh(); } 
  else if (map.ImageBlendingMode == ImageBlendingMode.Browser) 
  { map.RefreshResource(MyMapResource.Name); }
  

  
  [VB]

  If map.ImageBlendingMode = ImageBlendingMode.WebTier Then
    map.Refresh()
  ElseIf map.ImageBlendingMode = ImageBlendingMode.Browser Then
    map.RefreshResource(MyMapResource.Name)
  EndIf
  

• Change Scroll Wheel Zoom Direction
  
  By default, when using the mouse scroll wheel to navigate a map, moving the mouse wheel toward you (back) will zoom out and away from you (forward) will zoom in.  The Web ADF uses a JavaScript variable, mouseWheelAwayZoomIn to set this behavior.  By default, the value is true.  To switch this behavior, add the following script content in the aspx page that contains the map control.  This content must be added within or below the HTML form that contains the map :
  
  

  <script language="javascript" type="text/javascript">
    mouseWheelAwayZoomIn = false;
  <script>
  

    

• 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. 
           
• 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.
  

• 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 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.

  
  

• Track pending tiles as map content loads in the browser
  
  As a Web ADF developer working in an asynchronous communication environment, it is often beneficial to provide an end user with some indication that a user action is being processed. Since most Web ADF applications are centered on working with a map, the ability of an end user to effectively interact with map contents is essential. The Web ADF has the ability to asynchronously retrieve map data from multiple sources and consolidate it in a single map control. In general, data sources often differ in the time it takes to respond to a request. Since the Web ADF Map control is capable of rendering map data as it is returned to the browser, it’s possible that some portion of data in the map is visible and accessible before another portion. In this case, it will likely be important to let the end user know when the map control has finished loading map data from any and all sources.
  
  To support this capability, 9.2 service pack 2 includes an enhanced Web ADF JavaScript Map object. The JavaScript Map object has a set of "event handlers" on the pendingTiles property. The pendingTiles property references an array of map image tiles to be rendered. The array is updated when the map needs new image tiles based on the current extent. Events on the pendingTiles property are listed below:
  
  

  Event	Description
  add_onRequestsPending	Triggered when the number of items in the pendingTiles array changes from 0 to a higher value.
  add_onRequestsRemove	Triggered when an item is removed from the pendingTiles array.
  add_onRequestsCompleted	Triggered when the number of item in the pendingTiles array changes to 0.

  
  Use these handlers on the Map object’s pendingTiles property to register a JavaScript function with the event. For example:
  
  

  map.pendingTiles.add_onRequestsPending(showBusyIndicator)

  
  The variable "map" is the JavaScript Map object and "showBusyIndicator" is a JavaScript function to call when the number of items in the pendingTiles array changes from 0 to a higher value. The JavaScript function showBusyIndicator may appear as follows.
  
  

  function showBusyIndicator(sender) {
    showLayer("BusyIndicator");
    if (sender!=null) {
      window.status = "Pending Tiles: " + sender.pendingTiles.length; 
    }
  }

  
  The argument to the function is a reference to the JavaScript Map object. This argument can be used to gain access to map properties, such as the number of map image tiles left in the pendingTiles array. In this example, the number of pending tiles is output to the browser window’s status bar. If the argument is null, the pendingTiles array contains 0 items. The Web ADF includes two convenient JavaScript functions to show or hide a layer (div) based on its id, named showLayer and hideLayer, respectively. The functions are contained in the display_common.js file which, by default, is embedded with the Web ADF controls. In this example, the showLayer function is used to make the contents in the div tag with an id of "BusyIndicator" visible. Included below is a simple Web page with a MapResourceManager, Map, and a div tag containing an image. The JavaScript Map object events are handled after the form to let the content of the form load before interacting with it.
  
  

  <%@ Page Language="C#" AutoEventWireup="true"  CodeFile="Default.aspx.cs" Inherits="_Default" %>
  <%@ Register Assembly="ESRI.ArcGIS.ADF.Web.UI.WebControls, Version=9.2.2.1350, Culture=neutral, PublicKeyToken=8fc3cc631e44ad86"
      Namespace="ESRI.ArcGIS.ADF.Web.UI.WebControls" TagPrefix="esri" %>
  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  <html xmlns="http://www.w3.org/1999/xhtml" >
  <head runat="server">
      <title>Untitled Page</title>
  </head>
  <body>
      <form id="form1" runat="server">
      <div>
          <esri:MapResourceManager ID="MapResourceManager1" runat="server">
              <ResourceItems>
              </ResourceItems>
          </esri:MapResourceManager>
   
          <esri:Map ID="Map1" runat="server" Height="453px" Width="556px" MapResourceManager="MapResourceManager1">
          </esri:Map>    
      </div>         
       
       <div id="BusyIndicator" style="z-index: 1000; left: 25px; width: 100px; position: absolute; top: 422px;height: 100px">
          <img src="images/CircleThickbox.gif" />
       </div> 
     </form>
   
     <script language="javascript" type="text/javascript">
              
          function showBusyIndicator(sender) {
              showLayer("BusyIndicator");
              if (sender!=null) {
                  window.status = "Pending Tiles: " + sender.pendingTiles.length; 
              }  
          }
          
          function showPendingTiles(sender) {
              if (sender!=null) {
                  window.status = "Pending Tiles: " + sender.pendingTiles.length; 
              }  
          }
          
          function hideBusyIndicator(sender) {
              hideLayer("BusyIndicator");
              if (sender!=null) {
                  window.status = ""; 
              }  
          } 
          
          // add busy indicator functions to the map
          map = Maps["Map1"];
          map.pendingTiles.add_onRequestsPending(showBusyIndicator);
          map.pendingTiles.add_onRequestsRemove(showPendingTiles);
          map.pendingTiles.add_onRequestsCompleted(hideBusyIndicator);    
          
     </script>
   
  </body>
  </html>