bing maps ajax

Contents

Bing Maps AJAX Control, Version 7.0 ........................................................................................... 11

In This Section ............................................................................................................................ 11

See Also ..................................................................................................................................... 11

Getting Started with the 7.0 Map Control ...................................................................................... 11

Create a Bing Maps Account and Get a Key ............................................................................. 12

Get Familiar with the Bing Maps AJAX 7.0 Control ................................................................... 12

What's New in the AJAX Map Control ........................................................................................... 12

New Features ............................................................................................................................. 12

Developing with the 7.0 Map Control............................................................................................. 13

In This Section ............................................................................................................................ 13

Loading the AJAX Map Control ..................................................................................................... 13

Displaying the Default Map ........................................................................................................ 13

Customizing the Map When Loading ......................................................................................... 16

Example ..................................................................................................................................... 16

Setting Map Control Parameters ................................................................................................... 17

Parameters ................................................................................................................................. 17

Setting Parameters..................................................................................................................... 18

See Also ..................................................................................................................................... 18

Changing the Map View ................................................................................................................ 18

Setting the Initial Map View ........................................................................................................ 18

Changing the Map View ............................................................................................................. 19

Adding Entities to the Map ............................................................................................................. 22

Adding Single Entities to the Map .............................................................................................. 22

Adding a Pushpin .................................................................................................................... 22

Adding a Shape ...................................................................................................................... 24

Adding Multiple Entities to the Map ............................................................................................ 25

Changing Entities on the Map .................................................................................................... 27

Customizing Your Pushpins .......................................................................................................... 29

Customizing Your Pushpin Icon ................................................................................................. 30

Creating a Pushpin Infobox ........................................................................................................ 31

Displaying Location Search Results Using the REST Services .................................................... 33

Initialize the Map ........................................................................................................................ 33

Add Controls ............................................................................................................................... 34

Make a Geocode REST Request ............................................................................................... 35

Display the Results..................................................................................................................... 36

Getting Route Directions Using the REST Services ...................................................................... 38

Initialize the Map ........................................................................................................................ 38

Construct the Route Request ..................................................................................................... 39

Display the Results..................................................................................................................... 40

Working with Tile Layers ............................................................................................................... 43

Adding a Tile Layer .................................................................................................................... 43

Using Events in the AJAX Control ................................................................................................. 44

Example ..................................................................................................................................... 44

Returning a Localized Map ............................................................................................................ 48

Setting the Culture...................................................................................................................... 48

Supported Cultures .................................................................................................................... 48

Remarks ..................................................................................................................................... 49

Building Your Own Module ............................................................................................................ 49

Develop Your Module ................................................................................................................. 49

Register and Load Your Module ................................................................................................ 51

Use Your Module........................................................................................................................ 51

See Also ..................................................................................................................................... 52

Microsoft.Maps API Reference ...................................................................................................... 52

In This Section ............................................................................................................................ 53

Data Structures ....................................................................................................................... 53

Mapping .................................................................................................................................. 53

Entities .................................................................................................................................... 53

User Location .......................................................................................................................... 54

Dynamic Module Loading ....................................................................................................... 54

AltitudeReference Enumeration ..................................................................................................... 54

Constants ................................................................................................................................... 54

Methods ...................................................................................................................................... 54

Example ..................................................................................................................................... 54

AnimationVisibility Enumeration .................................................................................................... 56

Constants ................................................................................................................................... 56

Color Class .................................................................................................................................... 56

Constructor ................................................................................................................................. 56

Properties ................................................................................................................................... 57

Static Methods ............................................................................................................................ 57

Methods ...................................................................................................................................... 57

Example ..................................................................................................................................... 58

Coordinates Class ......................................................................................................................... 60

Properties ................................................................................................................................... 60

See Also ..................................................................................................................................... 61

EntityCollection Class .................................................................................................................... 61

Constructor ................................................................................................................................. 61

Methods ...................................................................................................................................... 61

Events ........................................................................................................................................ 63

Example ..................................................................................................................................... 64

EntityCollectionOptions Object ...................................................................................................... 66

Properties ................................................................................................................................... 66

Example ..................................................................................................................................... 67

Events Object ................................................................................................................................ 69

Methods ...................................................................................................................................... 69

Example ..................................................................................................................................... 70

GeoLocationProvider Class ........................................................................................................... 71

Constructor ................................................................................................................................. 72

Methods ...................................................................................................................................... 72

Example ..................................................................................................................................... 74

See Also ..................................................................................................................................... 75

Infobox Class ................................................................................................................................. 75

Constructor ................................................................................................................................. 75

Methods ...................................................................................................................................... 76

Events ........................................................................................................................................ 78

Remarks ..................................................................................................................................... 79

Example ..................................................................................................................................... 79

InfoboxOptions Object ................................................................................................................... 81

Properties ................................................................................................................................... 81

Example ..................................................................................................................................... 83

See Also ..................................................................................................................................... 85

KeyEventArgs Object .................................................................................................................... 85

Properties ................................................................................................................................... 85

Example ..................................................................................................................................... 86

LabelOverlay Enumeration ............................................................................................................ 87

Constants ................................................................................................................................... 87

Methods ...................................................................................................................................... 87

Example ..................................................................................................................................... 88

Location Class (AJAX) ................................................................................................................... 89

Constructor ................................................................................................................................. 89

Properties ................................................................................................................................... 89

Static Methods ............................................................................................................................ 89

Methods ...................................................................................................................................... 90

Example ..................................................................................................................................... 90

LocationRect Class ........................................................................................................................ 92

Constructor ................................................................................................................................. 92

Properties ................................................................................................................................... 92

Static Methods ............................................................................................................................ 92

Methods ...................................................................................................................................... 93

Example ..................................................................................................................................... 94

Map Class ...................................................................................................................................... 95

Constructor ................................................................................................................................. 96

Properties ................................................................................................................................... 96

Static Methods ............................................................................................................................ 96

Methods ...................................................................................................................................... 96

Events ...................................................................................................................................... 100

Example ................................................................................................................................... 102

MapOptions Object ...................................................................................................................... 103

Properties ................................................................................................................................. 103

Example ................................................................................................................................... 108

MapTypeId Enumeration ............................................................................................................. 109

Constants ................................................................................................................................. 109

Example ................................................................................................................................... 109

See Also ................................................................................................................................... 110

Module Loading Methods ............................................................................................................ 110

Methods .................................................................................................................................... 110

Example ................................................................................................................................... 112

See Also ................................................................................................................................... 114

MouseEventArgs Object .............................................................................................................. 114

Properties ................................................................................................................................. 114

Methods .................................................................................................................................... 115

Example ................................................................................................................................... 115

PixelReference Enumeration ....................................................................................................... 117

Constants ................................................................................................................................. 117

Methods .................................................................................................................................... 117

Example ................................................................................................................................... 117

Point Class ................................................................................................................................... 119

Constructor ............................................................................................................................... 119

Properties ................................................................................................................................. 119

Static Methods .......................................................................................................................... 120

Methods .................................................................................................................................... 120

Example ................................................................................................................................... 120

Polygon Class (AJAX) ................................................................................................................. 122

Constructor ............................................................................................................................... 122

Methods .................................................................................................................................... 122

Events ...................................................................................................................................... 123

Example ................................................................................................................................... 124

PolygonOptions Object ................................................................................................................ 126

Properties ................................................................................................................................. 126

Example ................................................................................................................................... 127

Polyline Class .............................................................................................................................. 128

Constructor ............................................................................................................................... 128

Methods .................................................................................................................................... 128

Events ...................................................................................................................................... 130

Example ................................................................................................................................... 130

PolylineOptions Object ................................................................................................................ 132

Properties ................................................................................................................................. 132

Example ................................................................................................................................... 133

Position Class .............................................................................................................................. 134

Properties ................................................................................................................................. 134

See Also ................................................................................................................................... 134

PositionCircleOptions Object ....................................................................................................... 135

Properties ................................................................................................................................. 135

Example ................................................................................................................................... 135

PositionError Class ...................................................................................................................... 137

Properties ................................................................................................................................. 137

See Also ................................................................................................................................... 137

PositionOptions Object ................................................................................................................ 137

Properties ................................................................................................................................. 138

Example ................................................................................................................................... 139

Pushpin Class (AJAX) ................................................................................................................. 141

Constructor ............................................................................................................................... 141

Methods .................................................................................................................................... 141

Events ...................................................................................................................................... 143

Example ................................................................................................................................... 144

PushpinOptions Object ................................................................................................................ 145

Properties ................................................................................................................................. 145

Example ................................................................................................................................... 146

TileLayer Class ............................................................................................................................ 148

Constructor ............................................................................................................................... 148

Methods .................................................................................................................................... 148

Events ...................................................................................................................................... 149

Example ................................................................................................................................... 149

See Also ................................................................................................................................... 151

TileLayerOptions Object .............................................................................................................. 151

Properties ................................................................................................................................. 151

Example ................................................................................................................................... 152

See Also ................................................................................................................................... 154

TileSource Class.......................................................................................................................... 154

Constructor ............................................................................................................................... 154

Methods .................................................................................................................................... 154

Example ................................................................................................................................... 155

See Also ................................................................................................................................... 156

TileSourceOptions Object ............................................................................................................ 156

Properties ................................................................................................................................. 156

Example ................................................................................................................................... 157

See Also ................................................................................................................................... 159

ViewOptions Object ..................................................................................................................... 159

Properties ................................................................................................................................. 159

Remarks ................................................................................................................................... 160

Example ................................................................................................................................... 160

Microsoft.Maps.Directions API Reference ................................................................................... 162

In This Section .......................................................................................................................... 162

BusinessDetails Class ................................................................................................................. 163

Properties ................................................................................................................................. 163

BusinessDisambiguationSuggestion Class ................................................................................. 164

Properties ................................................................................................................................. 164

Example ................................................................................................................................... 165

See Also ................................................................................................................................... 168

DirectionsErrorEventArgs Object ................................................................................................. 168

Properties ................................................................................................................................. 168

Example ................................................................................................................................... 168

DirectionsEventArgs Object ......................................................................................................... 171

Properties ................................................................................................................................. 171

Example ................................................................................................................................... 171

DirectionsManager Class ............................................................................................................ 173

Constructor ............................................................................................................................... 173

Methods .................................................................................................................................... 173

Events ...................................................................................................................................... 177

Example ................................................................................................................................... 179

DirectionsRenderOptions Object ................................................................................................. 181

Properties ................................................................................................................................. 181

DirectionsRequestOptions Object ............................................................................................... 183

Properties ................................................................................................................................. 183

DirectionsStep Class ................................................................................................................... 185

Properties ................................................................................................................................. 185

DirectionsStepEventArgs Object ................................................................................................. 186

Properties ................................................................................................................................. 186

DirectionsStepRenderEventArgs Object ..................................................................................... 187

Properties ................................................................................................................................. 187

DirectionsStepWarning Class ...................................................................................................... 188

Properties ................................................................................................................................. 188

DirectionsStepWarningType Enumeration .................................................................................. 188

Constants ................................................................................................................................. 188

Disambiguation Class .................................................................................................................. 189

Properties ................................................................................................................................. 189

Example ................................................................................................................................... 190

See Also ................................................................................................................................... 193

DistanceUnit Enumeration (AJAX) .............................................................................................. 193

Constants ................................................................................................................................. 193

LocationDisambiguationSuggestion Class .................................................................................. 193

Properties ................................................................................................................................. 193

Example ................................................................................................................................... 194

See Also ................................................................................................................................... 197

ManeuverType Enumeration (AJAX) ........................................................................................... 197

Constants ................................................................................................................................. 197

ResetDirectionsOptions Object ................................................................................................... 197

Properties ................................................................................................................................. 197

Route Class (AJAX) ..................................................................................................................... 198

Properties ................................................................................................................................. 198

RouteAvoidance Enumeration ..................................................................................................... 198

Constants ................................................................................................................................. 198

RouteIconType Enumeration ....................................................................................................... 199

Constants ................................................................................................................................. 199

RouteLeg Class (AJAX) ............................................................................................................... 200

Properties ................................................................................................................................. 200

Example ................................................................................................................................... 201

RouteMode Enumeration ............................................................................................................. 203

Constants ................................................................................................................................. 203

RouteOptimization Enumeration (AJAX) ..................................................................................... 203

Constants ................................................................................................................................. 203

RoutePath Class (AJAX) ............................................................................................................. 204

Properties ................................................................................................................................. 204

RouteResponseCode Enumeration ............................................................................................. 205

Constants ................................................................................................................................. 205

RouteSelectorEventArgs Object .................................................................................................. 206

Properties ................................................................................................................................. 207

RouteSelectorRenderEventArgs Object ...................................................................................... 207

Properties ................................................................................................................................. 207

RouteSubLeg Class ..................................................................................................................... 207

Properties ................................................................................................................................. 208

RouteSummary Class (AJAX) ..................................................................................................... 208

Properties ................................................................................................................................. 208

Example ................................................................................................................................... 209

RouteSummaryRenderEventArgs Object .................................................................................... 211

Properties ................................................................................................................................. 211

TimeType Enumeration ............................................................................................................... 212

Constants ................................................................................................................................. 212

TransitLine Class ......................................................................................................................... 212

Properties ................................................................................................................................. 212

TransitOptions Object .................................................................................................................. 213

Properties ................................................................................................................................. 213

Waypoint Class (AJAX) ............................................................................................................... 213

Constructor ............................................................................................................................... 214

Methods .................................................................................................................................... 214

Events ...................................................................................................................................... 216

WaypointEventArgs Object .......................................................................................................... 216

Properties ................................................................................................................................. 216

WaypointOptions Object .............................................................................................................. 216

Properties ................................................................................................................................. 216

WaypointRenderEventArgs Object .............................................................................................. 217

Properties ................................................................................................................................. 217

Microsoft.Maps.Traffic API Reference ......................................................................................... 218

In This Section .......................................................................................................................... 218

TrafficLayer Class ........................................................................................................................ 218

Constructor ............................................................................................................................... 218

Methods .................................................................................................................................... 218

Example ................................................................................................................................... 219

Microsoft.Maps.VenueMaps API Reference ............................................................................... 220

In This Section .......................................................................................................................... 220

Floor Class ................................................................................................................................... 221

Properties ................................................................................................................................. 221

Example ................................................................................................................................... 221

Footprint Class ............................................................................................................................. 223

Properties ................................................................................................................................. 224

Example ................................................................................................................................... 224

Metadata Class ............................................................................................................................ 226

Properties ................................................................................................................................. 226

Example ................................................................................................................................... 227

NearbyVenue Class ..................................................................................................................... 229

Properties ................................................................................................................................. 229

Example ................................................................................................................................... 229

NearbyVenueOptions Object ....................................................................................................... 231

Properties ................................................................................................................................. 231

Example ................................................................................................................................... 231

Polygon Class (Venue Map) ........................................................................................................ 233

Properties ................................................................................................................................. 233

Primitive Class ............................................................................................................................. 233

Properties ................................................................................................................................. 233

Methods .................................................................................................................................... 234

Example ................................................................................................................................... 234

VenueMap Class ......................................................................................................................... 236

Properties ................................................................................................................................. 236

Methods .................................................................................................................................... 237

Events ...................................................................................................................................... 238

Example ................................................................................................................................... 239

VenueMapCreationOptions Object .............................................................................................. 241

Properties ................................................................................................................................. 241

Example ................................................................................................................................... 242

VenueMapFactory Class ............................................................................................................. 243

Constructor ............................................................................................................................... 243

Methods .................................................................................................................................... 244

