Escolar Documentos
Profissional Documentos
Cultura Documentos
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
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
11
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.
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
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
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">
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>
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"/>
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>
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
onscriptload
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
18
<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>
19
<script type="text/javascript">
function GetMap() { 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: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">
function GetMap() {
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));
21
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">
function GetMap() { // Initialize the map var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), {credentials:"Your Bing Maps Key"});
22
// 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">
function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});
23
</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">
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});
</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>
25
<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
</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>
<script type="text/javascript">
// Define colors var blue = new Microsoft.Maps.Color(100, 0, 0, 200); var green = new Microsoft.Maps.Color(100, 0, 100, 100);
27
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});
function ChangePolygonColor() {
28
// Get the map square entity. We know square was the last entity added, // so we can calculate the index.
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>
<!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">
function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});
// 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>
<script type="text/javascript">
function GetMap()
31
// 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);
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>
<script type="text/javascript">
33
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
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
<script type="text/javascript">
function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Your Bing Maps Key", mapTypeId:Microsoft.Maps.MapTypeId.road});
function MakeGeocodeRequest(credentials) {
36
CallRestService(geocodeRequest); }
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
</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>
38
<script type="text/javascript">
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>
Then, construct the REST route request using the input values. 39
<script type="text/javascript">
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});
41
// 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>
<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 });
43
// Construct the layer using the tile source var tilelayer= new Microsoft.Maps.TileLayer({ mercator: tileSource, opacity: .7 });
</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:400px; height:400px;"></div> </body> </html>
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">
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">
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
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;
// 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>
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.
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
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 });
<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.
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
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
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
Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html>
54
<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};
// 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"}));
55
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
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
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">
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
// 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)});
// 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
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
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
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
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
<script type="text/javascript">
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
} }
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">
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
// 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);
} }
</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
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
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
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">
function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});
// 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);
</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
Methods
Name Definition Retur n Value Description
addAccuracyCircle
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)
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">
function GetMap() {
74
</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
Name
Definition
options?:InfoboxOptions)
Description
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()
getOffset
getOffset()
number
getOptions
getOptions()
InfoboxOpti
Name
Definition
Return Value
Description
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
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
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
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">
79
// 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);
80
</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
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">
83
function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});
// 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);
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
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">
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.
86
} }
</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
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">
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 }
</script> </head>
88
Constructor
Name Definition
Location(latitude:number, longitude:number, altitude?:number, altitudeReference?:AltitudeReference)
Description
Location
Properties
Name Type Description
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">
90
function GetMap() {
// Retrieve the latitude and longitude values- normalize the longitude value var latVal = parseInt(latLongArray[0]); var longVal = Microsoft.Maps.Location.normalizeLongitude(parseInt(latLongArray[1]));
} </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
Properties
Name Type Description
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
fromCorners(northwest:Loc
ation, southeast:Location)
fromEdges(north:number, west:number, south:number, east:number, altitude:number, altitudeReference:Altitude
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);
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
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
<script type="text/javascript">
function GetMap() {
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
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
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
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()
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
getTargetHeading()
number
getTargetMetersPerPixel()
number
getTargetZoom
getTargetZoom()
number
getUserLayer getViewportX
getUserLayer() getViewportX()
Node number
Name
Definition
Return Value
Description
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()
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({height:numbe
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:
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
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
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">
102
<script type="text/javascript">
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">
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};
108
MapTypeId Enumeration
Contains identifiers for the imagery displayed on the map.
Constants
Name Description
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
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
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
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">
var map;
// 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">
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
Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
117
<script type="text/javascript">
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);
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
Properties
Name Type Description
x y
number number
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">
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);
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
Constructor
Name Definition
Polygon(locations:Location[], options?:PolygonOptions)
Description
Polygon
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
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">
124
// 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});
</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
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">
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
</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
Methods
Name Definition
getLocations()
Return Value
Description
getLocations
Location[]
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">
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);
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">
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"});
</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">
function GetMap()
135
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
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">
var map;
function GetMap() {
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>
Constructor
Name Definition
Pushpin(location:Location, options?:PushpinOptions)
Description
Pushpin
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(location:Location)
setOptions(options:PushpinOptions)
toString()
Name
Definition
Return Value
Description
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
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">
function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});
// Add a pin to the center of the map var pin = new Microsoft.Maps.Pushpin(center, {draggable: true});
144
map.entities.push(pin); }
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">
function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("myMap"), {credentials:"Bing Maps Key"});
// 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
</body> </html>
TileLayer Class
Represents a tile layer.
Constructor
Name Definition
TileLayer(options:TileLayerOptions)
Description
TileLayer
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
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">
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 });
</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">
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 });
152
map.entities.push(tilelayer);
function SetOpacity() {
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
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">
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 });
155
</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">
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 });
</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.
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">
160
<script type="text/javascript">
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};
function SetZoom() { // Retrieve the zoom level set by the user - converting it to a number. var zoomLevel = parseInt(document.getElementById("txtZoom").value);
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>
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
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
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
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">
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
// 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') });
166
{ DisplayDisambiguation(); } }
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"/>
168
<script type="text/javascript">
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 });
// 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 );
</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">
function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"});
171
// 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.
// Specify a handler for when the directions are calculated Microsoft.Maps.Events.addHandler(directionsManager, 'directionsUpdated', displayRouteNumber);
172
</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
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
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
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
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">
function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"});
179
// 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') });
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
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
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
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">
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 });
// Create start and end waypoints var startWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"100 Main St., WA"});
190
directionsManager.addWaypoint(startWaypoint); directionsManager.addWaypoint(endWaypoint);
// Set the id of the div to use to display the directions directionsManager.setRenderOptions({ itineraryContainer: document.getElementById('itineraryDiv') });
function displayError(e) {
// If the error is a disambiguation error, show the disambiguation results if (e.responseCode == 12) { DisplayDisambiguation(); } }
function DisplayDisambiguation() {
191
if (disambigResult != null) { results = results + "Address matches for " + waypoints[i].getAddress() + ":\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)
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
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">
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 });
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') });
// If the error is a disambiguation error, display the results. if (e.responseCode == 12) { DisplayDisambiguation(); } }
function DisplayDisambiguation()
195
if (disambigResult != null) { results = results + "Address matches for " + waypoints[i].getAddress() + ":\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
Constants
Type Code Name Description
0 1 56 57 58 59 60 61
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
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
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
RouteIconType Enumeration
Contains route icon types.
Constants
Type Code Name Description
0 1 2 3 4
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
The icon is a bus, or transit, icon The icon is a train icon. The icon is an airline icon.
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
startWaypointLocation subLegs
Location RouteSubLeg[]
Name
Type
Description
summary
RouteSummary
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">
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 });
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);
function displayMessage(e) { alert("The calculated route has " + e.route[0].routeLegs[0].itineraryItems.length + " direction steps.");
</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 directions are calculated. Transit directions are calculated. Walking directions are calculated.
Constants
Code Name Description
0 1 3
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
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
RouteResponseCode Enumeration
Contains response codes for a route calculation request.
Constants
Response Code Name Description
0 1 2
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
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
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
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">
function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"});
209
// 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 );
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
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
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
Constructor
Name Definition
Waypoint(options:WaypointOptions)
Description
Waypoint
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
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
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.
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
Methods
218
Name
Definition
getTileLayer()
Return Value
Description
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">
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 });
219
</script> </head> <body onload="GetMap();"> <div id='mapDiv' style="position:relative; width:600px; height:600px;"></div> </body> </html>
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">
221
function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"});
function venuemapsModuleLoaded() {
DisplayVenueFloorInfo(venue);
222
function ShowError() { // Show an error alert("An error occurred trying to create the venue map.");
function DisplayVenueFloorInfo(venue) {
</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">
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});
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";
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
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">
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});
function venuemapsModuleLoaded()
227
// 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
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">
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
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">
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});
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>
Properties
Name Type Description
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
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
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">
function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"});
function venuemapsModuleLoaded() {
function ShowVenue(venue) {
235
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
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
phoneNumber
string
type
string
Methods
Name Definition
dispose()
Return Type
Description
dispose
None
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">
function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key"});
function venuemapsModuleLoaded() {
239
</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">
function GetMap() { // Initialize the map map = new Microsoft.Maps.Map(document.getElementById("mapDiv"), credentials:"Bing Maps Key"});
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 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
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">
244
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}); }
// 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>
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
Mobile Browser
Google Android 2.X Browser Research in Motion (RIM) BlackBerry 6.0 Browser
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