You are on page 1of 247

Contents

Bing Maps AJAX Control, Version 7.0 ........................................................................................... 11 In This Section............................................................................................................................ 11 See Also ..................................................................................................................................... 11 Getting Started with the 7.0 Map Control ...................................................................................... 11 Create a Bing Maps Account and Get a Key ............................................................................. 12 Get Familiar with the Bing Maps AJAX 7.0 Control ................................................................... 12 What's New in the AJAX Map Control ........................................................................................... 12 New Features ............................................................................................................................. 12 Developing with the 7.0 Map Control............................................................................................. 13 In This Section............................................................................................................................ 13 Loading the AJAX Map Control ..................................................................................................... 13 Displaying the Default Map ........................................................................................................ 13 Customizing the Map When Loading ......................................................................................... 16 Example ..................................................................................................................................... 16 Setting Map Control Parameters ................................................................................................... 17 Parameters ................................................................................................................................. 17 Setting Parameters..................................................................................................................... 18 See Also ..................................................................................................................................... 18 Changing the Map View ................................................................................................................ 18 Setting the Initial Map View ........................................................................................................ 18 Changing the Map View ............................................................................................................. 19 Adding Entities to the Map ............................................................................................................. 22 Adding Single Entities to the Map .............................................................................................. 22 Adding a Pushpin .................................................................................................................... 22 Adding a Shape ...................................................................................................................... 24 Adding Multiple Entities to the Map ............................................................................................ 25 Changing Entities on the Map .................................................................................................... 27 Customizing Your Pushpins .......................................................................................................... 29 Customizing Your Pushpin Icon ................................................................................................. 30 Creating a Pushpin Infobox ........................................................................................................ 31 Displaying Location Search Results Using the REST Services .................................................... 33 Initialize the Map ........................................................................................................................ 33 Add Controls ............................................................................................................................... 34

Make a Geocode REST Request ............................................................................................... 35 Display the Results..................................................................................................................... 36 Getting Route Directions Using the REST Services ...................................................................... 38 Initialize the Map ........................................................................................................................ 38 Construct the Route Request ..................................................................................................... 39 Display the Results..................................................................................................................... 40 Working with Tile Layers ............................................................................................................... 43 Adding a Tile Layer .................................................................................................................... 43 Using Events in the AJAX Control ................................................................................................. 44 Example ..................................................................................................................................... 44 Returning a Localized Map ............................................................................................................ 48 Setting the Culture...................................................................................................................... 48 Supported Cultures .................................................................................................................... 48 Remarks ..................................................................................................................................... 49 Building Your Own Module ............................................................................................................ 49 Develop Your Module ................................................................................................................. 49 Register and Load Your Module ................................................................................................ 51 Use Your Module........................................................................................................................ 51 See Also ..................................................................................................................................... 52 Microsoft.Maps API Reference ...................................................................................................... 52 In This Section............................................................................................................................ 53 Data Structures ....................................................................................................................... 53 Mapping .................................................................................................................................. 53 Entities .................................................................................................................................... 53 User Location .......................................................................................................................... 54 Dynamic Module Loading ....................................................................................................... 54 AltitudeReference Enumeration ..................................................................................................... 54 Constants ................................................................................................................................... 54 Methods ...................................................................................................................................... 54 Example ..................................................................................................................................... 54 AnimationVisibility Enumeration .................................................................................................... 56 Constants ................................................................................................................................... 56 Color Class .................................................................................................................................... 56 Constructor ................................................................................................................................. 56 Properties ................................................................................................................................... 57 Static Methods............................................................................................................................ 57 Methods ...................................................................................................................................... 57

Example ..................................................................................................................................... 58 Coordinates Class ......................................................................................................................... 60 Properties ................................................................................................................................... 60 See Also ..................................................................................................................................... 61 EntityCollection Class .................................................................................................................... 61 Constructor ................................................................................................................................. 61 Methods ...................................................................................................................................... 61 Events ........................................................................................................................................ 63 Example ..................................................................................................................................... 64 EntityCollectionOptions Object ...................................................................................................... 66 Properties ................................................................................................................................... 66 Example ..................................................................................................................................... 67 Events Object ................................................................................................................................ 69 Methods ...................................................................................................................................... 69 Example ..................................................................................................................................... 70 GeoLocationProvider Class ........................................................................................................... 71 Constructor ................................................................................................................................. 72 Methods ...................................................................................................................................... 72 Example ..................................................................................................................................... 74 See Also ..................................................................................................................................... 75 Infobox Class ................................................................................................................................. 75 Constructor ................................................................................................................................. 75 Methods ...................................................................................................................................... 76 Events ........................................................................................................................................ 78 Remarks ..................................................................................................................................... 79 Example ..................................................................................................................................... 79 InfoboxOptions Object ................................................................................................................... 81 Properties ................................................................................................................................... 81 Example ..................................................................................................................................... 83 See Also ..................................................................................................................................... 85 KeyEventArgs Object .................................................................................................................... 85 Properties ................................................................................................................................... 85 Example ..................................................................................................................................... 86 LabelOverlay Enumeration ............................................................................................................ 87 Constants ................................................................................................................................... 87 Methods ...................................................................................................................................... 87 Example ..................................................................................................................................... 88

Location Class (AJAX) ................................................................................................................... 89 Constructor ................................................................................................................................. 89 Properties ................................................................................................................................... 89 Static Methods............................................................................................................................ 89 Methods ...................................................................................................................................... 90 Example ..................................................................................................................................... 90 LocationRect Class ........................................................................................................................ 92 Constructor ................................................................................................................................. 92 Properties ................................................................................................................................... 92 Static Methods............................................................................................................................ 92 Methods ...................................................................................................................................... 93 Example ..................................................................................................................................... 94 Map Class ...................................................................................................................................... 95 Constructor ................................................................................................................................. 96 Properties ................................................................................................................................... 96 Static Methods............................................................................................................................ 96 Methods ...................................................................................................................................... 96 Events ...................................................................................................................................... 100 Example ................................................................................................................................... 102 MapOptions Object ...................................................................................................................... 103 Properties ................................................................................................................................. 103 Example ................................................................................................................................... 108 MapTypeId Enumeration ............................................................................................................. 109 Constants ................................................................................................................................. 109 Example ................................................................................................................................... 109 See Also ................................................................................................................................... 110 Module Loading Methods ............................................................................................................ 110 Methods .................................................................................................................................... 110 Example ................................................................................................................................... 112 See Also ................................................................................................................................... 114 MouseEventArgs Object .............................................................................................................. 114 Properties ................................................................................................................................. 114 Methods .................................................................................................................................... 115 Example ................................................................................................................................... 115 PixelReference Enumeration ....................................................................................................... 117 Constants ................................................................................................................................. 117 Methods .................................................................................................................................... 117 Example ................................................................................................................................... 117

Point Class ................................................................................................................................... 119 Constructor ............................................................................................................................... 119 Properties ................................................................................................................................. 119 Static Methods.......................................................................................................................... 120 Methods .................................................................................................................................... 120 Example ................................................................................................................................... 120 Polygon Class (AJAX) ................................................................................................................. 122 Constructor ............................................................................................................................... 122 Methods .................................................................................................................................... 122 Events ...................................................................................................................................... 123 Example ................................................................................................................................... 124 PolygonOptions Object ................................................................................................................ 126 Properties ................................................................................................................................. 126 Example ................................................................................................................................... 127 Polyline Class .............................................................................................................................. 128 Constructor ............................................................................................................................... 128 Methods .................................................................................................................................... 128 Events ...................................................................................................................................... 130 Example ................................................................................................................................... 130 PolylineOptions Object ................................................................................................................ 132 Properties ................................................................................................................................. 132 Example ................................................................................................................................... 133 Position Class .............................................................................................................................. 134 Properties ................................................................................................................................. 134 See Also ................................................................................................................................... 134 PositionCircleOptions Object ....................................................................................................... 135 Properties ................................................................................................................................. 135 Example ................................................................................................................................... 135 PositionError Class ...................................................................................................................... 137 Properties ................................................................................................................................. 137 See Also ................................................................................................................................... 137 PositionOptions Object ................................................................................................................ 137 Properties ................................................................................................................................. 138 Example ................................................................................................................................... 139 Pushpin Class (AJAX) ................................................................................................................. 141 Constructor ............................................................................................................................... 141 Methods .................................................................................................................................... 141

Events ...................................................................................................................................... 143 Example ................................................................................................................................... 144 PushpinOptions Object ................................................................................................................ 145 Properties ................................................................................................................................. 145 Example ................................................................................................................................... 146 TileLayer Class ............................................................................................................................ 148 Constructor ............................................................................................................................... 148 Methods .................................................................................................................................... 148 Events ...................................................................................................................................... 149 Example ................................................................................................................................... 149 See Also ................................................................................................................................... 151 TileLayerOptions Object .............................................................................................................. 151 Properties ................................................................................................................................. 151 Example ................................................................................................................................... 152 See Also ................................................................................................................................... 154 TileSource Class.......................................................................................................................... 154 Constructor ............................................................................................................................... 154 Methods .................................................................................................................................... 154 Example ................................................................................................................................... 155 See Also ................................................................................................................................... 156 TileSourceOptions Object ............................................................................................................ 156 Properties ................................................................................................................................. 156 Example ................................................................................................................................... 157 See Also ................................................................................................................................... 159 ViewOptions Object ..................................................................................................................... 159 Properties ................................................................................................................................. 159 Remarks ................................................................................................................................... 160 Example ................................................................................................................................... 160 Microsoft.Maps.Directions API Reference ................................................................................... 162 In This Section.......................................................................................................................... 162 BusinessDetails Class ................................................................................................................. 163 Properties ................................................................................................................................. 163 BusinessDisambiguationSuggestion Class ................................................................................. 164 Properties ................................................................................................................................. 164 Example ................................................................................................................................... 165 See Also ................................................................................................................................... 168

DirectionsErrorEventArgs Object................................................................................................. 168 Properties ................................................................................................................................. 168 Example ................................................................................................................................... 168 DirectionsEventArgs Object ......................................................................................................... 171 Properties ................................................................................................................................. 171 Example ................................................................................................................................... 171 DirectionsManager Class ............................................................................................................ 173 Constructor ............................................................................................................................... 173 Methods .................................................................................................................................... 173 Events ...................................................................................................................................... 177 Example ................................................................................................................................... 179 DirectionsRenderOptions Object ................................................................................................. 181 Properties ................................................................................................................................. 181 DirectionsRequestOptions Object ............................................................................................... 183 Properties ................................................................................................................................. 183 DirectionsStep Class ................................................................................................................... 185 Properties ................................................................................................................................. 185 DirectionsStepEventArgs Object ................................................................................................. 186 Properties ................................................................................................................................. 186 DirectionsStepRenderEventArgs Object ..................................................................................... 187 Properties ................................................................................................................................. 187 DirectionsStepWarning Class ...................................................................................................... 188 Properties ................................................................................................................................. 188 DirectionsStepWarningType Enumeration .................................................................................. 188 Constants ................................................................................................................................. 188 Disambiguation Class .................................................................................................................. 189 Properties ................................................................................................................................. 189 Example ................................................................................................................................... 190 See Also ................................................................................................................................... 193 DistanceUnit Enumeration (AJAX) .............................................................................................. 193 Constants ................................................................................................................................. 193 LocationDisambiguationSuggestion Class .................................................................................. 193 Properties ................................................................................................................................. 193 Example ................................................................................................................................... 194 See Also ................................................................................................................................... 197

ManeuverType Enumeration (AJAX) ........................................................................................... 197 Constants ................................................................................................................................. 197 ResetDirectionsOptions Object ................................................................................................... 197 Properties ................................................................................................................................. 197 Route Class (AJAX) ..................................................................................................................... 198 Properties ................................................................................................................................. 198 RouteAvoidance Enumeration ..................................................................................................... 198 Constants ................................................................................................................................. 198 RouteIconType Enumeration ....................................................................................................... 199 Constants ................................................................................................................................. 199 RouteLeg Class (AJAX) ............................................................................................................... 200 Properties ................................................................................................................................. 200 Example ................................................................................................................................... 201 RouteMode Enumeration ............................................................................................................. 203 Constants ................................................................................................................................. 203 RouteOptimization Enumeration (AJAX) ..................................................................................... 203 Constants ................................................................................................................................. 203 RoutePath Class (AJAX) ............................................................................................................. 204 Properties ................................................................................................................................. 204 RouteResponseCode Enumeration ............................................................................................. 205 Constants ................................................................................................................................. 205 RouteSelectorEventArgs Object .................................................................................................. 206 Properties ................................................................................................................................. 207 RouteSelectorRenderEventArgs Object ...................................................................................... 207 Properties ................................................................................................................................. 207 RouteSubLeg Class ..................................................................................................................... 207 Properties ................................................................................................................................. 208 RouteSummary Class (AJAX) ..................................................................................................... 208 Properties ................................................................................................................................. 208 Example ................................................................................................................................... 209 RouteSummaryRenderEventArgs Object .................................................................................... 211 Properties ................................................................................................................................. 211 TimeType Enumeration ............................................................................................................... 212

Constants ................................................................................................................................. 212 TransitLine Class ......................................................................................................................... 212 Properties ................................................................................................................................. 212 TransitOptions Object .................................................................................................................. 213 Properties ................................................................................................................................. 213 Waypoint Class (AJAX) ............................................................................................................... 213 Constructor ............................................................................................................................... 214 Methods .................................................................................................................................... 214 Events ...................................................................................................................................... 216 WaypointEventArgs Object .......................................................................................................... 216 Properties ................................................................................................................................. 216 WaypointOptions Object .............................................................................................................. 216 Properties ................................................................................................................................. 216 WaypointRenderEventArgs Object .............................................................................................. 217 Properties ................................................................................................................................. 217 Microsoft.Maps.Traffic API Reference ......................................................................................... 218 In This Section.......................................................................................................................... 218 TrafficLayer Class ........................................................................................................................ 218 Constructor ............................................................................................................................... 218 Methods .................................................................................................................................... 218 Example ................................................................................................................................... 219 Microsoft.Maps.VenueMaps API Reference ............................................................................... 220 In This Section.......................................................................................................................... 220 Floor Class ................................................................................................................................... 221 Properties ................................................................................................................................. 221 Example ................................................................................................................................... 221 Footprint Class............................................................................................................................. 223 Properties ................................................................................................................................. 224 Example ................................................................................................................................... 224 Metadata Class ............................................................................................................................ 226 Properties ................................................................................................................................. 226 Example ................................................................................................................................... 227 NearbyVenue Class ..................................................................................................................... 229 Properties ................................................................................................................................. 229 Example ................................................................................................................................... 229

NearbyVenueOptions Object ....................................................................................................... 231 Properties ................................................................................................................................. 231 Example ................................................................................................................................... 231 Polygon Class (Venue Map) ........................................................................................................ 233 Properties ................................................................................................................................. 233 Primitive Class ............................................................................................................................. 233 Properties ................................................................................................................................. 233 Methods .................................................................................................................................... 234 Example ................................................................................................................................... 234 VenueMap Class ......................................................................................................................... 236 Properties ................................................................................................................................. 236 Methods .................................................................................................................................... 237 Events ...................................................................................................................................... 238 Example ................................................................................................................................... 239 VenueMapCreationOptions Object .............................................................................................. 241 Properties ................................................................................................................................. 241 Example ................................................................................................................................... 242 VenueMapFactory Class ............................................................................................................. 243 Constructor ............................................................................................................................... 243 Methods .................................................................................................................................... 244 Example ................................................................................................................................... 244 Bing Maps AJAX Control 7.0 Supported Browsers ..................................................................... 246 Supported Browsers ................................................................................................................. 246 Bing Maps AJAX Control 7.0 Developer Resources ................................................................... 247 Developer Resources ............................................................................................................... 247 Account Issues ......................................................................................................................... 247 Licensing Questions ................................................................................................................. 247

Bing Maps AJAX Control, Version 7.0


Bing Maps is an online mapping service that enables users to search, discover, explore, plan, and share information about specific locations. By using enhanced road maps, labeled aerial photo views, and low-angle high-resolution aerial photos, Bing Maps AJAX Control 7.0, in conjunction with the Bing Maps REST Services, provides unique opportunities for developers to incorporate both location and local search features into their Web applications. The Bing Maps AJAX Control 7.0 software development kit (SDK) consists of a complete set of reference topics that cover the Bing Maps AJAX Control 7.0 application programming interface (API). For extra code snippets and feature samples, the Bing Maps AJAX Control 7.0 Interactive SDK is also available. If you are reading this help file online, you can download either the CHM or PDF version of this SDK for offline viewing. If you are looking for documentation for the legacy AJAX Map Control, see Bing Maps AJAX Control, Version 6.3 SDK.

In This Section
Getting Started with the 7.0 Map Control What's New in the AJAX Map Control Developing with the 7.0 Map Control API Reference Supported Browsers Developer Resources

See Also
Terms and Conditions

Getting Started with the 7.0 Map Control


The Bing Maps AJAX Control 7.0 is a JavaScript control that contains the objects, methods, and events that allow you to display maps powered by Bing Maps on your Web site. The sections in this topic describe the steps you need to take to start using the Bing Maps AJAX Control 7.0.

11

Create a Bing Maps Account and Get a Key


Before you begin developing your application, you need to create a developer account on the Bing Maps Account Center. A Bing Maps Developer Account allows you to create a Bing Maps Key to use in your map application. Getting a key is described in Getting a Bing Maps Key.

When the Bing Maps AJAX Control 7.0 is loaded with a valid Bing Maps Key, Bing Maps counts sessions. A session begins with the load of the Bing Maps AJAX Control 7.0 into a users browser and includes all Bing Maps AJAX Control 7.0 interactions until the browser is closed or the user moves to a different page. Detailed information about Bing Maps usage reports is found in Viewing Bing Maps Usage Reports.

Get Familiar with the Bing Maps AJAX 7.0 Control


The Developing with the 7.0 Map Control section of this SDK contains topics that describe how to use the features provided by the AJAX map control.

What's New in the AJAX Map Control


Welcome to the latest release of the Bing Maps AJAX Control 7.0!

New Features
This release of the map control includes the following new features: Calculate driving directions Use the new Microsoft.Maps.Directions module to easily calculate directions and display a route on your map. Display a venue map Discover and display maps for nearby venues such as malls and shopping centers using the Microsoft.Maps.VenueMaps module. Show current traffic Show or hide current traffic on the map using the Microsoft.Maps.Traffic module. Set polyline and polygon stroke dash To further customize your shapes, use the new property strokeDashArray of the PolylineOptions Object and PolygonOptions Object. New tile layer property and event Ensure the best performance of your tile layer during animation by modifying the new animationDisplay property of the TileLayerOptions Object. Also, determine when your tile layer is fully downloaded using the new tiledownloadcomplete event. New map options For increased flexibility, new options showBreadcrumb, disableBirdseye, disablePanning, and disableZooming have been added to the MapOptions Object.

12

Developing with the 7.0 Map Control


The topics in this section will help you to start using the Bing Maps AJAX Control 7.0.

In This Section
Loading the AJAX Map Control Setting Map Control Parameters Changing the Map View Adding Entities to the Map Customizing Your Pushpins Displaying Location Search Results Using the REST Services Calculating Directions Using the Directions Module Working with Tile Layers Using Events in the AJAX Control Returning a Localized Map Building Your Own Module

Loading the AJAX Map Control


This topic describes how to load the Bing Maps AJAX Control 7.0 into your Web page to display a map. This is the first step you need to take for any page that uses the map control.

Displaying the Default Map


Displaying the default map, which includes all of the navigation functionality, consists of the following steps: 1. At the top of the HTML page add the following DOCTYPE declaration. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 2. In the header section of an HTML page, add a META element with the charset attribute set to "utf-8", as follows. <meta http-equiv="Content-Type" content="text/html; charset=utf8"/>

It is recommended that you use UTF-8 encoding in your web page. 3. Also in the header section, add a reference to the map control, as follows.

13

<script charset="UTF-8" type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx? v=7.0"> </script> To use SSL, add the s parameter to the reference as shown below. <script charset="UTF-8" type="text/javascript" src="https://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx ?v=7.0&s=1"> </script> 4. In the body of the page, add a DIV element to the page to contain the map. The size of the map is defined by the height and width of the DIV element. The position of the map is set by using the "position", "top", and "left" properties. You can set these values either inline or by defining the values in a style class and then referencing that class, as follows. <div id='mapDiv' style="position:absolute; width:400px; height:400px;"></div> or .map { position: absolute; top: 20; left: 10; width: 400px; height: 400px; border:#555555 2px solid; } ... <div id="mapDiv" class="map"></div>

If you do not specify a width/height, the width/height of the div is used. For crossbrowser compatibility, you should always specify the position attribute (both "absolute" and "relative" are valid values). If you use a percentage width and or height in the map DIV, it is the percentage of the parent width or height, respectively.

The navigation control, map type selector, and breadcrumb may not work properly if you use margin to position the map. Use CSS absolute or relative positioning instead. 5. Next, within a new script tag, create a function that can be called when your web page loads. <script type="text/javascript"> 14

function GetMap() { } </script> Modify the body tag so that the GetMap function is called onload. <body onload="GetMap();"> 6. Finally, create an instance of the Map Class in the GetMap function. You also need to include a map options object to contain your credentials, which is your Bing Maps Key. See the Getting a Bing Maps Key topic. <script type="text/javascript"> var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials:"Your Bing Maps Key"}); </script> The full code is below.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