Example ................................................................................................................................... 244

Bing Maps AJAX Control 7.0 Supported Browsers ..................................................................... 246

Supported Browsers ................................................................................................................. 246

Bing Maps AJAX Control 7.0 Developer Resources ................................................................... 247

Developer Resources ............................................................................................................... 247

Account Issues ......................................................................................................................... 247

Licensing Questions ................................................................................................................. 247

11

Bing Maps AJAX Control, Version 7.0

Bing Maps™ is an online mapping service that enables users to search, discover, explore, plan,

and share information about specific locations. By using enhanced road maps, labeled aerial

photo views, and low-angle high-resolution aerial photos, Bing Maps AJAX Control 7.0, in

conjunction with the Bing Maps REST Services, provides unique opportunities for developers to

incorporate both location and local search features into their Web applications.

The Bing Maps AJAX Control 7.0 software development kit (SDK) consists of a complete set of

reference topics that cover the Bing Maps AJAX Control 7.0 application programming interface

(API). For extra code snippets and feature samples, the Bing Maps AJAX Control 7.0 Interactive

SDK is also available.

If you are reading this help file online, you can download either the CHM or PDF version of this

SDK for offline viewing.

If you are looking for documentation for the legacy AJAX Map Control, see Bing Maps AJAX

Control, Version 6.3 SDK.

In This Section Getting Started with the 7.0 Map Control

What's New in the AJAX Map Control

Developing with the 7.0 Map Control

API Reference

Supported Browsers

Developer Resources

See Also Terms and Conditions

Getting Started with the 7.0 Map Control

The Bing Maps AJAX Control 7.0 is a JavaScript control that contains the objects, methods, and

events that allow you to display maps powered by Bing Maps on your Web site. The sections in

this topic describe the steps you need to take to start using the Bing Maps AJAX Control 7.0.

http://bing.com/maps

http://msdn.microsoft.com/en-us/library/ff701713.aspx

http://go.microsoft.com/fwlink/?LinkID=217283&clcid=0x409


http://www.microsoft.com/downloads/details.aspx?FamilyID=4a8e5de3-51af-40c3-b35d-d5e91da2effa

http://www.microsoft.com/downloads/details.aspx?FamilyID=9477f0fd-da1d-4822-bb67-de4cda7c7895

http://msdn.microsoft.com/en-us/library/bb429619.aspx

http://msdn.microsoft.com/en-us/library/bb429619.aspx

http://go.microsoft.com/fwlink?LinkID=66121

12

Create a Bing Maps Account and Get a Key Before you begin developing your application, you need to create a developer account on the

Bing Maps Account Center. A Bing Maps Developer Account allows you to create a Bing Maps

Key to use in your map application. Getting a key is described in Getting a Bing Maps Key.

When the Bing Maps AJAX Control 7.0 is loaded with a valid Bing Maps Key, Bing Maps

counts sessions. A session begins with the load of the Bing Maps AJAX Control 7.0 into a

user‟s browser and includes all Bing Maps AJAX Control 7.0 interactions until the

browser is closed or the user moves to a different page. Detailed information about Bing

Maps usage reports is found in Viewing Bing Maps Usage Reports.

Get Familiar with the Bing Maps AJAX 7.0 Control The Developing with the 7.0 Map Control section of this SDK contains topics that describe how to

use the features provided by the AJAX map control.

What's New in the AJAX Map Control

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

New Features This release of the map control includes the following new features:

Calculate driving directions Use the new Microsoft.Maps.Directions module to easily

calculate directions and display a route on your map.

Display a venue map Discover and display maps for nearby venues such as malls and

shopping centers using the Microsoft.Maps.VenueMaps module.

Show current traffic Show or hide current traffic on the map using the

Microsoft.Maps.Traffic module.

Set polyline and polygon stroke dash To further customize your shapes, use the new

property strokeDashArray of the PolylineOptions Object and PolygonOptions Object.

New tile layer property and event Ensure the best performance of your tile layer during

animation by modifying the new animationDisplay property of the TileLayerOptions Object.

Also, determine when your tile layer is fully downloaded using the new tiledownloadcomplete

event.

New map options For increased flexibility, new options showBreadcrumb, disableBirdseye,

disablePanning, and disableZooming have been added to the MapOptions Object.

http://www.bingmapsportal.com/



13

Developing with the 7.0 Map Control

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

In This Section Loading the AJAX Map Control

Setting Map Control Parameters

Changing the Map View

Adding Entities to the Map

Customizing Your Pushpins

Displaying Location Search Results Using the REST Services

Calculating Directions Using the Directions Module

Working with Tile Layers

Using Events in the AJAX Control

Returning a Localized Map

Building Your Own Module

Loading the AJAX Map Control

This topic describes how to load the Bing Maps AJAX Control 7.0 into your Web page to display a

map. This is the first step you need to take for any page that uses the map control.

Displaying the Default Map Displaying the default map, which includes all of the navigation functionality, consists of the

following steps:

1. At the top of the HTML page add the following DOCTYPE declaration.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

2. In the header section of an HTML page, add a META element with the charset attribute set

to "utf-8", as follows.

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

8"/>

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.

14

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


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 cross-

browser 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">

15

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.


var map = new

Microsoft.Maps.Map(document.getElementById("mapDiv"),

{credentials:"Your Bing Maps Key"});

</script>

The full code is below.



<html>

<head>

<title></title>

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

<script type="text/javascript"

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


function GetMap()

{

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


}

</script>


16

</head>


<div id='mapDiv' style="position:absolute; width:400px; height:400px;"></div>

</body>

</html>

Customizing the Map When Loading You can also specify other options when the map is first loaded, such as the location, zoom level,

and the imagery of the map. To do this, pass in MapOptions or ViewOptions to the Map

constructor. The code below sets the imagery to Aerial.

var mapOptions = {

credentials: "Your Bing Maps Key",

mapTypeId: Microsoft.Maps.MapTypeId.aerial

}

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

Example The following code shows a complete Web page that loads a map. Valid map types are found in

the MapTypeId Enumeration topic.



<html>

<head>

<title></title>





function GetMap()

{


17

{credentials: "Your Bing Maps Key",

center: new Microsoft.Maps.Location(45.5, -122.5),

mapTypeId: Microsoft.Maps.MapTypeId.road,

zoom: 7});

}

</script>

</head>


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

</body>

</html>

Setting Map Control Parameters

This topic describes map control parameters.

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

Parameter Values Description

v 7.0 Specifies a major API version.

The default value is the latest

version, which is 7.0.

s 0, 1 Specifies whether to use SSL.

Set this value equal to 1 to use

SSL. The default value is 0.

mkt See the Returning a

Localized Map topic for a list

of values.

Specifies the market to use,

which defines the language Bing

Maps AJAX Control 7.0 uses.

The default value is "en-US"

(English).

onscriptload A string specifying a function

name.

Specifies the name of a

JavaScript function to call when

the map control script is loaded.

The name must contain only

alphanumeric characters.

18

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.


src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0&mkt=it-IT">

</script>

See Also Loading the AJAX Map Control


Changing the Map View

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

Setting the Initial Map View You can set the map view when you first load the map you can use any of the options available in

the MapOptions Object or ViewOptions Object.

The code below initializes the map with a specific view. The imagery displayed is set to Bird‟s eye

using the mapTypeId option. Valid map type IDs are listed in the MapTypeId Enumeration topic.



19

<html>

<head>

<title></title>

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




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

}


}

</script>

</head>



</body>

</html>

Changing the Map View If you want to change the map after it has loaded, use the setView method of the Map Class. The

ViewOptions Object contains available options that can be set.

The example below sets the map view to the specified zoom level.



20

<html>

<head>

<title></title>





var map = null;

function GetMap()

{

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

"Your Bing Maps Key", mapTypeId: Microsoft.Maps.MapTypeId.road});

}

function SetZoom()

{

var zoomLevel = parseInt(document.getElementById('txtZoom').value);

map.setView({zoom:zoomLevel});

}

</script>

</head>



Zoom Level:

<input id="txtZoom" type="text" value="1"/>

<input id="btnZoom" type="button" value="Click to set the zoom level"

onclick="SetZoom();"/>

</body>

21

</html>

To set the boundaries of the view instead of centering on a point, use the bounds option as shown

in the code below.



<html>

<head>

<title></title>





var map = null;

function GetMap()

{


"Your Bing Maps Key"});

var viewBoundaries = Microsoft.Maps.LocationRect.fromLocations(new

Microsoft.Maps.Location(47.618594, -122.347618), new Microsoft.Maps.Location(47.620700, -

122.347584), new Microsoft.Maps.Location(47.622052, -122.345869));

map.setView({ bounds: viewBoundaries});

}

</script>

</head>


22


</body>

</html>

Adding Entities to the Map

This topic describes how to add entities to the map. An Entity can be any one of the following

types: Polygon, Polyline, Pushpin, TileLayer, or EntityCollection. Information about working with

tile layers is in the Working with Tile Layers topic.

Adding Single Entities to the Map To add a pushpin, polygon, or polyline to the map, simply create your object then add the entity to

the entities property of the map.

Adding a Pushpin

The following code adds a pushpin to the center of the map with the label “1”.



<html>

<head>

<title></title>



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


function GetMap()

{

// Initialize the map



// Retrieve the location of the map center

23

var center = map.getCenter();

// Add a pin to the center of the map

var pin = new Microsoft.Maps.Pushpin(center, {text: '1'});

map.entities.push(pin);

}

</script>

</head>



</body>

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



<html>

<head>

<title></title>





var map = null;

function GetMap()

{


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

{credentials:"Bing Maps Key"});

24

// Define the pushpin location

var loc = new Microsoft.Maps.Location(47.592, -122.332);

// Add a pin to the map

var pin = new Microsoft.Maps.Pushpin(loc);


// Center the map on the location

map.setView({center: loc, zoom: 10});

}

</script>

</head>


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



<html>

<head>

<title></title>




25


function GetMap()

{


var map = new

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

// Create a polygon

var vertices = new Array(new Microsoft.Maps.Location(20,-20), new

Microsoft.Maps.Location(20,20), new Microsoft.Maps.Location(-20,20), new

Microsoft.Maps.Location(-20,-20), new Microsoft.Maps.Location(20,-20));

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

var polygon = new Microsoft.Maps.Polygon(vertices,{fillColor: polygoncolor,

strokeColor: polygoncolor});

// Add the polygon to the map

map.entities.push(polygon);

}

</script>

</head>



</body>

</html>

Adding Multiple Entities to the Map If you want to add multiple entities to the map at one time, first create an EntityCollection then

add this collection to the map. The code below adds a polygon with pushpins at its corners.



<html>

<head>

26

<title></title>





function GetMap()

{




// 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);




// 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));




27

// Add the shape to the map

map.entities.push(polygonWithPins)

}

</script>

</head>



</body>

</html>

Changing Entities on the Map Once entities have been added to the map, you can use the methods of the map entities

collection to change and manipulate those entities. The code implements a button to change the

color of a shape on the map.



<html>

<head>

<title></title>





var map = null;

// Define colors

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

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

28

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

function GetMap()

{


map = new






var location4 = new Microsoft.Maps.Location(-20, -20);

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

// Create some shapes

var triangleVertices = new Array(location1, location2, location5, location1);

var triangle = new Microsoft.Maps.Polygon(triangleVertices, { fillColor:

blue, strokeColor: blue });

var squareVertices = new Array(location1, location2, location3, location4,

location1);

var square = new Microsoft.Maps.Polygon(squareVertices,{fillColor: purple,

strokeColor:purple});

// Add the shapes to the map

map.entities.push(triangle);

map.entities.push(square);

}

function ChangePolygonColor()

{

29

// Get the map square entity. We know square was the last entity added,

// so we can calculate the index.

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

// Get the current color

var currentColor = mapSquare.getFillColor();

if((currentColor.toString()) == (purple.toString()))

{

// Change it to green

mapSquare.setOptions({fillColor: green, strokeColor:green});

}

else

{

// Change it back to purple

mapSquare.setOptions({fillColor:purple, strokeColor:purple});

}

}

</script>

</head>



<input id="btnChangeColor" type="button" value="Change Polygon Color"

onclick="ChangePolygonColor();"/>

</body>

</html>

Customizing Your Pushpins

The Bing Maps AJAX Control, Version 7.0 provides flexible pushpin functionality. Use options

provided in the PushpinOptions Object to customize your pushpins.

This topic describes how to customize your pushpin icon as well as how to create a pushpin info

box.

30

Customizing Your Pushpin Icon If you do not want to use the default pushpin icon, you can set the icon property of the

PushpinOptions to the image you want to use instead.

This example uses the image below, named “BluePushpin.png”, as the pushpin icon.



<html>

<head>

<title></title>





var map = null;

function GetMap()

{






// 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});

31


}

</script>

</head>



</body>

</html>

Creating a Pushpin Infobox The Bing Maps AJAX Control, Version 7.0 has built-in pushpin info box functionality which you

can customize to suit the needs of your application. To create an info box, use the Infobox and

InfoboxOptions types.

The example below shows how to display an info box when a pushpin is clicked.



<html>

<head>

<title></title>





var map = null;

var pinInfobox = null;

function GetMap()

32

{








// Create the infobox for the pushpin

pinInfobox = new Microsoft.Maps.Infobox(pin.getLocation(),

{title: 'My Pushpin',

description: 'This pushpin is located at (0,0).',

visible: false,

offset: new Microsoft.Maps.Point(0,15)});

// Add handler for the pushpin click event.

Microsoft.Maps.Events.addHandler(pin, 'click', displayInfobox);

// Hide the infobox when the map is moved.

Microsoft.Maps.Events.addHandler(map, 'viewchange', hideInfobox);

// Add the pushpin and infobox to the map


map.entities.push(pinInfobox);

}

function displayInfobox(e)

{

pinInfobox.setOptions({ visible:true });

33

}

function hideInfobox(e)

{

pinInfobox.setOptions({ visible: false });

}

</script>

</head>



</body>

</html>

Displaying Location Search Results Using the REST Services

The Bing Maps AJAX Control, version 7.0 does not have built in functionality to return find results,

but you can easily use the Bing Maps REST Services to geocode locations that you can then

display on the map.

Initialize the Map Before you add geocoding functionality, initialize the map using the following code.



<html>

<head>

<title></title>






34

var map = null;

function GetMap()

{


map = new

Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Your Bing Maps Key",

mapTypeId:Microsoft.Maps.MapTypeId.road});

}

</script>

</head>



</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);

}

35

Make a Geocode REST Request Next, make a geocode request to the Bing Maps REST Services using the value in the txtQuery

input box and the credentials.

The Bing Maps REST Services can return an XML or JSON response object. For JavaScript

code, JSON is more appropriate, so set output=JSON. This means that you need to also set a

jsonp callback function name. In this sample the callback function is named GeocodeCallback.

Finally, since you do not know if the text provided is a place name or an address, supply the

locationQuery parameter and set it to the value of the txtQuery text box. Your REST geocode

request looks like this:

var geocodeRequest = "http://dev.virtualearth.net/REST/v1/Locations/" +

document.getElementById('txtQuery').value + "?output=json&jsonp=GeocodeCallback&key=" +

credentials;

Now add script to make the REST request.

function MakeGeocodeRequest(credentials)

{



credentials;

CallRestService(geocodeRequest);

}

function CallRestService(request)

{

var script = document.createElement("script");

script.setAttribute("type", "text/javascript");

script.setAttribute("src", request);

document.body.appendChild(script);

}

function GeocodeCallback(result)

