Embed Size (px)
Citation preview
Contents
Bing Maps AJAX Control, Version 6.3 ........................................................................................... 13
Getting Started with the Bing Maps AJAX Control ..................................................................... 14
What's New in the Map Control? ................................................................................................ 15
Version Changelist .................................................................................................................. 16
Developing with the Bing Maps AJAX Control ........................................................................... 17
Displaying a Map Using JavaScript ........................................................................................ 18
Displaying an Embedded Map ................................................................................................ 20
Controlling the Map ................................................................................................................. 22
Adding Shapes to a Map ........................................................................................................ 23
Using Routes and Directions .................................................................................................. 27
Working with Bird's Eye Images ............................................................................................. 29
Displaying 3D Maps ................................................................................................................ 31
Using Map Control Parameters .............................................................................................. 33
Returning Localized Results ................................................................................................... 34
Tracking Your Bing Maps Usage ............................................................................................ 37
Bing Map Control Performance .............................................................................................. 38
Using the Core Map Control ................................................................................................... 40
Using the REST Services with the Core Map Control ............................................................ 49
Bing Maps AJAX Control Class Reference ................................................................................ 54
VEAltitudeMode Enumeration ................................................................................................. 56
VEBirdseyeScene Class ......................................................................................................... 56
VEBirdseyeScene Methods ................................................................................................. 57
VEBirdseyeScene.ContainsLatLong Method ................................................................... 58
VEBirdseyeScene.ContainsPixel Method ........................................................................ 59
VEBirdseyeScene.GetBoundingRectangle Method ......................................................... 59
VEBirdseyeScene.GetHeight Method .............................................................................. 60
VEBirdseyeScene.GetID Method ..................................................................................... 60
VEBirdseyeScene.GetOrientation Method ...................................................................... 60
VEBirdseyeScene.GetWidth Method ............................................................................... 61
VEBirdseyeScene.LatLongToPixel Method ..................................................................... 61
VEBirdseyeScene.PixelToLatLong Method ..................................................................... 62
VEClusteringOptions Class .................................................................................................... 62
VEClusteringOptions Constructor ....................................................................................... 63
VEClusteringOptions Properties .......................................................................................... 63
VEClusteringOptions.Icon Property ................................................................................. 64
VEClusteringOptions.Callback Property .......................................................................... 64
VEClusteringType Enumeration ............................................................................................. 64
VEClusterSpecification Class ................................................................................................. 65
VEClusterSpecification Methods ......................................................................................... 65
VEClusterSpecification.GetClusterShape Method ........................................................... 65
VEClusterSpecification Properties ...................................................................................... 66
VEClusterSpecification.Shapes Property......................................................................... 66
VEClusterSpecification.LatLong Property ........................................................................ 66
VEColor Class ......................................................................................................................... 66
VEColor Constructor............................................................................................................ 67
VEColor Properties .............................................................................................................. 68
VEColor.A Property .......................................................................................................... 68
VEColor.B Property .......................................................................................................... 69
VEColor.G Property ......................................................................................................... 69
VEColor.R Property.......................................................................................................... 69
VECustomIconSpecification Class ......................................................................................... 69
VECustomIconSpecification Constructor ............................................................................ 71
VECustomIconSpecification Properties............................................................................... 71
VECustomIconSpecification.BackColor Property ............................................................ 72
VECustomIconSpecification.CustomHTML Property ....................................................... 72
VECustomIconSpecification.ForeColor Property ............................................................. 72
VECustomIconSpecification.Image Property ................................................................... 73
VECustomIconSpecification.ImageOffset Property ......................................................... 73
VECustomIconSpecification.TextBold Property ............................................................... 73
VECustomIconSpecification.TextContent Property ......................................................... 73
VECustomIconSpecification.TextFont Property ............................................................... 73
VECustomIconSpecification.TextItalics Property ............................................................. 74
VECustomIconSpecification.TextOffset Property ............................................................ 74
VECustomIconSpecification.TextSize Property ............................................................... 74
VECustomIconSpecification.TextUnderline Property ...................................................... 74
VEDashboardSize Enumeration ............................................................................................. 74
VEDataType Enumeration ...................................................................................................... 75
VEDistanceUnit Enumeration ................................................................................................. 77
VEException Class ................................................................................................................. 78
VEException Properties ...................................................................................................... 79
VEException.message Property ...................................................................................... 79
VEException.name Property ............................................................................................ 79
VEException.source Property .......................................................................................... 79
VEFailedShapeRequest Enumeration .................................................................................... 79
VEFindResult Class ................................................................................................................ 80
VEFindResult Properties ..................................................................................................... 81
VEFindResult.Description Property ................................................................................. 81
VEFindResult.IsSponsored Property ............................................................................... 81
VEFindResult.LatLong Property ...................................................................................... 82
VEFindResult.Name Property .......................................................................................... 82
VEFindResult.Phone Property ......................................................................................... 82
VEFindResult.FindType Property .................................................................................... 82
VEFindResult.Shape Property ......................................................................................... 82
VEFindType Enumeration ....................................................................................................... 83
VEGeocodeLocation Class ..................................................................................................... 83
VEGeocodeLocation Properties .......................................................................................... 84
VEGeocodeLocation.LatLong Property ........................................................................... 84
VEGeocodeLocation.Precision Property.......................................................................... 84
VEGeocodeOptions Class ...................................................................................................... 84
VEGeocodeOptions Constructor ......................................................................................... 85
VEGeocodeOptions Properties ........................................................................................... 85
VEGeocodeOptions.SetBestMapView Property .............................................................. 86
VEGeocodeOptions.UseDefaultDisambiguation Property ............................................... 86
VEImageryMetadata Class ..................................................................................................... 86
VEImageryMetadata Properties .......................................................................................... 86
VEImageryMetadata.DateRangeStart Property ............................................................... 87
VEImageryMetadata.DateRangeEnd Property ................................................................ 87
VEImageryMetadataOptions Class ......................................................................................... 87
VEImageryMetadataOptions Constructor ........................................................................... 88
VEImageryMetadataOptions Properties .............................................................................. 88
VEImageryMetadataOptions.LatLong Property ............................................................... 89
VEImageryMetadataOptions.MapStyle Property ............................................................. 89
VEImageryMetadataOptions.ZoomLevel Property .......................................................... 89
VELatLong Class .................................................................................................................... 90
VELatLong Constructor ....................................................................................................... 90
VELatLong Properties ......................................................................................................... 91
VELatLong.Altitude Property ............................................................................................ 92
VELatLong.AltitudeMode Property ................................................................................... 92
VELatLong.Latitude Property ........................................................................................... 92
VELatLong.Longitude Property ........................................................................................ 92
VELatLong Methods ............................................................................................................ 93
VELatLong.SetAltitude Method ........................................................................................ 93
VELatLongRectangle Class .................................................................................................... 93
VELatLongRectangle Constructor ....................................................................................... 94
VELatLongRectangle Properties ......................................................................................... 95
VELatLongRectangle.BottomLeftLatLong Property ......................................................... 95
VELatLongRectangle.BottomRightLatLong Property ...................................................... 96
VELatLongRectangle.TopLeftLatLong Property .............................................................. 96
VELatLongRectangle.TopRightLatLong Property ............................................................ 96
VELocationPrecision Enumeration ......................................................................................... 96
VEMap Class .......................................................................................................................... 97
VEMap Constructor ........................................................................................................... 104
VEMap Events ................................................................................................................... 105
Keyboard Events ............................................................................................................ 105
VEMap.onkeypress Event .......................................................................................... 106
VEMap.onkeydown Event .......................................................................................... 106
VEMap.onkeyup Event ............................................................................................... 107
Mouse Events ................................................................................................................ 108
VEMap.onclick Event .................................................................................................. 109
VEMap.ondoubleclick Event ....................................................................................... 111
VEMap.onmousedown Event ..................................................................................... 113
VEMap.onmousemove Event ..................................................................................... 115
VEMap.onmouseout Event ......................................................................................... 116
VEMap.onmouseover Event ....................................................................................... 118
VEMap.onmouseup Event .......................................................................................... 119
VEMap.onmousewheel Event .................................................................................... 121
Bing Maps Events .......................................................................................................... 122
VEMap.onchangemapstyle Event .............................................................................. 124
VEMap.onchangeview Event ...................................................................................... 124
VEMap.oncredentialserror Event ................................................................................ 125
VEMap.oncredentialsvalid Event ................................................................................ 126
VEMap.onendpan Event ............................................................................................. 127
VEMap.onendzoom Event .......................................................................................... 127
VEMap.onerror Event ................................................................................................. 128
VEMap.oninitmode Event ........................................................................................... 129
VEMap.onmodenotavailable Event ............................................................................ 129
VEMap.onobliquechange Event ................................................................................. 130
VEMap.onobliqueenter Event ..................................................................................... 131
VEMap.onobliqueleave Event .................................................................................... 131
VEMap.onresize Event ............................................................................................... 132
VEMap.onstartpan Event ............................................................................................ 133
VEMap.onstartzoom Event ......................................................................................... 133
VEMap.ontokenerror Event ........................................................................................ 134
VEMap.ontokenexpire Event ...................................................................................... 135
VEMap Event Object Properties .................................................................................... 136
VEMap Methods ................................................................................................................ 138
VEMap.AddControl Method ........................................................................................... 145
VEMap.AddCustomLayer Method ................................................................................. 146
VEMap.AddShape Method ............................................................................................ 146
VEMap.AddShapeLayer Method ................................................................................... 147
VEMap.AddTileLayer Method ........................................................................................ 147
VEMap.AttachEvent Method .......................................................................................... 148
VEMap.Clear Method ..................................................................................................... 149
VEMap.ClearInfoBoxStyles Method ............................................................................... 149
VEMap.ClearTraffic Method ........................................................................................... 151
VEMap.DeleteAllShapeLayers Method.......................................................................... 152
VEMap.DeleteAllShapes Method ................................................................................... 152
VEMap.DeleteControl Method ....................................................................................... 152
VEMap.DeleteRoute Method ......................................................................................... 153
VEMap.DeleteShape Method ........................................................................................ 153
VEMap.DeleteShapeLayer Method ............................................................................... 153
VEMap.DeleteTileLayer Method .................................................................................... 154
VEMap.DetachEvent Method ......................................................................................... 154
VEMap.Dispose Method ................................................................................................ 155
VEMap.EnableShapeDisplayThreshold Method ............................................................ 155
VEMap.EndContinuousPan Method .............................................................................. 156
VEMap.Find Method ...................................................................................................... 156
VEMap.FindLocations Method ....................................................................................... 159
VEMap.Geocode Method ............................................................................................... 160
VEMap.GetAltitude Method ........................................................................................... 161
VEMap.GetBirdseyeScene Method ............................................................................... 161
VEMap.GetCenter Method ............................................................................................. 162
VEMap.GetDirections Method ....................................................................................... 162
VEMap.GetHeading Method .......................................................................................... 163
VEMap.GetImageryMetadata Method ........................................................................... 164
VEMap.GetLeft Method ................................................................................................. 165
VEMap.GetMapMode Method ....................................................................................... 165
VEMap.GetMapStyle Method ........................................................................................ 165
VEMap.GetMapView Method ......................................................................................... 165
VEMap.GetPitch Method ............................................................................................... 166
VEMap.GetRoute Method .............................................................................................. 166
VEMap.GetShapeByID Method ..................................................................................... 167
VEMap.GetShapeLayerByIndex Method ....................................................................... 168
VEMap.GetShapeLayerCount Method .......................................................................... 168
VEMap.GetTileLayerByID Method ................................................................................. 169
VEMap.GetTileLayerByIndex Method............................................................................ 169
VEMap.GetTileLayerCount Method ............................................................................... 170
VEMap.GetTop Method ................................................................................................. 170
VEMap.GetVersion Method ........................................................................................... 170
VEMap.GetZoomLevel Method ...................................................................................... 171
VEMap.Hide3DNavigationControl Method .................................................................... 171
VEMap.HideAllShapeLayers Method............................................................................. 171
VEMap.HideBaseTileLayer Method ............................................................................... 172
VEMap.HideControl Method .......................................................................................... 172
VEMap.HideDashboard Method .................................................................................... 172
VEMap.HideFindControl Method ................................................................................... 173
VEMap.HideInfoBox Method .......................................................................................... 173
VEMap.HideMiniMap Method ........................................................................................ 173
VEMap.HideScalebar Method ........................................................................................ 174
VEMap.HideTileLayer Method ....................................................................................... 174
VEMap.HideTrafficLegend Method ................................................................................ 174
VEMap.Import3DModel Method ..................................................................................... 175
VEMap.ImportShapeLayerData Method ........................................................................ 176
VEMap.IncludePointInView Method ............................................................................... 177
VEMap.IsBirdseyeAvailable Method .............................................................................. 177
VEMap.LatLongToPixel Method .................................................................................... 178
VEMap.LoadMap Method .............................................................................................. 179
VEMap.LoadTraffic Method ........................................................................................... 180
VEMap.Pan Method ....................................................................................................... 181
VEMap.PanToLatLong Method ...................................................................................... 181
VEMap.PixelToLatLong Method .................................................................................... 182
VEMap.RemoveCustomLayer Method .......................................................................... 182
VEMap.Resize Method .................................................................................................. 183
VEMap.Search Method .................................................................................................. 183
VEMap.SetAltitude Method ............................................................................................ 184
VEMap.SetBirdseyeOrientation Method ........................................................................ 185
VEMap.SetBirdseyeScene Method ................................................................................ 185
VEMap.SetBirdseyeScene(id) Method ....................................................................... 186
VEMap.SetBirdseyeScene(veLatLong, orientation, zoomLevel, callback) Method ... 186
VEMap.SetCenter Method ............................................................................................. 187
VEMap.SetCenterAndZoom Method ............................................................................. 187
VEMap.SetClientToken Method ..................................................................................... 188
VEMap.SetCredentials Method ...................................................................................... 189
VEMap.SetDashboardSize Method ............................................................................... 189
VEMap.SetDefaultInfoBoxStyles Method ...................................................................... 190
VEMap.SetFailedShapeRequest Method ...................................................................... 190
VEMap.SetHeading Method .......................................................................................... 191
VEMap.SetMapMode Method ........................................................................................ 191
VEMap.SetMapStyle Method ......................................................................................... 192
VEMap.SetMapView Method ......................................................................................... 192
VEMap.SetMouseWheelZoomToCenter Method .......................................................... 193
VEMap.SetPitch Method ................................................................................................ 193
VEMap.SetPrintOptions Method .................................................................................... 194
VEMap.SetScaleBarDistanceUnit Method ..................................................................... 195
VEMap.SetShapesAccuracy Method ............................................................................. 195
VEMap.SetShapesAccuracyRequestLimit Method ........................................................ 196
VEMap.SetTileBuffer Method ........................................................................................ 196
VEMap.SetTrafficLegendText Method ........................................................................... 197
VEMap.SetZoomLevel Method ...................................................................................... 197
VEMap.Show3DBirdseye Method .................................................................................. 198
VEMap.Show3DNavigationControl Method ................................................................... 199
VEMap.ShowAllShapeLayers Method ........................................................................... 199
VEMap.ShowBaseTileLayer Method ............................................................................. 199
VEMap.ShowControl Method ......................................................................................... 200
VEMap.ShowDashboard Method ................................................................................... 200
VEMap.ShowDisambiguationDialog Method ................................................................. 200
VEMap.ShowFindControl Method .................................................................................. 201
VEMap.ShowInfoBox Method ........................................................................................ 202
VEMap.ShowMessage Method ...................................................................................... 202
VEMap.ShowMiniMap Method ....................................................................................... 203
VEMap.ShowScalebar Method ...................................................................................... 203
VEMap.ShowTileLayer Method ..................................................................................... 204
VEMap.ShowTrafficLegend Method .............................................................................. 204
VEMap.StartContinuousPan Method ............................................................................. 205
VEMap.ZoomIn Method ................................................................................................. 206
VEMap.ZoomOut Method .............................................................................................. 206
VEMap Properties ............................................................................................................. 206
VEMap.onLoadMap Property ......................................................................................... 207
VEMapMode Enumeration .................................................................................................... 207
VEMapOptions Class ............................................................................................................ 208
VEMapOptions Constructor ............................................................................................... 210
VEMapOptions Properties ................................................................................................. 210
VEMapOptions.BirdseyeOrientation Property ............................................................... 212
VEMapOptions.DashboardColor Property ..................................................................... 212
VEMapOptions.EnableBirdseye Property ...................................................................... 212
VEMapOptions.EnableClickableLogo Property ............................................................. 213
VEMapOptions.EnableDashboardLabels Property ........................................................ 213
VEMapOptions.EnableSearchLogo Property ................................................................ 213
VEMapOptions.LoadBaseTiles Property ....................................................................... 213
VEMapOptions.UseEnhancedRoadStyle Property ........................................................ 214
VEMapStyle Enumeration ..................................................................................................... 214
VEMapViewSpecification Class ............................................................................................ 215
VEMapViewSpecification Constructor ............................................................................... 215
VEMatchCode Enumeration ................................................................................................. 216
VEMatchConfidence Enumeration........................................................................................ 217
VEMiniMapSize Enumeration ............................................................................................... 217
VEModelFormat Enumeration .............................................................................................. 218
VEModelOrientation Class .................................................................................................... 219
VEModelOrientation Constructor ....................................................................................... 220
VEModelOrientation Properties ......................................................................................... 221
VEModelOrientation.Heading Property .......................................................................... 221
VEModelOrientation.Roll Property ................................................................................. 221
VEModelOrientation.Tilt Property .................................................................................. 222
VEModelScale Class ............................................................................................................ 222
VEModelScale Constructor ............................................................................................... 223
VEModelScale Properties ................................................................................................. 224
VEModelScale.X Property ............................................................................................. 224
VEModelScale.Y Property ............................................................................................. 224
VEModelScale.Z Property .............................................................................................. 224
VEModelScaleUnit Enumeration .......................................................................................... 225
VEModelSourceSpecification Class ..................................................................................... 225
VEModelSourceSpecification Constructor ........................................................................ 226
VEModelSourceSpecification Properties .......................................................................... 226
VEModelSourceSpecification.Format Property ............................................................. 227
VEModelSourceSpecification.Layer Property ................................................................ 227
VEModelSourceSpecification.ModelSource Property .................................................... 227
VEModelStatusCode Enumeration ....................................................................................... 227
VEOrientation Enumeration .................................................................................................. 228
VEPixel Class ....................................................................................................................... 228
VEPixel Constructor .......................................................................................................... 229
VEPixel Properties............................................................................................................. 229
VEPixel.x Property ......................................................................................................... 230
VEPixel.y Property ......................................................................................................... 230
VEPlace Class ...................................................................................................................... 230
VEPlace Properties ........................................................................................................... 231
VEPlace.LatLong Property ............................................................................................. 232
VEPlace.Locations Property .......................................................................................... 232
VEPlace.MatchCode Property ....................................................................................... 232
VEPlace.MatchConfidence Property.............................................................................. 233
VEPlace.Name Property ................................................................................................ 233
VEPlace.Precision Property ........................................................................................... 233
VEPrintOptions Class ........................................................................................................... 233
VEPrintOptions Constructor .............................................................................................. 234
VEPrintOptions Properties ................................................................................................ 235
VEPrintOptions.EnablePrinting Property ....................................................................... 235
VERoute Class ...................................................................................................................... 235
VERoute Properties ........................................................................................................... 236
VERoute.Distance Property ........................................................................................... 236
VERoute.RouteLegs Property ........................................................................................ 237
VERoute.ShapePoints Property ..................................................................................... 237
VERoute.Time Property ................................................................................................. 237
VERouteDeprecated Class ................................................................................................... 237
VERouteDeprecated Properties ........................................................................................ 238
VERouteDeprecated.EndLocation Property .................................................................. 238
VERouteDeprecated.Itinerary Property ......................................................................... 238
VERouteDeprecated.StartLocation Property ................................................................. 239
VERouteDistanceUnit Enumeration ...................................................................................... 239
VERouteHint Class ............................................................................................................... 239
VERouteHint Properties .................................................................................................... 240
VERouteHint.Type Property ........................................................................................... 240
VERouteHint.Text Property ............................................................................................ 240
VERouteHintType Enumeration ............................................................................................ 241
VERouteItinerary Class ........................................................................................................ 241
VERouteItinerary Properties .............................................................................................. 242
VERouteItinerary.Items Property ................................................................................... 242
VERouteItineraryDeprecated Class ...................................................................................... 242
VERouteItineraryDeprecated Properties ........................................................................... 243
VERouteItineraryDeprecated.Distance Property ........................................................... 243
VERouteItineraryDeprecated.DistanceUnit Property ..................................................... 243
VERouteItineraryDeprecated.RouteType Property ........................................................ 243
VERouteItineraryDeprecated.Segments Property ......................................................... 243
VERouteItineraryDeprecated.Time Property ................................................................. 244
VERouteItineraryItem Class ................................................................................................. 244
VERouteItineraryItem Properties ....................................................................................... 245
VERouteItineraryItem.Distance Property ....................................................................... 245
VERouteItineraryItem.LatLong Property ........................................................................ 246
VERouteItineraryItem.Shape Property ........................................................................... 246
VERouteItineraryItem.Text Property .............................................................................. 246
VERouteItineraryItem.Time Property ............................................................................. 246
VERouteItineraryItem.Warnings Property ...................................................................... 246
VERouteItineraryItem.Hints Property ............................................................................. 246
VERouteLeg Class................................................................................................................ 247
VERouteLeg Properties ..................................................................................................... 247
VERouteLeg.Distance Property ..................................................................................... 248
VERouteLeg.Itinerary Property ...................................................................................... 248
VERouteLeg.Time Property ........................................................................................... 248
VERouteLocation Class ........................................................................................................ 248
VERouteLocation Properties ............................................................................................. 249
VERouteLocation.Address Property .............................................................................. 249
VERouteLocation.LatLong Property .............................................................................. 249
VERouteMode Enumeration ................................................................................................. 249
VERouteOptimize Enumeration ............................................................................................ 250
VERouteOptions Class ......................................................................................................... 250
VERouteOptions Constructor ............................................................................................ 252
VERouteOptions Properties .............................................................................................. 252
VERouteOptions.DistanceUnit Property ........................................................................ 253
VERouteOptions.DrawRoute Property ........................................................................... 253
VERouteOptions.RouteCallback Property ..................................................................... 254
VERouteOptions.RouteColor Property .......................................................................... 254
VERouteOptions.RouteMode Property .......................................................................... 254
VERouteOptions.RouteOptimize Property ..................................................................... 254
VERouteOptions.RouteWeight Property ........................................................................ 255
VERouteOptions.RouteZIndex Property ........................................................................ 255
VERouteOptions.SetBestMapView Property ................................................................. 255
VERouteOptions.ShowDisambiguation Property ........................................................... 255
VERouteOptions.ShowErrorMessages Property ........................................................... 256
VERouteOptions.UseMWS Property ............................................................................. 256
VERouteOptions.UseTraffic Property ............................................................................ 256
VERouteSegment Class ....................................................................................................... 257
VERouteSegment Properties ............................................................................................ 258
VERouteSegment.Instruction Property .......................................................................... 258
VERouteSegment.LatLong Property.............................................................................. 258
VERouteSegment.Distance Property............................................................................. 258
VERouteType Enumeration .................................................................................................. 259
VERouteWarning Class ........................................................................................................ 259
VERouteWarning Properties ............................................................................................. 260
VERouteWarning.Severity Property ............................................................................... 260
VERouteWarning.Text Property ..................................................................................... 260
VERouteWarningSeverity Enumeration ............................................................................... 260
VESearchOptions Class ....................................................................................................... 261
VESearchOptions Constructor .......................................................................................... 262
VESearchOptions Properties ............................................................................................ 263
VESearchOptions.BoundingRectangle Property ........................................................... 264
VESearchOptions.CreateResults Property .................................................................... 264
VESearchOptions.FindType Property ............................................................................ 264
VESearchOptions.NumberOfResults Property .............................................................. 264
VESearchOptions.SetBestMapView Property ............................................................... 265
VESearchOptions.ShapeLayer Property ....................................................................... 265
VESearchOptions.ShowResults Property ...................................................................... 265
VESearchOptions.StartIndex Property .......................................................................... 265
VESearchOptions.UseDefaultDisambiguation Property ................................................ 265
VEShape Class ..................................................................................................................... 266
VEShape Constructor ........................................................................................................ 269
VEShape Events ............................................................................................................... 270
VEShape.ondrag Event ................................................................................................. 270
VEShape.onenddrag Event ........................................................................................... 271
VEShape.onstartdrag Event .......................................................................................... 271
VEShape Methods............................................................................................................. 272
VEShape.GetAltitude Method ........................................................................................ 274
VEShape.GetAltitudeMode Method ............................................................................... 275
VEShape.GetCustomIcon Method ................................................................................. 275
VEShape.GetDescription Method .................................................................................. 276
VEShape.GetFillColor Method ....................................................................................... 276
VEShape.GetIconAnchor Method .................................................................................. 277
VEShape.GetID Method ................................................................................................ 277
VEShape.GetLineColor Method ..................................................................................... 277
VEShape.GetLineToGround Method ............................................................................. 278
VEShape.GetLineWidth Method .................................................................................... 278
VEShape.GetMaxZoomLevel Method ........................................................................... 278
VEShape.GetMinZoomLevel Method ............................................................................ 279
VEShape.GetMoreInfoURL Method ............................................................................... 279
VEShape.GetPhotoURL Method ................................................................................... 280
VEShape.GetPoints Method .......................................................................................... 280
VEShape.GetShapeLayer Method ................................................................................. 280
VEShape.GetTitle Method ............................................................................................. 281
VEShape.GetType Method ............................................................................................ 281
VEShape.GetZIndex Method ......................................................................................... 281
VEShape.GetZIndexPolyShape Method ....................................................................... 282
VEShape.Hide Method .................................................................................................. 282
VEShape.HideIcon Method ............................................................................................ 282
VEShape.IsModel Method ............................................................................................. 283
VEShape.SetAltitude Method ........................................................................................ 283
VEShape.SetAltitudeMode Method ............................................................................... 284
VEShape.SetCustomIcon Method ................................................................................. 284
VEShape.SetDescription Method .................................................................................. 285
VEShape.SetFillColor Method ....................................................................................... 286
VEShape.SetIconAnchor Method .................................................................................. 287
VEShape.SetLineColor Method ..................................................................................... 287
VEShape.SetLineToGround Method ............................................................................. 288
VEShape.SetLineWidth Method .................................................................................... 288
VEShape.SetMaxZoomLevel Method ............................................................................ 289
VEShape.SetMinZoomLevel Method ............................................................................. 289
VEShape.SetMoreInfoURL Method ............................................................................... 290
VEShape.SetPhotoURL Method .................................................................................... 290
VEShape.SetPoints Method .......................................................................................... 291
VEShape.SetTitle Method .............................................................................................. 291
VEShape.SetZIndex Method ......................................................................................... 292
VEShape.Show Method ................................................................................................. 293
VEShape.ShowIcon Method .......................................................................................... 294
VEShape Properties .......................................................................................................... 294
VEShape.Draggable Property ........................................................................................ 294
VEShapeLayer Class ............................................................................................................ 295
VEShapeLayer Constructor ............................................................................................... 296
VEShapeLayer Methods ................................................................................................... 297
VEShapeLayer.AddShape Method ................................................................................ 298
VEShapeLayer.DeleteAllShapes Method ...................................................................... 299
VEShapeLayer.DeleteShape Method ............................................................................ 299
VEShapeLayer.GetBoundingRectangle Method ........................................................... 299
VEShapeLayer.GetClusteredShapes Method ............................................................... 300
VEShapeLayer.GetDescription Method ......................................................................... 300
VEShapeLayer.GetShapeByID Method ......................................................................... 301
VEShapeLayer.GetShapeByIndex Method ................................................................... 301
VEShapeLayer.GetShapeCount Method ....................................................................... 302
VEShapeLayer.GetTitle Method .................................................................................... 302
VEShapeLayer.Hide Method ......................................................................................... 302
VEShapeLayer.IsVisible Method ................................................................................... 303
VEShapeLayer.SetClusteringConfiguration Method ...................................................... 303
VEShapeLayer.SetClusteringConfiguration(type, options) Method ........................... 303
VEShapeLayer.SetClusteringConfiguration(algorithm, options) Method ................... 304
VEShapeLayer.SetDescription Method ......................................................................... 305
VEShapeLayer.SetTitle Method ..................................................................................... 305
VEShapeLayer.Show Method ........................................................................................ 306
VEShapeAccuracy Enumeration .......................................................................................... 306
VEShapeSourceSpecification Class ..................................................................................... 307
VEShapeSourceSpecification Constructor ........................................................................ 308
VEShapeSourceSpecification Properties .......................................................................... 308
VEShapeSourceSpecification.Layer Property ............................................................... 309
VEShapeSourceSpecification.LayerSource Property .................................................... 309
VEShapeSourceSpecification.MaxImportedShapes Property ....................................... 309
VEShapeSourceSpecification.Type Property ................................................................ 310
VEShapeType Enumeration ................................................................................................. 310
VETileSourceSpecification Class ......................................................................................... 310
VETileSourceSpecification Constructor ............................................................................ 311
VETileSourceSpecification Properties............................................................................... 312
VETileSourceSpecification.Bounds Property ................................................................. 313
VETileSourceSpecification.GetTilePath Property .......................................................... 313
VETileSourceSpecification.ID Property ......................................................................... 314
VETileSourceSpecification.MaxZoomLevel Property .................................................... 314
VETileSourceSpecification.MinZoomLevel Property ..................................................... 314
VETileSourceSpecification.NumServers Property ......................................................... 315
VETileSourceSpecification.Opacity Property ................................................................. 315
VETileSourceSpecification.TileSource Property ............................................................ 315
VETileSourceSpecification.ZIndex Property .................................................................. 316
Bing Maps AJAX Control Troubleshooting and Support .......................................................... 316
13
Bing Maps AJAX Control, Version 6.3
Bing Maps™ is an online mapping service that enables users to search, discover, explore, plan,
and share information about specific locations. By using traditional road maps, labeled aerial
photo views, low-angle high-resolution aerial photos, and proximity searching capabilities, Bing
Maps provides unique opportunities for developers to incorporate both location and local search
features into their Web applications.
The Bing Maps AJAX Control 6.3 software development kit (SDK), Version 6.3 consists of a
complete set of reference topics that cover the Bing Maps AJAX Control 6.3 application
programming interface (API). You can find information about the newest Bing Maps AJAX
Control, Version 7.0, in the Version 7.0 SDK.
Bing Maps also provides an Interactive SDK available at
http://www.microsoft.com/maps/isdk/ajax. The Interactive SDK offers hands-on, task-based
demonstrations of features available in the version 6.3 API release, complete with code samples
and links back to the reference SDK.
If you are reading this SDK online, you can download the Bing Maps AJAX Control SDK CHM file
or PDF file for offline viewing.
Information about Microsoft's customer identification requirements can be found in the Getting
Started with the Bing Maps AJAX Control topic or the Implementing Customer Identification
article found in Bing Maps Articles.
The Bing Maps Silverlight Control, the Bing Maps SOAP Services, and the Bing Maps REST
Services are also available for users looking to integrate location intelligence into their Web
applications. More information about available Bing Maps APIs is found in the Getting Started
with Bing Maps topic.
In This Section Getting Started with the Bing Maps AJAX Control
What's New in the Map Control?
Developing with the Bing Maps AJAX Control
Bing Maps AJAX Control Class Reference
Troubleshooting and Support
See Also Terms and Conditions
14
Getting Started with the Bing Maps AJAX Control The Bing Maps™ map control 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 6.3.
Get Familiar with the Bing Maps AJAX Control
The Developing with the Bing Maps AJAX Control section of this SDK contains topics that
describe how to use the features provided by the AJAX map control. For information about
displaying a map on your Web page, see the Displaying a Map Using JavaScript topic or the
Displaying an Embedded Map topic.
Register Your Map Control Application
Create a Bing Maps Account and Get a Key
Once you have created your Bing Maps AJAX Control 6.3 application, you need to register this
application using the Bing Maps Account Center. The Bing Maps Account Center allows you to
create a developer account and get a Bing Maps Key for use in your application. These steps are
described in the Getting a Bing Maps Key topic.
Use the
After you have created a Bing Maps Account, available Bing Maps Keys appear in the Bing Maps
Account Center. Copy the key associated with the Web site URL which corresponds to the
application you are building and use this string value in the VEMap.SetCredentials Method as
shown in the example below.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>SetCredentials</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=6.3"></script>
<script type="text/javascript">
var map = null;
15
function GetMap()
{
map = new VEMap('myMap');
map.SetCredentials("Your Bing Maps Key");
map.LoadMap();
}
</script>
</head>
<body onload="GetMap();">
<div id='myMap' style="position:relative; width:600px; height:400px;"></div>
</body>
</html>
Session Counting
When the Bing Maps AJAX Control 6.3 is loaded with a valid Bing Maps Key, Bing Maps counts
sessions. A session begins with the load of the Bing Maps AJAX Control 6.3 into a user’s browser
and includes all Bing Maps AJAX Control 6.3 interactions until the browser is closed or the user
moves to a different page. Information about Bing Maps usage reports is in Viewing Bing Maps
Usage Reports.
If you are using tokens retrieved from the Bing Maps Token Service in your Bing Maps
AJAX Control 6.3 application, transaction definitions can be found in the Viewing Bing
Maps Transaction Reports topic.
See Also
VEMap.SetCredentials Method
VEMap.oncredentialserror Event
VEMap.oncredentialsvalid Event
What's New in the Map Control? Welcome to the latest release of the Bing Maps AJAX Control 6.3. This is an overview of the new
features in this release. For a detailed list of API changes, see the Version Changelist topic.
16
You can find information about the latest updates to the newest Bing Maps AJAX Control,
Version 7.0, in the Version 7.0 SDK.
New Features
This release of the map control includes the following new features:
Core functionality version of the map control. The Bing Maps AJAX Control 6.3 is now
available in both full functionality and core functionality versions. If you do not need enhanced
map features, you can improve the performance of your application by using the core version
of the latest map control. See the Using the Core Map Control topic for more information.
Geocoding and search capabilities are available from the Bing Maps REST Web Services,
which you can use in conjunction with the core map control as described in the Using the
REST Services with the Core Map Control topic.
New Search and Geocode methods. The new VEMap.Search Method and the
VEMap.Geocode Method provide an easier way to return the most accurate search results.
Drag-able pushpins With the latest version of the Bing Maps AJAX Control 6.3, your
pushpins become drag-able by simply setting the VEShape.Draggable Property of the
pushpin to true.
New map options. The color of the map dashboard, or navigation control, can now be
changed to black using the VEMapOptions.DashboardColor Property. In addition, give your
users easy access to search functionality by enabling the BingTM
hovering search logo using
the VEMapOptions.EnableSearchLogo Property and VEMapOptions.EnableClickableLogo
Property.
New enhanced road map style. Bing Maps introduced a new enhanced road map style,
which is in use on http://www.bing.com/maps. This style is designed to improve readability
and interaction for imagery with data overlays. On July 6, 2011, this new enhanced road map
style became the default and only road style available for all Bing Maps APIs.
Version Changelist
This topic describes the changes in the 6.3 release of the Bing Maps AJAX Control 6.3 SDK.
New Map Control Elements
The following API members are new in the 6.3 release of the map control.
Name Description
VEGeocodeOptions Class Contains additional geocoding options for the
VEMap.Geocode Method.
VEMap.Geocode Method Finds a geographic location based on a
specified address or place name string as well
as other geocoding options.
17
Name Description
VEMap.Search Method Performs a search based on a given query and
options.
VEMapOptions.DashboardColor Property A String that specifies whether the map
dashboard, or navigation control, is colored
blue or black. Valid values are ―blue‖ or ―black‖.
The default value is ―blue‖.
VEMapOptions.EnableClickableLogo Property A Boolean value indicating whether the BingTM
logo on the map is clickable. The default value
is false.
VEMapOptions.EnableSearchLogo Property A Boolean value indicating whether to enable
the BingTM
hovering search logo on the map.
The default value is false.
VEMapOptions.UseEnhancedRoadStyle
Property
A Boolean value indicating whether to use the
enhanced road map style. The default value is
false.
VESearchOptions Class Contains additional search options for the
VEMap.Search Method.
VEShape.Draggable Property A Boolean value indicating whether the
VEShape icon on the map can be dragged
using the mouse.
VEShape.ondrag Event Occurs when a shape is being dragged across
the map.
VEShape.onenddrag Event Occurs when a shape drag has stopped.
VEShape.onstartdrag Event Occurs when the user starts dragging the
shape.
Developing with the Bing Maps AJAX Control The Bing Maps™ map control is a JavaScript control that contains the objects, methods, and
events that you need to display maps powered by Bing Maps on your Web site.
Using the
The topics in this section provide a walkthrough to help you start using the map control.
Displaying a Map Using JavaScript
Displaying an Embedded Map
18
Controlling the Map
Adding Shapes to a Map
Using Routes and Directions
Working with Bird's Eye Images
Displaying 3D Maps
Using Map Control Parameters
Returning Localized Results
Tracking Your Bing Maps Usage
Bing Map Control Performance
Using the Core Map Control
Using the REST Services with the Core Map Control
Displaying a Map Using JavaScript
This topic describes using JavaScript to load the Bing Maps AJAX Control 6.3 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.
If you do not need the full functionality of the Bing Maps AJAX Control 6.3 and just want
to display a simple map on your Web page, you can use the embedded map feature of
the map control. This is described in the Displaying an Embedded Map topic.
Also note that you can use the core version of the map control to enhance the
performance of your map control. See Using the Core 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.
19
<script charset="UTF-8" type="text/javascript"
src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?
v=6.3&mkt=en-us">
</script>
More information about using the mkt attribute to set the culture of the map is found
in the Returning Localized Results topic.
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='myMap' 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="map" class="map"></div>
If you do not specify a width, a default width of 600 pixels is used. The default height
is 400 pixels. 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.
5. Create a new instance of the VEMap Class and call the VEMap.LoadMap Method, as follows.
var map = new VEMap('myMap');
map.LoadMap();
In most cases you must call the call LoadMap method before you call a VEMap
method or attempt to access a VEMap property. The exceptions, which you must call
20
after creating the new VEMap object but before you call the LoadMap method on
that object, are:
VEMap.onLoadMap Property
VEMap.SetDashboardSize Method
Customizing the Map When Loading
You can also specify the location, zoom level, and map style of the map when you first load it. To
do this, use the overloaded VEMap.LoadMap Method function as follows to pass in the location,
zoom level, map style, whether the map is locked, map mode, whether to show the map mode
switch, and how much of a tile buffer to display around the map.
var map = new VEMap('myMap');
map.LoadMap(new VELatLong(47.6, -122.33, 0, VEAltitudeMode.RelativeToGround), 10,
VEMapStyle.Road, false, VEMapMode.Mode2D, true, 1);
Example
A complete Web page with all of the elements required to show a map may look like the following.
VirtualEarthSDK#0
See Also
Controlling the Map
Displaying an Embedded Map
This topic describes how to put simple map onto your Web page.
If you want the full functionality of the Bing Maps AJAX Control 6.3, then you need to use
JavaScript to load the map control into your Web page. This is described in the
Displaying a Map Using JavaScript topic.
You can also use the core version of the map control. See Using the Core Map Control.
Add a Simple Map
To embed a map into your Web page, add an iframe tag to your Web page and set the src
parameter to the embedded map URL. The following code adds a simple Road map to a Web
page.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Embedded Map</title>
21
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body style="font-family:Arial">
<p>A simple embedded map.</p>
<iframe width="400" height="300" frameborder="0" scrolling="no" marginheight="0"
marginwidth="0"
src="http://dev.virtualearth.net/embeddedMap/v1/ajax/road"/>
</body>
</html>
Use Embedded Map Features
You can customize your embedded map by adding parameters to the map URL. The following
code sets the map style to Aerial and the zoom level to 10, then centers the map and adds a
pushpin to the center.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Embedded Map</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body style="font-family:Arial">
<p>A simple embedded map.</p>
<iframe width="400" height="300" frameborder="0" scrolling="no" marginheight="0"
marginwidth="0"
src="http://dev.virtualearth.net/embeddedMap/v1/ajax/aerial?zoomLevel=10¢er=47.5_-
122.5&pushpins=47.5_-122.5"/>
</body>
</html>
Embedded Map URL Parameters
The embedded map URL is in the following format:
http://dev.virtualearth.net/embeddedMap/v1/ajax/{mapMode}?zoomLevel={zoomLevel}¢er={c
enter}&heading={heading}&pushpins={pushpins}&culture={culture}
22
The table below lists the available parameters for the map URL. These parameters can be in any
order and are all optional.
Parameter Name Description
mapMode The style of the map. Valid values are: Road,
Aerial, AerialWithLabels, Birdseye,
BirdseyeWithLabels
zoomLevel An int indicating a valid zoom level for the map
style.
center Two doubles separated by an underscore that
are the latitude and longitude values of the
coordinate of the center of the map.
heading A double specifying the orientation of the map
in degrees.
pushpins Two doubles separated by an underscore that
are the latitude and longitude values of the
coordinate of the pushpin. Multiple pushpin
locations are separated by a ~.
culture A valid culture string. The default value is ―en-
us‖.
See Also
Displaying a Map Using JavaScript
Controlling the Map
After you have a map on your Web page, you can programmatically change the map. You can
change the map style, adjust the zoom level, pan the map to a new location, show and hide the
default navigation control, and add your own controls to the map.
Changing the Map View
There are several ways you can programmatically change the map view. You can:
Zoom the map in or out by calling the VEMap.ZoomIn Method and VEMap.ZoomOut Method.
Zoom to a specific level by calling the VEMap.SetZoomLevel Method.
Set the center of the map by calling the VEMap.SetCenter Method, or set the center of the
map and zoom in by calling the VEMap.SetCenterAndZoom Method.
Change the map style by calling the VEMap.SetMapStyle Method.
23
Let Bing Maps determine the best map to show, based on your set of points, pushpins, or
polylines. You accomplish this by passing an array of points or lines to the
VEMap.SetMapView Method.
Showing and Hiding Controls
You can show and hide the default map navigation control by calling the VEMap.HideDashboard
Method and VEMap.ShowDashboard Method. You can also create your own map navigation
control in HTML, and then add the control to the map by calling the VEMap.AddControl Method.
Adding Shapes to a Map
You can use shapes for tasks such as marking locations, highlighting geographical boundaries,
and displaying information on a map.
Shape Basics
There are three types of shapes: pushpins, polylines, and polygons. These correspond to a point,
a line, and a polygon, respectively, on a map. With the release of Version 5, all shape objects are
consolidated under the VEShape Class. You can add shapes directly to the base layer of a map,
or use the VEShapeLayer Class to create shape layers, which you can then use to create and
manage arbitrary groups of shapes. Once the shape objects are added, you can set and get
shape properties by calling methods against each object directly.
VEMap Shape Methods
Use the VEMap Class to add shapes to a map's base layer. This method adds an existing
VEShape object to the base layer of the map. Use the VEMap.DeleteShape Method to delete a
single shape from the base layer, and VEMap.DeleteAllShapes Method to delete all shape
objects from the base layer.
VEShapeLayer Shape Methods
Use the VEShapeLayer.AddShape Method to add a shape. Use the VEShapeLayer.DeleteShape
Method to delete a single shape from a layer, and VEShapeLayer.DeleteAllShapes Method
method to delete all shape objects from a layer.
Setting and Getting VEShape Object Properties
Once a shape has been added to a map, use the methods of the VEShape class to set and get
the shape's properties. These properties control aspects of the shape such as line color and
width, fill color and transparency, custom icon, image file, Latitude/Longitude coordinates, and
more. As of Version 5, the title and description properties can contain custom HTML, which you
can use to further extend and modify your shapes.
Adding a Shape to a Map
Adding a shape to a map consists of the following steps:
24
1. Define an array of VELatLong objects. Polygon objects require a minimum of three points,
polyline objects require a minimum of two points, and pushpin objects require only one point
which can be part of an array (the method uses the first VELatLong object), or a single
VELatLong object.
var points = new Array(
new VELatLong(45.01188,-111.06687, 0, VEAltitudeMode.
RelativeToGround),
new VELatLong(45.01534,-104.06324, 0, VEAltitudeMode.
RelativeToGround),
new VELatLong(41.01929,-104.06, 0, VEAltitudeMode.
RelativeToGround),
new VELatLong(41.003,-111.05878, 0, VEAltitudeMode.
RelativeToGround)
);
2. Create the VEShape object. The following code creates a new polygon shape, "myPolygon",
at the specified coordinates.
var myPolygon = new VEShape(VEShapeType.Polygon, points);
3. Add the VEShape object named "myPolygon" to the map.
var myPolygon = map.AddShape(myPolygon);
4. Edit the properties of the shape. In this example we will add strings for the title and
description of the shape. Although this example shows only text, these strings can also
contain valid HTML.
myPolygon.SetTitle("My Polygon");
myPolygon.SetDescription("This is the description for my
polygon.");
The resulting code for the entire page might look something like this:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Adding a Shape to a Map</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=6.3"> </script>
<script type="text/javascript">
25
var map = null;
var points = new Array(
new VELatLong(45.01188,-111.06687, 0, VEAltitudeMode.
RelativeToGround),
new VELatLong(45.01534,-104.06324, 0, VEAltitudeMode.
RelativeToGround),
new VELatLong(41.01929,-104.06, 0, VEAltitudeMode.
RelativeToGround),
new VELatLong(41.003,-111.05878, 0, VEAltitudeMode.
RelativeToGround)
);
function GetMap()
{
map = new VEMap('myMap');
map.LoadMap();
var myPolygon = new VEShape(VEShapeType.Polygon,
points);
map.AddShape(myPolygon);
myPolygon.SetTitle("My Polygon");
myPolygon.SetDescription("This is the description for
my polygon.");
}
</script>
</head>
<body onload="GetMap();">
<div id='myMap' style="position:relative; width:400px;
height:400px;"></div>
</body>
</html>
Adding a Shape Layer to a Map
Shape layers make it possible to create and manage multiple collections of shapes within a single
map. Adding a shape to a shape layer consists of the following steps.
1. Initialize a new instance of the VEShapeLayer classVEShapeLayer Class.
var myShapeLayer = new VEShapeLayer();
26
2. Add the shape layer to the map, using the VEMap.AddShapeLayer Method.
map.AddShapeLayer(myShapeLayer);
The shape layer is invisible on its own, so let's add a shape object to the layer.
3. Define an array of VELatLong objects.
var points = new Array(
new VELatLong(45.01188,-111.06687, 0, VEAltitudeMode.
RelativeToGround),
new VELatLong(45.01534,-104.06324, 0, VEAltitudeMode.
RelativeToGround),
new VELatLong(41.01929,-104.06, 0, VEAltitudeMode.
RelativeToGround),
new VELatLong(41.003,-111.05878, 0, VEAltitudeMode.
RelativeToGround)
);
4. Create a VEShape object to add to the map.
var myShape = new VEShape(VEShapeType.Polygon, points);
5. Use the VEShapeLayer.AddShape method to add the shape to the shape layer.
myShapeLayer.AddShape(myShape);
The resulting code for the entire page might look something like this:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Adding a Shape to a Map</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=6.3"></script>
<script type="text/javascript">
var map = null;
var points = new Array(
new VELatLong(45.01188,-111.06687, 0, VEAltitudeMode.
RelativeToGround),
new VELatLong(45.01534,-104.06324, 0, VEAltitudeMode.
RelativeToGround),
27
new VELatLong(41.01929,-104.06, 0, VEAltitudeMode.
RelativeToGround),
new VELatLong(41.003,-111.05878, 0, VEAltitudeMode.
RelativeToGround)
);
function GetMap()
{
map = new VEMap('myMap');
map.LoadMap();
var myShapeLayer = new VEShapeLayer();
map.AddShapeLayer(myShapeLayer);
var myShape = new VEShape(VEShapeType.Polygon, points);
myShapeLayer.AddShape(myShape);
}
</script>
</head>
<body onload="GetMap();">
<div id='myMap' style="position:relative; width:400px;
height:400px;"></div>
</body>
</html>
Using Routes and Directions
You can use the Bing Maps routing and driving directions feature to show routes on your custom
maps. Routes are automatically drawn on the map, and you can customize the driving directions
by writing your own event handler.
Getting a Route
If you want to display a driving route from one point to another on the map, with possible interim
points, call the VEMap.GetDirections Method. Any point can be specified as an address, place
name, or VELatLong Class object. The following examples are both valid.
var myOptions = new VERouteOptions();
myOptions.SetBestMapView = false; // Don't change map view
myOptions.RouteCallback = myRouteHandler; // Gets VERoute
28
map.GetDirections(["space needle", "LA Coliseum", "area 51"], myOptions);
map.GetDirections(["1 Microsoft Way, 98052", new VELatLong(47.969,-122.39, 0,
VEAltitudeMode.RelativeToGround)], myOptions);
The route is drawn on the map with start and end icons and waypoint icons. Each of the icons
has a default enhanced preview that displays the driving directions for that step. The
myRouteHandler function gets a VERoute Class object, which you can use to display the driving
directions.
Showing Driving Directions
The VERoute object contains the details about the route, including the driving directions. When
calling the GetDirections method, you can specify a callback function to handle the VERoute
object and use the information to display driving directions. The following example shows how to
display the route information in a JavaScript alert.
function myRouteHandler(route)
{
// Unroll route and populate alert text
var legs = route.RouteLegs;
var turns = "Turn-by-Turn Directions\n";
var leg = null;
var turnNum = 0; // The turn #
var totalDistance = 0; // The sum of all leg distances
// Get intermediate legs
for(var i = 0; i < legs.length; i++)
{
// Get this leg so we don't have to dereference multiple times
leg = legs[i]; // Leg is a VERouteLeg object
// Unroll each intermediate leg
var turn = null; // The itinerary leg
var legDistance = null; // The distance for this leg
for(var j = 0; j < leg.Itinerary.Items.length; j ++)
{
turnNum++;
// turn is a VERouteItineraryItem object
29
turn = leg.Itinerary.Items[j];
turns += turnNum + ": " + turn.Text;
legDistance = turn.Distance;
totalDistance += legDistance;
// Round distances to 1/10ths
// Note that miles is the default
turns += " (" + legDistance.toFixed(1) + " miles)\n";
}
}
turns += "Total distance: " + totalDistance.toFixed(1) + " miles\n";
// Show directions
alert(turns);
}
Returning Localized Directions
Information about returning localized directions including how to set the map control culture and a
list of supported cultures can be found in the Returning Localized Results topic.
If the localized content should be in kilometers instead of miles, set the
VERouteOptions.DistanceUnit Property to VERouteDistanceUnit.Kilometer.
Changing the Defaults
By default, the route is calculated in the order in which the locations are specified, and distances
are calculated in miles. However, you can specify the shortest route by distance or quickest route
by time and change the units to kilometers by setting the appropriate VERouteOptions Class
properties, as follows.
myOptions.RouteOptimize = VERouteOptimize.MinimizeDistance;
myOptions.RouteOptimize = VERouteOptimize.MinimizeTime;
myOptions.DistanceUnit = VERouteDistanceUnit.Kilometer;
Working with Bird's Eye Images
Bird's eye images are low-angle, very high-resolution aerial images. Unlike the other map styles,
bird's eye images exist only for specific regions and do not provide continuous map coverage.
The Bing Maps AJAX Control 6.3 has built-in support for the bird's eye image type. You do not
need to add any additional code to your Web page to enable your users to see bird's eye images.
30
If users move the map to a region where bird's eye images are available, the map navigation
control changes automatically.
However, there may be times when you want to show a specific bird's eye image or create your
own bird's eye navigation control. This topic explains how to programmatically use bird's eye
images.
Determining Whether Bird's Eye Images Are Available
You can determine whether bird's eye images are available at any point on the map by calling the
VEMap.IsBirdseyeAvailable Method.
Example
Suppose you want to let users know when the map is centered on a location that has bird's eye
images. You need to determine whether images are available at the center of the map whenever
the user moves the map to a new location. To do this, attach a function to the
VEMap.onchangeview Event. In the function you attach, call the IsBirdseyeAvailable method. If
the IsBirdseyeAvailable method returns a value of True, notify the user. Your code may look like
the following.
map = new VEMap('myMap');
map.LoadMap(new VELatLong(33.756, -84.37), 14 ,'r' ,false);
map.AttachEvent('onchangeview', onChangeView);
//...
function onChangeView(e)
{
if (map.IsBirdseyeAvailable())
{
alert("Bird's Eye images are available at the center of the map");
}
}
Switching to Bird's Eye View
To programmatically switch the current map view to use bird's eye images, call the
VEMap.SetMapStyle Method as follows.
map.SetMapStyle(VEMapStyle.Birdseye)
When the map style changes to use bird's eye, the map navigation control also changes to
include the bird's eye navigation controls.
31
Using the VEBirdseyeScene Object
The VEBirdseyeScene Class object provides additional functionality when you are working with
bird's eye images. By using this object, you can:
Determine whether a point on the globe (a VELatLong Class object) is within the currently
displayed bird's eye image by calling the VEBirdseyeScene.ContainsLatLong Method.
Determine the orientation of the current image by calling the
VEBirdseyeScene.GetOrientation Method.
Displaying 3D Maps
On November 2, 2010, the end-of-life was announced for the 3D control. Effective
December 1, 2011, the 3D control will no longer function. The full announcement is found
at: http://www.bing.com/community/site_blogs/b/maps/archive/2010/11/02/changes-to-
bird-s-eye-and-3d-maps.aspx
The Bing Maps AJAX Control 6.3 includes the ability to display a three-dimensional view of the
world so that you can you to incorporate the same Bing Maps 3D experience found at the Bing
Maps Web site into your own Web sites.
Enabling 3D maps
Because the three-dimensional map functionality is built in to the same map control as the
standard two-dimensional maps, you do not need to change how you build your map-enabled
Web site. You can program against the new 3D APIs in the same way that you use the 2D APIs.
On the programming side, including the 3D maps in your existing sites requires very little
additional effort.
However, because of the complexity and the graphics-intensive nature of the Bing Maps 3D
maps, software must be installed on the client computer, and the client computer must have
sufficient hardware to display the maps. The software, called Bing Maps 3D, requires the
following on the client computer:
Microsoft Windows XP Service Pack 2, Microsoft Windows Server 2003, or Microsoft
Windows Vista
Microsoft Internet Explorer 6, 7 or 8, including 64-bit versions, or Mozilla Firefox 2.0 or 3.0.
Microsoft .NET Framework version 2.0
250 MB or more of hard disk space
A 1.0 GHz processor (2.8 GHz or faster recommended)
256 MB of system memory (1 GB recommended)
32-MB video card (256 MB recommended) that supports Microsoft DirectX 9, with 3D
hardware acceleration enabled
A high-speed or broadband Internet connection
32
Verifying the Requirements
Because there are several client-side requirements that users don't need when viewing the
standard two-dimensional maps, you should provide an appropriate user interface to verify that
the Bing Maps 3D control is installed. To do this, use the VEMap.AttachEvent Method to attach
the VEMap.onmodenotavailable Event to your VEMap Class object. If the software is not yet
installed on the client computer when the map mode is changed to 3D mode, this event fires. You
can then provide instructions on installing the software.
For example, the following code creates a new VEMap object, attaches the onmodenotavailable
event, and loads the map. When run on a computer without the software installed, the event
handler is called when the map is switched to 3D mode. The event handler provides instructions
to the customer on how to install the Bing Maps 3D software.
map=null;
function onPageLoad()
{
map = new VEMap('map');
map.LoadMap();
map.AttachEvent('onmodenotavailable', No3DInstalled);
}
function No3DInstalled ()
{
alert('Before viewing the maps in 3D mode, '+
'you must install the Bing Maps 3D software on your computer.' +
'\nTo install the software, visit ' +
'http://go.microsoft.com/fwlink/?LinkId=72623.');
}
The link to the installation program for the Bing Maps 3D software (and its prerequisites)
is http://go.microsoft.com/fwlink/?LinkId=72623.
Issues when Using 3D Mode
Because Bing Maps 3D is an embedded control on your Web page, certain web-based events
and properties behave differently from the traditional 2D maps. Consider the following situations
when designing your site to use 3D maps:
Custom controls or Web elements that you display on top of a 2D map will be hidden behind
the 3D map. You can prevent this by using an IFRAME "shim" for each control. For more
information, see the VEMap.AddControl Method topic and code example.
The default find control is also hidden when the map mode is switched to 3D mode. To
prevent this call the VEMap.ShowFindControl Method when the map mode is changed.
33
When the Bing Maps 3D control has focus, it captures keyboard and mouse events and
handles them. Map Control events are passed from the Bing Maps 3D control, so you can
continue to use all of them except VEMap.onstartpan Event. Page-level events will not fire
when the Bing Maps 3D control has focus.
Other map enhancements, including pushpins, custom pushpin and tile layers, polylines, and
polygons work in both 2D and 3D mode maps.
The client computer cannot have more than one instance of the 3D map running in the
same process at the same time.
Disabling 3D maps
Because the additional requirements for displaying 3D maps, you may want to prevent users from
switching to 3D mode. You can do this by setting the showSwitch parameter of the
VEMap.LoadMap Method to false.
Using Map Control Parameters
This topic describes map control parameters.
Parameters
The following table contains available parameters for the map control handler.
Parameter Values Description
v 6.2, 6.3, 6.3c Specifies a major API version. The
default value is the latest version, which
is 6.3. For information about using
version 6.3c, see Using the Core Map
Control.
mkt See the Returning
Localized Results topic
for a list of values.
Specifies the market to use, which
defines the language Bing Maps 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.
The CSS and tiles will not be loaded
when this function is called.
(This parameter is useful for loading the
map control script from an UpdatePanel
in ASP.NET Ajax. Users can call
34
Parameter Values Description
Sys.Application.notifyScriptLoaded from
their callback to tell ASP.NET Ajax the
script has loaded.)
Adding 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 6.3 and the market to Italian.
<script charset="UTF-8" type="text/javascript"
src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.3&mkt=it-IT">
</script>
See Also
Displaying a Map Using JavaScript
Returning Localized Results
Returning Localized Results
The Bing Maps AJAX Control 6.3 provides the ability to return results in different languages.
Setting the Culture
By default the map control features 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).
<script type="text/javascript"
src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.3&mkt=fr-
fr"></script>
More information about setting map control parameters is found in the Using Map Control
Parameters topic.
Supported Cultures
Depending on the culture specified in the map control reference, the following items are returned
in the language of the culture:
The map control dashboard. The dashboard is the default interface for controlling the map
(the compass-and-zoom control).
3D setup and instructional dialog boxes.
35
The VEPlace.Name Property of the results returned by the VEMap.Find Method
The VERouteItineraryItem.Text Property for each VERouteItineraryItem in the
VERouteItinerary.Items array returned by the VEMap.GetDirections Method. Some locales
are only supported by VEMap.GetDirections when you set the VERouteOptions.UseMWS
Property to true.
Map labels for Road and Hybrid map styles.
The following table lists supported cultures for the map control and available features for each
culture. If you set the map control mkt parameter to a value not found in this table, the map
control will not load.
Language - Country/Region Culture Feature Support
Czech - Czech Republic cs-CZ VEMap.Find,
VEMap.GetDirections
Danish - Denmark da-DK VEMap.Find,
VEMap.GetDirections
Dutch - Belgium nl-BE Map labels
Dutch - Netherlands nl-NL VEMap.Find,
VEMap.GetDirections
English - Australia en-AU VEMap.GetDirections using MWS
English - Canada en-CA Map control dashboard,
VEMap.Find,
VEMap.GetDirections using MWS
English - India* en-IN* VEMap.GetDirections using
MWS*
English - United Kingdom en-GB VEMap.GetDirections using MWS
English - United States en-US All features. This is the default
culture.
Finnish -Finland fi-FI VEMap.Find,
VEMap.GetDirections
French - Canada fr-CA Map control dashboard, 3D
dialogs, VEMap.Find,
VEMap.GetDirections, map labels
French - France fr-FR Map control dashboard, 3D
dialogs, VEMap.Find,
VEMap.GetDirections, map labels
German - Germany de-DE Map control dashboard,
36
Language - Country/Region Culture Feature Support
VEMap.Find,
VEMap.GetDirections, map labels
Italian - Italy it-IT Map control dashboard, 3D
dialogs, VEMap.Find,
VEMap.GetDirections, map labels
Japanese - Japan ja-JP Map control dashboard, 3D
dialogs, VEMap.Find, map labels
Norwegian (Bokmal) - Norway nb-NO VEMap.Find,
VEMap.GetDirections
Portuguese - Brazil Pt-BR VEMap.Find,
VEMap.GetDirections
Portuguese - Portugal pt-PT VEMap.Find,
VEMap.GetDirections
Spanish - Mexico es-MX VEMap.GetDirections using
MWS, map labels
Spanish - Spain es-ES Map control dashboard,
VEMap.Find,
VEMap.GetDirections, map labels
Spanish - United States es-US Map control dashboard,
VEMap.Find,
VEMap.GetDirections using
MWS, map labels
Swedish - Sweden sv-SE VEMap.Find,
VEMap.GetDirections
* The src for the fully supported India map control is
http://dev.mapindia.live.com/mapcontrol/mapcontrol.ashx?v=6.2. Information about this map
control is found at http://dev.mapindia.live.com/sdk.
Remarks
If you set the VERouteOptions.UseMWS Property to true and use the VEMap.GetDirections
Method with a supported culture, the MapPoint Web Service will return the route directions in
the neutral language of that culture. See the Supported Languages topic in the Microsoft
MapPoint Web Service SDK for more information.
VEMap.GetRoute is deprecated and will ignore specified cultures.
Error messages are always displayed in English - United States.
37
See Also
VEMap.Find Method
VEMap.GetDirections Method
VEMap.ShowDashboard Method
VEPlace Class
VERoute Class
Tracking Your Bing Maps Usage
Bing Maps Keys are the recommended authentication method for accessing the Bing
Maps AJAX Control 6.3 as described in Getting a Bing Maps Key. Information about
transaction accounting provided by Bing Maps Keys is in Understanding Bing Maps
Usage Reports. If you are an existing customer using tokens, consider updating your
application to use Bing Maps Keys. See the Getting Started with the Bing Maps AJAX
Control topic.
This topic provides information about Bing Maps Tokens.
Using Tokens for Identification
In order for Bing Maps to track your map control usage, every map control request that your
application sends to the Bing Maps servers must be identified as belonging to you. The Bing
Maps Token Service is provided to generate a unique string, called a token, which identifies you.
Use the VEMap.SetClientToken Method to set this token before the map control is loaded. Then
all further requests to the Bing Maps servers are identified as requests made by you.
See the Implementing Customer Identification article and the Bing Maps Token Service for more
information about the Bing Maps Token Service. Note that you must be a Bing Maps customer to
use the Bing Maps Token Service.
Tracking Transactions
All map control requests sent to the Bing Maps servers after a valid Bing Maps token is set using
the VEMap.SetClientToken Method are tracked. The following Bing Maps methods make server
requests:
Any time new map tiles are requested from Bing Maps. This includes VEMap.LoadMap,
VEMap.ZoomIn, VEMap.ZoomOut, VEMap.Pan, VEMap.SetMapView, and many other
methods that cause the map to move. If traffic display is turned on using
VEMap.ShowTraffic, requests for traffic map tiles are tracked as well.
Any time Bing Maps AJAX Control 6.3 makes a where-only request for a find result. This
includes where-only requests from the VEMap.Find method as well as the
VEMap.GetDirections method.
Each request made using the VEMap.FindLocations method.
38
Each request made using the VEMap.GetDirections method.
Viewing Reports
You can view reports detailing your Bing Maps AJAX Control 6.3 usage. See the Implementing
Customer Identification article for more information.
See Also
VEMap.SetClientToken Method
VEMap.ontokenerror Event
VEMap.ontokenexpire Event
Bing Map Control Performance
To give end users the best possible performance, Microsoft Bing Maps AJAX Control 6.3 offers
the following improvements.
Core Functionality Version
Both full functionality and core functionality versions of the Bing Maps AJAX Control 6.3 are
available. If you do not need enhanced map features, you can improve the performance of your
application by using the core version of the map control. See the Using the Core Map Control
topic for more information. Geocoding and routing capabilities are available from the Bing Maps
REST API, which you can use in conjunction with the core map control as described in the Using
the REST Services with the Core Map Control topic.
Quicker Content Delivery with Advanced Network Technology
Microsoft Content Delivery Network (CDN) support. The addition of CDN to the Bing Maps
core infrastructure has improved delivery speeds of Bing Maps content up to 82%. CDN is a key
pillar of Microsoft’s cloud computing strategy and is one of the primary investments the Bing
Maps Platform team has made to increase overall platform performance. CDN is comprised of
multiple worldwide datacenters that allow Microsoft to host Bing Maps content closer to end
users.
To use CDN, set the map control src reference to the CDN URL, as demonstrated in the code
below.
<script charset="UTF-8" type="text/javascript"
src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.3&mkt=en-
us"></script>
The map control found at http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.3
does not use CDN, but will remain available for backwards compatibility.
39
Faster Rendering of Map Details
Add custom layer method. The VEMap.AddCustomLayer Method quickly adds custom data to
the map.
Add bulk pushpins. The Bing Maps AJAX Control 6.3 allows you to bulk add pushpins to the
map. The time to add these pushpins to the map is close to half the time it takes to add these
pushpins using the traditional method. The code below demonstrates this feature.
// Create an array with a large number of pushpins:
var center = map.GetCenter();
var shapes = new Array();
for (i=0 ; i < 150; ++i)
{
var shape = new VEShape(VEShapeType.Pushpin, new VELatLong(center.Latitude +
Math.random()*20 - 10, center.Longitude + Math.random()*20 - 10));
shapes.push(shape);
}
// Create an empty shape layer and add it to the map:
var shapeLayer = new VEShapeLayer();
map.AddShapeLayer(shapeLayer);
// Add the array of pushpins to the shape layer:
shapeLayer.AddShape(shapes);
Route rendering optimization. The Bing Maps AJAX Control 6.3 contains logic to optimize by
zoom level the number of route points needed to display a route on the map. When the map is
zoomed out, the route is rendered with fewer points.
In addition to the map control performance features above, you can further improve the
performance of your web page by following tips in the Performance and Load Testing
in Bing Maps article in the Bing Maps Articles.
See Also
Displaying a Map Using JavaScript
40
Using the Core Map Control
If you do not need enhanced map features, you can improve the performance of your application
by using the core version of the map control. This topic includes information about how to load
the core map control as well as the map control APIs that are supported in the core version.
Loading the Core Map Control
To load the core map control, set the v parameter of the map control to 6.3c. Your script tag in
the header of your web page now looks like this:
<script charset="UTF-8" type="text/javascript"
src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.3c&mkt=en-
us"></script>
Core Map Control API
The following APIs are supported in the core version of Bing Maps AJAX Control 6.3. If you need
geocoding or search functionality, you can use the Bing Maps REST Services in conjunction with
the core map control as described in the Using the REST Services with the Core Map Control
topic.
The core version of the map control is only supported on the following browsers: Internet
Explorer 7, Internet Explorer 8, Firefox 3.5, Firefox 3.6, Safari 4, and Google Chrome.
Supported Types
Type Supported Members
VEDistanceUnit Enumeration All members are supported.
VEException Class All members are supported.
VELatLong Class All members are supported.
VELatLongRectangle Class All members are supported.
VEMap Class Supported members are listed in the VEMap
member tables below.
VEMapOptions Class All members are supported.
VEMapStyle Enumeration All members are supported.
VEMapViewSpecification Class All members are supported.
VEPixel Class All members are supported.
VEShape Class Supported members are listed in the VEShape
member tables below.
41
Type Supported Members
VEShapeLayer Class Supported members are listed in the
VEShapeLayer member tables below.
VEShapeType Enumeration VEShapeType.Pushpin
VETileSourceSpecification Class All members are supported.
Supported VEMap Members
The following members of the VEMap Class are supported in the core version of the map control.
Public Constructor
Name Description
VEMap Constructor Initializes a new instance of the VEMap Class.
Public Events
Name Description
VEMap.onkeypress Event Occurs when a key is pressed and released.
VEMap.onkeydown Event Occurs when a key is pressed (but before it is
released).
VEMap.onkeyup Event Occurs when a key is released.
VEMap.onclick Event Occurs when a left or right mouse button is
single-clicked.
VEMap.ondoubleclick Event Occurs when a left mouse button is double-
clicked.
VEMap.onmousedown Event Occurs when a mouse button (left, right, or
middle) is clicked (but before it is released).
VEMap.onmousemove Event Occurs when the mouse cursor moves.
VEMap.onmouseout Event Occurs when the mouse cursor moves away
from a VEShape object.
VEMap.onmouseover Event Occurs when the mouse cursor moves over a
VEShape Class object.
VEMap.onmouseup Event Occurs when a mouse button (left, right, or
middle) is released.
VEMap.onmousewheel Event Occurs when the mouse wheel is moved.
42
Name Description
VEMap.onchangemapstyle Event Occurs when the map style changes.
VEMap.onchangeview Event Occurs whenever the map view changes.
VEMap.oncredentialserror Event Occurs when the map control makes a request
to the Bing Maps servers and the credentials
that were set using the VEMap.SetCredentials
Method are invalid.
VEMap.oncredentialsvalid Event Occurs when the map control makes a request
to the Bing Maps servers and the credentials
that were set using the VEMap.SetCredentials
Method are valid.
VEMap.onendpan Event Occurs when a pan of the map ends.
VEMap.onendzoom Event Occurs when the map zoom ends.
VEMap.onerror Event Occurs when there is a map control error.
VEMap.oninitmode Event Occurs after the map mode changes and the
map has reloaded.
VEMap.onresize Event Occurs when the map is resized.
VEMap.onstartpan Event Occurs when a pan of the map begins.
VEMap.onstartzoom Event Occurs when the map zoom begins.
Public Methods
Name Description
VEMap.AddControl Method Adds a custom control to the map.
VEMap.AddCustomLayer Method Adds a custom layer to the map.
VEMap.AddShape Method Adds an existing VEShape Class object, as
specified by the shape parameter, to the base
layer. The core version of this method does not
support adding shape arrays. Also note that the
core version of the map control only supports
VEShape objects that are of type
VEShapeType.Pushpin.
VEMap.AddShapeLayer Method Adds the specified shape layer to the map.
VEMap.AddTileLayer Method Adds a tile layer to the map, and if the
visibleOnLoad parameter is true, it also shows
43
Name Description
it on the map.
VEMap.AttachEvent Method Attaches a Map Control event to a specified
function.
VEMap.Clear Method Removes all shapes, shape layers, and search
results on the map. Also removes the route
from the map, if one is displayed.
VEMap.ClearInfoBoxStyles Method Clears out all of the default Bing Maps info box
CSS styles.
VEMap.ClearTraffic Method Clears the traffic map.
VEMap.DeleteControl Method Removes the specified control from the map.
VEMap.DeleteAllShapes Method Deletes all shapes in all layers, leaving empty
layers behind.
VEMap.DeleteAllShapeLayers Method Deletes all shape layers, along with any shapes
within the layers.
VEMap.DeleteShape Method Deletes a VEShape Class object from any
layer, including the base map layer.
VEMap.DeleteShapeLayer Method Deletes the specified shape layer from the
map.
VEMap.DeleteTileLayer Method Deletes a tile layer from view.
VEMap.DetachEvent Method Detaches the specified map control event so
that it no longer calls the specified function.
VEMap.Dispose Method Deletes the VEMap object and releases any
associated resources
VEMap.EndContinuousPan Method Stops the continuous map panning initiated by
a call to the VEMap.StartContinuousPan
Method.
VEMap.GetCenter Method Returns a VELatLong Class object that
represents the location of the center of the
current map view.
VEMap.GetLeft Method Returns the pixel value of the left edge of the
map control.
VEMap.GetMapStyle Method Returns the current map style.
VEMap.GetMapView Method Returns the current map view object as a
44
Name Description
VELatLongRectangle Class object.
VEMap.GetShapeByID Method Gets the reference to a VEShape Class object
based on its internal identifier.
VEMap.GetShapeLayerByIndex Method Gets the reference to a VEShapeLayer Class
object based on its index.
VEMap.GetShapeLayerCount Method Gets the total number of shape layers on the
map.
VEMap.GetTileLayerByID Method Gets a tile layer based upon its identifier.
VEMap.GetTileLayerByIndex Method Gets a tile layer based upon an index value.
VEMap.GetTileLayerCount Method Gets the number of tile layers.
VEMap.GetTop Method Returns the pixel value of the top edge of the
map control.
VEMap.GetVersion Method Returns the current version of the map control.
VEMap.GetZoomLevel Method Returns the current zoom level of the map.
VEMap.HideBaseTileLayer Method Hides the base tile layer of the map.
VEMap.HideControl Method Hides the specified control from view.
VEMap.HideDashboard Method Hides the default user interface for controlling
the map (the compass and the zoom control).
VEMap.HideInfoBox Method Hides a shape's custom or default info box.
VEMap.HideScalebar Method Hides the scale bar from the map.
VEMap.HideAllShapeLayers Method Hides all of the shape layers on the map.
VEMap.HideTileLayer Method Hides a tile layer from view.
VEMap.HideTrafficLegend Method Hides the traffic legend.
VEMap.IncludePointInView Method Changes the map view so that it includes both
the specified VELatLong Class point and the
center point of the current map.
VEMap.LatLongToPixel Method Converts an array of VELatLong Class objects
(latitude/longitude pair) to an array of VEPixel
Class objects.
VEMap.LoadMap Method Loads the specified map. All parameters are
optional.
45
Name Description
VEMap.LoadTraffic Method Loads the traffic map.
VEMap.Pan Method Moves the map the specified amount.
VEMap.PanToLatLong Method Pans the map to a specific latitude and
longitude.
VEMap.PixelToLatLong Method Converts a pixel (a point on the map) to a
VELatLong Class object (latitude/longitude
pair).
VEMap.RemoveCustomLayer Method Removes a custom layer from the map.
VEMap.Resize Method Resizes the map based on the specified width
and height.
VEMap.SetCenter Method Centers the map to a specific latitude and
longitude.
VEMap.SetCenterAndZoom Method Centers the map to a specific latitude and
longitude and sets the zoom level.
VEMap.SetCredentials Method Sets the credentials to use to authenticate map
service requests.
VEMap.SetDefaultInfoBoxStyles Method Sets the info box CSS styles back to their
original classes.
VEMap.SetMapStyle Method Sets the style of the map.
VEMap.SetMapView Method Sets the map view to include all of the points,
lines, or polygons specified in the provided
array, or to the view defined by a
VEMapViewSpecification Class object.
VEMap.SetMouseWheelZoomToCenter
Method
Specifies whether to zoom to the center of the
screen or to the cursor position on the screen.
VEMap.SetScaleBarDistanceUnit Method Sets the distance unit (kilometers or miles) for
the map scale.
VEMap.SetTileBuffer Method Sets the number of "rings" of map tiles that
should be loaded outside of the visible
mapview area.
VEMap.SetTrafficLegendText Method Specifies the text shown with the traffic legend,
if visible.
VEMap.SetZoomLevel Method Sets the view of the map to the specified zoom
46
Name Description
level.
VEMap.ShowAllShapeLayers Method Shows all shape layers on the map.
VEMap.ShowBaseTileLayer Method Shows the base tile layer of the map.
VEMap.ShowControl Method Makes the specified control visible. This
method only affects control elements that have
been hidden from view using the
VEMap.HideControl Method.
VEMap.ShowDashboard Method Shows the default user interface for controlling
the map (the compass-and-zoom control). By
default, this control is shown.
VEMap.ShowInfoBox Method Shows a shape's custom or default info box.
VEMap.ShowMessage Method Displays the specified message in a dialog box
on the map.
VEMap.ShowScalebar Method Displays the scale bar on the map.
VEMap.ShowTileLayer Method Shows a tile layer from view.
VEMap.ShowTrafficLegend Method Displays the traffic legend.
VEMap.StartContinuousPan Method Moves the map in the specified direction until
the VEMap.EndContinuousPan Method is
called.
VEMap.ZoomIn Method Increases the map zoom level by 1.
VEMap.ZoomOut Method Decreases the map zoom level by 1.
Public Properties
Name Description
VEMap.onLoadMap Property Specifies the function to call when the map is
first loaded.
Supported VEShape Members
The following members of the VEShape Class are supported in the core version of the map
control.
47
The core version of the map control only supports VEShape objects that are of type
VEShapeType.Pushpin.
Public Constructor
Name Description
VEShape Constructor Initializes a new instance of the VEShape Class.
Public Events
Name Description
VEShape.ondrag Event Occurs when a shape is being dragged across
the map.
VEShape.onenddrag Event Occurs when a shape drag has stopped.
VEShape.onstartdrag Event Occurs when the user starts dragging the
shape.
Public Methods
Name Description
VEShape.GetCustomIcon Method Gets the VEShape object's custom icon.
VEShape.GetDescription Method Gets the description of the VEShape object.
VEShape.GetIconAnchor Method Gets a VELatLong Class object representing
the shape's custom icon anchor point.
VEShape.GetID Method Gets the internal identifier of the VEShape
object.
VEShape.GetMaxZoomLevel Method Gets the maximum zoom level at which the
shape is visible.
VEShape.GetMinZoomLevel Method Gets the minimum zoom level at which the
shape is visible.
VEShape.GetPoints Method Returns an array of VELatLong Class objects
representing the points that make up the
pushpin.
VEShape.GetShapeLayer Method Gets the reference to the layer containing the
specified VEShape object.
VEShape.GetTitle Method Gets the title of the VEShape object.
48
Name Description
VEShape.GetType Method Gets the type of the VEShape object.
VEShape.GetZIndex Method Gets the z-index of a pushpin shape.
VEShape.Hide Method Hides the specified VEShape object from view.
VEShape.SetCustomIcon Method Sets the VEShape object's custom icon.
VEShape.SetDescription Method Sets the description of the VEShape object.
VEShape.SetIconAnchor Method Sets the info box anchor of the VEShape
object.
VEShape.SetMaxZoomLevel Method Sets the maximum zoom level at which the
shape is visible.
VEShape.SetMinZoomLevel Method Sets the minimum zoom level at which the
shape is visible.
VEShape.SetPoints Method Sets the points of the VEShape object.
VEShape.SetTitle Method Sets the title of the VEShape object.
VEShape.SetZIndex Method Sets the z-index value for a shape.
VEShape.Show Method Makes the specified VEShape object visible.
Public Properties
Name Description
VEShape.Draggable Property A Boolean value indicating whether the
VEShape icon on the map can be dragged
using the mouse.
Supported VEShapeLayer Members
The following members of the VEShapeLayer Class are supported in the core version of the map
control.
Public Constructor
Name Description
VEShapeLayer Constructor Initializes a new instance of the VEShapeLayer
Class.
Public Methods
49
Name Description
VEShapeLayer.AddShape Method Adds an existing VEShape Class object to the
layer based on the specified VEShape
reference. The core version of this method
does not support adding shape arrays. Also
note that the core version of the map control
only supports VEShape objects that are of type
VEShapeType.Pushpin.
VEShapeLayer.DeleteAllShapes Method Deletes all VEShape objects from the layer.
VEShapeLayer.DeleteShape Method Deletes a VEShape object from the current
layer.
VEShapeLayer.GetBoundingRectangle Method Returns a best-fit VELatLongRectangle Class
object based on the shapes currently present in
the layer.
VEShapeLayer.GetShapeByID Method Retrieves a reference to a VEShape object
contained in this layer based on the specified
ID.
VEShapeLayer.GetShapeByIndex Method Retrieves a reference to a VEShape object
contained in this layer based on the specified
index.
VEShapeLayer.GetShapeCount Method Returns the total number of shapes in the
current layer.
VEShapeLayer.IsVisible Method Returns whether the layer is visible.
VEShapeLayer.Hide Method Hides the layer from view on the map.
VEShapeLayer.Show Method Shows the layer on the map.
Using the REST Services with the Core Map Control
This topic describes how to use the core version of the Bing Maps AJAX Control 6.3 and the Bing
Maps REST Services to create a simple page that geocodes a given place or address string and
adds a pushpin to the map at that location.
Load the Core Map Control
Before you add geocoding functionality, load the core version of the map control using the
following code. The core map control is described in Using the Core Map Control.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
50
<html>
<head>
<title>Core Map Control Sample</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=6.3c"></script>
<script type="text/javascript">
var map = null;
function GetMap()
{
map = new VEMap('myMap');
map.LoadMap();
}
</script>
</head>
<body onload="GetMap();">
<div id='myMap' style="position:relative; width:400px; height:400px;"></div>
</body>
</html>
Add Controls
For this sample, add a text box and a geocode button. In your script, create a ClickGeocode
function that is called when the button is clicked.
<input id="txtQuery" type="text" value="Portland"/>
<input type="button" value="Geocode" onclick="ClickGeocode()"/>
51
Make a REST Geocode Request
Next, make a geocode request to the Bing Maps REST Services using the value in the txtQuery
input box.
The Bing Maps REST Services requires a Bing Maps Key. You can get a key by signing
up for a free Bing Maps developer account at https://www.bingmapsportal.com.
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=BingMapsKey";
Now add script to make the REST request.
function ClickGeocode()
{
var geocodeRequest = "http://dev.virtualearth.net/REST/v1/Locations/" +
document.getElementById('txtQuery').value +
"?output=json&jsonp=GeocodeCallback&key=BingMapsKey";
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)
{
52
// Do something with the result
}
Display the Result
Finally, add code to the GeocodeCallback function to set the map view to the found location and
add a pushpin at that location. The final code is shown below.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Core Map Control Sample</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=6.3c"></script>
<script type="text/javascript">
var map = null;
function GetMap()
{
map = new VEMap('myMap');
map.LoadMap();
}
function ClickGeocode()
{
var geocodeRequest = "http://dev.virtualearth.net/REST/v1/Locations/" +
document.getElementById('txtQuery').value +
"?output=json&jsonp=GeocodeCallback&key=BingMapsKey";
CallRestService(geocodeRequest);
53
}
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;
map.SetMapView(new VELatLongRectangle(new VELatLong(bbox[0], bbox[1]), new
VELatLong(bbox[2], bbox[3])));
// Add a pushpin at the found location
var latlong = new
VELatLong(result.resourceSets[0].resources[0].point.coordinates[0],
result.resourceSets[0].resources[0].point.coordinates[1]);
var pushpin = new VEShape(VEShapeType.Pushpin, latlong);
map.AddShape(pushpin);
}
}
function CallRestService(request)
{
var script = document.createElement("script");
script.setAttribute("type", "text/javascript");
script.setAttribute("src", request);
document.body.appendChild(script);
}
54
</script>
</head>
<body onload="GetMap();">
<div id='myMap' style="position:relative; width:400px; height:400px;"></div>
<input id="txtQuery" type="text" value="Portland"/><input type="button"
value="Geocode" onclick="ClickGeocode()"/>
</body>
</html>
See Also
Using the Core Map Control
Bing Maps AJAX Control Class Reference
In This Section
The following classes and enumerations are part of the Bing Maps AJAX Control 6.3.
VEAltitudeMode Enumeration
VEBirdseyeScene Class
VEClusteringOptions Class
VEClusteringType Enumeration
VEClusterSpecification Class
VEColor Class
VECustomIconSpecification Class
VEDashboardSize Enumeration
VEDataType Enumeration
VEDistanceUnit Enumeration
VEException Class
VEFailedShapeRequest Enumeration
VEFindResult Class
VEFindType Enumeration
VEGeocodeLocation Class
VEGeocodeOptions Class
VEImageryMetadata Class
VEImageryMetadataOptions Class
VELatLong Class
55
VELatLongRectangle Class
VELocationPrecision Enumeration
VEMap Class
VEMapMode Enumeration
VEMapOptions Class
VEMapStyle Enumeration
VEMapViewSpecification Class
VEMatchCode Enumeration
VEMatchConfidence Enumeration
VEMiniMapSize Enumeration
VEModelFormat Enumeration
VEModelOrientation Class
VEModelScale Class
VEModelScaleUnit Enumeration
VEModelSourceSpecification Class
VEModelStatusCode Enumeration
VEOrientation Enumeration
VEPixel Class
VEPlace Class
VEPrintOptions Class
VERoute Class
VERouteDeprecated Class
VERouteDistanceUnit Enumeration
VERouteHint Class
VERouteHintType Enumeration
VERouteItinerary Class
VERouteItineraryDeprecated Class
VERouteItineraryItem Class
VERouteLeg Class
VERouteLocation Class
VERouteMode Enumeration
VERouteOptimize Enumeration
VERouteOptions Class
VERouteSegment Class
VERouteType Enumeration
VERouteWarning Class
VERouteWarningSeverity Enumeration
VESearchOptions Class
56
VEShape Class
VEShapeLayer Class
VEShapeAccuracy Enumeration
VEShapeSourceSpecification Class
VEShapeType Enumeration
VETileSourceSpecification Class
VEAltitudeMode Enumeration
Defines the altitude of a point on the globe.
Syntax
VEAltitudeMode{ Default Absolute RelativeToGround }
Members
Member Description
Default The altitude is meters above ground level
Absolute The altitude is meters above the WGS 84
ellipsoid
RelativeToGround The altitude is meters above ground level
Remarks
If the object is a 3D model, then the altitude mode is always RelativeToGround.
See Also
VELatLong Constructor
VELatLong.AltitudeMode Property
VELatLong.SetAltitude Method
VEShape.SetAltitudeMode Method
VEBirdseyeScene Class
Contains the information about a specific bird's eye image.
Public Methods
57
Name Description
VEBirdseyeScene.ContainsLatLong Method Determines whether the location specified by a
VELatLong Class object is within the current
VEBirdseyeScene object.
VEBirdseyeScene.ContainsPixel Method Determines whether a specified pixel is within
the current VEBirdseyeScene object.
VEBirdseyeScene.GetBoundingRectangle
Method
Returns an unencrypted and rounded off
bounding rectangle for the VEBirdseyeScene
object.
VEBirdseyeScene.GetHeight Method Returns the height of the image in the current
VEBirdseyeScene object, in pixels, at
maximum resolution
VEBirdseyeScene.GetID Method Returns the ID of the current
VEBirdseyeScene object.
VEBirdseyeScene.GetOrientation Method Returns the orientation (VEOrientation
Enumeration) of the current VEBirdseyeScene
object.
VEBirdseyeScene.GetWidth Method Returns the width of the image in the current
VEBirdseyeScene object, in pixels, at
maximum resolution
VEBirdseyeScene.LatLongToPixel Method Converts a VELatLong Class object
(latitude/longitude pair) to the corresponding
pixel on the map.
VEBirdseyeScene.PixelToLatLong Method Converts a point in the bird's eye scene to an
encrypted latitude/longitude value.
Remarks
To get the VEBirdseyeScene object for the current map, call the VEMap.GetBirdseyeScene
Method.
To change the VEBirdseyeScene object for the current map, call the VEMap.SetBirdseyeScene
Method.
VEBirdseyeScene Methods
The methods of the VEBirdseyeScene class are listed here. For a complete list of
VEBirdseyeScene class members, see the VEBirdseyeScene Class topic.
58
Public Methods
Name Description
VEBirdseyeScene.ContainsLatLong Method Determines whether the location specified by a
VELatLong Class object is within the current
VEBirdseyeScene object.
VEBirdseyeScene.ContainsPixel Method Determines whether a specified pixel is within
the current VEBirdseyeScene object.
VEBirdseyeScene.GetBoundingRectangle
Method
Returns an unencrypted and rounded off
bounding rectangle for the VEBirdseyeScene
object.
VEBirdseyeScene.GetHeight Method Returns the height of the image in the current
VEBirdseyeScene object, in pixels, at
maximum resolution
VEBirdseyeScene.GetID Method Returns the ID of the current
VEBirdseyeScene object.
VEBirdseyeScene.GetOrientation Method Returns the orientation (VEOrientation
Enumeration) of the current VEBirdseyeScene
object.
VEBirdseyeScene.GetWidth Method Returns the width of the image in the current
VEBirdseyeScene object, in pixels, at
maximum resolution
VEBirdseyeScene.LatLongToPixel Method Converts a VELatLong Class object
(latitude/longitude pair) to the corresponding
pixel on the map.
VEBirdseyeScene.PixelToLatLong Method Converts a point in the bird's eye scene to an
encrypted latitude/longitude value.
VEBirdseyeScene.ContainsLatLong Method
Determines whether the location specified by a VELatLong Class object is within the current
VEBirdseyeScene object.
Syntax
VEBirdseyeScene.ContainsLatLong(Latlong);
Parameters
59
Parameter Description
Latlong A VELatLong Class object
Return Value
A Boolean value. True if the location specified by the VELatLong object is within the bounds of
the VEBirdseyeScene object.
Example
VirtualEarthSDK#0
VEBirdseyeScene.ContainsPixel Method
Determines whether a specified pixel is within the current VEBirdseyeScene object.
Syntax
VEBirdseyeScene.ContainsPixel(x, y, zoomLevel);
Parameters
Parameter Description
x The X component of the pixel
y The Y component of the pixel
zoomLevel The current zoom level of the map
Return Value
A Boolean value. True if the specified pixel is within the bounds of the VEBirdseyeScene object.
Remarks
The pixel location is relative to the scene, not the current view.
Example
VirtualEarthSDK#0
VEBirdseyeScene.GetBoundingRectangle Method
Returns an unencrypted and rounded off bounding rectangle for the VEBirdseyeScene object.
Syntax
VEBirdseyeScene.GetBoundingRectangle();
Return Value
A VELatLongRectangle Class object containing the bounding rectangle.
Remarks
60
The bounding rectangle's values can be up to two miles off the original latitude and longitude.
The bounding rectangle is the same size or larger than the original bounding rectangle. The
bounding rectangle is for the entire scene, not just for the map view. The center of the bounding
rectangle may not be the center of the scene. In some scenes, the center of the bounding
rectangle might not be within the scene.
Example
VirtualEarthSDK#17
VEBirdseyeScene.GetHeight Method
Returns the height of the image in the current VEBirdseyeScene object, in pixels, at maximum
resolution.
Syntax
VEBirdseyeScene.GetHeight();
Return Value
The height in pixels.
Remarks
To get the height of the image when it is zoomed out (at the minimum resolution), divide the value
returned from the GetHeight method by 2.
Example
VirtualEarthSDK#0
VEBirdseyeScene.GetID Method
Returns the ID of the current VEBirdseyeScene object.
Syntax
VEBirdseyeScene.GetID();
Return Value
The scene ID as an integer.
Example
VirtualEarthSDK#0
VEBirdseyeScene.GetOrientation Method
Returns the orientation (VEOrientation Enumeration) of the current VEBirdseyeScene object.
Syntax
VEBirdseyeScene.GetOrientation();
Return Value
61
The VEOrientation Enumeration value.
Example
VirtualEarthSDK#0
VEBirdseyeScene.GetWidth Method
Returns the width of the image in the current VEBirdseyeScene object, in pixels, at maximum
resolution.
Syntax
VEBirdseyeScene.GetWidth();
Return Value
The width in pixels.
Remarks
To get the width of the image when it is zoomed out (at the minimum resolution), divide the value
returned from the GetWidth method by 2.
Example
VirtualEarthSDK#0
VEBirdseyeScene.LatLongToPixel Method
Converts a VELatLong Class object (latitude/longitude pair) to the corresponding pixel on the
map.
Syntax
VEBirdseyeScene.LatLongToPixel(LatLong, zoomLevel);
Parameters
Parameter Description
LatLong A VELatLong Class object, which contains the
latitude and longitude of a point. This method
also accepts an encrypted VELatLong object,
as supplied by the
VEBirdseyeScene.PixelToLatLong Method.
zoomLevel The zoom level of the current map view
Return Value
A pixel location of the VELatLong Class point. This object has two properties, x and y.
Remarks
62
The x- and y-coordinates of the pixel returned by this method are with respect to the top-left
corner of the bird's eye scene. This differs from VEMap.LatLongToPixel Method, which returns x-
and y-coordinates with respect to the top-left corner of the map view.
VEMap.LatLongToPixel can also be called in bird's eye view.
Example
VirtualEarthSDK#1
VEBirdseyeScene.PixelToLatLong Method
Converts a point in the bird's eye scene to an encrypted latitude/longitude value.
Syntax
VEBirdseyeScene.PixelToLatLong(pixel, zoomLevel);
Parameters
Parameter Description
pixel A VEPixel Class object representing a pixel
location on the map
zoomLevel The zoom level of the current map view
Return Value
An encrypted VELatLong object.
Remarks
You cannot retrieve the unencrypted latitude and longitude of a specific point in a bird's eye
image. The return value is an encrypted VELatLong, but you can use it by passing it back to
other methods. For example, you can use the encrypted VELatLong as input for the
VEMap.GetRoute Method, the VEMap.SetCenter Method, and the VEMap.SetCenterAndZoom
Method.
Example
VirtualEarthSDK#1
VEClusteringOptions Class
Contains the options for customizing a pushpin cluster display.
Constructor
63
Name Description
VEClusteringOptions Constructor Initializes a new instance of a
VEClusteringOptions object.
Public Properties
Name Description
VEClusteringOptions.Icon Property A VECustomIconSpecification Class which
describes the icon representing the pushpin
cluster.
VEClusteringOptions.Callback Property The name of the function called when
clustering changes.
See Also
VEShapeLayer.SetClusteringConfiguration Method
VEClusteringOptions Constructor
Initializes a new instance of the VEClusteringOptions Class.
Syntax
var x = new VEClusteringOptions();
See Also
VEShapeLayer.SetClusteringConfiguration Method
VEClusteringOptions Properties
The properties of the VEClusteringOptions class are listed here. For a complete list of
VEClusteringOptions class members, see the VEClusteringOptions Class topic.
Public Properties
Name Description
VEClusteringOptions.Icon Property A VECustomIconSpecification Class which
describes the icon representing the pushpin
cluster.
VEClusteringOptions.Callback Property The name of the function called when
64
Name Description
clustering changes.
VEClusteringOptions.Icon Property
A VECustomIconSpecification Class which describes the icon representing the pushpin cluster.
Syntax
VEClusteringOptions.Icon = new VECustomIconSpecification();
Remarks
If the Icon property is specified, it is used to display clustered icons. If the Icon property is not
specified, the default cluster icon is used.
VEClusteringOptions.Callback Property
The name of the function called when clustering changes.
Syntax
VEClusteringOptions.Callback = value;
Remarks
The function specified in the Callback must take an array of VEClusterSpecification Class
objects.
See Also
VEClusterSpecification.GetClusterShape Method
VEClusteringType Enumeration
An enumeration of pushpin clustering algorithms.
Syntax
VEClusteringType { None Grid }
Members
Member Description
None No pushpin clustering
Grid A simple clustering algorithm
65
See Also
VEShapeLayer.SetClusteringConfiguration(type, options) Method
VEClusterSpecification Class
Contains the shape objects and location of a pushpin cluster.
Public Methods
Name Description
VEClusterSpecification.GetClusterShape
Method
Returns a VEShape Class that represents the
pushpin cluster.
Public Properties
Name Description
VEClusterSpecification.Shapes Property An array of VEShape Class items representing
the pushpins in a pushpin cluster.
VEClusterSpecification.LatLong Property A VELatLong Class object indicating the center
of the pushpin cluster.
See Also
VEShapeLayer.GetClusteredShapes Method
VEClusterSpecification Methods
The methods of the VEClusterSpecification class are listed here. For a complete list of
VEClusterSpecification class members, see the VEClusterSpecification Class topic.
Public Methods
Name Description
VEClusterSpecification.GetClusterShape
Method
Returns a VEShape Class that represents the
pushpin cluster.
VEClusterSpecification.GetClusterShape Method
Returns a VEShape Class that represents the pushpin cluster.
Syntax
66
VEClusterSpecification.GetClusterShape();
Return Value
A VEShape Class representing the pushpin cluster. Returns null if a VEClusterSpecification
object was returned from the VEShapeLayer.GetClusteredShapes Method.
See Also
VEClusterSpecification Class
VEClusterSpecification Properties
The properties of the VEClusterSpecification class are listed here. For a complete list of
VEClusterSpecification class members, see the VEClusterSpecification Class topic.
Public Properties
Name Description
VEClusterSpecification.Shapes Property An array of VEShape Class items representing
the pushpins in a pushpin cluster.
VEClusterSpecification.LatLong Property A VELatLong Class object indicating the center
of the pushpin cluster.
VEClusterSpecification.Shapes Property
An array of VEShape Class items representing the pushpins in a pushpin cluster.
Syntax
VEClusterSpecification.Shapes
VEClusterSpecification.LatLong Property
A VELatLong Class object indicating the center of the pushpin cluster.
Syntax
VEClusterSpecification.LatLong
VEColor Class
Specifies the color and transparency to use when drawing VEShape Class objects on the map.
Constructor
67
Name Description
VEColor Constructor Initializes a new instance of the VEColor
object.
Public Properties
Name Description
VEColor.R Property Specifies the red component value. Valid
values range from 0 through 255.
VEColor.G Property Specifies the green component value. Valid
values range from 0 through 255.
VEColor.B Property Specifies the blue component value. Valid
values range from 0 through 255.
VEColor.A Property Specifies the alpha (transparency) component
value. Valid values range from 0.0 through 1.0.
Remarks
Color values are specified on a scale from 0 through 255, while transparency is specified on a
scale from 0.0 (transparent) to 1.0 (opaque).
See Also
VEShape Class
VEShapeType Enumeration
VEColor Constructor
Specifies the red, green, and blue colors, plus the level of transparency, for the VEColor object.
Syntax
var x = new VEColor(r, g, b, a);
Parameters
Parameter Description
r The red component value. Valid values range
from 0 through 255.
68
Parameter Description
g The green component value. Valid values
range from 0 through 255.
b The blue component value. Valid values range
from 0 through 255.
a The alpha (transparency) component value.
Valid values range from 0.0 through 1.0.
Remarks
VEColor objects are defined by the intensity of the red, green, and blue colors, plus the level of
transparency.
VEColor Properties
The properties of the VEColor class are listed here. For a complete list of VEColor class
members, see the VEColor Class topic.
Public Properties
Name Description
VEColor.R Property Specifies the red component value. Valid values
range from 0 through 255.
VEColor.G Property Specifies the green component value. Valid
values range from 0 through 255.
VEColor.B Property Specifies the blue component value. Valid values
range from 0 through 255.
VEColor.A Property Specifies the alpha (transparency) component
value. Valid values range from 0.0 through 1.0.
VEColor.A Property
Specifies the alpha (transparency) component value. Valid values range from 0.0 through 1.0.
Syntax
VEColor.A = value
Remarks
The A property specifies the transparency you want. A value of 0.0 means the color is completely
transparent, while a value of 1.0 means the color is completely opaque.
69
See Also
VEColor.B Property
VEColor.B Property
Specifies the blue component value. Valid values range from 0 through 255.
Syntax
VEColor.B = value
See Also
VEColor.A Property
VEColor.G Property
Specifies the green component value. Valid values range from 0 through 255.
Syntax
VEColor.G = value
See Also
VEColor.R Property
VEColor.A Property
VEColor.R Property
Specifies the red component value. Valid values range from 0 through 255.
Syntax
VEColor.R = value
See Also
VEColor.G Property
VEColor.B Property
VEColor.A Property
VECustomIconSpecification Class
Specifies the appearance of a VEShape Class object's custom icon.
Constructor
Name Description
VECustomIconSpecification Constructor Initializes a new instance of the
VECustomIconSpecification object.
70
Public Properties
Name Description
VECustomIconSpecification.BackColor
Property
A VEColor object representing the icon's
background and transparency.
VECustomIconSpecification.CustomHTML
Property
Custom HTML representing the pin's
appearance. When specified, this HTML
represents the pin's icon for 2D views only.
String.
VECustomIconSpecification.ForeColor Property A VEColor object representing the icon's text
color and transparency.
VECustomIconSpecification.Image Property A String representing the URL of an image file.
VECustomIconSpecification.ImageOffset
Property
A VEPixel object representing the image's
offset from the icon's anchor.
VECustomIconSpecification.TextBold Property Specifies whether the text for the icon should
be bold. Boolean.
VECustomIconSpecification.TextContent
Property
The actual text to display for the icon. String.
VECustomIconSpecification.TextFont Property A String containing the name of the font to use
for the icon text.
VECustomIconSpecification.TextItalics Property Specifies whether the text for the icon should
be italic. Boolean.
VECustomIconSpecification.TextOffset
Property
A VEPixel object representing the amount to
offset text from the top left corner.
VECustomIconSpecification.TextSize Property Specifies the size at which to display text, in
points. Integer.
VECustomIconSpecification.TextUnderline
Property
Specifies whether the text for the icon should
be underlined. Boolean.
Remarks
The 3D control cannot accept custom HTML for custom icons. This class allows you to specify
custom HTML for an icon in 2D mode, if desired, as well as a parameterized property list to define
the custom icon's appearance in 3D mode. If you do not need to support custom icons in 3D
mode, do not use this class.
71
VECustomIconSpecification Constructor
Initializes a new instance of the VECustomIconSpecification class.
Syntax
var x = new VECustomIconSpecification();
VECustomIconSpecification Properties
The properties of the VECustomIconSpecification class are listed here. For a complete list of
VECustomIconSpecification class members, see the VECustomIconSpecification Class
topic.
Public Properties
Name Description
VECustomIconSpecification.BackColor
Property
A VEColor object representing the icon's
background and transparency.
VECustomIconSpecification.CustomHTML
Property
Custom HTML representing the pin's
appearance. When specified, this HTML
represents the pin's icon for 2D views only.
String.
VECustomIconSpecification.ForeColor Property A VEColor object representing the icon's text
color and transparency.
VECustomIconSpecification.Image Property A String representing the URL of an image file.
VECustomIconSpecification.ImageOffset
Property
A VEPixel object representing the image's
offset from the icon's anchor.
VECustomIconSpecification.TextBold Property Specifies whether the text for the icon should
be bold. Boolean.
VECustomIconSpecification.TextContent
Property
The actual text to display for the icon. String.
VECustomIconSpecification.TextFont Property A String containing the name of the font to use
for the icon text.
VECustomIconSpecification.TextItalics Property Specifies whether the text for the icon should
be italic. Boolean.
VECustomIconSpecification.TextOffset
Property
A VEPixel object representing the amount to
offset text from the top left corner.
VECustomIconSpecification.TextSize Property Specifies the size at which to display text, in
72
Name Description
points. Integer.
VECustomIconSpecification.TextUnderline
Property
Specifies whether the text for the icon should
be underlined. Boolean.
VECustomIconSpecification.BackColor Property
A VEColor object representing the icon's background and transparency.
Syntax
VECustomIconSpecification.BackColor = object
Remarks
See Also
VEColor Class
VECustomIconSpecification.CustomHTML Property
Custom HTML representing the pin's appearance. When specified, this HTML represents the
pin's icon for 2D views only. String.
Syntax
VECustomIconSpecification.CustomHTML = string
Remarks
The custom HTML is a string value, beginning with the < character, and ending with the >
character. In the middle should be well-formed HTML code.
If the CustomHTML property is present, the HTML code defined therein is used to display the
icon in 2D mode. If the CustomHTML property is not present, the icon still uses the other
properties that have been set for the VECustomIconSpecification object.
In 3D mode, the CustomHTML property is ignored.
VECustomIconSpecification.ForeColor Property
A VEColor object representing the icon's text color and transparency.
Syntax
VECustomIconSpecification.ForeColor = color
Remarks
See Also
VEColor Class
73
VECustomIconSpecification.Image Property
A String representing the URL of an image file.
Syntax
VECustomIconSpecification.Image = string;
Remarks
This value must be a fully qualified, externally accessible URL for 3D use. If the URL is not valid,
the property is ignored and the icon is not displayed.
VECustomIconSpecification.ImageOffset Property
A VEPixel object representing the image's offset from the icon's anchor.
Syntax
VECustomIconSpecification.ImageOffset = object
Remarks
See Also
VEPixel Class
VEShape.SetIconAnchor Method
VEShape.GetIconAnchor Method
VECustomIconSpecification.TextBold Property
Specifies whether the text for the icon should be bold. Boolean.
Syntax
VECustomIconSpecification.TextBold = boolean
Remarks
VECustomIconSpecification.TextContent Property
The actual text to display for the icon. String.
Syntax
VECustomIconSpecification.TextContent = string
Remarks
VECustomIconSpecification.TextFont Property
A String containing the name of the font to use for the icon text.
Syntax
74
VECustomIconSpecification.TextFont = string
Remarks
VECustomIconSpecification.TextItalics Property
Specifies whether the text for the icon should be italic. Boolean.
Syntax
VECustomIconSpecification.TextItalics = boolean
Remarks
VECustomIconSpecification.TextOffset Property
A VEPixel object representing the amount to offset text from the top left corner.
Syntax
VECustomIconSpecification.TextOffset = object
Remarks
The VEPixel object defines a pair of pixel coordinates (VEPixel.x and VEPixel.y). This determines
the pixel amount to offset the text to the right of, and below, the top left corner of the icon.
See Also
VEPixel Class
VECustomIconSpecification.TextSize Property
Specifies the size at which to display text, in points. Integer.
Syntax
VECustomIconSpecification.TextSize = value
Remarks
VECustomIconSpecification.TextUnderline Property
Specifies whether the text for the icon should be underlined. Boolean.
Syntax
VECustomIconSpecification.TextUnderline = boolean
Remarks
VEDashboardSize Enumeration
An enumeration that represents the size and type of dashboard to be displayed on the map.
75
Syntax
VEDashboardSize{ Normal Small Tiny }
Members
Member Description
Normal This is the dashboard that is used by default.
Small This is a dashboard smaller than the default: it
only contains zoom-out (+) and zoom-in (-)
buttons and road, aerial, and hybrid buttons for
changing the map style.
Tiny This is the smallest dashboard option available.
This dashboard only contains zoom-out (+) and
zoom-in (-) buttons.
See Also
VEMap.SetDashboardSize Method
VEMap.HideDashboard Method
VEDataType Enumeration
An enumeration of shape layer data types.
Syntax
VEDataType ( GeoRSS VECollection ImportXML }
Members
Member Description
GeoRSS This represents a GeoRSS data import.
VECollection This represents a Bing Maps Collection
(http://maps.live.com) import.
ImportXML This represents an XML data import.
76
Remarks
This enumeration represents the type of data to be imported into a shape layer as a
VEShapeSourceSpecification Class object using the VEMap.ImportShapeLayerData Method.
Supported File Formats
GeoRSS
If the data type is VEDataType.GeoRSS, then the file specified in the
VEShapeSourceSpecification.LayerSource Property must be a valid XML file. Additionally, the
file must be in W3C, Simple, or GML format and contain at least one supported type.
The following types are supported:
geo:lat
geo:lon
geo:long
geo:point
geo:Point
Point
pos
posList
georss:point
georss:line
georss:polygon
georss:where
gml:Point
gml:pos
gml:posList
gml:LineString
gml:Polygon
gml:exterior
gml:interior
gml:LinearRing
VECollection
If the data type is VEDataType.VECollection, then the URL specified in the
VEShapeSourceSpecification.LayerSource Property must be a valid Bing Maps
(http://maps.live.com) collection GUID.
ImportXML
If the data type is VEDataType.ImportXML, then the file specified in the
VEShapeSourceSpecification.LayerSource Property must be a valid XML file.
77
If the specified XML file is a KML file, the following KML elements are supported. These
elements are case sensitive. Note that the supported elements may contain sub elements that
are not supported. The sub elements refreshMode and refreshInterval are not supported.
Element Name Notes
Placemark Required
MultiGeometry Converts to multiple VEShape objects
Polygon
LineString
LinearRing
Point
NetworkLink One level support only. Data is imported once
when the VEMap.ImportShapeLayerData
Method is called.
Style Unsupported if the element contains a StyleUrl
that points to a separate KML file
Icon Unsupported if the element contains a StyleUrl
that points to a separate KML file
StyleUrl Unsupported if the specified URL is a separate
KML file
IconStyle Unsupported if the element contains a StyleUrl
that points to a separate KML file
LineStyle Unsupported if the element contains a StyleUrl
that points to a separate KML file
PolygonStyle Unsupported if the element contains a StyleUrl
that points to a separate KML file
See Also
VEShapeLayer Class
VEDistanceUnit Enumeration
An enumeration of the distance unit used for generating routes and itineraries.
78
Syntax
VEDistanceUnit{ Miles Kilometers }
Members
Member Description
Miles Generates route information in miles.
Kilometers Generates route information in kilometers.
Remarks
This enumeration is used in the units parameter of the VEMap.GetRoute Method and as the
VERouteItineraryDeprecated.DistanceUnit Property to specify the distance units to use when
generating the route.
This enumeration is also used with the VEMap.SetScaleBarDistanceUnit Method to change the
map scale bar units.
VEException Class
Contains the exception information for the map control.
Public Properties
Name Description
VEException.source Property The source object that caused the exception.
VEException.name Property The name of the exception.
VEException.message Property A text description of the exception.
Remarks
An exception returned from Bing Maps will always contain a value for the message property. The
source and name properties may have values, or may be null or undefined.
If you want to handle VEMap object errors, use the VEMap.onerror Event.
Example
VirtualEarthSDK#54
79
VEException Properties
The properties of the VEException class are listed here. For a complete list of VEException
class members, see the VEException Class topic.
Public Properties
Name Description
VEException.source Property The source object that caused the exception.
VEException.name Property The name of the exception.
VEException.message Property A text description of the exception.
VEException.message Property
A text description of the exception.
Syntax
VEException.message = value
VEException.name Property
The name of the exception.
Syntax
VEException.name = value
VEException.source Property
The source object that caused the exception.
Syntax
VEException.source = value
VEFailedShapeRequest Enumeration
Defines a list of the actions on how to draw the polygons or the polylines whose points exceed
the maximum limit or when a request to the server fails.
Syntax
VEFailedShapeRequest{ DoNotDraw DrawInaccurately QueueRequest }
80
Members
Member Description
DoNotDraw Do not draw the shape
DrawInaccurately Draw the shape inaccurately
QueueRequest Resubmit the drawing request
See Also
VEMap.SetFailedShapeRequest Method
VEFindResult Class
A single "what" result returned from a VEMap.Find Method search.
Public Properties
Name Description
VEFindResult.Shape Property A reference to the VEShape Class object
corresponding to this FindResult object. The
VEShape object represents the result's
pushpin displayed on the map.
VEFindResult.Name Property The name of the found result.
VEFindResult.Description Property The description of the found result.
VEFindResult.FindType Property The VEFindType Enumeration enumeration
that represents the type of Find that was
performed. This matches the findType
parameter specified in the Find method call
from which this result was generated.
VEFindResult.IsSponsored Property A Boolean value that indicates whether the
found result is a paid advertisement.
VEFindResult.LatLong Property A VELatLong Class object that represents the
location of the found result.
VEFindResult.Phone Property The telephone number of the found result.
81
VEFindResult Properties
The properties of the VEFindResult class are listed here. For a complete list of VEFindResult
class members, see the VEFindResult Class topic.
Public Properties
Name Description
VEFindResult.Shape Property A reference to the VEShape Class object
corresponding to this FindResult object. The
VEShape object represents the result's pushpin
displayed on the map.
VEFindResult.Name Property The name of the found result.
VEFindResult.Description Property The description of the found result.
VEFindResult.FindType Property The VEFindType Enumeration enumeration
that represents the type of Find that was
performed. This matches the findType
parameter specified in the Find method call
from which this result was generated.
VEFindResult.IsSponsored Property A Boolean value that indicates whether the
found result is a paid advertisement.
VEFindResult.LatLong Property A VELatLong Class object that represents
the location of the found result.
VEFindResult.Phone Property The telephone number of the found result.
VEFindResult.Description Property
The description of the found result.
Syntax
VEFindResult.Description = value
Remarks
The description field is typically the address of the found result.
VEFindResult.IsSponsored Property
A Boolean value that indicates whether the found result is a paid advertisement.
Syntax
VEFindResult.IsSponsored = value
82
Remarks
An IsSponsored value of true indicates that the found result is a paid advertisement.
VEFindResult.LatLong Property
A VELatLong Class object that represents the location of the found result.
Syntax
VEFindResult.LatLong = value
VEFindResult.Name Property
The name of the found result.
Syntax
VEFindResult.Name = value
Remarks
VEFindResult.Phone Property
The telephone number of the found result.
Syntax
VEFindResult.Phone = value
Remarks
VEFindResult.FindType Property
Gets or sets the VEFindType Enumeration that represents the type of Find that was performed.
Syntax
VEFindResult.FindType = value
Remarks
This value matches the findType parameter specified in the VEMap.Find Method call from which
this result was generated.
VEFindResult.Shape Property
A reference to the VEShape Class object corresponding to this FindResult object. The VEShape
object represents the result's pushpin displayed on the map.
Syntax
VEFindResult.Shape = value
Remarks
83
VEFindType Enumeration
An enumeration of search types.
Syntax
VEFindType{ Businesses }
Members
Member Description
Businesses Performs a business search.
Remarks
This enumeration specifies the search types that can be performed using the VEMap.Find
Method. It is also present in every VEFindResult Class available in the callback after a
VEMap.Find Method call. Businesses is the only valid value.
See Also
VEMap.Find Method
VEGeocodeLocation Class
A location used to interpolate a found result for a location search.
Public Properties
Property Description
VEGeocodeLocation.LatLong Property A VELatLong Class object specifying the
latitude and longitude of the location.
VEGeocodeLocation.Precision Property A VELocationPrecision Enumeration value
specifying the precision of the location.
See Also
VEPlace Class
84
VEGeocodeLocation Properties
The properties of the VEGeocodeLocation class are listed here. For a complete list of
VEGeocodeLocation class members, see the VEGeocodeLocation Class topic.
Public Properties
Property Description
VEGeocodeLocation.LatLong Property A VELatLong Class object specifying the
latitude and longitude of the location.
VEGeocodeLocation.Precision Property A VELocationPrecision Enumeration value
specifying the precision of the location.
VEGeocodeLocation.LatLong Property
A VELatLong Class object specifying the latitude and longitude of the location.
Syntax
VEGeocodeLocation.LatLong
See Also
VEGeocodeLocation.Precision Property
VEGeocodeLocation.Precision Property
A VELocationPrecision Enumeration value specifying the precision of the location.
Syntax
VEGeocodeLocation.Precision
See Also
VEGeocodeLocation.LatLong Property
VEGeocodeOptions Class
Contains additional geocoding options for the VEMap.Geocode Method.
Constructor
Name Description
VEGeocodeOptions Constructor Initializes a new instance of the
VEGeocodeOptions class.
85
Public Properties
Name Description
VEGeocodeOptions.SetBestMapView Property A Boolean value that specifies whether the
map control moves the view to the first location
match. The default value is true.
VEGeocodeOptions.UseDefaultDisambiguation
Property
A Boolean value indicating whether to show the
disambiguation dialog if there is more than one
result with high match confidence. The default
value is true.
See Also
VEMap.Geocode Method
VEGeocodeOptions Constructor
Initializes a new instance of the VEGeocodeOptions Class.
Syntax
var x = new VEGeocodeOptions();
See Also
VEMap.Geocode Method
VEGeocodeOptions Properties
The properties of the VEGeocodeOptions class are listed here. For a complete list of
VEGeocodeOptions class members, see the VEGeocodeOptions Class topic.
Public Properties
Name Description
VEGeocodeOptions.SetBestMapView Property A Boolean value that specifies whether the
map control moves the view to the first location
match. The default value is true.
VEGeocodeOptions.UseDefaultDisambiguation
Property
A Boolean value indicating whether to show the
disambiguation dialog if there is more than one
result with high match confidence. The default
value is true.
86
VEGeocodeOptions.SetBestMapView Property
A Boolean value that specifies whether the map control moves the view to the first location
match. The default value is true.
Syntax
VEGeocodeOptions.SetBestMapView = value;
See Also
VEMap.Geocode Method
VEGeocodeOptions.UseDefaultDisambiguation Property
A Boolean value indicating whether to show the disambiguation dialog if there is more than one
result with high match confidence. The default value is true.
Syntax
VEGeocodeOptions.UseDefaultDisambiguation = value;
See Also
VEMap.Geocode Method
VEImageryMetadata Class
Contains information about the specified imagery.
Public Properties
Name Description
VEImageryMetadata.DateRangeStart Property A string specifying the start date of the date
range when the imagery was created.
VEImageryMetadata.DateRangeEnd Property A string specifying the end date of the date
range when the imagery was created.
See Also
VEMap.GetImageryMetadata Method
VEImageryMetadata Properties
The properties of the VEImageryMetadata class are listed here. For a complete list of
VEImageryMetadata class members, see the VEImageryMetadata Class topic.
Public Properties
87
Name Description
VEImageryMetadata.DateRangeStart Property A string specifying the start date of the date
range when the imagery was created.
VEImageryMetadata.DateRangeEnd Property A string specifying the end date of the date
range when the imagery was created.
See Also
VEMap.GetImageryMetadata Method
VEImageryMetadata.DateRangeStart Property
A string specifying the start date of the date range when the imagery was created.
Syntax
VEImageryMetadata.DateRangeStart
Remarks
The format of the DateRangeStart property string is "mm/dd/yyyy".
See Also
VEImageryMetadata Class
VEMap.GetImageryMetadata Method
VEImageryMetadata.DateRangeEnd Property
A string specifying the end date of the date range when the imagery was created.
Syntax
VEImageryMetadata.DateRangeEnd
Remarks
The format of the DateRangeEnd property string is "mm/dd/yyyy".
See Also
VEImageryMetadata Class
VEMap.GetImageryMetadata Method
VEImageryMetadataOptions Class
Contains the options that represent the imagery.
Constructor
88
Name Description
VEImageryMetadataOptions Constructor Initializes a new instance of a
VEImageryMetadataOptions object.
Public Properties
Name Description
VEImageryMetadataOptions.LatLong Property A VELatLong Class object specifying the center
of the map view. Optional. Defaults to the
center of the current map view.
VEImageryMetadataOptions.MapStyle Property A VEMapStyle Enumeration value specifying
the map style. Optional. Defaults to the current
map style.
VEImageryMetadataOptions.ZoomLevel
Property
An integer specifying the zoom level. Optional.
Defaults to the current zoom level.
See Also
VEMap.GetImageryMetadata Method
VEImageryMetadataOptions Constructor
Initializes a new instance of the VEImageryMetadataOptions Class.
Syntax
var x = new VEImageryMetadataOptions();
See Also
VEMap.GetImageryMetadata Method
VEImageryMetadataOptions Properties
The properties of the VEImageryMetadataOptions class are listed here. For a complete list of
VEImageryMetadataOptions class members, see the VEImageryMetadataOptions Class topic
Public Properties
Name Description
VEImageryMetadataOptions.LatLong Property A VELatLong Class object specifying the center
89
Name Description
of the map view. Optional. Defaults to the
center of the current map view.
VEImageryMetadataOptions.MapStyle Property A VEMapStyle Enumeration value specifying
the map style. Optional. Defaults to the current
map style.
VEImageryMetadataOptions.ZoomLevel
Property
An integer specifying the zoom level. Optional.
Defaults to the current zoom level.
See Also
VEMap.GetImageryMetadata Method
VEImageryMetadataOptions.LatLong Property
A VELatLong Class object specifying the center of the map view. Defaults to the center of the
current map view.
Syntax
VEImageryMetadataOptions.LatLong = new VELatLong();
See Also
VEImageryMetadataOptions Class
VEImageryMetadataOptions.MapStyle Property
A VEMapStyle Enumeration value specifying the map style. Defaults to the current map style.
Syntax
VEImageryMetadataOptions.MapStyle = value;
See Also
VEImageryMetadataOptions Class
VEImageryMetadataOptions.ZoomLevel Property
An integer specifying the zoom level. Defaults to the current zoom level.
Syntax
VEImageryMetadataOptions.ZoomLevel = value;
See Also
VEImageryMetadataOptions Class
90
VELatLong Class
Contains the latitude and longitude of a single point on the globe.
Constructor
Name Description
VELatLong Constructor Initializes a new instance of the VELatLong
object.
Public Methods
Name Description
VELatLong.SetAltitude Method Specifies the altitude for a point on the globe.
Public Properties
Name Description
VELatLong.Altitude Property Specifies the altitude of a single point on the
globe.
VELatLong.AltitudeMode Property Specifies the mode in which an altitude is
represented.
VELatLong.Latitude Property Specifies the latitude of a single point on the
globe.
VELatLong.Longitude Property Specifies the longitude of a single point on the
globe.
Remarks
The Latitude and Longitude values use WGS 84 datum.
To obtain the VELatLong object of a point on the current map, use the VEMap.PixelToLatLong
Method. To convert a VELatLong object to a point on the current map, use the
VEMap.LatLongToPixel Method.
VELatLong Constructor
Initializes a new instance of the VELatLong Class.
91
Syntax
var x = new VELatLong(latitude, longitude, altitude, altitudeMode);
Parameters
Parameter Description
latitude The latitude of a single point on the globe
longitude The longitude of a single point on the globe
altitude The altitude of a single point on the globe.
Optional. The default value is 0 (zero).
altitudeMode A VEAltitudeMode Enumeration value
representing the mode in which an altitude is
represented. Optional. The default value is
VEAltitudeMode.Default.
Remarks
The latitude and longitude values use WGS 84 datum.
See Also
VELatLong.Altitude Property
VELatLong.AltitudeMode Property
VELatLong.Latitude Property
VELatLong.Longitude Property
VELatLong Properties
The properties of the VELatLong class are listed here. For a complete list of VELatLong class
members, see the VELatLong Class topic.
Public Properties
Name Description
VELatLong.Altitude Property Specifies the altitude of a single point on the
globe.
VELatLong.AltitudeMode Property Specifies the mode in which an altitude is
represented.
VELatLong.Latitude Property Specifies the latitude of a single point on the
globe.
92
Name Description
VELatLong.Longitude Property Specifies the longitude of a single point on the
globe.
VELatLong.Altitude Property
Specifies the altitude of a single point on the globe.
Syntax
VELatLong.Altitude = value
Remarks
The value is a floating-point value representing either meters above the ground, or meters above
the WGS 84 ellipsoid, as specified by the VELatLong.AltitudeMode Property.
See Also
VELatLong.SetAltitude Method
VELatLong.AltitudeMode Property
Specifies the mode in which an altitude is represented.
Syntax
VELatLong.AltitudeMode = value
Remarks
The value must be one of the VEAltitudeMode Enumeration values.
See Also
VELatLong.SetAltitude Method
VELatLong.Latitude Property
Specifies the latitude of a single point on the globe.
Syntax
VELatLong.Latitude = value
Remarks
This property is a floating-point value in decimal degrees representing a WGS 84 datum.
VELatLong.Longitude Property
Specifies the longitude of a single point on the globe.
Syntax
93
VELatLong.Longitude = value
Remarks
This property is a floating-point value in decimal degrees representing a WGS 84 datum.
VELatLong Methods
The methods of the VELatLong class are listed here. For a complete list of VELatLong class
members, see the VELatLong Class topic.
Public Methods
Name Description
VELatLong.SetAltitude Method Specifies the altitude for a point on the globe.
VELatLong.SetAltitude Method
Specifies the altitude for a point on the globe.
Syntax
VELatLong.SetAltitude(altitude, mode)
Parameters
Parameter Description
altitude The altitude, in meters
mode The VEAltitudeMode Enumeration value that
defines whether altitude is relative to ground-
level or absolute
Example
VirtualEarthSDK#41
See Also
VELatLong.Altitude Property
VELatLong.AltitudeMode Property
VELatLongRectangle Class
Contains VELatLong Class objects that define the boundaries of the current map view.
Constructor
94
Name Description
VELatLongRectangle Constructor Initializes a new instance of the
VELatLongRectangle Class object.
Public Properties
Name Description
VELatLongRectangle.TopLeftLatLong Property A VELatLong Class object that specifies the
latitude and longitude of the upper-left corner of
the map view.
VELatLongRectangle.BottomRightLatLong
Property
A VELatLong Class object that specifies the
latitude and longitude of the lower-right corner
of the map view.
VELatLongRectangle.TopRightLatLong
Property
If the map is in 3D mode, a VELatLong Class
object that specifies the latitude and longitude
of the upper-right corner of the map view.
VELatLongRectangle.BottomLeftLatLong
Property
If the map is in 3D mode, a VELatLong Class
object that specifies the latitude and longitude
of the lower-left corner of the map
Remarks
The VELatLongRectangle object is used as a parameter in the VETileSourceSpecification
Constructor. An array of VELatLongRectangle objects is used with the
VETileSourceSpecification.Bounds Property.
A VELatLongRectangle object is returned by the VEMap.GetMapView Method.
VELatLongRectangle Constructor
Initializes a new instance of the VELatLongRectangle class.
Syntax
var x = new VELatLongRectangle(TopLeftLatLong, BottomRightLatLong, TopRightLatLong,
BottomLeftLatLong);
Parameters
95
Parameter Description
TopLeftLatLong A VELatLong Class object that specifies the
latitude and longitude of the upper-left corner of
the map view
BottomRightLatLong A VELatLong Class object that specifies the
latitude and longitude of the lower-right corner
of the map view
TopRightLatLong If the map is in 3D mode, a VELatLong Class
object that specifies the latitude and longitude
of the upper-right corner of the map view
BottomLeftLatLong If the map is in 3D mode, a VELatLong Class
object that specifies the latitude and longitude
of the lower-left corner of the map view
VELatLongRectangle Properties
The properties of the VELatLongRectangle class are listed here. For a complete list of
VELatLongRectangle class members, see the VELatLongRectangle Class topic.
Public Properties
Name Description
VELatLongRectangle.TopLeftLatLong Property A VELatLong Class object that specifies the
latitude and longitude of the upper-left corner of
the map view.
VELatLongRectangle.BottomRightLatLong
Property
A VELatLong Class object that specifies the
latitude and longitude of the lower-right corner
of the map view.
VELatLongRectangle.TopRightLatLong
Property
If the map is in 3D mode, a VELatLong Class
object that specifies the latitude and longitude
of the upper-right corner of the map view.
VELatLongRectangle.BottomLeftLatLong
Property
If the map is in 3D mode, a VELatLong Class
object that specifies the latitude and longitude
of the lower-left corner of the map
VELatLongRectangle.BottomLeftLatLong Property
A VELatLong Class object that specifies the latitude and longitude of the lower-left corner of the
map view.
96
Syntax
VELatLongRectangle.BottomLeftLatLong = value
VELatLongRectangle.BottomRightLatLong Property
A VELatLong Class object that specifies the latitude and longitude of the lower-right corner of the
map view.
Syntax
VELatLongRectangle.BottomRightLatLong = value
VELatLongRectangle.TopLeftLatLong Property
A VELatLong Class object that specifies the latitude and longitude of the upper-left corner of the
map view.
Syntax
VELatLongRectangle.TopLeftLatLong = value
VELatLongRectangle.TopRightLatLong Property
A VELatLong Class object that specifies the latitude and longitude of the upper-right corner of the
map view.
Syntax
VELatLongRectangle.TopRightLatLong = value
VELocationPrecision Enumeration
An enumeration of location precision values.
Syntax
VELocationPrecision { Interpolated Rooftop }
Members
Member Description
Interpolated The precision is estimated from multiple
geocoded sources.
Rooftop The precision is from a single match.
97
See Also
VEGeocodeLocation.Precision Property
VEPlace.Precision Property
VEMap Class
Provides Bing map and search functionality to a Web page.
Constructor
Name Description
VEMap Constructor Initializes a new instance of the VEMap object.
Public Events
The events of the VEMap Class are divided into events specific to Bing Maps, mouse events, and
keyboard events. For a complete list of VEMap events, see the VEMap Events topic.
Name Description
Keyboard Events Input events produced by the keyboard
connected to the computer.
Mouse Events Input events produced by the mouse device
connected to the computer.
Bing Maps Events The events of the VEMap Class specific to
Bing Maps.
Public Methods
Name Description
VEMap.AddControl Method Adds a custom control to the map.
VEMap.AddCustomLayer Method Adds a custom layer to the map.
VEMap.AddShape Method Adds an existing VEShape Class object, as
specified by the shape parameter, to the base
layer.
VEMap.AddShapeLayer Method Adds the specified shape layer to the map.
VEMap.AddTileLayer Method Adds a tile layer to the map, and if the
98
Name Description
visibleOnLoad parameter is true, it also shows
it on the map.
VEMap.AttachEvent Method Attaches a Map Control event to a specified
function.
VEMap.Clear Method Removes all shapes, shape layers, and search
results on the map. Also removes the route
from the map, if one is displayed.
VEMap.ClearInfoBoxStyles Method Clears out all of the default Bing Maps info box
CSS styles.
VEMap.ClearTraffic Method Clears the traffic map.
VEMap.DeleteAllShapeLayers Method Deletes all shape layers, along with any shapes
within the layers.
VEMap.DeleteAllShapes Method Deletes all shapes in all layers, leaving empty
layers behind.
VEMap.DeleteControl Method Removes the specified control from the map.
VEMap.DeleteRoute Method Clears the current route, VERoute Class object,
from the map.
VEMap.DeleteShape Method Deletes a VEShape Class object from any
layer, including the base map layer.
VEMap.DeleteShapeLayer Method Deletes the specified shape layer from the
map.
VEMap.DeleteTileLayer Method Deletes a tile layer from view.
VEMap.DetachEvent Method Detaches the specified map control event so
that it no longer calls the specified function.
VEMap.Dispose Method Deletes the VEMap object and releases any
associated resources
VEMap.EnableShapeDisplayThreshold Method Specifies whether shapes are drawn below a
threshold zoom level.
VEMap.EndContinuousPan Method Stops the continuous map panning initiated by
a call to the VEMap.StartContinuousPan
Method.
VEMap.Find Method Returns an array of found results.
VEMap.FindLocations Method Performs a search for locations that match a
99
Name Description
VELatLong Class input.
VEMap.Geocode Method Finds a geographic location based on a
specified address or place name string as well
as other geocoding options.
VEMap.GetAltitude Method In 3D mode, returns a double that represents
the altitude (in meters) above the geoid.
VEMap.GetBirdseyeScene Method If the map view is already set to bird's eye,
returns the current VEBirdseyeScene Class
object.
VEMap.GetCenter Method Returns a VELatLong Class object that
represents the location of the center of the
current map view.
VEMap.GetDirections Method Draws a multi-point route on the map and
sends details about the route to a callback
function.
VEMap.GetHeading Method In 3D mode, returns an integer that represents
the compass heading of the current map view.
VEMap.GetImageryMetadata Method Returns information about the requested
imagery, including imagery date stamps and
vendor attribution.
VEMap.GetLeft Method Returns the pixel value of the left edge of the
map control.
VEMap.GetMapMode Method Returns the current map mode.
VEMap.GetMapStyle Method Returns the current map style.
VEMap.GetMapView Method Returns the current map view object as a
VELatLongRectangle Class object.
VEMap.GetPitch Method In 3D mode, returns an integer that represents
the pitch of the current map view.
VEMap.GetRoute Method Deprecated. Draws a route on the map and
sends details about the route to a callback
function.
VEMap.GetShapeByID Method Gets the reference to a VEShape Class object
based on its internal identifier.
VEMap.GetShapeLayerByIndex Method Gets the reference to a VEShapeLayer Class
100
Name Description
object based on its index.
VEMap.GetShapeLayerCount Method Gets the total number of shape layers on the
map.
VEMap.GetTileLayerCount Method Gets the number of tile layers.
VEMap.GetTileLayerByID Method Gets a tile layer based upon its identifier.
VEMap.GetTileLayerByIndex Method Gets a tile layer based upon an index value.
VEMap.GetTop Method Returns the pixel value of the top edge of the
map control.
VEMap.GetVersion Method Returns the current version of the map control.
VEMap.GetZoomLevel Method Returns the current zoom level of the map.
VEMap.Hide3DNavigationControl Method In 3D mode, hides the default user interface for
controlling the map in 3D mode. By default, this
control is shown.
VEMap.HideAllShapeLayers Method Hides all of the shape layers on the map.
VEMap.HideBaseTileLayer Method Hides the base tile layer of the map.
VEMap.HideControl Method Hides the specified control from view.
VEMap.HideDashboard Method Hides the default user interface for controlling
the map (the compass and the zoom control).
VEMap.HideFindControl Method Deprecated. Removes the Find control from the
map.
VEMap.HideInfoBox Method Hides a shape's custom or default info box.
VEMap.HideMiniMap Method Hides the mini map from view.
VEMap.HideScalebar Method Hides the scale bar from the map.
VEMap.HideTileLayer Method Hides a tile layer from view.
VEMap.HideTrafficLegend Method Hides the traffic legend.
VEMap.Import3DModel Method Imports data from a Wavefront OBJ file and
displays it as a 3D model on the map.
VEMap.ImportShapeLayerData Method Imports data from a GeoRSS feed, Bing Maps
(http://maps.live.com) collection, or KML URL.
VEMap.IncludePointInView Method Changes the map view so that it includes both
the specified VELatLong Class point and the
101
Name Description
center point of the current map.
VEMap.IsBirdseyeAvailable Method Determines whether the bird's eye map style is
available in the current map view.
VEMap.LatLongToPixel Method Converts an array of VELatLong Class objects
(latitude/longitude pair) to an array of VEPixel
Class objects.
VEMap.LoadTraffic Method Loads the traffic map.
VEMap.LoadMap Method Loads the specified map. All parameters are
optional.
VEMap.Pan Method When in 2D mode, moves the map the
specified amount.
VEMap.PanToLatLong Method Pans the map to a specific latitude and
longitude.
VEMap.PixelToLatLong Method Converts a pixel (a point on the map) to a
VELatLong Class object (latitude/longitude
pair).
VEMap.RemoveCustomLayer Method Removes a custom layer from the map.
VEMap.Resize Method Resizes the map based on the specified width
and height.
VEMap.Search Method Performs a search based on a given query and
options.
VEMap.SetAltitude Method In 3D mode, sets the altitude, in meters, above
the WGS 84 ellipsoid in the map view.
VEMap.SetBirdseyeOrientation Method Changes the orientation of the existing bird's
eye image (VEBirdseyeScene Class object) to
the specified orientation.
VEMap.SetBirdseyeScene Method Overloaded. Displays the specified bird's eye
image.
VEMap.SetCenter Method Centers the map to a specific latitude and
longitude.
VEMap.SetCenterAndZoom Method Centers the map to a specific latitude and
longitude and sets the zoom level.
VEMap.SetClientToken Method Sets a Bing Maps token for the VEMap object.
102
Name Description
VEMap.SetCredentials Method Sets the credentials to use to authenticate map
service requests.
VEMap.SetDashboardSize Method Sets the map dashboard size and type.
VEMap.SetDefaultInfoBoxStyles Method Sets the info box CSS styles back to their
original classes.
VEMap.SetFailedShapeRequest Method Specifies what the map control does when a
request to the server to get the accurate
position of a shape when the map style is
changed to birdseye fails.
VEMap.SetHeading Method In 3D mode, sets the compass heading of the
current map view.
VEMap.SetMapMode Method Sets the mode of the map.
VEMap.SetMapStyle Method Sets the style of the map.
VEMap.SetMapView Method Sets the map view to include all of the points,
lines, or polygons specified in the provided
array, or to the view defined by a
VEMapViewSpecification Class object.
VEMap.SetMouseWheelZoomToCenter
Method
Specifies whether to zoom to the center of the
screen or to the cursor position on the screen.
VEMap.SetPitch Method In 3D mode, sets the pitch of the current map
view.
VEMap.SetPrintOptions Method Sets the print options for the current map.
VEMap.SetScaleBarDistanceUnit Method Sets the distance unit (kilometers or miles) for
the map scale.
VEMap.SetShapesAccuracy Method Specifies the accuracy in converting shapes
when the map style is changed to birdseye.
VEMap.SetShapesAccuracyRequestLimit
Method
Specifies how to draw the polygons or the
polylines whose points exceed the maximum
limit or when a request to the server fails when
the map style is changed to birdseye.
VEMap.SetTileBuffer Method Sets the number of "rings" of map tiles that
should be loaded outside of the visible
mapview area.
VEMap.SetTrafficLegendText Method Specifies the text shown with the traffic legend,
103
Name Description
if visible.
VEMap.SetZoomLevel Method Sets the view of the map to the specified zoom
level.
VEMap.Show3DBirdseye Method Controls whether or not to show the Birdseye
and BirdseyeHybrid map styles when the map
mode is set to VEMapMode.Mode3D.
VEMap.Show3DNavigationControl Method In 3D mode, shows the default user interface
for controlling the map in 3D mode. By default,
this control is shown.
VEMap.ShowAllShapeLayers Method Shows all shape layers on the map.
VEMap.ShowBaseTileLayer Method Shows the base tile layer of the map.
VEMap.ShowControl Method Makes the specified control visible. This
method only affects control elements that have
been hidden from view using the
VEMap.HideControl Method.
VEMap.ShowDashboard Method Shows the default user interface for controlling
the map (the compass-and-zoom control). By
default, this control is shown.
VEMap.ShowDisambiguationDialog Method Specifies whether the default disambiguation
dialog is displayed when multiple results are
returned from a location query.
VEMap.ShowFindControl Method Deprecated. Shows the Find control, which
enables users to enter search queries.
VEMap.ShowInfoBox Method Shows a shape's custom or default info box.
VEMap.ShowMessage Method Displays the specified message in a dialog box
on the map.
VEMap.ShowMiniMap Method Displays the mini map at the specified offset
from the top left corner of the screen.
VEMap.ShowScalebar Method Displays the scale bar on the map.
VEMap.ShowTileLayer Method Shows a tile layer from view.
VEMap.ShowTrafficLegend Method Displays the traffic legend.
VEMap.StartContinuousPan Method Moves the map in the specified direction until
the VEMap.EndContinuousPan Method is
called.
104
Name Description
VEMap.ZoomIn Method Increases the map zoom level by 1.
VEMap.ZoomOut Method Decreases the map zoom level by 1.
Public Properties
Name Description
VEMap.onLoadMap Property Specifies the function to call when the map is
first loaded.
See Also
VEMap Event Object Properties
VEMap Constructor
Initializes a new instance of the VEMap class.
Syntax
var x = new VEMap(control_id);
Parameters
Parameter Description
control_id The ID of the HTML control that will contain the
map
Remarks
After initializing the map object, call the VEMap.LoadMap Method.
When you create a new instance of VEMap Class, you must specify the control on the Web page
that will contain the map. For example, it is most common to display the map in a DIV control.
You specify the value of the id parameter of the DIV control when initializing VEMap, as shown in
the following example.
See Also
VEMap.Dispose Method
105
VEMap Events
The events of the VEMap Class are listed here, divided into events specific to Bing Maps, mouse
events, and keyboard events. For a complete list of VEMap class members, see the VEMap
Class topic.
Public Events
Keyboard Events
Mouse Events
Bing Maps Events
VEMap Event Object Properties
Remarks
An event handler can disable the default Bing Maps action associated with that event by returning
true. If the event handler does not return a value or returns false, the default action occurs after
any actions defined in the event handler.
Note Use only the function name to attach a handler to an event. If an entire function is
attached as the handler to an event, it cannot be detached.
An event object is passed to the event handler when the event is fired. Depending on the event, a
subset of the values in the VEMap Event Object Properties table are accessible from the event
object. For a list of the properties that are available for a particular event, see the reference topic
for that event.
Event handlers can perform actions based on the type of element (normally a VEShape Class
object) by using the elementID property of the event object in conjunction with the
VEMap.GetShapeByID Method method. See the example code in the VEMap Event Object
Properties topic for further information.
Keyboard Events
The events of the VEMap Class class that are specific to keyboard events are listed here.
Public Keyboard Events
Name Description
VEMap.onkeypress Event Occurs when a key is pressed and released. This
is not supported in 3D mode.
VEMap.onkeydown Event Occurs when a key is pressed (but before it is
released). This is not supported in 3D mode.
VEMap.onkeyup Event Occurs when a key is released. This is not
supported in 3D mode.
See Also
Mouse Events
106
Bing Maps Events
VEMap Event Object Properties
VEMap.onkeypress Event
Occurs when a key is pressed, and released. This is not supported in 3D mode.
Syntax
VEMap.AttachEvent("onkeypress", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
altKey A Boolean object representing whether the
ALT key was held when the key was pressed.
ctrlKey A Boolean object representing whether the
CTRL key was held when the key was pressed.
eventName A String object representing the type of event
that occurred.
keyCode The key code of the key that has been pressed.
mapStyle The current map style
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
shiftKey A Boolean object representing whether the
shift key was held when the key was pressed.
zoomLevel The current zoom level of the map.
See Also
VEMap Event Object Properties
VEMap.onkeydown Event
Occurs when a key is pressed (but before it is released). This is not supported in 3D mode.
Syntax
VEMap.AttachEvent("onkeydown, function_name);
Return Value
107
A MapEvent object, which has the following properties:
Property Description
altKey A Boolean object representing whether the
ALT key was held when the key was pressed.
ctrlKey A Boolean object representing whether the
CTRL key was held when the key was pressed.
eventName A String object representing the type of event
that occurred.
keyCode The key code of the key that has been pressed.
mapStyle The current map style
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
shiftKey A Boolean object representing whether the
shift key was held when the key was pressed.
zoomLevel The current zoom level of the map.
See Also
VEMap Event Object Properties
VEMap.onkeyup Event
Occurs when a key is released. This is not supported in 3D mode.
Syntax
VEMap.AttachEvent("onkeyup", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
altKey A Boolean object representing whether the
ALT key was held when the key was pressed.
ctrlKey A Boolean object representing whether the
CTRL key was held when the key was pressed.
eventName A String object representing the type of event
108
Property Description
that occurred.
keyCode The key code of the key that has been pressed.
mapStyle The current map style
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
shiftKey A Boolean object representing whether the
shift key was held when the key was pressed.
zoomLevel The current zoom level of the map.
See Also
VEMap Event Object Properties
Mouse Events
The events of the VEMap Class that are specific to mouse events are listed here.
Public Mouse Events
Name Description
VEMap.onclick Event Occurs when a left or right mouse button is
single-clicked.
VEMap.ondoubleclick Event Occurs when a left mouse button is double-
clicked.
VEMap.onmousemove Event Occurs when the mouse cursor moves.
This is not supported in 3D mode.
VEMap.onmousedown Event Occurs when a mouse button (left, right, or
middle) is clicked (but before it is released).
VEMap.onmouseup Event Occurs when a mouse button (left, right, or
middle) is released.
VEMap.onmouseover Event Occurs when the mouse cursor moves over a
VEShape Class object.
VEMap.onmouseout Event Occurs when the mouse cursor moves away
from a VEShape object.
109
Name Description
VEMap.onmousewheel Event Occurs when the mouse wheel is moved.
This method is not supported in 3D
mode, and the coordinate values
returned in Firefox 1.5 and 2.0 are not
correct.
See Also
Bing Maps Events
Keyboard Events
VEMap Event Object Properties
VEMap.onclick Event
Occurs when a left or right mouse button is single-clicked.
Syntax
VEMap.AttachEvent("onclick", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
altKey A Boolean object representing whether the
ALT key was held when the key was pressed.
This is not supported in 3D mode.
ctrlKey A Boolean object representing whether the
CTRL key was held when the key was pressed.
This is not supported in 3D mode.
elementID The ID of the object associated with the event,
usually a VEShape Class object or the base
map.
eventName A String object representing the type of event
that occurred.
latLong The latLong coordinates of the clicked location.
110
Property Description
This only works in 3D mode and is not
supported in the Core Map Control. For 2D, you
can convert mapX and mapY to a latLong using
the VEMap.PixelToLatLong Method method.
leftMouseButton A Boolean object representing whether the left
mouse button has been clicked.
rightMouseButton A Boolean object representing whether the
right mouse button has been clicked.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
shiftKey A Boolean object representing whether the
shift key was held when the key was pressed.
This is not supported in 3D mode.
clientX The x coordinate of the mouse cursor relative to
the browser window.
clientY The y coordinate of the mouse cursor relative to
the browser window.
screenX The x coordinate of the mouse cursor relative to
the screen.
This is not supported in 3D mode.
screenY The y coordinate of the mouse cursor relative to
the screen.
This is not supported in 3D mode.
mapX The x coordinate of the map relative to the
screen.
111
Property Description
This is not supported in 3D mode.
mapY The y coordinate of the map relative to the
screen.
This is not supported in 3D mode.
zoomLevel The current zoom level of the map.
See Also
VEMap Event Object Properties
VEMap.ondoubleclick Event
VEMap.ondoubleclick Event
Occurs when the left mouse button is double-clicked.
Syntax
VEMap.AttachEvent("ondoubleclick", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
altKey A Boolean object representing whether the
ALT key was held when the key was pressed.
This is not supported in 3D mode.
ctrlKey A Boolean object representing whether the
CTRL key was held when the key was pressed.
This is not supported in 3D mode.
elementID The ID of the object associated with the event,
usually a VEShape Class object or the base
map.
eventName A String object representing the type of event
that occurred.
latLong The latlong coordinates of the clicked location.
This only works in 3D mode and is not
112
Property Description
supported in the Core Map Control. For 2D, you
can convert mapX and mapY to a latlong using
the VEMap.PixelToLatLong Method.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
shiftKey A Boolean object representing whether the
shift key was held when the key was pressed.
This is not supported in 3D mode.
clientX The x coordinate of the mouse cursor relative to
the browser window.
clientY The y coordinate of the mouse cursor relative to
the browser window.
screenX The x coordinate of the mouse cursor relative to
the screen.
This is not supported in 3D mode.
screenY The y coordinate of the mouse cursor relative to
the screen.
This is not supported in 3D mode.
mapX The x coordinate of the map relative to the
screen.
This is not supported in 3D mode.
mapY The y coordinate of the map relative to the
screen.
This is not supported in 3D mode.
113
Property Description
zoomLevel The current zoom level of the map.
See Also
VEMap.onclick Event
VEMap.onmousedown Event
Occurs when a mouse button (left, right, or middle) is clicked but before it is released.
Syntax
VEMap.AttachEvent("onmousedown", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
altKey A Boolean object representing whether the
ALT key was held when the key was pressed.
This is not supported in 3D mode.
ctrlKey A Boolean object representing whether the
CTRL key was held when the key was pressed.
This is not supported in 3D mode.
elementID The ID of the object associated with the event,
usually a VEShape Class object or the base
map.
eventName A String object representing the type of event
that occurred.
latLong The latlong coordinates of the clicked location.
This only works in 3D mode and is not
supported in the Core Map Control. For 2D, you
can convert mapX and mapX to a latlong using
the VEMap.PixelToLatLong Method.
leftMouseButton A Boolean object representing whether the left
mouse button has been clicked.
rightMouseButton A Boolean object representing whether the right
114
Property Description
mouse button has been clicked.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
shiftKey A Boolean object representing whether the
shift key was held when the key was pressed.
This is not supported in 3D mode.
clientX The x coordinate of the mouse cursor relative to
the browser window.
clientY The y coordinate of the mouse cursor relative to
the browser window.
screenX The x coordinate of the mouse cursor relative to
the screen.
This is not supported in 3D mode.
screenY The y coordinate of the mouse cursor relative to
the screen.
This is not supported in 3D mode.
mapX The x coordinate of the map relative to the
screen.
This is not supported in 3D mode.
mapY The y coordinate of the map relative to the
screen.
This is not supported in 3D mode.
zoomLevel The current zoom level of the map.
115
See Also
VEMap.onmouseup Event
VEMap Event Object Properties
VEMap.onmousemove Event
Occurs when the mouse cursor moves.
Syntax
VEMap.AttachEvent("onmousemove", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
altKey A Boolean object representing whether the
ALT key was held when the key was pressed.
ctrlKey A Boolean object representing whether the
CTRL key was held when the key was pressed.
elementID The ID of the object associated with the event,
usually a VEShape Class object or the base
map.
eventName A String object representing the type of event
that occurred.
leftMouseButton A Boolean object representing whether the left
mouse button has been clicked.
rightMouseButton A Boolean object representing whether the
right mouse button has been clicked.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
shiftKey A Boolean object representing whether the
shift key was held when the key was pressed.
clientX The x coordinate of the mouse cursor relative
to the browser window.
116
Property Description
clientY The y coordinate of the mouse cursor relative
to the browser window.
screenX The x coordinate of the mouse cursor relative
to the screen.
screenY The y coordinate of the mouse cursor relative
to the screen.
mapX The x coordinate of the map relative to the
screen.
mapY The y coordinate of the map relative to the
screen.
zoomLevel The current zoom level of the map.
Remarks
This is not supported in 3D mode.
VEMap.onmouseout Event
Occurs when the mouse cursor moves away from a VEShape Class object.
Syntax
VEMap.AttachEvent("onmouseout", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
altKey A Boolean object representing whether the
ALT key was held when the key was pressed.
This is not supported in 3D mode.
ctrlKey A Boolean object representing whether the
CTRL key was held when the key was pressed.
This is not supported in 3D mode.
elementID The ID of the object associated with the event,
usually a VEShape Class object or the base
map.
117
Property Description
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String object. Valid
String results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
shiftKey A Boolean object representing whether the
shift key was held when the key was pressed.
This is not supported in 3D mode.
clientX The x coordinate of the mouse cursor relative
to the browser window.
clientY The y coordinate of the mouse cursor relative
to the browser window.
screenX The x coordinate of the mouse cursor relative
to the screen.
This is not supported in 3D mode.
screenY The y coordinate of the mouse cursor relative
to the screen.
This is not supported in 3D mode.
mapX The x coordinate of the map relative to the
screen.
This is not supported in 3D mode.
mapY The y coordinate of the map relative to the
screen.
This is not supported in 3D mode.
118
Property Description
zoomLevel The current zoom level of the map.
See Also
VEMap.onmouseover Event
VEMap.onmouseover Event
Occurs when the mouse cursor moves over a VEShape Class object.
Syntax
VEMap.AttachEvent("onmouseover", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
altKey A Boolean object representing whether the
ALT key was held when the key was pressed.
This is not supported in 3D mode.
ctrlKey A Boolean object representing whether the
CTRL key was held when the key was pressed.
This is not supported in 3D mode.
elementID The ID of the object associated with the event,
usually a VEShape Class object or the base
map.
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
shiftKey A Boolean object representing whether the
shift key was held when the key was pressed.
119
Property Description
This is not supported in 3D mode.
clientX The x coordinate of the mouse cursor relative
to the browser window.
clientY The y coordinate of the mouse cursor relative
to the browser window.
screenX The x coordinate of the mouse cursor relative
to the screen.
This is not supported in 3D mode.
screenY The y coordinate of the mouse cursor relative
to the screen.
This is not supported in 3D mode.
mapX The x coordinate of the map relative to the
screen.
This is not supported in 3D mode.
mapY The y coordinate of the map relative to the
screen.
This is not supported in 3D mode.
zoomLevel The current zoom level of the map.
See Also
VEMap.onmouseup Event
VEMap.onmouseup Event
Occurs when a mouse button (left, right, or middle) is released.
Syntax
VEMap.AttachEvent("onmouseup", function_name);
Return Value
A MapEvent object, which has the following properties:
120
Property Description
altKey A Boolean object representing whether the
ALT key was held when the key was pressed.
Note This is not supported in 3D mode.
ctrlKey A Boolean object representing whether the
CTRL key was held when the key was pressed.
Note This is not supported in 3D mode.
elementID The ID of the object associated with the event,
usually a VEShape Class object or the base
map.
eventName A String object representing the type of event
that occurred.
latLong The latlong coordinates of the clicked location.
This only works in 3D mode and is not
supported in the Core Map Control. For 2D, you
can convert mapX and mapY to a latlong using
the VEMap.PixelToLatLong Method method.
leftMouseButton A Boolean object representing whether the left
mouse button has been clicked.
rightMouseButton A Boolean object representing whether the
right mouse button has been clicked.
mapStyle The current map style as a String. Valid String
results are ga, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
shiftKey A Boolean object representing whether the
shift key was held when the key was pressed.
Note This is not supported in 3D mode.
clientX The x coordinate of the mouse cursor relative to
the browser window.
clientY The y coordinate of the mouse cursor relative to
the browser window.
screenX The x coordinate of the mouse cursor relative to
121
Property Description
the screen.
Note This is not supported in 3D mode.
screenY The y coordinate of the mouse cursor relative to
the screen.
Note This is not supported in 3D mode.
mapX The x coordinate of the map relative to the
screen.
Note This is not supported in 3D mode.
mapY The y coordinate of the map relative to the
screen.
Note This is not supported in 3D mode.
zoomLevel The current zoom level of the map.
See Also
VEMap.onmousedown Event
VEMap.onmousewheel Event
Occurs when the mouse wheel is moved.
Syntax
VEMap.AttachEvent("onmousewheel", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
altKey A Boolean object representing whether the
ALT key was held when the key was pressed.
ctrlKey A Boolean object representing whether the
CTRL key was held when the key was pressed.
elementID The ID of the object associated with the event,
usually a VEShape Class object or the base
map.
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String. Valid String
122
Property Description
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
shiftKey A Boolean object representing whether the
shift key was held when the key was pressed.
ClientX The x coordinate of the mouse cursor relative
to the browser window.
ClientY The y coordinate of the mouse cursor relative
to the browser window.
ScreenX The x coordinate of the mouse cursor relative
to the screen.
ScreenY The y coordinate of the mouse cursor relative
to the screen.
MapX The x coordinate of the map relative to the
screen.
MapY The y coordinate of the map relative to the
screen.
ZoomLevel The current zoom level of the map.
Remarks
This method is not supported in 3D mode, and the coordinate values returned in Firefox 1.5 and
2.0 are not correct.
Bing Maps Events
The events of the VEMap Class that are specific to maps are listed here.
Public Events
Name Description
VEMap.onchangemapstyle Event Occurs when the map style changes.
VEMap.onchangeview Event Occurs whenever the map view changes.
VEMap.oncredentialserror Event Occurs when the map control makes a
request to the Bing Maps servers and the
credentials that were set using the
123
Name Description
VEMap.SetCredentials Method are invalid.
VEMap.oncredentialsvalid Event Occurs when the map control makes a
request to the Bing Maps servers and the
credentials that were set using the
VEMap.SetCredentials Method are valid.
VEMap.onendpan Event Occurs when a pan of the map ends.
VEMap.onendzoom Event Occurs when the map zoom ends.
VEMap.onerror Event Occurs when there is a map control error.
VEMap.oninitmode Event Occurs after the map mode changes and the
map has reloaded.
VEMap.onmodenotavailable Event Occurs when the map mode fails to change to
3D mode.
VEMap.onobliquechange Event Occurs only when the bird's eye image scene ID
is changed. This event fires only if the map is
currently displaying a bird's eye image and that
image is changed.
VEMap.onobliqueenter Event Occurs when bird's eye images are available at
the center of the current map.
VEMap.onobliqueleave Event Occurs when bird's eye images are no longer
available at the center of the current map.
VEMap.onresize Event Occurs when the map is resized.
VEMap.onstartpan Event Occurs when a pan of the map begins. This
event is not supported in 3D mode.
VEMap.onstartzoom Event Occurs when the map zoom begins.
VEMap.ontokenerror Event Occurs when the map control makes a request to
the Bing Maps servers and the token that was
set using the VEMap.SetClientToken Method is
not valid.
VEMap.ontokenexpire Event Occurs when the map control makes a request to
the Bing Maps servers and the token that was
set using the VEMap.SetClientToken Method is
expired.
Remarks
See Also
124
Mouse Events
Keyboard Events
VEMap Event Object Properties
VEMap.onchangemapstyle Event
Occurs when the map style changes.
Syntax
VEMap.AttachEvent("onchangemapstyle", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
zoomLevel The current zoom level of the map.
See Also
Keyboard Events
Mouse Events
VEMap.onchangeview Event
Occurs whenever the map view changes.
Syntax
VEMap.AttachEvent("onchangeview", function_name);
Remarks
The onchangeview event fires whenever the map changes, including a change in the center
point, the zoom level, or the map style. For example, if a user pans the map by using the
compass control, the onchangeview event fires.
Return Value
A MapEvent object, which has the following properties:
125
Property Description
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
zoomLevel The current zoom level of the map.
See Also
VEMap.onchangemapstyle Event
VEMap.oncredentialserror Event
Occurs when the map control makes a request to the Bing Maps servers and the credentials that
were set using the VEMap.SetCredentials Method are invalid.
Syntax
VEMap.AttachEvent("oncredentialserror", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
zoomLevel The current zoom level of the map.
Remarks
126
The oncredentialserror and oncredentialsvalid events only occur when the map control makes
a server request to Bing Maps with invalid or valid credentials. The following map control methods
make server requests:
VEMap.Find Method
VEMap.FindLocations Method
VEMap.GetDirections Method
VEMap.GetImageryMetadata Method
VEMap.IsBirdseyeAvailable Method
VEMap.SetBirdseyeScene Method
See Also
Keyboard Events
Mouse Events
VEMap.oncredentialsvalid Event
Occurs when the map control makes a request to the Bing Maps servers and the credentials that
were set using the VEMap.SetCredentials Method are valid.
Syntax
VEMap.AttachEvent("oncredentialsvalid", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
zoomLevel The current zoom level of the map.
Remarks
The oncredentialserror and oncredentialsvalid events only occur when the map control makes
a server request to Bing Maps with invalid or valid credentials. The following map control methods
make server requests:
VEMap.Find Method
VEMap.FindLocations Method
127
VEMap.GetDirections Method
VEMap.GetImageryMetadata Method
VEMap.IsBirdseyeAvailable Method
VEMap.SetBirdseyeScene Method
See Also
Keyboard Events
Mouse Events
VEMap.onendpan Event
Occurs when a pan of the map ends.
Syntax
VEMap.AttachEvent("onendpan", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
eventName A String object representing
the type of event that occurred.
mapStyle The current map style as a
String. Valid String results are
a, r, h, and o.
sceneID If the map style is set to bird's
eye (oblique), the unique
identifier of the current bird's
eye scene.
sceneOrientation If the map style is set to bird's
eye (oblique), the orientation
of the current bird's eye scene.
zoomLevel The current zoom level of the
map.
See Also
VEMap.onstartpan Event
VEMap.onendzoom Event
Occurs when the map zoom ends.
Syntax
128
VEMap.AttachEvent("onendzoom", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
zoomLevel The current zoom level of the map.
See Also
VEMap.onstartzoom Event
VEMap.onerror Event
Occurs when there is a map control error.
Syntax
VEMap.AttachEvent("onerror", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
error A String object containing the error message, if
any.
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
129
Property Description
orientation of the current bird's eye scene.
zoomLevel The current zoom level of the map.
VEMap.oninitmode Event
Occurs after the map mode changes and the map has reloaded.
Syntax
VEMap.AttachEvent("oninitmode", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String. Valid string
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
zoomLevel The current zoom level of the map.
Remarks
You can use the VEMap.GetMapMode Method to determine which mode the map is in after the
mode has changed.
VEMap.onmodenotavailable Event
Occurs when the map mode fails to change to 3D mode.
Syntax
VEMap.AttachEvent("onmodenotavailable", function_name);
Return Value
A MapEvent object, which has the following properties:
130
Property Description
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
zoomLevel The current zoom level of the map.
Remarks
Use this event to determine whether the client computer has the ability to view maps in 3D mode.
This event occurs whenever the Bing Maps 3D control fails to load. Typically this happens
because the client software has not been installed or hardware acceleration is not enabled.
See Also
VEMap.oninitmode Event
VEMap.onobliquechange Event
Occurs only when the bird's eye image is changed. This event fires only if the map is currently
displaying a bird's eye image and that image is changed.
Syntax
VEMap.AttachEvent("onobliquechange", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
131
Property Description
zoomLevel The current zoom level of the map.
See Also
VEMap.onobliqueenter Event
VEMap.onobliqueleave Event
VEMap.onobliqueenter Event
Occurs when bird's eye images are available at the center of the current map.
Syntax
VEMap.AttachEvent("onobliqueenter", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
zoomLevel The current zoom level of the map.
See Also
VEMap.onobliquechange Event
VEMap.onobliqueleave Event
VEMap.onobliqueleave Event
Occurs when bird's eye images are no longer available at the center of the current map.
Syntax
VEMap.AttachEvent("onobliqueleave", function_name);
Return Value
A MapEvent object, which has the following properties:
132
Property Description
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
zoomLevel The current zoom level of the map.
Remarks
The onobliqueleave event only occurs after the VEMap.onobliqueenter Event has occurred, and
the map view has changed to a location that does not have bird's eye images.
See Also
VEMap.onobliqueenter Event
VEMap.onobliqueleave Event
VEMap.onresize Event
Occurs when the map is resized.
Syntax
VEMap.AttachEvent("onresize", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
zoomLevel The current zoom level of the map.
133
VEMap.onstartpan Event
Occurs when a pan of the map begins.
Syntax
VEMap.AttachEvent("onstartpan", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
zoomLevel The current zoom level of the map.
Remarks
This event only fires when the map is in 2D mode.
See Also
VEMap.onendpan Event
VEMap.onstartzoom Event
Occurs when the map zoom begins.
Syntax
VEMap.AttachEvent("onstartzoom", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String. Valid String
134
Property Description
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
zoomLevel The current zoom level of the map.
See Also
VEMap.onendzoom Event
VEMap.ontokenerror Event
Occurs when the map control makes a request to the Bing Maps servers and the token that was
set using the VEMap.SetClientToken Method is not valid.
Syntax
VEMap.AttachEvent("ontokenerror", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
zoomLevel The current zoom level of the map.
Remarks
The ontokenerror and ontokenexpire events only occur when the map control makes a server
request to Bing Maps with an invalid or expired token. The following map control methods make
server requests:
VEMap.Find Method
VEMap.FindLocations Method
135
VEMap.GetDirections Method
VEMap.GetImageryMetadata Method
VEMap.IsBirdseyeAvailable Method
VEMap.SetBirdseyeScene Method
See Also
VEMap.SetClientToken Method
VEMap.ontokenexpire Event
VEMap.ontokenexpire Event
Occurs when the map control makes a request to the Bing Maps servers and the token that was
set using the VEMap.SetClientToken Method is expired.
Syntax
VEMap.AttachEvent("ontokenexpire", function_name);
Return Value
A MapEvent object, which has the following properties:
Property Description
eventName A String object representing the type of event
that occurred.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
sceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
sceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
zoomLevel The current zoom level of the map.
Remarks
The ontokenerror and ontokenexpire events only occur when the map control makes a server
request to Bing Maps with an invalid or expired token. The following map control methods make
server requests:
VEMap.Find Method
VEMap.FindLocations Method
VEMap.GetDirections Method
VEMap.GetImageryMetadata Method
VEMap.IsBirdseyeAvailable Method
VEMap.SetBirdseyeScene Method
136
See Also
VEMap.SetClientToken Method
VEMap.ontokenerror Event
VEMap Event Object Properties
The MapEvent object properties that are available from the callback method are listed below.
Event Object Properties
Property Description
error A String object containing the error message, if
any.
zoomLevel The current map zoom level.
mapStyle The current map style as a String. Valid String
results are a, r, h, and o.
birdseyeSceneID If the map style is set to bird's eye (oblique), the
unique identifier of the current bird's eye scene.
birdseyeSceneOrientation If the map style is set to bird's eye (oblique), the
orientation of the current bird's eye scene.
leftMouseButton A boolean representing whether the left mouse
button has been clicked.
rightMouseButton A boolean representing whether the right mouse
button has been clicked.
middleMouseButton A boolean representing whether the middle
mouse button (or mouse wheel) has been
clicked.
mouseWheelChange The number of units that the mouse wheel has
changed.
This is not supported in 3D mode, and
the value returned in Firefox 1.5 and 2.0
is incorrect.
clientX The x coordinate of the mouse cursor relative to
the browser window.
clientY The y coordinate of the mouse cursor relative to
the browser window.
screenX The x coordinate of the mouse cursor relative to
137
Property Description
the screen.
This is not supported in 3D mode.
screenY The y coordinate of the mouse cursor relative to
the screen.
This is not supported in 3D mode.
mapX The x coordinate of the map relative to the
screen.
This is not supported in 3D mode.
mapY The y coordinate of the map relative to the
screen.
This is not supported in 3D mode.
latLong The latlong coordinates of the clicked location.
This only works in 3D mode. For 2D, you can
convert mapX and mapY to a latlong using the
VEMap.PixelToLatLong Method method.
keyCode The key code of the key that has been pressed.
This is not supported in 3D mode.
altKey A boolean representing whether the ALT key was
held when the key was pressed.
This is not supported in 3D mode.
ctrlKey A boolean representing whether the CTRL key
was held when the key was pressed.
This is not supported in 3D mode.
shiftKey A boolean representing whether the shift key was
held when the key was pressed.
138
Property Description
This is not supported in 3D mode.
eventName A string representing the type of event that
occurred.
elementID The ID of the object associated with the event,
usually a VEShape Class object or the base
map.
Remarks
The ID string for shapes, as provided by an Event object, (see VEMap Events) may have some
extensions on it beyond the root ID string. Use the VEShape.GetID Method to return the correct
shape reference, as shown in the following example.
function ShapeHandler(e)
{
if (e.elementID)
{
// e.elementID is the root ID, plus extensions.
alert("ID of shape on mouseover is " + e.elementID);
// Use VEMap.GetShapeByID, then VEShape.GetID
// to return the root ID.
var id = map.GetShapeByID(e.elementID).GetID();
alert("ID of shape on mouseover is " + id);
return true;
}
}
See Also
Keyboard Events
Mouse Events
Bing Maps Events
VEMap Methods
The methods of the VEMap class are listed here. For a complete list of VEMap class members,
see the VEMap Class topic.
139
Public Methods
Name Description
VEMap.AddControl Method Adds a custom control to the map.
VEMap.AddCustomLayer Method Adds a custom layer to the map.
VEMap.AddShape Method Adds an existing VEShape Class object, as
specified by the shape parameter, to the base
layer.
VEMap.AddShapeLayer Method Adds the specified shape layer to the map.
VEMap.AddTileLayer Method Adds a tile layer to the map, and if the
visibleOnLoad parameter is true, it also shows
it on the map.
VEMap.AttachEvent Method Attaches a Map Control event to a specified
function.
VEMap.Clear Method Removes all shapes, shape layers, and search
results on the map. Also removes the route
from the map, if one is displayed.
VEMap.ClearInfoBoxStyles Method Clears out all of the default Bing Maps info box
CSS styles.
VEMap.ClearTraffic Method Clears the traffic map.
VEMap.DeleteAllShapeLayers Method Deletes all shape layers, along with any shapes
within the layers.
VEMap.DeleteAllShapes Method Deletes all shapes in all layers, leaving empty
layers behind.
VEMap.DeleteControl Method Removes the specified control from the map.
VEMap.DeleteRoute Method Clears the current route, VERoute Class object,
from the map.
VEMap.DeleteShape Method Deletes a VEShape Class object from any
layer, including the base map layer.
VEMap.DeleteShapeLayer Method Deletes the specified shape layer from the
map.
VEMap.DeleteTileLayer Method Deletes a tile layer from view.
VEMap.DetachEvent Method Detaches the specified map control event so
that it no longer calls the specified function.
140
Name Description
VEMap.Dispose Method Deletes the VEMap object and releases any
associated resources
VEMap.EnableShapeDisplayThreshold Method Specifies whether shapes are drawn below a
threshold zoom level.
VEMap.EndContinuousPan Method Stops the continuous map panning initiated by
a call to the VEMap.StartContinuousPan
Method.
VEMap.Find Method Returns an array of found results.
VEMap.FindLocations Method Performs a search for locations that match a
VELatLong Class input.
VEMap.Geocode Method Finds a geographic location based on a
specified address or place name string as well
as other geocoding options.
VEMap.GetAltitude Method In 3D mode, returns a double that represents
the altitude (in meters) above the geoid.
VEMap.GetBirdseyeScene Method If the map view is already set to bird's eye,
returns the current VEBirdseyeScene Class
object.
VEMap.GetCenter Method Returns a VELatLong Class object that
represents the location of the center of the
current map view.
VEMap.GetDirections Method Draws a multi-point route on the map and
sends details about the route to a callback
function.
VEMap.GetHeading Method In 3D mode, returns an integer that represents
the compass heading of the current map view.
VEMap.GetImageryMetadata Method Returns information about the requested
imagery, including imagery date stamps and
vendor attribution.
VEMap.GetLeft Method Returns the pixel value of the left edge of the
map control.
VEMap.GetMapMode Method Returns the current map mode.
VEMap.GetMapStyle Method Returns the current map style.
VEMap.GetMapView Method Returns the current map view object as a
141
Name Description
VELatLongRectangle Class object.
VEMap.GetPitch Method In 3D mode, returns an integer that represents
the pitch of the current map view.
VEMap.GetRoute Method Deprecated. Draws a route on the map and
sends details about the route to a callback
function.
VEMap.GetShapeByID Method Gets the reference to a VEShape Class object
based on its internal identifier.
VEMap.GetShapeLayerByIndex Method Gets the reference to a VEShapeLayer Class
object based on its index.
VEMap.GetShapeLayerCount Method Gets the total number of shape layers on the
map.
VEMap.GetTileLayerCount Method Gets the number of tile layers.
VEMap.GetTileLayerByID Method Gets a tile layer based upon its identifier.
VEMap.GetTileLayerByIndex Method Gets a tile layer based upon an index value.
VEMap.GetTop Method Returns the pixel value of the top edge of the
map control.
VEMap.GetVersion Method Returns the current version of the map control.
VEMap.GetZoomLevel Method Returns the current zoom level of the map.
VEMap.Hide3DNavigationControl Method In 3D mode, hides the default user interface for
controlling the map in 3D mode. By default, this
control is shown.
VEMap.HideAllShapeLayers Method Hides all of the shape layers on the map.
VEMap.HideBaseTileLayer Method Hides the base tile layer of the map.
VEMap.HideControl Method Hides the specified control from view.
VEMap.HideDashboard Method Hides the default user interface for controlling
the map (the compass and the zoom control).
VEMap.HideFindControl Method Deprecated. Removes the Find control from the
map.
VEMap.HideInfoBox Method Hides a shape's custom or default info box.
VEMap.HideMiniMap Method Hides the mini map from view.
VEMap.HideScalebar Method Hides the scale bar from the map.
142
Name Description
VEMap.HideTileLayer Method Hides a tile layer from view.
VEMap.HideTrafficLegend Method Hides the traffic legend.
VEMap.Import3DModel Method Imports data from a Wavefront OBJ file and
displays it as a 3D model on the map.
VEMap.ImportShapeLayerData Method Imports data from a GeoRSS feed, Bing Maps
(http://maps.live.com) collection, or KML URL.
VEMap.IncludePointInView Method Changes the map view so that it includes both
the specified VELatLong Class point and the
center point of the current map.
VEMap.IsBirdseyeAvailable Method Determines whether the bird's eye map style is
available in the current map view.
VEMap.LatLongToPixel Method Converts an array of VELatLong Class objects
(latitude/longitude pair) to an array of VEPixel
Class objects.
VEMap.LoadTraffic Method Loads the traffic map.
VEMap.LoadMap Method Loads the specified map. All parameters are
optional.
VEMap.Pan Method When in 2D mode, moves the map the
specified amount.
VEMap.PanToLatLong Method Pans the map to a specific latitude and
longitude.
VEMap.PixelToLatLong Method Converts a pixel (a point on the map) to a
VELatLong Class object (latitude/longitude
pair).
VEMap.RemoveCustomLayer Method Removes a custom layer from the map.
VEMap.Resize Method Resizes the map based on the specified width
and height.
VEMap.Search Method Performs a search based on a given query and
options.
VEMap.SetAltitude Method In 3D mode, sets the altitude, in meters, above
the WGS 84 ellipsoid in the map view.
VEMap.SetBirdseyeOrientation Method Changes the orientation of the existing bird's
eye image (VEBirdseyeScene Class object) to
143
Name Description
the specified orientation.
VEMap.SetBirdseyeScene Method Overloaded. Displays the specified bird's eye
image.
VEMap.SetCenter Method Centers the map to a specific latitude and
longitude.
VEMap.SetCenterAndZoom Method Centers the map to a specific latitude and
longitude and sets the zoom level.
VEMap.SetClientToken Method Sets a Bing Maps token for the VEMap object.
VEMap.SetCredentials Method Sets the credentials to use to authenticate map
service requests.
VEMap.SetDashboardSize Method Sets the map dashboard size and type.
VEMap.SetDefaultInfoBoxStyles Method Sets the info box CSS styles back to their
original classes.
VEMap.SetFailedShapeRequest Method Specifies what the map control does when a
request to the server to get the accurate
position of a shape when the map style is
changed to birdseye fails.
VEMap.SetHeading Method In 3D mode, sets the compass heading of the
current map view.
VEMap.SetMapMode Method Sets the mode of the map.
VEMap.SetMapStyle Method Sets the style of the map.
VEMap.SetMapView Method Sets the map view to include all of the points,
lines, or polygons specified in the provided
array, or to the view defined by a
VEMapViewSpecification Class object.
VEMap.SetMouseWheelZoomToCenter
Method
Specifies whether to zoom to the center of the
screen or to the cursor position on the screen.
VEMap.SetPitch Method In 3D mode, sets the pitch of the current map
view.
VEMap.SetPrintOptions Method Sets the print options for the current map.
VEMap.SetScaleBarDistanceUnit Method Sets the distance unit (kilometers or miles) for
the map scale.
VEMap.SetShapesAccuracy Method Specifies the accuracy in converting shapes
144
Name Description
when the map style is changed to birdseye.
VEMap.SetShapesAccuracyRequestLimit
Method
Specifies how to draw the polygons or the
polylines whose points exceed the maximum
limit or when a request to the server fails when
the map style is changed to birdseye.
VEMap.SetTileBuffer Method Sets the number of "rings" of map tiles that
should be loaded outside of the visible
mapview area.
VEMap.SetTrafficLegendText Method Specifies the text shown with the traffic legend,
if visible.
VEMap.SetZoomLevel Method Sets the view of the map to the specified zoom
level.
VEMap.Show3DBirdseye Method Controls whether or not to show the Birdseye
and BirdseyeHybrid map styles when the map
mode is set to VEMapMode.Mode3D.
VEMap.Show3DNavigationControl Method In 3D mode, shows the default user interface
for controlling the map in 3D mode. By default,
this control is shown.
VEMap.ShowAllShapeLayers Method Shows all shape layers on the map.
VEMap.ShowBaseTileLayer Method Shows the base tile layer of the map.
VEMap.ShowControl Method Makes the specified control visible. This
method only affects control elements that have
been hidden from view using the
VEMap.HideControl Method.
VEMap.ShowDashboard Method Shows the default user interface for controlling
the map (the compass-and-zoom control). By
default, this control is shown.
VEMap.ShowDisambiguationDialog Method Specifies whether the default disambiguation
dialog is displayed when multiple results are
returned from a location query.
VEMap.ShowFindControl Method Deprecated. Shows the Find control, which
enables users to enter search queries.
VEMap.ShowInfoBox Method Shows a shape's custom or default info box.
VEMap.ShowMessage Method Displays the specified message in a dialog box
on the map.
145
Name Description
VEMap.ShowMiniMap Method Displays the mini map at the specified offset
from the top left corner of the screen.
VEMap.ShowScalebar Method Displays the scale bar on the map.
VEMap.ShowTileLayer Method Shows a tile layer from view.
VEMap.ShowTrafficLegend Method Displays the traffic legend.
VEMap.StartContinuousPan Method Moves the map in the specified direction until
the VEMap.EndContinuousPan Method is
called.
VEMap.ZoomIn Method Increases the map zoom level by 1.
VEMap.ZoomOut Method Decreases the map zoom level by 1.
VEMap.AddControl Method
Adds a custom control to the map.
Syntax
VEMap.AddControl(element, zIndex);
Parameters
Parameter Description
element An HTML element that contains the control to
be added
zIndex The z-order for the control. Optional.
Caution The element parameter is an HTML element that can have JavaScript embedded in it.
Verify the input value before executing it on your web page.
Remarks
You can use the document.CreateElement method of the Document Object Model (DOM) to
create a new HTML element. Add the functionality you want, and then call the AddControl
method. You can also use the DOM to remove the control once it has been added.
Because of the way Internet Explorer displays embedded controls on a Web page, when working
with maps in 3D mode, custom controls are hidden behind the map. If you want to show a custom
control on top of the 3D map, follow these steps:
1. Create an IFRAME element that is the same size and at the same location as the custom
control.
2. Set the frameborder property of the IFRAME to 0 and the scrolling property to "no".
146
3. In the style property for the IFRAME, set the z-index to 1 and the position settings to match
those of your control.
4. In the style property for your custom control, set the z-index to a number larger than 1.
5. Call the following lines of code, where shim is the IFRAME element and el is your custom
control:
el.shimElement = shim;
el.parentNode.insertBefore(shim, el);
Example
VirtualEarthSDK#3
See Also
VEMap.DeleteControl Method
VEMap.HideControl Method
VEMap.ShowControl Method
VEMap.AddCustomLayer Method
Adds a custom layer to the map.
Syntax
VEMap.AddCustomLayer(object);
Parameters
Parameter Description
object The object to add as a layer to the map DIV
container.
Example
VirtualEarthSDK#61
See Also
VEMap.RemoveCustomLayer Method
VEMap.AddTileLayer Method
VEMap.AddShape Method
Adds a VEShape Class object or array of VEShape pushpin objects to the base layer.
Syntax
VEMap.AddShape(shape);
Parameters
147
Parameter Description
Shape The VEShape object or array of VEShape
pushpin objects to be added. Required.
Remarks
The shape parameter can be a single pushpin, polyline, or polygon, or an array of pushpins. If the
map is in 3D mode, the shapes are added one-by-one. If the map has been redrawn, shapes are
added one-by-one. If a shape with the same internal identifier already exists in the base layer,
this method throws an exception.
Examples
VirtualEarthSDK#7
See Also
VEMap.DeleteShape Method
VEMap.AddShapeLayer Method
Adds the specified VEShapeLayer Class object to the map.
Syntax
VEMap.AddShapeLayer(Layer);
Parameters
Parameter Description
Layer The VEShapeLayer Class object to add.
Remarks
If the layer reference already exists on the map, an exception is thrown, and no new layer is
created.
Examples
VirtualEarthSDK#8
See Also
VEMap.AddShape Method
VEMap.DeleteShapeLayer Method
VEMap.AddTileLayer Method
Adds a tile layer to the map, and if the visibleOnLoad parameter is true, it also shows it on the
map.
Syntax
148
VEMap.AddTileLayer(layerSource, visibleOnLoad);
Parameters
Parameter Description
layerSource The VETileSourceSpecification Class object
representing the source of the tile layer.
Required.
visibleOnLoad If true, the layer is immediately shown when
added to the map. Optional.
Example
VirtualEarthSDK#9
See Also
VEMap.DeleteTileLayer Method
VEMap.HideTileLayer Method
VEMap.AttachEvent Method
Attaches a Map Control event to a specified function.
Syntax
VEMap.AttachEvent(event, function);
Parameters
Parameter Description
event The name of the Map Control event that
generates the call.
function The function to run when the event fires. It can
be either the name of a function or the function
itself.
Return Value
Remarks
For a list of Map Control events, see VEMap Events.
When the event fires, you can specify either the name of the function to call or the function itself.
The following example shows each option.
For the keyboard and mouse events, the custom function is executed before the default action is
executed. If the custom function returns false, the default action is executed. If the custom
function returns true, the default action is not executed. For example, if you have attached the
149
onLeftMouseDoubleClick event, then your custom function is executed first. If it returns false,
the default map behavior, which is to zoom-in, is executed. If it returns true, the zoom-in behavior
is disabled.
You can also perform actions based on the type of object associated with the event. The
VEShape Class object is normally the object associated with an event.
If you specify the entire function to attach, as opposed to just the function name, it will be
impossible to detach it later.
See the VEMap Events topic for more information.
Examples
VirtualEarthSDK#10
See Also
VEMap.DetachEvent Method
VEMap.Clear Method
Removes all shapes, shape layers, and search results on the map. Also removes the route from
the map, if one is displayed.
Syntax
VEMap.Clear();
Remarks
The Clear method does not remove custom tile layers from the map.
Example
VirtualEarthSDK#7
VEMap.ClearInfoBoxStyles Method
Clears out all of the default Bing Maps info box CSS styles.
Syntax
VEMap.ClearInfoBoxStyles();
Remarks
This method internally clears out the default info box styles used to give the Bing Maps default
info box its look and feel. You are left with a few basic style components to get you started. You
can then reference your own CSS classes from within your custom HTML content for your ERO
to style your info box as you wish.
The default style sheets that remain after this method is called are listed here:
/* Styles that apply to the info box's containing element whether it has no beak, a
rightBeak, or a leftBeak */
150
.customInfoBox-noBeak,
.customInfoBox-with-rightBeak,
.customInfoBox-with-leftBeak
{
position: absolute;
}
/* Offset the body for the drop-shadow and set the body background and border just for
starters (developers can change this easily)*/
.customInfoBox-body
{
position: relative;
top: -5px;
left: -5px;
padding: 8px;
border: 1px solid #000;
background-color: #fff;
}
/* Apply a nice default drop-shadow after the default Bing Maps info box styles are
cleared */
.customInfoBox-shadow
{
position: relative;
background-color: #ccc;
}
/* Sections of the info box that a developer could style if desired, but have no style
when the default Bing Maps info box styles are cleared */
.customInfoBox-previewArea,
151
.customInfoBox-actionsBackground
{
}
/* Sections of the info box that should not be visible when the default Bing Maps info
box styles are cleared */
.customInfoBox-actions,
.customInfoBox-paddingHack
{
display: none;
}
.customInfoBox-beak,
.customInfoBox-progressAnimation
{
visibility: hidden;
}
Examples
VirtualEarthSDK#12
See Also
VEMap.SetDefaultInfoBoxStyles Method
VEMap.ClearTraffic Method
Clears the traffic map.
Syntax
VEMap.ClearTraffic()
Example
VirtualEarthSDK#13
See Also
VEMap.HideTrafficLegend Method
VEMap.LoadTraffic Method
152
VEMap.DeleteAllShapeLayers Method
Deletes all VEShapeLayer Class objects on the map as well as any VEShape Class objects
within the layers.
Syntax
VEMap.DeleteAllShapeLayers();
Examples
VirtualEarthSDK#8
See Also
VEMap.AddShapeLayer Method
VEMap.DeleteAllShapes Method
Deletes all of the VEShape Class objects from all layers.
Syntax
VEMap.DeleteAllShapes();
Examples
VirtualEarthSDK#8
See Also
VEMap.DeleteAllShapeLayers Method
VEMap.AddShapeLayer Method
VEMap.DeleteControl Method
Removes the specified control from the map.
Syntax
VEMap.DeleteControl(element);
Parameters
Parameter Description
element An HTML element that contains the control to
be deleted
Examples
VirtualEarthSDK#3
See Also
VEMap.AddControl Method
153
VEMap.HideControl Method
VEMap.DeleteRoute Method
Clears the current route (VERoute Class object) from the map.
Syntax
VEMap.DeleteRoute();
Example
VirtualEarthSDK#11
VEMap.DeleteShape Method
Deletes a VEShape Class object from any layer, including the base map layer.
Syntax
VEMap.DeleteShape(shape);
Parameters
Parameter Description
shape The VEShape Class object to be deleted.
Required.
Remarks
The VEShape object can be a pushpin, polyline, or polygon.
Example
VirtualEarthSDK#7
See Also
VEMap.DeleteAllShapes Method
VEMap.AddShape Method
VEMap.DeleteShapeLayer Method
Deletes the specified VEShapeLayer Class object from the map.
Syntax
VEMap.DeleteShapeLayer(layer);
Parameters
154
Parameter Description
layer A VEShapeLayer Class object to delete.
Required.
Remarks
Examples
VirtualEarthSDK#8
See Also
VEMap.AddShapeLayer Method
VEMap.DeleteAllShapeLayers Method
VEMap.DeleteTileLayer Method
Completely removes a tile layer from the map.
Syntax
VEMap.DeleteTileLayer(layerID);
Parameters
Parameter Description
layerID The ID of the layer to be deleted.
Example
VirtualEarthSDK#9
See Also
VEMap.HideTileLayer Method
VEMap.ShowTileLayer Method
VEMap.DetachEvent Method
Detaches the specified map control event so that it no longer calls the specified function.
Syntax
VEMap.DetachEvent(event, function);
Parameters
Parameter Description
event The name of the map control event that
generates the call.
155
Parameter Description
function The function that was specified to run when the
event fired.
Return Value
Remarks
For a list of map control events, see VEMap Events.
Because a single event can be attached to multiple functions, you must specify the event and
function names when detaching.
Example
VirtualEarthSDK#10
See Also
VEMap.AttachEvent Method
VEMap.Dispose Method
Deletes the VEMap object and releases any associated resources.
Syntax
VEMap.Dispose();
Example
VirtualEarthSDK#29
See Also
VEMap Constructor
VEMap.EnableShapeDisplayThreshold Method
Specifies whether shapes are drawn below a threshold zoom level.
Syntax
VEMap.EnableShapeDisplayThreshold(enable);
Parameters
Parameter Description
enable A Boolean value specifying whether to draw
shapes below a threshold zoom level. By
default shapes are not drawn below a threshold
zoom level.
156
Remarks
By default, the map control performs the following polyline and polygon shape performance
optimizations at low zoom levels.
If a polyline or polygon is very small, it is not drawn.
If the latitude and longitude of two vertices of a polyline or polygon are too near each other,
they are not drawn.
If this method is called with enable set to false, these optimizations are disabled and the map
control does the following.
The map control attempts to draw the polyline or polygon, regardless of its size.
The map control attempts to draw all of the vertices of the polyline or polygon, regardless of
how close they are to another vertex.
Example
VirtualEarthSDK#48
See Also
VEShape.SetMinZoomLevel Method
VEMap.EndContinuousPan Method
Stops the continuous map panning initiated by a call to the VEMap.StartContinuousPan Method.
Syntax
VEMap.EndContinuousPan();
Example
VirtualEarthSDK#14
VEMap.Find Method
Performs a what (business) search or a where (location) search. At least one of these two
parameters is required.
Syntax
VEMap.Find(what, where, findType, shapeLayer, startIndex, numberOfResults, showResults,
createResults, useDefaultDisambiguation, setBestMapView, callback);
Parameters
Parameter Description
what The business name, category, or other item for
which the search is conducted. This parameter
must be supplied for a pushpin to be included
in the results.
157
Parameter Description
where The address or place name of the area for
which the search is conducted. This parameter
is overloaded; see the Remarks section for
more information.
findType A VEFindType Enumeration value that
specifies the type of search performed. The
only currently supported value is
VEFindType.Businesses.
shapeLayer A reference to the VEShapeLayer Class object
that contain the pins that result from this search
if a what parameter is specified. Optional. If the
shape layer is not specified, the pins are added
to the base map layer. If the reference is not a
valid VEShapeLayer reference, an exception is
thrown.
startIndex The beginning index of the results returned.
Optional. Default is 0.
numberOfResults The number of results to be returned, starting
at startIndex. The default is 10, the minimum is
1, and the maximum is 20.
showResults A Boolean value that specifies whether the
resulting pushpins are visible. Optional. Default
is true.
createResults A Boolean value that specifies whether
pushpins are created when a what parameter is
supplied. Optional. If true, pushpins are
created. If false, the arguments sent to the
function specified by the callback parameter
are set as follows:
The array of VEFindResult Class objects is
still present, but no pushpin layer is
created.
Each VEFindResult object's corresponding
Shape property is null.
useDefaultDisambiguation A Boolean value that specifies whether the
map control displays a disambiguation box
when multiple location matches are possible. If
true, the map control displays a disambiguation
158
Parameter Description
box. Optional. The default is true. To ensure no
messages appear when
useDefaultDisambiguation is false, set the
VEMap.ShowMessageBox Property to false.
setBestMapView A Boolean value that specifies whether the
map control moves the view to the first location
match. If true, the map control moves the view.
Optional. Default is true.
callback The name of the function that the server calls
with the search results.
If this parameter is not null and
useDefaultDisambiguation is true, this function
is not called until the user has made a
disambiguation choice. Optional.
Return Value
This method does not return a value. The function defined by the callback parameter receives the
following arguments, in the order shown, from the server:
A VEShapeLayer Class object. If shapeLayer was supplied, it should be the same object.
An array of VEFindResult Class objects.
An array of VEPlace Class objects.
A Boolean value indicating whether there are more results after the current set.
A String containing a possible error message.
Remarks
The callback function for this method is not re-entrant. If an application calls Find before a
previous Find call has returned the search results to the callback function, the first set of
arguments are destroyed and are no longer available.
A Find call must include a non-null what parameter or non-null where parameter (or both).
If the Find call contains a non-null what parameter:
The map control returns a VEShapeLayer Class object as the first argument to the callback
function. If the search is unsuccessful, this argument is null. Otherwise, the pushpins that are
returned as the second argument are all on this layer.
The map control returns an array of VEFindResult Class objects as the second argument to
the callback function. If the search is unsuccessful, this argument is null. Otherwise, each
VEFindResult object contains a reference to a corresponding VEShape Class pushpin.
If a what parameter is specified, but the where parameter is null, the current map view is
used, even if the setBestMapView parameter is true.
If the numberOfResults parameter is set, it will limit the number of locations returned.
159
If the Find call provides a non-null where parameter:
The where parameter is overloaded. It can be either a String, representing a place such as
"London" or "123 Main Street," a VEPlace Class object, or a VELatLongRectangle Class
object. If it is a VEPlace object or a VELatLongRectangle object, then the what parameter
must be non-null.
If the where parameter is a String, it is used to geocode a place name or an address.
The map control returns an array of VEPlace objects as the third argument to the callback
function. If the search is unsuccessful, this argument is null. Otherwise, these objects
represent the possible location matches.
If more than one location matches the where search string, and the
useDefaultDisambiguation parameter is true, the map control displays a disambiguation
dialog box. The user must select a location from this dialog before the map control completes
the search and calls the callback function.
If a where parameter is specified, the what parameter is null, and at least one of the VEPlace
objects returned as the third argument to the callback function has a MatchConfidence
property value of VEMatchConfidence.High, the map control does not display a
disambiguation dialog box, even if the useDefaultDisambiguation parameter is true, but
displays the first VEPlace object in the array. However, since all of the possible places are
returned in the array, an application could build its own disambiguation dialog and query the
user.
Localized search results can be returned by adding a mkt attribute to the map control reference.
Information about returning localized results including supported cultures can be found in the
Returning Localized Results topic.
Example
VirtualEarthSDK#15
See Also
VEPlace Class
VEFindResult Class
VEShapeLayer Class
Returning Localized Results
VEMap.FindLocations Method
Performs a search for locations that match a VELatLong input.
Syntax
VEMap.FindLocations(veLatLong, callback);
Parameters
Parameter Description
veLatLong A VELatLong Class object that specifies what
160
Parameter Description
map location to match.
callback The name of the function that the server calls
when it returns search results.
Return Value
This method does not return a value. The function defined by the callback parameter receives
one argument from the server:
An array of VEPlace Class objects. If the search is unsuccessful, this argument is null.
Otherwise, these objects represent the possible location matches.
Remarks
The VEMap.FindLocations method is only supported in the United States.
Example
VirtualEarthSDK#52
See Also
VELatLong Class
VEMap.Find Method
VEMap.Geocode Method
Finds a geographic location based on a specified address or place name string as well as other
geocoding options.
Syntax
VEMap.Geocode(query, callback, options);
Parameters
Parameter Description
query The query string to match to a location on the
map.
callback The name of the function that the server calls
with the geocode results. If this parameter is
not null and useDefaultDisambiguation is true,
this function is not called until the user has
made a disambiguation choice.
options A VEGeocodeOptions Class object specifying
additional options.
Return Value
161
This method does not return a value. The function defined by the callback parameter receives the
following arguments, in the order shown, from the server:
A VEShapeLayer Class object.
An array of VEFindResult Class objects. For a Geocode call, this argument will always be
null.
An array of VEPlace Class objects.
A Boolean value indicating whether there are more results after the current set.
A String containing a possible error message.
Remarks
The Geocode method only returns results with high match confidence to the callback function.
Example
VirtualEarthSDK#66
See Also
VEGeocodeOptions Class
VEMap.Search Method
VEMap.GetAltitude Method
In 3D mode, returns a double that represents the altitude (in meters) above the geoid.
Syntax
VEMap.GetAltitude();
Return Value
A double that represents the altitude (in meters) above the geoid.
Remarks
Altitude is represented as meters above the geoid, not above the ground level.
The GetAltitude method, VEMap.GetHeading Method, and VEMap.GetPitch Method return
values only when the map mode (VEMapMode Enumeration) is set to Mode3D and the current
map view is completely loaded. To be sure that the map view is completely loaded, you can use
the VEMap.onendpan Event.
Example
VirtualEarthSDK#16
VEMap.GetBirdseyeScene Method
If the map view is already set to bird's eye, returns the current VEBirdseyeScene Class object.
Syntax
VEMap.GetBirdseyeScene();
Return Value
162
Returns null if the map mode is set to 3D (VEMap.GetMapMode Method returns 2). Otherwise
returns a VEBirdseyeScene Class object that represents the current bird's eye image.
Example
VirtualEarthSDK#17
VEMap.GetCenter Method
Returns a VELatLong Class object that represents the location of the center of the current map
view.
Syntax
VEMap.GetCenter();
Return Value
A VELatLong Class object.
Remarks
This method returns null when the map style is set to VEMapStyle.Birdseye or
VEMapStyle.BirdseyeHybrid.
Example
VirtualEarthSDK#6
See Also
VEMap.SetCenter Method
VEMapStyle Enumeration
VEMap.GetDirections Method
Draws a multi-point route on the map and sends details about the route to a callback function.
Syntax
VEMap.GetDirections(locations, options);
Parameters
Parameter Description
locations An array of objects specifying the points
through which the route must pass. The points
can be either VELatLong Class objects or
String objects. A maximum of 25 locations can
be specified.
options A VERouteOptions Class object specifying the
routing options.
163
Return Value
The callback function specified in the VERouteOptions.RouteCallback Property of the
VERouteOptions object passed to the options parameter receives a VERoute Class object
containing route details, including the step-by-step route directions.
If the locations parameter length is greater than 25, an empty VERoute object will be returned.
An empty VERoute object has no itinerary and the VERoute.Distance Property and
VERoute.Time Property are 0.
If one or more of the points specified in the locations parameter is not found, then null will be
returned to the callback function.
If the VERouteOptions.RouteMode Property is set to VERouteMode.Walking, an empty
VERoute object will be returned if the total route distance between the start and end points is
greater than 16 kilometers. This total route distance includes portions of the route where you
may not be walking. For example, ferry segments of the route are included in the total route
distance.
Remarks
The route can contain localized directions by adding a mkt attribute to the map control reference,
and in some cases setting the VERouteOptions.UseMWS Property to true. Information about
returning localized results including supported cultures can be found in the Returning Localized
Results topic.
If content should be in kilometers instead of miles, set the VERouteOptions.DistanceUnit Property
to VERouteDistanceUnit.Kilometer.
If the VERouteOptions.RouteMode Property is set to VERouteMode.Walking, a walking speed of
4.8 km/hr is used to calculate the route time.
Example
VirtualEarthSDK#11
See Also
VERouteOptions Class
VERoute Class
Returning Localized Results
VEMap.GetHeading Method
In 3D mode, returns a double that represents the compass heading of the current map view.
Syntax
VEMap.GetHeading();
Return Value
A double that represents the compass heading, where 0 is true north and 180 is true south.
Remarks
164
The VEMap.GetAltitude Method, the GetHeading method and the VEMap.GetPitch Method
return values only when the map mode (VEMapMode Enumeration) is set to Mode3D and the
current map view is completely loaded. To be sure that the map view is completely loaded, you
can use the VEMap.onendpan Event.
Example
VirtualEarthSDK#18
VEMap.GetImageryMetadata Method
Returns information about the requested imagery, including imagery date stamps. This method
requires that a valid token has been set using the VEMap.SetClientToken Method.
Syntax
VEMap.GetImageryMetadata(callback, options);
Parameters
Parameter Description
callback The name of the function to call when results
are returned. The function must accept a
VEImageryMetadata Class object. Required.
options A VEImageryMetadataOptions Class object
specifying the imagery for which information is
returned. Optional.
Return Value
Returns a VEImageryMetadata Class to the callback function.
Remarks
If the options parameter is not specified, then the GetImageryMetadata method returns
information about the current map view.
The GetImageryMetadata method is supported for VEMapStyle.Aerial and
VEMapStyle.Hybrid.
In order to retrieve imagery metadata, use the VEMap.SetClientToken Method to set a valid token
before calling the GetImageryMetadata method.
Example
VirtualEarthSDK#56
See Also
VEImageryMetadata Class
VEImageryMetadataOptions Class
165
VEMap.GetLeft Method
Returns the pixel value of the left edge of the map control.
Syntax
VEMap.GetLeft();
Return Value
The position of the left edge of the map control.
Remarks
The pixel value is relative to the browser window, not the entire display screen.
Example
VirtualEarthSDK#19
VEMap.GetMapMode Method
Returns the current map mode.
Syntax
VEMap.GetMapMode();
Return Value
A VEMapMode Enumeration value.
Example
VirtualEarthSDK#20
VEMap.GetMapStyle Method
Returns the current map style.
Syntax
VEMap.GetMapStyle();
Return Value
A VEMapStyle Enumeration value that represents the current map style.
Remarks
You can determine the current map style by using the GetMapStyle method, and then setting the
map style using the VEMap.SetMapStyle Method.
Example
VirtualEarthSDK#20
VEMap.GetMapView Method
Returns the current map view object as a VELatLongRectangle Class object.
Syntax
166
VEMap.GetMapView();
Return Value
A VELatLongRectangle Class object that represents the current map view.
Example
VirtualEarthSDK#21
VEMap.GetPitch Method
In 3D mode, returns a double that represents the pitch of the current map view.
Syntax
VEMap.GetPitch();
Return Value
A double that represents the pitch, where 0 is level and -90 is straight down.
Remarks
The VEMap.GetAltitude Method, VEMap.GetHeading Method, and GetPitch method return
values only when the map mode (VEMapMode Enumeration) is set to Mode3D and the current
map view is completely loaded. To be sure that the map view is completely loaded, you can use
the VEMap.onendpan Event.
Example
VirtualEarthSDK#22
VEMap.GetRoute Method
Deprecated. Use the VEMap.GetDirections Method instead.
Draws a route on the map and sends details about the route to a callback function.
Syntax
VEMap.GetRoute(start, end, units, route_type, callback);
Parameters
Parameter Description
start The start location. This can be a string value of
an address, a place name, or a VELatLong
Class object that specifies the start location
end The ending location. This can be a string value
of an address, a place name, or a VELatLong
object that specifies the end location
167
Parameter Description
units A VEDistanceUnit Enumeration value that
specifies either miles or kilometers. Optional.
Default is VEDistanceUnit.Miles
route_type A VERouteType Enumeration value specifying
either the shortest route or the quickest route.
Optional. Default is VERouteType.Shortest
callback Specifies the function called after the route is
drawn on the map. The callback function is
passed a VERouteDeprecated Class object
containing information about the route.
Remarks
This method has been deprecated. Use the VEMap.GetDirections Method instead. Note that the
routes returned by the two methods may vary.
This method ignores specified cultures. Use the VEMap.GetDirections Method if you want to
return localized directions.
See Also
VEMap.GetDirections Method
Returning Localized Results
VEMap.GetShapeByID Method
Gets the reference to a VEShape Class object based on its internal identifier.
Syntax
VEMap.GetShapeByID(ID);
Parameters
Parameter Description
ID The identifier of the shape to retrieve.
Required.
Return Value
A reference to the specified VEShape object. If no shape exists with the specified ID, this method
returns null.
Remarks
A shape's ID is internal and cannot be changed. A shape's ID string as provided by an Event
object (see VEMap Events) may have some extensions on it beyond the root ID string returned
168
by VEShape.GetID Method. However, this method will always return the correct shape reference,
regardless of any extension after the root ID.
Example
VirtualEarthSDK#38
See Also
VEMap.AddShape Method
VEMap.GetShapeLayerByIndex Method
Gets the reference to a VEShapeLayer Class object based on its index.
Syntax
VEMap.GetShapeLayerByIndex(index);
Parameters
Parameter Description
index The index of the layer that you wish to retrieve.
Required.
Return Value
A reference to the requested layer. If there is not a valid shape layer at the specified index, null is
returned.
Example
VirtualEarthSDK#23
VEMap.GetShapeLayerCount Method
Gets the total number of shape layers on the map.
Syntax
VEMap.GetShapeLayerCount();
Return Value
An integer representing the total number of shape layers on the map.
Remarks
The number of shape layers returned by the GetShapeLayerCount method includes the base
map layer. For example, if you add one shape layer, then the GetShapeLayerCount method
returns 2.
Example
VirtualEarthSDK#8
169
VEMap.GetTileLayerByID Method
Gets a tile layer based upon its identifier.
Syntax
VEMap.GetTileLayerByID(id);
Parameters
Parameter Description
id The unique identifier of the tile layer
Return Value
A VETileSourceSpecification Class object.
Example
VirtualEarthSDK#64
See Also
VEMap.GetTileLayerByIndex Method
VEMap.GetTileLayerCount Method
VEMap.GetTileLayerByIndex Method
Gets a tile layer based upon an index value.
Syntax
VEMap.GetTileLayerByIndex(index);
Parameters
Parameter Description
index The index into the list of tile layers. The value
ranges from 0 to GetTileLayerCount.
Return Value
A VETileSourceSpecification Class object.
Example
VirtualEarthSDK#42
See Also
VEMap.GetTileLayerByID Method
VEMap.GetTileLayerCount Method
170
VEMap.GetTileLayerCount Method
Gets the number of tile layers.
Syntax
VEMap.GetTileLayerCount();
Return Value
An integer specifying the number of tile layers.
Example
VirtualEarthSDK#42
See Also
VEMap.GetTileLayerByID Method
VEMap.GetTileLayerByIndex Method
VEMap.GetTop Method
Returns the pixel value of the top edge of the map control.
Syntax
VEMap.GetTop();
Return Value
The position of the top edge of the map control.
Remarks
The pixel value is relative to the browser window, not the entire display screen.
Example
VirtualEarthSDK#19
VEMap.GetVersion Method
Returns the current version of the map control.
Syntax
VEMap.GetVersion();
Return Value
A string of the current map version.
Remarks
You use the GetVersion method with the VEMap object itself, not an instance of the
object. This is because every instance of the VEMap object on a page will be the same
version.
171
Example
VirtualEarthSDK#19
VEMap.GetZoomLevel Method
Returns the current zoom level of the map.
Syntax
VEMap.GetZoomLevel();
Return Value
A string of the current zoom level.
Remarks
This method may not give the same value in 3D mode as in 2D mode.
Example
VirtualEarthSDK#19
VEMap.Hide3DNavigationControl Method
On November 2, 2010, the end-of-life was announced for the 3D control. Effective
December 1, 2011, the 3D control will no longer function. The full announcement is found
at: http://www.bing.com/community/site_blogs/b/maps/archive/2010/11/02/changes-to-
bird-s-eye-and-3d-maps.aspx
In 3D mode, hides the default user interface for controlling the map in 3D mode. By default, this
control is shown.
Syntax
VEMap.Hide3DNavigationControl();
Remarks
By default, the 3D Navigation control is displayed on the map when the map is set to 3D mode. If
you want to hide this control, you can call this method. To show the control, call the
VEMap.Show3DNavigationControl Method.
Example
VirtualEarthSDK#24
VEMap.HideAllShapeLayers Method
Hides all of the VEShapeLayer Class objects on the map.
Syntax
VEMap.HideAllShapeLayers();
172
Example
VirtualEarthSDK#25
See Also
VEMap.ShowAllShapeLayers Method
VEMap.HideBaseTileLayer Method
Hides the base tile layer of the map.
Syntax
VEMap.HideBaseTileLayer();
Example
VirtualEarthSDK#63
See Also
VEMap.ShowBaseTileLayer Method
VEMap.HideControl Method
Hides the specified control from view.
Syntax
VEMap.HideControl(element);
Parameters
Parameter Description
element An HTML element that contains the control to
be hidden.
Example
VirtualEarthSDK#3
See Also
VEMap.DeleteControl Method
VEMap.ShowControl Method
VEMap.HideDashboard Method
Hides the default user interface for controlling the map (the compass and the zoom control).
Syntax
VEMap.HideDashboard();
Remarks
173
If you want to provide your own user interface for controlling the map, you can call this method to
hide the default controls, and then use the VEMap.AddControl Method to display your custom
control.
To show the default dashboard, call the VEMap.ShowDashboard Method.
Example
VirtualEarthSDK#24
VEMap.HideFindControl Method
Deprecated. Removes the Find control from the map.
Note This method is deprecated. Use the example below to create a custom Find control.
Syntax
VEMap.HideFindControl();
Remarks
The Find control enables users to find information and locations on the map. By default, the Find
control is not displayed on the map. You can display it by calling the VEMap.ShowFindControl
Method.
Example
VirtualEarthSDK#60
See Also
VEMap.Find Method
VEMap.HideInfoBox Method
Hides a shape's custom or default info box.
Syntax
VEMap.HideInfoBox();
Remarks
There can be only one info box on the screen at a given time. The method will hide any currently
visible info box. You do not need to specify a specific VEShape Class object in this method.
Example
VirtualEarthSDK#26
VEMap.HideMiniMap Method
Hides the mini map from view.
Syntax
VEMap.HideMiniMap();
174
Remarks
Call VEMap.ShowMiniMap to display the mini map.
The mini map is not supported in 3D.
Example
VirtualEarthSDK#24
See Also
VEMap.ShowMiniMap Method
VEMap.HideScalebar Method
Hides the scale bar from the map.
Syntax
VEMap.HideScalebar();
Remarks
By default the scale bar is displayed on the map.
Example
VirtualEarthSDK#55
See Also
VEMap.ShowScalebar Method
VEMap.HideTileLayer Method
Hides a tile layer from view.
Syntax
VEMap.HideTileLayer(layerID);
Parameters
Parameter Description
layerID The ID of the layer to be hidden.
Example
VirtualEarthSDK#9
See Also
VEMap.DeleteTileLayer Method
VEMap.ShowTileLayer Method
VEMap.HideTrafficLegend Method
Hides the traffic legend.
175
Syntax
VEMap.HideTrafficLegend()
Example
VirtualEarthSDK#13
See Also
VEMap.ClearTraffic Method
VEMap.ShowTrafficLegend Method
VEMap.Import3DModel Method
On November 2, 2010, the end-of-life was announced for the 3D control. Effective
December 1, 2011, the 3D control will no longer function. The full announcement is found
at: http://www.bing.com/community/site_blogs/b/maps/archive/2010/11/02/changes-to-
bird-s-eye-and-3d-maps.aspx
Imports a model data file and displays a 3D model on the map.
Syntax
VEMap.Import3DModel(modelShapeSource, callback, latLong, orientation, scale);
Parameters
Parameter Description
modelShapeSource A VEModelSourceSpecification Class object
specifying the model data to import.
callback The name of the function that is called after the
data has been imported. See below for the
arguments received by the callback.
latLong A VELatLong Class object that specifies the
point at which to place the origin of the model.
orientation A VEModelOrientation Class object that
specifies the orientation of the model on the
map.
scale A VEModelScale Class object that specifies the
scale of the model.
Return Value
176
A VEShape Class object corresponding to the pushpin associated with the 3D model. This is also
returned to the function specified in the callback parameter.
The function defined in the callback parameter receives the following arguments, in the order
shown:
A VEShape Class object corresponding to the pushpin associated with the 3D model. This is
the same object returned by the Import3DModel method.
A VEModelStatusCode Enumeration value indicating the status of the 3D model import. This
status code only indicates if the model data was successfully imported. It does not indicate
whether or not the model rendered properly.
Remarks
3D models support VEShape Class methods that have pushpin support.
Information about file support is found in the VEModelFormat Enumeration topic.
The function specified in the callback parameter is called if the user switches to
VEMapMode.Mode3D from VEMapMode.Mode2D.
The function specified in the callback parameter is called when the following methods are used:
VEShape.Show Method, VEShape.SetZIndex Method, VEShape.SetMaxZoomLevel Method,
VEShape.SetMinZoomLevel Method, VEShape.ShowIcon Method, and VEShape.HideIcon
Method.
Example
VirtualEarthSDK#59
VEMap.ImportShapeLayerData Method
Imports data from a GeoRSS feed, Bing Maps (http://maps.live.com) collection, or KML URL.
Syntax
VEMap.ImportShapeLayerData(shapeSource, callback, setBestView);
Parameters
Parameter Description
shapeSource A VEShapeSourceSpecification Class object
specifying the imported shape data.
callback The function that is called after the data has
been imported.
setBestView A Boolean value that specifies whether the
map view is changed to the best view for the
layer.
Return Value
177
This method returns nothing. The imported data is passed as a VEShapeLayer Class object to
the function specified by callback.
Remarks
If the specified layer has not already been added to the map, this method adds it automatically. If
the GeoRSS feed URL, Bing Maps collection GUID, or XML URL is invalid, this method throws an
exception.
To set the map view to the best view on the imported shapes, add the shapes to an empty layer.
For more information about supported file formats, see the VEDataType Enumeration topic.
Example
VirtualEarthSDK#27
See Also
VEShapeSourceSpecification Class
VEDataType Enumeration
VEMap.IncludePointInView Method
Changes the map view so that it includes both the specified VELatLong Class point and the
center point of the current map.
Syntax
VEMap.IncludePointInView(latlong);
Parameters
Parameter Description
latlong A VELatLong Class object that specifies the
latitude and longitude of the point to include
Remarks
When you call the IncludePointInView method, the center point of the map changes, but the
original center point remains within the map view.
Example
VirtualEarthSDK#28
VEMap.IsBirdseyeAvailable Method
Determines whether the bird's eye map style is available in the current map view.
Syntax
VEMap.IsBirdseyeAvailable();
Return Value
178
Returns false if the map mode is set to 3D (VEMap.GetMapMode Method returns 2). Returns
true if bird's eye images are available and the zoom level is 11 or greater.
Example
VirtualEarthSDK#17
See Also
VEMap.SetZoomLevel Method
VEMap.LatLongToPixel Method
Converts VELatLong Class objects (latitude/longitude pair) to VEPixel Class objects.
Syntax
VEMap.LatLongToPixel(latLongArray, zoomLevel, callback);
Parameters
Parameter Description
latLongArray A VELatLong object or an array of VELatLong
objects. Required. If an array is passed, the
callback parameter must be specified.
zoomLevel The zoom level at which the VELatLong
objects are converted to VEPixel objects.
Optional. If this parameter is not supplied, the
current zoom level is used.
callback The name of the function called with the array
of corresponding VEPixel objects. Optional.
Return Value
If the callback parameter is not supplied, the LatLongToPixel method returns a VEPixel object
corresponding to the VELatLong object specified in the latLongArray parameter.
If the callback parameter is supplied, the specified callback function must accept an array of
VEPixel objects.
Remarks
To get the latitude and longitude of a point on the map, use the VEMap.PixelToLatLong Method.
Example
VirtualEarthSDK#53
See Also
VEBirdseyeScene.LatLongToPixel Method
179
VEMap.LoadMap Method
Loads the specified map. All parameters are optional.
Syntax
VEMap.LoadMap(VELatLong, zoom, style, fixed, mode, showSwitch, tileBuffer, mapOptions);
Parameters
Parameter Description
VELatLong A VELatLong Class object that represents the
center of the map. Optional.
zoom The zoom level to display. Valid values range
from 1 through 19. Optional. Default is 4.
style A VEMapStyle Enumeration value specifying
the map style. Optional. Default is
VEMapStyle.Road.
fixed A Boolean value that specifies whether the map
view is displayed as a fixed map that the user
cannot change. Optional. Default is false.
mode A VEMapMode Enumeration value that
specifies whether to load the map in 2D or 3D
mode. Optional. Default is
VEMapMode.Mode2D.
showSwitch A Boolean value that specifies whether to show
the map mode switch on the dashboard control.
Optional. Default is true (the switch is
displayed).
tileBuffer How much tile buffer to use when loading map.
Default is 0 (do not load an extra boundary of
tiles). This parameter is ignored in 3D mode.
mapOptions A VEMapOptions Class that specifies other
map options to set.
Remarks
Before calling this method, you must initialize the map object by using the VEMap Constructor.
If you want to use a callback function with the map control, set the VEMap.onLoadMap Property
before calling the LoadMap method.
Use the VEMap.Dispose Method before calling LoadMap a second time.
180
To 'lock' the map in a certain position, either set the fixed parameter to true when loading the map
or disable mouse events during the application session. The following code disables mouse
events.
// Attach an event handler for a mousedown event.
map.AttachEvent("onmousedown", DisableMap);
// When the mouse is used, the DisableMap function will
// get called. Returning true will disable the mousedown
// event, which disables panning.
function DisableMap()
{
return true;
}
Example
VirtualEarthSDK#29
See Also
VEMap.SetCenter Method
VEMap.SetCenterAndZoom Method
VEMap.SetMapStyle Method
VEMap.SetMapMode Method
VEMapOptions Class
VEMap.LoadTraffic Method
Loads the traffic map.
Syntax
VEMap.LoadTraffic(showFlow);
Parameters
Parameter Description
showFlow Whether to show the traffic flow
Remarks
The traffic map is only available at zoom levels from 9 through 14, inclusively.
Terms of Use
181
All use of traffic data is restricted to customers who have received explicit permission and
instructions about traffic from Microsoft. For more information on terms for use of traffic, contact
the Bing Maps Licensing Team.
Example
VirtualEarthSDK#13
See Also
VEMap.ClearTraffic Method
VEMap.ShowTrafficLegend Method
VEMap.Pan Method
When in 2D mode, moves the map the specified amount.
Syntax
VEMap.Pan(deltaX, deltaY);
Parameters
Parameter Description
deltaX The amount to move the map horizontally, in
pixels
deltaY The amount to move the map vertically, in
pixels
Remarks
The Pan method only applies to 2D mode maps. If you are working with maps in 3D mode, use
the VEMap.StartContinuousPan Method and VEMap.EndContinuousPan Method.
If the deltaX parameter is greater than the map view width or the deltaY parameter is greater than
the map view height, then a jump pan occurs instead of a gradual pan. If a jump pan occurs that
causes the map to pan past one of the world map bounds, then the map will zoom to level 1 to
show the entire world map.
Example
VirtualEarthSDK#30
See Also
VEMap.PanToLatLong Method
VEMap.PanToLatLong Method
Pans the map to a specific latitude and longitude.
Syntax
182
VEMap.PanToLatLong(VELatLong);
Parameters
Parameter Description
VELatLong A VELatLong Class object that represents the
latitude and longitude of the point on which to
center the map
Remarks
The PanToLatLong method moves the map from one location to another with a smooth
transition effect. If you want the map to instantly reposition on a new center point, use the
VEMap.SetCenter Method.
Example
VirtualEarthSDK#30
See Also
VEMap.Pan Method
VEMap.PixelToLatLong Method
Converts a pixel (a point on the map) to a VELatLong Class object (latitude/longitude pair).
Syntax
VEMap.PixelToLatLong(pixel);
Parameters
Parameter Description
pixel A VEPixel Class object representing a pixel
location on the map.
Return Value
A VELatLong Class object of the pixel point.
Remarks
This method may return null values when the map is in 3D mode.
To obtain the bounding area of a map in 3D mode, call the VEMap.GetMapView Method.
Example
VirtualEarthSDK#31
VEMap.RemoveCustomLayer Method
Removes a custom layer from the map.
183
Syntax
VEMap.RemoveCustomLayer(object);
Parameters
Parameter Description
object The object to remove from the map DIV
container.
Example
VirtualEarthSDK#61
See Also
VEMap.AddCustomLayer Method
VEMap.Resize Method
Resizes the map based on the specified width and height.
Syntax
VEMap.Resize(width, height);
Parameters
Parameter Description
width The width, in pixels, of the map. Optional.
height The height, in pixels, of the map. Optional.
Remarks
If this method is called with no parameters, the map is resized to fit the entire DIV element.
This method triggers the VEMap.onresize Event.
Example
VirtualEarthSDK#32
VEMap.Search Method
Performs a search based on a given query and options.
Syntax
VEMap.Search(query, callback, options);
Parameters
184
Parameter Description
query The string to use in the search.
callback The name of the function that the server calls
with the search results.
options A VESearchOptions Class object specifying
additional options.
Return Value
This method does not return a value. The function defined by the callback parameter receives the
following arguments, in the order shown, from the server:
A VEShapeLayer Class object.
An array of VEFindResult Class objects.
An array of VEPlace Class objects.
A Boolean value indicating whether there are more results after the current set.
A String containing a possible error message.
Example
VirtualEarthSDK#67
See Also
VESearchOptions Class
VEMap.Geocode Method
VEMap.SetAltitude Method
In 3D mode, sets the altitude, in meters, above the WGS 84 ellipsoid in the map view.
Syntax
VEMap.SetAltitude(altitude);
Parameters
Parameter Description
altitude The altitude, in meters
Remarks
The SetAltitude method, VEMap.SetHeading Method, and VEMap.SetPitch Method apply only
when the map mode (VEMapMode Enumeration) is set to Mode3D and the current map view is
completely loaded. To be sure that the map view is completely loaded, you can use the
VEMap.onendpan Event.
Example
185
VirtualEarthSDK#16
VEMap.SetBirdseyeOrientation Method
Changes the orientation of the existing bird's eye image (VEBirdseyeScene Class object) to the
specified orientation.
Syntax
VEMap.SetBirdseyeOrientation(orientation);
Parameters
Parameter Description
orientation You can set this value by using either the
VEOrientation Enumeration or a string value.
Valid string values are North, South, East, and
West.
Return Value
Returns false if the map mode is set to 3D (VEMap.GetMapMode Method returns 2).
Example
VirtualEarthSDK#33
VEMap.SetBirdseyeScene Method
Displays the specified bird's eye image.
Overload List
Method Description
VEMap.SetBirdseyeScene(id) Method Displays the bird's eye image specified by the
VEBirdseyeScene Class ID
VEMap.SetBirdseyeScene(veLatLong,
orientation, zoomLevel, callback) Method
Displays the bird's eye image specified by the
center of the map, the orientation, and the
zoom level
Return Value
Returns false if the map mode is set to 3D (VEMap.GetMapMode Method returns 2).
Remarks
If the current map style is VEMapStyle.Birdseye or VEMapStyle.BirdseyeHybrid, then the
VEMapOptions.EnableDashboardLabels Property value is ignored when the SetBirdseyeScene
method is called.
186
VEMap.SetBirdseyeScene(id) Method
Displays the bird's eye image specified by the VEBirdseyeScene Class ID.
Syntax
VEMap.SetBirdseyeScene(id);
Parameters
Parameter Description
id The ID of the VEBirdseyeScene Class object
that you want to display
Example
VirtualEarthSDK#33
See Also
VEMap.SetBirdseyeScene(veLatLong, orientation, zoomLevel, callback) Method
VEMap.SetBirdseyeScene(veLatLong, orientation, zoomLevel, callback) Method
Displays the specified bird's eye image.
Syntax
VEMap.SetBirdseyeScene(veLatLong, orientation, zoomLevel, callback);
Parameters
Parameter Description
veLatLong A VELatLong Class object specifying the center
of the image. Optional. If this parameter is not
supplied the center of the map is used.
orientation A VEOrientation Enumeration value specifying
the direction to which which the image is
viewed. Optional. If this value is not supplied,
the default value VEOrientation.North is used.
zoomLevel The level of zoom. Optional. If this parameter is
not supplied, the value 1 is used.
callback The name of the function called when the
SetBirdseyeScene method completes.
Return Value
The callback function receives a VEBirdseyeScene Class object.
187
Example
VirtualEarthSDK#33
See Also
VEMap.SetBirdseyeScene(id) Method
VEMap.SetCenter Method
Centers the map to a specific latitude and longitude.
Syntax
VEMap.SetCenter(VELatLong);
Parameters
Parameter Description
VELatLong A VELatLong Class object that contains the
latitude and longitude of the point on which to
center the map.
Remarks
If you are setting both the center point and the zoom level, you should use the
VEMap.SetCenterAndZoom Method, rather than calling the SetCenter method and the
VEMap.SetZoomLevel Method separately.
Example
VirtualEarthSDK#34
See Also
VEMap.GetCenter Method
VEMap.SetCenterAndZoom Method
Centers the map to a specific latitude and longitude and sets the zoom level.
Syntax
VEMap.SetCenterAndZoom(VELatLong, zoomLevel);
Parameters
Parameter Description
VELatLong A VELatLong Class object that contains the
latitude and longitude of the point on which to
center the map,
188
Parameter Description
zoomLevel The zoom level for the map. Valid values range
from 1 through 19.
Remarks
The SetCenterAndZoom method returns results faster than if you call both the
VEMap.SetCenter Method and the VEMap.SetZoomLevel Method separately.
Example
VirtualEarthSDK#34
See Also
VEMap.GetCenter Method
VEMap.SetClientToken Method
Bing Maps Keys are the recommended authentication method for accessing the Bing
Maps AJAX Control 6.3 as described in Getting a Bing Maps Key. Information about
transaction accounting provided by Bing Maps Keys is in Understanding Bing Maps
Usage Reports. If you are an existing customer using tokens, consider updating your
application to use Bing Maps Keys. See the Getting Started with the Bing Maps AJAX
Control topic.
Sets a Bing Maps token for the VEMap object.
Syntax
VEMap.SetClientToken(clientToken);
Parameters
Parameter Description
clientToken A string representing the Bing Maps token.
Remarks
The SetClientToken method is used to help Bing Maps customers monitor their map control
usage. By setting a token on the VEMap object, requests made to Bing Maps by the map control
can be tracked. More information is found in the Tracking Your Bing Maps Usage topic.
Use the SetClientToken method to set a token before calling the VEMap.LoadMap Method to
ensure all map control and tile requests are tracked.
If an invalid token is set, the VEMap.ontokenerror Event fires when the map control makes a
request to Bing Maps.
189
If an expired token is set, the VEMap.ontokenexpire Event fires when the map control makes a
request to Bing Maps.
Example
VirtualEarthSDK#57
See Also
VEMap.ontokenerror Event
VEMap.ontokenexpire Event
VEMap.SetCredentials Method
Sets the credentials to use to authenticate map service requests.
Use the SetCredentials method to set the Bing Maps Key that you obtained from the
Bing Maps Account Center as described in the Getting Started with the Bing Maps AJAX
Control topic. Information about Bing Maps usage reports is in Viewing Bing Maps Usage
Reports.
Syntax
VEMap.SetCredentials(credentials);
Parameters
Parameter Description
credentials A string that is the Bing Maps Key to set.
Example
VirtualEarthSDK#62
VEMap.SetDashboardSize Method
Sets the map dashboard size and type.
Syntax
VEMap.SetDashboardSize(dashboard);
Parameters
Parameter Description
dashboardSize A VEDashboardSize Enumeration representing
the dashboard size. Valid values are Normal,
Small, and Tiny.
190
Remarks
This method must be called before VEMap.LoadMap Method.
Example
VirtualEarthSDK#24
See Also
VEMap.HideDashboard Method
VEMap.SetDefaultInfoBoxStyles Method
Sets the info box CSS styles back to their original classes.
Syntax
VEMap.SetDefaultInfoBoxStyles();
Remarks
The VEMap.SetDefaultInfoBoxStyles method, called after a call to VEMap.ClearInfoBoxStyles
Method, resets all of the original info box styles. The method VEMap.ClearInfoBoxStyles clears
out all of the default info box styles and sets just a few basic styles.
Examples
VirtualEarthSDK#12
VEMap.SetFailedShapeRequest Method
Specifies what the map control does when a request to the server to get the accurate position of
a shape when the map style is changed to birdseye fails.
Syntax
VEMap.SetFailedShapeRequest(policy);
Parameters
Parameter Description
policy A VEFailedShapeRequest Enumeration value
that defines the policy.
Remarks
By default, shapes are not subject to increased accuracy representation when the map style is
set to birdseye (the default accuracy is VEShapeAccuracy.None). Use the
VEMap.SetShapesAccuracy Method to improve the accuracy of shapes when setting the map
style to birdseye. By default, up to 50 shapes are converted at at time. To change this value, use
the VEMap.SetShapesAccuracyRequestLimit Method.
This method must be called before the shapes are added to the map, otherwise the default policy
(VEFailedShapeRequest.DrawInaccurately) is followed.
191
The examples uses the following custom images.
Examples
VirtualEarthSDK#43
VEMap.SetHeading Method
In 3D mode, sets the compass heading of the current map view.
Syntax
VEMap.SetHeading(heading);
Parameters
Parameter Description
heading The compass direction, expressed as a double.
A value of 0 is true north, and a value of 180 is
true south. Values less than 0 and greater than
360 are valid and are calculated as compass
directions.
Remarks
The VEMap.SetAltitude Method, SetHeading method, and VEMap.SetPitch Method apply only
when the map mode (VEMapMode Enumeration) is set to Mode3D and the current map view is
completely loaded. To be sure that the map view is completely loaded, you can use the
VEMap.onendpan Event.
Example
VirtualEarthSDK#18
VEMap.SetMapMode Method
Sets the mode of the map.
Syntax
VEMap.SetMapMode(mode);
Parameters
Parameter Description
mode A VEMapMode Enumeration value that
192
Parameter Description
specifies whether to load the map in 2D or 3D
mode
Example
VirtualEarthSDK#20
VEMap.SetMapStyle Method
Sets the style of the map.
On July 6, 2011, the new enhanced road map style in use on http://www.bing.com/maps
became the default and only road style available for all Bing Maps APIs.
Syntax
VEMap.SetMapStyle(mapStyle);
Parameters
Parameter Description
mapStyle A VEMapStyle Enumeration value specifying
the map style.
Remarks
The map style can also be set when the map is loaded with the VEMap.LoadMap Method.
Example
VirtualEarthSDK#20
See Also
VEMap.GetMapStyle Method
VEMap.SetMapView Method
Sets the map view to include all of the points, lines, or polygons specified in the provided array, or
to the view defined by a VEMapViewSpecification Class object.
Syntax
VEMap.SetMapView(object);
Parameters
193
Parameter Description
object In 2D mode, an array of VELatLong Class
points or a VELatLongRectangle Class object.
In 3D mode, can also be a
VEMapViewSpecification Class object. This
object defines the location, altitude, pitch, and
heading to use for the map view.
Remarks
The method is useful when you want a map to cover a known collection of points, but you are not
sure what the center point is, or what zoom level is required to fit the entire region in your current
map control.
Example
VirtualEarthSDK#20
VEMap.SetMouseWheelZoomToCenter Method
Specifies whether to zoom to the center of the screen or to the cursor position on the screen.
Syntax
VEMap.SetMouseWheelZoomToCenter(zoomToCenter);
Parameters
Parameter Description
zoomToCenter A Boolean value specifying whether to zoom to
the center of the screen or to the cursor
position. If true, the map control zooms to the
center of the screen; if false, the map control
zooms to the cursor position on the screen.
Remarks
By default the map control zooms to the center of the screen.
Example
VirtualEarthSDK#34
See Also
VEMap.SetZoomLevel Method
VEMap.SetPitch Method
In 3D mode, sets the pitch of the current map view.
Syntax
194
VEMap.SetPitch(pitch);
Parameters
Parameter Description
pitch The pitch direction, expressed as a double. A
value of 0 is level and a value of -90 is straight
down. Values less than -90 or greater than 0
are ignored, and the pitch is set to -90.
Remarks
The VEMap.SetAltitude Method, VEMap.SetHeading Method, and SetPitch method apply only
when the map mode (VEMapMode Enumeration) is set to Mode3D and the current map view is
completely loaded. To be sure that the map view is completely loaded, you can use the
VEMap.onendpan Event.
Example
VirtualEarthSDK#35
VEMap.SetPrintOptions Method
This method controls how the map is printed.
Syntax
VEMap.SetPrintOptions(printOptions);
Parameters
Parameter Description
printOptions A VEPrintOptions Class specifying the print
options to set.
Remarks
The default value for the VEPrintOptions.EnablePrinting Property is false, which means printing
support is off by default.
There may be a decrease in the performance of the map control if the
VEPrintOptions.EnablePrinting Property is equal to true.
Example
VirtualEarthSDK#50
See Also
VEPrintOptions Class
195
VEMap.SetScaleBarDistanceUnit Method
Sets the distance unit (kilometers or miles) for the map scale.
Syntax
VEMap.SetScaleBarDistanceUnit(distanceUnit);
Parameters
Parameter Description
distanceUnit A VEDistanceUnit Enumeration value that
specifies either miles or kilometers
Remarks
This method changes the scale bar on the map. It does not affect the units used in driving
directions. To change the units used for driving directions, use the VERouteOptions.DistanceUnit
Property with the VEMap.GetDirections Method.
Example
VirtualEarthSDK#24
VEMap.SetShapesAccuracy Method
Specifies the accuracy in converting shapes when the map style is changed to birdseye.
Syntax
VEMap.SetShapesAccuracy(policy);
Parameters
Parameter Description
policy The VEShapeAccuracy Enumeration value
specifying the accuracy in converting shapes.
Remarks
By default, shapes are not subject to increased accuracy representation when the map style is
set to birdseye (the default accuracy is VEShapeAccuracy.None). Use this method to improve
the accuracy of shapes when setting the map style to birdseye. By default, up to 50 shapes are
converted at a time. To change this value, use the VEMap.SetShapesAccuracyRequestLimit
Method.
The example uses the following custom images.
196
Examples
VirtualEarthSDK#43
VEMap.SetShapesAccuracyRequestLimit Method
Specifies the maximum number of shapes that are accurately converted at one time when the
map style is changed to birdseye.
Syntax
VEMap.SetShapesAccuracyRequestLimit(max);
Parameters
Parameter Description
max The maximum number of shapes that are
accurately converted.
Remarks
By default, shapes are not subject to increased accuracy representation when the map style is
set to birdseye (the default accuracy is VEShapeAccuracy.None). Use the
VEMap.SetShapesAccuracy Method to improve the accuracy of shapes when setting the map
style to birdseye. By default, up to 50 shapes are converted at a time. To change this value, use
this method.
The examples uses the following custom images.
Examples
VirtualEarthSDK#43
Remarks
The default value is 50. This method only effects pushpin locations.
VEMap.SetTileBuffer Method
Sets the number of "rings" of map tiles that should be loaded outside of the visible mapview area.
This is also called tile overfetching.
Syntax
VEMap.SetTileBuffer(numRings);
Parameters
197
Parameter Description
numRings An integer value greater than or equal to 0 that
indicates the number of rings of additional tiles
that should be loaded. The default is 0, and the
maximum is 3.
Remarks
This method can be called before VEMap.LoadMap Method to affect how tiles are loaded initially,
but it can also be called at any time after the map is loaded to change the overfetch behavior.
There are performance considerations with this method. Loading more rings may improve
a user's initial map panning experience, but this may initially cause the page to load more
slowly.
Example
VirtualEarthSDK#36
VEMap.SetTrafficLegendText Method
Specifies the text shown with the traffic legend, if visible.
Syntax
VEMap.SetTrafficLegendText(text)
Parameters
Parameter Description
text A string specifying the text shown with the
traffic legend.
Example
VirtualEarthSDK#13
See Also
VEMap.ShowTrafficLegend Method
VEMap.SetZoomLevel Method
Sets the view of the map to the specified zoom level.
Syntax
VEMap.SetZoomLevel(zoomLevel);
Parameters
198
Parameter Description
zoomLevel The zoom level for the map. Valid values range
from 1 through 19
Remarks
Higher zoom levels show more detail on the map, and you appear closer to the ground.
Some areas do not have high-resolution aerial photography and therefore may not support the
highest zoom levels.
If you are setting both the center point and the zoom level, you should use the
VEMap.SetCenterAndZoom Method, rather than calling the VEMap.SetCenter Method and the
SetZoomLevel method separately.
Example
VirtualEarthSDK#34
See Also
VEMap.SetMouseWheelZoomToCenter Method
VEMap.Show3DBirdseye Method
Controls whether or not to show the Birdseye and BirdseyeHybrid map styles when the map
mode is set to VEMapMode.Mode3D.
Syntax
VEMap.Show3DBirdseye(showBirdseye);
Parameters
Parameter Description
showBirdseye A Boolean value that specifies whether or not to
show the Birdseye or BirdseyeHybrid map
styles when the map mode is set to
VEMapMode.Mode3D. The default is false.
Remarks
This method does not do anything when the map mode is set to VEMapMode.Mode2D.
This method does not do anything when the VEMapOptions.EnableBirdseye Property is set to
false.
Example
VirtualEarthSDK#51
See Also
199
VEMapStyle Enumeration
VEMapMode Enumeration
VEMap.Show3DNavigationControl Method
On November 2, 2010, the end-of-life was announced for the 3D control. Effective
December 1, 2011, the 3D control will no longer function. The full announcement is found
at: http://www.bing.com/community/site_blogs/b/maps/archive/2010/11/02/changes-to-
bird-s-eye-and-3d-maps.aspx
In 3D mode, shows the default user interface for controlling the map in 3D mode. By default, this
control is shown.
Syntax
VEMap.Show3DNavigationControl();
Remarks
By default, the 3D Navigation control is displayed on the map when the map is set to 3D mode. If
you want to hide this control, you can call the VEMap.Hide3DNavigationControl Method.
Example
VirtualEarthSDK#24
VEMap.ShowAllShapeLayers Method
Shows all of the VEShapeLayer Class objects on the map.
Syntax
VEMap.ShowAllShapeLayers();
Example
VirtualEarthSDK#25
See Also
VEMap.HideAllShapeLayers Method
VEMap.ShowBaseTileLayer Method
Shows the base tile layer of the map.
Syntax
VEMap.ShowBaseTileLayer();
Example
VirtualEarthSDK#63
See Also
VEMap.HideBaseTileLayer Method
200
VEMap.ShowControl Method
Makes the specified control visible. This method only affects control elements that have been
hidden from view using the VEMap.HideControl Method.
Syntax
VEMap.ShowControl(element);
Parameters
Parameter Description
element An HTML element that contains the control to
be shown.
Example
VirtualEarthSDK#3
See Also
VEMap.AddControl Method
VEMap.HideControl Method
VEMap.ShowDashboard Method
Shows the default user interface for controlling the map (the compass-and-zoom control). By
default, this control is shown.
Syntax
VEMap.ShowDashboard();
Remarks
If you want to provide your own user interface for controlling the map, you can call the
VEMap.HideDashboard Method to hide the default controls, and then use the VEMap.AddControl
Method to display your custom control.
Example
VirtualEarthSDK#24
VEMap.ShowDisambiguationDialog Method
Specifies whether the default disambiguation dialog is displayed when multiple results are
returned from a location query using the VEMap.GetDirections Method.
Syntax
VEMap.ShowDisambiguationDialog(showDialog);
Parameters
201
Parameter Description
showDialog A Boolean value. True enables the
disambiguation dialog; false disables it.
Remarks
By default, the disambiguation dialog is displayed whenever the map control returns more than
one result from a location search. This dialog enables the user to select the correct location from
the list of returned results. By disabling this dialog, the first location will always be chosen.
Example
VirtualEarthSDK#49
VEMap.ShowFindControl Method
Deprecated. Shows the Find control, which enables users to enter search queries.
Note This method is deprecated. Use the example below to create a custom Find control.
Syntax
VEMap.ShowFindControl(top, left);
Parameters
Parameter Description
top An integer specifying the number of pixels
between the top edge of the map and the top
edge of the Find control. Optional. The default
is 35 pixels.
left An integer specifying the number of pixels
between the left edge of the map and the left
edge of the Find control. Optional. The default
is 195 pixels.
Remarks
By default, the Find control is not visible. By calling this method, you can quickly and easily
provide search capabilities to your map.
To hide the Find control, call the VEMap.HideFindControl Method.
Example
VirtualEarthSDK#60
See Also
VEMap.HideFindControl Method
VEMap.Find Method
202
VEMap.ShowInfoBox Method
Shows an information box for the shape.
Syntax
VEMap.ShowInfoBox(shape, anchor, offset);
Parameters
Parameter Description
shape The reference to the shape for which an info
box is to be shown. Required.
anchor The anchor point where the info box is docked
when displayed. This can either be a
VELatLong Class object or a VEPixel Class
object. This value must be a valid point on the
current map. Optional.
offset If the anchor point is a VELatLong object, this
parameter, a VEPixel object, specifies the
anchor point's offset from that latlong position.
Optional.
Remarks
The direction that the info box is placed with respect to the anchor point is handled by Bing Maps.
It is placed to ensure that it does not cover the pin and is within the map boundaries.
You can customize the appearance of an information box with custom HTML in the
VEShape.SetTitle Method and VEShape.SetDescription Method, as well as set styles for the
information box in the VEMap.ClearInfoBoxStyles Method and VEMap.SetDefaultInfoBoxStyles
Method.
At least one of the shape's VEShape.GetTitle Method, VEShape.GetDescription Method,
VEShape.GetMoreInfoURL Method or VEShape.GetPhotoURL Method must return a non-zero-
length value, otherwise this method does not display any information box about the shape.
Example
VirtualEarthSDK#26
See Also
VEMap.HideInfoBox Method
VEMap.ShowMessage Method
Displays the specified message in a dialog box on the map.
Syntax
203
VEMap.ShowMessage(message);
Parameters
Parameter Description
message The message you want to display on the map
Caution The message box is an HTML element that can have JavaScript embedded in it. Verify
the input value before executing it on your web page.
Remarks
The message dialog box appears for 10 seconds, and then disappears automatically.
Example
VirtualEarthSDK#37
VEMap.ShowMiniMap Method
Displays the mini map at the specified offset from the top left corner of the screen.
Syntax
VEMap.ShowMiniMap(xoffset, yoffset, size);
Parameters
Parameter Description
xoffset The x coordinate offset as a number of pixels
from the top left corner of the screen. Optional
yoffset The y coordinate offset as a number of pixels
from the top left corner of the screen. Optional
size A VEMiniMapSize Enumeration value that
specifies the mini map size. Optional. Default
value is VEMiniMapSize.Small.
Example
VirtualEarthSDK#24
See Also
VEMap.HideMiniMap Method
VEMap.ShowScalebar Method
Displays the scale bar on the map.
Syntax
204
VEMap.ShowScalebar();
Remarks
By default the scale bar is displayed on the map.
Example
VirtualEarthSDK#55
See Also
VEMap.HideScalebar Method
VEMap.ShowTileLayer Method
Shows a tile layer on the map.
Syntax
VEMap.ShowTileLayer(layerID);
Parameters
Parameter Description
layerID The ID of the layer to be shown.
Remarks
If a layer's VETileSourceSpecification Class object has been changed, the changes will take
effect each time it is shown.
Example
VirtualEarthSDK#9
See Also
VEMap.DeleteTileLayer Method
VEMap.HideTileLayer Method
VEMap.ShowTrafficLegend Method
Displays the traffic legend.
Syntax
VEMap.ShowTrafficLegend(x, y)
Parameters
Parameter Description
x The x-coordinate of the top-left corner of the
205
Parameter Description
legend. Optional.
y The y-coordinate of the top-left corner of the
legend. Optional.
Remarks
If x and y are not specified, the legend is displayed at the bottom-right of the copyright. If the
legend is already visible, this method moves the legend to the specified coordinates, or to the
bottom-right if x and y are not specified.
Example
VirtualEarthSDK#13
See Also
VEMap.HideTrafficLegend Method
VEMap.SetTrafficLegendText Method
VEMap.StartContinuousPan Method
Moves the map in the specified direction until the VEMap.EndContinuousPan Method is called.
Syntax
VEMap.StartContinuousPan(x, y);
Parameters
Parameter Description
x The speed, as a percentage of the fastest
speed, to move the map in the x direction.
Positive numbers move the map to the right,
while negative numbers move the map to the
left
y The speed, as a percentage of the fastest
speed, to move the map in the y direction.
Positive numbers move the map down, while
negative numbers move the map up
Remarks
The StartContinuousPan method moves the map in the direction specified by the two variables.
The direction is specified by the relative speed of the two parameters. For example, the following
code moves the map as fast as the client computer can to the right:
map.StartContinuousPan(100,0);
206
The following code moves the map to the right at 30% of the fastest speed and up at 20% of the
fastest speed:
map.StartContinuousPan(30,-20);
To stop panning the map, call the VEMap.EndContinuousPan Method.
Example
VirtualEarthSDK#14
VEMap.ZoomIn Method
Increases the map zoom level by 1.
Syntax
VEMap.ZoomIn();
Remarks
Valid values range from 1 through 19. If you call the ZoomIn method when the current zoom level
is already at the maximum, the zoom level does not change.
Example
VirtualEarthSDK#34
VEMap.ZoomOut Method
Decreases the map zoom level by 1.
Syntax
VEMap.ZoomOut();
Remarks
Valid values range from 1 through 19. If you call the ZoomOut method when the current zoom
level is already at the minimum, the zoom level does not change.
Example
VirtualEarthSDK#34
VEMap Properties
The properties of the VEMap class are listed here. For a complete list of VEMap class members,
see the VEMap Class topic.
Public Properties
Name Description
VEMap.onLoadMap Property Specifies the function to call when the map is
first loaded.
207
See Also
VEMap Events
VEMap Methods
VEMap.onLoadMap Property
Specifies the function to call when the map is first loaded.
Syntax
VEMap.onLoadMap = value
Remarks
You must set the onLoadMap property before calling the VEMap.LoadMap Method.
VEMapMode Enumeration
An enumeration of map modes.
Syntax
VEMapMode{ Mode2D Mode3D }
Members
Member Description
Mode2
D
Displays the map in the traditional two dimensions
Mode3
D
Loads the Bing Maps 3D control, displays the map in three dimensions, and displays
the 3D navigation control
On November 2, 2010, the end-of-life was announced for the 3D control.
Effective December 1, 2011, the 3D control will no longer function. The full
announcement is found at:
http://www.bing.com/community/site_blogs/b/maps/archive/2010/11/02/change
s-to-bird-s-eye-and-3d-maps.aspx
Remarks
This enumeration is used with the VEMap.SetMapMode Method to specify the map mode. It is
also returned by the VEMap.GetMapMode Method and the VEMap.oninitmode Event.
208
VEMapOptions Class
Contains the options to set when loading the map.
Constructor
Name Description
VEMapOptions Constructor Initializes a new instance of a VEMapOptions
object.
Public Properties
Name Description
VEMapOptions.BirdseyeOrientation Property A VEOrientation Enumeration value indicating
the orientation of the bird's eye map. The
default value is VEOrientation.North.
VEMapOptions.DashboardColor Property A String that specifies whether the map
dashboard, or navigation control, is colored
blue or black. Valid values are ―blue‖ or ―black‖.
The default value is ―blue‖.
VEMapOptions.EnableBirdseye Property A Boolean value specifying whether or not to
enable the Birdseye map style in the map
control. The default value is true.
VEMapOptions.EnableClickableLogo Property A Boolean value indicating whether the BingTM
logo on the map is clickable. The default value
is false.
VEMapOptions.EnableDashboardLabels
Property
A Boolean value that specifies whether or not
labels appear on the map when a user clicks
the Aerial or Birdseye map style buttons on the
map control dashboard. The default value is
true.
VEMapOptions.EnableSearchLogo Property A Boolean value indicating whether to enable
the BingTM
hovering search logo on the map.
The default value is false.
VEMapOptions.LoadBaseTiles Property A Boolean value indicating whether or not to
load the base map tiles. The default value is
true.
209
Name Description
VEMapOptions.UseEnhancedRoadStyle
Property
On July 6, 2011, the new enhanced
road map style in use on
http://www.bing.com/maps became the
default and only road style available for
all Bing Maps APIs. The
UseEnhancedRoadStyle property is
deprecated.
A Boolean value indicating whether to use the
enhanced road map style.
Example
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title></title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<script type="text/javascript"
src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.3"></script>
<script type="text/javascript">
var map = null;
function GetMap()
{
map = new VEMap('myMap');
mapOptions = new VEMapOptions();
mapOptions.DashboardColor = "black";
mapOptions.EnableSearchLogo = true;
210
map.LoadMap(
new VELatLong(47.6, -122.3), // center
10, // zoom level
VEMapStyle.Road, // map style
false, // fixed map
VEMapMode.Mode2D, // map mode
true, // show map mode switch
0, // tile buffer
mapOptions// options
);
}
</script>
</head>
<body onload="GetMap();" style="font-family: Arial">
<div id='myMap' style="position: relative; width: 800px; height: 400px;">
</div>
</body>
</html>
See Also
VEMap.LoadMap Method
VEMapOptions Constructor
Initializes a new instance of the VEMapOptions Class.
Syntax
var x = new VEMapOptions();
VEMapOptions Properties
The properties of the VEMapOptions class are listed here. For a complete list of VEMapOptions
class members, see the VEMapOptions Class topic.
211
Public Properties
Name Description
VEMapOptions.BirdseyeOrientation Property A VEOrientation Enumeration value indicating
the orientation of the bird's eye map. The
default value is VEOrientation.North.
VEMapOptions.DashboardColor Property A String that specifies whether the map
dashboard, or navigation control, is colored
blue or black. Valid values are ―blue‖ or ―black‖.
The default value is ―blue‖.
VEMapOptions.EnableBirdseye Property A Boolean value specifying whether or not to
enable the Birdseye map style in the map
control. The default value is true.
VEMapOptions.EnableClickableLogo Property A Boolean value indicating whether the BingTM
logo on the map is clickable. The default value
is false.
VEMapOptions.EnableDashboardLabels
Property
A Boolean value that specifies whether or not
labels appear on the map when a user clicks
the Aerial or Birdseye map style buttons on the
map control dashboard. The default value is
true.
VEMapOptions.EnableSearchLogo Property A Boolean value indicating whether to enable
the BingTM
hovering search logo on the map.
The default value is false.
VEMapOptions.LoadBaseTiles Property A Boolean value indicating whether or not to
load the base map tiles. The default value is
true.
VEMapOptions.UseEnhancedRoadStyle
Property
On July 6, 2011, the new enhanced
road map style in use on
http://www.bing.com/maps became the
default and only road style available for
all Bing Maps APIs. The
UseEnhancedRoadStyle property is
deprecated.
A Boolean value indicating whether to use the
enhanced road map style.
212
See Also
VEMapOptions Class
VEMap.LoadMap Method
VEMapOptions.BirdseyeOrientation Property
A VEOrientation Enumeration value indicating the orientation of the bird's eye map. The default
value is VEOrientation.North.
Syntax
VEMapOptions.BirdseyeOrientation = value;
VEMapOptions.DashboardColor Property
A String that specifies whether the map dashboard, or navigation control, is colored blue or black.
Valid values are ―blue‖ or ―black‖. The default value is ―blue‖.
Syntax
VEMapOptions.DashboardColor = value;
Remarks
The dashboard color can only be changed if the size of the dashboard is set to
VEDashboardSize.Normal.
VEMapOptions.EnableBirdseye Property
A Boolean value specifying whether or not to enable the Birdseye map style in the map control.
The default value is true.
Syntax
VEMapOptions.EnableBirdseye = bool;
Remarks
If the VEMapOptions.EnableBirdseye property is set to false, then:
The Birdseye map style button normally found in the map control dashboard will be absent.
Keyboard shortcuts used to show the Birdseye map style in 2D and 3D will not function.
The VEMap.SetMapStyle Method will not change the map style if VEMapStyle.Birdseye or
VEMapStyle.BirdseyeHybrid are passed as values.
The VEMap.SetBirdseyeOrientation Method, the VEMap.SetBirdseyeScene Method, and the
VEMap.Show3DBirdseye Method will do nothing.
The VEMap.IsBirdseyeAvailable Method will return false at all zoom levels.
See Also
VEMapStyle Enumeration
VEMap.SetMapStyle Method
VEMap.Show3DBirdseye Method
213
VEMapOptions.EnableClickableLogo Property
A Boolean value indicating whether the BingTM
logo on the map is clickable. The default value is
false.
Syntax
VEMapOptions.EnableClickableLogo = value;
Remarks
If the EnableClickableLogo property is set to true, the http://www.bing.com/maps web page is
opened when the Bing logo is clicked. The Bing Maps site map view is set to the zoom level and
area of interest of the referring site map view.
VEMapOptions.EnableDashboardLabels Property
A Boolean value that specifies whether or not labels appear on the map when a user clicks the
Aerial or Birdseye map style buttons on the map control dashboard. The default value is true.
Syntax
VEMapOptions.EnableDashboardLabels = bool;
Remarks
Setting the map style supersedes the EnableDashboardLabels setting. For example, if the
VEMapStyle.Aerial or VEMapStyle.Birdseye map styles are set for the Style parameter in the
VEMap.LoadMap call, labels will not appear on the map.
If the current map style is VEMapStyle.Birdseye or VEMapStyle.BirdseyeHybrid, then the
EnableDashboardLabels property is ignored when the VEMap.SetBirdseyeScene Method is
called.
See Also
VEMap.GetMapStyle Method
VEMapStyle Enumeration
VEMapOptions Class
VEMapOptions.EnableSearchLogo Property
A Boolean value indicating whether to enable the BingTM
hovering search logo on the map. The
default value is false.
Syntax
VEMapOptions.EnableSearchLogo = value;
Remarks
If the EnableSearchLogo property is set to true, a Bing search box appears when the user
hovers over the Bing logo on the map.
VEMapOptions.LoadBaseTiles Property
A Boolean value indicating whether or not to load the base map tiles. The default value is true.
214
Syntax
VEMapOptions.LoadBaseTiles = value;
See Also
VEMap.HideScalebar Method
VEMap.HideDashboard Method
VEMapOptions.UseEnhancedRoadStyle Property
On July 6, 2011, the new enhanced road map style in use on http://www.bing.com/maps
became the default and only road style available for all Bing Maps APIs. The
UseEnhancedRoadStyle property is deprecated.
A Boolean value indicating whether to use the enhanced road map style.
Syntax
VEMapOptions.UseEnhancedRoadStyle = value;
VEMapStyle Enumeration
An enumeration of map styles.
On July 6, 2011, the new enhanced road map style in use on http://www.bing.com/maps
became the default and only road style available for all Bing Maps APIs.
Syntax
VEMapStyle{ Road Shaded Aerial Hybrid Oblique Birdseye BirdseyeHybrid }
Members
Member Description
Road The road map style
Shaded The shaded map style, which is a road map
with shaded contours.
Aerial The aerial map style
Hybrid The hybrid map style, which is an aerial map
with a label overlay
Oblique The oblique map style, which is the same as
215
Member Description
Birdseye
Birdseye The bird's eye (oblique-angle) imagery map
style
BirdseyeHybrid The bird's eye hybrid map style, which is a
bird's eye map with a label overlay
Remarks
Shaded maps are not supported in all regions.
If you would like to see either the Birdseye or BirdseyeHybrid map style in
VEMapMode.Mode3D, then you will need to use the VEMap.Show3DBirdseye Method.
See Also
VEMap.GetMapStyle Method
VEMap.SetMapStyle Method
VEMap.LoadMap Method
VEMapMode Enumeration
VEMapViewSpecification Class
Contains the information about a map view. The map view includes the center point and zoom
level of the map. If the map is in 3D mode, the map view also includes the altitude, pitch, and
heading of the view.
A VEMapViewSpecification object is passed to the VEMap.SetMapView Method.
Constructor
Name Description
VEMapViewSpecification Constructor Initializes a new instance of the
VEMapViewSpecification object.
VEMapViewSpecification Constructor
Initializes a new instance of the VEMapViewSpecification class.
Syntax
var x = new VEMapViewSpecification(center, zoom, altitude, pitch, heading);
216
Parameters
Parameter Description
center A VELatLong Class object that specifies the
center point of the map. Required.
zoom An integer that represents the zoom level of the
map. Required if VEMapMode Enumeration is
set to Mode2D. Ignored if VEMapMode is set to
Mode3D and the altitude parameter is
specified.
altitude If VEMapMode Enumeration is set to Mode3D,
the altitude of the view, in meters above the
geoid.
pitch If VEMapMode Enumeration is set to Mode3D,
the pitch of the view, in degrees. A value of –90
is straight down and a value of 0 is level.
heading If VEMapMode Enumeration is set to Mode3D,
the heading of the view, in compass degrees. A
value of 0 or 360 is true north.
Remarks
VEMatchCode Enumeration
A match code value as received from the geocoder.
Syntax
VEMatchCode{ None Good Ambiguous UpHierarchy Modified }
Members
Member Description
None No match was found
Good The match was good
Ambiguous The match was ambiguous
UpHierarchy The match was found by a broader search
217
Member Description
Modified The match was found, but to a modified place
See Also
VEPlace.MatchCode Property
VEMatchConfidence Enumeration
A match confidence value as received from the geocoder.
Syntax
VEMatchConfidence{ High Medium Low }
Members
Member Description
High The confidence of a match is high
Medium The confidence of a match is medium
Low The confidence of a match is low
See Also
VEPlace.MatchConfidence Property
VEMiniMapSize Enumeration
This enumeration represents the size of the mini map.
Syntax
VEMiniMapSize{ Small Large }
Members
Member Description
Small This represents a small mini map.
218
Member Description
Large This represents a large mini map.
See Also
VEMap.ShowMiniMap Method
VEModelFormat Enumeration
An enumeration of 3D model formats.
Syntax
VEModelFormat{ OBJ }
Members
Member Description
OBJ The 3D model data is in Wavefront OBJ format.
Remarks
Bing Maps supports the import of OBJ data files where the following items are true:
The file is a valid OBJ ASCII (.obj) file.
Any MTL or other texture file names referenced within the OBJ file do not contain spaces.
Any references to MTL or other texture files are located in the same base location or working
directory or in a subfolder of the base location or working directory as the OBJ file. For
example, if the VEModelSourceSpecification.ModelSource Property is
"http://www.mysite.com/models/house.obj" and the file "house.obj" references "house.mtl",
then Bing Maps expects the file "house.mtl" to be found at
"http://www.mysite.com/models/house.mtl" and the file reference "house_textures/roof.jpg" to
be found at "http://www.mysite.com/models/house_textures/roof.jpg".
The file contains BMP, GIF, JPG, PNG, and TIFF texture formats.
Additionally, the following OBJ keywords are supported:
mtllib
usemtl
vn
v
vt
219
f
And the following MTL statements are supported:
D
newmtl
map_Ka
map_Kd
Ka
Kd
Note Bing Maps does not support advanced OBJ features, including curved surfaces. Materials
support is limited to ambient and diffuse color and texture. More complex materials such as those
that use bump-mapping are not supported. Unsupported features found in a 3D model file are
ignored.
To ensure that your OBJ model renders properly in Bing Maps 3D, turn on the "Triangulate faces"
export option in the 3D authoring application that you use.
See Also
VEMap.Import3DModel Method
VEModelOrientation Class
Represents the orientation of a 3D model on the map.
Constructor
Name Description
VEModelOrientation Constructor Initializes a new instance of a
VEModelOrientation object.
Public Properties
Name Description
VEModelOrientation.Heading Property A floating-point value specifying in decimal
degrees the counter-clockwise rotation of the
3D model about the z-axis, looking along the
positive z-axis away from the origin.
VEModelOrientation.Roll Property A floating-point value specifying in decimal
degrees the counter-clockwise rotation of the
3D model about the y-axis, looking along the
220
Name Description
positive y-axis away from the origin.
VEModelOrientation.Tilt Property A floating-point value specifying in decimal
degrees the counter-clockwise rotation of the
3D model about the x-axis, looking along the
positive x-axis away from the origin.
Remarks
The Heading, Roll, and Tilt property value range is -360 to 360.
See Also
VEMap.Import3DModel Method
VEModelOrientation Constructor
Initializes a new instance of the VEModelOrientation Class.
Syntax
var x = new VEModelOrientation(heading, tilt, roll);
Parameters
Parameter Description
heading A floating-point value specifying in decimal
degrees the counter-clockwise rotation of the
3D model about the z-axis, looking along the
positive z-axis away from the origin. Optional.
The default value is 0.
tilt A floating-point value specifying in decimal
degrees the counter-clockwise rotation of the
3D model about the x-axis, looking along the
positive x-axis away from the origin. Optional.
The default value is 0.
roll A floating-point value specifying in decimal
degrees the counter-clockwise rotation of the
3D model about the y-axis, looking along the
positive y-axis away from the origin. Optional.
The default value is 0.
221
VEModelOrientation Properties
The properties of the VEModelOrientation class are listed here. For a complete list of
VEModelOrientation class members, see the VEModelOrientation Class topic.
Public Properties
Name Description
VEModelOrientation.Heading Property A floating-point value specifying in decimal
degrees the counter-clockwise rotation of the
3D model about the z-axis, looking along the
positive z-axis away from the origin.
VEModelOrientation.Roll Property A floating-point value specifying in decimal
degrees the counter-clockwise rotation of the
3D model about the y-axis, looking along the
positive y-axis away from the origin.
VEModelOrientation.Tilt Property A floating-point value specifying in decimal
degrees the counter-clockwise rotation of the
3D model about the x-axis, looking along the
positive x-axis away from the origin.
VEModelOrientation.Heading Property
A floating-point value specifying in decimal degrees the counter-clockwise rotation of the 3D
model about the z-axis, looking along the positive z-axis away from the origin.
Syntax
VEModelOrientation.Heading = value;
Remarks
The Heading property value range is from -360 to 360. An increase in the value of the Heading
property represents a counter-clockwise rotation around the z-axis, looking along the z-axis away
from the origin.
VEModelOrientation.Roll Property
A floating-point value specifying in decimal degrees the counter-clockwise rotation of the 3D
model about the y-axis, looking along the positive y-axis away from the origin.
Syntax
VEModelOrientation.Roll = value;
222
Remarks
The Roll property value range is from -360 to 360. An increase in the value of the Roll property
represents a counter-clockwise rotation around the y-axis, looking along the y-axis away from the
origin.
VEModelOrientation.Tilt Property
A floating-point value specifying in decimal degrees the counter-clockwise rotation of the 3D
model about the x-axis, looking along the positive x-axis away from the origin.
Syntax
VEModelOrientation.Tilt = value;
Remarks
The Tilt property value range is from -360 to 360. An increase in the value of the Tilt property
represents a counter-clockwise rotation around the x-axis, looking along the x-axis away from the
origin.
VEModelScale Class
Represents the scale of a 3D model with respect to the map.
Constructor
Name Description
VEModelScale Constructor Initializes a new instance of a VEModelScale
object.
Public Properties
Name Description
VEModelScale.X Property A floating-point value specifying the x-axis
scale factor of a 3D model.
VEModelScale.Y Property A floating-point value specifying the y-axis
scale factor of a 3D model.
VEModelScale.Z Property A floating-point value specifying the z-axis
scale factor of a 3D model.
223
Remarks
The model scale can be set to a specific unit of measurement by passing the VEModelScale
Constructor a VEModelScaleUnit Enumeration value. Alternatively, each VEModelScale property
can be set to a VEModelScaleUnit Enumeration value.
By default one scale unit is equal to one meter. This can be modified by setting the
VEModelScale properties to the appropriate VEModelScaleUnit Enumeration value.
Using large scale values may prevent the 3D model from rendering.
See Also
VEMap.Import3DModel Method
VEModelScale Constructor
Initializes a new instance of the VEModelScale Class.
Syntax
var x = new VEModelScale(x, y, z);
Parameters
Parameter Description
x A floating-point value specifying the x-axis
scale factor of a 3D model. Optional. The
default value is 1.
y A floating-point value specifying the y-axis
scale factor of a 3D model. Optional. The
default value is 1.
z A floating-point value specifying the z-axis
scale factor of a 3D model. Optional. The
default value is 1.
Remarks
If a single parameter is passed to the VEModelScale constructor, then the scale factor for the x-
axis, y-axis, and z-axis are set to that value. A VEModelScaleUnit Enumeration value can be
passed to set the model scale factors to a specific unit of measurement.
To set the model scale to a specific unit of measurement, set the parameters of the
VEModelScale constructor to one of the VEModelScaleUnit Enumeration values.
224
VEModelScale Properties
The properties of the VEModelScale class are listed here. For a complete list of VEModelScale
class members, see the VEModelScale Class topic.
Public Properties
Name Description
VEModelScale.X Property A floating-point value specifying the x-axis
scale factor of a 3D model.
VEModelScale.Y Property A floating-point value specifying the y-axis
scale factor of a 3D model.
VEModelScale.Z Property A floating-point value specifying the z-axis
scale factor of a 3D model.
VEModelScale.X Property
A floating-point value specifying the x-axis scale factor of a 3D model.
Syntax
VEModelScale.X = value;
Remarks
To set the scale to a specific unit of measurement, use the VEModelScaleUnit Enumeration.
VEModelScale.Y Property
A floating-point value specifying the y-axis scale factor of a 3D model.
Syntax
VEModelScale.Y = value;
Remarks
To set the scale to a specific unit of measurement, use the VEModelScaleUnit Enumeration.
VEModelScale.Z Property
A floating-point value specifying the z-axis scale factor of a 3D model.
Syntax
VEModelScale.Z = value;
Remarks
To set the scale to a specific unit of measurement, use the VEModelScaleUnit Enumeration.
225
VEModelScaleUnit Enumeration
An enumeration of scale units.
Syntax
VEModelScaleUnit { Inches, Feet, Yards, Millimeters, Centimeters, Meters }
Members
Member Description
Inches Scale is defined in inches.
Feet Scale is defined in feet.
Yards Scale is defined in yards.
Millimeters Scale is defined in millimeters.
Centimeters Scale is defined in centimeters.
Meters Scale is defined in meters.
See Also
VEModelScale Class
VEMap.Import3DModel Method
VEModelSourceSpecification Class
Contains the specification for importing a 3D model onto the map.
Constructor
Name Description
VEModelSourceSpecification Constructor Initializes a new instance of a
VEModelSourceSpecification object.
Public Properties
226
Name Description
VEModelSourceSpecification.Format Property A VEModelFormat Enumeration value
specifying the data format of the 3D model
being imported.
VEModelSourceSpecification.Layer Property A VEShapeLayer Class specifying the shape
layer into which the 3D model will be imported.
VEModelSourceSpecification.ModelSource
Property
A string specifying the URL of the 3D model
data file.
See Also
VEMap.Import3DModel Method
VEModelSourceSpecification Constructor
Initializes a new instance of the VEModelSourceSpecification Class.
Syntax
var x = new VEModelSourceSpecification(modelFormat, modelSource, layer);
Parameters
Parameter Description
modelFormat A VEModelFormat Enumeration value
specifying the data format of the 3D model
being imported. Optional. The default value is
VEModelFormat.OBJ.
modelSource A string specifying the URL of the 3D model
data file. Required.
layer A VEShapeLayer Class specifying the shape
layer into which the 3D model will be imported.
Optional. If this parameter is not specified, the
3D model is added to the base layer.
VEModelSourceSpecification Properties
The properties of the VEModelSourceSpecification class are listed here. For a complete list of
VEModelSourceSpecification class members, see the VEModelSourceSpecification Class
topic.
227
Public Properties
Name Description
VEModelSourceSpecification.Format Property A VEModelFormat Enumeration value
specifying the data format of the 3D model
being imported.
VEModelSourceSpecification.Layer Property A VEShapeLayer Class specifying the shape
layer into which the 3D model will be imported.
VEModelSourceSpecification.ModelSource
Property
A string specifying the URL of the 3D model
data file.
VEModelSourceSpecification.Format Property
A VEModelFormat Enumeration value specifying the data format of the 3D model being imported.
Syntax
VEModelSourceSpecification.Format = value;
VEModelSourceSpecification.Layer Property
A VEShapeLayer Class specifying the shape layer into which the 3D model will be imported.
Syntax
VEModelSourceSpecification.Layer = value;
VEModelSourceSpecification.ModelSource Property
A string specifying the URL of the 3D model data file.
Syntax
VEModelSourceSpecification.ModelSource = value;
VEModelStatusCode Enumeration
An enumeration of status codes returned in callback of the VEMap.Import3DModel Method.
Syntax
VEModelStatusCode{ Success, InvalidURL, Failed }
Members
228
Member Description
Success The 3D model was successfully loaded.
Failed The 3D model failed to load. The URL may be
invalid or the file format may be incorrect.
VEOrientation Enumeration
An enumeration of available directional views for a bird's eye image.
Syntax
VEOrientation { North South East West }
Members
Member Description
North The image was taken looking toward the north.
South The image was taken looking toward the south.
East The image was taken looking toward the east.
West The image was taken looking toward the west.
Remarks
For more information about bird's eye images, see VEBirdseyeScene Class and Working with
Bird's Eye Images.
See Also
VEMap.SetBirdseyeScene(veLatLong, orientation, zoomLevel, callback) Method
VEBirdseyeScene.GetOrientation Method
VEPixel Class
Contains the information about a map pixel.
Constructor
229
Name Description
VEPixel Constructor Initializes a new instance of the VEPixel object.
Public Properties
Name Description
VEPixel.x Property Gets or sets the pixel's x coordinate.
VEPixel.y Property Gets or sets the pixel's y coordinate.
See Also
VEMap Class
VEPixel Constructor
This constructor instantiates a pixel relative to the top left corner of the current map window.
Syntax
var pixel = new VEPixel(x, y);
Parameters
Parameter Description
x The pixel's x coordinate.
y The pixel's y coordinate.
See Also
VEPixel.x Property
VEPixel.y Property
VEPixel Properties
The properties of the VEPixel class are listed here. For a complete list of VEPixel class
members, see the VEPixel Class topic.
Public Properties
230
Name Description
VEPixel.x Property Gets or sets the pixel's x coordinate.
VEPixel.y Property Gets or sets the pixel's y coordinate.
VEPixel.x Property
Gets or sets the pixel's x coordinate.
Syntax
VEPixel.x = value
Remarks
See Also
VEPixel.y Property
VEPixel.y Property
Gets or sets the pixel's y coordinate.
Syntax
VEPixel.y = value
Remarks
See Also
VEPixel.x Property
VEPlace Class
A found result returned from a location search.
Public Properties
Name Description
VEPlace.LatLong Property Gets a VELatLong Class object that represents
the best location of the found result.
VEPlace.Locations Property An array of VEGeocodeLocation Class objects
specifying all of the possible match results
returned by the geocoder for this place.
VEPlace.Name Property Gets the String object that represents the
unambiguous name for the Bing Maps location.
231
Name Description
VEPlace.MatchCode Property A VEMatchCode Enumeration value specifying
the match code from the geocoder. This property
value is only valid for where-only searches.
VEPlace.MatchConfidence Property A VEMatchConfidence Enumeration value
specifying the match confidence from the
geocoder. This property value is only valid for
where-only searches.
VEPlace.Precision Property A VELocationPrecision Enumeration value
specifying the match precision from the geocoder
for the best result, which is found in the
VEPlace.LatLong property.
Remarks
If the Precision property value is VELocationPrecision.Interpolated, the VEPlace.LatLong
property contains a result found using interpolated geocoding. If the Precision property value is
VELocationPrecision.Rooftop, the VEPlace.LatLong property contains a result found using
rooftop geocoding.
The VEMap.Find Method returns an array of VEPlace objects in the callback. However, the
VEPlace class has no constructor, so it cannot be created independently of a VEMap.Find
method call. The VEMap.Find method where parameter accepts a VEPlace object reference.
VEPlace Properties
The properties of the VEPlace class are listed here. For a complete list of VEPlace class
members, see the VEPlace Class topic.
Public Properties
Name Description
VEPlace.LatLong Property Gets or sets a VELatLong Class object that
represents the location of the found result.
VEPlace.Locations Property An array of VEGeocodeLocation Class objects
specifying all of the possible match results
returned by the geocoder for this place.
VEPlace.Name Property Gets the String object that represents the
unambiguous name for the Bing Maps location.
VEPlace.MatchCode Property A VEMatchCode Enumeration value specifying
232
Name Description
the match code from the geocoder. This property
value is only valid for where-only searches.
VEPlace.MatchConfidence Property A VEMatchConfidence Enumeration value
specifying the match confidence from the
geocoder. This property value is only valid for
where-only searches.
VEPlace.Precision Property A VELocationPrecision Enumeration value
specifying the match precision from the geocoder
for the best result, which is found in the
VEPlace.LatLong property.
See Also
VEMap.Find Method
VEPlace.LatLong Property
Gets or sets a VELatLong Class object that represents the location of the found result.
Syntax
VEPlace.LatLong = value
Remarks
See Also
VEPlace.Name Property
VEPlace.Locations Property
An array of VEGeocodeLocation Class objects specifying all of the possible match results
returned by the geocoder for this place.
Syntax
VEPlace.Locations
See Also
VEPlace.Precision Property
VEPlace.MatchCode Property
A VEMatchCode Enumeration value specifying the match code from the geocoder.
Syntax
VEPlace.MatchCode = value;
233
Remarks
This property value is only valid for where-only searches. It is a bitmask of VEMatchCode values.
See Also
VEPlace.MatchConfidence Property
VEPlace.MatchConfidence Property
A VEMatchConfidence Enumeration value specifying the match confidence from the geocoder.
Syntax
VEPlace.MatchConfidence = value;
Remarks
This property value is only valid for where-only searches.
See Also
VEPlace.MatchCode Property
VEPlace.Name Property
Gets the String object that represents the unambiguous name for the Bing Maps location.
Syntax
VEPlace.Name = value
Remarks
The name could be an address, city, state, zip, a city and state, a state, a country, or one of many
other types of locations.
See Also
VEPlace.LatLong Property
VEPlace.Precision Property
A VELocationPrecision Enumeration value specifying the match precision from the geocoder for
the best result, which is found in the VEPlace.LatLong Property.
Syntax
VEPlace.Precision
See Also
VEPlace.Locations Property
VEPrintOptions Class
Contains the print options of the map.
234
Constructor
Name Description
VEPrintOptions Constructor Initializes a new instance of a VEPrintOptions
object.
Public Properties
Name Description
VEPrintOptions.EnablePrinting Property A Boolean value specifying whether or not to
make the map printable.
See Also
VEMap.SetPrintOptions Method
VEPrintOptions Constructor
Initializes a new instance of the VEPrintOptions class.
Syntax
var x = new VEPrintOptions(enablePrinting);
Parameters
Parameter Description
enablePrinting A Boolean value that represents whether or not
to make the map printable. Required.
Remarks
Setting the enablePrinting parameter to a value of true ensures that all of the map control items
print properly. However, this may cause a decrease in the performance of the map control, so
you should only set this parameter to true when you are ready to print.
See Also
VEPrintOptions.EnablePrinting Property
VEMap.SetPrintOptions Method
235
VEPrintOptions Properties
The properties of the VEPrintOptions class are listed here. For a complete list of
VEPrintOptions class members, see the VEPrintOptions Class topic.
Public Properties
Name Description
VEPrintOptions.EnablePrinting Property A Boolean value specifying whether or not to
make the map printable.
See Also
VEMap.SetPrintOptions Method
VEPrintOptions.EnablePrinting Property
A Boolean value specifying whether or not to make the map printable.
Syntax
VEPrintOptions.EnablePrinting = bool;
Remarks
The default value for the EnablePrinting property is false.
Setting the EnablePrinting property to a value of true ensures that all of the map control items
print properly. However, this may cause a decrease in the performance of the map control, so
you should only set this property to true when you are ready to print.
See Also
VEPrintOptions Class
VEMap.SetPrintOptions Method
VERoute Class
Contains the route and itinerary information for a generated route. A VERoute object is returned
to the callback when the VEMap.GetDirections Method is called.
Public Properties
Name Description
VERoute.Distance Property A floating-point value that specifies the total
length of the route.
VERoute.RouteLegs Property An array of VERouteLeg Class objects that
specify the intermediate legs of the route.
236
Name Description
VERoute.ShapePoints Property An array of VELatLong Class objects that identify
the shape of the route.
VERoute.Time Property An integer specifying the total elapsed time, in
seconds, to traverse the route.
See Also
VEMap.GetDirections Method
VERoute Properties
The properties of the VERoute class are listed here. For a complete list of VERoute class
members, see the VERoute Class topic.
Public Properties
Name Description
VERoute.Distance Property A floating-point value that specifies the total
length of the route.
VERoute.RouteLegs Property An array of VERouteLeg Class objects that
specify the intermediate legs of the route.
VERoute.ShapePoints Property An array of VELatLong Class objects that identify
the shape of the route.
VERoute.Time Property An integer specifying the total elapsed time, in
seconds, to traverse the route.
See Also
VEMap.GetDirections Method
VERoute.Distance Property
A floating-point value that specifies the total length of the route.
Syntax
VERoute.Distance
See Also
VERoute.Time Property
237
VERoute.RouteLegs Property
An array of VERouteLeg Class objects that specify the intermediate legs of the route.
Syntax
VERoute.RouteLegs
VERoute.ShapePoints Property
An array of VELatLong Class objects that identify the shape of the route.
Syntax
VERoute.ShapePoints
Remarks
The shape points are created for the highest zoom level, which means the closest to the ground.
See Also
VERoute Class
VELatLong Class
VERoute.Time Property
An intege specifying the total elapsed time, in seconds, to traverse the route.
Syntax
VERoute.Time
Return Value
An integer specifying the time, in seconds.
See Also
VERoute.Distance Property
VERouteDeprecated Class
Deprecated. Contains the route and itinerary information for a generated route. A
VERouteDeprecated object is returned to the callback when the VEMap.GetRoute Method is
called. The VEMap.GetRoute method is deprecated. Use VEMap.GetDirections Method instead.
Public Properties
Name Description
VERouteDeprecated.EndLocation Property A VERouteLocation Class object that specifies
the final destination of the route.
238
Name Description
VERouteDeprecated.Itinerary Property A VERouteItineraryDeprecated Class object that
specifies the itinerary (the step-by-step driving
directions) of the route.
VERouteDeprecated.StartLocation Property A VERouteLocation Class object that specifies
the starting point of the route.
Remarks
This class has been deprecated.
VERouteDeprecated Properties
The properties of the VERouteDeprecated class are listed here. For a complete list of
VERouteDeprecated class members, see the VERouteDeprecated Class topic.
Public Properties
Name Description
VERouteDeprecated.EndLocation Property A VERouteLocation Class object that specifies
the final destination of the route.
VERouteDeprecated.Itinerary Property A VERouteItineraryDeprecated Class object that
specifies the itinerary (the step-by-step driving
directions) of the route.
VERouteDeprecated.StartLocation Property A VERouteLocation Class object that specifies
the starting point of the route.
VERouteDeprecated.EndLocation Property
A VERouteLocation Class object that specifies the final destination of the route.
Syntax
VERouteDeprecated.EndLocation
VERouteDeprecated.Itinerary Property
A VERouteItineraryDeprecated Class object that specifies the itinerary (the step-by-step driving
directions) of the route.
Syntax
VERouteDeprecated.Itinerary
239
Remarks
The VERouteItineraryDeprecated.Segments property is an array of VERouteSegment Class
objects. You can use the built-in length property to determine the number of segments in the
array, and the [] operator to specify individual route segments.
VERouteDeprecated.StartLocation Property
A VERouteLocation Class object that specifies the starting point of the route.
Syntax
VERouteDeprecated.StartLocation
VERouteDistanceUnit Enumeration
An enumeration specifying the units used for the route.
Syntax
VERouteDistanceUnit{ Mile Kilometer }
Members
Member Description
Mile The route is shown in units of miles
Kilometer The route is shown in units of kilometers
See Also
VERouteOptions.DistanceUnit Property
VERouteHint Class
Specifies a route itinerary item hint.
Public Properties
Name Description
VERouteHint.Type Property A VERouteHintType Enumeration value
specifying the type of the hint.
VERouteHint.Text Property A string that describes the route itinerary item
240
Name Description
hint.
See Also
VERouteHintType Enumeration
VERouteItineraryItem.Hints Property
VERouteHint Properties
The properties of the VERouteHint class are listed here. For a complete list of VERouteHint
members, see the VERouteHint Class topic.
Public Properties
Name Description
VERouteHint.Type Property A VERouteHintType Enumeration value
specifying the type of the hint.
VERouteHint.Text Property A string that describes the route itinerary item
hint.
See Also
VERouteHintType Enumeration
VERouteItineraryItem.Hints Property
VERouteHint.Type Property
A VERouteHintType Enumeration value specifying the type of the hint.
Syntax
VERouteHint.Type
See Also
VERouteHintType Enumeration
VERouteItineraryItem.Hints Property
VERouteHint.Text Property
A string that describes the route itinerary item hint.
Syntax
VERouteHint.Text
241
Remarks
If the mkt parameter is specified, the Text property is returned in the language of the specified
culture. Any business names found in the string are not changed.
See Also
VERouteItineraryItem.Hints Property
VERouteHintType Enumeration
An enumeration specifying route itinerary item hint types.
Syntax
VERouteHintType { PreviousIntersection NextIntersection Landmark }
Members
Member Description
PreviousIntersection The hint describes the intersection that comes
before the itinerary item.
NextIntersection The hint describes the intersection that comes
after the itinerary item.
Landmark The hint describes a landmark along the road
or near the itinerary item.
See Also
VERouteItineraryItem.Hints Property
VERouteHint.Type Property
VERouteItinerary Class
Contains the itinerary information (step-by-step directions) of a VERoute Class object.
Public Properties
Name Description
VERouteItinerary.Items Property An array of VERouteItineraryItem Class objects
specifying the step-by-step directions for the
route.
242
VERouteItinerary Properties
The properties of the VERouteItinerary class are listed here. For a complete list of
VERouteItinerary class members, see the VERouteItinerary Class topic.
Public Properties
Name Description
VERouteItinerary.Items Property An array of VERouteItineraryItem Class objects
specifying the step-by-step directions for the
route.
VERouteItinerary.Items Property
An array of VERouteItineraryItem Class objects specifying the step-by-step directions for the
route.
Syntax
VERouteItineraryItem.Items = value;
VERouteItineraryDeprecated Class
Deprecated. Contains the itinerary information (step-by-step directions) of a VERouteDeprecated
Class object.
Public Properties
Name Description
VERouteItineraryDeprecated.Distance
Property
The total distance of the route.
VERouteItineraryDeprecated.DistanceUnit
Property
A VEDistanceUnit Enumeration that defines the
units (miles or kilometers) used in the route.
VERouteItineraryDeprecated.RouteType
Property
A VERouteType Enumeration that defines the
type of the route.
VERouteItineraryDeprecated.Segments
Property
An array of VERouteSegment Class objects,
which define each segment of the total route.
VERouteItineraryDeprecated.Time Property The total estimated driving time of the route.
243
VERouteItineraryDeprecated Properties
The properties of the VERouteDeprecated class are listed here. For a complete list of
VERouteDeprecated class members, see the VERouteDeprecated Class topic.
Public Properties
Name Description
VERouteItineraryDeprecated.Distance
Property
The total distance of the route.
VERouteItineraryDeprecated.DistanceUnit
Property
A VEDistanceUnit Enumeration that defines the
units (miles or kilometers) used in the route.
VERouteItineraryDeprecated.RouteType
Property
A VERouteType Enumeration that defines the
type of the route.
VERouteItineraryDeprecated.Segments
Property
An array of VERouteSegment Class objects,
which define each segment of the total route.
VERouteItineraryDeprecated.Time Property The total estimated driving time of the route.
VERouteItineraryDeprecated.Distance Property
The total distance of the route.
Syntax
VERouteItineraryDeprecated.Distance
VERouteItineraryDeprecated.DistanceUnit Property
A VEDistanceUnit Enumeration object that defines the units (miles or kilometers) used in the
route.
Syntax
VERouteItineraryDeprecated.DistanceUnit
VERouteItineraryDeprecated.RouteType Property
A VERouteType Enumeration that defines the type of the route.
Syntax
VERouteItineraryDeprecated.RouteType
VERouteItineraryDeprecated.Segments Property
An array of VERouteSegment Class objects, which define each segment of the total route.
244
Syntax
VERouteItineraryDeprecated.Segments
Remarks
The VERouteItineraryDeprecated object contains an array of VERouteSegment Class objects.
You can use the built-in length property to determine the number of segments in the array, and
the [] operator to specify individual route segments.
VERouteItineraryDeprecated.Time Property
The total estimated driving time of the route.
Syntax
VERouteItineraryDeprecated.Time
Remarks
The time is returned as a formatted string that includes units. For example, if the time is 23
minutes, the Time property contains the string "23 Minutes".
VERouteItineraryItem Class
Specifies a step in the step-by-step directions of a route.
Public Properties
Property Description
VERouteItineraryItem.Distance Property A floating-point number specifying the distance
of the step
VERouteItineraryItem.LatLong Property A VELatLong Class object specifying the
position of the step
VERouteItineraryItem.Shape Property A VEShape Class object specifying the shape
of the step
VERouteItineraryItem.Text Property A String specifying the description of the step
VERouteItineraryItem.Time Property An integer specifying the total elapsed time, in
seconds, to traverse the route itinerary step.
VERouteItineraryItem.Warnings Property An array of VERouteWarning Class items that
correspond to the itinerary item.
VERouteItineraryItem.Hints Property An array of VERouteHint Class items that
correspond to the itinerary item.
245
See Also
VERouteItinerary Class
VERouteItineraryItem Properties
The properties of the VERouteItineraryItem class are listed here. For a complete list of
VERouteItineraryItem class members, see the VERouteItineraryItem Class topic.
Public Properties
Property Description
VERouteItineraryItem.Distance Property A floating-point number specifying the distance
of the step
VERouteItineraryItem.LatLong Property A VELatLong Class object specifying the
position of the step
VERouteItineraryItem.Shape Property A VEShape Class object specifying the shape
of the step
VERouteItineraryItem.Text Property A String specifying the description of the step
VERouteItineraryItem.Time Property An integer specifying the total elapsed time, in
seconds, to traverse the route itinerary step.
VERouteItineraryItem.Warnings Property An array of VERouteWarning Class items that
correspond to the itinerary item.
VERouteItineraryItem.Hints Property An array of VERouteHint Class items that
correspond to the itinerary item.
See Also
VERouteItineraryItem Class
VERouteItinerary Class
VERouteItineraryItem.Distance Property
A floating-point number specifying the distance of the step
Syntax
VERouteItineraryItem.Distance
See Also
VERouteItineraryItem.Time Property
246
VERouteItineraryItem.LatLong Property
A VELatLong Class object specifying the position of the step
Syntax
VERouteItineraryItem.LatLong
VERouteItineraryItem.Shape Property
A VEShape Class object specifying the shape of the step
Syntax
VERouteItineraryItem.Shape
VERouteItineraryItem.Text Property
A String specifying the description of the step
Syntax
VERouteItineraryItem.Text
VERouteItineraryItem.Time Property
An integer specifying the total elapsed time, in seconds, to traverse the route itinerary step.
Syntax
VERouteItineraryItem.Time
See Also
VERouteItineraryItem.Distance Property
VERouteItineraryItem.Warnings Property
An array of VERouteWarning Class items that correspond to the itinerary item.
Syntax
VERouteItineraryItem.Warnings
See Also
VERouteWarning Class
VERouteItineraryItem Class
VERouteItinerary Class
VERouteOptions.UseTraffic Property
VERouteItineraryItem.Hints Property
An array of VERouteHint Class items that correspond to the itinerary item.
247
Syntax
VERouteItineraryItem.Hints
See Also
VERouteHint Class
VERouteHintType Enumeration
VERouteLeg Class
Specifies the intermediate legs of the route.
Public Properties
Name Description
VERouteLeg.Distance Property A floating-point number specifying the length of
the route leg.
VERouteLeg.Itinerary Property A VERouteItinerary Class object specifying the
itinerary of the route leg.
VERouteLeg.Time Property An integer specifying the total elapsed time, in
seconds, to traverse the route leg.
See Also
VERoute.RouteLegs Property
VERouteLeg Properties
The properties of the VERouteLeg class are listed here. For a complete list of VERouteLeg
class members, see the VERouteLeg Class topic.
Public Properties
Name Description
VERouteLeg.Distance Property A floating-point number specifying the length of
the route leg.
VERouteLeg.Itinerary Property A VERouteItinerary Class object specifying the
itinerary of the route leg.
VERouteLeg.Time Property An integer specifying the total elapsed time, in
seconds, to traverse the route leg.
248
VERouteLeg.Distance Property
A floating-point number specifying the length of the route leg.
Syntax
VERouteLeg.Distance
See Also
VERouteLeg.Time Property
VERouteLeg.Itinerary Property
A VERouteItinerary Class object specifying the itinerary of the route leg.
Syntax
VERouteLeg.Itinerary
VERouteLeg.Time Property
An integer specifying the total elapsed time, in seconds, to traverse the route leg.
Syntax
VERouteLeg.Time
See Also
VERouteLeg.Distance Property
VERouteLocation Class
Contains the location information (address and a latitude/longitude pair) of the
VERouteDeprecated.StartLocation Property and VERouteDeprecated.EndLocation Property
points of a route.
Public Properties
Name Description
VERouteLocation.Address Property Specifies the street address (as a string) of the
location.
VERouteLocation.LatLong Property Specifies the latitude and longitude (as a
VELatLong Class object) of the location.
249
VERouteLocation Properties
The properties of the VERouteLocation class are listed here. For a complete list of
VERouteLocation class members, see the VERouteLocation Class topic.
Public Properties
Name Description
VERouteLocation.Address Property Specifies the street address (as a string) of the
location.
VERouteLocation.LatLong Property Specifies the latitude and longitude (as a
VELatLong Class object) of the location.
VERouteLocation.Address Property
Specifies the street address (as a string) of the location.
Syntax
VERouteLocation.Address = value
VERouteLocation.LatLong Property
Specifies the latitude and longitude (as a VELatLong Class) of the location.
Syntax
VERouteLocation.LatLong = value
VERouteMode Enumeration
An enumeration of route modes.
Syntax
VERouteMode{ Driving Walking }
Members
Member Description
Driving The returned route contains driving directions
Walking The returned route contains walking directions
250
VERouteOptimize Enumeration
An enumeration specifying how a route is calculated.
Syntax
VERouteOptimize{ MinimizeTime MinimizeDistance }
Members
Member Description
MinimizeTime The route is calculated to minimize time.
MinimizeDistance The route is calculated to minimize distance.
See Also
VERouteOptions.RouteOptimize Property
VERouteOptions Class
Contains additional options to customize the returned route.
Constructor
Name Description
VERouteOptions Constructor Initializes a new instance of the
VERouteOptions Class.
Public Properties
Name Description
VERouteOptions.DistanceUnit Property A VERouteDistanceUnit Enumeration value
specifying the units used for the route. The
default value is VERouteDistanceUnit.Mile.
VERouteOptions.DrawRoute Property A Boolean value specifying whether the route is
drawn on the map. The default value is true,
which means the route is drawn on the map.
VERouteOptions.RouteCallback Property The name of the function called when the
251
Name Description
method has generated the route. Optional. The
default value is null. The called function
receives a VERoute Class object.
VERouteOptions.RouteColor Property The VEColor Class object specifying the color
of the route line. The default value is default is
VEColor(0,169,235,0.7).
VERouteOptions.RouteMode Property A VERouteMode Enumeration value specifying
the mode of route to return. The default value is
VERouteMode.Driving.
VERouteOptions.RouteOptimize Property A VERouteOptimize Enumeration value
specifying how the route is optimized. The
default value is
VERouteOptimize.MinimizeTime.
VERouteOptions.RouteWeight Property The thickness, in pixels, of the route line. The
default value is 6 pixels.
VERouteOptions.RouteZIndex Property The z-index of the route line. The default value
is 4.
VERouteOptions.SetBestMapView Property A Boolean value specifying whether the map
view is set to the best view of the route after it
is drawn. The default is true, which means that
the map view is set.
VERouteOptions.ShowDisambiguation Property A Boolean value specifying whether a
disambiguation dialog box is shown. Optional.
The default value is true, which means the
disambiguation dialog box is shown. If false, no
disambiguation dialogs are displayed and the
route uses the first geocoded response for
each location.
VERouteOptions.ShowErrorMessages Property Whether to show any error messages. The
default value is true.
VERouteOptions.UseMWS Property A Boolean value specifying whether to use the
MapPoint Web Service to generate the route.
The default value is false.
VERouteOptions.UseTraffic Property A Boolean value specifying whether to
calculate the route using traffic information. The
default value is false.
252
See Also
VEMap.GetDirections Method
VERouteOptions Constructor
Initializes a new instance of the VERouteOptions Class.
Syntax
var x = new VERouteOptions();
See Also
VERouteOptions Class
VERouteOptions Properties
The properties of the VERouteOptions class are listed here. For a complete list of
VERouteOptions class members, see the VERouteOptions Class topic.
Public Properties
Property Description
VERouteOptions.DistanceUnit Property A VERouteDistanceUnit Enumeration value
specifying the units used by the route. Optional.
The default value is
VERouteDistanceUnit.Miles.
VERouteOptions.DrawRoute Property A Boolean value specifying whether the route is
drawn on the map. The default value is true,
which means the route is drawn on the map.
VERouteOptions.RouteCallback Property The name of the function called when the
method has generated the route. Optional. The
default value is null. The called function
receives a VERoute Class object.
VERouteOptions.RouteColor Property The VEColor Class object specifying the color
of the route line. The default value is default is
VEColor(0,169,235,0.7).
VERouteOptions.RouteMode Property A VERouteMode Enumeration value specifying
the mode of route to return. The default value
is VERouteMode.Driving.
VERouteOptions.RouteOptimize Property A VERouteOptimize Enumeration object
specifying how the route is optimized. The
253
Property Description
default value is
VERouteOptimize.MinimizeTime.
VERouteOptions.RouteWeight Property The thickness, in pixels, of the route line. The
default value is 6 pixels.
VERouteOptions.SetBestMapView Property A Boolean value specifying whether the map
view is set to the best view of the route after it
is drawn. The default is true, which means that
the map view is set.
VERouteOptions.ShowDisambiguation Property A Boolean value specifying whether a
disambiguation dialog box is shown. Optional.
The default value is true, which means the
disambiguation dialog box is shown. If false, no
disambiguation dialogs are displayed and the
route uses the first geocoded response for
each location.
VERouteOptions.ShowErrorMessages Property Whether to show any error messages. The
default value is true.
VERouteOptions.UseMWS Property A Boolean value specifying whether to use the
MapPoint Web Service to generate the route.
The default value is false.
VERouteOptions.UseTraffic Property A Boolean value specifying whether to
calculate the route using traffic information.
The default value is false.
See Also
VEMap.GetDirections Method
VERouteOptions.DistanceUnit Property
A VERouteDistanceUnit Enumeration value specifying the units used by the route.
Syntax
VERouteOptions.DistanceUnit = value;
VERouteOptions.DrawRoute Property
A Boolean value specifying whether the route is drawn on the map.
Syntax
254
VERouteOptions.DrawRoute = value;
VERouteOptions.RouteCallback Property
The name of the function called when the method has generated the route.
Syntax
VERouteOptions.RouteCallback = value;
VERouteOptions.RouteColor Property
A VEColor Class object specifying the color of the route line.
Syntax
VERouteOptions.RouteColor = value;
Remarks
The default value for this property is VEColor(0,169,235,0.7).
VERouteOptions.RouteMode Property
A VERouteMode Enumeration value specifying the mode of route to return.
Syntax
VERouteOptions.RouteMode = value;
Remarks
The default value is VERouteMode.Driving.
If the RouteMode property is set to VERouteMode.Driving, the returned route will contain
driving directions in the itinerary.
If the RouteMode property is set to VERouteMode.Walking, the returned route will contain
walking directions in the itinerary unless the VERouteOptions.UseMWS Property is set to true or
the VERouteOptions.UseTraffic Property is set to true, in which case an empty VERoute object
is returned. An empty VERoute object has no itinerary and the VERoute.Distance Property and
VERoute.Time Property are 0.
If the RouteMode property is set to VERouteMode.Walking and the
VERouteOptions.RouteOptimize Property is set to VERouteOptimize.MinimizeTime, then an
empty VERoute object is returned.
See Also
VERouteOptions Class
VERouteMode Enumeration
VERouteOptions.RouteOptimize Property
A VERouteOptimize Enumeration value specifying how the route is calculated.
255
Syntax
VERouteOptions.RouteOptimize = value;
Remarks
The default value for this property is MinimizeTime. This means that the route will be calculated
to minimize the route time.
You can set the VERouteOptions.UseTraffic Property to true if you'd like the route to consider
available traffic information to minimize the route time.
If the RouteOptimize property is set to VERouteOptimize.MinimizeTime and the
VERouteOptions.RouteMode Property is set to VERouteMode.Walking, then an empty VERoute
object is returned.
See Also
VERouteOptimize Enumeration
VERouteOptions.RouteWeight Property
The thickness, in pixels, of the route line.
Syntax
VERouteOptions.RouteWeight = value;
Remarks
The default value is 6 pixels.
VERouteOptions.RouteZIndex Property
The z-index of the route line.
Syntax
VERouteOptions.RouteZIndex = value;
Remarks
The default value is 4.
VERouteOptions.SetBestMapView Property
A Boolean value specifying whether the map view is set to the best view of the route after it is
drawn.
Syntax
VERouteOptions.SetBestMapView = value;
VERouteOptions.ShowDisambiguation Property
A Boolean value specifying whether a disambiguation dialog box is shown.
256
Syntax
VERouteOptions.ShowDisambiguation = value;
VERouteOptions.ShowErrorMessages Property
Whether to show any error messages.
Syntax
VERouteOptions.ShowErrorMessages = value;
Remarks
The default value is true.
See Also
VERouteOptions.ShowDisambiguation Property
VERouteOptions.UseMWS Property
A Boolean value specifying whether to use the MapPoint Web Service to generate the route.
Syntax
VERouteOptions.UseMWS = bool;
Remarks
By default the route is generated by the new routing service. To use the MWS routing service, set
this property to true.
For some cultures, this property must be set to true to return localized directions. See the
Returning Localized Results topic for more information.
The MapPoint Web Service can only be used to calculate directions if the
VERouteOptions.RouteMode Property is set to VERouteMode.Driving. If the UseMWS property
is set to true and the VERouteOptions.RouteMode property is set to VERouteMode.Walking,
then an empty VERoute object is returned. An empty VERoute object has no itinerary and the
VERoute.Distance Property and VERoute.Time Property are 0.
See Also
VERouteOptions Class
VERouteOptions.UseTraffic Property
A Boolean value specifying whether to calculate the route using traffic information.
Syntax
VERouteOptions.UseTraffic = bool;
Remarks
257
The default value is false, which means the route will be calculated without considering traffic
information.
If the property UseTraffic is set to true and the VERouteOptions.RouteOptimize property is set
to VERouteOptimize.MimimizeTime, then the route calculation engine considers available traffic
information and changes the route accordingly to minimize the route time.
If the property UseTraffic is set to true and the VERouteOptions.RouteOptimize property is set
to VERouteOptimize.MimimizeDistance, then the route will not change, but available traffic
information will be included in the itinerary.
Available traffic information is returned only if the VERouteOptions.RouteMode Property is set to
VERouteMode.Driving. If the UseTraffic property is set to true and the
VERouteOptions.RouteMode property is set to VERouteMode.Walking, then an empty
VERoute object is returned. An empty VERoute object has no itinerary and the
VERoute.Distance Property and VERoute.Time Property are 0.
See Also
VERouteOptions Class
VERouteOptions.RouteOptimize Property
VERouteOptimize Enumeration
VEMap.LoadTraffic Method
VERouteSegment Class
Contains details about one segment of a VERoute Class object.
Public Properties
Name Description
VERouteSegment.Instruction Property The driving instructions for this segment of the
route.
VERouteSegment.Distance Property The distance of this segment of the route.
VERouteSegment.LatLong Property A VELatLong Class object of the start point of
this segment.
Remarks
The VERouteItineraryDeprecated.Segments Property contains an array of VERouteSegment
objects.
258
VERouteSegment Properties
The properties of the VERouteSegment class are listed here. For a complete list of
VERouteSegment class members, see the VERouteSegment Classtopic.
Public Properties
Name Description
VERouteSegment.Instruction Property The driving instructions for this segment of the
route.
VERouteSegment.Distance Property The distance of this segment of the route.
VERouteSegment.LatLong Property A VELatLong Class object of the start point of
this segment.
VERouteSegment.Instruction Property
The driving instructions for this segment of the route.
Syntax
VERouteSegment.Instruction = value
VERouteSegment.LatLong Property
A VELatLong Class object of the start point of this segment.
Syntax
VERouteSegment.LatLong = value
Remarks
Each route segment is defined by the latitude and longitude of the start point and the distance of
the segment. The end point of any given segment is defined by the LatLong property of the next
segment in the route. Therefore, for the last VERouteSegment object in a route, the LatLong
property is the location of the end point of the entire route, and the VERouteSegment.Distance
Property has a value of 0 (zero).
VERouteSegment.Distance Property
The distance of this segment of the route.
Syntax
VERouteSegment.Distance = value
Remarks
259
Each route segment is defined by the latitude and longitude of the start point and the distance of
the segment. The end point of any given segment is defined by the VERouteSegment.LatLong
Property of the next segment in the route. Therefore, for the last VERouteSegment object in a
route, the LatLong property is the location of the end point of the entire route, and the Distance
property has a value of 0 (zero).
VERouteType Enumeration
An enumeration of route types.
Syntax
VERouteType{ Shortest Quickest }
Members
Member Description
Shortest Generates the shortest (by distance) route
Quickest Generates the quickest (by estimated driving
time) route
Remarks
This enumeration is used in the route_type parameter of the VEMap.GetRoute Method to specify
the type of route to generate.
VERouteWarning Class
Specifies a traffic warning.
Public Properties
Property Description
VERouteWarning.Severity Property A VERouteWarningSeverity Enumeration value
specifying the severity level of the warning.
VERouteWarning.Text Property A String that describes the route warning.
See Also
VERouteItineraryItem.Warnings Property
260
VERouteOptions.UseTraffic Property
VERouteWarning Properties
The properties of the VERouteWarning class are listed here. For a complete list of
VERouteWarning class members, go to the VERouteWarning Class topic.
Public Properties
Property Description
VERouteWarning.Severity Property A VERouteWarningSeverity Enumeration value
specifying the severity level of the warning.
VERouteWarning.Text Property A String that describes the route warning.
See Also
VERouteItineraryItem.Warnings Property
VERouteOptions.UseTraffic Property
VERouteWarning.Severity Property
A VERouteWarningSeverity Enumeration value specifying the severity level of the warning.
Syntax
VERouteWarning.Severity = value;
See Also
VERouteItineraryItem.Warnings Property
VERouteWarningSeverity Enumeration
VERouteWarning.Text Property
A String that describes the route warning.
Syntax
VERouteWarning.Text
See Also
VERouteWarning Class
VERouteItineraryItem Class
VERouteItineraryItem.Warnings Property
VERouteWarningSeverity Enumeration
An enumeration specifying the severity level of a route warning.
261
Syntax
VERouteWarningSeverity{ None LowImpact Minor Moderate Serious }
Members
Member Description
None A warning which has no impact on traffic
LowImpact A warning which has low impact on traffic
Minor A minor traffic incident
Moderate A moderate traffic incident
Serious A serious traffic incident
See Also
VERouteWarning.Severity Property
VERouteItineraryItem.Warnings Property
VESearchOptions Class
Contains additional search options for the VEMap.Search Method.
Constructor
Name Description
VESearchOptions Constructor Initializes a new instance of the
VESearchOptions class.
Public Properties
Name Description
VESearchOptions.BoundingRectangle Property A VELatLongRectangle Class that defines the
area to search. If this property is not specified,
the current map view is used. The default value
is null.
VESearchOptions.CreateResults Property A Boolean value that specifies whether
262
Name Description
VEShape objects are created. The default
value is true.
VESearchOptions.FindType Property A VEFindType Enumeration value that
specifies the type of search performed. The
only supported value is
VEFindType.Businesses.
VESearchOptions.NumberOfResults Property An integer that defines the number of results to
be returned, starting at StartIndex. The default
value is 10, the minimum value is 1, and the
maximum value is 20.
VESearchOptions.SetBestMapView Property A Boolean value that specifies whether the
map control moves the view to the first location
match. The default value is true.
VESearchOptions.ShapeLayer Property A VEShapeLayer Class object that will contain
the VEShape objects created as a result of this
search. Optional. If the shape layer is not
specified, the pins are added to the base map
layer. The default value is null.
VESearchOptions.ShowResults Property A Boolean value indicating whether the
VEShape objects are visible. Optional. The
default value is true.
VESearchOptions.StartIndex Property An integer specifying the beginning index of the
results returned. Optional. The default value is
0.
VESearchOptions.UseDefaultDisambiguation
Property
A Boolean value indicating whether to show the
disambiguation dialog if there is more than one
result with high match confidence. The default
value is true.
See Also
VEMap.Search Method
VESearchOptions Constructor
Initializes a new instance of the VESearchOptions Class.
Syntax
var x = new VESearchOptions();
263
See Also
VEMap.Search Method
VESearchOptions Properties
The properties of the VESearchOptions class are listed here. For a complete list of
VESearchOptions class members, see the VESearchOptions Class topic.
Public Properties
Name Description
VESearchOptions.BoundingRectangle Property A VELatLongRectangle Class that defines the
area to search. If this property is not specified,
the current map view is used. The default value
is null.
VESearchOptions.CreateResults Property A Boolean value that specifies whether
VEShape objects are created. The default
value is true.
VESearchOptions.FindType Property A VEFindType Enumeration value that
specifies the type of search performed. The
only supported value is
VEFindType.Businesses.
VESearchOptions.NumberOfResults Property An integer that defines the number of results to
be returned, starting at StartIndex. The default
value is 10, the minimum value is 1, and the
maximum value is 20.
VESearchOptions.SetBestMapView Property A Boolean value that specifies whether the
map control moves the view to the first location
match. The default value is true.
VESearchOptions.ShapeLayer Property A VEShapeLayer Class object that will contain
the VEShape objects created as a result of this
search. Optional. If the shape layer is not
specified, the pins are added to the base map
layer. The default value is null.
VESearchOptions.ShowResults Property A Boolean value indicating whether the
VEShape objects are visible. Optional. The
default value is true.
VESearchOptions.StartIndex Property An integer specifying the beginning index of the
results returned. Optional. The default value is
0.
264
Name Description
VESearchOptions.UseDefaultDisambiguation
Property
A Boolean value indicating whether to show the
disambiguation dialog if there is more than one
result with high match confidence. The default
value is true.
See Also
VEMap.Search Method
VESearchOptions.BoundingRectangle Property
A VELatLongRectangle Class that defines the area to search. If null, the current map view is
used.
Syntax
VESearchOptions.BoundingRectangle = object;
VESearchOptions.CreateResults Property
A Boolean value that specifies whether VEShape objects are created.
Syntax
VESearchOptions.CreateResults = value;
Remarks
If CreateResults is set to true, VEShape objects are returned to the callback function. These
objects can be used to create pushpins on the map to display search results.
If CreateResults is set to false the following modifications occur in the arguments returned to the
callback function:
The array of VEFindResult Class objects is still present, but no shape layer is created.
Each VEFindResult object's corresponding Shape property is null.
VESearchOptions.FindType Property
A VEFindType Enumeration value that specifies the type of search performed. The only
supported value is VEFindType.Businesses.
Syntax
VESearchOptions.FindType = VEFindType.Businesses;
VESearchOptions.NumberOfResults Property
An integer that defines the number of results to be returned, starting at StartIndex. The default
value is 10, the minimum value is 1, and the maximum value is 20.
Syntax
VESearchOptions.NumberOfResults = value;
265
VESearchOptions.SetBestMapView Property
A Boolean value that specifies whether the map control moves the view to the first location
match. The default value is true.
Syntax
VESearchOptions.SetBestMapView = value;
VESearchOptions.ShapeLayer Property
A VEShapeLayer Class object that will contain the VEShape objects created as a result of this
search. Optional. If the shape layer is not specified, the pins are added to the base map layer.
Syntax
VESearchOptions.ShapeLayer = object;
VESearchOptions.ShowResults Property
A Boolean value indicating whether the VEShape objects are visible. Optional. The default value
is true.
Syntax
VESearchOptions.ShowResults = value;
VESearchOptions.StartIndex Property
An integer specifying the beginning index of the results returned. Optional. The default value is 0.
Syntax
VESearchOptions.StartIndex = value;
VESearchOptions.UseDefaultDisambiguation Property
A Boolean value indicating whether to show the disambiguation dialog if there is more than one
result with high match confidence. The default value is true.
Syntax
VESearchOptions.UseDefaultDisambiguation = value;
Parameters
Property Value/Return Value
Exceptions
Remarks
Example
Description
This is the description for a Code Example.
266
Microsoft.Win32.RegistryKey#4
Comments
Optional comments.
.NET Framework Equivalent
Optional .NET Framework equivalent section.
Requirements
Subsection Heading
VEShape Class
Contains the information about a map shape.
Constructor
Name Description
VEShape Constructor Initializes a new instance of the VEShape object.
Public Events
Name Description
VEShape.ondrag Event Occurs when a shape is being dragged across
the map.
VEShape.onenddrag Event Occurs when a shape drag has stopped.
VEShape.onstartdrag Event Occurs when the user starts dragging the
shape.
Public Methods
Name Description
VEShape.GetAltitude Method Returns the altitude for the shape.
VEShape.GetAltitudeMode Method Gets the mode in which the shape's
altitude is represented.
VEShape.GetCustomIcon Method Gets the VEShape object's custom icon.
267
Name Description
VEShape.GetDescription Method Gets the description of the VEShape object.
VEShape.GetFillColor Method Gets the fill color and transparency for a
polygon.
VEShape.GetIconAnchor Method Gets a VELatLong Class object
representing the shape's custom icon
anchor point.
VEShape.GetID Method Gets the internal identifier of the VEShape object.
VEShape.GetLineColor Method Gets the line color or transparency for a
polyline or polygon.
VEShape.GetLineToGround Method Gets whether a line is drawn from the
shape to the ground.
VEShape.GetLineWidth Method Gets the line width of a polyline or
polygon.
VEShape.GetMaxZoomLevel Method Gets the maximum zoom level at which
the shape is visible.
VEShape.GetMinZoomLevel Method Gets the minimum zoom level at which the
shape is visible.
VEShape.GetMoreInfoURL Method Gets the shape's "more info" URL.
VEShape.GetPhotoURL Method Gets the shape's "photo" URL.
VEShape.GetPoints Method Returns an array of VELatLong Class
objects representing the points that make
up the pushpin, polyline, or polygon.
VEShape.GetShapeLayer Method Gets the reference to the layer containing
the specified VEShape object.
VEShape.GetTitle Method Gets the title of the VEShape object.
VEShape.GetType Method Gets the type of the VEShape object.
VEShape.GetZIndex Method Gets the z-index of a pushpin shape or pushpin
attached to a polyline or polygon.
VEShape.GetZIndexPolyShape Method Gets the z-index for a polyline or polygon.
VEShape.Hide Method Hides the specified VEShape object from view.
VEShape.HideIcon Method Hides the icon associated with a polyline
or polygon. This method is ignored for
268
Name Description
pushpins.
VEShape.IsModel Method Returns whether the shape is a model.
VEShape.SetAltitude Method Specifies the altitude for the shape.
VEShape.SetAltitudeMode Method Specifies the mode in which a shape's
altitude is represented.
VEShape.SetCustomIcon Method Sets the VEShape object's custom icon.
VEShape.SetDescription Method Sets the description of the VEShape object.
VEShape.SetFillColor Method Sets the fill color and transparency of a
polygon.
VEShape.SetIconAnchor Method Sets the info box anchor of the VEShape
object.
VEShape.SetLineColor Method Sets the line color or transparency for a
polyline or polygon.
VEShape.SetLineToGround Method Specifies whether a line is drawn from the
shape to the ground.
VEShape.SetLineWidth Method Sets the line width for a polyline or
polygon.
VEShape.SetMaxZoomLevel Method Sets the maximum zoom level at which the
shape is visible.
VEShape.SetMinZoomLevel Method Sets the minimum zoom level at which the
shape is visible.
VEShape.SetMoreInfoURL Method Sets the shape's "more info" URL.
VEShape.SetPhotoURL Method Sets the shape's "photo" URL.
VEShape.SetPoints Method Sets the points of the VEShape object.
VEShape.SetTitle Method Sets the title of the VEShape object.
VEShape.SetZIndex Method Sets the z-index value for a shape.
VEShape.Show Method Makes the specified VEShape object
visible.
VEShape.ShowIcon Method Shows the icon associated with a polyline
or polygon. This method is ignored for
pushpins.
269
Public Properties
Name Description
VEShape.Draggable Property A Boolean value indicating whether the
VEShape icon on the map can be dragged
using the mouse.
Remarks
The VEShape class is designed to provide advanced polygon and polyline functionality. The
VEShape class contains enumerated types for pushpins, polylines, and polygons.
See Also
VEShapeLayer Class
VEMap Class
VEShape Constructor
Initializes a new instance of the VEShape class.
Syntax
var x = new VEShape(type, points);
Parameters
Parameter Description
type A VEShapeType Enumeration value of type
that represents the type of shape. Required.
points If the shape is a pushpin, this parameter can
either be a single VELatLong Class object or an
array of VELatLong objects. If it is an array of
VELatLong objects, only the first VELatLong
object is used to define the pushpin's location.
Any additional data members are ignored. If the
shape is a polyline or polygon, it must be an
array of VELatLong objects, containing at least
two points for a polyline and at least three
points for a polygon. Required.
270
Remarks
A VEMap Class object must be instantiated before a VEShape object can be created.
All shapes must be contained in a layer. Any shape added using the VEMap.AddShape Method is
added to the map's base layer. This base layer is always located at index 0 and cannot be
deleted. Any shape added using a VEShapeLayer.AddShape Method is added to that specific
layer.
If the points parameter contains an array of VELatLong objects and any of those objects has an
altitude, the altitudes of the other VELatLong objects either be the same value or null.
VEShape Events
The events of the VEShape Class are listed here. For a complete list of VEShape class
members, see the VEShape Class topic.
Public Events
Name Description
VEShape.ondrag Event Occurs when a shape is being dragged across
the map.
VEShape.onenddrag Event Occurs when a shape drag has stopped.
VEShape.onstartdrag Event Occurs when the user starts dragging the
shape.
See Also
VEShape.Draggable Property
VEShape.ondrag Event
Occurs when a shape is being dragged across the map.
Syntax
VEShape.ondrag = function_name;
Return Value
A ShapeDragEventArgs object, which has the following properties:
Property Description
Shape The VEShape object that fired the event.
LatLong The current VELatLong of the shape.
Remarks
271
The ondrag event occurs when the user moves the mouse and the left mouse button is pressed
down.
The ondrag event only occurs after the VEShape.onstartdrag Event has occurred.
For the ondrag event to occur, the VEShape.Draggable Property must be set to true.
Example
VirtualEarthSDK#65
See Also
VEShape.Draggable Property
VEShape.onstartdrag Event
VEShape.onenddrag Event
VEShape.onenddrag Event
Occurs when a shape drag has stopped.
Syntax
VEShape.onenddrag = function_name;
Return Value
A ShapeDragEventArgs object, which has the following properties:
Property Description
Shape The VEShape object that fired the event.
LatLong The current VELatLong of the shape.
Remarks
The onenddrag event occurs when the left mouse button up event occurs after a shape has
been dragged.
The onenddrag event only occurs after the VEShape.onstartdrag Event has occurred.
For the onenddrag event to occur, the VEShape.Draggable Property must be set to true.
Example
VirtualEarthSDK#65
See Also
VEShape.Draggable Property
VEShape.onstartdrag Event
VEShape.ondrag Event
VEShape.onstartdrag Event
Occurs when the user starts dragging the shape.
Syntax
272
VEShape.onstartdrag = function_name;
Return Value
A ShapeDragEventArgs object, which has the following properties:
Property Description
Shape The VEShape object that fired the event.
LatLong The current VELatLong of the shape.
Remarks
The onstartdrag event occurs when the user presses the left mouse button down when the
mouse is over a shape.
For the onstartdrag event to occur, the VEShape.Draggable Property must be set to true.
Example
VirtualEarthSDK#65
See Also
VEShape.Draggable Property
VEShape.ondrag Event
VEShape.onenddrag Event
VEShape Methods
The methods of the VEShape class are listed here. For a complete list of VEShape class
members see VEShape Class.
Public Methods
Name Description
VEShape.GetAltitude Method Returns the altitude for the shape.
VEShape.GetAltitudeMode Method Gets the mode in which the shape's
altitude is represented.
VEShape.GetCustomIcon Method Gets the VEShape object's custom icon.
VEShape.GetDescription Method Gets the description of the VEShape object.
VEShape.GetFillColor Method Gets the fill color and transparency for a
polygon.
VEShape.GetIconAnchor Method Gets a VELatLong Class object
representing the shape's custom icon
anchor point.
273
Name Description
VEShape.GetID Method Gets the internal identifier of the VEShape object.
VEShape.GetLineColor Method Gets the line color or transparency for a
polyline or polygon.
VEShape.GetLineToGround Method Gets whether a line is drawn from the
shape to the ground.
VEShape.GetLineWidth Method Gets the line width of a polyline or
polygon.
VEShape.GetMaxZoomLevel Method Gets the maximum zoom level at which
the shape is visible.
VEShape.GetMinZoomLevel Method Gets the minimum zoom level at which the
shape is visible.
VEShape.GetMoreInfoURL Method Gets the shape's "more info" URL.
VEShape.GetPhotoURL Method Gets the shape's "photo" URL.
VEShape.GetPoints Method Returns an array of VELatLong Class
objects representing the points that make
up the pushpin, polyline, or polygon.
VEShape.GetShapeLayer Method Gets the reference to the layer containing
the specified VEShape object.
VEShape.GetTitle Method Gets the title of the VEShape object.
VEShape.GetType Method Gets the type of the VEShape object.
VEShape.GetZIndex Method Gets the z-index of a pushpin shape or
pushpin attached to a polyline or polygon.
VEShape.GetZIndexPolyShape Method Gets the z-index for a polyline or polygon.
VEShape.Hide Method Hides the specified VEShape object from
view.
VEShape.HideIcon Method Hides the icon associated with a polyline
or polygon. This method is ignored for
pushpins.
VEShape.IsModel Method Returns whether the shape is a model.
VEShape.SetAltitude Method Specifies the altitude for the shape.
VEShape.SetAltitudeMode Method Specifies the mode in which a shape's
altitude is represented.
274
Name Description
VEShape.SetCustomIcon Method Sets the VEShape object's custom icon.
VEShape.SetDescription Method Sets the description of the VEShape object.
VEShape.SetFillColor Method Sets the fill color and transparency of a
polygon.
VEShape.SetIconAnchor Method Sets the info box anchor of the VEShape
object.
VEShape.SetLineColor Method Sets the line color or transparency for a
polyline or polygon.
VEShape.SetLineToGround Method Specifies whether a line is drawn from the
shape to the ground.
VEShape.SetLineWidth Method Sets the line width for a polyline or
polygon.
VEShape.SetMaxZoomLevel Method Sets the maximum zoom level at which the
shape is visible.
VEShape.SetMinZoomLevel Method Sets the minimum zoom level at which the
shape is visible.
VEShape.SetMoreInfoURL Method Sets the shape's "more info" URL.
VEShape.SetPhotoURL Method Sets the shape's "photo" URL.
VEShape.SetPoints Method Sets the points of the VEShape object.
VEShape.SetTitle Method Sets the title of the VEShape object.
VEShape.SetZIndex Method Sets the z-index value for a shape.
VEShape.Show Method Makes the specified VEShape object
visible.
VEShape.ShowIcon Method Shows the icon associated with a polyline
or polygon. This method is ignored for
pushpins.
See Also
VEShapeLayer Class
VEMap Class
VEShape.GetAltitude Method
Returns the altitude for the shape.
275
Syntax
VEShape.GetAltitude();
Return Value
A floating-point values representing meters above the level represented by the altitude mode.
Remarks
The example code uses the following custom image.
Examples
VirtualEarthSDK#44
See Also
VEShape.GetAltitudeMode Method
VEShape.SetAltitude Method
VEShape.GetAltitudeMode Method
Gets the mode in which the shape's altitude is represented.
Syntax
VEShape.GetAltitudeMode();
Return Value
A VEAltitudeMode Enumeration value.
Remarks
This method returns VEAltitudeMode.RelativeToGround if the altitude is not set.
The sample uses the following custom image.
Examples
VirtualEarthSDK#44
See Also
VEShape.GetAltitude Method
VEShape.SetAltitudeMode Method
VEShape.GetCustomIcon Method
Gets the VEShape objects custom icon.
Syntax
VEShape.GetCustomIcon();
276
Returns
A String or VECustomIconSpecification Class object representing the custom icon of the
VEShape object.
The example for this topic uses the following custom icon images.
Example
VirtualEarthSDK#39
See Also
VEShape.SetCustomIcon Method
VEShape.GetDescription Method
Gets the description of the VEShape object. This description will be displayed in the shape's info
box.
Syntax
VEShape.GetDescription();
Returns
A String object representing the description field of the VEShape object.
Example
VirtualEarthSDK#38
See Also
VEShape.SetDescription Method
VEShape.GetFillColor Method
Gets the fill color and transparency for a polygon.
Syntax
VEShape.GetFillColor();
Returns
A VEColor object representing the fill color/transparency for a polygon.
Remarks
277
The default is semi-transparent green (alpha=0.3, RGB=0, 128, 0). This method is ignored for
pushpins and polylines.
Example
VirtualEarthSDK#38
See Also
VEShape.SetFillColor Method
VEShape.GetIconAnchor Method
Gets a VELatLong Class object representing the shape's custom icon anchor point.
Syntax
VEShape.GetIconAnchor();
Returns
A VELatLong Class object representing the anchor point for the shape's info box.
Example
VirtualEarthSDK#39
See Also
VEShape.SetIconAnchor Method
VEShape.GetID Method
Gets the internal identifier of the VEShape object.
Syntax
VEShape.GetID();
Returns
A String object representing the internal identifier of the VEShape object.
Returns
Use this identifier when working with VEShape object events. A VEShape object only has an
identifier when it has been added to a layer. If you try to get the identifier of a VEShape object
that is not part of a layer, the VEShape.GetID method returns null.
Example
VirtualEarthSDK#38
VEShape.GetLineColor Method
Gets the line color or transparency for a polyline or polygon.
Syntax
VEShape.GetLineColor();
278
Returns
A VEColor Class object representing the line color or transparency for a polyline or polygon. This
method returns null for pushpins.
Remarks
The default is semi-transparent blue (alpha=0.5, RGB=0, 0, 255).
Example
VirtualEarthSDK#38
See Also
VEShape.SetLineColor Method
VEShape.GetLineToGround Method
Gets whether a line is drawn from the shape to the ground.
Syntax
VEShape.GetLineToGround();
Return Value
If the shape type is Polyline or Polygon, this method returns a Boolean value; if the shape type is
Pushpin, this method returns null.
Examples
VirtualEarthSDK#45
See Also
VEShape.SetLineToGround Method
VEShape.GetLineWidth Method
Gets the line width of a polyline or polygon.
Syntax
VEShape.GetLineWidth();
Returns
The line width of the polyline or polygon. This method returns null for pushpins. If the line width is
not set, the default value 2 is returned.
Example
VirtualEarthSDK#38
See Also
VEShape.SetLineWidth Method
VEShape.GetMaxZoomLevel Method
Gets the maximum zoom level at which the shape is visible.
279
Syntax
VEShape.GetMaxZoomLevel();
Return Value
An integer specifying the maximum zoom level.
Remarks
The default maximum zoom level is 21.
Examples
VirtualEarthSDK#46
See Also
VEShape.GetMinZoomLevel Method
VEShape.SetMaxZoomLevel Method
VEShape.GetMinZoomLevel Method
Gets the minimum zoom level at which the shape is visible.
Syntax
VEShape.GetMinZoomLevel();
Return Value
An integer specifying the minimum zoom level.
Remarks
The default minimum zoom level is 1.
Examples
VirtualEarthSDK#46
See Also
VEShape.GetMaxZoomLevel Method
VEShape.SetMinZoomLevel Method
VEShape.GetMoreInfoURL Method
Gets the shape's "more info" URL.
Syntax
VEShape.GetMoreInfoURL();
Returns
The string containing the URL of the "more info" link that is displayed in the shape's info box.
Example
VirtualEarthSDK#38
280
See Also
VEShape.SetMoreInfoURL Method
VEShape.GetPhotoURL Method
Gets the shape's "photo" URL.
Syntax
VEShape.GetPhotoURL();
Returns
A String object containing the URL of the image that is displayed in the shape's info box.
Example
VirtualEarthSDK#38
See Also
VEShape.SetPhotoURL Method
VEShape.GetPoints Method
Returns an array of VELatLong Class objects representing the points that make up the pushpin,
polyline, or polygon.
Syntax
VEShape.GetPoints();
Returns
An array of VELatLong objects representing the points that make up the pushpin, polyline, or
polygon.
In the case of a pushpin, this will be a one-cell VELatLong array.
Remarks
Example
VirtualEarthSDK#38
See Also
VEShape.SetPoints Method
VEShape.GetShapeLayer Method
Gets the reference to the layer containing the specified VEShape object.
Syntax
VEShape.GetShapeLayer();
Returns
281
Returns a reference to the layer containing the specified VEShape object. If the VEShape object
is not contained in any layer, null is returned.
Remarks
Example
VirtualEarthSDK#8
VEShape.GetTitle Method
Gets the title of the VEShape object.
Syntax
VEShape.GetTitle();
Returns
A String object representing the title of the VEShape object.
Example
VirtualEarthSDK#38
See Also
VEShape.SetTitle Method
VEShape.GetType Method
Gets the type of the VEShape object.
Syntax
VEShape.GetType();
Returns
An VEShapeType Enumeration representing the type of the VEShape object. Valid shapes are
VEShapeType.Pushpin, VEShapeType.Polyline, or VEShapeType.Polygon.
Example
VirtualEarthSDK#38
VEShape.GetZIndex Method
Gets the z-index of a pushpin shape or pushpin attached to a polyline or polygon.
Syntax
VEShape.GetZIndex();
Return Value
An integer containing the z-index of the pushpin shape or pushpin attached to a polyline or
polygon. Use the VEShape.GetZIndexPolyShape Method to get the z-indices for a polyline or
polygon.
282
Examples
VirtualEarthSDK#47
See Also
VEShape.SetZIndex Method
VEShape.GetZIndexPolyShape Method
Gets the z-index for a polyline or polygon.
Syntax
VEShape.GetZIndexPolyShape();
Return Value
An integer containing the z-index value.
Remarks
Use the VEShape.GetZIndex Method to get the z-index of a pushpin shape or pushpin attached
to a polyline or polygon.
Examples
VirtualEarthSDK#46
See Also
VEShape.SetZIndex Method
VEShape.Hide Method
Hides the specified VEShape object from view.
Syntax
VEShape.Hide();
Example
VirtualEarthSDK#7
See Also
VEShape.Show Method
VEShape.HideIcon Method
Hides the icon associated with a polyline or polygon.
Syntax
VEShape.HideIcon();
Remarks
The associated icon is either the object's default icon, or its icon set by the
VEShape.SetCustomIcon Method. This method is ignored for pushpins.
283
Example
VirtualEarthSDK#39
See Also
VEShape.ShowIcon Method
VEShape.IsModel Method
Returns whether the shape is a 3D model.
Syntax
VEShape.IsModel();
Return Value
A Boolean value specifying whether the shape is a 3D model.
Remarks
3D model shapes can be created using the 3DVIA tool in 3D at http://maps.live.com or by
importing model data using the VEMap.Import3DModel Method.
VEShape.SetAltitude Method
Specifies the altitude for the shape.
Syntax
VEShape.SetAltitude(altitude, altitudeMode);
Parameters
Parameter Description
altitude A floating-point value or array of floating-point
values specifying the altitude, in meters, of the
shape.
altitudeMode A VEAltitudeMode Enumeration value
specifying the mode in which the shape's
altitude is represented.
Remarks
If the shape is a model, this method returns false, and the altitude is not changed.
If the shape is a pushpin, altitude must be a single floating-point value. If the shape is a polyline
or polygon and altitude is an array of floating-point values, the array must be the same length as
the number of points in the shape and the shape altitudes are set to the respective array value.
Otherwise, this method throws an exception.
The sample uses the following custom image.
284
Examples
VirtualEarthSDK#44
See Also
VEShape.GetAltitude Method
VEShape.SetAltitudeMode Method
VEShape.SetAltitudeMode Method
Specifies the mode in which a shape's altitude is represented.
Syntax
VEShape.SetAltitudeMode(mode);
Parameters
Parameter Description
mode A VEAltitudeMode Enumeration value
specifying the altitude representation.
Remarks
If the shape is a model, the altitude mode cannot be set.
If any point in the shape has a null altitude value, this method sets that altitude value to 0.
The sample uses the following custom image.
Examples
VirtualEarthSDK#44
See Also
VEShape.GetAltitudeMode Method
VEShape.SetAltitude Method
VEShape.SetCustomIcon Method
Sets the VEShape object's custom icon.
Syntax
VEShape.SetCustomIcon(customIcon);
Parameters
285
Parameter Description
customIcon A String object containing either a URL to an
image, custom HTML that defines the custom
icon, or a VECustomIconSpecification Class
object.
Remarks
If the customIcon field is a string that begins with the < character, it is considered to be HTML,
and it is used to create the pushpin icon. All other strings are treated as URLs to an image. If the
URL is invalid or doesn't point to an image, then nothing will be displayed for the pushpin icon.
Do not use the <a> tag within custom HTML, as this will cause a browser error. The HTML for
custom icons is automatically enclosed within an <a> tag. Adding an additional <a> tag results in
an illegally nested tag.
You can also overlay text on top of your custom image by using HTML with an <img> tag. One
possible use of this would be to show incremental numbers or letters on a group of pins that
share the same custom image.
If you only want to use 2D mode, use raw html to create the pin. If you only want to use 3D mode,
use a VECustomIconSpecification object and specify all of the 3D parameters.
The example for this topic uses the following custom icon images.
Example
VirtualEarthSDK#39
See Also
VEShape.GetCustomIcon Method
VEShape.SetDescription Method
Sets the description of the VEShape object.
Syntax
VEShape.SetDescription(details);
Parameters
286
Parameter Description
details A String object containing either plain text or
HTML that represents the VEShape object's
description field.
Remarks
To customize your info box to something instead of the default plain text, you can provide your
own custom HTML by using the VEShape.SetDescription method details parameter. The
content of the Details parameter is wrapped in a DIV tag and, along with the content defined by
VEShape.SetTitle Method (if any), forms the custom info box. See also
VEMap.ClearInfoBoxStyles Method and VEMap.SetDefaultInfoBoxStyles Method for further style
customization options.
There is no maximum length for this String. Depending on your formatting, style settings,
and browser, it may extend beyond the visible area of the info box. Be sure to format it
appropriately to avoid this problem
Example
VirtualEarthSDK#38
See Also
VEShape.GetDescription Method
VEShape.SetFillColor Method
Sets the fill color and transparency of a polygon.
Syntax
VEShape.SetFillColor(color);
Parameters
Parameter Description
color A VEColor object representing the fill color and
transparency.
Remarks
This method is ignored for pushpins. The default is semi-transparent blue (alpha=0.5, RGB=0, 0,
255).
Example
VirtualEarthSDK#38
See Also
287
VEShape.GetFillColor Method
VEShape.SetIconAnchor Method
Sets the info box anchor of the VEShape object.
Syntax
VEShape.SetIconAnchor(point);
Parameters
Parameter Description
point A VELatLong Class object representing the
shape's info box anchor point.
Remarks
This value is ignored for a pushpin. A pushpin's icon anchor point, either custom or default, is
always the latitude and longitude of the pin itself.
Example
VirtualEarthSDK#39
See Also
VEShape.GetIconAnchor Method
VEShape.SetLineColor Method
Sets the line color or transparency for a polyline or polygon.
Syntax
VEShape.SetLineColor(color);
Parameters
Parameter Description
color A VEColor Class object representing the line
color and transparency.
Remarks
This method is ignored for pushpins. The default is semi-transparent blue (alpha=0.5, RGB=0, 0,
255).
Example
VirtualEarthSDK#38
See Also
288
VEShape.GetLineColor Method
VEShape.SetLineToGround Method
Specifies whether a line is drawn from the shape to the ground.
Syntax
VEShape.SetLineToGround(extrude);
Parameters
Parameter Description
extrude A Boolean value specifying whether a line is
drawn from the shape to the ground.
Return Value
Returns false if the shape is a model; otherwise does not return a value.
Remarks
This method is for Polyline and Polygon shapes.
Examples
VirtualEarthSDK#45
See Also
VEShape.GetLineToGround Method
VEShape.SetLineWidth Method
Sets the line width for a polyline or polygon.
Syntax
VEShape.SetLineWidth(width);
Parameters
Parameter Description
width An integer representing the line's width.
Remarks
The default line width is 2. If the line width is invalid, an exception is thrown. This method is
ignored for pushpins.
Example
VirtualEarthSDK#38
289
See Also
VEShape.GetLineWidth Method
VEShape.SetMaxZoomLevel Method
Sets the maximum zoom level at which the shape is visible.
Syntax
VEShape.SetMaxZoomLevel(level);
Parameters
Parameter Description
level An integer specifying the maximum zoom level.
Exceptions
This method throws an exception if level is either greater than 21 or less than the current
minimum zoom level.
Remarks
The default maximum zoom level is 21.
If the minimum and maximum zoom levels are equal, the shape is visible only at that zoom level.
Examples
VirtualEarthSDK#46
See Also
VEShape.GetMaxZoomLevel Method
VEShape.SetMinZoomLevel Method
VEShape.SetMinZoomLevel Method
Sets the minimum zoom level at which the shape is visible.
Syntax
VEShape.SetMinZoomLevel(level);
Parameters
Parameter Description
level An integer specifying the minimum zoom level.
Exceptions
This method throws an exception if the level parameter is either less than 1 or greater than the
current maximum zoom level.
290
Remarks
The default minimum zoom level for a shape is 1.
If the minimum and maximum zoom levels are equal, the shape is visible only at that zoom level.
Examples
VirtualEarthSDK#46
See Also
VEMap.EnableShapeDisplayThreshold Method
VEShape.GetMinZoomLevel Method
VEShape.SetMaxZoomLevel Method
VEShape.SetMoreInfoURL Method
Sets the shape's "more info" URL.
Syntax
VEShape.SetMoreInfoURL(moreInfoURL);
Parameters
Parameter Description
moreInfoURL A String object containing the URL of the
"more info" link that is displayed in the shape's
info box.
Example
VirtualEarthSDK#38
See Also
VEShape.GetMoreInfoURL Method
VEShape.SetPhotoURL Method
Sets the shape's photo URL.
Syntax
VEShape.SetPhotoURL(photoURL);
Parameters
Parameter Description
photoURL The string containing the URL of the image that
is displayed in the shape's info box.
291
Remarks
The image area is set to 80 pixels wide by 80 pixels deep. These dimensions cannot be changed.
Images specified using this method should be sized accordingly. Alternatively, you can call the
VEShape.SetDescription Method, and specify custom HTML markup within the description.
Example
VirtualEarthSDK#38
See Also
VEShape.GetPhotoURL Method
VEShape.SetPoints Method
Sets the points of the VEShape Class object.
Syntax
VEShape.SetPoints(points);
Parameters
Parameter Description
points An array of VELatLong Class objects.
Remarks
If the SetPoints method is used to modify the shape so that it is no longer compatible with its
VEShapeType Enumeration, an exception will be thrown.
Example
VirtualEarthSDK#38
See Also
VEShape.GetPoints Method
VEShape.SetTitle Method
Sets the title of the VEShape object. This title will be displayed in the shape's info box.
Syntax
VEShape.SetTitle(title);
Parameters
Parameter Description
title A String object containing either plain text or
HTML that represents the VEShape object's
title.
292
Remarks
To customize your info box to something instead of the default plain text, you can provide your
own custom HTML by using the VEShape.SetTitle method Title parameter. The content of the
Title parameter is wrapped in a DIV tag and, along with the content defined by
VEShape.SetDescription Method (if any), forms the custom info box. See also
VEMap.ClearInfoBoxStyles Method and VEMap.SetDefaultInfoBoxStyles Method for further style
customization options.
Passing malformed HTML, or a blank string, will prevent the shape from rendering.
There is no maximum length for this String. Depending on your formatting, style settings, and
browser, it may extend beyond the visible area of the info box. Format it appropriately to avoid
this problem.
Example
VirtualEarthSDK#38
See Also
VEShape.GetTitle Method
VEShape.SetZIndex Method
Sets the z-index value for a shape.
Syntax
VEShape.SetZIndex(icon, polyshape);
Parameters
Parameter Description
icon Optional. An integer specifying the z-index for
the shape's icon (or for the pushpin if the shape
is a pushpin). If this value is null or undefined
the z-index is not changed.
polyshape Optional. An integer specifying the z-index for
the shape. This parameter is ignored if the
shape is a pushpin. If this value is null or
undefined the z-index is not changed.
Remarks
Although both parameters are optional, at least one parameter must be supplied.
Z-indices define the order in which items are drawn. Shapes with higher z-indices are drawn on
top of shapes with lower z-indices.
293
All shapes have the same default z-index. 1000 for icon and 50 for polyshape. The following table
lists the z-indices for most objects.
Object Z-Index
Shape Icon 1000
Route Icon 998
ERO
ERO Progress Bar
500
Disambiguation Box
Message box
201
Find control 199
Dashboard
Minimap
100
Route line 60
Shape Polyshape 50
Copyright
Scalebar
31 or 30
Logo 30
Traffic tiles 2
Custom tiles
Map
Road/Aerial/Hybrid tiles
1
VE Container 0
Examples
VirtualEarthSDK#46
See Also
VEShape.GetZIndex Method
VEShape.GetZIndexPolyShape Method
VEShape.Show Method
Makes the specified VEShape object visible. This method only has an effect if the object was
previously hidden using the VEShape.Hide Method.
Syntax
294
VEShape.Show();
Example
VirtualEarthSDK#7
See Also
VEShape.Hide Method
VEShape.ShowIcon Method
Shows the icon associated with a polyline or polygon. This method is ignored for pushpins.
Syntax
VEShape.ShowIcon();
Remarks
The associated icon is either the object's default icon, or its icon set by the
VEShape.SetCustomIcon Method method.
Example
VirtualEarthSDK#39
See Also
VEShape.HideIcon Method
VEShape Properties
The properties of the VEShape class are listed here. For a complete list of VEShape class
members, see the VEShape Class topic.
Public Properties
Name Description
VEShape.Draggable Property A Boolean value indicating whether the
VEShape icon on the map can be dragged
using the mouse.
VEShape.Draggable Property
A Boolean value indicating whether the VEShape icon on the map can be dragged using the
mouse.
Syntax
VEShape.Draggable = value;
Remarks
The default value of the Draggable property is false.
295
Pushpins and the icons corresponding to polygons and polylines are can be dragged. However,
polygon lines and polyline lines cannot be dragged.
Example
VirtualEarthSDK#65
See Also
VEShape.onstartdrag Event
VEShape.ondrag Event
VEShape.onenddrag Event
VEShapeLayer Class
Contains information about shape layers. Shape layers are a mechanism to create and manage
arbitrary groups of shapes (pushpines, polylines, and polygons). Map shape layers can be
created from GeoRSS XML files, custom map tiles, or from any public Bing Maps
(http://maps.live.com) collection.
Constructor
Name Description
VEShapeLayer Constructor Initializes a new instance of the VEShapeLayer
object.
Public Methods
Name Description
VEShapeLayer.AddShape Method Adds an existing VEShape Class object to
the layer based on the specified VEShape
reference.
VEShapeLayer.DeleteAllShapes Method Deletes all VEShape objects from the layer.
VEShapeLayer.DeleteShape Method Deletes a VEShape object from the current
layer.
VEShapeLayer.GetBoundingRectangle
Method
Returns a best-fit VELatLongRectangle
Class object based on the shapes
currently present in the layer.
VEShapeLayer.GetClusteredShapes Method Returns an array of
VEClusterSpecification Class objects
representing the calculated pushpin
296
Name Description
clusters.
VEShapeLayer.GetDescription Method A String object containing the description
of the VEShapeLayer object.
VEShapeLayer.GetShapeByID Method Retrieves a reference to a VEShape object
contained in this layer based on the specified ID.
VEShapeLayer.GetShapeByIndex Method Retrieves a reference to a VEShape object
contained in this layer based on the specified
index.
VEShapeLayer.GetShapeCount Method Returns the total number of shapes in the
current layer.
VEShapeLayer.GetTitle Method Gets the title of the VEShapeLayer
object.
VEShapeLayer.IsVisible Method Returns whether the layer is visible.
VEShapeLayer.Hide Method Hides the layer from view on the map.
VEShapeLayer.SetClusteringConfiguration
Method
Sets the method for determining which
pushpins are clustered as well as how the
cluster is displayed.
VEShapeLayer.SetDescription Method Sets the description of the
VEShapeLayer object.
VEShapeLayer.SetTitle Method Sets the title of the VEShapeLayer
object.
VEShapeLayer.Show Method Shows the layer on the map.
See Also
VEShapeType Enumeration
VEShape Class
VEShapeLayer Constructor
Initializes a new instance of the VEShapeLayer class.
Syntax
var x = new VEShapeLayer();
297
Remarks
Creates a new layer, which can then be added to the map using VEMap.AddShapeLayer Method.
See Also
VEShape Class
VEShapeLayer Methods
The methods of the VEShapeLayer class are listed here. For a complete list of VEShapeLayer
class members, see the VEShapeLayer Class topic.
Public Methods
Name Description
VEShapeLayer.AddShape Method Adds an existing VEShape Class object to
the layer based on the specified VEShape
reference.
VEShapeLayer.DeleteAllShapes Method Deletes all VEShape objects from the layer.
VEShapeLayer.DeleteShape Method Deletes a VEShape object from the current
layer.
VEShapeLayer.GetBoundingRectangle
Method
Returns a best-fit VELatLongRectangle
Class object based on the shapes
currently present in the layer.
VEShapeLayer.GetClusteredShapes Method Returns an array of
VEClusterSpecification Class objects
representing the calculated pushpin
clusters.
VEShapeLayer.GetDescription Method A String object containing the description
of the VEShapeLayer object.
VEShapeLayer.GetShapeByID Method Retrieves a reference to a VEShape object
contained in this layer based on the specified ID.
VEShapeLayer.GetShapeByIndex Method Retrieves a reference to a VEShape object
contained in this layer based on the specified
index.
VEShapeLayer.GetShapeCount Method Returns the total number of shapes in the
current layer.
VEShapeLayer.GetTitle Method Gets the title of the VEShapeLayer
object.
298
Name Description
VEShapeLayer.IsVisible Method Returns whether the layer is visible.
VEShapeLayer.Hide Method Hides the layer from view on the map.
VEShapeLayer.SetClusteringConfiguration
Method
Sets the method for determining which
pushpins are clustered as well as how the
cluster is displayed.
VEShapeLayer.SetDescription Method Sets the description of the
VEShapeLayer object.
VEShapeLayer.SetTitle Method Sets the title of the VEShapeLayer
object.
VEShapeLayer.Show Method Shows the layer on the map.
See Also
VEShape Class
VEShapeType Enumeration
VEShapeLayer.AddShape Method
Adds a VEShape Class object or array of VEShape objects to the layer.
Syntax
VEShapeLayer.AddShape(shape);
Parameters
Parameter Description
Shape The VEShape object or array of VEShape
objects to be added. Required.
Remarks
The shape parameter can be a single pushpin, polyline, or polygon, or an array of pushpins. You
must add the VEShapeLayer to the map before calling this method, otherwise, the shapes are
added one-by-one. If the map is in 3D mode, the shapes are added one-by-one. If the map has
been redrawn, shapes are added one-by-one. If a shape with the same internal identifier already
exists in the layer, this method throws an exception.
Example
VirtualEarthSDK#23
See Also
299
VEShapeLayer.DeleteShape Method
VEShapeLayer.DeleteAllShapes Method
VEShapeLayer.DeleteAllShapes Method
Deletes all VEShape Class objects (pushpins, polylines, and polygons) from the layer.
Syntax
VEShapeLayer.DeleteAllShapes();
Remarks
Valid Shape objects are pushpin, polyline, or polygon.
Example
VirtualEarthSDK#23
See Also
VEShapeLayer.AddShape Method
VEShapeLayer.DeleteShape Method
Deletes a VEShape Class object from the current layer.
Syntax
VEShapeLayer.DeleteShape(shape);
Parameters
Parameter Description
shape A reference to the VEShape object to delete.
Required.
Remarks
Valid Shape objects are pushpin, polyline, or polygon.
Example
VirtualEarthSDK#23
See Also
VEShapeLayer.AddShape Method
VEShapeLayer.GetBoundingRectangle Method
Returns a best-fit VELatLongRectangle Class object based on the shapes currently present in the
layer.
Syntax
300
VEShapeLayer.GetBoundingRectangle();
Returns
A best-fit VELatLongRectangle object based on the shapes currently present in the layer.
Remarks
This can be used with VEMap.SetMapView Method to change the current map view to the best-fit
view for the shapes in this layer.
Example
VirtualEarthSDK#23
VEShapeLayer.GetClusteredShapes Method
Returns an array of VEClusterSpecification Class objects representing the calculated pushpin
clusters.
Syntax
VEShapeLayer.GetClusteredShapes(type);
Parameters
Parameter Description
type A VEClusteringType Enumeration specifying
the algorithm used to determine which pushpins
to cluster.
Return Value
An array of VEClusterSpecification Class objects that represent the pushpin clusters of the shape
layer.
Remarks
The GetClusteredShapes method can be used to calculate the pushpin clusters before
clustering is set.
Example
VirtualEarthSDK#58
See Also
VEClusterSpecification.GetClusterShape Method
VEShapeLayer.GetDescription Method
Gets the description of the VEShapeLayer object.
Syntax
VEShapeLayer.GetDescription();
301
Returns
A String object containing the description of the VEShapeLayer object.
Example
VirtualEarthSDK#23
See Also
VEShapeLayer.SetDescription Method
VEShapeLayer.GetShapeByID Method
Retrieves a reference to a VEShape Class object contained in this layer based on the specified
ID.
Syntax
VEShapeLayer.GetShapeByID(ID);
Parameters
Parameter Description
ID The identifier of the VEShape object. Required.
Remarks
Returns a reference to a VEShape object, or null if the shape is not found in this layer.
Example
VirtualEarthSDK#38
See Also
VEShapeLayer.AddShape Method
VEShapeLayer.DeleteShape Method
VEShapeLayer.GetShapeByIndex Method
Retrieves a reference to a VEShape Class object contained in this layer based on the specified
index.
Syntax
VEShapeLayer.GetShapeByIndex(index);
Parameters
Parameter Description
index The index of the shape to retrieve. Required.
Returns
302
A reference to a VEShape object, or null if no shape with the specified index exists in this layer.
Example
VirtualEarthSDK#23
VEShapeLayer.GetShapeCount Method
Returns the total number of shapes in the current layer.
Syntax
VEShapeLayer.GetShapeCount();
Returns
An integer representing the total number of shapes in the current layer.
Example
VirtualEarthSDK#23
See Also
VEShape Class
VEShapeLayer.GetTitle Method
Gets the title of the VEShapeLayer Class object.
Syntax
VEShapeLayer.GetTitle();
Returns
A String object representing the title of the VEShapeLayer object.
Example
VirtualEarthSDK#23
See Also
VEShapeLayer.SetTitle Method
VEShapeLayer.Hide Method
Hides the layer from view on the map.
Syntax
VEShapeLayer.Hide();
Remarks
If the layer has not yet been added to the map when this method is called, it will be invisible as
soon as it is added.
Example
303
VirtualEarthSDK#23
See Also
VEShapeLayer.IsVisible Method
VEShapeLayer.Show Method
VEShapeLayer.IsVisible Method
Returns whether the layer is visible.
Syntax
VEShapeLayer.IsVisible();
Return Value
Returns true if the layer is visible, otherwise returns false.
Example
VirtualEarthSDK#23
See Also
VEShapeLayer.Hide Method
VEShapeLayer.Show Method
VEShapeLayer.SetClusteringConfiguration Method
Sets the method for determining which pushpins are clustered as well as how the cluster is
displayed.
Overload List
Method Description
VEShapeLayer.SetClusteringConfiguration(type,
options) Method
Sets the method for determining which
pushpins are clustered as well as how the
cluster is displayed.
VEShapeLayer.SetClusteringConfiguration(algorithm,
options) Method
Sets the algorithm for determining which
pushpins are clustered as well as how the
cluster is displayed.
See Also
VEShapeLayer.GetClusteredShapes Method
VEShapeLayer.SetClusteringConfiguration(type, options) Method
Sets the method for determining which pushpins are clustered as well as how the cluster is
displayed.
Syntax
304
VEShapeLayer.SetClusteringConfiguration(type, options);
Parameters
Name Description
type A VEClusteringType Enumeration specifying
which shapes to cluster. Required.
options A VEClusteringOptions Class object specifying
how the pushpin cluster is displayed. Optional.
Remarks
If the VEClusteringOptions.Icon Property is specified, it is used to display clustered icons. If the
Icon property is not specified, the default cluster icon is used.
The SetClusteringConfiguration settings are used when the map is panned, zoomed, or shapes
are added or removed from the shape layer.
If clustering is configured for the shape layer, then shapes created by importing data into the
shape layer using the VEMap.ImportShapeLayerData Method are clustered.
The SetClusteringConfiguration settings are ignored when the map mode is set to
VEMapMode.Mode3D.
Example
VirtualEarthSDK#58
See Also
VEShapeLayer.SetClusteringConfiguration(algorithm, options) Method
VEShapeLayer.SetClusteringConfiguration(algorithm, options) Method
Sets the algorithm for determining which pushpins are clustered as well as how the cluster is
displayed.
Syntax
VEShapeLayer.SetClusteringConfiguration(algorithm, options);
Parameters
Name Description
algorithm The name of the function used to determine
which pushpins are clustered. The function
must accept a VEShapeLayer Class object and
return an array of VEClusterSpecification Class
objects. Required.
options A VEClusteringOptions Class object specifying
305
Name Description
how the pushpin cluster is displayed. Optional.
Remarks
If the VEClusteringOptions.Icon Property is specified, it is used to display clustered icons. If the
Icon property is not specified, the default cluster icon is used.
The SetClusteringConfiguration settings are used when the map is panned, zoomed, or shapes
are added or removed from the shape layer.
If clustering is configured for the shape layer, then shapes created by importing data into the
shape layer using the VEMap.ImportShapeLayerData Method are clustered.
The SetClusteringConfiguration settings are ignored when the map mode is set to
VEMapMode.Mode3D.
See Also
VEShapeLayer.SetClusteringConfiguration(type, options) Method
VEShapeLayer.SetDescription Method
Sets the description of the VEShapeLayer object.
Syntax
VEShapeLayer.SetDescription(details);
Parameters
Parameter Description
details A String object containing either plain text or
HTML that represents the VEShapeLayer
object's description field.
Example
VirtualEarthSDK#23
See Also
VEShapeLayer.GetDescription Method
VEShapeLayer.SetTitle Method
Sets the title of the VEShapeLayer object.
Syntax
VEShapeLayer.SetTitle(title);
Parameters
306
Parameter Description
title A String object containing either plain text or
HTML that represents the VEShapeLayer
object's title.
Example
VirtualEarthSDK#23
See Also
VEShapeLayer.GetTitle Method
VEShapeLayer.Show Method
Shows the layer on the map.
Syntax
VEShapeLayer.Show();
Remarks
If the layer has not yet been added to the map when this method is called, it will be visible as
soon as it is added.
Example
VirtualEarthSDK#23
See Also
VEShapeLayer.Hide Method
VEShapeLayer.IsVisible Method
VEShapeAccuracy Enumeration
Specifies the accuracy of shape conversions when the map style is changed to birdseye.
Syntax
VEShapeAccuracy{ None Pushpin }
Members
Member Description
None No shapes are accurately converted
Pushpin Only pushpins are accurately converted
307
Remarks
Shape conversion is also limited by the number of shapes (see
VEMap.SetShapesAccuracyRequestLimit Method).
See Also
VEMap.SetShapesAccuracy Method
VEShapeSourceSpecification Class
Defines the specification for importing VEShape Class objects to the map.
Constructor
Name Description
VEShapeSourceSpecification Constructor Initializes a new instance of the
VEShapeSourceSpecification object.
Public Properties
Name Description
VEShapeSourceSpecification.Layer Property A VEShapeLayer Class object in which the
VEShape objects are contained after
importing.
VEShapeSourceSpecification.LayerSource
Property
A String specifying the layer source.
VEShapeSourceSpecification.MaxImportedShapes
Property
Specifies the maximum number of items that
can be imported from an XML file. The
default value is 200.
VEShapeSourceSpecification.Type Property A VEDataType Enumeration value defining
the type of data to be imported into a shape
layer.
See Also
VEMap Class
VEMap.ImportShapeLayerData Method
308
VEShape Class
VEShapeLayer Class
VEShapeSourceSpecification Constructor
Initializes a new instance of the VEShapeSourceSpecification class.
Syntax
var x = new VEShapeSourceSpecification (dataType, dataSource, layer);
Parameters
Parameter Description
dataType A VEDataType Enumeration that specifies the
type of data to import. Required.
dataSource A URL representing the GeoRSS feed or KML
data, or a globally-unique identifier (GUID)
representing the Live Maps collection.
Required.
layer A VEShapeLayer Class object in which the
VEShape objects are contained after importing.
If this parameter value is null, the VEShape
objects are added to the base layer.
Remarks
See Also
VEMap.ImportShapeLayerData Method
VEShapeSourceSpecification.Layer Property
VEShapeSourceSpecification.LayerSource Property
VEShapeSourceSpecification.Type Property
VEShapeSourceSpecification Properties
The public properties of the VEShapeSourceSpecification Class are described here.
Public Properties
Name Description
VEShapeSourceSpecification.Layer Property A VEShapeLayer Class object in which the
309
Name Description
VEShape Class objects are contained after
importing.
VEShapeSourceSpecification.LayerSource
Property
A String specifying the layer source.
VEShapeSourceSpecification.MaxImportedShapes
Property
Specifies the maximum number of items that
can be imported from an XML file. The
default value is 200.
VEShapeSourceSpecification.Type Property A VEDataType Enumeration value defining
the type of data to be imported into a shape
layer.
VEShapeSourceSpecification.Layer Property
A VEShapeLayer Class object in which the VEShape Class objects are contained after importing.
Syntax
VEShapeSourceSpecification.Layer = new VEShapeLayer();
VEShapeSourceSpecification.LayerSource Property
A String specifying the layer source.
Syntax
VEShapeSourceSpecification.LayerSource = source;
Remarks
The source value must agree with the VEShapeSourceSpecification.Type Property value. If Type
is VEDataType.GeoRSS or VEDataType.ImportXML, the source value must be a URL and
cannot be a reference to a local file, such as ./myfile. If Type is VEDataType.VECollection, the
source value must be a collection ID from http://maps.live.com.
VEShapeSourceSpecification.MaxImportedShapes Property
Specifies the maximum number of items that can be imported from an XML file. The default value
is 200.
Syntax
VEShapeSourceSpecification.MaxImportedShapes = value;
See Also
VEMap.ImportShapeLayerData Method
310
VEDataType Enumeration
VEShapeSourceSpecification.Type Property
A VEDataType Enumeration value defining the type of data to be imported into a shape layer.
Syntax
VEShapeSourceSpecification.Type = VEDataType.VECollection;
VEShapeType Enumeration
An enumeration of the available Shape types.
Syntax
VEShapeType{ Pushpin Polyline Polygon }
Members
Member Description
Pushpin This represents a Shape object that is a
pushpin.
Polyline This represents a Shape object that is a
polyline.
Polygon This represents a Shape object that is a
polygon.
Remarks
This enumeration represents the Shape type for a VEShape Class object.
See Also
VEShapeLayer Class
VETileSourceSpecification Class
Contains information about a custom map tile source.
Constructor
311
Name Description
VETileSourceSpecification Constructor Initializes a new instance of the
VETileSourceSpecification object.
Public Properties
Name Description
VETileSourceSpecification.Bounds Property An array of VELatLongRectangle Class objects
that specifies the approximate coverage area of
the layer.
VETileSourceSpecification.ID Property The unique identifier for the layer. Each tile
layer on a map must have a unique ID.
VETileSourceSpecification.MaxZoomLevel
Property
The maximum zoom level at which to display
the custom tile source.
VETileSourceSpecification.MinZoomLevel
Property
The minimum zoom level at which to display
the custom tile source.
VETileSourceSpecification.NumServers
Property
The number of servers on which the tiles are
hosted.
VETileSourceSpecification.Opacity Property Specifies the opacity level of the tiles when
displayed on the map.
VETileSourceSpecification.TileSource Property The location of the tiles.
VETileSourceSpecification.ZIndex Property Specifies the z-index for the tiles.
VETileSourceSpecification Constructor
Initializes a new instance of the VETileSourceSpecification class.
Syntax
var x = new VETileSourceSpecification(tileSourceId, tileSource, numServers, bounds, minZoom,
maxZoom, getTilePath, opacity, zindex);
Parameters
Parameter Description
tileSourceId A unique identifier for the layer. Each layer on a
312
Parameter Description
map must have a unique Identifier. Required.
tileSource The location of the tiles. Required. Information
about the format of the tile source URL is found
in the VETileSourceSpecification.TileSource
Property topic.
numServers The number of servers on which the tiles are
hosted. Optional. The default value is 1.
bounds An array of VELatLongRectangle Class objects
that specifies the approximate coverage area of
the layer. Optional.
minZoom The minimum zoom level at which to display
the custom tile source. Optional.
maxZoom The maximum zoom level at which to display
the custom tile source. Optional.
getTilePath When viewing a map in 2D mode, the function
that determines the correct file names for the
tiles. Optional.
opacity The opacity level of the tiles when displayed on
the map. Optional.
zindex The z-index value for the tiles. Optional.
VETileSourceSpecification Properties
The properties of the VETileSourceSpecification class are listed here. For a complete list of
VETileSourceSpecification class members, see the VETileSourceSpecification Class topic.
Public Properties
Name Description
VETileSourceSpecification.Bounds Property An array of VELatLongRectangle Class objects
that specifies the approximate coverage area of
the layer.
VETileSourceSpecification.ID Property The unique identifier for the layer. Each tile
layer on a map must have a unique ID.
VETileSourceSpecification.MaxZoomLevel
Property
The maximum zoom level at which to display
the custom tile source.
313
Name Description
VETileSourceSpecification.MinZoomLevel
Property
The minimum zoom level at which to display
the custom tile source.
VETileSourceSpecification.NumServers
Property
The number of servers on which the tiles are
hosted.
VETileSourceSpecification.Opacity Property Specifies the opacity level of the tiles when
displayed on the map.
VETileSourceSpecification.TileSource Property The location of the tiles.
VETileSourceSpecification.ZIndex Property Specifies the z-index for the tiles.
See Also
VETileContext Class
VETileSourceSpecification.Bounds Property
Specifies an array of VELatLongRectangle Class objects that specifies the approximate coverage
area of the layer.
Syntax
VETileSourceSpecification.Bounds = value;
Remarks
Set the Bounds property to an array of VELatLongRectangle Class objects.
Use the Bounds property, the VETileSourceSpecification.MinZoomLevel Property, and the
VETileSourceSpecification.MaxZoomLevel Property to improve Web site performance. The tile
layer is not added to the map unless the map is currently displaying the area that the Bounds
property specifies, and the zoom level of the map is between the values that the MinZoomLevel
and MaxZoomLevel properties specify.
VETileSourceSpecification.GetTilePath Property
When viewing a map in 2D mode, this property specifies the function that determines the correct
file names for your tiles.
Syntax
VETileSourceSpecification.GetTilePath = value;
Remarks
If you have created your own tile set and are using a tile naming convention other than the
standard Bing Maps tile naming convention, you must create a function that returns the correct
file names for your tiles. The GetTilePath property specifies this function.
314
Custom tile naming is currently not supported in 3D map mode. This feature only works
when the map mode is set to MapMode.2D.
When you use the GetTilePath property, the VETileSourceSpecification.NumServers Property
and VETileSourceSpecification.TileSource Property are ignored.
For more information about creating custom tiles and the standard naming convention, see
Working with Tile Layers.
VETileSourceSpecification.ID Property
Specifies a unique identifier for the layer. Each layer on a map must have a unique Identifier.
Required.
Syntax
VETileSourceSpecification.ID = value;
Remarks
VETileSourceSpecification.MaxZoomLevel Property
Specifies the maximum zoom level at which to display the custom tile source.
Syntax
VETileSourceSpecification.MaxZoom = value;
Remarks
Use the VETileSourceSpecification.Bounds Property, the
VETileSourceSpecification.MinZoomLevel Property, and the MaxZoom property to improve Web
site performance. The tile layer is not added to the map unless the map is currently displaying the
area that the Bounds property specifies, and the zoom level of the map is between the values
that the MinZoom and MaxZoom properties specify.
VETileSourceSpecification.MinZoomLevel Property
Specifies the minimum zoom level at which to display the custom tile source.
Syntax
VETileSourceSpecification.MinZoomLevel = value;
Remarks
Use the VETileSourceSpecification.Bounds Property, the MinZoomLevel property, and the
VETileSourceSpecification.MaxZoomLevel Property to improve Web site performance. The tile
layer is not added to the map unless the map is currently displaying the area that the Bounds
property specifies, and the zoom level of the map is between the values that the MinZoomLevel
and MaxZoomLevel properties specify.
315
VETileSourceSpecification.NumServers Property
Specifies the number of servers on which the tiles are hosted.
Syntax
VETileSourceSpecification.NumServers = value;
Remarks
The VETileSourceSpecification.NumServers property is optional. The default value is 1. Use
this property if your tile server uses more than one server.
VETileSourceSpecification.Opacity Property
Specifies the opacity level of the tiles when displayed on the map.
Syntax
VETileSourceSpecification.Opacity = value;
Remarks
This property is optional. The default value is 1.0.
VETileSourceSpecification.TileSource Property
Specifies the location of the tiles.
Syntax
VETileSourceSpecification.TileSource = value;
Remarks
The value you specify for the TileSource property must be a valid URL. However, you can use 3
variables in the URL to specify the map mode with which to associate tiles, the number of servers
that host the tiles, and a variable to retrieve the individual file names of tiles. The variables you
can use are:
%1—this parameter specifies the map style to associate with your customer tiles. For
example, if your tile file names begin with "r", the custom tiles will only be displayed if the map
style is set to "road". Valid values are r, h, and a.
%2—if you are using more than one server for load-balancing, this parameter is used in
conjunction with the VETileSourceSpecification.NumServers Property to cycle through the tile
servers.
%4—the quadkey of the tile. This variable cycles through the file names.
For example, suppose you have three servers named TileServer0, TileServer1, and TileServer2
that host your tiles. You have a set of custom tiles that you only want to display when the map
style is set to aerial. The tile names follow the standard Bing Maps naming convention, are
preceded by the letter a, and are all .png files (for example, "a00245676.png"). You should set
the TileSource property to http://TileServer%2/MyTiles/%1%4.png and the
VETileSourceSpecification.NumServers Property to 3.
316
The %2 variable cycles through integer values, beginning with 0 and ending after the number of
cycles that the NumServers property specifies. The %4 variable uses the standard Bing Maps
naming convention. The %1 variable filters the results so that tiles will only display when the map
style is set to aerial.
See Also
Bing Maps Tile System
VETileSourceSpecification.ZIndex Property
Specifies the zIndex value for the tiles.
Syntax
VETileSourceSpecification.ZIndex = value;
Remarks
This property is optional.
Bing Maps AJAX Control Troubleshooting and Support This topic contains information about common problems that arise when developing applications
using the Bing Maps AJAX Control 6.3.
Rendering Issues
Supported Browsers
Proxy Authentication Errors
Printing Issues
Bing Maps Developer Resources and Support
Rendering Issues
The following solutions may help if you are experiencing issues downloading or rendering the
map control.
If the map control is not downloading properly, the script tag src attribute of your page may
not be set correctly. Make sure you are referencing the map control correctly using
http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.3.
If the map is not rendering properly, note that version 6.0 and higher of the map control
supports the correct method of setting the page height to 100% by using an absolute height
attribute in the body tag. The previous versions of the map control did not require this setting.
Users upgrading to this version of the map control should change the body tag to the
following to render the page at 100%.
<body style="position:absolute;width:100%;height:100%;" …
If the map is not rendering properly, check that you have specified DOCTYPE at the
beginning of your HTML page.
317
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
If routes are not displaying on the map, check that charset is set to UTF-8 in the meta tag of
your HTML page.
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
Supported Browsers
The latest version of the Bing Maps AJAX Control 6.3 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.
Browser Version 6.3, Full Version 6.3, Core
Internet Explorer 7.0 Supported on the PC Supported on the PC
Internet Explorer 8.0 Supported on the PC Supported on the PC
Internet Explorer 9.0 Supported on the PC Supported on the PC
Firefox 2.0 Supported on the PC Not supported
Firefox 3.0 Supported on the PC Not supported
Firefox 3.5 Supported on the PC Supported on the PC
Firefox 3.6 Supported on the PC Supported on the PC
Firefox 4.0 Supported on the PC Supported on the PC
Safari 2 Supported on the Mac Not supported
Safari 3 Supported on the Mac Not supported
Safari 4 Supported on the Mac Supported on the Mac
Google Chrome Supported on the PC Supported on the PC
Remarks
Routes do not display in Safari 2.0.
Proxy Authentication Errors
If you receive a proxy authentication error (HTTP status code 407) when executing certain calls to
the map control, check your proxy settings in Internet Explorer or in Windows.
To check your proxy setting in Internet Explorer, click Tools, Internet Options. Select the
Connections tab and click the LAN Settings button. Under the Proxy server section, set
the Address and Port values.
318
To check your proxy setting in Windows, click Start, Control Panel, Internet Options. Select
the Connections tab and click the LAN Settings button. Under the Proxy server section,
set the Address and Port values.
Printing Issues
If your map is not printing correctly, one of the following solutions may help:
Enable Printing
Before you can print the map, set the VEPrintOptions.EnablePrinting Property to true, and pass
the VEPrintOptions object to the VEMap.SetPrintOptions Method to enable printing. Make sure
you do this only once you are ready to print, as setting this property to true may cause a
decrease in the performance of the map control.
Turn on the Print Backgrounds browser option
To properly print all of the items on the map, the Print Backgrounds setting must be selected.
This option is not turned on by default.
In Internet Explorer browsers:
Select the Tools menu.
Select the Internet Options menu item.
Go to the Advanced Settings tab.
Check the Print Backgrounds item under Printing.
In Firefox browsers:
Select the File menu.
Select the Page Setup menu item.
Go to the Format and Options tab.
Check Print Backgrounds.
In Safari browsers:
Select the File menu.
Select the Print menu item.
Click on the Copies & Pages drop-down box.
Select Safari.
Check Print Backgrounds.
Notes about printing certain features
Copyright. The copyright on the map prints with a white background, unless the Web
browser print background setting is false.
Scale Bar. The scale bar color will not print if the Web browser print background setting is
false.
319
Map control dashboard. The map control dashboard, which includes the map navigation
controls and map style settings, does not print.
Find control. If you have used the VEMap.ShowFindControl Method to show the find
control, this control will not print.
Find disambiguation box. The disambiguation box that appears when you have requested
that ambiguous search results appear does not print.
Information boxes. If you use your mouse pointer to hover over pushpins or steps along a
route, a box will appear that contains pushpin property details or route instruction text. These
information boxes do not print.
Tile opacity. User specified tile opacity will not be printed.
Image opacity. Image opacity does not print when using Internet Explorer 7.
Pushpin transparency. Pushpin transparency does not always print.
Shapes when DPI is 120. When your display is set to 120DPI, shapes do not print properly
when Internet Explorer is your Web browser.
Developer Resources and Support
Developer Resources
The following resources are available for Bing Maps developers:
View the Bing Maps Interactive SDK.
Connect with other Bing Maps developers on the Bing Maps Forum.
Visit the http://www.microsoft.com/maps website.
Read the following blogs:
Bing Maps Developer blog
Bing
Account Access Issues
If you are using the Bing Maps Token Service to track your map control usage and you are
experiencing issues with your Bing Maps Customer Services site user name and password, or
with your Bing Maps Developer Account ID and password, contact the Bing Maps Account
Administrator.
Note Support for Bing Maps account access issues is available only through e-mail. E-mail
messages are answered within two business days.
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/contact.aspx. From
North, Central, and South America, you can also contact Bing Maps by calling (800) 426-9400,
ext. 11315.