function GetMap() { var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials:"Your Bing Maps Key"}); }

</script>

15

</head> <body onload="GetMap();"> <div id='mapDiv' style="position:absolute; width:400px; height:400px;"></div> </body> </html>

Customizing the Map When Loading


You can also specify other options when the map is first loaded, such as the location, zoom level, and the imagery of the map. To do this, pass in MapOptions or ViewOptions to the Map constructor. The code below sets the imagery to Aerial.
var mapOptions = { credentials: "Your Bing Maps Key", mapTypeId: Microsoft.Maps.MapTypeId.aerial }

var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), mapOptions);

Example
The following code shows a complete Web page that loads a map. Valid map types are found in the MapTypeId Enumeration topic.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript"> function GetMap() {

var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),

16

{credentials: "Your Bing Maps Key", center: new Microsoft.Maps.Location(45.5, -122.5), mapTypeId: Microsoft.Maps.MapTypeId.road, zoom: 7}); } </script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

Setting Map Control Parameters


This topic describes map control parameters.

Parameters
The following table contains available parameters for the map control reference.
Parameter Values Description

7.0

Specifies a major API version. The default value is the latest version, which is 7.0. Specifies whether to use SSL. Set this value equal to 1 to use SSL. The default value is 0. Specifies the market to use, which defines the language Bing Maps AJAX Control 7.0 uses. The default value is "en-US" (English). Specifies the name of a JavaScript function to call when the map control script is loaded. The name must contain only alphanumeric characters. 17

0, 1

mkt

See the Returning a Localized Map topic for a list of values.

onscriptload

A string specifying a function name.

Parameter

Values

Description

The CSS and tiles will not be loaded when this function is called. This parameter is useful for loading the map control asynchronously, which can improve your site performance by allowing the map control script to load in parallel with other content.

Setting Parameters
To add a parameter to the map control src URL, add a "?", the parameter, and set it "=" to one of the allowable values. Use "&" to separate parameters. The following example sets the map control version to 7.0 and the market to Italian.
<script charset="UTF-8" type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0&mkt=it-IT"> </script>

See Also
Loading the AJAX Map Control Returning a Localized Map

Changing the Map View


This topic describes how to change the map that is displayed.

Setting the Initial Map View


You can set the map view when you first load the map you can use any of the options available in the MapOptions Object or ViewOptions Object. The code below initializes the map with a specific view. The imagery displayed is set to Birds eye using the mapTypeId option. Valid map type IDs are listed in the MapTypeId Enumeration topic.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

18

<html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript"> function GetMap() { var mapOptions = { credentials: "Your Bing Maps Key", center: new Microsoft.Maps.Location(47.592, -122.332), mapTypeId: Microsoft.Maps.MapTypeId.birdseye, zoom: 17, showScalebar: false }

var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), mapOptions); } </script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:600px; height:600px;"></div> </body> </html>

Changing the Map View


If you want to change the map after it has loaded, use the setView method of the Map Class. The ViewOptions Object contains available options that can be set. The example below sets the map view to the specified zoom level.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

19

<html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials: "Your Bing Maps Key", mapTypeId: Microsoft.Maps.MapTypeId.road}); }

function SetZoom() { var zoomLevel = parseInt(document.getElementById('txtZoom').value); map.setView({zoom:zoomLevel}); }

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:500px; height:500px;"></div> Zoom Level: <input id="txtZoom" type="text" value="1"/> <input id="btnZoom" type="button" value="Click to set the zoom level" onclick="SetZoom();"/>

</body>

20

</html>

To set the boundaries of the view instead of centering on a point, use the bounds option as shown in the code below.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() {

map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials: "Your Bing Maps Key"});

var viewBoundaries = Microsoft.Maps.LocationRect.fromLocations(new Microsoft.Maps.Location(47.618594, -122.347618), new Microsoft.Maps.Location(47.620700, 122.347584), new Microsoft.Maps.Location(47.622052, -122.345869));

map.setView({ bounds: viewBoundaries});

</script> </head> <body onload="GetMap();">

21

<div id='mapDiv' style="position:relative; width:500px; height:500px;"></div> </body> </html>

Adding Entities to the Map


This topic describes how to add entities to the map. An Entity can be any one of the following types: Polygon, Polyline, Pushpin, TileLayer, or EntityCollection. Information about working with tile layers is in the Working with Tile Layers topic.

Adding Single Entities to the Map


To add a pushpin, polygon, or polyline to the map, simply create your object then add the entity to the entities property of the map.

Adding a Pushpin
The following code adds a pushpin to the center of the map with the label 1.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

function GetMap() { // Initialize the map var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials:"Your Bing Maps Key"});

// Retrieve the location of the map center

22

var center = map.getCenter();

// Add a pin to the center of the map var pin = new Microsoft.Maps.Pushpin(center, {text: '1'}); map.entities.push(pin); }

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

To add a pushpin to a custom latitude and longitude coordinate, pass the Location object to the Pushpin constructor, then set the view based on the location as shown below.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});

23

// Define the pushpin location var loc = new Microsoft.Maps.Location(47.592, -122.332);

// Add a pin to the map var pin = new Microsoft.Maps.Pushpin(loc); map.entities.push(pin);

// Center the map on the location map.setView({center: loc, zoom: 10});

</script> </head> <body onload="GetMap();"> <div id='myMap' style="position:relative; width:400px; height:400px;"></div> </body> </html>

Adding a Shape
To add a polyline or a polygon, use the same method used to add a pushpin. First, create your shape then add it to the entities property of the map. The following code adds a purple polygon to the map.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

24

<script type="text/javascript">