{

// Do something with the result

}

36

Display the Results Finally, add code to the GeocodeCallback function to set the map view to the found location and

add a pushpin at that location. The final code is shown below.



<html>

<head>

<title></title>





var map = null;

function GetMap()

{


map = new


mapTypeId:Microsoft.Maps.MapTypeId.road});

}

function ClickGeocode(credentials)

{

map.getCredentials(MakeGeocodeRequest);

}

function MakeGeocodeRequest(credentials)

{

37



credentials;

CallRestService(geocodeRequest);

}

function GeocodeCallback(result)

{

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

if (result &&

result.resourceSets &&

result.resourceSets.length > 0 &&

result.resourceSets[0].resources &&

result.resourceSets[0].resources.length > 0)

{

// Set the map view using the returned bounding box

var bbox = result.resourceSets[0].resources[0].bbox;


Microsoft.Maps.Location(bbox[0], bbox[1]), new Microsoft.Maps.Location(bbox[2],

bbox[3]));


// 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);

}

}


{

38





}

</script>

</head>



<input id="txtQuery" type="text" value="Portland"/>

<input type="button" value="Geocode" onclick="ClickGeocode()"/>

</body>

</html>

Getting Route Directions Using the REST Services

The latest release of the Bing Maps AJAX Control 7.0 provides directions functionality in

the Microsoft.Maps.Directions module. This module allows you to easily customize,

calculate, and display directions and a route on your web site without needing to use

REST services. Get started by going to the DirectionsManager Class topic, which

contains information about the calculateDirections method and sample code.

This topic describes how to use the Bing Maps REST Services to calculate and display a route on

the map.

Initialize the Map Before you add route functionality, initialize the map using the following code.



<html>

<head>

<title></title>


39





var map = null;

function GetMap()

{


map = new


mapTypeId: Microsoft.Maps.MapTypeId.road });

}

</script>

</head>



</body>

</html>

Construct the Route Request Next, add input controls and construct the Bing Maps REST Services Route request.

In this example, a route is calculated between a specified start and end point. Add two text boxes

and a button to initiate the route calculation.

<input id="txtStart" type="text" value="Seattle"/>

<input id="txtEnd" type="text" value="Portland"/>

<input type="button" value="Calculate Route" onclick="ClickRoute()"/>

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

40

var routeRequest = "http://dev.virtualearth.net/REST/v1/Routes?wp.0=" +

document.getElementById('txtStart').value + "&wp.1=" +

document.getElementById('txtEnd').value +

"&routePathOutput=Points&output=json&jsonp=RouteCallback&key=" + credentials;

Display the Results Finally, add code to make the route request when the button is clicked, and add code to the

RouteCallback function to set the map view and draw the route. The final code is shown below.



<html>

<head>

<title></title>





var map = null;

function GetMap()

{


map = new



}

function ClickRoute(credentials)

{

41

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;


Microsoft.Maps.Location(bbox[0], bbox[1]), new Microsoft.Maps.Location(bbox[2],

bbox[3]));


// Draw the route

42

var routeline = result.resourceSets[0].resources[0].routePath.line;

var routepoints = new Array();

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

routepoints[i]=new

Microsoft.Maps.Location(routeline.coordinates[i][0], routeline.coordinates[i][1]);

}

// Draw the route on the map

var routeshape = new Microsoft.Maps.Polyline(routepoints,

{strokeColor:new Microsoft.Maps.Color(200,0,0,200)});

map.entities.push(routeshape);

}

}


{





}

</script>

</head>



<input id="txtStart" type="text" value="Seattle"/>

<input id="txtEnd" type="text" value="Portland"/>

<input type="button" value="Calculate Route" onclick="ClickRoute()"/>

43

</body>

</html>

Working with Tile Layers

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

Adding a Tile Layer A tile layer is a valid map entity, so after you construct your layer, you can add it to the map using

the push method of the map entities collection. The code below adds a custom tile layer to the

map.



<html>

<head>

<title></title>





function GetMap()

{


var map = new


center:new Microsoft.Maps.Location(48.03,-122.4), zoom:12, mapTypeId:

Microsoft.Maps.MapTypeId.road });

try

{

// Create the tile layer source

44

var tileSource = new Microsoft.Maps.TileSource({uriConstructor:

'http://www.microsoft.com/maps/isdk/ajax/layers/lidar/{quadkey}.png'});

// Construct the layer using the tile source

var tilelayer= new Microsoft.Maps.TileLayer({ mercator: tileSource,

opacity: .7 });

// Push the tile layer to the map

map.entities.push(tilelayer);

}

catch(err)

{

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

}

}

</script>

</head>



</body>

</html>

Using Events in the AJAX Control

The Bing Maps AJAX Control 7.0 provides many events to allow your application to respond to

user actions. The EntityCollection, Map, Pushpin, Polyline, and Polygon classes all have event

members. The code examples in this topic show how to use the Map click event and the

EntityCollection entityadded event.

Example The example below shows how to use the Map click event to display the coordinate values of

the clicked point in a text box.

45



<html>

<head>

<title></title>





var map = null;

function GetMap()

{




//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;

}

46

}

</script>

</head>


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



<html>

<head>

<title></title>





var map = null;

var noPins = true;

function GetMap()

{




47

// Add a handler for the map click event.

Microsoft.Maps.Events.addHandler(map, 'click', addPin);

// Add a handler to function that will grey out

// other pins in the collection when a new one is added

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

}

function addPin(e) {






}

}

function shadePins(e) {

if (noPins) {

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

noPins = false;

}

else

{

var pin = null;

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

48

// 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>



<b>Click the map to add a pushpin at that point.</b><br>

</body>

</html>


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

Setting the Culture By default the map labels and the navigation control text are provided in the culture English-

United States (en-US). However, the map control culture can be changed by adding the mkt

parameter to the map control reference, as in the following example, which sets the culture to

French-France (fr-FR).


src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0&mkt=fr-

fr"></script>

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

values for the mkt parameter.

49

Language - Country/Region Culture

Dutch - Belgium nl-BE

English - Canada en-CA

English - India en-IN

English - United Kingdom en-GB

English - United States en-US

French - Canada fr-CA

French - France fr-FR

German - Germany de-DE

Italian - Italy it-IT

Japanese - Japan ja-JP

Spanish - Mexico es-MX

Spanish - Spain es-ES

Spanish – United States es-US

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

Building Your Own Module

The Bing Maps AJAX Control 7.0 allows you to easily register and load your own script modules.

This topic describes how to create a simple module.

Develop Your Module Begin by developing your module. The sample module below takes a map object as its

constructor and exposes a method to draw a red arrow pointing to a given location.

// arrowmodule.js

function ArrowModule(map)

{

// Use the given location to draw an arrow pointing to that spot

50

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);


location.longitude-5);







points[6] = new Microsoft.Maps.Location(location.latitude, location.longitude-

10);

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.

51

Register and Load Your Module After you have created your module and hosted it, register it within your map control application

using the Microsoft.Maps.registerModule method.

Microsoft.Maps.registerModule("ArrowModule", "http://example.com/arrowmodule.js");

Next, load your module using the Microsoft.Maps.loadModule method, specifying the function

to call when the module is loaded.

Microsoft.Maps.loadModule("ArrowModule", { callback: myModuleLoaded });

Use Your Module Finally, use the functions provided by your module in your map control code. The sample code

below uses the drawRedArrow method of the ArrowModule to draw an arrow pointing to the

center of the map.



<html>

<head>

<title></title>





var map;

function myModuleLoaded()

{

// When the module is fully loaded, then this function is called.

// Now you can initialize a module object and use the module function to

// draw an arrow pointing to the center of the map.

var arrowModule = new ArrowModule(map);

arrowModule.drawRedArrow(map.getCenter());

}

52

function GetMap()

{


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>


<div id='mapDiv' style="position:relative; width:400px;

height:400px;"></div>

</body>

</html>

See Also Module Loading Methods

Microsoft.Maps API Reference

This section contains reference documentation for the Microsoft.Maps API, which contains the

core types of the Bing Maps AJAX Control 7.0.

53

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


Polyline Class

PolylineOptions Object

Polygon Class

PolygonOptions Object

Pushpin Class

PushpinOptions Object

TileLayer Class

TileLayerOptions Object

TileSource Class

TileSourceOptions Object

54

User Location

Coordinates Class

GeoLocationProvider Class

Position Class

PositionCircleOptions Object

PositionError Class

PositionOptions Object

Dynamic Module Loading

Module Loading Methods

AltitudeReference Enumeration

Defines the reference point from which the altitude is measured.

Constants

Name Description

ground The altitude is measured from the ground level.

ellipsoid The altitude is measured from the WGS 84

ellipsoid of the Earth.

Methods

Name Definition Return Value Description

isValid isValid(reference:AltitudeReference) boolean Determines if the

specified reference is a

supported

AltitudeReference.

Example <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"


<html>

55

<head>

<title></title>





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,


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"}));

}

</script>

</head>


56


</body>

</html>

AnimationVisibility Enumeration

Defines a tile layer‟s 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.

hide The tile layer is not displayed during animation.

show The tile layer is displayed during animations.

This option may impact performance on older

browsers.

Color Class

Represents a color.

Constructor

Name Definition Description

Color Color(a:number, r:number,

g:number, b:number)

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.

57

Properties

Name Type Description

a number The opacity of the color. The

range of valid values is 0 to 255.

r number The red value of the color. The


g number The green value of the color.

The range of valid values is 0 to

255.

b number The blue value of the color. The


Static Methods


clone clone(color:Color) Color Creates a copy of the

Color object.

fromHex fromHex(hex:string) Color Converts the specified

hex string to a Color.

Methods


clone clone() Color Returns a copy of the

Color object.

getOpacity getOpacity() number Returns the opacity of

the Color as a value

between 0 (a=0) and 1

(a=255).

toHex toHex() string Converts the Color into

a 6-digit hex string.

Opacity is ignored. For

example, a Color with

58


values (255,0,0,0) is

returned as hex string

#000000.

toString toString() string Converts the Color

object to a string.



<html>

<head>

<title></title>





var map = null;

function GetMap()

{


map = new







59


// 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)});


map.entities.push(line);

}

function SetPolygonColor()

{

// Get the polyline entity.

var mapLine = map.entities.get(0);

// Set the option values

var opacity = document.getElementById('txtA').value;

var rValue = document.getElementById('txtR').value;

var gValue = document.getElementById('txtG').value;

var bValue = document.getElementById('txtB').value;

var lineWidth = document.getElementById('txtWidth').value;

// Verify input values and set the opacity, color,

// and width of the line.

if (((opacity < 0) || (opacity > 255)) ||

((rValue < 0) || (rValue > 255)) ||

((gValue < 0) || (gValue > 255)) ||

((bValue < 0) || (bValue > 255)) )

{

60

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>



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


accuracy number The accuracy, in meters, of

the latitude and longitude

61


values.

altitude number The altitude of the location.

altitudeAccuracy number The accuracy, in meters, of

the altitude value.

heading number The direction of travel of the

hosting device.

latitude number The latitude of the location.

longitude number The longitude of the location.

speed number 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


EntityCollection EntityCollection(options?:EntityCollectionOptions) Initializes a new

instance of the

EntityCollection

class.

Methods

62

Name Definition Return

Value

Description

clear clear() None Removes all

entities from the

collection.

get get(index:number) Entity* Returns the entity

at the specified

index in the

collection.

getLength getLength() number Returns the

number of entities

in the collection.

getVisible getVisible() boolean Returns whether

the entity

collection is visible

on the map.

getZIndex getZIndex() number Gets the z-index

of the entity

collection with

respect to other

items on the map.

indexOf indexOf(entity:Entity*) number Returns the index

of the specified

entity in the

collection. If the

entity is not found

in the collection, -1

is returned.

insert insert(entity:Entity*, index:number) None Inserts the

specified entity

into the collection

at the given index.

pop pop() Entity* Removes the last

entity from the

collection and

returns it.

push push(entity:Entity*) None Adds the specified

entity to the last

position in the

63


Value

Description

collection.

remove remove(entity:Entity*) Entity* Removes the

specified entity

from the collection

and returns it.

removeAt removeAt(index:number) Entity* Removes the

entity at the

specified index

from the collection

and returns it.

setOptions setOptions(options:EntityCollectionOptions) None Sets the options

for the entity

collection.

toString toString() string Converts the

EntityCollection

object to a string.

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

or EntityCollection.

Events

Name Arguments Description

entityadded object: {collection:

EntityCollection, entity:Entity*}

Occurs when one of the

following happens:

An entity is added to the

collection.

One of the entities of the

collection (such as another

entity collection) fires the

entityadded event.

For example, if collection #1

contains an entity, which is

another collection #2, then

when an entity is added to

collection #2, two entityadded

events are fired.

64


entitychanged object: {collection:



following happens:

The collection changes.

An entity of the

collection changes.




entitychanged event.




when an entity of collection #2

changes, two entitychanged

events are fired.

entityremoved object: {collection:



following happens:

An entity of the

collection is removed.




entityremoved event.




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.



<html>

<head>

65

<title></title>





var map = null;

var pinTotal = 0;

function GetMap()

{


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


// Add handler for the map click event - add a pin to the click location.


}



// Return the location where the map was clicked and create the pin.




// Attach a handler to the pin so that it is removed when it is clicked

Microsoft.Maps.Events.addHandler(pin, 'click', removePin);

66

// Add the pushpin


}

}

function removePin(e)

{

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

map.entities.removeAt(indexOfPinToRemove);

}

</script>

</head>



<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

67


visible boolean A Boolean indicating whether

the entity collection is visible on

the map.

zIndex number The z-index of the entity

collection with respect to other

items on the map.



<html>

<head>

<title></title>





var map = null;

function GetMap()

{


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.


}

68



// Return the location where the map was clicked and create the pin.




// Add the pushpin


}

}

function hideAllPins(){

// Hide all the entities on the map

map.entities.setOptions({visible:false});

}

function showAllPins(){

// Show all the entities on the map

map.entities.setOptions({visible:true});

}

</script>

</head>



<input type="button" value="Hide all pins" onclick="hideAllPins();"/>

<input type="button" value="Show all pins" onclick="showAllPins();"/>

</body>

69

</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


Value

Description

addHandler addHandler(target:object,

eventName:string,

handler:function)

object Attaches the handler for the event

that is thrown by the target. Use

the return object to remove the

handler using the removeHandler

method.

Microsoft.Maps.Events.addHandle

r(map, 'viewchangedend’,

function(e){ //Handle the

event });

addThrottledHan

dler

addThrottledHandler(target:o

bject, eventName:string,

handler:function,

throttleInterval:number)

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 hasHandler(target:object,

eventName:string)

boolea

n

Checks if the target has any

attached event handler.

invoke invoke(target:object,

eventName:string, args:object)

None Invokes an event on the target.

This causes all handlers for the

specified eventName to be called.

removeHandler removeHandler(handlerId:

object)

None Detaches the specified handler

from the event. The handlerId is

returned by the addHandler and

70


Value

Description

addThrottledHandler methods.



<html>

<head>

<title></title>





var map = null;

var infobox = null;

function GetMap()

{






// 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)});

71

// 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(infobox);

}

function showInfobox()

{

infobox.setOptions({visible:true});

}

function hideInfobox()

{

infobox.setOptions({visible:false});

}

</script>

</head>



</body>

</html>

GeoLocationProvider Class

Contains methods for obtaining and displaying the user‟s current location.

72

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

Constructor


GeoLocationProvider GeoLocationProvider(map:Map) Initializes a new instance of

the GeoLocationProvider

class.

Methods

Name Definition Retur

n

Value

Description

addAccuracyCircle addAccuracyCircle(center:Location,

radiusInMeters:number,

segments:number,

options:PositionCircleOptions)

None Renders a geo

location accuracy

circle on the map.

The accuracy

circle is created

with the center at

the specified

location, using the

given

radiusInMeters,

and with the

specified number

of segments for

the accuracy

circle polygon.

Additional options

are also available

to adjust the style

of the polygon.

cancelRequest cancelRequest() None Cancels the

processing of the

current

getCurrentPositio

http://dev.w3.org/geo/api/spec-source.html

73


n

Value

Description

n request. This

method prevents

the response from

being processed.

getCurrentPosition getCurrentPosition(options:PositionOptio

ns)

None Obtains the user‟s

current location

and displays it on

the map.

The

accuracy

of the

user

location

obtained

using this

method

varies

widely

dependin

g on the

desktop

browser

or mobile

device of

the

requestin

g client.

Desktop

users

may

experienc

e low

user

location

accuracy

(accuracy

circles

74


n

Value

Description

with large

radiuses),

while

mobile

user

location

accuracy

may be

much

greater (a

few

meters).

removeAccuracyCircl

e

removeAccuracyCircle() None Removes the

current geo

location accuracy

circle.



<html>

<head>

<title></title>





function GetMap()

{

75

// Set the map options

var mapOptions = {credentials:"Bing Maps Key"};



mapOptions);

// Initialize the location provider

var geoLocationProvider = new Microsoft.Maps.GeoLocationProvider(map);

// Get the user's current location

geoLocationProvider.getCurrentPosition();

}

</script>

</head>



</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


Infobox Infobox(location:Location, Initializes a new instance of

76


options?:InfoboxOptions) the Infobox class.

Methods


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.

getAnchor getAnchor() Point 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.

getDescription getDescription() string Returns the string that is printed

inside the infobox.

getHeight getHeight() number Returns the height of the

infobox.

getHtmlContent getHtmlContent() string Returns the infobox as HTML.

getId getId() string Returns the ID of the infobox.

getLocation getLocation() Location Returns the location on the map

where the infobox‟s anchor is

attached.

getOffset getOffset() number 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.

getOptions getOptions() InfoboxOpti Returns the infobox options.

77


Value

Description

ons

getShowCloseB

utton

getShowCloseButton() boolean Returns a boolean indicating

whether the infobox close button

is shown.

getShowPointer getShowPointer() boolean Returns a boolean indicating

whether the infobox is drawn

with a pointer.

getTitle getTitle() string Returns a string that is the title of

the infobox.

getTitleClickHan

dler

getTitleClickHandler() string Returns the name of the function

to call when the title of the

infobox is clicked.

getVisible getVisible() boolean 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.

getWidth getWidth() number Returns the width of the infobox.

getZIndex getZIndex() number Returns the z-index of the

infobox with respect to other

items on the map.

setHtmlContent setHtmlContent(content:stri

ng)

None 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 );

78


Value

Description

map.entities.push(defInfobox);

defInfobox.setHtmlContent('<di

v id="infoboxText"

style="background-color:White;

border-style:solid;border-

width:medium; border-

color:DarkOrange; min-

height: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

on)

None Sets the location on the map

where the anchor of the infobox

is attached.

setOptions setOptions(options:Infobox

Options)

None Sets options for the infobox.

toString toString() string Converts the Infobox object to a

string.

Events


click eventArgs:MouseEventArgs Occurs when the mouse is

used to click the infobox.

entitychanged object: {entity:Entity} Occurs when the location

of the infobox or any of the

infobox options change.

79


mouseenter eventArgs:MouseEventArgs Occurs when the mouse

cursor enters the area

covered by the infobox.

mouseleave eventArgs:MouseEventArgs Occurs when the mouse

cursor leaves the area

covered by the infobox.

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.



<html>

<head>

<title></title>





var map = null;

var pinInfobox = null;

function GetMap()

{


80







// 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(pinInfobox);

}

function displayInfobox(e)

{

pinInfobox.setOptions({ visible:true });

}

81

function hideInfobox(e)

{

pinInfobox.setOptions({ visible: false });

}

</script>

</head>



</html>

InfoboxOptions Object

Represents the options for an infobox.

Properties


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 string The string displayed inside the info

box.

height number The height of the info box. The

default value is 126.

82


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 string The ID associated with the info box.

location Location The location on the map where the

info box‟s anchor is attached.

offset Point 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.

showCloseButton boolean 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.

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

83


is anchored at the bottom left corner.

This property is ignored if custom

HTML is used to represent the info

box.

title string The title of the info box.

titleClickHandler string 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.

visible boolean 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.

width number The width of the info box. The default

value is 256.

zIndex number The z-index of the info box with

respect to other items on the map.



<html>

<head>

<title></title>





84

var map = null;

function GetMap()

{






// Create an info box

var infoboxOptions = {width:300,

height: 100,

title: "Information Box Title",

description: "This is the map.",

showPointer: false,

titleClickHandler: InfoboxHandler,

offset: new Microsoft.Maps.Point(-100,0)};

var myInfobox = new Microsoft.Maps.Infobox(center, infoboxOptions);

// Add the info box to the map

map.entities.push(myInfobox);

}

function InfoboxHandler()

{

alert("Infobox title was clicked!");

}

85

</script>

</head>



</html>

See Also Infobox Class

KeyEventArgs Object

Contains the arguments for keyboard events.

Properties


altKey boolean A boolean indicating if the ALT

key was pressed.

ctrlKey boolean A boolean indicating if the

CTRL key was pressed.

eventName string The event that occurred.

handled boolean 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.

keyCode string The ASCII character code that

identifies the keyboard key that

was pressed.

originalEvent object The original browser event.

shiftKey boolean A boolean indicating if the

SHIFT key was pressed.

http://en.wikipedia.org/wiki/ASCII

86



<html>

<head>

<title></title>





var map = null;

function GetMap()

{





Microsoft.Maps.Events.addHandler(map, 'keypress', addPin);

}


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

// If the 'p' key is pressed, add a pushpin to the center of the

// current map view.


87

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


}

}

</script>

</head>



<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 Map labels are not shown on top of imagery.

visible Map labels are shown on top of imagery.

Methods


isValid isValid(labelOverlay:LabelOverlay) boolean Determines whether

the specified

labelOverlay is a

supported

LabelOverlay.

88



<html>

<head>

<title></title>





function GetMap()

{

// Initialize the map options. In this case,

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

var mapOptions =

{

credentials:"Your Bing Maps Key",


center: new Microsoft.Maps.Location(37.794973,-122.393542),

zoom: 17,

labelOverlay: Microsoft.Maps.LabelOverlay.hidden

}

//Load the map


mapOptions );

}

</script>

</head>

89



</body>

</html>

Location Class (AJAX)

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

Constructor


Location Location(latitude:number,

longitude:number, altitude?:number,

altitudeReference?:AltitudeReference)


the Location class. The

altitude and

altitudeReference

parameters default to

undefined.

Properties


altitude number The altitude of the location.

altitudeReference AltitudeReference The reference from which

the altitude is measured.

latitude number The latitude of the location.

longitude number The longitude of the

location.

Static Methods

90


Value

Description

areEqual areEqual(location1:Location,

location2:Location)

boolean Determines if

the specified

Location

objects are

equal.

normalizeLongitude normalizeLongitude(longitude:number) number Normalizes

the specified

longitude so

that it is

between -180

and 180.

Methods


clone clone() Location Returns a copy of the

Location object.

toString toString() string Converts the Location

object to a string.



<html>

<head>

<title></title>





91

var map = null;

function GetMap()

{


"Bing Maps Key"});

}

function SetLocation()

{

// Parse the input string

var latLongArray = (document.getElementById("txtlatlong").value).split(",");

// Retrieve the latitude and longitude values- normalize the longitude value

var latVal = parseInt(latLongArray[0]);

var longVal =

Microsoft.Maps.Location.normalizeLongitude(parseInt(latLongArray[1]));

// Set the map center

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

}

</script>

</head>



Latitude, Longitude: <input id="txtlatlong" type="text" value="40, -120"/>

<input type="button" value="Set center location" onclick="SetLocation();"/>

</body>

</html>

92

LocationRect Class

Represents a rectangle on the map.

Constructor


LocationRect LocationRect(center:Location,

width:number, height:number)

Initializes a new instance

of the LocationRect class.

Properties


center Location The location that defines the

center of the rectangle.

height number The height, in degrees, of the

rectangle.

width number The width, in degrees, of the

rectangle.

Static Methods


Value

Description

fromCorn

ers

fromCorners(northwest:Loc

ation, southeast:Location)

Location

Rect

Returns a LocationRect using the

specified locations for the northwest and

southeast corners.

fromEdge

s

fromEdges(north:number,

west:number,

south:number,

east:number,

altitude:number,

altitudeReference:Altitude

Reference)

Location

Rect

Returns a LocationRect using the

specified northern and southern latitudes

and western and eastern longitudes for

the rectangle boundaries.

93


Value

Description

fromLocat

ions

fromLocations(list of

locations/array)

Location

Rect

Returns a LocationRect using a list of

locations or an array of locations.

To provide a list of locations:

Microsoft.Maps.LocationRect.fromLocati

ons(location1, location2, location3);

To provide an array of locations:

var locations = [location1, location2,

location3];

Microsoft.Maps.LocationRect.fromLocati

ons(locations);

fromStrin

g

fromString(string:string) Location

Rect

Creates a LocationRect from a string with

the following format:

"north,west,south,east". North, west,

south and east specify the coordinate

number values.

Methods


clone clone() LocationRect Returns a copy of

the LocationRect

object.

contains contains(location:Location) boolean Returns whether

the specified

Location is within

the LocationRect.

getEast getEast() number Returns the

longitude that

defines the

eastern edge of

the LocationRect.

getNorth getNorth() number Returns the

latitude that

defines the

northern edge of

94


the LocationRect.

getNorthwest getNorthwest() Location Returns the

Location that

defines the

northwest corner

of the

LocationRect.

getSouth getSouth() number Returns the

latitude that

defines the

southern edge of

the LocationRect.

getSoutheast getSoutheast() Location Returns the

Location that

defines the

southeast corner

of the

LocationRect.

getWest getWest() number Returns the

latitude that

defines the

western edge of

the LocationRect.

intersects intersects(rect:LocationRect) boolean Returns whether

the specified

LocationRect

intersects with this

LocationRect.


LocationRect

object to a string.



<html>

95

<head>

<title></title>





var map = null;

function GetMap()

{


"Bing Maps Key"});

var viewRect = Microsoft.Maps.LocationRect.fromCorners(new

Microsoft.Maps.Location(40,-120), new Microsoft.Maps.Location(35,-115));

map.setView({bounds: viewRect});

}

</script>

</head>



</body>

</html>

Map Class

Represents a map.

96

Constructor


Map Map(containerElement:node,

options?:MapOptions or

ViewOptions)


the Map class.

Properties


entities EntityCollection The map‟s entities. Use this

property to add or remove

entities from the map.

Static Methods


getVersion getVersion() string Returns the version of

the map control.

Methods


blur blur() None Removes focus from the map

control so that it does not

respond to keyboard events.

dispose dispose() None Deletes the Map object and

releases any associated

resources.

focus focus() None Applies focus to the map

control so that it responds to

keyboard events.

getBounds getBounds() LocationRect Returns the location rectangle

97


that defines the boundaries of

the current map view.

getCenter getCenter() Location Returns the location of the

center of the current map

view.

getCopyrights getCopyrights(callback:fu

nction)

string[] Returns to the specified

callback an array of strings

representing the attributions of

the imagery currently

displayed on the map.

getCredentials getCredentials(callback:f

unction)

None 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) { /* Valid session

Id. Use it to call REST

service */ }

});

getHeading getHeading() number Returns the heading of the

current map view.

getHeight getHeight() number Returns the height of the map

control.

getImageryId getImageryId() string Returns the string that

represents the imagery

currently displayed on the

map.

getMapTypeId getMapTypeId() string Returns a string that

represents the current map

type displayed on the map.

Valid map types are listed in

the MapTypeId Enumeration

topic.

getMetersPerPix getMetersPerPixel() number Returns the current scale in

meters per pixel of the center

98


el of the map.

getModeLayer getModeLayer() Node Returns the map‟s mode node.

getOptions getOptions() MapOptions 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.

getPageX getPageX() number Returns the x coordinate of the

top left corner of the map

control, relative to the page.

getPageY getPageY() number Returns the y coordinate of the

top left corner of the map

control, relative to the page.

getRootElement getRootElement() Node Returns the map‟s root node.

getTargetBounds getTargetBounds() LocationRect Returns the location rectangle

that defines the boundaries of

the view to which the map is

navigating.

getTargetCenter getTargetCenter() Location Returns the center location of

the view to which the map is

navigating.

getTargetHeadin

g

getTargetHeading() number Returns the heading of the

view to which the map is

navigating.

getTargetMeters

PerPixel

getTargetMetersPerPixel() number Returns the scale in meters

per pixel of the center of the


navigating.

getTargetZoom getTargetZoom() number Returns the zoom level of the


navigating.

getUserLayer getUserLayer() Node Returns the map‟s user node.

getViewportX getViewportX() number Returns the x coordinate of the

viewport origin (the center of

99


the map), relative to the page.

getViewportY getViewportY() number Returns the y coordinate of the

viewport origin (the center of

the map), relative to the page.

getWidth getWidth() number Returns the width of the map

control.

getZoom getZoom() number Returns the zoom level of the

current map view.

getZoomRange getZoomRange() object:{min:nu

mber, max:

number}

Returns the range of valid

zoom levels for the current

map view.

isMercator isMercator() boolean Returns whether the map is in

a regular Mercator nadir

mode.

isRotationEnable

d

isRotationEnabled() boolean Returns true if the current map

type allows the heading to

change; false if the display

heading is fixed.

setMapType setMapType(mapTypeId:strin

g)

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

setOptions setOptions({height:numbe

r, width: number})

None Sets the height and width of

the map.

setView setView(options:ViewOptio

ns)

None Sets the map view based on

the specified options.

tryLocationToPix

el

tryLocationToPixel(locati

on:Location |Location[],

reference?:PixelReference

)

null, Point, or

Point[]

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.

100


Alternatively, converts an

array of Locations and returns

an array of Points if all

locations were converted. If

any of the conversions fail, null

is returned.

tryPixelToLocati

on

tryPixelToLocation(point:

Point |Point[],

reference?:PixelReference

)

null, Location,

or Location[]

Converts a specified Point to a

Location on the map relative to

the specified PixelReference.

If reference is not specified,

PixelReference.viewport is

used. If the map is not able to

convert the Point, null is

returned.

Alternatively, converts an

array of Points and returns an

array of Locations if all points

were converted. If any of the

conversions fail, null is

returned.

Events



used to click the map.

copyrightchanged None Occurs when the copyright

of the map changes.

dblclick eventArgs:MouseEventArgs Occurs when the mouse is

used to double click the

map.

imagerychanged None 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

101


changed.

keydown eventArgs:KeyEventArgs Occurs when a keyboard

key is pressed down.

keypress eventArgs:KeyEventArgs Occurs when a keyboard

key is pressed.

keyup eventArgs:KeyEventArgs Occurs when a keyboard

key that is pressed down is

released.

maptypechanged None Occurs when the map type

changes.

mousedown eventArgs:MouseEventArgs Occurs when the left mouse

button is pressed when the

mouse cursor is over the