function GetMap() { // Initialize the map var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Your Bing Maps Key"});

// Create a polygon var vertices = new Array(new Microsoft.Maps.Location(20,-20), new Microsoft.Maps.Location(20,20), new Microsoft.Maps.Location(-20,20), new Microsoft.Maps.Location(-20,-20), new Microsoft.Maps.Location(20,-20)); var polygoncolor = new Microsoft.Maps.Color(100,100,0,100); var polygon = new Microsoft.Maps.Polygon(vertices,{fillColor: polygoncolor, strokeColor: polygoncolor});

// Add the polygon to the map map.entities.push(polygon); }

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

Adding Multiple Entities to the Map


If you want to add multiple entities to the map at one time, first create an EntityCollection then add this collection to the map. The code below adds a polygon with pushpins at its corners.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head>

25

<title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

function GetMap() { // Initialize the map var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials:"Your Bing Maps Key"});

// Create the locations var location1 = new Microsoft.Maps.Location(20,-20); var location2 = new Microsoft.Maps.Location(20,20); var location3 = new Microsoft.Maps.Location(-20,20); var location4 = new Microsoft.Maps.Location(-20,-20);

// Create a polygon var vertices = new Array(location1, location2, location3, location4, location1); var polygoncolor = new Microsoft.Maps.Color(100,100,0,100); var polygon = new Microsoft.Maps.Polygon(vertices,{fillColor: polygoncolor, strokeColor: polygoncolor});

// Create the entity collection with the polygon and pushpins at each corner var polygonWithPins = new Microsoft.Maps.EntityCollection(); polygonWithPins.push(polygon); polygonWithPins.push(new Microsoft.Maps.Pushpin(location1)); polygonWithPins.push(new Microsoft.Maps.Pushpin(location2)); polygonWithPins.push(new Microsoft.Maps.Pushpin(location3)); polygonWithPins.push(new Microsoft.Maps.Pushpin(location4));

26

// Add the shape to the map map.entities.push(polygonWithPins)

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

Changing Entities on the Map


Once entities have been added to the map, you can use the methods of the map entities collection to change and manipulate those entities. The code implements a button to change the color of a shape on the map.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

// Define colors var blue = new Microsoft.Maps.Color(100, 0, 0, 200); var green = new Microsoft.Maps.Color(100, 0, 100, 100);

27

var purple = new Microsoft.Maps.Color(100, 100, 0, 100);

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Your Bing Maps Key"});

// Create the locations var location1 = new Microsoft.Maps.Location(20,-20); var location2 = new Microsoft.Maps.Location(20,20); var location3 = new Microsoft.Maps.Location(-20,20); var location4 = new Microsoft.Maps.Location(-20, -20); var location5 = new Microsoft.Maps.Location(40, 0);

// Create some shapes var triangleVertices = new Array(location1, location2, location5, location1); var triangle = new Microsoft.Maps.Polygon(triangleVertices, { fillColor: blue, strokeColor: blue });

var squareVertices = new Array(location1, location2, location3, location4, location1); var square = new Microsoft.Maps.Polygon(squareVertices,{fillColor: purple, strokeColor:purple});

// Add the shapes to the map map.entities.push(triangle); map.entities.push(square); }

function ChangePolygonColor() {

28

// Get the map square entity. We know square was the last entity added, // so we can calculate the index.

var mapSquare = map.entities.get(map.entities.getLength()-1);

// Get the current color var currentColor = mapSquare.getFillColor();

if((currentColor.toString()) == (purple.toString())) { // Change it to green mapSquare.setOptions({fillColor: green, strokeColor:green}); } else { // Change it back to purple mapSquare.setOptions({fillColor:purple, strokeColor:purple}); } } </script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> <input id="btnChangeColor" type="button" value="Change Polygon Color" onclick="ChangePolygonColor();"/> </body> </html>

Customizing Your Pushpins


The Bing Maps AJAX Control, Version 7.0 provides flexible pushpin functionality. Use options provided in the PushpinOptions Object to customize your pushpins. This topic describes how to customize your pushpin icon as well as how to create a pushpin info box. 29

Customizing Your Pushpin Icon


If you do not want to use the default pushpin icon, you can set the icon property of the PushpinOptions to the image you want to use instead. This example uses the image below, named BluePushpin.png, as the pushpin icon.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});

// Retrieve the location of the map center var center = map.getCenter();

// Add a pin to the center of the map, using a custom icon var pin = new Microsoft.Maps.Pushpin(center, {icon: 'BluePushpin.png', width: 50, height: 50, draggable: true});

30

map.entities.push(pin); }

</script> </head> <body onload="GetMap();"> <div id='myMap' style="position:relative; width:400px; height:400px;"></div> </body> </html>

Creating a Pushpin Infobox


The Bing Maps AJAX Control, Version 7.0 has built-in pushpin info box functionality which you can customize to suit the needs of your application. To create an info box, use the Infobox and InfoboxOptions types. The example below shows how to display an info box when a pushpin is clicked.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null; var pinInfobox = null;

function GetMap()

31

{ // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});

// Retrieve the location of the map center var center = map.getCenter();

// Add a pin to the center of the map var pin = new Microsoft.Maps.Pushpin(center, {text: '1'});

// Create the infobox for the pushpin pinInfobox = new Microsoft.Maps.Infobox(pin.getLocation(), {title: 'My Pushpin', description: 'This pushpin is located at (0,0).', visible: false, offset: new Microsoft.Maps.Point(0,15)});

// Add handler for the pushpin click event. Microsoft.Maps.Events.addHandler(pin, 'click', displayInfobox);

// Hide the infobox when the map is moved. Microsoft.Maps.Events.addHandler(map, 'viewchange', hideInfobox);

// Add the pushpin and infobox to the map map.entities.push(pin); map.entities.push(pinInfobox);

function displayInfobox(e) { pinInfobox.setOptions({ visible:true });

32

function hideInfobox(e) { pinInfobox.setOptions({ visible: false }); } </script> </head> <body onload="GetMap();"> <div id='myMap' style="position:relative; width:500px; height:500px;"></div> </body> </html>

Displaying Location Search Results Using the REST Services


The Bing Maps AJAX Control, version 7.0 does not have built in functionality to return find results, but you can easily use the Bing Maps REST Services to geocode locations that you can then display on the map.

Initialize the Map


Before you add geocoding functionality, initialize the map using the following code.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

33

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Your Bing Maps Key", mapTypeId:Microsoft.Maps.MapTypeId.road});

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

Add Controls
For this sample, add a text box and a Geocode button. In your script, create a ClickGeocode function that is called when the button is clicked.
<input id="txtQuery" type="text" value="Portland"/> <input type="button" value="Geocode" onclick="ClickGeocode()"/>

Since the Bing Maps REST Services also require a Bing Maps Key, you need to first retrieve the key from the map object to ensure the session is valid. Use the getCredentials method of the Map Class to do this. The getCredentials method takes a function to call when the credentials are retrieved.
function ClickGeocode(credentials) { map.getCredentials(MakeGeocodeRequest); }

34

Make a Geocode REST Request


Next, make a geocode request to the Bing Maps REST Services using the value in the txtQuery input box and the credentials. The Bing Maps REST Services can return an XML or JSON response object. For JavaScript code, JSON is more appropriate, so set output=JSON. This means that you need to also set a jsonp callback function name. In this sample the callback function is named GeocodeCallback. Finally, since you do not know if the text provided is a place name or an address, supply the locationQuery parameter and set it to the value of the txtQuery text box. Your REST geocode request looks like this:
var geocodeRequest = "http://dev.virtualearth.net/REST/v1/Locations/" + document.getElementById('txtQuery').value + "?output=json&jsonp=GeocodeCallback&key=" + credentials;

Now add script to make the REST request.


function MakeGeocodeRequest(credentials) { var geocodeRequest = "http://dev.virtualearth.net/REST/v1/Locations/" + document.getElementById('txtQuery').value + "?output=json&jsonp=GeocodeCallback&key=" + credentials;

CallRestService(geocodeRequest); }

function CallRestService(request) { var script = document.createElement("script"); script.setAttribute("type", "text/javascript"); script.setAttribute("src", request); document.body.appendChild(script); } function GeocodeCallback(result) { // Do something with the result }

35

Display the Results


Finally, add code to the GeocodeCallback function to set the map view to the found location and add a pushpin at that location. The final code is shown below.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Your Bing Maps Key", mapTypeId:Microsoft.Maps.MapTypeId.road});

function ClickGeocode(credentials) { map.getCredentials(MakeGeocodeRequest); }

function MakeGeocodeRequest(credentials) {

36

var geocodeRequest = "http://dev.virtualearth.net/REST/v1/Locations/" + document.getElementById('txtQuery').value + "?output=json&jsonp=GeocodeCallback&key=" + credentials;

CallRestService(geocodeRequest); }

function GeocodeCallback(result) { alert("Found location: " + result.resourceSets[0].resources[0].name);

if (result && result.resourceSets && result.resourceSets.length > 0 && result.resourceSets[0].resources && result.resourceSets[0].resources.length > 0) { // Set the map view using the returned bounding box var bbox = result.resourceSets[0].resources[0].bbox; var viewBoundaries = Microsoft.Maps.LocationRect.fromLocations(new Microsoft.Maps.Location(bbox[0], bbox[1]), new Microsoft.Maps.Location(bbox[2], bbox[3])); map.setView({ bounds: viewBoundaries});

// Add a pushpin at the found location var location = new Microsoft.Maps.Location(result.resourceSets[0].resources[0].point.coordinates[0], result.resourceSets[0].resources[0].point.coordinates[1]); var pushpin = new Microsoft.Maps.Pushpin(location); map.entities.push(pushpin); } }

function CallRestService(request) {

37

var script = document.createElement("script"); script.setAttribute("type", "text/javascript"); script.setAttribute("src", request); document.body.appendChild(script); }

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> <input id="txtQuery" type="text" value="Portland"/> <input type="button" value="Geocode" onclick="ClickGeocode()"/> </body> </html>

Getting Route Directions Using the REST Services


The latest release of the Bing Maps AJAX Control 7.0 provides directions functionality in the Microsoft.Maps.Directions module. This module allows you to easily customize, calculate, and display directions and a route on your web site without needing to use REST services. Get started by going to the DirectionsManager Class topic, which contains information about the calculateDirections method and sample code. This topic describes how to use the Bing Maps REST Services to calculate and display a route on the map.

Initialize the Map


Before you add route functionality, initialize the map using the following code.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title>

38

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Your Bing Maps Key", mapTypeId: Microsoft.Maps.MapTypeId.road });

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

Construct the Route Request


Next, add input controls and construct the Bing Maps REST Services Route request. In this example, a route is calculated between a specified start and end point. Add two text boxes and a button to initiate the route calculation.
<input id="txtStart" type="text" value="Seattle"/> <input id="txtEnd" type="text" value="Portland"/> <input type="button" value="Calculate Route" onclick="ClickRoute()"/>

Then, construct the REST route request using the input values. 39

var routeRequest = "http://dev.virtualearth.net/REST/v1/Routes?wp.0=" + document.getElementById('txtStart').value + "&wp.1=" + document.getElementById('txtEnd').value + "&routePathOutput=Points&output=json&jsonp=RouteCallback&key=" + credentials;

Display the Results


Finally, add code to make the route request when the button is clicked, and add code to the RouteCallback function to set the map view and draw the route. The final code is shown below.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Your Bing Maps Key", mapTypeId: Microsoft.Maps.MapTypeId.road });

function ClickRoute(credentials) {

40

map.getCredentials(MakeRouteRequest); }

function MakeRouteRequest(credentials) { var routeRequest = "http://dev.virtualearth.net/REST/v1/Routes?wp.0=" + document.getElementById('txtStart').value + "&wp.1=" + document.getElementById('txtEnd').value + "&routePathOutput=Points&output=json&jsonp=RouteCallback&key=" + credentials;

CallRestService(routeRequest);

function RouteCallback(result) {

if (result && result.resourceSets && result.resourceSets.length > 0 && result.resourceSets[0].resources && result.resourceSets[0].resources.length > 0) {

// Set the map view var bbox = result.resourceSets[0].resources[0].bbox; var viewBoundaries = Microsoft.Maps.LocationRect.fromLocations(new Microsoft.Maps.Location(bbox[0], bbox[1]), new Microsoft.Maps.Location(bbox[2], bbox[3])); map.setView({ bounds: viewBoundaries});

// Draw the route

41

var routeline = result.resourceSets[0].resources[0].routePath.line; var routepoints = new Array();

for (var i = 0; i < routeline.coordinates.length; i++) {

routepoints[i]=new Microsoft.Maps.Location(routeline.coordinates[i][0], routeline.coordinates[i][1]); }

// Draw the route on the map var routeshape = new Microsoft.Maps.Polyline(routepoints, {strokeColor:new Microsoft.Maps.Color(200,0,0,200)}); map.entities.push(routeshape);

} }

function CallRestService(request) { var script = document.createElement("script"); script.setAttribute("type", "text/javascript"); script.setAttribute("src", request); document.body.appendChild(script); }

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> <input id="txtStart" type="text" value="Seattle"/> <input id="txtEnd" type="text" value="Portland"/> <input type="button" value="Calculate Route" onclick="ClickRoute()"/>

42

</body> </html>

Working with Tile Layers


This topic describes how to add a custom tile layer to the map.

Adding a Tile Layer


A tile layer is a valid map entity, so after you construct your layer, you can add it to the map using the push method of the map entities collection. The code below adds a custom tile layer to the map.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

function GetMap() { // Initialize the map var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Your Bing Maps Key", center:new Microsoft.Maps.Location(48.03,-122.4), zoom:12, mapTypeId: Microsoft.Maps.MapTypeId.road });

try { // Create the tile layer source

43

var tileSource = new Microsoft.Maps.TileSource({uriConstructor: 'http://www.microsoft.com/maps/isdk/ajax/layers/lidar/{quadkey}.png'});

// Construct the layer using the tile source var tilelayer= new Microsoft.Maps.TileLayer({ mercator: tileSource, opacity: .7 });

// Push the tile layer to the map map.entities.push(tilelayer);

} catch(err) { alert( 'Error Message:' + err.message); } }

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

Using Events in the AJAX Control


The Bing Maps AJAX Control 7.0 provides many events to allow your application to respond to user actions. The EntityCollection, Map, Pushpin, Polyline, and Polygon classes all have event members. The code examples in this topic show how to use the Map click event and the EntityCollection entityadded event.

Example
The example below shows how to use the Map click event to display the coordinate values of the clicked point in a text box.

44

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});

//Add handler for the map click event. Microsoft.Maps.Events.addHandler(map, 'click', displayLatLong);

function displayLatLong(e) { if (e.targetType == "map") { var point = new Microsoft.Maps.Point(e.getX(), e.getY()); var loc = e.target.tryPixelToLocation(point); document.getElementById("textBox").value= loc.latitude + ", " + loc.longitude;

45

</script> </head> <body onload="GetMap();"> <div id='myMap' style="position:relative; width:400px; height:400px;"></div><br> <b>Click the map to display the coordinate values at that point.</b><br> Latitude, Longitude: <input id='textBox' type="text" style="width:250px;"/> </body> </html>

You can expand the example above and add a pushpin wherever the user clicks. The code below also greys out the other pushpins in the entities collection when a new one is added.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null; var noPins = true;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});

46

// Add a handler for the map click event. Microsoft.Maps.Events.addHandler(map, 'click', addPin);

// Add a handler to function that will grey out // other pins in the collection when a new one is added

Microsoft.Maps.Events.addHandler(map.entities, 'entityadded', shadePins);

function addPin(e) { if (e.targetType == "map") { var point = new Microsoft.Maps.Point(e.getX(), e.getY()); var loc = e.target.tryPixelToLocation(point); var pin = new Microsoft.Maps.Pushpin(loc);

map.entities.push(pin); } }

function shadePins(e) {

if (noPins) {

// If there aren't yet any pins on the map, do not grey the pin out. noPins = false;

} else { var pin = null;

// Loop through the collection of pushpins on the map and grey out

47

//

all but the last one added (which is at the end of the array).

var i = 0; for (i = 0; i < e.collection.getLength() - 1; i++) { pin = e.collection.get(i); pin.setOptions({ icon: "GreyPin.png" }); } } }

</script> </head> <body onload="GetMap();"> <div id='myMap' style="position:relative; width:400px; height:400px;"></div><br> <b>Click the map to add a pushpin at that point.</b><br> </body> </html>

Returning a Localized Map


The Bing Maps AJAX Control 7.0 provides the ability to return a localized map.

Setting the Culture


By default the map labels and the navigation control text are provided in the culture EnglishUnited States (en-US). However, the map control culture can be changed by adding the mkt parameter to the map control reference, as in the following example, which sets the culture to French-France (fr-FR).
<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0&mkt=frfr"></script>

Supported Cultures
The following table lists supported cultures for the map control. The Culture column lists the valid values for the mkt parameter.

48

Language - Country/Region

Culture

Dutch - Belgium English - Canada English - India English - United Kingdom English - United States French - Canada French - France German - Germany Italian - Italy Japanese - Japan Spanish - Mexico Spanish - Spain Spanish United States

nl-BE en-CA en-IN en-GB en-US fr-CA fr-FR de-DE it-IT ja-JP es-MX es-ES es-US

Remarks
Error messages are always displayed in English - United States.

Building Your Own Module


The Bing Maps AJAX Control 7.0 allows you to easily register and load your own script modules. This topic describes how to create a simple module.

Develop Your Module


Begin by developing your module. The sample module below takes a map object as its constructor and exposes a method to draw a red arrow pointing to a given location.
// arrowmodule.js

function ArrowModule(map) { // Use the given location to draw an arrow pointing to that spot

49

this.drawRedArrow = function(location) { // Initialize the polygon locations var points = new Array(8); points[0] = location; points[1] = new Microsoft.Maps.Location(location.latitude+10, location.longitude); points[2] = new Microsoft.Maps.Location(location.latitude+5, location.longitude-5); points[3] = new Microsoft.Maps.Location(location.latitude+30, location.longitude-25); points[4] = new Microsoft.Maps.Location(location.latitude+25, location.longitude-30); points[5] = new Microsoft.Maps.Location(location.latitude+5, location.longitude-5); points[6] = new Microsoft.Maps.Location(location.latitude, location.longitude10); points[7] = location;

// Create the arrow var red = new Microsoft.Maps.Color(200, 200, 0, 0); var arrow = new Microsoft.Maps.Polygon(points, {strokeColor:red, fillColor:red});

map.entities.push(arrow);

} Microsoft.Maps.moduleLoaded('ArrowModule');

Note that the last line of the module calls the Microsoft.Maps.moduleLoaded method, which calls the main code callback function. After you have finished implementing your module, host your module script file on a web server.

50

Register and Load Your Module


After you have created your module and hosted it, register it within your map control application using the Microsoft.Maps.registerModule method.
Microsoft.Maps.registerModule("ArrowModule", "http://example.com/arrowmodule.js");

Next, load your module using the Microsoft.Maps.loadModule method, specifying the function to call when the module is loaded.
Microsoft.Maps.loadModule("ArrowModule", { callback: myModuleLoaded });

Use Your Module


Finally, use the functions provided by your module in your map control code. The sample code below uses the drawRedArrow method of the ArrowModule to draw an arrow pointing to the center of the map.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map;

function myModuleLoaded() { // When the module is fully loaded, then this function is called. // Now you can initialize a module object and use the module function to // draw an arrow pointing to the center of the map.

var arrowModule = new ArrowModule(map); arrowModule.drawRedArrow(map.getCenter()); }

51

function GetMap() { // Initialize the map var options = {credentials: "Bing Maps Key"}; map = new Microsoft.Maps.Map(document.getElementById('mapDiv'), options);

// Register and load the arrow module Microsoft.Maps.registerModule("ArrowModule", "http://example.com/arrowmodule.js"); Microsoft.Maps.loadModule("ArrowModule", { callback: myModuleLoaded });

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

See Also
Module Loading Methods

Microsoft.Maps API Reference


This section contains reference documentation for the Microsoft.Maps API, which contains the core types of the Bing Maps AJAX Control 7.0.

52

In This Section
Data Structures
AltitudeReference Enumeration Location Class LocationRect Class Point Class

Mapping
Events Object KeyEventArgs Object LabelOverlay Enumeration Map Class MapOptions Object MapTypeId Enumeration MouseEventArgs Object PixelReference Enumeration ViewOptions Object

Entities
Color Class EntityCollection Class EntityCollectionOptions Object Events Object Infobox Class InfoboxOptions Object MouseEventArgs Object Polyline Class PolylineOptions Object Polygon Class PolygonOptions Object Pushpin Class PushpinOptions Object TileLayer Class TileLayerOptions Object TileSource Class TileSourceOptions Object 53

User Location
Coordinates Class GeoLocationProvider Class Position Class PositionCircleOptions Object PositionError Class PositionOptions Object

Dynamic Module Loading


Module Loading Methods

AltitudeReference Enumeration
Defines the reference point from which the altitude is measured.

Constants
Name Description

ground ellipsoid

The altitude is measured from the ground level. The altitude is measured from the WGS 84 ellipsoid of the Earth.

Methods
Name Definition
isValid(reference:AltitudeReference)

Return Value

Description

isValid

boolean

Determines if the specified reference is a supported AltitudeReference.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html>

54

<head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript"> function GetMap() { // Create two locations with different altitude references. var groundLoc = new Microsoft.Maps.Location(47, -122, 100, Microsoft.Maps.AltitudeReference.ground); var ellipsoidLoc = new Microsoft.Maps.Location(47, -122, 100, Microsoft.Maps.AltitudeReference.ellipsoid);

// Set the map view var mapOptions = {credentials: "Bing Maps Key", center: groundLoc, mapTypeId: Microsoft.Maps.MapTypeId.birdseye, zoom:16};

var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), mapOptions);

// Add two pushpins to demonstrate the difference when using different altitude references map.entities.push(new Microsoft.Maps.Pushpin(groundLoc, {text: "G"})); map.entities.push(new Microsoft.Maps.Pushpin(ellipsoidLoc, {text: "E"}));

} </script> </head> <body onload="GetMap();">

55

<div id='mapDiv' style="position:relative; width:600px; height:600px;"></div> </body> </html>

AnimationVisibility Enumeration
Defines a tile layers visibility during animation.

Constants
Name Description

auto

The map control determines whether or not to show a tile layer based on system capability. If a browser can render a tile layer with acceptable performance, it is displayed during animations. The tile layer is not displayed during animation. The tile layer is displayed during animations. This option may impact performance on older browsers.

hide show

Color Class
Represents a color.

Constructor
Name Definition
Color(a:number, r:number, g:number, b:number)

Description

Color

Initializes a new instance of the Color class. The a parameter represents opacity. The range of valid values for all parameters is 0 to 255.

56

Properties
Name Type Description

a r g

number number number

The opacity of the color. The range of valid values is 0 to 255. The red value of the color. The range of valid values is 0 to 255. The green value of the color. The range of valid values is 0 to 255. The blue value of the color. The range of valid values is 0 to 255.

number

Static Methods
Name Definition
clone(color:Color)

Return Value

Description

clone fromHex

Color Color

Creates a copy of the Color object. Converts the specified hex string to a Color.

fromHex(hex:string)

Methods
Name Definition
clone()

Return Value

Description

clone getOpacity

Color number

Returns a copy of the Color object. Returns the opacity of the Color as a value between 0 (a=0) and 1 (a=255). Converts the Color into a 6-digit hex string. Opacity is ignored. For example, a Color with 57

getOpacity()

toHex

toHex()

string

Name

Definition

Return Value

Description

values (255,0,0,0) is returned as hex string #000000. toString


toString()

string

Converts the Color object to a string.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Your Bing Maps Key"});

// Create the locations var location1 = new Microsoft.Maps.Location(-20,-20); var location2 = new Microsoft.Maps.Location(20,-20); var location3 = new Microsoft.Maps.Location(20,20); var location4 = new Microsoft.Maps.Location(60, 20);

58

var location5 = new Microsoft.Maps.Location(60, 60);

// Create a shape var lineVertices = new Array(location1, location2, location3, location4, location5); var line = new Microsoft.Maps.Polyline(lineVertices,{strokeColor:new Microsoft.Maps.Color(100, 100, 0, 100)});

// Add the shape to the map map.entities.push(line);

function SetPolygonColor() { // Get the polyline entity. var mapLine = map.entities.get(0);

// Set the option values var opacity = document.getElementById('txtA').value; var rValue = document.getElementById('txtR').value; var gValue = document.getElementById('txtG').value; var bValue = document.getElementById('txtB').value; var lineWidth = document.getElementById('txtWidth').value;

// Verify input values and set the opacity, color, // and width of the line.

if (((opacity < 0) || (opacity > 255)) || ((rValue < 0) || (rValue > 255)) || ((gValue < 0) || (gValue > 255)) || ((bValue < 0) || (bValue > 255)) ) {

59

alert("Opacity and all color values must be between 0 and 255."); } else { mapLine.setOptions({strokeColor:new Microsoft.Maps.Color(opacity, rValue, gValue, bValue), strokeThickness:lineWidth}); }

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> Line Opacity: <input id="txtA" type="text" value="100"/><br/> Red Color Value: <input id="txtR" type="text" value="100"/><br/> Green Color Value: <input id="txtG" type="text" value="100"/><br/> Blue Color Value: <input id="txtB" type="text" value="100"/><br/> Line Width: <input id="txtWidth" type="text" value="5"/><br/> <input id="btnChangeColor" type="button" value="Set Polygon Color" onclick="SetPolygonColor();"/> </body> </html>

Coordinates Class
Represents the coordinates of the position of the user.

Properties
Name Type Description

accuracy

number

The accuracy, in meters, of the latitude and longitude 60

Name

Type

Description

values. altitude altitudeAccuracy heading latitude longitude speed number number number number number number The altitude of the location. The accuracy, in meters, of the altitude value. The direction of travel of the hosting device. The latitude of the location. The longitude of the location. The ground speed of the hosting device, in meters per second.

See Also
GeoLocationProvider Class

EntityCollection Class
Contains a collection of entities. An Entity can be any one of the following types: Polygon, Polyline, Pushpin, TileLayer, or EntityCollection.

Constructor
Name Definition
EntityCollection(options?:EntityCollectionOptions)

Description

EntityCollection

Initializes a new instance of the EntityCollection class.

Methods

61

Name

Definition

Return Value

Description

clear

clear()

None

Removes all entities from the collection. Returns the entity at the specified index in the collection. Returns the number of entities in the collection. Returns whether the entity collection is visible on the map. Gets the z-index of the entity collection with respect to other items on the map. Returns the index of the specified entity in the collection. If the entity is not found in the collection, -1 is returned. Inserts the specified entity into the collection at the given index. Removes the last entity from the collection and returns it. Adds the specified entity to the last position in the 62

get

get(index:number)

Entity*

getLength

getLength()

number

getVisible

getVisible()

boolean

getZIndex

getZIndex()

number

indexOf

indexOf(entity:Entity*)

number

insert

insert(entity:Entity*, index:number)

None

pop

pop()

Entity*

push

push(entity:Entity*)

None

Name

Definition

Return Value

Description

collection. remove
remove(entity:Entity*)

Entity*

Removes the specified entity from the collection and returns it. Removes the entity at the specified index from the collection and returns it. Sets the options for the entity collection. Converts the EntityCollection object to a string.

removeAt

removeAt(index:number)

Entity*

setOptions

setOptions(options:EntityCollectionOptions)

None

toString

toString()

string

* An Entity can be any one of the following types: Infobox, Polygon, Polyline, Pushpin, TileLayer, or EntityCollection.

Events
Name Arguments Description

entityadded

object: {collection: EntityCollection, entity:Entity*}

Occurs when one of the following happens: An entity is added to the collection. One of the entities of the collection (such as another entity collection) fires the entityadded event.

For example, if collection #1 contains an entity, which is another collection #2, then when an entity is added to collection #2, two entityadded events are fired. 63

Name

Arguments

Description

entitychanged

object: {collection: EntityCollection, entity:Entity*}

Occurs when one of the following happens: The collection changes. An entity of the collection changes. One of the entities of the collection (such as another entity collection) fires the entitychanged event.

For example, if collection #1 contains an entity, which is another collection #2, then when an entity of collection #2 changes, two entitychanged events are fired. entityremoved object: {collection: EntityCollection, entity:Entity*} Occurs when one of the following happens: An entity of the collection is removed. One of the entities of the collection (such as another entity collection) fires the entityremoved event.

For example, if collection #1 contains an entity, which is another collection #2, then when an entity of collection #2 is removed, two entityremoved events are fired. * An Entity can be any one of the following types: Infobox, Polygon, Polyline, Pushpin, TileLayer, or EntityCollection.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head>

64

<title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null; var pinTotal = 0;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials:"Bing Maps Key"});

// Add handler for the map click event - add a pin to the click location. Microsoft.Maps.Events.addHandler(map, 'click', addPin);

function addPin(e) {

if (e.targetType == "map") {

// Return the location where the map was clicked and create the pin. var point = new Microsoft.Maps.Point(e.getX(), e.getY()); var loc = e.target.tryPixelToLocation(point); var pin = new Microsoft.Maps.Pushpin(loc);

// Attach a handler to the pin so that it is removed when it is clicked Microsoft.Maps.Events.addHandler(pin, 'click', removePin);

65

// Add the pushpin map.entities.push(pin);

} }

function removePin(e) { var indexOfPinToRemove = map.entities.indexOf(e.target);

map.entities.removeAt(indexOfPinToRemove);

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> <b>Click the map to add a pin, or click a pin to remove it.<b/> </body> </html>

EntityCollectionOptions Object
Contains options for an entity collection.

Properties
66

Name

Type

Description

visible

boolean

A Boolean indicating whether the entity collection is visible on the map. The z-index of the entity collection with respect to other items on the map.

zIndex

number

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript"> var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"});

// Add handler for the map click event - add a pin to the click location. Microsoft.Maps.Events.addHandler(map, 'click', addPin);

67

function addPin(e) { if (e.targetType == "map") {

// Return the location where the map was clicked and create the pin. var point = new Microsoft.Maps.Point(e.getX(), e.getY()); var loc = e.target.tryPixelToLocation(point); var pin = new Microsoft.Maps.Pushpin(loc);

// Add the pushpin map.entities.push(pin);

} }

function hideAllPins(){ // Hide all the entities on the map map.entities.setOptions({visible:false}); }

function showAllPins(){ // Show all the entities on the map map.entities.setOptions({visible:true}); }

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> <input type="button" value="Hide all pins" onclick="hideAllPins();"/> <input type="button" value="Show all pins" onclick="showAllPins();"/> </body>

68

</html>

Events Object
Provides event handling functionality for map and entity events.

The Events object does not need to be initialized. Call the Events methods directly.

Methods
Name Definition Return Value Description

addHandler

addHandler(target:object, eventName:string, handler:function)

object

Attaches the handler for the event that is thrown by the target. Use the return object to remove the handler using the removeHandler method.
Microsoft.Maps.Events.addHandle r(map, 'viewchangedend, function(e){ event }); //Handle the

addThrottledHan dler

addThrottledHandler(target:o

object

bject, eventName:string, handler:function, throttleInterval:number)

Attaches the handler for the event that is thrown by the target, where the minimum interval between events (in milliseconds) is specified in the throttleInterval parameter. The last occurrence of the event is called after the specified throttleInterval.

hasHandler invoke

hasHandler(target:object, eventName:string) invoke(target:object, eventName:string, args:object)

boolea Checks if the target has any n attached event handler. None Invokes an event on the target. This causes all handlers for the specified eventName to be called. Detaches the specified handler from the event. The handlerId is returned by the addHandler and 69

removeHandler

removeHandler(handlerId:

None

object)

Name

Definition

Return Value

Description

addThrottledHandler methods.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null; var infobox = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});

// Retrieve the location of the map center var center = map.getCenter();

// Create a pin at the center of the map and its corresponding infobox var pin = new Microsoft.Maps.Pushpin(center); infobox = new Microsoft.Maps.Infobox(center, {title: 'Pushpin infobox', visible:false, offset:new Microsoft.Maps.Point(0,35)});

70

// Add event handlers for hovering over the pushpin Microsoft.Maps.Events.addHandler(pin, 'mouseover', showInfobox); Microsoft.Maps.Events.addHandler(pin, 'mouseout', hideInfobox);

// Add the pushpin and hidden infobox to the map map.entities.push(pin); map.entities.push(infobox);

function showInfobox() { infobox.setOptions({visible:true});

function hideInfobox() { infobox.setOptions({visible:false});

</script> </head> <body onload="GetMap();"> <div id='myMap' style="position:relative; width:500px; height:500px;"></div> </body> </html>

GeoLocationProvider Class
Contains methods for obtaining and displaying the users current location. 71

This functionality is only available on browsers that support the W3C GeoLocation API.

Constructor
Name Definition
GeoLocationProvider(map:Map)

Description

GeoLocationProvider

Initializes a new instance of the GeoLocationProvider class.

Methods
Name Definition Retur n Value Description

addAccuracyCircle

addAccuracyCircle(center:Location, radiusInMeters:number, segments:number, options:PositionCircleOptions)

None

Renders a geo location accuracy circle on the map. The accuracy circle is created with the center at the specified location, using the given radiusInMeters, and with the specified number of segments for the accuracy circle polygon. Additional options are also available to adjust the style of the polygon. Cancels the processing of the current getCurrentPositio 72

cancelRequest

cancelRequest()

None

Name

Definition

Retur n Value

Description

n request. This method prevents the response from being processed. getCurrentPosition
getCurrentPosition(options:PositionOptio

None

ns)

Obtains the users current location and displays it on the map.

The accuracy of the user location obtained using this method varies widely dependin g on the desktop browser or mobile device of the requestin g client. Desktop users may experienc e low user location accuracy (accuracy circles 73

Name

Definition

Retur n Value

Description

with large radiuses), while mobile user location accuracy may be much greater (a few meters). removeAccuracyCircl removeAccuracyCircle() e None Removes the current geo location accuracy circle.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

function GetMap() {

74

// Set the map options var mapOptions = {credentials:"Bing Maps Key"};

// Initialize the map var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), mapOptions);

// Initialize the location provider var geoLocationProvider = new Microsoft.Maps.GeoLocationProvider(map);

// Get the user's current location geoLocationProvider.getCurrentPosition();

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

See Also
PositionOptions Object

Infobox Class
Represents an info box on the map. You can use this class to create pop-up balloons for pushpins.

Constructor
Name Definition
Infobox(location:Location,

Description

Infobox

Initializes a new instance of 75

Name

Definition
options?:InfoboxOptions)

Description

the Infobox class.

Methods
Name Definition Return Value Description

getActions

getActions()

Object

Returns a list of actions, where each item is a name-value pair indicating an action link name and the event name for the action that corresponds to that action link. Returns the point on the infobox which is anchored to the map. An anchor of (0,0) is the top left corner of the infobox. Returns the string that is printed inside the infobox. Returns the height of the infobox. Returns the infobox as HTML. Returns the ID of the infobox. Returns the location on the map where the infoboxs anchor is attached. Returns the amount the infobox pointer is shifted from the location of the infobox, or if showPointer is false, then it is the amount the infobox bottom left edge is shifted from the location of the infobox. The default value is (0,0), which means there is no offset. Returns the infobox options. 76

getAnchor

getAnchor()

Point

getDescription getHeight getHtmlContent getId getLocation

getDescription()

string number string string Location

getHeight()

getHtmlContent() getId() getLocation()

getOffset

getOffset()

number

getOptions

getOptions()

InfoboxOpti

Name

Definition

Return Value

Description

ons getShowCloseB utton getShowPointer


getShowCloseButton()

boolean

Returns a boolean indicating whether the infobox close button is shown. Returns a boolean indicating whether the infobox is drawn with a pointer. Returns a string that is the title of the infobox. Returns the name of the function to call when the title of the infobox is clicked. Returns whether the infobox is visible. A value of false indicates that the infobox is hidden, although it is still an entity on the map. Returns the width of the infobox. Returns the z-index of the infobox with respect to other items on the map. Sets the HTML content of the infobox. You can use this method to change the look of the infobox. When custom HTML is used to represent the info box, the info box is anchored at the top-left corner.
var infoboxOptions = {width :200, height :100, showCloseButton: true, zIndex: 0, offset:new Microsoft.Maps.Point(10,0), showPointer: true}; var defInfobox = new Microsoft.Maps.Infobox(map.get Center(), infoboxOptions );

getShowPointer()

boolean

getTitle

getTitle()

string string

getTitleClickHan getTitleClickHandler() dler getVisible

getVisible()

boolean

getWidth getZIndex

getWidth() getZIndex()

number number

setHtmlContent

setHtmlContent(content:stri

None

ng)

77

Name

Definition

Return Value

Description

map.entities.push(defInfobox); defInfobox.setHtmlContent('<di v id="infoboxText" style="background-color:White; border-style:solid;borderwidth:medium; bordercolor:DarkOrange; minheight:100px; position:absolute;top:0px; left:23px; width:240px;"><b id="infoboxTitle" style="position:absolute; top:10px; left:10px; width:220px;">myTitle</b><a id="infoboxDescription" style="position:absolute; top:30px; left:10px; width:220px;">lkjsl lkjdkl lkajdlkj klasdjfkl</a></div>');

setLocation

setLocation(location:Locati

None

on) setOptions toString


setOptions(options:Infobox

Sets the location on the map where the anchor of the infobox is attached. Sets options for the infobox. Converts the Infobox object to a string.

None string

Options)
toString()

Events
Name Arguments Description

click entitychanged

eventArgs:MouseEventArgs object: {entity:Entity}

Occurs when the mouse is used to click the infobox. Occurs when the location of the infobox or any of the infobox options change. 78

Name

Arguments

Description

mouseenter

eventArgs:MouseEventArgs

Occurs when the mouse cursor enters the area covered by the infobox. Occurs when the mouse cursor leaves the area covered by the infobox.

mouseleave

eventArgs:MouseEventArgs

Remarks
The Bing Maps AJAX Control default info box is designed for desktop browsers and may not function properly on all mobile browsers. For the best performance, it is recommended that you have only one info box on the map at a time.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null; var pinInfobox = null;

function GetMap() { // Initialize the map

79

map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});

// Retrieve the location of the map center var center = map.getCenter();

// Add a pin to the center of the map var pin = new Microsoft.Maps.Pushpin(center, {text: '1'});

// Create the info box for the pushpin pinInfobox = new Microsoft.Maps.Infobox(new Microsoft.Maps.Location(0,0), {title: 'My Pushpin', visible: true});

// Add a handler for the pushpin click event. Microsoft.Maps.Events.addHandler(pin, 'click', displayInfobox);

// Hide the info box when the map is moved. Microsoft.Maps.Events.addHandler(map, 'viewchange', hideInfobox);

// Add the pushpin and info box to the map map.entities.push(pin); map.entities.push(pinInfobox);

function displayInfobox(e) { pinInfobox.setOptions({ visible:true }); }

80

function hideInfobox(e) { pinInfobox.setOptions({ visible: false }); }

</script> </head> <body onload="GetMap();"> <div id='myMap' style="position:relative; width:500px; height:500px;"></div> </html>

InfoboxOptions Object
Represents the options for an infobox.

Properties
Name Type Description

actions

Object

A list of the info box actions, where each item is a label (the action link text) and eventHandler (name of the function handling a click of the action link).
var infoboxOptions = {title:'My Infobox', description:'Testing actions', actions:[{label: 'test1', eventHandler: testEvent1}, {label: 'test2', eventHandler: testEvent2},{label: 'test3', eventHandler: testEvent3}] };

description height

string number

The string displayed inside the info box. The height of the info box. The default value is 126. 81

Name

Type

Description

htmlContent

string

The HTML that represents the info box. If custom HTML is used to represent the info box, the info box is anchored at the top-left corner.
var infoboxOptions = {width :200, height :100, showCloseButton: true, zIndex: 0, offset:new Microsoft.Maps.Point(10,0), showPointer: true, htmlContent:'<b>Custom HTML</b>'};

id location offset

string Location Point

The ID associated with the info box. The location on the map where the info boxs anchor is attached. The amount the info box pointer is shifted from the location of the info box, or if showPointer is false, then it is the amount the info box bottom left edge is shifted from the location of the info box. If custom HTML is set, it is the amount the top-left corner of the info box is shifted from its location. The default offset value is (0,0), which means there is no offset. A boolean indicating whether to show the close dialog button on the info box. The default value is true. By default the close button is displayed as an X in the top right corner of the info box. This property is ignored if custom HTML is used to represent the info box.

showCloseButton

boolean

showPointer

boolean

A boolean indicating whether to display the info box with a pointer. The default value is true. In this case the info box is anchored at the bottom point of the pointer. If this property is set to false, the info box 82

Name

Type

Description

is anchored at the bottom left corner. This property is ignored if custom HTML is used to represent the info box. title titleClickHandler string string The title of the info box. The name of the function to call when the title of the info box is clicked. If this property is set, the title of the info box is displayed as a link. A boolean indicating whether to show or hide the info box. The default value is true. A value of false indicates that the info box is hidden, although it is still an entity on the map. The width of the info box. The default value is 256. The z-index of the info box with respect to other items on the map.

visible

boolean

width zIndex

number number

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

83

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});

// Retrieve the location of the map center var center = map.getCenter();

// Create an info box var infoboxOptions = {width:300, height: 100, title: "Information Box Title", description: "This is the map.", showPointer: false, titleClickHandler: InfoboxHandler, offset: new Microsoft.Maps.Point(-100,0)}; var myInfobox = new Microsoft.Maps.Infobox(center, infoboxOptions);

// Add the info box to the map map.entities.push(myInfobox);

function InfoboxHandler() { alert("Infobox title was clicked!"); }

84

</script> </head> <body onload="GetMap();"> <div id='myMap' style="position:relative; width:500px; height:500px;"></div> </html>

See Also
Infobox Class

KeyEventArgs Object
Contains the arguments for keyboard events.

Properties
Name Type Description

altKey ctrlKey eventName handled

boolean boolean string boolean

A boolean indicating if the ALT key was pressed. A boolean indicating if the CTRL key was pressed. The event that occurred. A boolean indicating whether the event is handled. If this property is set to true, the default map control behavior for the event is cancelled. The ASCII character code that identifies the keyboard key that was pressed. The original browser event. A boolean indicating if the SHIFT key was pressed.

keyCode

string

originalEvent shiftKey

object boolean

85

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});

//Add handler for the map click event. Microsoft.Maps.Events.addHandler(map, 'keypress', addPin);

function addPin(e) {

if (e.keyCode == "112") {

// If the 'p' key is pressed, add a pushpin to the center of the // current map view.

var center = map.getCenter();

86

var pin = new Microsoft.Maps.Pushpin(center); map.entities.push(pin);

} }

</script> </head> <body onload="GetMap();"> <div id='myMap' style="position:relative; width:400px; height:400px;"></div><br> <b>Click the 'p' key to add a pushpin to the map.</b> </body> </html>

LabelOverlay Enumeration
Defines how map labels are displayed.

Constants
Name Description

hidden visible

Map labels are not shown on top of imagery. Map labels are shown on top of imagery.

Methods
Name Definition
isValid(labelOverlay:LabelOverlay)

Return Value

Description

isValid

boolean

Determines whether the specified labelOverlay is a supported LabelOverlay.

87

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

function GetMap() { // Initialize the map options. // In this case,

turn the label overlay on a bird's eye map off.

var mapOptions = { credentials:"Your Bing Maps Key", mapTypeId: Microsoft.Maps.MapTypeId.birdseye, center: new Microsoft.Maps.Location(37.794973,-122.393542), zoom: 17, labelOverlay: Microsoft.Maps.LabelOverlay.hidden }

//Load the map var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), mapOptions );

</script> </head>

88

<body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

Location Class (AJAX)


Contains the altitude and coordinate values of a location on the map.

Constructor
Name Definition
Location(latitude:number, longitude:number, altitude?:number, altitudeReference?:AltitudeReference)

Description

Location

Initializes a new instance of the Location class. The altitude and


altitudeReference

parameters default to undefined.

Properties
Name Type Description

altitude altitudeReference latitude longitude

number AltitudeReference number number

The altitude of the location. The reference from which the altitude is measured. The latitude of the location. The longitude of the location.

Static Methods

89

Name

Definition

Return Value

Description

areEqual

areEqual(location1:Location, location2:Location)

boolean

Determines if the specified Location objects are equal. Normalizes the specified longitude so that it is between -180 and 180.

normalizeLongitude

normalizeLongitude(longitude:number)

number

Methods
Name Definition
clone()

Return Value

Description

clone toString

Location string

Returns a copy of the Location object. Converts the Location object to a string.

toString()

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

90

var map = null;

function GetMap() {

map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials: "Bing Maps Key"});

function SetLocation() { // Parse the input string var latLongArray = (document.getElementById("txtlatlong").value).split(",");

// Retrieve the latitude and longitude values- normalize the longitude value var latVal = parseInt(latLongArray[0]); var longVal = Microsoft.Maps.Location.normalizeLongitude(parseInt(latLongArray[1]));

// Set the map center map.setView({center:new Microsoft.Maps.Location(latVal, longVal)});

} </script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:600px; height:600px;"></div> Latitude, Longitude: <input id="txtlatlong" type="text" value="40, -120"/> <input type="button" value="Set center location" onclick="SetLocation();"/> </body> </html>

91

LocationRect Class
Represents a rectangle on the map.

Constructor
Name Definition
LocationRect(center:Location, width:number, height:number)

Description

LocationRect

Initializes a new instance of the LocationRect class.

Properties
Name Type Description

center height width

Location number number

The location that defines the center of the rectangle. The height, in degrees, of the rectangle. The width, in degrees, of the rectangle.

Static Methods
Name Definition Return Value Description

fromCorn ers fromEdge s

fromCorners(northwest:Loc

ation, southeast:Location)
fromEdges(north:number, west:number, south:number, east:number, altitude:number, altitudeReference:Altitude

Location Rect Location Rect

Returns a LocationRect using the specified locations for the northwest and southeast corners. Returns a LocationRect using the specified northern and southern latitudes and western and eastern longitudes for the rectangle boundaries.

Reference)

92

Name

Definition

Return Value

Description

fromLocat ions

fromLocations(list of locations/array)

Location Rect

Returns a LocationRect using a list of locations or an array of locations. To provide a list of locations:
Microsoft.Maps.LocationRect.fromLocati ons(location1, location2, location3);

To provide an array of locations:


var locations = [location1, location2, location3]; Microsoft.Maps.LocationRect.fromLocati ons(locations);

fromStrin g

fromString(string:string)

Location Rect

Creates a LocationRect from a string with the following format: "north,west,south,east". North, west, south and east specify the coordinate number values.

Methods
Name Definition
clone()

Return Value

Description

clone

LocationRect

Returns a copy of the LocationRect object. Returns whether the specified Location is within the LocationRect. Returns the longitude that defines the eastern edge of the LocationRect. Returns the latitude that defines the northern edge of 93

contains

contains(location:Location)

boolean

getEast

getEast()

number

getNorth

getNorth()

number

Name

Definition

Return Value

Description

the LocationRect. getNorthwest


getNorthwest()

Location

Returns the Location that defines the northwest corner of the LocationRect. Returns the latitude that defines the southern edge of the LocationRect. Returns the Location that defines the southeast corner of the LocationRect. Returns the latitude that defines the western edge of the LocationRect. Returns whether the specified LocationRect intersects with this LocationRect. Converts the LocationRect object to a string.

getSouth

getSouth()

number

getSoutheast

getSoutheast()

Location

getWest

getWest()

number

intersects

intersects(rect:LocationRect)

boolean

toString

toString()

string

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html>

94

<head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() {

map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials: "Bing Maps Key"});

var viewRect = Microsoft.Maps.LocationRect.fromCorners(new Microsoft.Maps.Location(40,-120), new Microsoft.Maps.Location(35,-115));

map.setView({bounds: viewRect});

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:500px; height:500px;"></div> </body> </html>

Map Class
Represents a map. 95

Constructor
Name Definition
Map(containerElement:node, options?:MapOptions

Description

Map

or

Initializes a new instance of the Map class.

ViewOptions)

Properties
Name Type Description

entities

EntityCollection

The maps entities. Use this property to add or remove entities from the map.

Static Methods
Name Definition
getVersion()

Return Value

Description

getVersion

string

Returns the version of the map control.

Methods
Name Definition
blur()

Return Value

Description

blur

None

Removes focus from the map control so that it does not respond to keyboard events. Deletes the Map object and releases any associated resources. Applies focus to the map control so that it responds to keyboard events. Returns the location rectangle 96

dispose

dispose()

None

focus

focus()

None

getBounds

getBounds()

LocationRect

Name

Definition

Return Value

Description

that defines the boundaries of the current map view. getCenter


getCenter()

Location

Returns the location of the center of the current map view. Returns to the specified callback an array of strings representing the attributions of the imagery currently displayed on the map. Gets the session ID. This method calls the callback function with the session ID as the first parameter.
map.getCredentials(function( credentials) { if(credentials !== null) { service }); /* Valid session */ } Id. Use it to call REST

getCopyrights

getCopyrights(callback:fu

string[]

nction)

getCredentials

getCredentials(callback:f

None

unction)

getHeading getHeight getImageryId

getHeading()

number number string

Returns the heading of the current map view. Returns the height of the map control. Returns the string that represents the imagery currently displayed on the map. Returns a string that represents the current map type displayed on the map. Valid map types are listed in the MapTypeId Enumeration topic. Returns the current scale in meters per pixel of the center 97

getHeight()

getImageryId()

getMapTypeId

getMapTypeId()

string

getMetersPerPix

getMetersPerPixel()

number

Name

Definition

Return Value

Description

el getModeLayer getOptions
getModeLayer() getOptions()

of the map. Node MapOptions Returns the maps mode node. Returns the map options that have been set. Note that if an option is not set, then the default value for that option is assumed and getOptions returns undefined for that option. Returns the x coordinate of the top left corner of the map control, relative to the page. Returns the y coordinate of the top left corner of the map control, relative to the page. Returns the maps root node. Returns the location rectangle that defines the boundaries of the view to which the map is navigating. Returns the center location of the view to which the map is navigating. Returns the heading of the view to which the map is navigating. Returns the scale in meters per pixel of the center of the view to which the map is navigating. Returns the zoom level of the view to which the map is navigating. Returns the maps user node. Returns the x coordinate of the viewport origin (the center of 98

getPageX

getPageX()

number

getPageY

getPageY()

number

getRootElement

getRootElement()

Node LocationRect

getTargetBounds getTargetBounds()

getTargetCenter

getTargetCenter()

Location

getTargetHeadin g getTargetMeters PerPixel

getTargetHeading()

number

getTargetMetersPerPixel()

number

getTargetZoom

getTargetZoom()

number

getUserLayer getViewportX

getUserLayer() getViewportX()

Node number

Name

Definition

Return Value

Description

the map), relative to the page. getViewportY


getViewportY()

number

Returns the y coordinate of the viewport origin (the center of the map), relative to the page. Returns the width of the map control. Returns the zoom level of the current map view.

getWidth getZoom getZoomRange

getWidth()

number number

getZoom()

getZoomRange()

object:{min:nu Returns the range of valid mber, max: zoom levels for the current number} map view. boolean Returns whether the map is in a regular Mercator nadir mode. Returns true if the current map type allows the heading to change; false if the display heading is fixed. Sets the current map type. The specified mapTypeId must be a valid map type ID or a registered map type ID. Valid map type IDs are listed in the MapTypeId Enumeration topic. Sets the height and width of the map. Sets the map view based on the specified options. Converts a specified Location to a Point on the map relative to the specified PixelReference. If reference is not specified, PixelReference.viewport is used. If the map is not able to convert the Location, null is returned. 99

isMercator

isMercator()

isRotationEnable d

isRotationEnabled()

boolean

setMapType

setMapType(mapTypeId:strin

None

g)

setOptions setView tryLocationToPix el

setOptions({height:numbe

None None null, Point, or Point[]

r, width: number})
setView(options:ViewOptio

ns)
tryLocationToPixel(locati on:Location |Location[], reference?:PixelReference )

Name

Definition

Return Value

Description

Alternatively, converts an array of Locations and returns an array of Points if all locations were converted. If any of the conversions fail, null is returned. tryPixelToLocati on
tryPixelToLocation(point:

Point |Point[], reference?:PixelReference


)

null, Location, or Location[]

Converts a specified Point to a Location on the map relative to the specified PixelReference. If reference is not specified, PixelReference.viewport is used. If the map is not able to convert the Point, null is returned. Alternatively, converts an array of Points and returns an array of Locations if all points were converted. If any of the conversions fail, null is returned.

Events
Name Arguments Description

click copyrightchanged dblclick

eventArgs:MouseEventArgs None eventArgs:MouseEventArgs

Occurs when the mouse is used to click the map. Occurs when the copyright of the map changes. Occurs when the mouse is used to double click the map. Occurs when the underlying imagery used by the map changes. This is different from the maptypechanged event, which occurs when the map type being used is 100

imagerychanged

None

Name

Arguments

Description

changed. keydown keypress keyup eventArgs:KeyEventArgs eventArgs:KeyEventArgs eventArgs:KeyEventArgs Occurs when a keyboard key is pressed down. Occurs when a keyboard key is pressed. Occurs when a keyboard key that is pressed down is released. Occurs when the map type changes. Occurs when the left mouse button is pressed when the mouse cursor is over the map. Occurs when the mouse cursor moves over the map. Occurs when the mouse cursor moves out of the area covered by the map. Occurs when the mouse is over the map. Occurs when the left mouse button is lifted up when the mouse cursor is over the map. Occurs when the mouse wheel is used when the mouse cursor is over the map. Occurs when the right mouse button is used to click the map. Occurs when the view towards which the map is navigating changes.

maptypechanged mousedown

None eventArgs:MouseEventArgs

mousemove mouseout

eventArgs:MouseEventArgs eventArgs:MouseEventArgs

mouseover mouseup

eventArgs:MouseEventArgs eventArgs:MouseEventArgs

mousewheel

eventArgs:MouseEventArgs

rightclick

eventArgs:MouseEventArgs

targetviewchanged

None

101

Name

Arguments

Description

tiledownloadcomplete

None

Occurs when all the map tiles of a map view have loaded. Occurs for every frame of a map view change. Occurs when the map view is done changing. This event occurs when a view is the same for one frame of a map view change. For example, if the mouse is used to drag the map to change the view, but pauses during the drag (without releasing the mouse button), viewchangeend occurs twice. You can use the addThrottledHandler method to customize the number of events that occur.

viewchange viewchangeend

None None

viewchangestart

None

Occurs when the map view starts changing.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

102

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});

</script> </head> <body onload="GetMap();"> <div id='myMap' style="position:relative; width:400px; height:400px;"></div> </body> </html>

MapOptions Object
Represents options to customize the map that is displayed.

Properties
Name Type Description

backgroundColor

Color Class

The color to use for the map control background. The default color is #F4F2EE. This property can only be set when using the Map constructor.

credentials

string

The Bing Maps Key used to authenticate the application. This property can only be set 103

Name

Type

Description

when using the Map constructor. disableBirdseye boolean A boolean indicating whether to disable the birds eye map type. The default value is false. If this property is set to true, birds eye will be removed from the map navigation control and the birdseye MapTypeId is disabled. Additionally, the auto map type will only display road or aerial. This property can only be set when using the Map constructor. disableKeyboardInput boolean A boolean value indicating whether to disable the maps response to keyboard input. The default value is false. A boolean value indicating whether to disable the maps response to mouse input. The default value is false. A boolean value indicating whether to disable the users ability to pan the map. The default value is false. A boolean value indicating whether to disable the maps response to touch input. The default value is false. A boolean value indicating whether to disable the maps response to any user input. The default value is false. A boolean value indicating whether to disable the users ability to zoom in or out. The 104

disableMouseInput

boolean

disablePanning

boolean

disableTouchInput

boolean

disableUserInput

boolean

disableZooming

boolean

Name

Type

Description

default value is false. enableClickableLogo boolean A boolean value indicating TM whether the Bing logo on the map is clickable. The default value is true. This property can only be set when using the Map constructor. enableSearchLogo boolean A boolean value indicating TM whether to enable the Bing hovering search logo on the map. The default value is true. This property can only be set when using the Map constructor. fixedMapPosition boolean A boolean indicating whether the div containing the map control is fixed on the page and the browser will not be resized. The default value is false. In this case the map control redraws if necessary based on any div or window resize. If this property is set to true, the map control does not check the size of the div containing it every time the map view changes, thus increasing the performance of the control. This property can only be set when using the Map constructor. height number The height of the map. The default value is null. If no height is specified, the height of the div is used. If height is specified, then width must be specified as well.

105

Name

Type

Description

inertiaIntensity

number

A number between 0 and 1 specifying the intensity of the inertia animation effect. The inertia effect increases as the intensity value gets larger. The default value is .85. Setting this property to 0 indicates no inertia effect. The useInertia property must be set to true for the inertiaIntensity value to have an effect.

showBreadcrumb

boolean

A boolean value indicating whether to display the breadcrumb control. The breadcrumb control shows the current center locations geography hierarchy. For example, if the location center is Seattle, the breadcrumb control displays World . United States . WA. The default value is false. This property can only be set when using the Map constructor.

showCopyright

boolean

A boolean value indicating whether or not to show the map copyright. The default value is true. This property can only be set when using the Map constructor.

Bing Maps Platform API Terms of Use requires copyright information to be displayed. Only set this option to false when copyright 106

Name

Type

Description

information is displayed through alternate means. showDashboard boolean A boolean value indicating whether to show the map navigation control. The default value is true. This property can only be set when using the Map constructor. showMapTypeSelector boolean A boolean value indicating whether to show the map type selector in the map navigation control. The default value is true. This property can only be set when using the Map constructor. showScalebar boolean A boolean value indicating whether to show the scale bar. The default value is true. This property can only be set when using the Map constructor. tileBuffer number A number between 0 and 4 specifying how many tiles to use as a buffer around the map view. The default value is 0. A boolean value indicating whether to use the inertia animation effect during map navigation. The default value is true. The width of the map. The default value is null. If no width is specified, the width of the div is used. If width is specified, then height must be specified 107

useInertia

boolean

width

number

Name

Type

Description

as well.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