map.

mousemove eventArgs:MouseEventArgs Occurs when the mouse

cursor moves over the map.

mouseout eventArgs:MouseEventArgs Occurs when the mouse

cursor moves out of the area

covered by the map.

mouseover eventArgs:MouseEventArgs Occurs when the mouse is

over the map.

mouseup eventArgs:MouseEventArgs Occurs when the left mouse

button is lifted up when the


map.

mousewheel eventArgs:MouseEventArgs Occurs when the mouse

wheel is used when the


map.

rightclick eventArgs:MouseEventArgs Occurs when the right

mouse button is used to

click the map.

targetviewchanged None Occurs when the view

towards which the map is

navigating changes.

102


tiledownloadcomplete None Occurs when all the map

tiles of a map view have

loaded.

viewchange None Occurs for every frame of a

map view change.

viewchangeend None 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.

viewchangestart None Occurs when the map view

starts changing.



<html>

<head>

<title></title>




103


var map = null;

function GetMap()

{




}

</script>

</head>



</body>

</html>

MapOptions Object

Represents options to customize the map that is displayed.

Properties


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.



104


when using the Map

constructor.

disableBirdseye boolean A boolean indicating whether to

disable the bird‟s eye map type.

The default value is false. If this

property is set to true, bird‟s

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.


when using the Map

constructor.

disableKeyboardInput boolean A boolean value indicating

whether to disable the map‟s

response to keyboard input.

The default value is false.

disableMouseInput boolean A boolean value indicating


response to mouse input. The

default value is false.

disablePanning boolean A boolean value indicating

whether to disable the user‟s

ability to pan the map. The


disableTouchInput boolean A boolean value indicating


response to touch input. The


disableUserInput boolean A boolean value indicating


response to any user input. The


disableZooming boolean A boolean value indicating

whether to disable the user‟s

ability to zoom in or out. The

105



enableClickableLogo boolean A boolean value indicating

whether the BingTM

logo on the

map is clickable. The default

value is true.


when using the Map

constructor.

enableSearchLogo boolean A boolean value indicating

whether to enable the BingTM

hovering search logo on the

map. The default value is true.


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.


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.

106


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 location‟s

geography hierarchy. For

example, if the location center is

Seattle, the breadcrumb control

displays “World . United States .

WA”. The default value is false.


when using the Map

constructor.

showCopyright boolean A boolean value indicating

whether or not to show the map

copyright. The default value is

true.


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



107


information is displayed

through alternate

means.

showDashboard boolean A boolean value indicating

whether to show the map

navigation control. The default

value is true.


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.


when using the Map

constructor.

showScalebar boolean A boolean value indicating

whether to show the scale bar.

The default value is true.


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.

useInertia boolean A boolean value indicating

whether to use the inertia

animation effect during map

navigation. The default value is

true.

width number 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

108


as well.



<html>

<head>

<title></title>





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};



mapOptions);

}

109

</script>

</head>


<div id='mapDiv' style="position:relative;"></div>

</body>

</html>

MapTypeId Enumeration

Contains identifiers for the imagery displayed on the map.

Constants

Name Description

aerial The aerial map style is being used.

auto The map is set to choose the best imagery for

the current view.

birdseye The bird‟s eye map type is being used.

collinsBart Collin‟s Bart (mkt=en-gb) map type is being

used.

mercator The Mercator style is being used.

ordnanceSurvey Ordnance Survey (mkt=en-gb) map type is

being used.

road The road map style is being used.

Example This code sample sets the map imagery to Collin‟s Bart (collinsBart). Since this imagery is only

supported for the en-gb culture, the mkt parameter of the control is set to this culture.



<html>

<head>

<title></title>

110



src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0&mkt=en-

gb"></script>


function GetMap()

{


{credentials:"Bing Maps Key", center: new Microsoft.Maps.Location(51.5, -.1), zoom: 10,

mapTypeId:Microsoft.Maps.MapTypeId.collinsBart});

}

</script>

</head>



</body>

</html>

See Also Changing the Map View


Module Loading Methods

The following methods allow you to register and load your own modules for use by the map

control. More information about building your own module is in the Building Your Own Module

topic.

Methods

111


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

Microsoft.Maps.Traffic

Microsoft.Maps.Venue

Maps

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.

registerModule registerModule(moduleKey:string,

scriptUrl:string,

options:{styleURLs})

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

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

112


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.



<html>

<head>

<title></title>





var map;

function myModuleLoaded()

{

alert("myModule has loaded.");

// Use the function provided by the newly loaded module

var myModule = new MyModule(map);

myModule.HelloWorld();

}

113

function GetMap()

{


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>

</html>

// mymodule.js

function MyModule(map)

{

this.HelloWorld = function()

{

alert("Hello World - map Center is " + map.getCenter().toString());

}

}

Microsoft.Maps.moduleLoaded('MyModule1');

114

See Also Building Your Own Module


Contains the arguments for mouse events.

Properties


eventName string The event that occurred.


the event is handled. If this

property is set to true, the

default map control behavior

for the event is cancelled.

isPrimary boolean A boolean indicating if the

primary button (such as the left

mouse button or a tap on a

touch screen) was used.

isSecondary boolean A boolean indicating if the

secondary mouse button (such

as the right mouse button) was

used.

isTouchEvent boolean A boolean indicating whether

the event that occurred was a

touch event.

originalEvent object The original browser event.

pageX number The x-value of the pixel

coordinate on the page of the

mouse cursor.

pageY number The y-value of the pixel

coordinate on the page of the

mouse cursor.

target object The object that fired the event.

115


targetType string The type of the object that fired

the event. Valid values include

the following: „map‟, „polygon‟,

„polyline‟, or „pushpin‟

wheelDelta number The number of units that the

mouse wheel has changed.

Methods


getX getX() number Returns the x-value of

the pixel coordinate,

relative to the map, of

the mouse.

getY getY() number Returns the y-value of

the pixel coordinate,

relative to the map, of

the mouse.



<html>

<head>

<title></title>





var map = null;

116

function GetMap()

{





Microsoft.Maps.Events.addHandler(map, 'click', displayEventInfo);

}

function displayEventInfo(e) {




document.getElementById("textBox").value = loc.latitude + ", " +

loc.longitude;

}

}

</script>

</head>




Latitude, Longitude:

<input id='textBox' type="text" style="width:250px;"/>

</body>

</html>

117

PixelReference Enumeration

Contains constants used to show how pixels are defined.

Constants

Name Description

control The pixel is defined relative to the map control‟s

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.

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

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

Methods


isValid isValid(reference:PixelReference) boolean Determines whether

the specified

reference is a

supported

PixelReference.



118

<html>

<head>

<title></title>





var map = null;

function GetMap()

{




// Add handler for the map click event.


}



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)

{

119

alert("The location " + loc.latitude + ", " + loc.longitude + " was

clicked.");

}

}

}

</script>

</head>




</body>

</html>

Point Class

Represents a point on the map.

Constructor


Point Point(x:number, y:number) Initializes a new instance of

the Point class.

Properties


x number The x value of the coordinate.

y number The y-value of the coordinate.

120

Static Methods


areEqual areEqual(point1:Point,

point2:Point)

boolean Determines if the

specified points are

equal.

clone clone(Point) Point Returns a copy of the

Point object.

Methods


clone clone() Point Returns a copy of the

Point object.

toString toString() string Converts the Point

object into a string.



<html>

<head>

<title></title>





var map = null;

function GetMap()

121

{



{credentials:"Bing Maps Key "});

// Add handler for the map click event.


}





if (loc!=null)

{

alert("The location " + loc.latitude + ", " + loc.longitude + " was

clicked.");

}

}

}

</script>

</head>




</body>

</html>

122

Polygon Class (AJAX)

Represents a polygon on the map.

Constructor


Polygon Polygon(locations:Location[],

options?:PolygonOptions)


the Polygon class.

Methods


getFillColor getFillColor() Color Returns the

color of the

inside of the

polygon.

getLocations getLocations() Location[] Returns the

locations that

define the

corners of the

polygon.

getStrokeColor getStrokeColor() Color Returns the

color of the

outline of the

polygon.

getStrokeDashArray getStrokeDashArray() string Returns the

string that

represents the

stroke/gap

sequence

used to draw

the outline of

the polygon.

getStrokeThickness getStrokeThickness() number Returns the

thickness of

the outline of

123


the polygon.

getVisible getVisible() boolean Returns

whether the

polygon is

visible. A

value of false

indicates that

the polygon is

hidden,

although it is

still an entity

on the map.

setLocations setLocations(locations:Location[]) None Sets the

locations that

define the

corners of the

polygon.

setOptions setOptions(options:PolygonOptions) None Sets options

for the

polygon.


Polygon object

to a string.

Events



used to click the polygon.



polygon.


of the polygon or any of

the polygon‟s options

change.

124


mousedown eventArgs:MouseEventArgs Occurs when the left

mouse button is pressed

when the mouse is over

the polygon.


cursor moves out of the

area covered by the

polygon.


over the polygon.

mouseup eventArgs:MouseEventArgs Occurs when the left

mouse button is lifted up


the polygon.



click the polygon.



<html>

<head>

<title></title>





function GetMap()

{


125








// Create a polygon


location1);





map.entities.push(polygon)

// Set the view

map.setView({bounds: Microsoft.Maps.LocationRect.fromLocations(vertices)});

}

</script>

</head>



</body>

</html>

126

PolygonOptions Object

Represents the options for a polygon.

Properties


fillColor Color The color of the inside of the

polygon.

strokeColor Color The color of the outline of the

polygon.

strokeDashArray string 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.

strokeThickness number The thickness of the outline of

the polygon.

visible boolean 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.

127



<html>

<head>

<title></title>





function GetMap()

{









// Create a polygon


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});

128


map.entities.push(polygon)

// Set the view

map.setView({bounds: Microsoft.Maps.LocationRect.fromLocations(vertices)});

}

</script>

</head>



</body>

</html>

Polyline Class

Represents a polyline on the map.

Constructor


Polyline Polyline(locations:Location[],

options?:PolylineOptions)


the Polyline class.

Methods


getLocations getLocations() Location[] Returns the

locations that

define the

129


polyline.

getStrokeColor getStrokeColor() Color Returns the

color of the

polyline.

getStrokeDashArray getStrokeDashArray() string Returns the

string that

represents the

stroke/gap

sequence

used to draw

the polyline.

getStrokeThickness getStrokeThickness() number Returns the

thickness of

the polyline.

getVisible getVisible() boolean 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.

setLocations setLocations(locations:Location[]) None Sets the

locations that

define the

polyline.

setOptions setOptions(options:PolylineOptions) None Sets options

for the

polyline.


Polyline object

to a string.

130

Events



used to click the polyline.



polyline.


of the polyline or any of the

polyline‟s options change.




the polyline.



area covered by the

polyline.


over the polyline.




the polyline.



click the polyline.



<html>

<head>

<title></title>


131




var map = null;

function GetMap()

{


map = new








// Create a polyline


location5);

var line = new Microsoft.Maps.Polyline(lineVertices);

// Add the polyline to the map


}

132

</script>

</head>



</body>

</html>

PolylineOptions Object

Represents the options for a polyline.

Properties


strokeColor Color The color of the polyline.

strokeDashArray string 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.

strokeThickness number The thickness of the polyline.


to show or hide the polyline. A


the polyline is hidden, although

it is still an entity on the map.

133



<html>

<head>

<title></title>





var map = null;

function GetMap()

{


map = new








// Create a polyline


location5);

134

var line = new Microsoft.Maps.Polyline(lineVertices,{strokeColor:new

Microsoft.Maps.Color(200, 100, 0, 100), strokeThickness:5, strokeDashArray:"5 2"});

// Add the polyline to the map


}

</script>

</head>



</body>

</html>

Position Class

Represents the position of a user on a map.

Properties


coords Coordinates The position as a W3C

Coordinates object.

timestamp string The time when the position was

determined, in the form of a

DOMTimeStamp.


135

PositionCircleOptions Object

Contains options for the addAccuracyCircle method of the GeoLocationProvider class.

Properties


polygonOptions PolygonOptions The polygon options for the

geo location accuracy circle.

showOnMap boolean 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.



<html>

<head>

<title></title>





var map;

var geoLocationProvider;

function GetMap()

136

{




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


geoLocationProvider = new Microsoft.Maps.GeoLocationProvider(map);


geoLocationProvider.getCurrentPosition({successCallback:drawCircle,

showAccuracyCircle:false});

}

function drawCircle(args)

{

// Draw the accuracy circle using a different color

geoLocationProvider.addAccuracyCircle(args.center, 50000, 50000,

{polygonOptions:{fillColor:new Microsoft.Maps.Color(100,100,0,100), strokeColor:new

Microsoft.Maps.Color(100,100,0,100)}});

}

</script>

</head>



</body>

137

</html>

PositionError Class

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

Properties


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.


PositionOptions Object

Contains options for the getCurrentPosition method of the GeoLocationProvider class.

138

Properties


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.

errorCallback function 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 user‟s browser

does not support geo

location.

maximumAge number A number indicating the

acceptable age, in

milliseconds, of a cached geo

139


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.


successCallback function The function to call when the

user‟s 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.

timeout number The length of time, in

milliseconds, to allow for the

geo location request to return.

By default there is no timeout.

updateMapView boolean A boolean indicating whether

to update the map view with

the best view of the user‟s

location (if the request is

successful). The default value

is true.



<html>

<head>

<title></title>


140




var map;

function GetMap()

{




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


var geoLocationProvider = new Microsoft.Maps.GeoLocationProvider(map);


geoLocationProvider.getCurrentPosition({successCallback:displayCenter});

}

function displayCenter(args)

{

// Display the user location when the geo location request returns

alert("The user's location is " + args.center);

}

</script>

141

</head>



</body>

</html>

Pushpin Class (AJAX)

Defines a pushpin on the map.

Constructor


Pushpin Pushpin(location:Location,

options?:PushpinOptions)


the Pushpin class.

Methods


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

getIcon getIcon() string Returns the

pushpin icon.

getHeight getHeight() number Returns the

height of the

pushpin, which

is the height of

the pushpin icon.

142


getLocation getLocation() Location Returns the

location of the

pushpin.

getText getText() string Returns the text

associated with

the pushpin.

getTextOffset getTextOffset() Point Returns the

amount the text

is shifted from

the pushpin icon.

getTypeName getTypeName() string Returns the type

of the pushpin.

getVisible getVisible() boolean 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.

getWidth getWidth() number Returns the

width of the

pushpin, which

is the width of

the pushpin icon.

getZIndex getZIndex() number Returns the z-

index of the

pushpin with

respect to other

items on the

map.

setLocation setLocation(location:Location) None Sets the location

of the pushpin.

setOptions setOptions(options:PushpinOptions) None Sets options for

the pushpin.


143


Pushpin object

to a string.

Events



used to click the pushpin.



pushpin.

drag eventArgs:MouseEventArgs Occurs when the pushpin

is being dragged.

dragend eventArgs:MouseEventArgs Occurs when the pushpin

stops being dragged.

dragstart eventArgs:MouseEventArgs Occurs when the pushpin

starts being dragged.


of the pushpin or any of

the pushpin‟s options

change.




the pushpin.



area covered by the

pushpin.


over the pushpin.




the pushpin.

144




click the pushpin.



<html>

<head>

<title></title>





var map = null;

function GetMap()

{







var pin = new Microsoft.Maps.Pushpin(center, {draggable: true});

// Add a handler to the pushpin drag

145

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


}

function DisplayLoc(e){

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

var pinLoc = e.target.getLocation();

alert("The location of the pushpin is now " + pinLoc.latitude + ", " +

pinLoc.longitude);

}

}

</script>

</head>



<b>Drag the pushpin to a new location.</b>

</body>

</html>

PushpinOptions Object

Represents the options for a pushpin.

Properties


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

146


bottom center of the icon.

draggable boolean A boolean indicating whether

the pushpin can be dragged to

a new position with the mouse.

icon string The path of the image to use

as the pushpin icon.

height number The height of the pushpin,

which is the height of the

pushpin icon. The default value

is 39.

text string The text associated with the

pushpin.

textOffset Point The amount the text is shifted

from the pushpin icon. The

default value is (0,5).

typeName string The type of the pushpin, as a

string. The pushpin DOM

(document object model) node

created for the pushpin will

have the specified typeName.

visible boolean 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.

width number The width of the pushpin, which

is the width of the pushpin icon.

The default value is 25.

zIndex number The z-index of the pushpin with

respect to other items on the

map.

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

147



<html>

<head>

<title></title>





var map = null;

function GetMap()

{







var pin = new Microsoft.Maps.Pushpin(center, {icon:"BluePushpin.png",

height:50, width:50, anchor:new

Microsoft.Maps.Point(0,50), draggable: true});


148

}

</script>

</head>



</body>

</html>

TileLayer Class

Represents a tile layer.

Constructor


TileLayer TileLayer(options:TileLayerOptions) Initializes a new instance

of the TileLayer class.

Methods


Type

Description

getOpacity getOpacty() number Returns the opacity of the

tile layer, defined as a

double between 0 (not

visible) and 1.

getTileSourc

e

getTileSource(projection:string) TileSourc

e

Returns the tile source of

the tile layer.

The projection parameter

accepts the following

values: mercator,

enhancedBirdseyeNorthUp,

enhancedBirdseyeSouthUp

149


Type

Description

,

enhancedBirdseyeEastUp,

enhancedBirdseyeWestUp

getZIndex getZIndex() number Returns the z-index of the

tile layer with respect to

other items on the map.

setOptions setOptions(options:TileLayerOptions

)

None Sets options for the tile

layer.

toString toString() string Converts the TileLayer

object to a string.

Events


tiledownloadcomplete None Occurs when all the tiles of

the tile layer have loaded.



<html>

<head>

<title></title>





function GetMap()

{

150



{credentials:"Bing Maps Key", center:new Microsoft.Maps.Location(48.03,-

122.4), zoom:12, mapTypeId: Microsoft.Maps.MapTypeId.road });

try

{






opacity: .7 });



}

catch(err)

{


}

}

</script>

</head>



</body>

</html>

151

See Also Working with Tile Layers

TileLayerOptions Object

Defines the options for a tile layer.

Properties


animationDisplay AnimationVisibility The tile layer‟s visibility

during animation. You can

use this property to prevent

overlays from displaying

during animations, which can

impact performance. The

default value is auto.

mercator TileSource The tile source for the tile

layer.

opacity number The opacity of the tile layer,

defined by a number

between 0 (not visible) and

1.


to show or hide the tile layer.

The default value is true. A


the tile layer is hidden,

although it is still an entity on

the map.

zIndex number The z-index of the tile layer,

with respect to other items

on the map.

152



<html>

<head>

<title></title>





var map = null;

var tilelayer = null;

function GetMap()

{



{credentials:"Bing Maps Key", center:new Microsoft.Maps.Location(48.03,-122.4), zoom:12,


try

{





tilelayer= new Microsoft.Maps.TileLayer({ mercator: tileSource, opacity:

.7 });


153


}

catch(err)

{


}

}

function SetOpacity()

{

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

if ((opacityVal > 1) || (opacityVal < 0))

{

alert("The opacity value must be between 0 and 1.");

}

else

{

tilelayer.setOptions({opacity: opacityVal});

}

}

</script>

</head>



<input id="txtOpacity" type="text" value=".1" style="width:25px;"/>

<input type="button" value="Set Opacity" onclick="SetOpacity();"/>

154

</body>

</html>


TileSource Class

Defines a tile source for a tile layer.

Constructor


TileSource TileSource(options:TileSourceOptions) Initializes a new instance

of the TileSource class.

Methods

Name Definition Return Type Description

getHeight getHeight() Number Returns the pixel

height of each tile in

the tile source.

getUriConstructor getUriConstructor() string Returns a string

that constructs tile

URLs used to

retrieve tiles for the

tile layer.

getWidth getWidth() number Returns the pixel

width of each tile in

the tile source.


TileSource object to

a string.

155



<html>

<head>

<title></title>





function GetMap()

{


var map = new

Microsoft.Maps.Map(document.getElementById("mapDiv"),{credentials:"Bing Maps Key",



try

{






opacity: .7 });



}

156

catch(err)

{


}

}

</script>

</head>



</body>

</html>


TileSourceOptions Object

Defines options for a tile source.

Properties


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 projection‟s tile height

for the tiles to be shown. For

example, since Mercator tile

source tiles are 256x256, this

157


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

projection‟s 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.



<html>

<head>

<title></title>





158

function GetMap()

{


var map = new




try

{






opacity: .7 });



}

catch(err)

{


}

}

</script>

</head>



</body>

</html>

159


ViewOptions Object

Contains options for the map view.

Properties


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.

bounds LocationRect The bounding rectangle of the

map view. If both are

specified, bounds takes

precedence over center.

center Location The location of the center of

the map view. If both are

specified, bounds takes

precedence over center.

centerOffset Point The amount the center is

shifted. This property is

ignored if center is not

specified.

heading number 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.

labelOverlay LabelOverlay A constant indicating how map

labels are displayed.

mapTypeId string The map type of the view.

160


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.

zoom number The zoom level of the map

view.

Remarks To 'lock' the map in a certain position, disable mouse and keyboard events during the application

session. The following code disables mouse events.

// Attach an event handler for a mousemove event.

Microsoft.Maps.Events.addHandler(map, "mousemove", cancelEvent);

// When the mouse is used, the cancelEvent function will

// get called. Setting the handled property to true will

// disable the mousemove event, which disables panning.

function cancelEvent(e)

{

e.handled = true;

}



<html>

<head>

<title></title>




161


var map = null;

function GetMap()

{

// Set the initial map and view settings

var initialViewBounds = Microsoft.Maps.LocationRect.fromCorners(new

Microsoft.Maps.Location(43,-123), new Microsoft.Maps.Location(33,-113));

var options = {credentials:"Bing Maps Key", width: 500, height: 500, bounds:

initialViewBounds, mapTypeId:Microsoft.Maps.MapTypeId.aerial, animate: false};


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

}

function SetZoom()

{

// Retrieve the zoom level set by the user - converting it to a number.

var zoomLevel = parseInt(document.getElementById("txtZoom").value);

// Get the existing options.

var options = map.getOptions();

// Set the zoom level of the map

options.zoom = zoomLevel;

map.setView(options);

}

162

</script>

</head>


<div id='mapDiv' style="position:relative;"></div>

<input id="txtZoom" type="text" value="1"/>

<input type="button" value="Set Zoom" onclick="SetZoom();"/>

</body>

</html>

Microsoft.Maps.Directions API Reference

This section contains reference documentation for the Microsoft.Maps.Directions API, which

contains types that allow you to calculate route directions and display them on your Bing Maps

AJAX Control 7.0 map. Use the calculateDirections method of the DirectionsManager Class to

calculate a route. Sample code can be found at http://www.bingmapsportal.com/isdk/ajaxv7.

Before you can access the types found in the Microsoft.Maps.Directions API, you must

first load this module using the loadModule method. Information about loading modules

is in the Module Loading Methods topic.

In This Section BusinessDetails Class

BusinessDisambiguationSuggestion Class

DirectionsErrorEventArgs Object

DirectionsEventArgs Object

DirectionsManager Class

DirectionsRenderOptions Object

DirectionsRequestOptions Object

DirectionsStep Class

DirectionsStepEventArgs Object

DirectionsStepRenderEventArgs Object

DirectionsStepWarning Class

DirectionsStepWarningType Enumeration

Disambiguation Class

DistanceUnit Enumeration

LocationDisambiguationSuggestion Class

http://www.bingmapsportal.com/isdk/ajaxv7

163

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


businessName string The business name of the

waypoint.

entityId string The Bing Maps entity ID of the

business.

phoneNumber string The phone number of the

business.

164


website string The URL of the business‟

website.

BusinessDisambiguationSuggestion Class

Contains a possible business result returned from geocoding a specified waypoint address or

location.

Properties


address string The address of the business

result.

distance number The distance of the business

result from the originally

specified waypoint address or

location.

entityId string The Yellow Pages ID for the

business.

index number The index of this suggestion

within the business suggestion

array.

isApproximate boolean A boolean indicating whether

the result location is

approximate.

location Location The location of the business

suggestion.

name string The name of the business.

phoneNumber string The phone number of the

business suggestion.

photoUrl string The URL of a photo of the


rooftopLocation Location The rooftop location of the

165



website string The URL of the business

result‟s website.



<html>

<head>

<title></title>





var map = null;

var directionsManager = null;

function GetMap()

{


map = new


Microsoft.Maps.loadModule('Microsoft.Maps.Directions', { callback:

directionsModuleLoaded });

}

166

function directionsModuleLoaded()

{

// Initialize the DirectionsManager

directionsManager = new Microsoft.Maps.Directions.DirectionsManager(map);

// Create start and end waypoints

var startWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Seattle,

WA"});

var endWaypoint = new Microsoft.Maps.Directions.Waypoint({ address:

"Microsoft" } );

directionsManager.addWaypoint(startWaypoint);

directionsManager.addWaypoint(endWaypoint);

// Set the id of the div to use to display the directions

directionsManager.setRenderOptions({ itineraryContainer:

document.getElementById('itineraryDiv') });

// Specify a handler for when an error occurs

Microsoft.Maps.Events.addHandler(directionsManager, 'directionsError',

displayError);

// Calculate directions, which displays a route on the map

directionsManager.calculateDirections();

}

function displayError(e)

{

// Display the error message

alert(e.message);

// If the error is a disambiguation error, display the results.

if (e.responseCode == 12)

167

{

DisplayDisambiguation();

}

}

function DisplayDisambiguation()

{

var results = "";

var waypoints = directionsManager.getAllWaypoints();

var i = 0;

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

{

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

if (disambigResult != null)

{

results = results + "Address matches for " + waypoints[i].getAddress()

+ ":\n";

var j = 0;

for (j=0; j<disambigResult.businessSuggestions.length; j++)

{

results = results + disambigResult.businessSuggestions[j].name + ",

" + disambigResult.businessSuggestions[j].address + "\n";

}

}

}

alert(results);

}

168

</script>

</head>



<div id='itineraryDiv' style="position:relative; width:400px;"></div>

</body>

</html>

See Also Disambiguation Class

DirectionsErrorEventArgs Object

Contains arguments for directions error events.

Properties


responseCode RouteResponseCode The code which identifies

the error that occurred.

message string The error message.



<html>

<head>

<title></title>




169


var map = null;

function GetMap()

{


map = new




}


{


var directionsManager = new Microsoft.Maps.Directions.DirectionsManager(map);

// Create start and end waypoints and add them to the route


WA"});

var endWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Paris,

France"});



// Set directions render options - in this case, specify the div where the

itinerary is displayed.



170

// Specify a handler for when the directions are calculated and when an error

occurs

Microsoft.Maps.Events.addHandler(directionsManager, 'directionsUpdated',

displayMessage );


displayError );



}

function displayMessage(e)

{

alert("Route calculation complete!");

}


{

alert( e.message );

}

</script>

</head>




</body>

</html>

171

DirectionsEventArgs Object

Contains the arguments for directions events.

Properties


routeSummary RouteSummary[] The route summary (or

summaries) of the route(s)

defined in the route property.

route Route[] The calculated route (or

routes, if the route mode is

transit).



<html>

<head>

<title></title>





var map = null;

function GetMap()

{


map = new


172



}


{





WA"});

var endWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"Bellevue,

WA"});



// 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


displayRouteNumber);



173

}

function displayRouteNumber(e)

{

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

}

</script>

</head>




</body>

</html>

DirectionsManager Class

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

Constructor


DirectionsManager DirectionsManager(map:Map) Initializes a new instance of

the DirectionsManager

class.

Methods


addWaypoint addWaypoint(waypoint:Waypoint) None Adds a

174


waypoint to the

route. To

recalculate the

route, use

calculateDirec

tions. The

maximum

number of

waypoints is

15.

calculateDirecti

ons

calculateDirections() None Calculates

directions

based on

request and

render options

set

(setRequestO

ptions,

setRenderOpti

ons) and the

waypoints

added

(addWaypoint)

. The

directionsUpd

ated event fires

when the

calculation is

complete and

the route is

displayed on

the map.

You must call

this method

after making

any changes to

the route

options or

waypoints.

clearDisplay clearDisplay() None Clears the

175


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.

getAllWaypoint

s

getAllWaypoints() Waypoint[] Returns the

waypoints for

the route.

getMap getMap() Map Returns the

map object

associated with

the directions

manager.

getNearbyMajor

Roads

getNearbyMajorRoads(location:Locatio

n, callback:function,

errorCallback:function,

userData:object)

None Searches

around the

specified

location for

nearby major

roads and

176


returns them as

an object to the

callback

function.

getRenderOptio

ns

getRenderOptions() DirectionsRender

Options

Returns the

route render

options.

getRequestOpti

ons

getRequestOptions() DirectionsRequest

Options

Returns the

directions

request

options.

getRouteResult getRouteResult() Route[] Returns the

current

calculated

route(s). If the

route was not

successfully

calculated, null

is returned.

removeWaypoi

nt

removeWaypoint(waypoint:Waypoint) or

removeWaypoints(index:number)

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

resetDirections resetDirections(options:ResetDirectio

nsOptions)

None If no options

object is

supplied, clears

the directions

request and

render options

and removes

all waypoints.

177


reverseGeocod

e

reverseGeocode(location:Location,

callback:function,

errorCallback:function,

userData:object)

None Matches the

specified

location to an

address and

returns the

address to the

specified

callback

function.

setMapView setMapView() None Sets the map

view based on

the current

route index.

setRenderOptio

ns

setRenderOptions(options:DirectionsR

enderOptions)

None Sets the

specified

render options

for the route.

setRequestOpti

ons

setRequestOptions(options:Directions

RequestOptions)

None Sets the

specified route

calculation

options.

Events


afterRouteSelectorRender RouteSelectorRenderEventArgs Occurs after the

route selector has

fully rendered.

afterStepRender DirectionsStepRenderEventArgs Occurs after each

step in the itinerary

has fully rendered.

afterSummaryRender RouteSummaryRenderEventArgs Occurs after the

route summary has

fully rendered.

afterWaypointRender WaypointRenderEventArgs Occurs after each

route waypoint has

178


fully rendered.

beforeRouteSelectorRender RouteSelectorRenderEventArgs Occurs just before

the route selector

renders.

beforeStepRender DirectionsStepRenderEventArgs Occurs just before

each step in the

itinerary renders.

beforeSummaryRender RouteSummaryRenderEventArgs Occurs just before

the route summary

renders.

beforeWaypointRender WaypointRenderEventArgs Occurs just before

each route waypoint

renders.

directionsError DirectionsErrorEventArgs Occurs when

calculating the

directions caused an

error.

directionsUpdated DirectionsEventArgs Occurs when the

directions calculation

was successful and

the itinerary and

route on the map