function GetMap() {

// Set the map and view options, setting the map style to Road and // removing the user's ability to change the map style

var mapOptions = {credentials:"Bing Maps Key", height: 400, width: 400, mapTypeId: Microsoft.Maps.MapTypeId.road, showMapTypeSelector: false};

// Initialize the map var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), mapOptions);

108

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative;"></div> </body> </html>

MapTypeId Enumeration
Contains identifiers for the imagery displayed on the map.

Constants
Name Description

aerial auto birdseye collinsBart mercator ordnanceSurvey road

The aerial map style is being used. The map is set to choose the best imagery for the current view. The birds eye map type is being used. Collins Bart (mkt=en-gb) map type is being used. The Mercator style is being used. Ordnance Survey (mkt=en-gb) map type is being used. The road map style is being used.

Example
This code sample sets the map imagery to Collins Bart (collinsBart). Since this imagery is only supported for the en-gb culture, the mkt parameter of the control is set to this culture.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title>

109

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0&mkt=engb"></script>

<script type="text/javascript"> function GetMap() {

var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials:"Bing Maps Key", center: new Microsoft.Maps.Location(51.5, -.1), zoom: 10, mapTypeId:Microsoft.Maps.MapTypeId.collinsBart}); } </script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:600px; height:600px;"></div> </body> </html>

See Also
Changing the Map View Returning a Localized Map

Module Loading Methods


The following methods allow you to register and load your own modules for use by the map control. More information about building your own module is in the Building Your Own Module topic.

Methods

110

Name

Definition

Return Value

Description

loadModule

loadModule(moduleKey:string, options:function)

None

Loads the specified registered module, making its functionality available. An optional function can be specified that is called when the module is loaded. To register a module, use the registerModule method. The following Bing Maps modules are available: Microsoft.Maps.Venue Maps Microsoft.Maps.Directions Microsoft.Maps.Traffic

moduleLoaded

moduleLoaded(moduleKey:string)

None

Signals that the specified module has been loaded and if specified, calls the callback function in loadModule. Call this method at the end of your module script. Registers a module with the map control. The name of the module is specified in moduleKey, the module script is defined in scriptUrl, and the options provides the location of a *.css file to load with the module.

registerModule

registerModule(moduleKey:string, scriptUrl:string, options:{styleURLs})

None

To minimize possible conflicts with other custom modules, choose a unique module name (defined in moduleKey). For example, you can use your company name in the name of the 111

Name

Definition

Return Value

Description

module. Once you have registered a module, you can make its functionality available by loading it using loadModule.

Example
The code below shows how to register and load a module, named MyModule1. The code for MyModule1 is found in the next code section.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map;

function myModuleLoaded() { alert("myModule has loaded.");

// Use the function provided by the newly loaded module var myModule = new MyModule(map); myModule.HelloWorld();

112

function GetMap() { // Initialize the map var options = {credentials: "Bing Maps Key"}; map = new Microsoft.Maps.Map(document.getElementById('mapDiv'), options);

// Register and load a new module Microsoft.Maps.registerModule("MyModule1", "http://example.com/mymodule.js"); Microsoft.Maps.loadModule("MyModule1", { callback: myModuleLoaded });

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

// mymodule.js function MyModule(map) { this.HelloWorld = function() { alert("Hello World - map Center is " + map.getCenter().toString()); } } Microsoft.Maps.moduleLoaded('MyModule1');

113

See Also
Building Your Own Module

MouseEventArgs Object
Contains the arguments for mouse events.

Properties
Name Type Description

eventName handled

string boolean

The event that occurred. A boolean indicating whether the event is handled. If this property is set to true, the default map control behavior for the event is cancelled. A boolean indicating if the primary button (such as the left mouse button or a tap on a touch screen) was used. A boolean indicating if the secondary mouse button (such as the right mouse button) was used. A boolean indicating whether the event that occurred was a touch event. The original browser event. The x-value of the pixel coordinate on the page of the mouse cursor. The y-value of the pixel coordinate on the page of the mouse cursor. The object that fired the event.

isPrimary

boolean

isSecondary

boolean

isTouchEvent

boolean

originalEvent pageX

object number

pageY

number

target

object

114

Name

Type

Description

targetType

string

The type of the object that fired the event. Valid values include the following: map, polygon, polyline, or pushpin The number of units that the mouse wheel has changed.

wheelDelta

number

Methods
Name Definition
getX()

Return Value

Description

getX

number

Returns the x-value of the pixel coordinate, relative to the map, of the mouse. Returns the y-value of the pixel coordinate, relative to the map, of the mouse.

getY

getY()

number

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

115

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});

//Add handler for the map click event. Microsoft.Maps.Events.addHandler(map, 'click', displayEventInfo);

function displayEventInfo(e) { if (e.targetType == "map") { var point = new Microsoft.Maps.Point(e.getX(), e.getY()); var loc = e.target.tryPixelToLocation(point); document.getElementById("textBox").value = loc.latitude + ", " + loc.longitude;

} }

</script> </head> <body onload="GetMap();"> <div id='myMap' style="position:relative; width:400px; height:400px;"></div><br> <b>Click the map to display the coordinate values at that point.</b><br> Latitude, Longitude: <input id='textBox' type="text" style="width:250px;"/> </body> </html>

116

PixelReference Enumeration
Contains constants used to show how pixels are defined.

Constants
Name Description

control

The pixel is defined relative to the map controls root element, where the top left corner of the map control is (0, 0). Using this option might cause a page reflow which may negatively impact performance. The pixel is defined relative to the page, where the top left corner of the HTML page is (0, 0). This option is best used when working with mouse or touch events. Using this option might cause a page reflow which may negatively impact performance. The pixel is defined in viewport coordinates, relative to the center of the map, where the center of the map is (0, 0). This option is best used for positioning geo-aligned entities added to the user layer.

page

viewport

Methods
Name Definition
isValid(reference:PixelReference)

Return Value

Description

isValid

boolean

Determines whether the specified reference is a supported PixelReference.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

117

<html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});

// Add handler for the map click event. Microsoft.Maps.Events.addHandler(map, 'click', displayEventInfo);

function displayEventInfo(e) { if (e.targetType == "map") {

var point = new Microsoft.Maps.Point(e.pageX, e.pageY, Microsoft.Maps.PixelReference.page); var loc = e.target.tryPixelToLocation(point, Microsoft.Maps.PixelReference.page);

if (loc!=null) {

118

alert("The location " + loc.latitude + ", " + loc.longitude + " was clicked."); }

} }

</script> </head> <body onload="GetMap();"> <div id='myMap' style="position:relative; width:400px; height:400px;"></div><br> <b>Click the map to display the coordinate values at that point.</b><br> </body> </html>

Point Class
Represents a point on the map.

Constructor
Name Definition
Point(x:number, y:number)

Description

Point

Initializes a new instance of the Point class.

Properties
Name Type Description

x y

number number

The x value of the coordinate. The y-value of the coordinate.

119

Static Methods
Name Definition
areEqual(point1:Point, point2:Point)

Return Value

Description

areEqual

boolean

Determines if the specified points are equal. Returns a copy of the Point object.

clone

clone(Point)

Point

Methods
Name Definition
clone()

Return Value

Description

clone toString

Point string

Returns a copy of the Point object. Converts the Point object into a string.

toString()

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap()

120

{ // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key "});

// Add handler for the map click event. Microsoft.Maps.Events.addHandler(map, 'click', displayEventInfo);

function displayEventInfo(e) { if (e.targetType == "map") {

var point = new Microsoft.Maps.Point(e.getX(), e.getY()); var loc = e.target.tryPixelToLocation(point);

if (loc!=null) { alert("The location " + loc.latitude + ", " + loc.longitude + " was clicked."); }

} }

</script> </head> <body onload="GetMap();"> <div id='myMap' style="position:relative; width:400px; height:400px;"></div><br> <b>Click the map to display the coordinate values at that point.</b><br> </body> </html>

121

Polygon Class (AJAX)


Represents a polygon on the map.

Constructor
Name Definition
Polygon(locations:Location[], options?:PolygonOptions)

Description

Polygon

Initializes a new instance of the Polygon class.

Methods
Name Definition
getFillColor()

Return Value

Description

getFillColor

Color

Returns the color of the inside of the polygon. Returns the locations that define the corners of the polygon. Returns the color of the outline of the polygon. Returns the string that represents the stroke/gap sequence used to draw the outline of the polygon. Returns the thickness of the outline of 122

getLocations

getLocations()

Location[]

getStrokeColor

getStrokeColor()

Color

getStrokeDashArray

getStrokeDashArray()

string

getStrokeThickness

getStrokeThickness()

number

Name

Definition

Return Value

Description

the polygon. getVisible


getVisible()

boolean

Returns whether the polygon is visible. A value of false indicates that the polygon is hidden, although it is still an entity on the map. Sets the locations that define the corners of the polygon. Sets options for the polygon. Converts the Polygon object to a string.

setLocations

setLocations(locations:Location[])

None

setOptions

setOptions(options:PolygonOptions)

None

toString

toString()

string

Events
Name Arguments Description

click dblclick

eventArgs:MouseEventArgs eventArgs:MouseEventArgs

Occurs when the mouse is used to click the polygon. Occurs when the mouse is used to double click the polygon. Occurs when the location of the polygon or any of the polygons options change. 123

entitychanged

object: {entity:Entity}

Name

Arguments

Description

mousedown

eventArgs:MouseEventArgs

Occurs when the left mouse button is pressed when the mouse is over the polygon. Occurs when the mouse cursor moves out of the area covered by the polygon. Occurs when the mouse is over the polygon. Occurs when the left mouse button is lifted up when the mouse is over the polygon. Occurs when the right mouse button is used to click the polygon.

mouseout

eventArgs:MouseEventArgs

mouseover mouseup

eventArgs:MouseEventArgs eventArgs:MouseEventArgs

rightclick

eventArgs:MouseEventArgs

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

function GetMap() { // Initialize the map

124

var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials:"Bing Maps Key"});

// Create the locations var location1 = new Microsoft.Maps.Location(20,-20); var location2 = new Microsoft.Maps.Location(20,20); var location3 = new Microsoft.Maps.Location(-20,20); var location4 = new Microsoft.Maps.Location(-20,-20);

// Create a polygon var vertices = new Array(location1, location2, location3, location4, location1); var polygoncolor = new Microsoft.Maps.Color(100,100,0,100); var polygon = new Microsoft.Maps.Polygon(vertices,{fillColor: polygoncolor, strokeColor: polygoncolor});

// Add the shape to the map map.entities.push(polygon)

// Set the view map.setView({bounds: Microsoft.Maps.LocationRect.fromLocations(vertices)});

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

125

PolygonOptions Object
Represents the options for a polygon.

Properties
Name Type Description

fillColor strokeColor strokeDashArray

Color Color string

The color of the inside of the polygon. The color of the outline of the polygon. A string representing the stroke/gap sequence to use to draw the outline of the polygon. The string must be in the format S, G, S*, G*, where S represents the stroke length and G represents gap length. Stroke lengths and gap lengths can be separated by commas or spaces. For example, a stroke dash string of 1 4 2 1 would draw the polygon outline with a dash, four spaces, two dashes, one space, and then repeated. The thickness of the outline of the polygon. A boolean indicating whether to show or hide the polygon. A value of false indicates that the polygon is hidden, although it is still an entity on the map.

strokeThickness visible

number boolean

126

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

function GetMap() { // Initialize the map var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials:"Bing Maps Key"});

// Create the locations var location1 = new Microsoft.Maps.Location(20,-20); var location2 = new Microsoft.Maps.Location(20,20); var location3 = new Microsoft.Maps.Location(-20,20); var location4 = new Microsoft.Maps.Location(-20,-20);

// Create a polygon var vertices = new Array(location1, location2, location3, location4, location1); var polygon = new Microsoft.Maps.Polygon(vertices, {fillColor: new Microsoft.Maps.Color(100,100,0,100), strokeColor: new Microsoft.Maps.Color(200,0,100,100), strokeThickness: 5});

127

// Add the shape to the map map.entities.push(polygon)

// Set the view map.setView({bounds: Microsoft.Maps.LocationRect.fromLocations(vertices)});

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

Polyline Class
Represents a polyline on the map.

Constructor
Name Definition
Polyline(locations:Location[], options?:PolylineOptions)

Description

Polyline

Initializes a new instance of the Polyline class.

Methods
Name Definition
getLocations()

Return Value

Description

getLocations

Location[]

Returns the locations that define the 128

Name

Definition

Return Value

Description

polyline. getStrokeColor
getStrokeColor()

Color

Returns the color of the polyline. Returns the string that represents the stroke/gap sequence used to draw the polyline. Returns the thickness of the polyline. Returns whether the polyline is visible. A value of false indicates that the polyline is hidden, although it is still an entity on the map. Sets the locations that define the polyline. Sets options for the polyline. Converts the Polyline object to a string.

getStrokeDashArray

getStrokeDashArray()

string

getStrokeThickness

getStrokeThickness()

number

getVisible

getVisible()

boolean

setLocations

setLocations(locations:Location[])

None

setOptions

setOptions(options:PolylineOptions)

None

toString

toString()

string

129

Events
Name Arguments Description

click dblclick

eventArgs:MouseEventArgs eventArgs:MouseEventArgs

Occurs when the mouse is used to click the polyline. Occurs when the mouse is used to double click the polyline. Occurs when the location of the polyline or any of the polylines options change. Occurs when the left mouse button is pressed when the mouse is over the polyline. Occurs when the mouse cursor moves out of the area covered by the polyline. Occurs when the mouse is over the polyline. Occurs when the left mouse button is lifted up when the mouse is over the polyline. Occurs when the right mouse button is used to click the polyline.

entitychanged

object: {entity:Entity}

mousedown

eventArgs:MouseEventArgs

mouseout

eventArgs:MouseEventArgs

mouseover mouseup

eventArgs:MouseEventArgs eventArgs:MouseEventArgs

rightclick

eventArgs:MouseEventArgs

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

130

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Your Bing Maps Key"});

// Create the locations var location1 = new Microsoft.Maps.Location(-20,-20); var location2 = new Microsoft.Maps.Location(20,-20); var location3 = new Microsoft.Maps.Location(20,20); var location4 = new Microsoft.Maps.Location(60, 20); var location5 = new Microsoft.Maps.Location(60, 60);

// Create a polyline var lineVertices = new Array(location1, location2, location3, location4, location5); var line = new Microsoft.Maps.Polyline(lineVertices);

// Add the polyline to the map map.entities.push(line);

131

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

PolylineOptions Object
Represents the options for a polyline.

Properties
Name Type Description

strokeColor strokeDashArray

Color string

The color of the polyline. A string representing the stroke/gap sequence to use to draw the polyline. The string must be in the format S, G, S*, G*, where S represents the stroke length and G represents gap length. Stroke lengths and gap lengths can be separated by commas or spaces. For example, a stroke dash string of 1 4 2 1 would draw the polyline with a dash, four spaces, two dashes, one space, and then repeated. The thickness of the polyline. A boolean indicating whether to show or hide the polyline. A value of false indicates that the polyline is hidden, although it is still an entity on the map.

strokeThickness visible

number boolean

132

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Your Bing Maps Key"});

// Create the locations var location1 = new Microsoft.Maps.Location(-20,-20); var location2 = new Microsoft.Maps.Location(20,-20); var location3 = new Microsoft.Maps.Location(20,20); var location4 = new Microsoft.Maps.Location(60, 20); var location5 = new Microsoft.Maps.Location(60, 60);

// Create a polyline var lineVertices = new Array(location1, location2, location3, location4, location5);

133

var line = new Microsoft.Maps.Polyline(lineVertices,{strokeColor:new Microsoft.Maps.Color(200, 100, 0, 100), strokeThickness:5, strokeDashArray:"5 2"});

// Add the polyline to the map map.entities.push(line);

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

Position Class
Represents the position of a user on a map.

Properties
Name Type Description

coords timestamp

Coordinates string

The position as a W3C Coordinates object. The time when the position was determined, in the form of a DOMTimeStamp.

See Also
GeoLocationProvider Class

134

PositionCircleOptions Object
Contains options for the addAccuracyCircle method of the GeoLocationProvider class.

Properties
Name Type Description

polygonOptions showOnMap

PolygonOptions boolean

The polygon options for the geo location accuracy circle. A boolean indicating whether to display the geo location accuracy circle. The default value is true. If this property is set to false, a geo location accuracy circle is not drawn and any existing accuracy circles are removed.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map; var geoLocationProvider;

function GetMap()

135

// Set the map options var mapOptions = {credentials:"Bing Maps Key"};

// Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), mapOptions);

// Initialize the location provider geoLocationProvider = new Microsoft.Maps.GeoLocationProvider(map);

// Get the user's current location geoLocationProvider.getCurrentPosition({successCallback:drawCircle, showAccuracyCircle:false});

function drawCircle(args) { // Draw the accuracy circle using a different color geoLocationProvider.addAccuracyCircle(args.center, 50000, 50000, {polygonOptions:{fillColor:new Microsoft.Maps.Color(100,100,0,100), strokeColor:new Microsoft.Maps.Color(100,100,0,100)}}); }

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body>

136

</html>

PositionError Class
Represents the error when a user position request does not succeed.

Properties
Name Type Description

code

number

The error code. Any one of the following error codes may be returned: 0 An error occurred that is not covered by other error codes. 1 The application does not have permission to use the GeoLocation API. 2 The position of the host device could not be determined. 3 The specified timeout was exceeded.

message string

The error message. This message is for the developer and is not intended to be displayed to the end user.

See Also
GeoLocationProvider Class

PositionOptions Object
Contains options for the getCurrentPosition method of the GeoLocationProvider class.

137

Properties
Name Type Description

enableHighAccuracy

boolean

A boolean indicating whether only a high accuracy result should be retrieved. The default value is false. Setting this property to true may result in a slower response time. The function to call when an error occurs during the user location request. The callback function must accept one argument. The argument object contains two properties, internalError, a PositionError type, and errorCode, a number. Any one of the following errorCode values may be returned: 1 The application origin does not have permission to use the GeoLocation API. 2 The position of the user could not be determined because of a device failure. 3 The time specified in timeout has been exceeded. 4 A request is already in process. 5 The users browser does not support geo location.

errorCallback

function

maximumAge

number

A number indicating the acceptable age, in milliseconds, of a cached geo 138

Name

Type

Description

location result to return. The default value is 0, which indicates a new (not cached) result will be retrieved. showAccuracyCircle boolean A boolean indicating whether to display the polygon on the map that shows the accuracy of the returned geo location. The default value is true. The function to call when the users location was successfully retrieved. The callback function must accept one argument. The argument object contains two properties, center, a Location type, and position, a Position type. The length of time, in milliseconds, to allow for the geo location request to return. By default there is no timeout. A boolean indicating whether to update the map view with the best view of the users location (if the request is successful). The default value is true.

successCallback

function

timeout

number

updateMapView

boolean

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

139

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map;

function GetMap() {

// Set the map options var mapOptions = {credentials:"Bing Maps Key"};

// Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), mapOptions);

// Initialize the location provider var geoLocationProvider = new Microsoft.Maps.GeoLocationProvider(map);

// Get the user's current location geoLocationProvider.getCurrentPosition({successCallback:displayCenter});

function displayCenter(args) { // Display the user location when the geo location request returns alert("The user's location is " + args.center); }

</script>

140

</head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

Pushpin Class (AJAX)


Defines a pushpin on the map.

Constructor
Name Definition
Pushpin(location:Location, options?:PushpinOptions)

Description

Pushpin

Initializes a new instance of the Pushpin class.

Methods
Name Definition
getAnchor()

Return Value

Description

getAnchor

Point

Returns the point on the pushpin icon which is anchored to the pushpin location. An anchor of (0,0) is the top left corner of the icon. Returns the pushpin icon. Returns the height of the pushpin, which is the height of the pushpin icon. 141

getIcon getHeight

getIcon()

string number

getHeight()

Name

Definition
getLocation()

Return Value

Description

getLocation

Location

Returns the location of the pushpin. Returns the text associated with the pushpin. Returns the amount the text is shifted from the pushpin icon. Returns the type of the pushpin. Returns whether the pushpin is visible. A value of false indicates that the pushpin is hidden, although it is still an entity on the map. Returns the width of the pushpin, which is the width of the pushpin icon. Returns the zindex of the pushpin with respect to other items on the map. Sets the location of the pushpin. Sets options for the pushpin. Converts the 142

getText

getText()

string

getTextOffset

getTextOffset()

Point

getTypeName getVisible

getTypeName()

string boolean

getVisible()

getWidth

getWidth()

number

getZIndex

getZIndex()

number

setLocation setOptions toString

setLocation(location:Location)

None None string

setOptions(options:PushpinOptions)

toString()

Name

Definition

Return Value

Description

Pushpin object to a string.

Events
Name Arguments Description

click dblclick

eventArgs:MouseEventArgs eventArgs:MouseEventArgs

Occurs when the mouse is used to click the pushpin. Occurs when the mouse is used to double click the pushpin. Occurs when the pushpin is being dragged. Occurs when the pushpin stops being dragged. Occurs when the pushpin starts being dragged. Occurs when the location of the pushpin or any of the pushpins options change. Occurs when the left mouse button is pressed when the mouse is over the pushpin. Occurs when the mouse cursor moves out of the area covered by the pushpin. Occurs when the mouse is over the pushpin. Occurs when the left mouse button is lifted up when the mouse is over the pushpin. 143

drag dragend dragstart entitychanged

eventArgs:MouseEventArgs eventArgs:MouseEventArgs eventArgs:MouseEventArgs object: {entity:Entity}

mousedown

eventArgs:MouseEventArgs

mouseout

eventArgs:MouseEventArgs

mouseover mouseup

eventArgs:MouseEventArgs eventArgs:MouseEventArgs

Name

Arguments

Description

rightclick

eventArgs:MouseEventArgs

Occurs when the right mouse button is used to click the pushpin.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});

// Retrieve the location of the map center var center = map.getCenter();

// Add a pin to the center of the map var pin = new Microsoft.Maps.Pushpin(center, {draggable: true});

// Add a handler to the pushpin drag

144

Microsoft.Maps.Events.addHandler(pin, 'mouseup', DisplayLoc);

map.entities.push(pin); }

function DisplayLoc(e){ if (e.targetType == 'pushpin'){

var pinLoc = e.target.getLocation(); alert("The location of the pushpin is now " + pinLoc.latitude + ", " + pinLoc.longitude);

} }

</script> </head> <body onload="GetMap();"> <div id='myMap' style="position:relative; width:400px; height:400px;"></div> <b>Drag the pushpin to a new location.</b> </body> </html>

PushpinOptions Object
Represents the options for a pushpin.

Properties
Name Type Description

anchor

Point

The point on the pushpin icon which is anchored to the pushpin location. An anchor of (0,0) is the top left corner of the icon. The default anchor is the 145

Name

Type

Description

bottom center of the icon. draggable boolean A boolean indicating whether the pushpin can be dragged to a new position with the mouse. The path of the image to use as the pushpin icon. The height of the pushpin, which is the height of the pushpin icon. The default value is 39. The text associated with the pushpin. The amount the text is shifted from the pushpin icon. The default value is (0,5). The type of the pushpin, as a string. The pushpin DOM (document object model) node created for the pushpin will have the specified typeName. A boolean indicating whether to show or hide the pushpin. The default value is true. A value of false indicates that the pushpin is hidden, although it is still an entity on the map. The width of the pushpin, which is the width of the pushpin icon. The default value is 25. The z-index of the pushpin with respect to other items on the map.

icon height

string number

text textOffset

string Point

typeName

string

visible

boolean

width

number

zIndex

number

Example
This example uses the image below, named BluePushpin.png, as the pushpin icon. 146

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});