have been updated.

itineraryStepClicked DirectionsStepEventArgs Occurs when a step

in the itinerary is

clicked.

mouseEnterRouteSelector RouteSelectorEventArgs Occurs when the

mouse cursor is over

the route selector.

mouseEnterStep DirectionsStepEventArgs Occurs when the

mouse cursor is over

a directions step.

mouseLeaveRouteSelector RouteSelectorEventArgs Occurs when the

mouse cursor leaves

the route selector.

mouseLeaveStep DirectionsStepEventArgs Occurs when the

179


mouse cursor leaves

a directions step.

routeSelectorClicked RouteSelectorEventArgs Occurs when the

route selector is

clicked.

waypointAdded WaypointEventArgs Occurs when a new

waypoint is added to

the route.

waypointRemoved WaypointEventArgs Occurs when a

waypoint is removed

from the route.



<html>

<head>

<title></title>





var map = null;

function GetMap()

{


map = new


180



}


{





WA"});

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

OR"});








displayError);



}


{

181

alert(e.message);

}

</script>

</head>




</body>

</html>

DirectionsRenderOptions Object

Represents render options for a route.

Properties


displayDisclaimer boolean A boolean indicating


disclaimer about the

accuracy of the

directions. The default

value is false.

displayManeuverIcons boolean A boolean indicating


icons for each direction

maneuver. The default

value is true.

displayPostItineraryItemHints boolean A boolean indicating

whether to display

direction hints that

describe when an

direction step was

missed. The default value

182


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.

displayRouteSelector boolean A boolean indicating


route selector control.


displayStepWarnings boolean A boolean indicating

whether to display

direction warnings. The

default value is true.

displayTrafficAvoidanceOption boolean A boolean indicating


control that allows the

user to choose to avoid

traffic. The default value

is true.

displayWalkingWarning boolean A boolean indicating

whether to display a

warning about walking

directions. The default

value is true.

drivingPolylineOptions PolylineOptions The options that define

how to draw the route line

on the map, if the

RouteMode is driving.

itineraryContainer DOMElement The DOM element inside

which the directions

itinerary will be rendered.

lastWaypointIcon string The URL of the icon to

use for the end waypoint.

stepPushpinOptions PushpinOptions The options that define

183


the pushpin to use for

each direction step.

transitPolylineOptions PolylineOptions The options that define


on the map, if the

RouteMode is transit.

viapointPushpinsOptions PushpinOptions 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.

walkingPolylineOptions PolylineOptions The options that define


on the map, if the

RouteMode is walking.

waypointPushpinOptions PushpinOptions The options that define

the pushpin to use for the

route waypoint.

DirectionsRequestOptions Object

Contains options for the directions to calculate.

Properties


avoidTraffic boolean A boolean indicating whether to

use traffic data when calculating

the route. The default value is

false.

distanceUnit DistanceUnit The unit to use when displaying

direction distances. The default

value is based on the specified

culture.

184


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.

routeAvoidance RouteAvoidance[] The features to avoid when

calculating the route. The default

value is none.

routeDraggable boolean A boolean indicating whether the

route line on the map can be

dragged with the mouse cursor.


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

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.

routeMode RouteMode The type of directions to calculate.

The default value is driving. The

route mode transit is only

supported when the culture is ja-

jp, which is the default for that

market.

routeOptimization RouteOptimization The optimization setting for the

route calculation. The default

value is shortestTime.

transitOptions TransitOptions The extra options for calculating a

route if the routeMode is transit.

185

DirectionsStep Class

Represents one direction in a set of route directions.

Properties


childItineraryItems DirectionsStep[] The child direction items for this

directions step.

coordinate Location The location of the start of the

direction.

distance string The total distance of the step in

the unit specified in the

distanceUnit property of the

DirectionsRequestOptions.

durationInSeconds number The total time, in seconds, of the

direction step.

formattedText string The HTML formatted route

instruction associated with the

step.

iconType RouteIconType The type of the icon associated

with this step.

isImageRoadShield boolean A boolean indicating whether

the maneuver image is a road

shield image.

maneuver ManeuverType The maneuver type associated

with this step.

maneuverImageName string The name of the maneuver

image.

monetaryCost number The cost of the step.

postIntersectionHints string[] 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.

preIntersectionHints string[] An array of strings, where each

186


string is a hint to help determine

when you have arrived at this

direction step. Not all direction

steps have hints.

startStopName string The name of the transit stop

where this step originates.

transitLine TransitLine The transit line associated with

this step.

transitStopId string The ID of the transit stop.

transitTerminus string The name of the transit line end.

warnings DirectionsStepWarning[] An array of strings, where each

string is a route warning

associated with this step.

DirectionsStepEventArgs Object

Contains arguments for directions step events.

Properties



the event is handled. Set this

property to true to override

the default behavior.

location Location The location along the route

where the direction step

occurs.

routeIndex number A number indicating the route

(if multiple routes were

returned) to which the

directions step belongs.

routeLegIndex number A number indicating the route

leg to which the directions

187


step belongs.

step DirectionsStep The directions step.

stepIndex number A number indicating the index

of the directions step within

the route leg array.

stepNumber number A number indicating the

directions step number within

the route.

DirectionsStepRenderEventArgs Object

Contains arguments for directions step render events.

Properties


containerElement object The DOM element which

contains the directions step.

You can use this property to

add custom content.


the event is handled. This

property is only available for the

beforeStepRender event. Set

this property to true to override


lastStep boolean A boolean indicating whether

the step is the last directions

step.

routeIndex number A number indicating the index

of the route to which this step

belongs.

routeLegIndex number A number indicating the index

of the route leg to which this

188


step belongs.

step DirectionsStep The directions step.

stepIndex number 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


style DirectionStepWarningType The type of the route

warning.

text string The warning text.

DirectionsStepWarningType Enumeration

Contains types of route direction warnings.

Constants

Code Name Description

0 info The warning is just information

about the route direction.

1 minor The warning is a minor

warning, and may affect the

route direction.

2 moderate The warning is a moderate

warning and is likely to affect

the route direction.

189


3 major The warning is a major

warning, and is highly likely to

affect the route direction.

4 ccZoneEnter The warning indicates a

congestion zone is being

entered.

5 ccZoneExit The warning indicates a

congestion zone is being

exited.

Disambiguation Class

Contains disambiguation results for a waypoint geocoding request.

Properties


businessSuggestions BusinessDiambiguationSuggestion[] The possible business

result matches for the

originally specified

waypoint address or

location.

hasMoreSuggestions boolean A boolean indicating

whether there are more

result suggestions

available.

headerText string The disambiguation

header text.

locationSuggestions LocationDiambiguationSuggestion[] The possible location

result matches for the

originally specified

waypoint address or

location.

190



<html>

<head>

<title></title>





var map = null;


function GetMap()

{


map = new




}


{




var startWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"100 Main

St., WA"});

191


OR"});








displayError);



}


{

// Display an error

alert(e.message);

// If the error is a disambiguation error, show the disambiguation results


{


}

}


{

192

var results = "";


var i = 0;


{



{


+ ":\n";

var j = 0;

for (j=0; j<disambigResult.locationSuggestions.length; j++)

{

results = results + disambigResult.locationSuggestions[j].suggestion

+ "\n";

}

}

}

alert(results);

}

</script>

</head>




</body>

193

</html>

See Also Waypoint Class (AJAX)

DistanceUnit Enumeration (AJAX)

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

Constants


0 kilometers Kilometers are used to measure

route distances.

1 miles Miles are used to measure

route distances.

LocationDisambiguationSuggestion Class

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

Properties


formattedSuggestion string The HTML formatted address

suggestion.

location Location The location of the

suggestion.

rooftopLocation Location The rooftop location of the

suggestion.

suggestion string The address suggestion.

194



<html>

<head>

<title></title>





var map = null;


function GetMap()

{


map = new




}


{




195

var startWaypoint = new Microsoft.Maps.Directions.Waypoint({address:"100 Main

St., WA"});


OR"});








displayError);



}


{

// Display the error message

alert(e.message);

// If the error is a disambiguation error, display the results.


{


}

}


196

{

var results = "";


var i = 0;


{



{


+ ":\n";

var j = 0;

for (j=0; j<disambigResult.locationSuggestions.length; j++)

{

results = results + disambigResult.locationSuggestions[j].suggestion

+ "\n";

}

}

}

alert(results);

}

</script>

</head>




197

</body>

</html>

See Also Disambiguation Class

ManeuverType Enumeration (AJAX)

Contains route maneuver types.

Constants

Type Code Name Description

0 none The step is not a maneuver.

1 unknown The maneuver is unknown.

56 transfer The step is a transit transfer

instruction.

57 wait The step is a wait instruction.

58 takeTransit The step is information about

what transit line to take.

59 walk The step is a walking

instruction.

60 transitDepart The step is a transit departure

instruction.

61 transitArrive The step is a transit arrival

instruction.

ResetDirectionsOptions Object

Contains options for the resetDirections method of the DirectionsManager Class.

Properties

198


removeAllWaypoints boolean A boolean indicating whether

to remove all of the

waypoints of the route. The


resetRenderOptions boolean A boolean indicating whether

to reset all of the render

options set for the route. The


resetRequestOptions boolean A boolean indicating whether

to reset all of the request

options set for the route. The


Route Class (AJAX)

Represents a route.

Properties


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


0 none Calculate the best route

using any travel option

199


available.

1 minimizeLimitedAccessHighway Reduce the use of limited

access highways when

calculating the route.

2 minimizeToll Reduce the use of roads

with tolls when calculating

the route.

4 avoidLimitedAccessHighway Avoid using limited access

highways when calculating

the route.

8 avoidToll Avoid using roads with tolls

when calculating the route.

16 avoidExpressTrain Avoid using express trains


32 avoidAirline Avoid using airlines when

calculating the route.

64 avoidBulletTrain Avoid using bullet trains


RouteIconType Enumeration

Contains route icon types.

Constants


0 none There is no route icon.

1 other The icon is some other type of

icon.

2 auto The icon is a car icon.

3 ferry The icon is a ferry icon.

4 walk The icon is a walking icon.

200


5 bus The icon is a bus, or transit, icon

6 train The icon is a train icon.

7 airline The icon is an airline icon.

RouteLeg Class (AJAX)

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

Properties


endTime DateTime The end time of the route leg.

This property only applies when

the routeMode of the

DirectionsRequestOptions is set

to transit.

endWaypointLocation Location The location of the last waypoint

of this leg.

itineraryItems DirectionsStep[] The directions steps associated

with this route leg.

originalRouteIndex number The index of the route to which

this route leg belongs.

startTime DateTime The start time of the route leg.

This property only applies when

the routeMode of the

DirectionsRequestOptions is set

to transit.

startWaypointLocation Location The location of the first waypoint

of this route leg.

subLegs RouteSubLeg[] 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.

201


summary RouteSummary The summary which describes

this route leg.



<html>

<head>

<title></title>





var map = null;

function GetMap()

{


map = new




}


{



202



WA"});


WA"});





displayMessage);


displayError);



}

function displayMessage(e)

{

alert("The calculated route has " +

e.route[0].routeLegs[0].itineraryItems.length + " direction steps.");

}


{

alert("An error has occurred calculating the directions.");

}

</script>

203

</head>



</body>

</html>

RouteMode Enumeration

Defines the type of route to calculate.

Constants

Name Description

driving Driving directions are calculated.

transit Transit directions are calculated.

walking Walking directions are calculated.

RouteOptimization Enumeration (AJAX)

Defines optimization options for calculating directions.

Constants


0 shortestTime Calculate a route the shortest

time.

1 shortestDistance Calculate a route with the

shortest distance.

3 minimizeMoney Minimize the cost when

calculating directions. This

option only affects routes with

a transit RouteMode, which is

only available when the culture

204


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.

5 minimizeWalking 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.

RoutePath Class (AJAX)

Represents the route line shape on the map.

Use the setRenderOptions method of the DirectionsManager Class to set

DirectionsRenderOptions to customize the look of the route line on the map.

Properties


decodedLatitudes double[] An array of latitudes, where

each latitude is the latitude for

one of the locations that

define the route line.

decodedLongitudes double[] An array of longitudes, where

each is the longitude value for

one of the locations that

define the route line.

decodedRegions Object[] An array of regions that

define, depending on the

205


zoom level, how the route line

should be rendered.

RouteResponseCode Enumeration

Contains response codes for a route calculation request.

Constants

Response Code Name Description

0 success The route was successfully

calculated.

1 unknownError An unknown error has

occurred.

2 cannotFindNearbyRoad A nearby road cannot be

found for one or more of the

route waypoints.

3 tooFar 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.

4 noSolution 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.

5 dataSourceNotFound There is no route data for the

specified waypoints.

7 noAvailableTransitTrip There are no transit options

available for the specified

time.

206

Response Code Name Description

8 transitStopsTooClose The transit stops are so

close that walking is always

a better option.

9 walkingBestAlternative The transit stops are so

close that walking is a better

option.

10 outOfTransitBounds 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.

11 timeout The directions calculation

request has timed out.

12 waypointDisambiguation One or more waypoints need

to be disambiguated.

13 hasEmptyWaypoint One or more waypoints do

not have an address or

location specified.

14 exceedMaxWaypointLimit The maximum number of

waypoints, which is 15, has

been exceeded.

15 atleastTwoWaypointRequired At least two waypoints are

required to calculate a route.

16 firstOrLastStoppointIsVia The first or last waypoint is a

via point, which is not

allowed.

17 searchServiceFailed The search service failed to

return results.

RouteSelectorEventArgs Object

Contains arguments for route selector events.

207

Properties



the event is handled. Set this

property to true to override the

default behavior.

routeIndex number A number indicating the index

of the route that was selected.

RouteSelectorRenderEventArgs Object

Contains arguments for route selector render events.

Properties


containerElement object The DOM element which contains

the route selector. You can use this

property to add custom content.

handled boolean A boolean indicating whether the

event is handled. This property is

only available for the

beforeRouteSelectorRender event.

Set this property to true to override


routeIndex number A number indicating the index of the

selected route.

routeLeg RouteLeg The route leg of the selected route.

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.

208

Properties


actualEnd Location The location of the last

waypoint of the sub leg.

actualStart Location The location of the first


endDescription string The description of the last


routhPath RoutePath The properties that define

the route line of this sub leg

on the map.

startDescription string The description of the first


summary RouteSummary The summary of this route

sub leg.

RouteSummary Class (AJAX)

Represents a route summary.

Properties


distance double The total travel distance of the

route, specified in the units set in

the distanceUnit property of the

DirectionsRequestOptions.

monetaryCost double 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.

northEast Location The location of the northeast corner

of bounding box that defines the

209


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.

time number The total travel time, in seconds, for

the route.

timeWithTraffic number 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.



<html>

<head>

<title></title>





var map = null;

function GetMap()

{


map = new


210



}


{





WA"});


WA"});



// Set directions render options - in this case, specify the div where the

itinerary is displayed.





displayDistanceAndTime );



}

211

function displayDistanceAndTime(e)

{

alert("Total Distance: " + e.routeSummary[0].distance + " miles\n" + "Total

Time: " + e.routeSummary[0].time/60 + " minutes" );

}

</script>

</head>




</body>

</html>

RouteSummaryRenderEventArgs Object

Contains arguments for route summary render events.

Properties



the summary. You can use this





beforeSummaryRender event.

Set this property to true to

override the default behavior.

212


routeLegIndex number A number indicating the index of

the route leg which this summary

describes.

summary RouteSummary The summary that was rendered.

TimeType Enumeration

Defines the time type.

Constants

Name Description

arrival The time specified is an arrival time.

departure The time specified is a departure time.

lastAvailable 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


abbreviatedName string The short name for the transit

line.

agencyId number The ID of the agency that

owns the transit line.

agencyName string The name of the agency that

213


owns the transit line.

agencyUrl string The URL of the website of the

agency that owns the transit

line.

lineColor Color The color to use when

rendering this transit line on

the map.

lineTextColor Color The color to use when

rendering text associated with

this transit line.

providerInfo string Information about the provider

of this transit line data.

verboseName string The full name of this transit

line.

TransitOptions Object

Contains extra options for transit routes.

Properties


timeType TimeType The type of the time specified

in transitTime. The default

value is departure.

transitTime Date The transit time to use when

calculating the route. If this

property is set to null, the

current time is used.

Waypoint Class (AJAX)

Represents a route waypoint.

214

Constructor


Waypoint Waypoint(options:WaypointOptions) Initializes a new instance

of the Waypoint class.

Methods


clear clear() None Clears all

options

associated

with this

waypoint.

dispose dispose() None Releases any

resources

associated

with the

waypoint.

getAddress getAddress() string Returns the

address

associated

with the

waypoint.

getBusinessDetails getBusinessDetails() BusinessDetail

s

Returns the

business

details

associated

with the

waypoint.

getDisambiguationRes

ult

getDisambiguationResult() Disambiguatio

n

Returns the

result of the

waypoint

geocoding

disambiguatio

n.

getLocation getLocation() Location Returns the

215


location of the

waypoint.

getShortAddress getShortAddress() string Returns the

short address

for the

waypoint.

isExactLocation isExactLocation() boolean Returns a

boolean

indicating

whether the

waypoint

location is the

exact location.

isViapoint isViapoint() boolean 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.

setOptions setOptions(options:WaypointOptio

ns)

None Sets options

for the

waypoint. For

these options

to take effect,

you must

recalculate the

route.

216

Events


changed WaypointEventArgs Occurs when the any

properties of the waypoint

change or are updated.

geocoded WaypointEventArgs Occurs when a geocoding

request for the waypoint‟s

address is made.

reverseGeocoded WaypointEventArgs Occurs when a reverse

geocoding request for the

waypoint‟s 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).

WaypointEventArgs Object

Contains the arguments for route waypoint events.

Properties


waypoint Waypoint The waypoint for which the

event occurred.

WaypointOptions Object

Contains waypoint options.

Properties

217


address string The address of the waypoint.

Either address or location

must be specified.

businessDetails BusinessDetails The business details of the

waypoint, if it is a business.

exactLocation boolean A boolean indicating whether

the waypoint location is the

exact location. The default

value is false.

isViapoint boolean 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.

location Location The location of the waypoint.

Either address or location

must be specified.

shortAddress string The short address of the

waypoint.

WaypointRenderEventArgs Object

Contains arguments for waypoint render events.

Properties



the waypoint. You can use this




218



beforeWaypointRender event.

Set this property to true to override


waypoint Waypoint The waypoint for which the event

occurred.

Microsoft.Maps.Traffic API Reference

This section contains reference documentation for the Microsoft.Maps.Traffic API, which contains

types that allow you to display traffic on your Bing Maps AJAX Control 7.0 map.

Before you can access the types found in the Microsoft.Maps.Traffic API, you must first

load this module using the loadModule method. Information about loading modules is in

the Module Loading Methods topic.

In This Section TrafficLayer Class

TrafficLayer Class

Represents a traffic layer on the map.

Constructor


TrafficLayer TrafficLayer(map:Map) Initializes a new instance of

the TrafficLayer class.

Methods

219


getTileLayer getTileLayer() TileLayer Returns the traffic

layer.

hide hide() None Hides the traffic layer.

show show() None Displays the traffic

layer.



<html>

<head>

<title></title>





var map = null;

function GetMap()

{


"Bing Maps Key", center: new Microsoft.Maps.Location(47.5, -122.3), zoom: 9 });

Microsoft.Maps.loadModule('Microsoft.Maps.Traffic', { callback:

trafficModuleLoaded });

}

220

function trafficModuleLoaded()

{

var trafficLayer = new Microsoft.Maps.Traffic.TrafficLayer(map);

trafficLayer.show();

}

</script>

</head>



</body>

</html>

Microsoft.Maps.VenueMaps API Reference

This section contains reference documentation for the Microsoft.Maps.VenueMaps API. Use the

VenueMapFactory Class to search for available venue maps.

Before you can access the types found in the Microsoft.Maps.VenueMaps API, you must

first load this module using the loadModule method. Information about loading modules

is in the Module Loading Methods topic.

In This Section Floor Class

Footprint Class

Metadata Class

NearbyVenue Class

NearbyVenueOptions Object

Polygon Class

Primitive Class

VenueMap Class

VenueMapCreationOptions Object

221

VenueMapFactory Class

Floor Class

Represents one floor map of a venue map.

Properties


name string The name of the floor.

primitives Primitive[] An array of Primitive objects

that represent the points of

interest (for example, stores)

on this venue floor.

zoomRange double[] An array of doubles indicating

the minimum and maximum

zoom levels where imagery is

available for this venue map

floor.



<html>

<head>

<title></title>





var map = null;

222

function GetMap()

{


map = new


Microsoft.Maps.loadModule('Microsoft.Maps.VenueMaps', { callback:

venuemapsModuleLoaded });

}

function venuemapsModuleLoaded()

{

// Create the venue map

var vmaps = new Microsoft.Maps.VenueMaps.VenueMapFactory(map);

vmaps.create({venueMapId: 'bingmapsteam-bellevuesquare', success:ShowVenue,

error:ShowError});

}

function ShowVenue(venue)

{

// Set the map view

map.setView(venue.bestMapView);

venue.show();

DisplayVenueFloorInfo(venue);

}

223

function ShowError()

{

// Show an error

alert("An error occurred trying to create the venue map.");

}

function DisplayVenueFloorInfo(venue)

{

var floors = "Available floor maps for " + venue.name +":\n";

for(var i in venue.floors)

{

floors = floors + venue.floors[i].name + "\n";

}

// Display the floor info

alert(floors);

}

</script>

</head>



</body>

</html>

Footprint Class

Represents the footprint of the venue map.

224

Properties


polygons Polygon[] The shapes that make up the

footprint of this venue.

zoomRange double[] An array of doubles indicating

the minimum and maximum

zoom levels where imagery is

available for this venue map.



<html>

<head>

<title></title>





var map = null;

function GetMap()

{






}

225


{




error:ShowError});

}


{

// Set the map view


venue.show();

DisplayVenueInfo(venue);

}


{

// Show an error


}

function DisplayVenueInfo(venue)

{

var venueinfo = "Venue: " + venue.name +"\n" + "Venue Map ID: " + venue.id +

"\n" + "Venue Map Type: " + venue.type + "\n" + "Default Floor: " + venue.defaultFloor +

"\n" + "Detail Level Range for Default Floor: " + venue.footprint.zoomRange + "\n";

// Display the venue info

226

alert(venueinfo);

}

</script>

</head>



</body>

</html>

Metadata Class

Contains information about a venue map.

Properties


CenterLat number The latitude of the center

location of the venue map.

CenterLong number The longitude of the center

location of the venue map.

DefaultFloor string The ID of the default floor of

the venue map.

FloorHeader string A string used in the floor bar of

the venue map.

Floors Floor[] An array containing the floors

of the venue map.

Footprint Footprint The footprint of the venue

map.

MapId string The unique ID of the venue

map.

MapType string A string describing the venue

map type (for example, “mall”).

227


Name string The name of the venue map.

YpId string The Yellow Pages ID of the

venue.



<html>

<head>

<title></title>





var map = null;

function GetMap()

{

// Initialize the map and set the view to a specific location

map = new


center: new Microsoft.Maps.Location(47.6,-122.3), zoom:11});



}


228

{



// 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>

</html>

229

NearbyVenue Class

Defines a nearby venue map.

Properties


distance double The distance, in meters, to the

venue.

metadata Metadata The venue map metadata.



<html>

<head>

<title></title>





var map = null;

function GetMap()

{


map = new



230



}


{






}


{

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>

231

</head>



</body>

</html>

NearbyVenueOptions Object

Contains search options for retrieving nearby venue maps.

Properties


callback function The function to call when the

search is completed. The

function must accept an array

of VenueMap objects.

location Location The center of the circle in which

to search for nearby venue

maps.

map Map The base map.

radius double The radius, in meters, of the

circle in which to search for

nearby venue maps.



<html>

<head>

<title></title>


232




var map = null;

function GetMap()

{


map = new





}


{






}


{

alert("There are " + venues.length + " venue maps nearby.");

233

}

</script>

</head>



</body>

</html>

Polygon Class (Venue Map)

Defines the shape of venue map entities.

Properties


bounds LocationRect The rectangle that defines the

bounding box for the polygon.

center Location The center of the polygon.

locations Location[] The locations that define the

vertices of the polygon.

Primitive Class

Represents a venue map primitive, which represents a venue map entity.

Properties


bounds LocationRect The rectangle that defines the

bounding box for the

primitive.

234


businessId string The Yellow Pages ID for the

entity.

categoryId string The Yellow Pages business

category ID for the entity.

categoryName string The Yellow Pages business

category name for the entity.


the primitive.

floor Floor The floor to which this

primitive belongs.

id string The unique ID of the entity.

locations Location[] An array of locations that

represent the vertices of the

primitive.

name string The name of the entity.

Methods


highlight highlight() None Highlights the

primitive.

unhighlight unhighlight() None Removes the

highlighting of the

primitive.



<html>

<head>

<title></title>


235




var map = null;

var vmaps = null;

function GetMap()

{


map = new




}


{



vmaps.create({venueMapId: 'bingmapsteam-bellevuesquare', success:ShowVenue});

}


{

236

// Set the map view


venue.show();

Microsoft.Maps.Events.addHandler(venue, 'click', DisplayVenueEntity);

alert("Click on the venue map to display entity info.");

}

function DisplayVenueEntity(e)

{

alert("The name of the store that was clicked is " + e.name + ".");

}

</script>

</head>



</body>

</html>

VenueMap Class

Represents a venue map. An example of a venue map is a mall.

Properties

237


address string The full address of the venue.

bestMapView ViewOptions The best map view of the

venue map.

businessId string The Yellow Pages ID for the

venue map.


the venue map.

defaultFloor string The floor that is displayed if

no floor is specified.

floorHeader string The header for floors for this

venue map. For example, for

a mall the floor header would

be “Level”.

floors Floor[] An array, where each element

represents a floor of the

venue.

footprint Footprint The shapes that make up the

venue map.

id string The unique venue map ID.

name string The name of the venue

represented by the venue

map.

phoneNumber string The phone number for the

venue represented by the

venue map.

type string The venue map type, such as

“Mall”.

Methods


dispose dispose() None Disposes the

venue map

238


object.

getActiveFloor getActiveFloor() string Returns the

venue floor map

that is currently

displayed.

hide hide() None Hides the venue

map.

setActiveFloor setActiveFloor(venueMapId:string,

floor:string)

None Displays the

specified floor

map for the

venue map

identified by the

given ID.

show show() None Displays the

venue map.

Events


click eventArgs:Primitive Occurs when the mouse is

used to click the venue map.

close None Occurs when the close

button on the venue map is

clicked.

footprintclick eventArgs:Primitive Occurs when the detailed

map of the venue is clicked.

mouseout eventArgs:Primitive Occurs when the mouse

cursor moves out of the area

covered by the venue map.

mouseover eventArgs:Primitive Occurs when the mouse

cursor is over the venue

map.

239



<html>

<head>

<title></title>





var map = null;

var venue = null;

function GetMap()

{


map = new




}


{



vmaps.create({venueMapId: 'bingmapsteam-bellevuesquare', success:SetVenue});

240

}

function SetVenue(venueObj)

{

venue = venueObj;

}

function ShowVenue()

{

// Set the map view


venue.show();

}

function HideVenue()

{

venue.hide();

}

</script>

</head>



<input type="button" value="Show Venue Map" onclick="ShowVenue()"/><input

type="button" value="Hide Venue Map" onclick="HideVenue()"/>

</body>

</html>

241

VenueMapCreationOptions Object

Contains options for creating a venue map.

Properties


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.

venueMapId string A string that identifies the venue

map to display.

242



<html>

<head>

<title></title>





var map = null;

function GetMap()

{



credentials:"Bing Maps Key"});



}


{




error:ShowError});

}

243


{

// Set the map view


venue.show();

}


{

// Show an error


}

</script>

</head>



</body>

</html>

VenueMapFactory Class

Contains methods for creating a venue map.

Constructor


VenueMapFactory VenueMapFactory(map:Map) Initializes a new instance of

the VenueMapFactory class.

244

Methods


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.



<html>

<head>

<title></title>





245

var map = null;

function GetMap()

{






}


{



vmaps.create({venueMapId: 'bingmapsteam-bellevuesquare',

success:DisplayInfobox});

}

function DisplayInfobox(venue)

{

// Set the map view


venue.show();

// Put an info box label on the map

mapCenter = map.getTargetCenter();

var venueinfobox = new Microsoft.Maps.Infobox(mapCenter, {title: venue.name,

showPointer: false, showCloseButton:false, height: 50, width: 180, offset:new

Microsoft.Maps.Point(-220, 150)});

map.entities.push(venueinfobox);

246

}

</script>

</head>



</body>

</html>

Bing Maps AJAX Control 7.0 Supported Browsers

This topic contains information about browser support for the Bing Maps AJAX Control 7.0.

The Bing Maps AJAX Control 7.0 uses features of HTML5 if it detects that the client

browser supports HTML5. If this is the case, map performance will be faster, and map

animations and transitions will be smoother.

Supported Browsers The Bing Maps AJAX Control 7.0 is supported on the following Web browsers. If you are not

using a supported Web browser, certain features of the map control may not work.

Desktop Browser Description

Internet Explorer 7.0 Supported on the PC



Firefox 3.6 Supported on the PC and the Mac

Firefox 4.0 Supported on the PC and the Mac

Safari 5 Supported on the Mac

Google Chrome Supported on the PC

Mobile Browser

Apple 3GS/4.0 iPhone Browser

247

Mobile Browser

Google Android 2.X Browser

Research in Motion (RIM) BlackBerry 6.0

Browser

Bing Maps AJAX Control 7.0 Developer Resources

This topic contains support resources and contact information.

Developer Resources The following resources are available for Bing Maps developers:

Check out the Bing Maps AJAX Control 7.0 Interactive SDK, which allows you to test out your

own map control code.

Connect with other Bing Maps developers on the Bing Maps AJAX Control Forum.

Visit the http://www.microsoft.com/maps website.

Read the Bing Maps Developer blog

Account Issues If you are having issues creating a Bing Maps Developer Account, getting a Bing Maps Key, or

have an account access question, contact [email protected].

Licensing Questions If you are interested in finding out more about Bing Maps or have questions about licensing Bing

Maps, email [email protected] 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.


http://www.bing.com/community/forums/12284.aspx

http://www.microsoft.com/maps

http://www.bing.com/community/blogs/maps/default.aspx

mailto:[email protected]

mailto:[email protected]?subject=Bing%20Maps%20Licensing%20Question

http://www.microsoft.com/maps/resources/default.aspx

bing maps ajax

Documents

outputjsonamp

jsonproutecallbackamp

negatively

jsonpgeocodecallbackamp

mouse cursor

top left corner

bing maps

bounds takes