// Retrieve the location of the map center var center = map.getCenter();

// Add a pin to the center of the map var pin = new Microsoft.Maps.Pushpin(center, {icon:"BluePushpin.png", height:50, width:50, anchor:new Microsoft.Maps.Point(0,50), draggable: true});

map.entities.push(pin);

147

</script> </head> <body onload="GetMap();"> <div id='myMap' style="position:relative; width:400px; height:400px;"></div>

</body> </html>

TileLayer Class
Represents a tile layer.

Constructor
Name Definition
TileLayer(options:TileLayerOptions)

Description

TileLayer

Initializes a new instance of the TileLayer class.

Methods
Name Definition Return Type Description

getOpacity

getOpacty()

number

Returns the opacity of the tile layer, defined as a double between 0 (not visible) and 1. Returns the tile source of the tile layer. The projection parameter accepts the following values: mercator, enhancedBirdseyeNorthUp, enhancedBirdseyeSouthUp 148

getTileSourc e

getTileSource(projection:string)

TileSourc e

Name

Definition

Return Type

Description

, enhancedBirdseyeEastUp, enhancedBirdseyeWestUp getZIndex


getZIndex()

number

Returns the z-index of the tile layer with respect to other items on the map. Sets options for the tile layer. Converts the TileLayer object to a string.

setOptions toString

setOptions(options:TileLayerOptions ) toString()

None string

Events
Name Arguments Description

tiledownloadcomplete

None

Occurs when all the tiles of the tile layer have loaded.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

function GetMap() {

149

// Initialize the map var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials:"Bing Maps Key", center:new Microsoft.Maps.Location(48.03,122.4), zoom:12, mapTypeId: Microsoft.Maps.MapTypeId.road });

try { // Create the tile layer source var tileSource = new Microsoft.Maps.TileSource({uriConstructor: 'http://www.microsoft.com/maps/isdk/ajax/layers/lidar/{quadkey}.png'});

// Construct the layer using the tile source var tilelayer= new Microsoft.Maps.TileLayer({ mercator: tileSource, opacity: .7 });

// Push the tile layer to the map map.entities.push(tilelayer);

} catch(err) { alert( 'Error Message:' + err.message); }

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

150

See Also
Working with Tile Layers

TileLayerOptions Object
Defines the options for a tile layer.

Properties
Name Type Description

animationDisplay

AnimationVisibility

The tile layers visibility during animation. You can use this property to prevent overlays from displaying during animations, which can impact performance. The default value is auto. The tile source for the tile layer. The opacity of the tile layer, defined by a number between 0 (not visible) and 1. A boolean indicating whether to show or hide the tile layer. The default value is true. A value of false indicates that the tile layer is hidden, although it is still an entity on the map. The z-index of the tile layer, with respect to other items on the map.

mercator opacity

TileSource number

visible

boolean

zIndex

number

151

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null; var tilelayer = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials:"Bing Maps Key", center:new Microsoft.Maps.Location(48.03,-122.4), zoom:12, mapTypeId: Microsoft.Maps.MapTypeId.road });

try { // Create the tile layer source var tileSource = new Microsoft.Maps.TileSource({uriConstructor: 'http://www.microsoft.com/maps/isdk/ajax/layers/lidar/{quadkey}.png'});

// Construct the layer using the tile source tilelayer= new Microsoft.Maps.TileLayer({ mercator: tileSource, opacity: .7 });

// Push the tile layer to the map

152

map.entities.push(tilelayer);

} catch(err) { alert( 'Error Message:' + err.message); }

function SetOpacity() {

var opacityVal = parseFloat(document.getElementById("txtOpacity").value);

if ((opacityVal > 1) || (opacityVal < 0)) { alert("The opacity value must be between 0 and 1."); } else { tilelayer.setOptions({opacity: opacityVal}); }

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> <input id="txtOpacity" type="text" value=".1" style="width:25px;"/> <input type="button" value="Set Opacity" onclick="SetOpacity();"/>

153

</body> </html>

See Also
Working with Tile Layers

TileSource Class
Defines a tile source for a tile layer.

Constructor
Name Definition
TileSource(options:TileSourceOptions)

Description

TileSource

Initializes a new instance of the TileSource class.

Methods
Name Definition
getHeight()

Return Type

Description

getHeight

Number

Returns the pixel height of each tile in the tile source. Returns a string that constructs tile URLs used to retrieve tiles for the tile layer. Returns the pixel width of each tile in the tile source. Converts the TileSource object to a string.

getUriConstructor

getUriConstructor()

string

getWidth

getWidth()

number

toString

toString()

string

154

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

function GetMap() { // Initialize the map var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key", center:new Microsoft.Maps.Location(48.03,-122.4), zoom:12, mapTypeId: Microsoft.Maps.MapTypeId.road });

try { // Create the tile layer source var tileSource = new Microsoft.Maps.TileSource({uriConstructor: 'http://www.microsoft.com/maps/isdk/ajax/layers/lidar/{quadkey}.png'});

// Construct the layer using the tile source var tilelayer= new Microsoft.Maps.TileLayer({ mercator: tileSource, opacity: .7 });

// Push the tile layer to the map map.entities.push(tilelayer);

155

catch(err) { alert( 'Error Message:' + err.message); }

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

See Also
Working with Tile Layers

TileSourceOptions Object
Defines options for a tile source.

Properties
Name Type Description

height

number

The pixel height of each tile in the tile source. The default value is 256. The specified height needs to be a multiplier of 2 of the current projections tile height for the tiles to be shown. For example, since Mercator tile source tiles are 256x256, this 156

Name

Type

Description

projection supports tiles that are 64x64, 128x128, 256x256, 512x512, or any combination of these. uriConstructor string The string that constructs the URLs used to retrieve tiles from the tile source. This property is required. The uriConstructor will replace {subdomain} and {quadkey}. width number The pixel width of each tile in the tile source. The default value is 256. The specified width needs to be a multiplier of 2 of the current projections tile width for the tiles to be shown. For example, since Mercator tile source tiles are 256x256, this projection supports tiles that are 64x64, 128x128, 256x256, 512x512, or any combination of these.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

157

function GetMap() { // Initialize the map var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key", center:new Microsoft.Maps.Location(48.03,-122.4), zoom:12, mapTypeId: Microsoft.Maps.MapTypeId.road });

try { // Create the tile layer source var tileSource = new Microsoft.Maps.TileSource({uriConstructor: 'http://www.microsoft.com/maps/isdk/ajax/layers/lidar/{quadkey}.png'});

// Construct the layer using the tile source var tilelayer= new Microsoft.Maps.TileLayer({ mercator: tileSource, opacity: .7 });

// Push the tile layer to the map map.entities.push(tilelayer);

} catch(err) { alert( 'Error Message:' + err.message); }

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

158

See Also
Working with Tile Layers

ViewOptions Object
Contains options for the map view.

Properties
Name Type Description

animate

boolean

A boolean that specifies whether to animate map navigation. Note that this option is associated with each setView call and defaults to true if not specified. The bounding rectangle of the map view. If both are specified, bounds takes precedence over center. The location of the center of the map view. If both are specified, bounds takes precedence over center. The amount the center is shifted. This property is ignored if center is not specified. The directional heading of the map. The heading is represented in geometric degrees with 0 or 360 = North, 90 = East, 180 = South, and 270 = West. A constant indicating how map labels are displayed. The map type of the view. 159

bounds

LocationRect

center

Location

centerOffset

Point

heading

number

labelOverlay mapTypeId

LabelOverlay string

Name

Type

Description

Valid map types are found in the MapTypeId Enumeration topic. padding number The amount of padding to be added to each side of the bounds of the map view. The zoom level of the map view.

zoom

number

Remarks
To 'lock' the map in a certain position, disable mouse and keyboard events during the application session. The following code disables mouse events.
// Attach an event handler for a mousemove event. Microsoft.Maps.Events.addHandler(map, "mousemove", cancelEvent);

// When the mouse is used, the cancelEvent function will // // get called. Setting the handled property to true will disable the mousemove event, which disables panning.

function cancelEvent(e) { e.handled = true; }

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

160

<script type="text/javascript">

var map = null;

function GetMap() { // Set the initial map and view settings

var initialViewBounds = Microsoft.Maps.LocationRect.fromCorners(new Microsoft.Maps.Location(43,-123), new Microsoft.Maps.Location(33,-113)); var options = {credentials:"Bing Maps Key", width: 500, height: 500, bounds: initialViewBounds, mapTypeId:Microsoft.Maps.MapTypeId.aerial, animate: false};

// Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),options);

function SetZoom() { // Retrieve the zoom level set by the user - converting it to a number. var zoomLevel = parseInt(document.getElementById("txtZoom").value);

// Get the existing options. var options = map.getOptions();

// Set the zoom level of the map options.zoom = zoomLevel; map.setView(options);

161

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative;"></div> <input id="txtZoom" type="text" value="1"/> <input type="button" value="Set Zoom" onclick="SetZoom();"/> </body> </html>

Microsoft.Maps.Directions API Reference


This section contains reference documentation for the Microsoft.Maps.Directions API, which contains types that allow you to calculate route directions and display them on your Bing Maps AJAX Control 7.0 map. Use the calculateDirections method of the DirectionsManager Class to calculate a route. Sample code can be found at http://www.bingmapsportal.com/isdk/ajaxv7.

Before you can access the types found in the Microsoft.Maps.Directions API, you must first load this module using the loadModule method. Information about loading modules is in the Module Loading Methods topic.

In This Section
BusinessDetails Class BusinessDisambiguationSuggestion Class DirectionsErrorEventArgs Object DirectionsEventArgs Object DirectionsManager Class DirectionsRenderOptions Object DirectionsRequestOptions Object DirectionsStep Class DirectionsStepEventArgs Object DirectionsStepRenderEventArgs Object DirectionsStepWarning Class DirectionsStepWarningType Enumeration Disambiguation Class DistanceUnit Enumeration LocationDisambiguationSuggestion Class 162

ManeuverType Enumeration ResetDirectionsOptions Object Route Class RouteAvoidance Enumeration RouteIconType Enumeration RouteLeg Class RouteMode Enumeration RouteOptimization Enumeration RoutePath Class RouteResponseCode Enumeration RouteSelectorEventArgs Object RouteSelectorRenderEventArgs Object RouteSubLeg Class RouteSummary Class RouteSummaryRenderEventArgs Object TimeType Enumeration TransitLine Class TransitOptions Object Waypoint Class WaypointEventArgs Object WaypointOptions Object WaypointRenderEventArgs Object

BusinessDetails Class
Contains business details for a waypoint.

Properties
Name Type Description

businessName entityId phoneNumber

string string string

The business name of the waypoint. The Bing Maps entity ID of the business. The phone number of the business. 163

Name

Type

Description

website

string

The URL of the business website.

BusinessDisambiguationSuggestion Class
Contains a possible business result returned from geocoding a specified waypoint address or location.

Properties
Name Type Description

address distance

string number

The address of the business result. The distance of the business result from the originally specified waypoint address or location. The Yellow Pages ID for the business. The index of this suggestion within the business suggestion array. A boolean indicating whether the result location is approximate. The location of the business suggestion. The name of the business. The phone number of the business suggestion. The URL of a photo of the business suggestion. The rooftop location of the 164

entityId index

string number

isApproximate

boolean

location name phoneNumber photoUrl rooftopLocation

Location string string string Location

Name

Type

Description

business suggestion. website string The URL of the business results website.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null; var directionsManager = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"}); Microsoft.Maps.loadModule('Microsoft.Maps.Directions', { callback: directionsModuleLoaded });

165

function directionsModuleLoaded() { // Initialize the DirectionsManager directionsManager = new Microsoft.Maps.Directions.DirectionsManager(map);

// Create start and end waypoints var startWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Seattle, WA"}); var endWaypoint = new Microsoft.Maps.Directions.Waypoint({ address: "Microsoft" } );

directionsManager.addWaypoint(startWaypoint); directionsManager.addWaypoint(endWaypoint);

// Set the id of the div to use to display the directions directionsManager.setRenderOptions({ itineraryContainer: document.getElementById('itineraryDiv') });

// Specify a handler for when an error occurs Microsoft.Maps.Events.addHandler(directionsManager, 'directionsError', displayError);

// Calculate directions, which displays a route on the map directionsManager.calculateDirections();

function displayError(e) { // Display the error message alert(e.message);

// If the error is a disambiguation error, display the results. if (e.responseCode == 12)

166

{ DisplayDisambiguation(); } }

function DisplayDisambiguation() { var results = "";

var waypoints = directionsManager.getAllWaypoints();

var i = 0; for (i=0; i<waypoints.length; i++) {

var disambigResult = waypoints[i].getDisambiguationResult();

if (disambigResult != null) { results = results + "Address matches for " + waypoints[i].getAddress() + ":\n";

var j = 0; for (j=0; j<disambigResult.businessSuggestions.length; j++) { results = results + disambigResult.businessSuggestions[j].name + ", " + disambigResult.businessSuggestions[j].address + "\n"; } } }

alert(results);

167

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> <div id='itineraryDiv' style="position:relative; width:400px;"></div> </body> </html>

See Also
Disambiguation Class

DirectionsErrorEventArgs Object
Contains arguments for directions error events.

Properties
Name Type Description

responseCode message

RouteResponseCode string

The code which identifies the error that occurred. The error message.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

168

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"}); Microsoft.Maps.loadModule('Microsoft.Maps.Directions', { callback: directionsModuleLoaded });

function directionsModuleLoaded() { // Initialize the DirectionsManager var directionsManager = new Microsoft.Maps.Directions.DirectionsManager(map);

// Create start and end waypoints and add them to the route var startWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Seattle, WA"}); var endWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Paris, France"});

directionsManager.addWaypoint(startWaypoint); directionsManager.addWaypoint(endWaypoint);

// Set directions render options - in this case, specify the div where the itinerary is displayed. directionsManager.setRenderOptions({ itineraryContainer: document.getElementById('itineraryDiv') });

169

// Specify a handler for when the directions are calculated and when an error occurs Microsoft.Maps.Events.addHandler(directionsManager, 'directionsUpdated', displayMessage ); Microsoft.Maps.Events.addHandler(directionsManager, 'directionsError', displayError );

// Calculate directions, which displays a route on the map directionsManager.calculateDirections();

function displayMessage(e) { alert("Route calculation complete!");

function displayError(e) { alert( e.message ); }

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> <div id='itineraryDiv' style="position:relative; width:400px;"></div> </body> </html>

170

DirectionsEventArgs Object
Contains the arguments for directions events.

Properties
Name Type Description

routeSummary

RouteSummary[]

The route summary (or summaries) of the route(s) defined in the route property. The calculated route (or routes, if the route mode is transit).

route

Route[]

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"});

171

Microsoft.Maps.loadModule('Microsoft.Maps.Directions', { callback: directionsModuleLoaded });

function directionsModuleLoaded() { // Initialize the DirectionsManager var directionsManager = new Microsoft.Maps.Directions.DirectionsManager(map);

// Create start and end waypoints and add them to the route var startWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Seattle, WA"}); var endWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Bellevue, WA"});

directionsManager.addWaypoint(startWaypoint); directionsManager.addWaypoint(endWaypoint);

// Set directions options - in this case, calculate a transit route. directionsManager.setRequestOptions({ routeMode: Microsoft.Maps.Directions.RouteMode.transit });

// Set directions render options - in this case, specify the div // where the itinerary is displayed.

directionsManager.setRenderOptions({ itineraryContainer: document.getElementById('itineraryDiv') });

// Specify a handler for when the directions are calculated Microsoft.Maps.Events.addHandler(directionsManager, 'directionsUpdated', displayRouteNumber);

// Calculate directions, which displays a route on the map directionsManager.calculateDirections();

172

function displayRouteNumber(e) { alert("Number of transit routes available: " + e.route.length);

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> <div id='itineraryDiv' style="position:relative; width:400px;"></div> </body> </html>

DirectionsManager Class
Contains methods for calculating directions and displaying a route on a map.

Constructor
Name Definition
DirectionsManager(map:Map)

Description

DirectionsManager

Initializes a new instance of the DirectionsManager class.

Methods
Name Definition
addWaypoint(waypoint:Waypoint)

Return Value

Description

addWaypoint

None

Adds a 173

Name

Definition

Return Value

Description

waypoint to the route. To recalculate the route, use calculateDirec tions. The maximum number of waypoints is 15. calculateDirecti ons
calculateDirections()

None

Calculates directions based on request and render options set (setRequestO ptions, setRenderOpti ons) and the waypoints added (addWaypoint) . The directionsUpd ated event fires when the calculation is complete and the route is displayed on the map. You must call this method after making any changes to the route options or waypoints.

clearDisplay

clearDisplay()

None

Clears the 174

Name

Definition

Return Value

Description

directions displayed and removes the route line from the map. This method does not remove waypoints from the route and retains all calculated direction information and option settings. To clear the calculated directions and options, use resetDirection s. dispose
dispose()

None

Deletes the DirectionsMan ager object and releases any associated resources. Returns the waypoints for the route. Returns the map object associated with the directions manager. Searches around the specified location for nearby major roads and 175

getAllWaypoint s getMap

getAllWaypoints()

Waypoint[]

getMap()

Map

getNearbyMajor getNearbyMajorRoads(location:Locatio Roads n, callback:function, errorCallback:function, userData:object)

None

Name

Definition

Return Value

Description

returns them as an object to the callback function. getRenderOptio getRenderOptions() ns getRequestOpti ons DirectionsRender Options DirectionsRequest Options Returns the route render options. Returns the directions request options. Returns the current calculated route(s). If the route was not successfully calculated, null is returned. Removes the given waypoint or the waypoint identified by the given index from the route. Use calculateDirec tions to update the route once a waypoint has been removed. If no options object is supplied, clears the directions request and render options and removes all waypoints. 176

getRequestOptions()

getRouteResult

getRouteResult()

Route[]

removeWaypoi nt

removeWaypoint(waypoint:Waypoint) removeWaypoints(index:number)

or

None

resetDirections

resetDirections(options:ResetDirectio

None

nsOptions)

Name

Definition
reverseGeocode(location:Location, callback:function, errorCallback:function, userData:object)

Return Value

Description

reverseGeocod e

None

Matches the specified location to an address and returns the address to the specified callback function. Sets the map view based on the current route index. Sets the specified render options for the route. Sets the specified route calculation options.

setMapView

setMapView()

None

setRenderOptio setRenderOptions(options:DirectionsR ns enderOptions)

None

setRequestOpti ons

setRequestOptions(options:Directions

None

RequestOptions)

Events
Name Arguments Description

afterRouteSelectorRender

RouteSelectorRenderEventArgs

Occurs after the route selector has fully rendered. Occurs after each step in the itinerary has fully rendered. Occurs after the route summary has fully rendered. Occurs after each route waypoint has 177

afterStepRender

DirectionsStepRenderEventArgs

afterSummaryRender

RouteSummaryRenderEventArgs

afterWaypointRender

WaypointRenderEventArgs

Name

Arguments

Description

fully rendered. beforeRouteSelectorRender RouteSelectorRenderEventArgs Occurs just before the route selector renders. Occurs just before each step in the itinerary renders. Occurs just before the route summary renders. Occurs just before each route waypoint renders. Occurs when calculating the directions caused an error. Occurs when the directions calculation was successful and the itinerary and route on the map have been updated. Occurs when a step in the itinerary is clicked. Occurs when the mouse cursor is over the route selector. Occurs when the mouse cursor is over a directions step. Occurs when the mouse cursor leaves the route selector. Occurs when the 178

beforeStepRender

DirectionsStepRenderEventArgs

beforeSummaryRender

RouteSummaryRenderEventArgs

beforeWaypointRender

WaypointRenderEventArgs

directionsError

DirectionsErrorEventArgs

directionsUpdated

DirectionsEventArgs

itineraryStepClicked

DirectionsStepEventArgs

mouseEnterRouteSelector

RouteSelectorEventArgs

mouseEnterStep

DirectionsStepEventArgs

mouseLeaveRouteSelector

RouteSelectorEventArgs

mouseLeaveStep

DirectionsStepEventArgs

Name

Arguments

Description

mouse cursor leaves a directions step. routeSelectorClicked RouteSelectorEventArgs Occurs when the route selector is clicked. Occurs when a new waypoint is added to the route. Occurs when a waypoint is removed from the route.

waypointAdded

WaypointEventArgs

waypointRemoved

WaypointEventArgs

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"});

179

Microsoft.Maps.loadModule('Microsoft.Maps.Directions', { callback: directionsModuleLoaded });

function directionsModuleLoaded() { // Initialize the DirectionsManager var directionsManager = new Microsoft.Maps.Directions.DirectionsManager(map);

// Create start and end waypoints var startWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Seattle, WA"}); var endWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Portland, OR"});

directionsManager.addWaypoint(startWaypoint); directionsManager.addWaypoint(endWaypoint);

// Set the id of the div to use to display the directions directionsManager.setRenderOptions({ itineraryContainer: document.getElementById('itineraryDiv') });

// Specify a handler for when an error occurs Microsoft.Maps.Events.addHandler(directionsManager, 'directionsError', displayError);

// Calculate directions, which displays a route on the map directionsManager.calculateDirections();

function displayError(e) {

180

alert(e.message); }

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> <div id='itineraryDiv' style="position:relative; width:400px;"></div> </body> </html>

DirectionsRenderOptions Object
Represents render options for a route.

Properties
Name Type Description

displayDisclaimer

boolean

A boolean indicating whether to display the disclaimer about the accuracy of the directions. The default value is false. A boolean indicating whether to display the icons for each direction maneuver. The default value is true. A boolean indicating whether to display direction hints that describe when an direction step was missed. The default value 181

displayManeuverIcons

boolean

displayPostItineraryItemHints

boolean

Name

Type

Description

is true. displayPreItineraryItemHints boolean A boolean indicating whether to display direction hints that describe what to look for before you come to the next direction step. The default value is true. A boolean indicating whether to display the route selector control. The default value is true. A boolean indicating whether to display direction warnings. The default value is true. A boolean indicating whether to display the control that allows the user to choose to avoid traffic. The default value is true. A boolean indicating whether to display a warning about walking directions. The default value is true. The options that define how to draw the route line on the map, if the RouteMode is driving. The DOM element inside which the directions itinerary will be rendered. The URL of the icon to use for the end waypoint. The options that define 182

displayRouteSelector

boolean

displayStepWarnings

boolean

displayTrafficAvoidanceOption

boolean

displayWalkingWarning

boolean

drivingPolylineOptions

PolylineOptions

itineraryContainer

DOMElement

lastWaypointIcon stepPushpinOptions

string PushpinOptions

Name

Type

Description

the pushpin to use for each direction step. transitPolylineOptions PolylineOptions The options that define how to draw the route line on the map, if the RouteMode is transit. The options that define the pushpin to use for each via point of the route, which are any waypoints other than the start and end waypoints. The options that define how to draw the route line on the map, if the RouteMode is walking. The options that define the pushpin to use for the route waypoint.

viapointPushpinsOptions

PushpinOptions

walkingPolylineOptions

PolylineOptions

waypointPushpinOptions

PushpinOptions

DirectionsRequestOptions Object
Contains options for the directions to calculate.

Properties
Name Type Description

avoidTraffic

boolean

A boolean indicating whether to use traffic data when calculating the route. The default value is false. The unit to use when displaying direction distances. The default value is based on the specified culture. 183

distanceUnit

DistanceUnit

Name

Type

Description

maxRoutes

number

The number of routes to calculate. If the routeMode is driving or walking, only 1 route is supported. If the routeMode is transit, up to 6 routes can be calculated and the default is 3. The features to avoid when calculating the route. The default value is none. A boolean indicating whether the route line on the map can be dragged with the mouse cursor. The default value is true. When a route is dragged, a via point is added to the route. To change the drag behavior of a waypoint, set the draggable property of the waypointPushpinOptions (of the DirectionsRenderOptions).

routeAvoidance

RouteAvoidance[]

routeDraggable

boolean

routeIndex

number

If multiple routes are returned, the index of the route and directions to display. This property only applies to routes where the routeMode is transit, and in this case up to 6 routes are supported. The type of directions to calculate. The default value is driving. The route mode transit is only supported when the culture is jajp, which is the default for that market. The optimization setting for the route calculation. The default value is shortestTime. The extra options for calculating a route if the routeMode is transit.

routeMode

RouteMode

routeOptimization

RouteOptimization

transitOptions

TransitOptions

184

DirectionsStep Class
Represents one direction in a set of route directions.

Properties
Name Type Description

childItineraryItems coordinate distance

DirectionsStep[] Location string

The child direction items for this directions step. The location of the start of the direction. The total distance of the step in the unit specified in the distanceUnit property of the DirectionsRequestOptions. The total time, in seconds, of the direction step. The HTML formatted route instruction associated with the step. The type of the icon associated with this step. A boolean indicating whether the maneuver image is a road shield image. The maneuver type associated with this step. The name of the maneuver image. The cost of the step. An array of strings, where each string is a hint to help determine when to move to the next direction step. Not all direction steps have hints. An array of strings, where each 185

durationInSeconds formattedText

number string

iconType isImageRoadShield

RouteIconType boolean

maneuver maneuverImageName monetaryCost postIntersectionHints

ManeuverType string number string[]

preIntersectionHints

string[]

Name

Type

Description

string is a hint to help determine when you have arrived at this direction step. Not all direction steps have hints. startStopName transitLine transitStopId transitTerminus warnings string TransitLine string string DirectionsStepWarning[] The name of the transit stop where this step originates. The transit line associated with this step. The ID of the transit stop. The name of the transit line end. An array of strings, where each string is a route warning associated with this step.

DirectionsStepEventArgs Object
Contains arguments for directions step events.

Properties
Name Type Description

handled

boolean

A boolean indicating whether the event is handled. Set this property to true to override the default behavior. The location along the route where the direction step occurs. A number indicating the route (if multiple routes were returned) to which the directions step belongs. A number indicating the route leg to which the directions 186

location

Location

routeIndex

number

routeLegIndex

number

Name

Type

Description

step belongs. step stepIndex DirectionsStep number The directions step. A number indicating the index of the directions step within the route leg array. A number indicating the directions step number within the route.

stepNumber

number

DirectionsStepRenderEventArgs Object
Contains arguments for directions step render events.

Properties
Name Type Description

containerElement

object

The DOM element which contains the directions step. You can use this property to add custom content. A boolean indicating whether the event is handled. This property is only available for the beforeStepRender event. Set this property to true to override the default behavior. A boolean indicating whether the step is the last directions step. A number indicating the index of the route to which this step belongs. A number indicating the index of the route leg to which this 187

handled

boolean

lastStep

boolean

routeIndex

number

routeLegIndex

number

Name

Type

Description

step belongs. step stepIndex DirectionsStep number The directions step. The index of this directions step within the route leg step array.

DirectionsStepWarning Class
Represents a route direction warning, such as a construction zone warning.

Properties
Name Type Description

style text

DirectionStepWarningType string

The type of the route warning. The warning text.

DirectionsStepWarningType Enumeration
Contains types of route direction warnings.

Constants
Code Name Description

0 1

info minor

The warning is just information about the route direction. The warning is a minor warning, and may affect the route direction. The warning is a moderate warning and is likely to affect the route direction.

moderate

188

Code

Name

Description

major

The warning is a major warning, and is highly likely to affect the route direction. The warning indicates a congestion zone is being entered. The warning indicates a congestion zone is being exited.

ccZoneEnter

ccZoneExit

Disambiguation Class
Contains disambiguation results for a waypoint geocoding request.

Properties
Name Type Description

businessSuggestions

BusinessDiambiguationSuggestion[]

The possible business result matches for the originally specified waypoint address or location. A boolean indicating whether there are more result suggestions available. The disambiguation header text. The possible location result matches for the originally specified waypoint address or location.

hasMoreSuggestions

boolean

headerText locationSuggestions

string LocationDiambiguationSuggestion[]

189

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null; var directionsManager = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"}); Microsoft.Maps.loadModule('Microsoft.Maps.Directions', { callback: directionsModuleLoaded });

function directionsModuleLoaded() { // Initialize the DirectionsManager directionsManager = new Microsoft.Maps.Directions.DirectionsManager(map);

// Create start and end waypoints var startWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"100 Main St., WA"});

190

var endWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Portland, OR"});

directionsManager.addWaypoint(startWaypoint); directionsManager.addWaypoint(endWaypoint);

// Set the id of the div to use to display the directions directionsManager.setRenderOptions({ itineraryContainer: document.getElementById('itineraryDiv') });

// Specify a handler for when an error occurs Microsoft.Maps.Events.addHandler(directionsManager, 'directionsError', displayError);

// Calculate directions, which displays a route on the map directionsManager.calculateDirections();

function displayError(e) {

// Display an error alert(e.message);

// If the error is a disambiguation error, show the disambiguation results if (e.responseCode == 12) { DisplayDisambiguation(); } }

function DisplayDisambiguation() {

191

var results = "";

var waypoints = directionsManager.getAllWaypoints();

var i = 0; for (i=0; i<waypoints.length; i++) {

var disambigResult = waypoints[i].getDisambiguationResult();

if (disambigResult != null) { results = results + "Address matches for " + waypoints[i].getAddress() + ":\n";

var j = 0; for (j=0; j<disambigResult.locationSuggestions.length; j++) { results = results + disambigResult.locationSuggestions[j].suggestion + "\n"; } } }

alert(results);

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> <div id='itineraryDiv' style="position:relative; width:400px;"></div> </body>

192

</html>

See Also
Waypoint Class (AJAX)

DistanceUnit Enumeration (AJAX)


Defines the distance unit to use when generating routes and corresponding itineraries.

Constants
Code Name Description

0 1

kilometers miles

Kilometers are used to measure route distances. Miles are used to measure route distances.

LocationDisambiguationSuggestion Class
Contains a possible result returned from geocoding a specified waypoint address or location.

Properties
Name Type Description

formattedSuggestion location rooftopLocation suggestion

string Location Location string

The HTML formatted address suggestion. The location of the suggestion. The rooftop location of the suggestion. The address suggestion.

193

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null; var directionsManager = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"}); Microsoft.Maps.loadModule('Microsoft.Maps.Directions', { callback: directionsModuleLoaded });

function directionsModuleLoaded() { // Initialize the DirectionsManager directionsManager = new Microsoft.Maps.Directions.DirectionsManager(map);

// Create start and end waypoints

194

var startWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"100 Main St., WA"}); var endWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Portland, OR"});

directionsManager.addWaypoint(startWaypoint); directionsManager.addWaypoint(endWaypoint);

// Set the id of the div to use to display the directions directionsManager.setRenderOptions({ itineraryContainer: document.getElementById('itineraryDiv') });

// Specify a handler for when an error occurs Microsoft.Maps.Events.addHandler(directionsManager, 'directionsError', displayError);

// Calculate directions, which displays a route on the map directionsManager.calculateDirections();

function displayError(e) { // Display the error message alert(e.message);

// If the error is a disambiguation error, display the results. if (e.responseCode == 12) { DisplayDisambiguation(); } }

function DisplayDisambiguation()

195

{ var results = "";

var waypoints = directionsManager.getAllWaypoints();

var i = 0; for (i=0; i<waypoints.length; i++) {

var disambigResult = waypoints[i].getDisambiguationResult();

if (disambigResult != null) { results = results + "Address matches for " + waypoints[i].getAddress() + ":\n";

var j = 0; for (j=0; j<disambigResult.locationSuggestions.length; j++) { results = results + disambigResult.locationSuggestions[j].suggestion + "\n"; } } }

alert(results);

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> <div id='itineraryDiv' style="position:relative; width:400px;"></div>

196

</body> </html>

See Also
Disambiguation Class

ManeuverType Enumeration (AJAX)


Contains route maneuver types.

Constants
Type Code Name Description

0 1 56 57 58 59 60 61

none unknown transfer wait takeTransit walk transitDepart transitArrive

The step is not a maneuver. The maneuver is unknown. The step is a transit transfer instruction. The step is a wait instruction. The step is information about what transit line to take. The step is a walking instruction. The step is a transit departure instruction. The step is a transit arrival instruction.

ResetDirectionsOptions Object
Contains options for the resetDirections method of the DirectionsManager Class.

Properties
197

Name

Type

Description

removeAllWaypoints

boolean

A boolean indicating whether to remove all of the waypoints of the route. The default value is false. A boolean indicating whether to reset all of the render options set for the route. The default value is false. A boolean indicating whether to reset all of the request options set for the route. The default value is false.

resetRenderOptions

boolean

resetRequestOptions

boolean

Route Class (AJAX)


Represents a route.

Properties
Name Type Description

routeLegs

RouteLeg[]

The legs of the route. Each route leg represents the route between two waypoints.

RouteAvoidance Enumeration
Defines features to avoid when calculating the route.

Constants
Code Name Description

none

Calculate the best route using any travel option 198

Code

Name

Description

available. 1 minimizeLimitedAccessHighway Reduce the use of limited access highways when calculating the route. Reduce the use of roads with tolls when calculating the route. Avoid using limited access highways when calculating the route. Avoid using roads with tolls when calculating the route. Avoid using express trains when calculating the route. Avoid using airlines when calculating the route. Avoid using bullet trains when calculating the route.

minimizeToll

avoidLimitedAccessHighway

8 16 32 64

avoidToll avoidExpressTrain avoidAirline avoidBulletTrain

RouteIconType Enumeration
Contains route icon types.

Constants
Type Code Name Description

0 1 2 3 4

none other auto ferry walk

There is no route icon. The icon is some other type of icon. The icon is a car icon. The icon is a ferry icon. The icon is a walking icon. 199

Type Code

Name

Description

5 6 7

bus train airline

The icon is a bus, or transit, icon The icon is a train icon. The icon is an airline icon.

RouteLeg Class (AJAX)


Represents a leg of a route. A route leg is the part of the route between two stop waypoints.

Properties
Name Type Description

endTime

DateTime

The end time of the route leg. This property only applies when the routeMode of the DirectionsRequestOptions is set to transit. The location of the last waypoint of this leg. The directions steps associated with this route leg. The index of the route to which this route leg belongs. The start time of the route leg. This property only applies when the routeMode of the DirectionsRequestOptions is set to transit. The location of the first waypoint of this route leg. The sub legs of this route leg. A sub leg of a route is the part of the route between a stop point and a via point or between two via points. 200

endWaypointLocation itineraryItems originalRouteIndex startTime

Location DirectionsStep[] number DateTime

startWaypointLocation subLegs

Location RouteSubLeg[]

Name

Type

Description

summary

RouteSummary

The summary which describes this route leg.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"}); Microsoft.Maps.loadModule('Microsoft.Maps.Directions', { callback: directionsModuleLoaded });

function directionsModuleLoaded() { // Initialize the DirectionsManager var directionsManager = new Microsoft.Maps.Directions.DirectionsManager(map);

201

// Create start and end waypoints and add them to the route var startWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Seattle, WA"}); var endWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Bellevue, WA"});

directionsManager.addWaypoint(startWaypoint); directionsManager.addWaypoint(endWaypoint);

// Specify a handler for when the directions are calculated Microsoft.Maps.Events.addHandler(directionsManager, 'directionsUpdated', displayMessage); Microsoft.Maps.Events.addHandler(directionsManager, 'directionsError', displayError);

// Calculate directions, which displays a route on the map directionsManager.calculateDirections();

function displayMessage(e) { alert("The calculated route has " + e.route[0].routeLegs[0].itineraryItems.length + " direction steps.");

function displayError(e) { alert("An error has occurred calculating the directions."); }

</script>

202

</head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>

RouteMode Enumeration
Defines the type of route to calculate.

Constants
Name Description

driving transit walking

Driving directions are calculated. Transit directions are calculated. Walking directions are calculated.

RouteOptimization Enumeration (AJAX)


Defines optimization options for calculating directions.

Constants
Code Name Description

0 1 3

shortestTime shortestDistance minimizeMoney

Calculate a route the shortest time. Calculate a route with the shortest distance. Minimize the cost when calculating directions. This option only affects routes with a transit RouteMode, which is only available when the culture 203

Code

Name

Description

is set to ja-jp. 4 minimizeTransfers Minimize transit transfers when calculating directions. This option only affects routes with a transit RouteMode, which is only available when the culture is set to ja-jp. Minimize the amount of walking when calculating directions. This option only affects routes with a transit RouteMode, which is only available when the culture is set to ja-jp.

minimizeWalking

RoutePath Class (AJAX)


Represents the route line shape on the map.

Use the setRenderOptions method of the DirectionsManager Class to set DirectionsRenderOptions to customize the look of the route line on the map.

Properties
Name Type Description

decodedLatitudes

double[]

An array of latitudes, where each latitude is the latitude for one of the locations that define the route line. An array of longitudes, where each is the longitude value for one of the locations that define the route line. An array of regions that define, depending on the 204

decodedLongitudes

double[]

decodedRegions

Object[]

Name

Type

Description

zoom level, how the route line should be rendered.

RouteResponseCode Enumeration
Contains response codes for a route calculation request.

Constants
Response Code Name Description

0 1 2

success unknownError cannotFindNearbyRoad

The route was successfully calculated. An unknown error has occurred. A nearby road cannot be found for one or more of the route waypoints. The distance between two route waypoints, or the total length of the route exceeds the limit of the route mode. Modify the waypoint locations so that they are closer together. A route cannot be calculated for the specified waypoints. For example, this code is returned when a route between Seattle, WA and Honolulu, HI is requested. There is no route data for the specified waypoints. There are no transit options available for the specified time. 205

tooFar

noSolution

5 7

dataSourceNotFound noAvailableTransitTrip

Response Code

Name

Description

transitStopsTooClose

The transit stops are so close that walking is always a better option. The transit stops are so close that walking is a better option. There is no transit data available for the route or for one or more of the specified waypoints, or the waypoints are in different transit areas that do not overlap. The directions calculation request has timed out. One or more waypoints need to be disambiguated. One or more waypoints do not have an address or location specified. The maximum number of waypoints, which is 15, has been exceeded. At least two waypoints are required to calculate a route. The first or last waypoint is a via point, which is not allowed. The search service failed to return results.

walkingBestAlternative

10

outOfTransitBounds

11 12 13

timeout waypointDisambiguation hasEmptyWaypoint

14

exceedMaxWaypointLimit

15 16

atleastTwoWaypointRequired firstOrLastStoppointIsVia

17

searchServiceFailed

RouteSelectorEventArgs Object
Contains arguments for route selector events.

206

Properties
Name Type Description

handled

boolean

A boolean indicating whether the event is handled. Set this property to true to override the default behavior. A number indicating the index of the route that was selected.

routeIndex

number

RouteSelectorRenderEventArgs Object
Contains arguments for route selector render events.

Properties
Name Type Description

containerElement

object

The DOM element which contains the route selector. You can use this property to add custom content. A boolean indicating whether the event is handled. This property is only available for the beforeRouteSelectorRender event. Set this property to true to override the default behavior. A number indicating the index of the selected route. The route leg of the selected route.

handled

boolean

routeIndex routeLeg

number RouteLeg

RouteSubLeg Class
Represents a route sub leg. A route sub leg is the part of the route between a stop point and a via point or between two via points. One or more sub legs make up a route leg. 207

Properties
Name Type Description

actualEnd actualStart endDescription routhPath

Location Location string RoutePath

The location of the last waypoint of the sub leg. The location of the first waypoint of the sub leg. The description of the last waypoint of the sub leg. The properties that define the route line of this sub leg on the map. The description of the first waypoint of the sub leg. The summary of this route sub leg.

startDescription summary

string RouteSummary

RouteSummary Class (AJAX)


Represents a route summary.

Properties
Name Type Description

distance

double

The total travel distance of the route, specified in the units set in the distanceUnit property of the DirectionsRequestOptions. The cost of the route. This property is only returned if the routeMode of the DirectionsRequestOptions is set to transit and the map culture is set to ja-jp. The location of the northeast corner of bounding box that defines the 208

monetaryCost

double

northEast

Location

Name

Type

Description

best map view of the route. southWest Location The location of the southwest corner of bounding box that defines the best map view of the route. The total travel time, in seconds, for the route. The total travel time, in seconds, taking into account traffic delays, for the route. This property is 0 if the avoidTraffic property of the DirectionsRequestOptions is set to false.

time timeWithTraffic

number number

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"});

209

Microsoft.Maps.loadModule('Microsoft.Maps.Directions', { callback: directionsModuleLoaded });

function directionsModuleLoaded() { // Initialize the DirectionsManager var directionsManager = new Microsoft.Maps.Directions.DirectionsManager(map);

// Create start and end waypoints and add them to the route var startWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Seattle, WA"}); var endWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Bellevue, WA"});

directionsManager.addWaypoint(startWaypoint); directionsManager.addWaypoint(endWaypoint);

// Set directions render options - in this case, specify the div where the itinerary is displayed. directionsManager.setRenderOptions({ itineraryContainer: document.getElementById('itineraryDiv') });

// Specify a handler for when the directions are calculated Microsoft.Maps.Events.addHandler(directionsManager, 'directionsUpdated', displayDistanceAndTime );

// Calculate directions, which displays a route on the map directionsManager.calculateDirections();

210

function displayDistanceAndTime(e) { alert("Total Distance: " + e.routeSummary[0].distance + " miles\n" + "Total Time: " + e.routeSummary[0].time/60 + " minutes" );

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> <div id='itineraryDiv' style="position:relative; width:400px;"></div> </body> </html>

RouteSummaryRenderEventArgs Object
Contains arguments for route summary render events.

Properties
Name Type Description

containerElement

object

The DOM element which contains the summary. You can use this property to add custom content. A boolean indicating whether the event is handled. This property is only available for the beforeSummaryRender event. Set this property to true to override the default behavior. 211

handled

boolean

Name

Type

Description

routeLegIndex

number

A number indicating the index of the route leg which this summary describes. The summary that was rendered.

summary

RouteSummary

TimeType Enumeration
Defines the time type.

Constants
Name Description

arrival departure lastAvailable

The time specified is an arrival time. The time specified is a departure time. The time specified is the last available time. These time types are only returned for routes with a transit RouteMode, which is only available when the culture is set to ja-jp.

TransitLine Class
Contains information about a transit line.

Properties
Name Type Description

abbreviatedName agencyId agencyName

string number string

The short name for the transit line. The ID of the agency that owns the transit line. The name of the agency that 212

Name

Type

Description

owns the transit line. agencyUrl string The URL of the website of the agency that owns the transit line. The color to use when rendering this transit line on the map. The color to use when rendering text associated with this transit line. Information about the provider of this transit line data. The full name of this transit line.

lineColor

Color

lineTextColor

Color

providerInfo verboseName

string string

TransitOptions Object
Contains extra options for transit routes.

Properties
Name Type Description

timeType

TimeType

The type of the time specified in transitTime. The default value is departure. The transit time to use when calculating the route. If this property is set to null, the current time is used.

transitTime

Date

Waypoint Class (AJAX)


Represents a route waypoint. 213

Constructor
Name Definition
Waypoint(options:WaypointOptions)

Description

Waypoint

Initializes a new instance of the Waypoint class.

Methods
Name Definition
clear()

Return Value

Description

clear

None

Clears all options associated with this waypoint. Releases any resources associated with the waypoint. Returns the address associated with the waypoint.

dispose

dispose()

None

getAddress

getAddress()

string

getBusinessDetails

getBusinessDetails()

BusinessDetail Returns the s business details associated with the waypoint. Disambiguatio n Returns the result of the waypoint geocoding disambiguatio n. Returns the 214

getDisambiguationRes ult

getDisambiguationResult()

getLocation

getLocation()

Location

Name

Definition

Return Value

Description

location of the waypoint. getShortAddress


getShortAddress()

string

Returns the short address for the waypoint. Returns a boolean indicating whether the waypoint location is the exact location. Returns a boolean value indicating whether the waypoint is a via point. A via point is a location that your route is guaranteed to pass through. There can be multiple via points between two stop points. Sets options for the waypoint. For these options to take effect, you must recalculate the route.

isExactLocation

isExactLocation()

boolean

isViapoint

isViapoint()

boolean

setOptions

setOptions(options:WaypointOptio

None

ns)

215

Events
Name Arguments Description

changed

WaypointEventArgs

Occurs when the any properties of the waypoint change or are updated. Occurs when a geocoding request for the waypoints address is made. Occurs when a reverse geocoding request for the waypoints location is made. This happens when no address is provided for the waypoint, or if the waypoint is dragged (in which case its location is changed).

geocoded

WaypointEventArgs

reverseGeocoded

WaypointEventArgs

WaypointEventArgs Object
Contains the arguments for route waypoint events.

Properties
Name Type Description

waypoint

Waypoint

The waypoint for which the event occurred.

WaypointOptions Object
Contains waypoint options.

Properties
216

Name

Type

Description

address

string

The address of the waypoint. Either address or location must be specified. The business details of the waypoint, if it is a business. A boolean indicating whether the waypoint location is the exact location. The default value is false. A boolean indicating whether the waypoint is a via point. A via point is a point along the route that is not a stop point. Set this property to true if you just want the route to pass through this location. The default value is false. The location of the waypoint. Either address or location must be specified. The short address of the waypoint.

businessDetails exactLocation

BusinessDetails boolean

isViapoint

boolean

location

Location

shortAddress

string

WaypointRenderEventArgs Object
Contains arguments for waypoint render events.

Properties
Name Type Description

containerElement

object

The DOM element which contains the waypoint. You can use this property to add custom content. A boolean indicating whether the event is handled. This property is 217

handled

boolean

Name

Type

Description

only available for the beforeWaypointRender event. Set this property to true to override the default behavior. waypoint Waypoint The waypoint for which the event occurred.

Microsoft.Maps.Traffic API Reference


This section contains reference documentation for the Microsoft.Maps.Traffic API, which contains types that allow you to display traffic on your Bing Maps AJAX Control 7.0 map.

Before you can access the types found in the Microsoft.Maps.Traffic API, you must first load this module using the loadModule method. Information about loading modules is in the Module Loading Methods topic.

In This Section
TrafficLayer Class

TrafficLayer Class
Represents a traffic layer on the map.

Constructor
Name Definition
TrafficLayer(map:Map)

Description

TrafficLayer

Initializes a new instance of the TrafficLayer class.

Methods

218

Name

Definition
getTileLayer()

Return Value

Description

getTileLayer hide show

TileLayer None None

Returns the traffic layer. Hides the traffic layer. Displays the traffic layer.

hide() show()

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() {

map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials: "Bing Maps Key", center: new Microsoft.Maps.Location(47.5, -122.3), zoom: 9 });

Microsoft.Maps.loadModule('Microsoft.Maps.Traffic', { callback: trafficModuleLoaded });

219

function trafficModuleLoaded() { var trafficLayer = new Microsoft.Maps.Traffic.TrafficLayer(map); trafficLayer.show(); }

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:600px; height:600px;"></div> </body> </html>

Microsoft.Maps.VenueMaps API Reference


This section contains reference documentation for the Microsoft.Maps.VenueMaps API. Use the VenueMapFactory Class to search for available venue maps.

Before you can access the types found in the Microsoft.Maps.VenueMaps API, you must first load this module using the loadModule method. Information about loading modules is in the Module Loading Methods topic.

In This Section
Floor Class Footprint Class Metadata Class NearbyVenue Class NearbyVenueOptions Object Polygon Class Primitive Class VenueMap Class VenueMapCreationOptions Object 220

VenueMapFactory Class

Floor Class
Represents one floor map of a venue map.

Properties
Name Type Description

name primitives

string Primitive[]

The name of the floor. An array of Primitive objects that represent the points of interest (for example, stores) on this venue floor. An array of doubles indicating the minimum and maximum zoom levels where imagery is available for this venue map floor.

zoomRange

double[]

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

221

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"});

Microsoft.Maps.loadModule('Microsoft.Maps.VenueMaps', { callback: venuemapsModuleLoaded });

function venuemapsModuleLoaded() {

// Create the venue map var vmaps = new Microsoft.Maps.VenueMaps.VenueMapFactory(map);

vmaps.create({venueMapId: 'bingmapsteam-bellevuesquare', success:ShowVenue, error:ShowError});

function ShowVenue(venue) { // Set the map view map.setView(venue.bestMapView); venue.show();

DisplayVenueFloorInfo(venue);

222

function ShowError() { // Show an error alert("An error occurred trying to create the venue map.");

function DisplayVenueFloorInfo(venue) {

var floors = "Available floor maps for " + venue.name +":\n";

for(var i in venue.floors) { floors = floors + venue.floors[i].name + "\n";

// Display the floor info alert(floors);

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:500px; height:500px;"></div> </body> </html>

Footprint Class
Represents the footprint of the venue map. 223

Properties
Name Type Description

polygons zoomRange

Polygon[] double[]

The shapes that make up the footprint of this venue. An array of doubles indicating the minimum and maximum zoom levels where imagery is available for this venue map.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials:"Bing Maps Key"}); Microsoft.Maps.loadModule('Microsoft.Maps.VenueMaps', { callback: venuemapsModuleLoaded });

224

function venuemapsModuleLoaded() { // Create the venue map var vmaps = new Microsoft.Maps.VenueMaps.VenueMapFactory(map); vmaps.create({venueMapId: 'bingmapsteam-bellevuesquare', success:ShowVenue, error:ShowError});

function ShowVenue(venue) { // Set the map view map.setView(venue.bestMapView); venue.show();

DisplayVenueInfo(venue);

function ShowError() { // Show an error alert("An error occurred trying to create the venue map.");

function DisplayVenueInfo(venue) { var venueinfo = "Venue: " + venue.name +"\n" + "Venue Map ID: " + venue.id + "\n" + "Venue Map Type: " + venue.type + "\n" + "Default Floor: " + venue.defaultFloor + "\n" + "Detail Level Range for Default Floor: " + venue.footprint.zoomRange + "\n";

// Display the venue info

225

alert(venueinfo);

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:500px; height:500px;"></div> </body> </html>

Metadata Class
Contains information about a venue map.

Properties
Name Type Description

CenterLat CenterLong DefaultFloor FloorHeader Floors Footprint MapId MapType

number number string string Floor[] Footprint string string

The latitude of the center location of the venue map. The longitude of the center location of the venue map. The ID of the default floor of the venue map. A string used in the floor bar of the venue map. An array containing the floors of the venue map. The footprint of the venue map. The unique ID of the venue map. A string describing the venue map type (for example, mall). 226

Name

Type

Description

Name YpId

string string

The name of the venue map. The Yellow Pages ID of the venue.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map and set the view to a specific location map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key", center: new Microsoft.Maps.Location(47.6,-122.3), zoom:11});

Microsoft.Maps.loadModule('Microsoft.Maps.VenueMaps', { callback: venuemapsModuleLoaded });

function venuemapsModuleLoaded()

227

{ // Create the venue map var vmaps = new Microsoft.Maps.VenueMaps.VenueMapFactory(map);

// Search for nearby venues vmaps.getNearbyVenues({map: map, location: map.getCenter(), radius:10000, callback:DisplayNearbyVenueCount});

function DisplayNearbyVenueCount(venues) { var displayResults = "Nearby venues with available venue maps:\n";

for (var i=0; i<venues.length; i++) { displayResults = displayResults + venues[i].metadata.Name + "\t" + venues[i].distance/1000 + " km\n";

alert(displayResults); }

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:500px; height:500px;"></div> </body> </html>

228

NearbyVenue Class
Defines a nearby venue map.

Properties
Name Type Description

distance metadata

double Metadata

The distance, in meters, to the venue. The venue map metadata.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map and set the view to a specific location map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key", center: new Microsoft.Maps.Location(47.6,-122.3), zoom:11});

229

Microsoft.Maps.loadModule('Microsoft.Maps.VenueMaps', { callback: venuemapsModuleLoaded });

function venuemapsModuleLoaded() { // Create the venue map var vmaps = new Microsoft.Maps.VenueMaps.VenueMapFactory(map);

// Search for nearby venues vmaps.getNearbyVenues({map: map, location: map.getCenter(), radius:10000, callback:DisplayNearbyVenueCount});

function DisplayNearbyVenueCount(venues) { var displayResults = "Nearby venues with available venue maps:\n";

for (var i=0; i<venues.length; i++) { displayResults = displayResults + venues[i].metadata.Name + "\t" + venues[i].distance/1000 + " km\n";

alert(displayResults); }

</script>

230

</head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:500px; height:500px;"></div> </body> </html>

NearbyVenueOptions Object
Contains search options for retrieving nearby venue maps.

Properties
Name Type Description

callback

function

The function to call when the search is completed. The function must accept an array of VenueMap objects. The center of the circle in which to search for nearby venue maps. The base map. The radius, in meters, of the circle in which to search for nearby venue maps.

location

Location

map radius

Map double

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

231

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map and set the view to a specific location map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key", center: new Microsoft.Maps.Location(47.6,-122.3), zoom:11});

Microsoft.Maps.loadModule('Microsoft.Maps.VenueMaps', { callback: venuemapsModuleLoaded });

function venuemapsModuleLoaded() { // Create the venue map var vmaps = new Microsoft.Maps.VenueMaps.VenueMapFactory(map);

// Search for nearby venues vmaps.getNearbyVenues({map: map, location: map.getCenter(), radius:10000, callback:DisplayNearbyVenueCount});

function DisplayNearbyVenueCount(venues) { alert("There are " + venues.length + " venue maps nearby.");

232

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:500px; height:500px;"></div> </body> </html>

Polygon Class (Venue Map)


Defines the shape of venue map entities.

Properties
Name Type Description

bounds center locations

LocationRect Location Location[]

The rectangle that defines the bounding box for the polygon. The center of the polygon. The locations that define the vertices of the polygon.

Primitive Class
Represents a venue map primitive, which represents a venue map entity.

Properties
Name Type Description

bounds

LocationRect

The rectangle that defines the bounding box for the primitive. 233

Name

Type

Description

businessId categoryId categoryName center floor id locations

string string string Location Floor string Location[]

The Yellow Pages ID for the entity. The Yellow Pages business category ID for the entity. The Yellow Pages business category name for the entity. The location of the center of the primitive. The floor to which this primitive belongs. The unique ID of the entity. An array of locations that represent the vertices of the primitive. The name of the entity.

name

string

Methods
Name Definition
highlight()

Return Type

Description

highlight unhighlight

None None

Highlights the primitive. Removes the highlighting of the primitive.

unhighlight()

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

234

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null; var vmaps = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"});

Microsoft.Maps.loadModule('Microsoft.Maps.VenueMaps', { callback: venuemapsModuleLoaded });

function venuemapsModuleLoaded() {

// Create the venue map var vmaps = new Microsoft.Maps.VenueMaps.VenueMapFactory(map);

vmaps.create({venueMapId: 'bingmapsteam-bellevuesquare', success:ShowVenue});

function ShowVenue(venue) {

235

// Set the map view map.setView(venue.bestMapView); venue.show();

Microsoft.Maps.Events.addHandler(venue, 'click', DisplayVenueEntity);

alert("Click on the venue map to display entity info.");

function DisplayVenueEntity(e) { alert("The name of the store that was clicked is " + e.name + ".");

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:500px; height:500px;"></div> </body> </html>

VenueMap Class
Represents a venue map. An example of a venue map is a mall.

Properties

236

Name

Type

Description

address bestMapView businessId center defaultFloor floorHeader

string ViewOptions string Location string string

The full address of the venue. The best map view of the venue map. The Yellow Pages ID for the venue map. The location of the center of the venue map. The floor that is displayed if no floor is specified. The header for floors for this venue map. For example, for a mall the floor header would be Level. An array, where each element represents a floor of the venue. The shapes that make up the venue map. The unique venue map ID. The name of the venue represented by the venue map. The phone number for the venue represented by the venue map. The venue map type, such as Mall.

floors

Floor[]

footprint id name

Footprint string string

phoneNumber

string

type

string

Methods
Name Definition
dispose()

Return Type

Description

dispose

None

Disposes the venue map 237

Name

Definition

Return Type

Description

object. getActiveFloor
getActiveFloor()

string

Returns the venue floor map that is currently displayed. Hides the venue map. Displays the specified floor map for the venue map identified by the given ID. Displays the venue map.

hide setActiveFloor

hide()

None None

setActiveFloor(venueMapId:string, floor:string)

show

show()

None

Events
Name Arguments Description

click close

eventArgs:Primitive None

Occurs when the mouse is used to click the venue map. Occurs when the close button on the venue map is clicked. Occurs when the detailed map of the venue is clicked. Occurs when the mouse cursor moves out of the area covered by the venue map. Occurs when the mouse cursor is over the venue map.

footprintclick mouseout

eventArgs:Primitive eventArgs:Primitive

mouseover

eventArgs:Primitive

238

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null; var venue = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"});

Microsoft.Maps.loadModule('Microsoft.Maps.VenueMaps', { callback: venuemapsModuleLoaded });

function venuemapsModuleLoaded() {

// Create the venue map var vmaps = new Microsoft.Maps.VenueMaps.VenueMapFactory(map);

vmaps.create({venueMapId: 'bingmapsteam-bellevuesquare', success:SetVenue});

239

function SetVenue(venueObj) { venue = venueObj; }

function ShowVenue() { // Set the map view map.setView(venue.bestMapView); venue.show();

function HideVenue() { venue.hide();

</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:500px; height:500px;"></div> <input type="button" value="Show Venue Map" onclick="ShowVenue()"/><input type="button" value="Hide Venue Map" onclick="HideVenue()"/> </body> </html>

240

VenueMapCreationOptions Object
Contains options for creating a venue map.

Properties
Name Type Description

error

function

The function to call if the venue map was not successfully created. The function must accept two parameters: an integer which is an error code and an object that contains the arguments passed to the create method of the VenueMapFactory. The error codes are: 1 The metadata needed to create the venue map was not found because of a 404 or other web exception, or because the metadata was found but was empty. 2 The venue map metadata is invalid. 3 A timeout has occurred trying to retrieve the venue map metadata.

success

function

The function to call if the venue map was successfully created. The function must accept two parameters: a VenueMap and an object that contains the arguments passed to the create method of the VenueMapFactory. A string that identifies the venue map to display.

venueMapId

string

241

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), credentials:"Bing Maps Key"});

Microsoft.Maps.loadModule('Microsoft.Maps.VenueMaps', { callback: venuemapsModuleLoaded });

function venuemapsModuleLoaded() { // Create the venue map var vmaps = new Microsoft.Maps.VenueMaps.VenueMapFactory(map); vmaps.create({venueMapId: 'bingmapsteam-bellevuesquare', success:ShowVenue, error:ShowError});

242

function ShowVenue(venue) { // Set the map view map.setView(venue.bestMapView); venue.show();

function ShowError() { // Show an error alert("An error occurred trying to create the venue map.");

} </script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:500px; height:500px;"></div> </body> </html>

VenueMapFactory Class
Contains methods for creating a venue map.

Constructor
Name Definition
VenueMapFactory(map:Map)

Description

VenueMapFactory

Initializes a new instance of the VenueMapFactory class.

243

Methods
Name Definition Retur n Type Description

create

create(options:VenueMapCreationOptions)

None Creates a venue map. If the venue map is created successfully, a VenueMap is returned to the function specified in the success property of the VenueMapCreationOpti ons. You can display a venue map using the show method of the VenueMap Class.

getNearbyVen ues

getNearbyVenues(options:NearbyVenueMap

Options)

None Searches for venue maps within a specified distance. The callback function must accept a NearbyVenue array.

Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>

<script type="text/javascript">

244

var map = null;

function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials:"Bing Maps Key"}); Microsoft.Maps.loadModule('Microsoft.Maps.VenueMaps', { callback: venuemapsModuleLoaded });

function venuemapsModuleLoaded() { // Create the venue map var vmaps = new Microsoft.Maps.VenueMaps.VenueMapFactory(map); vmaps.create({venueMapId: 'bingmapsteam-bellevuesquare', success:DisplayInfobox}); }

function DisplayInfobox(venue) { // Set the map view map.setView(venue.bestMapView); venue.show();

// Put an info box label on the map mapCenter = map.getTargetCenter(); var venueinfobox = new Microsoft.Maps.Infobox(mapCenter, {title: venue.name, showPointer: false, showCloseButton:false, height: 50, width: 180, offset:new Microsoft.Maps.Point(-220, 150)});

map.entities.push(venueinfobox);

245

} </script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:500px; height:500px;"></div> </body> </html>

Bing Maps AJAX Control 7.0 Supported Browsers


This topic contains information about browser support for the Bing Maps AJAX Control 7.0.

The Bing Maps AJAX Control 7.0 uses features of HTML5 if it detects that the client browser supports HTML5. If this is the case, map performance will be faster, and map animations and transitions will be smoother.

Supported Browsers
The Bing Maps AJAX Control 7.0 is supported on the following Web browsers. If you are not using a supported Web browser, certain features of the map control may not work.
Desktop Browser Description

Internet Explorer 7.0 Internet Explorer 8.0 Internet Explorer 9.0 Firefox 3.6 Firefox 4.0 Safari 5 Google Chrome

Supported on the PC Supported on the PC Supported on the PC Supported on the PC and the Mac Supported on the PC and the Mac Supported on the Mac Supported on the PC

Mobile Browser

Apple 3GS/4.0 iPhone Browser 246

Mobile Browser

Google Android 2.X Browser Research in Motion (RIM) BlackBerry 6.0 Browser

Bing Maps AJAX Control 7.0 Developer Resources


This topic contains support resources and contact information.

Developer Resources
The following resources are available for Bing Maps developers: Check out the Bing Maps AJAX Control 7.0 Interactive SDK, which allows you to test out your own map control code. Connect with other Bing Maps developers on the Bing Maps AJAX Control Forum. Visit the http://www.microsoft.com/maps website. Read the Bing Maps Developer blog

Account Issues
If you are having issues creating a Bing Maps Developer Account, getting a Bing Maps Key, or have an account access question, contact mpnet@microsoft.com.

Licensing Questions
If you are interested in finding out more about Bing Maps or have questions about licensing Bing Maps, email maplic@microsoft.com or go to http://www.microsoft.com/maps/resources/default.aspx. From North, Central, and South America, you can also contact Bing Maps by calling (800) 426-9400, ext. 11315.

247