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

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

13

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

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

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 TM users easy access to search functionality by enabling the Bing 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 VEMap.Geocode Method

Contains additional geocoding options for the VEMap.Geocode Method. Finds a geographic location based on a specified address or place name string as well as other geocoding options.
16

Name

Description

VEMap.Search Method VEMapOptions.DashboardColor Property

Performs a search based on a given query and options. 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. A Boolean value indicating whether the Bing logo on the map is clickable. The default value is false. A Boolean value indicating whether to enable TM the Bing hovering search logo on the map. The default value is false. A Boolean value indicating whether to use the enhanced road map style. The default value is false. Contains additional search options for the VEMap.Search Method. A Boolean value indicating whether the VEShape icon on the map can be dragged using the mouse. Occurs when a shape is being dragged across the map. Occurs when a shape drag has stopped. Occurs when the user starts dragging the shape.
TM

VEMapOptions.EnableClickableLogo Property

VEMapOptions.EnableSearchLogo Property

VEMapOptions.UseEnhancedRoadStyle Property VESearchOptions Class VEShape.Draggable Property

VEShape.ondrag Event VEShape.onenddrag Event VEShape.onstartdrag Event

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
17

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=utf8">

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

18

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

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

<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&center=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}&center={c enter}&heading={heading}&pushpins={pushpins}&culture={culture}

21

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 An int indicating a valid zoom level for the map style. Two doubles separated by an underscore that are the latitude and longitude values of the coordinate of the center of the map. A double specifying the orientation of the map in degrees. 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 ~. A valid culture string. The default value is enus.

zoomLevel center

heading pushpins

culture

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.

22

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

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

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

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),
26

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 27

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 var turns var leg var turnNum = route.RouteLegs; = "Turn-by-Turn Directions\n"; = null; = 0; // The turn # // The sum of all leg distances

var totalDistance = 0;

// 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 // The distance for this leg

var legDistance = null;

for(var j = 0; j < leg.Itinerary.Items.length; j ++) { turnNum++; // turn is a VERouteItineraryItem object 28

turn = leg.Itinerary.Items[j]; turns += turnNum + ": legDistance " + turn.Text;

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

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.

30

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

31

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

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

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. Specifies the market to use, which defines the language Bing Maps uses. The default value is "en-US" (English). Specifies the name of a JavaScript function to call when the map control script is loaded. The name must contain only alphanumeric characters. 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
33

mkt

See the Returning Localized Results topic for a list of values. A string specifying a function name.

onscriptload

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=frfr"></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.
34

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 Danish - Denmark Dutch - Belgium Dutch - Netherlands English - Australia English - Canada

cs-CZ da-DK nl-BE nl-NL en-AU en-CA

VEMap.Find, VEMap.GetDirections VEMap.Find, VEMap.GetDirections Map labels VEMap.Find, VEMap.GetDirections VEMap.GetDirections using MWS Map control dashboard, VEMap.Find, VEMap.GetDirections using MWS VEMap.GetDirections using MWS* VEMap.GetDirections using MWS All features. This is the default culture. VEMap.Find, VEMap.GetDirections Map control dashboard, 3D dialogs, VEMap.Find, VEMap.GetDirections, map labels Map control dashboard, 3D dialogs, VEMap.Find, VEMap.GetDirections, map labels Map control dashboard,
35

English - India* English - United Kingdom English - United States Finnish -Finland French - Canada

en-IN* en-GB en-US fi-FI fr-CA

French - France

fr-FR

German - Germany

de-DE

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 Map control dashboard, 3D dialogs, VEMap.Find, map labels VEMap.Find, VEMap.GetDirections VEMap.Find, VEMap.GetDirections VEMap.Find, VEMap.GetDirections VEMap.GetDirections using MWS, map labels Map control dashboard, VEMap.Find, VEMap.GetDirections, map labels Map control dashboard, VEMap.Find, VEMap.GetDirections using MWS, map labels VEMap.Find, VEMap.GetDirections

Japanese - Japan Norwegian (Bokmal) - Norway Portuguese - Brazil Portuguese - Portugal Spanish - Mexico Spanish - Spain

ja-JP nb-NO Pt-BR pt-PT es-MX es-ES

Spanish - United States

es-US

Swedish - Sweden

sv-SE

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

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

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 Microsofts 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=enus"></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.
38

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

39

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=enus"></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 VEException Class VELatLong Class VELatLongRectangle Class VEMap Class VEMapOptions Class VEMapStyle Enumeration VEMapViewSpecification Class VEPixel Class VEShape Class

All members are supported. All members are supported. All members are supported. All members are supported. Supported members are listed in the VEMap member tables below. All members are supported. All members are supported. All members are supported. All members are supported. Supported members are listed in the VEShape member tables below.
40

Type

Supported Members

VEShapeLayer Class VEShapeType Enumeration VETileSourceSpecification Class

Supported members are listed in the VEShapeLayer member tables below. VEShapeType.Pushpin 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 Public Events

Name

Initializes a new instance of the VEMap Class.

Description

VEMap.onkeypress Event VEMap.onkeydown Event VEMap.onkeyup Event VEMap.onclick Event VEMap.ondoubleclick Event VEMap.onmousedown Event VEMap.onmousemove Event VEMap.onmouseout Event VEMap.onmouseover Event VEMap.onmouseup Event VEMap.onmousewheel Event

Occurs when a key is pressed and released. Occurs when a key is pressed (but before it is released). Occurs when a key is released. Occurs when a left or right mouse button is single-clicked. Occurs when a left mouse button is doubleclicked. Occurs when a mouse button (left, right, or middle) is clicked (but before it is released). Occurs when the mouse cursor moves. Occurs when the mouse cursor moves away from a VEShape object. Occurs when the mouse cursor moves over a VEShape Class object. Occurs when a mouse button (left, right, or middle) is released. Occurs when the mouse wheel is moved.
41

Name

Description

VEMap.onchangemapstyle Event VEMap.onchangeview Event VEMap.oncredentialserror Event

Occurs when the map style changes. Occurs whenever the map view changes. 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. 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. Occurs when a pan of the map ends. Occurs when the map zoom ends. Occurs when there is a map control error. Occurs after the map mode changes and the map has reloaded. Occurs when the map is resized. Occurs when a pan of the map begins. Occurs when the map zoom begins.

VEMap.oncredentialsvalid Event

VEMap.onendpan Event VEMap.onendzoom Event VEMap.onerror Event VEMap.oninitmode Event VEMap.onresize Event VEMap.onstartpan Event VEMap.onstartzoom Event Public Methods
Name

Description

VEMap.AddControl Method VEMap.AddCustomLayer Method VEMap.AddShape Method

Adds a custom control to the map. Adds a custom layer to the map. 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. Adds the specified shape layer to the map. Adds a tile layer to the map, and if the visibleOnLoad parameter is true, it also shows
42

VEMap.AddShapeLayer Method VEMap.AddTileLayer Method

Name

Description

it on the map. VEMap.AttachEvent Method VEMap.Clear Method Attaches a Map Control event to a specified function. Removes all shapes, shape layers, and search results on the map. Also removes the route from the map, if one is displayed. Clears out all of the default Bing Maps info box CSS styles. Clears the traffic map. Removes the specified control from the map. Deletes all shapes in all layers, leaving empty layers behind. Deletes all shape layers, along with any shapes within the layers. Deletes a VEShape Class object from any layer, including the base map layer. Deletes the specified shape layer from the map. Deletes a tile layer from view. Detaches the specified map control event so that it no longer calls the specified function. Deletes the VEMap object and releases any associated resources Stops the continuous map panning initiated by a call to the VEMap.StartContinuousPan Method. Returns a VELatLong Class object that represents the location of the center of the current map view. Returns the pixel value of the left edge of the map control. Returns the current map style. Returns the current map view object as a
43

VEMap.ClearInfoBoxStyles Method VEMap.ClearTraffic Method VEMap.DeleteControl Method VEMap.DeleteAllShapes Method VEMap.DeleteAllShapeLayers Method VEMap.DeleteShape Method VEMap.DeleteShapeLayer Method VEMap.DeleteTileLayer Method VEMap.DetachEvent Method VEMap.Dispose Method VEMap.EndContinuousPan Method

VEMap.GetCenter Method

VEMap.GetLeft Method VEMap.GetMapStyle Method VEMap.GetMapView Method

Name

Description

VELatLongRectangle Class object. VEMap.GetShapeByID Method VEMap.GetShapeLayerByIndex Method VEMap.GetShapeLayerCount Method VEMap.GetTileLayerByID Method VEMap.GetTileLayerByIndex Method VEMap.GetTileLayerCount Method VEMap.GetTop Method VEMap.GetVersion Method VEMap.GetZoomLevel Method VEMap.HideBaseTileLayer Method VEMap.HideControl Method VEMap.HideDashboard Method VEMap.HideInfoBox Method VEMap.HideScalebar Method VEMap.HideAllShapeLayers Method VEMap.HideTileLayer Method VEMap.HideTrafficLegend Method VEMap.IncludePointInView Method Gets the reference to a VEShape Class object based on its internal identifier. Gets the reference to a VEShapeLayer Class object based on its index. Gets the total number of shape layers on the map. Gets a tile layer based upon its identifier. Gets a tile layer based upon an index value. Gets the number of tile layers. Returns the pixel value of the top edge of the map control. Returns the current version of the map control. Returns the current zoom level of the map. Hides the base tile layer of the map. Hides the specified control from view. Hides the default user interface for controlling the map (the compass and the zoom control). Hides a shape's custom or default info box. Hides the scale bar from the map. Hides all of the shape layers on the map. Hides a tile layer from view. Hides the traffic legend. Changes the map view so that it includes both the specified VELatLong Class point and the center point of the current map. Converts an array of VELatLong Class objects (latitude/longitude pair) to an array of VEPixel Class objects. Loads the specified map. All parameters are optional.

VEMap.LatLongToPixel Method

VEMap.LoadMap Method

44

Name

Description

VEMap.LoadTraffic Method VEMap.Pan Method VEMap.PanToLatLong Method VEMap.PixelToLatLong Method

Loads the traffic map. Moves the map the specified amount. Pans the map to a specific latitude and longitude. Converts a pixel (a point on the map) to a VELatLong Class object (latitude/longitude pair). Removes a custom layer from the map. Resizes the map based on the specified width and height. Centers the map to a specific latitude and longitude. Centers the map to a specific latitude and longitude and sets the zoom level. Sets the credentials to use to authenticate map service requests. Sets the info box CSS styles back to their original classes. Sets the style of the map. 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. Specifies whether to zoom to the center of the screen or to the cursor position on the screen. Sets the distance unit (kilometers or miles) for the map scale. Sets the number of "rings" of map tiles that should be loaded outside of the visible mapview area. Specifies the text shown with the traffic legend, if visible. Sets the view of the map to the specified zoom
45

VEMap.RemoveCustomLayer Method VEMap.Resize Method VEMap.SetCenter Method VEMap.SetCenterAndZoom Method VEMap.SetCredentials Method VEMap.SetDefaultInfoBoxStyles Method VEMap.SetMapStyle Method VEMap.SetMapView Method

VEMap.SetMouseWheelZoomToCenter Method VEMap.SetScaleBarDistanceUnit Method VEMap.SetTileBuffer Method

VEMap.SetTrafficLegendText Method VEMap.SetZoomLevel Method

Name

Description

level. VEMap.ShowAllShapeLayers Method VEMap.ShowBaseTileLayer Method VEMap.ShowControl Method Shows all shape layers on the map. Shows the base tile layer of the map. Makes the specified control visible. This method only affects control elements that have been hidden from view using the VEMap.HideControl Method. Shows the default user interface for controlling the map (the compass-and-zoom control). By default, this control is shown. Shows a shape's custom or default info box. Displays the specified message in a dialog box on the map. Displays the scale bar on the map. Shows a tile layer from view. Displays the traffic legend. Moves the map in the specified direction until the VEMap.EndContinuousPan Method is called. Increases the map zoom level by 1. Decreases the map zoom level by 1.

VEMap.ShowDashboard Method

VEMap.ShowInfoBox Method VEMap.ShowMessage Method VEMap.ShowScalebar Method VEMap.ShowTileLayer Method VEMap.ShowTrafficLegend Method VEMap.StartContinuousPan Method

VEMap.ZoomIn Method VEMap.ZoomOut Method 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.

46

The core version of the map control only supports VEShape objects that are of type VEShapeType.Pushpin. Public Constructor
Name Description

VEShape Constructor Public Events

Name

Initializes a new instance of the VEShape Class.

Description

VEShape.ondrag Event VEShape.onenddrag Event VEShape.onstartdrag Event

Occurs when a shape is being dragged across the map. Occurs when a shape drag has stopped. Occurs when the user starts dragging the shape.

Public Methods
Name Description

VEShape.GetCustomIcon Method VEShape.GetDescription Method VEShape.GetIconAnchor Method VEShape.GetID Method VEShape.GetMaxZoomLevel Method VEShape.GetMinZoomLevel Method VEShape.GetPoints Method

Gets the VEShape object's custom icon. Gets the description of the VEShape object. Gets a VELatLong Class object representing the shape's custom icon anchor point. Gets the internal identifier of the VEShape object. Gets the maximum zoom level at which the shape is visible. Gets the minimum zoom level at which the shape is visible. Returns an array of VELatLong Class objects representing the points that make up the pushpin. Gets the reference to the layer containing the specified VEShape object. Gets the title of the VEShape object.
47

VEShape.GetShapeLayer Method VEShape.GetTitle Method

Name

Description

VEShape.GetType Method VEShape.GetZIndex Method VEShape.Hide Method VEShape.SetCustomIcon Method VEShape.SetDescription Method VEShape.SetIconAnchor Method VEShape.SetMaxZoomLevel Method VEShape.SetMinZoomLevel Method VEShape.SetPoints Method VEShape.SetTitle Method VEShape.SetZIndex Method VEShape.Show Method Public Properties
Name

Gets the type of the VEShape object. Gets the z-index of a pushpin shape. Hides the specified VEShape object from view. Sets the VEShape object's custom icon. Sets the description of the VEShape object. Sets the info box anchor of the VEShape object. Sets the maximum zoom level at which the shape is visible. Sets the minimum zoom level at which the shape is visible. Sets the points of the VEShape object. Sets the title of the VEShape object. Sets the z-index value for a shape. Makes the specified VEShape object visible.

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
48

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. Deletes all VEShape objects from the layer. Deletes a VEShape object from the current layer. Returns a best-fit VELatLongRectangle Class object based on the shapes currently present in the layer. Retrieves a reference to a VEShape object contained in this layer based on the specified ID. Retrieves a reference to a VEShape object contained in this layer based on the specified index. Returns the total number of shapes in the current layer. Returns whether the layer is visible. Hides the layer from view on the map. Shows the layer on the map.

VEShapeLayer.DeleteAllShapes Method VEShapeLayer.DeleteShape Method VEShapeLayer.GetBoundingRectangle Method

VEShapeLayer.GetShapeByID Method

VEShapeLayer.GetShapeByIndex Method

VEShapeLayer.GetShapeCount Method VEShapeLayer.IsVisible Method VEShapeLayer.Hide Method VEShapeLayer.Show Method

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

<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()"/>

50

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) { 51

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

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

53

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

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
55

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 Absolute RelativeToGround

The altitude is meters above ground level The altitude is meters above the WGS 84 ellipsoid 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
56

Name

Description

VEBirdseyeScene.ContainsLatLong Method

Determines whether the location specified by a VELatLong Class object is within the current VEBirdseyeScene object. Determines whether a specified pixel is within the current VEBirdseyeScene object. Returns an unencrypted and rounded off bounding rectangle for the VEBirdseyeScene object. Returns the height of the image in the current VEBirdseyeScene object, in pixels, at maximum resolution Returns the ID of the current VEBirdseyeScene object. Returns the orientation (VEOrientation Enumeration) of the current VEBirdseyeScene object. Returns the width of the image in the current VEBirdseyeScene object, in pixels, at maximum resolution Converts a VELatLong Class object (latitude/longitude pair) to the corresponding pixel on the map. Converts a point in the bird's eye scene to an encrypted latitude/longitude value.

VEBirdseyeScene.ContainsPixel Method VEBirdseyeScene.GetBoundingRectangle Method VEBirdseyeScene.GetHeight Method

VEBirdseyeScene.GetID Method VEBirdseyeScene.GetOrientation Method

VEBirdseyeScene.GetWidth Method

VEBirdseyeScene.LatLongToPixel Method

VEBirdseyeScene.PixelToLatLong Method

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.

57

Public Methods
Name Description

VEBirdseyeScene.ContainsLatLong Method

Determines whether the location specified by a VELatLong Class object is within the current VEBirdseyeScene object. Determines whether a specified pixel is within the current VEBirdseyeScene object. Returns an unencrypted and rounded off bounding rectangle for the VEBirdseyeScene object. Returns the height of the image in the current VEBirdseyeScene object, in pixels, at maximum resolution Returns the ID of the current VEBirdseyeScene object. Returns the orientation (VEOrientation Enumeration) of the current VEBirdseyeScene object. Returns the width of the image in the current VEBirdseyeScene object, in pixels, at maximum resolution Converts a VELatLong Class object (latitude/longitude pair) to the corresponding pixel on the map. Converts a point in the bird's eye scene to an encrypted latitude/longitude value.

VEBirdseyeScene.ContainsPixel Method VEBirdseyeScene.GetBoundingRectangle Method VEBirdseyeScene.GetHeight Method

VEBirdseyeScene.GetID Method VEBirdseyeScene.GetOrientation Method

VEBirdseyeScene.GetWidth Method

VEBirdseyeScene.LatLongToPixel Method

VEBirdseyeScene.PixelToLatLong Method

VEBirdseyeScene.ContainsLatLong Method Determines whether the location specified by a VELatLong Class object is within the current VEBirdseyeScene object. Syntax VEBirdseyeScene.ContainsLatLong(Latlong); Parameters

58

Parameter

Description

Latlong Return Value

A VELatLong Class object

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 y zoomLevel Return Value

The X component of the pixel The Y component of the pixel The current zoom level of the map

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
59

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
60

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. The zoom level of the current map view

zoomLevel Return Value

A pixel location of the VELatLong Class point. This object has two properties, x and y. Remarks

61

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 xand 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 zoomLevel Return Value An encrypted VELatLong object. Remarks

A VEPixel Class object representing a pixel location on the map The zoom level of the current map view

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

62

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. The name of the function called when clustering changes.

VEClusteringOptions.Callback Property

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. The name of the function called when
63

VEClusteringOptions.Callback Property

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 Grid

No pushpin clustering A simple clustering algorithm

64

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 VEClusterSpecification.LatLong Property

An array of VEShape Class items representing the pushpins in a pushpin cluster. 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
65

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 VEClusterSpecification.LatLong Property

An array of VEShape Class items representing the pushpins in a pushpin cluster. 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

66

Name

Description

VEColor Constructor

Initializes a new instance of the VEColor object.

Public Properties
Name Description

VEColor.R Property VEColor.G Property VEColor.B Property VEColor.A Property

Specifies the red component value. Valid values range from 0 through 255. Specifies the green component value. Valid values range from 0 through 255. Specifies the blue component value. Valid values range from 0 through 255. 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

The red component value. Valid values range from 0 through 255.
67

Parameter

Description

g b a

The green component value. Valid values range from 0 through 255. The blue component value. Valid values range from 0 through 255. 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 VEColor.G Property VEColor.B Property VEColor.A Property

Specifies the red component value. Valid values range from 0 through 255. Specifies the green component value. Valid values range from 0 through 255. Specifies the blue component value. Valid values range from 0 through 255. 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.
68

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.

69

Public Properties
Name Description

VECustomIconSpecification.BackColor Property VECustomIconSpecification.CustomHTML Property

A VEColor object representing the icon's background and transparency. Custom HTML representing the pin's appearance. When specified, this HTML represents the pin's icon for 2D views only. String. A VEColor object representing the icon's text color and transparency. A String representing the URL of an image file. A VEPixel object representing the image's offset from the icon's anchor. Specifies whether the text for the icon should be bold. Boolean. The actual text to display for the icon. String. A String containing the name of the font to use for the icon text.

VECustomIconSpecification.ForeColor Property VECustomIconSpecification.Image Property VECustomIconSpecification.ImageOffset Property VECustomIconSpecification.TextBold Property VECustomIconSpecification.TextContent Property VECustomIconSpecification.TextFont Property

VECustomIconSpecification.TextItalics Property Specifies whether the text for the icon should be italic. Boolean. VECustomIconSpecification.TextOffset Property VECustomIconSpecification.TextSize Property VECustomIconSpecification.TextUnderline Property A VEPixel object representing the amount to offset text from the top left corner. Specifies the size at which to display text, in points. Integer. 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.
70

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 VECustomIconSpecification.CustomHTML Property

A VEColor object representing the icon's background and transparency. Custom HTML representing the pin's appearance. When specified, this HTML represents the pin's icon for 2D views only. String. A VEColor object representing the icon's text color and transparency. A String representing the URL of an image file. A VEPixel object representing the image's offset from the icon's anchor. Specifies whether the text for the icon should be bold. Boolean. The actual text to display for the icon. String. A String containing the name of the font to use for the icon text.

VECustomIconSpecification.ForeColor Property VECustomIconSpecification.Image Property VECustomIconSpecification.ImageOffset Property VECustomIconSpecification.TextBold Property VECustomIconSpecification.TextContent Property VECustomIconSpecification.TextFont Property

VECustomIconSpecification.TextItalics Property Specifies whether the text for the icon should be italic. Boolean. VECustomIconSpecification.TextOffset Property VECustomIconSpecification.TextSize Property A VEPixel object representing the amount to offset text from the top left corner. Specifies the size at which to display text, in
71

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

72

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

73

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.

74

Syntax
VEDashboardSize{ Normal Small Tiny }

Members
Member Description

Normal Small

This is the dashboard that is used by default. 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. This is the smallest dashboard option available. This dashboard only contains zoom-out (+) and zoom-in (-) buttons.

Tiny

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 VECollection ImportXML

This represents a GeoRSS data import. This represents a Bing Maps Collection (http://maps.live.com) import. This represents an XML data import.

75

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.

76

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 MultiGeometry Polygon LineString LinearRing Point NetworkLink

Required Converts to multiple VEShape objects

One level support only. Data is imported once when the VEMap.ImportShapeLayerData Method is called. Unsupported if the element contains a StyleUrl that points to a separate KML file Unsupported if the element contains a StyleUrl that points to a separate KML file Unsupported if the specified URL is a separate KML file Unsupported if the element contains a StyleUrl that points to a separate KML file Unsupported if the element contains a StyleUrl that points to a separate KML file Unsupported if the element contains a StyleUrl that points to a separate KML file

Style Icon StyleUrl IconStyle LineStyle PolygonStyle

See Also
VEShapeLayer Class

VEDistanceUnit Enumeration
An enumeration of the distance unit used for generating routes and itineraries.

77

Syntax
VEDistanceUnit{ Miles Kilometers }

Members
Member Description

Miles Kilometers

Generates route information in miles. 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 VEException.name Property VEException.message Property

The source object that caused the exception. The name of the exception. 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

78

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 VEException.name Property VEException.message Property

The source object that caused the exception. The name of the exception. 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 }

79

Members
Member Description

DoNotDraw DrawInaccurately QueueRequest

Do not draw the shape Draw the shape inaccurately 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. The name of the found result. The description of the found result. 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. A Boolean value that indicates whether the found result is a paid advertisement. A VELatLong Class object that represents the location of the found result. The telephone number of the found result.

VEFindResult.Name Property VEFindResult.Description Property VEFindResult.FindType Property

VEFindResult.IsSponsored Property VEFindResult.LatLong Property VEFindResult.Phone Property

80

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. The name of the found result. The description of the found result. 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. A Boolean value that indicates whether the found result is a paid advertisement. A VELatLong Class object that represents the location of the found result. The telephone number of the found result.

VEFindResult.Name Property VEFindResult.Description Property VEFindResult.FindType Property

VEFindResult.IsSponsored Property VEFindResult.LatLong Property VEFindResult.Phone Property

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
81

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
82

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 VEGeocodeLocation.Precision Property

A VELatLong Class object specifying the latitude and longitude of the location. A VELocationPrecision Enumeration value specifying the precision of the location.

See Also
VEPlace Class

83

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 VEGeocodeLocation.Precision Property

A VELatLong Class object specifying the latitude and longitude of the location. 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.

84

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

VEGeocodeOptions.UseDefaultDisambiguation Property

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

VEGeocodeOptions.UseDefaultDisambiguation Property

85

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 VEImageryMetadata.DateRangeEnd Property

A string specifying the start date of the date range when the imagery was created. 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

86

Name

Description

VEImageryMetadata.DateRangeStart Property VEImageryMetadata.DateRangeEnd Property

A string specifying the start date of the date range when the imagery was created. 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

87

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. A VEMapStyle Enumeration value specifying the map style. Optional. Defaults to the current map style. An integer specifying the zoom level. Optional. Defaults to the current zoom level.

VEImageryMetadataOptions.MapStyle Property

VEImageryMetadataOptions.ZoomLevel Property

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

88

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. An integer specifying the zoom level. Optional. Defaults to the current zoom level.

VEImageryMetadataOptions.ZoomLevel Property

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

89

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 VELatLong.AltitudeMode Property VELatLong.Latitude Property VELatLong.Longitude Property

Specifies the altitude of a single point on the globe. Specifies the mode in which an altitude is represented. Specifies the latitude of a single point on the globe. 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.
90

Syntax var x = new VELatLong(latitude, longitude, altitude, altitudeMode); Parameters

Parameter Description

latitude longitude altitude altitudeMode

The latitude of a single point on the globe The longitude of a single point on the globe The altitude of a single point on the globe. Optional. The default value is 0 (zero). 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 VELatLong.AltitudeMode Property VELatLong.Latitude Property

Specifies the altitude of a single point on the globe. Specifies the mode in which an altitude is represented. Specifies the latitude of a single point on the globe.
91

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

92

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 mode

The altitude, in meters The VEAltitudeMode Enumeration value that defines whether altitude is relative to groundlevel 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
93

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. A VELatLong Class object that specifies the latitude and longitude of the lower-right corner of the map view. 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. 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.BottomRightLatLong Property VELatLongRectangle.TopRightLatLong Property VELatLongRectangle.BottomLeftLatLong Property

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

94

Parameter

Description

TopLeftLatLong

A VELatLong Class object that specifies the latitude and longitude of the upper-left corner of the map view A VELatLong Class object that specifies the latitude and longitude of the lower-right corner of the map view 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 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

BottomRightLatLong

TopRightLatLong

BottomLeftLatLong

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. A VELatLong Class object that specifies the latitude and longitude of the lower-right corner of the map view. 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. 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.BottomRightLatLong Property VELatLongRectangle.TopRightLatLong Property VELatLongRectangle.BottomLeftLatLong Property

VELatLongRectangle.BottomLeftLatLong Property A VELatLong Class object that specifies the latitude and longitude of the lower-left corner of the map view.
95

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 Rooftop

The precision is estimated from multiple geocoded sources. The precision is from a single match.
96

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 Mouse Events Bing Maps Events

Input events produced by the keyboard connected to the computer. Input events produced by the mouse device connected to the computer. The events of the VEMap Class specific to Bing Maps.

Public Methods
Name Description

VEMap.AddControl Method VEMap.AddCustomLayer Method VEMap.AddShape Method

Adds a custom control to the map. Adds a custom layer to the map. Adds an existing VEShape Class object, as specified by the shape parameter, to the base layer. Adds the specified shape layer to the map. Adds a tile layer to the map, and if the
97

VEMap.AddShapeLayer Method VEMap.AddTileLayer Method

Name

Description

visibleOnLoad parameter is true, it also shows it on the map. VEMap.AttachEvent Method VEMap.Clear Method Attaches a Map Control event to a specified function. Removes all shapes, shape layers, and search results on the map. Also removes the route from the map, if one is displayed. Clears out all of the default Bing Maps info box CSS styles. Clears the traffic map. Deletes all shape layers, along with any shapes within the layers. Deletes all shapes in all layers, leaving empty layers behind. Removes the specified control from the map. Clears the current route, VERoute Class object, from the map. Deletes a VEShape Class object from any layer, including the base map layer. Deletes the specified shape layer from the map. Deletes a tile layer from view. Detaches the specified map control event so that it no longer calls the specified function. Deletes the VEMap object and releases any associated resources Specifies whether shapes are drawn below a threshold zoom level. Stops the continuous map panning initiated by a call to the VEMap.StartContinuousPan Method. Returns an array of found results. Performs a search for locations that match a
98

VEMap.ClearInfoBoxStyles Method VEMap.ClearTraffic Method VEMap.DeleteAllShapeLayers Method VEMap.DeleteAllShapes Method VEMap.DeleteControl Method VEMap.DeleteRoute Method VEMap.DeleteShape Method VEMap.DeleteShapeLayer Method VEMap.DeleteTileLayer Method VEMap.DetachEvent Method VEMap.Dispose Method VEMap.EnableShapeDisplayThreshold Method VEMap.EndContinuousPan Method

VEMap.Find Method VEMap.FindLocations Method

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. In 3D mode, returns a double that represents the altitude (in meters) above the geoid. If the map view is already set to bird's eye, returns the current VEBirdseyeScene Class object. Returns a VELatLong Class object that represents the location of the center of the current map view. Draws a multi-point route on the map and sends details about the route to a callback function. In 3D mode, returns an integer that represents the compass heading of the current map view. Returns information about the requested imagery, including imagery date stamps and vendor attribution. Returns the pixel value of the left edge of the map control. Returns the current map mode. Returns the current map style. Returns the current map view object as a VELatLongRectangle Class object. In 3D mode, returns an integer that represents the pitch of the current map view. Deprecated. Draws a route on the map and sends details about the route to a callback function. Gets the reference to a VEShape Class object based on its internal identifier. Gets the reference to a VEShapeLayer Class
99

VEMap.GetAltitude Method VEMap.GetBirdseyeScene Method

VEMap.GetCenter Method

VEMap.GetDirections Method

VEMap.GetHeading Method VEMap.GetImageryMetadata Method

VEMap.GetLeft Method VEMap.GetMapMode Method VEMap.GetMapStyle Method VEMap.GetMapView Method VEMap.GetPitch Method VEMap.GetRoute Method

VEMap.GetShapeByID Method VEMap.GetShapeLayerByIndex Method

Name

Description

object based on its index. VEMap.GetShapeLayerCount Method VEMap.GetTileLayerCount Method VEMap.GetTileLayerByID Method VEMap.GetTileLayerByIndex Method VEMap.GetTop Method VEMap.GetVersion Method VEMap.GetZoomLevel Method VEMap.Hide3DNavigationControl Method Gets the total number of shape layers on the map. Gets the number of tile layers. Gets a tile layer based upon its identifier. Gets a tile layer based upon an index value. Returns the pixel value of the top edge of the map control. Returns the current version of the map control. Returns the current zoom level of the map. In 3D mode, hides the default user interface for controlling the map in 3D mode. By default, this control is shown. Hides all of the shape layers on the map. Hides the base tile layer of the map. Hides the specified control from view. Hides the default user interface for controlling the map (the compass and the zoom control). Deprecated. Removes the Find control from the map. Hides a shape's custom or default info box. Hides the mini map from view. Hides the scale bar from the map. Hides a tile layer from view. Hides the traffic legend. Imports data from a Wavefront OBJ file and displays it as a 3D model on the map. Imports data from a GeoRSS feed, Bing Maps (http://maps.live.com) collection, or KML URL. Changes the map view so that it includes both the specified VELatLong Class point and the
100

VEMap.HideAllShapeLayers Method VEMap.HideBaseTileLayer Method VEMap.HideControl Method VEMap.HideDashboard Method VEMap.HideFindControl Method VEMap.HideInfoBox Method VEMap.HideMiniMap Method VEMap.HideScalebar Method VEMap.HideTileLayer Method VEMap.HideTrafficLegend Method VEMap.Import3DModel Method VEMap.ImportShapeLayerData Method VEMap.IncludePointInView Method

Name

Description

center point of the current map. VEMap.IsBirdseyeAvailable Method VEMap.LatLongToPixel Method Determines whether the bird's eye map style is available in the current map view. Converts an array of VELatLong Class objects (latitude/longitude pair) to an array of VEPixel Class objects. Loads the traffic map. Loads the specified map. All parameters are optional. When in 2D mode, moves the map the specified amount. Pans the map to a specific latitude and longitude. Converts a pixel (a point on the map) to a VELatLong Class object (latitude/longitude pair). Removes a custom layer from the map. Resizes the map based on the specified width and height. Performs a search based on a given query and options. In 3D mode, sets the altitude, in meters, above the WGS 84 ellipsoid in the map view. Changes the orientation of the existing bird's eye image (VEBirdseyeScene Class object) to the specified orientation. Overloaded. Displays the specified bird's eye image. Centers the map to a specific latitude and longitude. Centers the map to a specific latitude and longitude and sets the zoom level. Sets a Bing Maps token for the VEMap object.

VEMap.LoadTraffic Method VEMap.LoadMap Method VEMap.Pan Method VEMap.PanToLatLong Method VEMap.PixelToLatLong Method

VEMap.RemoveCustomLayer Method VEMap.Resize Method VEMap.Search Method VEMap.SetAltitude Method VEMap.SetBirdseyeOrientation Method

VEMap.SetBirdseyeScene Method VEMap.SetCenter Method VEMap.SetCenterAndZoom Method VEMap.SetClientToken Method

101

Name

Description

VEMap.SetCredentials Method VEMap.SetDashboardSize Method VEMap.SetDefaultInfoBoxStyles Method VEMap.SetFailedShapeRequest Method

Sets the credentials to use to authenticate map service requests. Sets the map dashboard size and type. Sets the info box CSS styles back to their original classes. 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. In 3D mode, sets the compass heading of the current map view. Sets the mode of the map. Sets the style of the map. 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. Specifies whether to zoom to the center of the screen or to the cursor position on the screen. In 3D mode, sets the pitch of the current map view. Sets the print options for the current map. Sets the distance unit (kilometers or miles) for the map scale. Specifies the accuracy in converting shapes when the map style is changed to birdseye. 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. Sets the number of "rings" of map tiles that should be loaded outside of the visible mapview area. Specifies the text shown with the traffic legend,
102

VEMap.SetHeading Method VEMap.SetMapMode Method VEMap.SetMapStyle Method VEMap.SetMapView Method

VEMap.SetMouseWheelZoomToCenter Method VEMap.SetPitch Method VEMap.SetPrintOptions Method VEMap.SetScaleBarDistanceUnit Method VEMap.SetShapesAccuracy Method VEMap.SetShapesAccuracyRequestLimit Method

VEMap.SetTileBuffer Method

VEMap.SetTrafficLegendText Method

Name

Description

if visible. VEMap.SetZoomLevel Method VEMap.Show3DBirdseye Method Sets the view of the map to the specified zoom level. Controls whether or not to show the Birdseye and BirdseyeHybrid map styles when the map mode is set to VEMapMode.Mode3D. In 3D mode, shows the default user interface for controlling the map in 3D mode. By default, this control is shown. Shows all shape layers on the map. Shows the base tile layer of the map. Makes the specified control visible. This method only affects control elements that have been hidden from view using the VEMap.HideControl Method. Shows the default user interface for controlling the map (the compass-and-zoom control). By default, this control is shown. Specifies whether the default disambiguation dialog is displayed when multiple results are returned from a location query. Deprecated. Shows the Find control, which enables users to enter search queries. Shows a shape's custom or default info box. Displays the specified message in a dialog box on the map. Displays the mini map at the specified offset from the top left corner of the screen. Displays the scale bar on the map. Shows a tile layer from view. Displays the traffic legend. Moves the map in the specified direction until the VEMap.EndContinuousPan Method is called.
103

VEMap.Show3DNavigationControl Method

VEMap.ShowAllShapeLayers Method VEMap.ShowBaseTileLayer Method VEMap.ShowControl Method

VEMap.ShowDashboard Method

VEMap.ShowDisambiguationDialog Method

VEMap.ShowFindControl Method VEMap.ShowInfoBox Method VEMap.ShowMessage Method VEMap.ShowMiniMap Method VEMap.ShowScalebar Method VEMap.ShowTileLayer Method VEMap.ShowTrafficLegend Method VEMap.StartContinuousPan Method

Name

Description

VEMap.ZoomIn Method VEMap.ZoomOut Method

Increases the map zoom level by 1. 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

104

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 VEMap.onkeydown Event VEMap.onkeyup Event

Occurs when a key is pressed and released. This is not supported in 3D mode. Occurs when a key is pressed (but before it is released). This is not supported in 3D mode. Occurs when a key is released. This is not supported in 3D mode.

See Also Mouse Events

105

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 ctrlKey eventName keyCode mapStyle sceneID sceneOrientation shiftKey zoomLevel See Also VEMap Event Object Properties VEMap.onkeydown Event

A Boolean object representing whether the ALT key was held when the key was pressed. A Boolean object representing whether the CTRL key was held when the key was pressed. A String object representing the type of event that occurred. The key code of the key that has been pressed. The current map style If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. A Boolean object representing whether the shift key was held when the key was pressed. The current zoom level of the map.

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
106

A MapEvent object, which has the following properties:

Property Description

altKey ctrlKey eventName keyCode mapStyle sceneID sceneOrientation shiftKey zoomLevel See Also VEMap Event Object Properties VEMap.onkeyup Event

A Boolean object representing whether the ALT key was held when the key was pressed. A Boolean object representing whether the CTRL key was held when the key was pressed. A String object representing the type of event that occurred. The key code of the key that has been pressed. The current map style If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. A Boolean object representing whether the shift key was held when the key was pressed. The current zoom level of the map.

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 ctrlKey eventName

A Boolean object representing whether the ALT key was held when the key was pressed. A Boolean object representing whether the CTRL key was held when the key was pressed. A String object representing the type of event
107

Property

Description

that occurred. keyCode mapStyle sceneID sceneOrientation shiftKey zoomLevel 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

The key code of the key that has been pressed. The current map style If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. A Boolean object representing whether the shift key was held when the key was pressed. The current zoom level of the map.

VEMap.onclick Event VEMap.ondoubleclick Event VEMap.onmousemove Event

Occurs when a left or right mouse button is single-clicked. Occurs when a left mouse button is doubleclicked. Occurs when the mouse cursor moves.

This is not supported in 3D mode. VEMap.onmousedown Event VEMap.onmouseup Event VEMap.onmouseover Event VEMap.onmouseout Event Occurs when a mouse button (left, right, or middle) is clicked (but before it is released). Occurs when a mouse button (left, right, or middle) is released. Occurs when the mouse cursor moves over a VEShape Class object. Occurs when the mouse cursor moves away from a VEShape object.
108

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. A String object representing the type of event that occurred. The latLong coordinates of the clicked location.
109

eventName latLong

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 rightMouseButton mapStyle sceneID sceneOrientation shiftKey A Boolean object representing whether the left mouse button has been clicked. A Boolean object representing whether the right mouse button has been clicked. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. A Boolean object representing whether the shift key was held when the key was pressed.

This is not supported in 3D mode. clientX clientY screenX The x coordinate of the mouse cursor relative to the browser window. The y coordinate of the mouse cursor relative to the browser window. 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.

110

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

The current zoom level of the map.

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. A String object representing the type of event that occurred. The latlong coordinates of the clicked location. This only works in 3D mode and is not
111

eventName latLong

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 sceneID sceneOrientation shiftKey The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. A Boolean object representing whether the shift key was held when the key was pressed.

This is not supported in 3D mode. clientX clientY screenX The x coordinate of the mouse cursor relative to the browser window. The y coordinate of the mouse cursor relative to the browser window. 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.

112

Property

Description

zoomLevel See Also VEMap.onclick Event VEMap.onmousedown Event

The current zoom level of the map.

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. A String object representing the type of event that occurred. 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. A Boolean object representing whether the left mouse button has been clicked. A Boolean object representing whether the right
113

eventName latLong

leftMouseButton rightMouseButton

Property

Description

mouse button has been clicked. mapStyle sceneID sceneOrientation shiftKey The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. A Boolean object representing whether the shift key was held when the key was pressed.

This is not supported in 3D mode. clientX clientY screenX The x coordinate of the mouse cursor relative to the browser window. The y coordinate of the mouse cursor relative to the browser window. 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.

114

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 ctrlKey elementID

A Boolean object representing whether the ALT key was held when the key was pressed. A Boolean object representing whether the CTRL key was held when the key was pressed. The ID of the object associated with the event, usually a VEShape Class object or the base map. A String object representing the type of event that occurred. A Boolean object representing whether the left mouse button has been clicked. A Boolean object representing whether the right mouse button has been clicked. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. A Boolean object representing whether the shift key was held when the key was pressed. The x coordinate of the mouse cursor relative to the browser window.

eventName leftMouseButton rightMouseButton mapStyle sceneID sceneOrientation shiftKey clientX

115

Property

Description

clientY screenX screenY mapX mapY zoomLevel Remarks This is not supported in 3D mode. VEMap.onmouseout Event

The y coordinate of the mouse cursor relative to the browser window. The x coordinate of the mouse cursor relative to the screen. The y coordinate of the mouse cursor relative to the screen. The x coordinate of the map relative to the screen. The y coordinate of the map relative to the screen. The current zoom level of the map.

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

Property

Description

eventName mapStyle sceneID sceneOrientation shiftKey

A String object representing the type of event that occurred. The current map style as a String object. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. A Boolean object representing whether the shift key was held when the key was pressed.

This is not supported in 3D mode. clientX clientY screenX The x coordinate of the mouse cursor relative to the browser window. The y coordinate of the mouse cursor relative to the browser window. 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.

117

Property

Description

zoomLevel See Also VEMap.onmouseover Event VEMap.onmouseover Event

The current zoom level of the map.

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. A String object representing the type of event that occurred. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. A Boolean object representing whether the shift key was held when the key was pressed.
118

eventName mapStyle sceneID sceneOrientation shiftKey

Property

Description

This is not supported in 3D mode. clientX clientY screenX The x coordinate of the mouse cursor relative to the browser window. The y coordinate of the mouse cursor relative to the browser window. 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 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:
119

The current zoom level of the map.

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. A String object representing the type of event that occurred. 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. A Boolean object representing whether the left mouse button has been clicked. A Boolean object representing whether the right mouse button has been clicked. The current map style as a String. Valid String results are ga, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. A Boolean object representing whether the shift key was held when the key was pressed. Note This is not supported in 3D mode.

eventName latLong

leftMouseButton rightMouseButton mapStyle sceneID sceneOrientation shiftKey

clientX clientY screenX

The x coordinate of the mouse cursor relative to the browser window. The y coordinate of the mouse cursor relative to the browser window. The x coordinate of the mouse cursor relative to
120

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

The current zoom level of the map.

altKey ctrlKey elementID

A Boolean object representing whether the ALT key was held when the key was pressed. A Boolean object representing whether the CTRL key was held when the key was pressed. The ID of the object associated with the event, usually a VEShape Class object or the base map. A String object representing the type of event that occurred. The current map style as a String. Valid String
121

eventName mapStyle

Property

Description

results are a, r, h, and o. sceneID sceneOrientation shiftKey ClientX ClientY ScreenX ScreenY MapX MapY ZoomLevel 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

If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. A Boolean object representing whether the shift key was held when the key was pressed. The x coordinate of the mouse cursor relative to the browser window. The y coordinate of the mouse cursor relative to the browser window. The x coordinate of the mouse cursor relative to the screen. The y coordinate of the mouse cursor relative to the screen. The x coordinate of the map relative to the screen. The y coordinate of the map relative to the screen. The current zoom level of the map.

VEMap.onchangemapstyle Event VEMap.onchangeview Event VEMap.oncredentialserror Event

Occurs when the map style changes. Occurs whenever the map view changes. Occurs when the map control makes a request to the Bing Maps servers and the credentials that were set using the
122

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. Occurs when a pan of the map ends. Occurs when the map zoom ends. Occurs when there is a map control error. Occurs after the map mode changes and the map has reloaded. Occurs when the map mode fails to change to 3D mode. 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. Occurs when bird's eye images are available at the center of the current map. Occurs when bird's eye images are no longer available at the center of the current map. Occurs when the map is resized. Occurs when a pan of the map begins. This event is not supported in 3D mode. Occurs when the map zoom begins. 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. 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.

VEMap.onendpan Event VEMap.onendzoom Event VEMap.onerror Event VEMap.oninitmode Event VEMap.onmodenotavailable Event VEMap.onobliquechange Event

VEMap.onobliqueenter Event VEMap.onobliqueleave Event VEMap.onresize Event VEMap.onstartpan Event VEMap.onstartzoom Event VEMap.ontokenerror Event

VEMap.ontokenexpire Event

Remarks See Also

123

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 mapStyle sceneID sceneOrientation zoomLevel See Also Keyboard Events Mouse Events VEMap.onchangeview Event Occurs whenever the map view changes. Syntax

A String object representing the type of event that occurred. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. The current zoom level of the map.

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

Property

Description

eventName mapStyle sceneID sceneOrientation zoomLevel See Also VEMap.onchangemapstyle Event VEMap.oncredentialserror Event

A String object representing the type of event that occurred. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. The current zoom level of the map.

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 mapStyle sceneID sceneOrientation zoomLevel Remarks

A String object representing the type of event that occurred. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. The current zoom level of the map.

125

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 mapStyle sceneID sceneOrientation zoomLevel Remarks

A String object representing the type of event that occurred. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. The current zoom level of the map.

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
126

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 mapStyle

A String object representing the type of event that occurred. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. The current zoom level of the map.

sceneID

sceneOrientation

zoomLevel

See Also VEMap.onstartpan Event VEMap.onendzoom Event Occurs when the map zoom ends. Syntax

127

VEMap.AttachEvent("onendzoom", function_name); Return Value A MapEvent object, which has the following properties:
Property Description

eventName mapStyle sceneID sceneOrientation zoomLevel 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 String object representing the type of event that occurred. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. The current zoom level of the map.

A MapEvent object, which has the following properties:

Property Description

error eventName mapStyle sceneID sceneOrientation

A String object containing the error message, if any. A String object representing the type of event that occurred. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the
128

Property

Description

orientation of the current bird's eye scene. zoomLevel 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

The current zoom level of the map.

eventName mapStyle sceneID sceneOrientation zoomLevel Remarks

A String object representing the type of event that occurred. The current map style as a String. Valid string results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. The current zoom level of the map.

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:

129

Property

Description

eventName mapStyle sceneID sceneOrientation zoomLevel Remarks

A String object representing the type of event that occurred. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. The current zoom level of the map.

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 mapStyle sceneID sceneOrientation

A String object representing the type of event that occurred. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene.

130

Property

Description

zoomLevel See Also VEMap.onobliqueenter Event VEMap.onobliqueleave Event VEMap.onobliqueenter Event

The current zoom level of the map.

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 mapStyle sceneID sceneOrientation zoomLevel See Also VEMap.onobliquechange Event VEMap.onobliqueleave Event VEMap.onobliqueleave Event

A String object representing the type of event that occurred. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. The current zoom level of the map.

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

Property

Description

eventName mapStyle sceneID sceneOrientation zoomLevel Remarks

A String object representing the type of event that occurred. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. The current zoom level of the map.

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 mapStyle sceneID sceneOrientation zoomLevel

A String object representing the type of event that occurred. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. The current zoom level of the map.
132

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 mapStyle sceneID sceneOrientation zoomLevel Remarks

A String object representing the type of event that occurred. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. The current zoom level of the map.

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 mapStyle

A String object representing the type of event that occurred. The current map style as a String. Valid String
133

Property

Description

results are a, r, h, and o. sceneID sceneOrientation zoomLevel 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

If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. The current zoom level of the map.

eventName mapStyle sceneID sceneOrientation zoomLevel Remarks

A String object representing the type of event that occurred. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. The current zoom level of the map.

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
134

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 mapStyle sceneID sceneOrientation zoomLevel Remarks

A String object representing the type of event that occurred. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. The current zoom level of the map.

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
135

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 zoomLevel mapStyle birdseyeSceneID birdseyeSceneOrientation leftMouseButton rightMouseButton middleMouseButton

A String object containing the error message, if any. The current map zoom level. The current map style as a String. Valid String results are a, r, h, and o. If the map style is set to bird's eye (oblique), the unique identifier of the current bird's eye scene. If the map style is set to bird's eye (oblique), the orientation of the current bird's eye scene. A boolean representing whether the left mouse button has been clicked. A boolean representing whether the right mouse button has been clicked. A boolean representing whether the middle mouse button (or mouse wheel) has been clicked. The number of units that the mouse wheel has changed.

mouseWheelChange

This is not supported in 3D mode, and the value returned in Firefox 1.5 and 2.0 is incorrect. clientX clientY screenX The x coordinate of the mouse cursor relative to the browser window. The y coordinate of the mouse cursor relative to the browser window. The x coordinate of the mouse cursor relative to
136

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. The key code of the key that has been pressed.

keyCode

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.

137

Property

Description

This is not supported in 3D mode. eventName elementID A string representing the type of event that occurred. 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.

138

Public Methods
Name Description

VEMap.AddControl Method VEMap.AddCustomLayer Method VEMap.AddShape Method

Adds a custom control to the map. Adds a custom layer to the map. Adds an existing VEShape Class object, as specified by the shape parameter, to the base layer. Adds the specified shape layer to the map. Adds a tile layer to the map, and if the visibleOnLoad parameter is true, it also shows it on the map. Attaches a Map Control event to a specified function. Removes all shapes, shape layers, and search results on the map. Also removes the route from the map, if one is displayed. Clears out all of the default Bing Maps info box CSS styles. Clears the traffic map. Deletes all shape layers, along with any shapes within the layers. Deletes all shapes in all layers, leaving empty layers behind. Removes the specified control from the map. Clears the current route, VERoute Class object, from the map. Deletes a VEShape Class object from any layer, including the base map layer. Deletes the specified shape layer from the map. Deletes a tile layer from view. Detaches the specified map control event so that it no longer calls the specified function.

VEMap.AddShapeLayer Method VEMap.AddTileLayer Method

VEMap.AttachEvent Method VEMap.Clear Method

VEMap.ClearInfoBoxStyles Method VEMap.ClearTraffic Method VEMap.DeleteAllShapeLayers Method VEMap.DeleteAllShapes Method VEMap.DeleteControl Method VEMap.DeleteRoute Method VEMap.DeleteShape Method VEMap.DeleteShapeLayer Method VEMap.DeleteTileLayer Method VEMap.DetachEvent Method

139

Name

Description

VEMap.Dispose Method VEMap.EnableShapeDisplayThreshold Method VEMap.EndContinuousPan Method

Deletes the VEMap object and releases any associated resources Specifies whether shapes are drawn below a threshold zoom level. Stops the continuous map panning initiated by a call to the VEMap.StartContinuousPan Method. Returns an array of found results. Performs a search for locations that match a VELatLong Class input. Finds a geographic location based on a specified address or place name string as well as other geocoding options. In 3D mode, returns a double that represents the altitude (in meters) above the geoid. If the map view is already set to bird's eye, returns the current VEBirdseyeScene Class object. Returns a VELatLong Class object that represents the location of the center of the current map view. Draws a multi-point route on the map and sends details about the route to a callback function. In 3D mode, returns an integer that represents the compass heading of the current map view. Returns information about the requested imagery, including imagery date stamps and vendor attribution. Returns the pixel value of the left edge of the map control. Returns the current map mode. Returns the current map style. Returns the current map view object as a
140

VEMap.Find Method VEMap.FindLocations Method VEMap.Geocode Method

VEMap.GetAltitude Method VEMap.GetBirdseyeScene Method

VEMap.GetCenter Method

VEMap.GetDirections Method

VEMap.GetHeading Method VEMap.GetImageryMetadata Method

VEMap.GetLeft Method VEMap.GetMapMode Method VEMap.GetMapStyle Method VEMap.GetMapView Method

Name

Description

VELatLongRectangle Class object. VEMap.GetPitch Method VEMap.GetRoute Method In 3D mode, returns an integer that represents the pitch of the current map view. Deprecated. Draws a route on the map and sends details about the route to a callback function. Gets the reference to a VEShape Class object based on its internal identifier. Gets the reference to a VEShapeLayer Class object based on its index. Gets the total number of shape layers on the map. Gets the number of tile layers. Gets a tile layer based upon its identifier. Gets a tile layer based upon an index value. Returns the pixel value of the top edge of the map control. Returns the current version of the map control. Returns the current zoom level of the map. In 3D mode, hides the default user interface for controlling the map in 3D mode. By default, this control is shown. Hides all of the shape layers on the map. Hides the base tile layer of the map. Hides the specified control from view. Hides the default user interface for controlling the map (the compass and the zoom control). Deprecated. Removes the Find control from the map. Hides a shape's custom or default info box. Hides the mini map from view. Hides the scale bar from the map.
141

VEMap.GetShapeByID Method VEMap.GetShapeLayerByIndex Method VEMap.GetShapeLayerCount Method VEMap.GetTileLayerCount Method VEMap.GetTileLayerByID Method VEMap.GetTileLayerByIndex Method VEMap.GetTop Method VEMap.GetVersion Method VEMap.GetZoomLevel Method VEMap.Hide3DNavigationControl Method

VEMap.HideAllShapeLayers Method VEMap.HideBaseTileLayer Method VEMap.HideControl Method VEMap.HideDashboard Method VEMap.HideFindControl Method VEMap.HideInfoBox Method VEMap.HideMiniMap Method VEMap.HideScalebar Method

Name

Description

VEMap.HideTileLayer Method VEMap.HideTrafficLegend Method VEMap.Import3DModel Method VEMap.ImportShapeLayerData Method VEMap.IncludePointInView Method

Hides a tile layer from view. Hides the traffic legend. Imports data from a Wavefront OBJ file and displays it as a 3D model on the map. Imports data from a GeoRSS feed, Bing Maps (http://maps.live.com) collection, or KML URL. Changes the map view so that it includes both the specified VELatLong Class point and the center point of the current map. Determines whether the bird's eye map style is available in the current map view. Converts an array of VELatLong Class objects (latitude/longitude pair) to an array of VEPixel Class objects. Loads the traffic map. Loads the specified map. All parameters are optional. When in 2D mode, moves the map the specified amount. Pans the map to a specific latitude and longitude. Converts a pixel (a point on the map) to a VELatLong Class object (latitude/longitude pair). Removes a custom layer from the map. Resizes the map based on the specified width and height. Performs a search based on a given query and options. In 3D mode, sets the altitude, in meters, above the WGS 84 ellipsoid in the map view. Changes the orientation of the existing bird's eye image (VEBirdseyeScene Class object) to
142

VEMap.IsBirdseyeAvailable Method VEMap.LatLongToPixel Method

VEMap.LoadTraffic Method VEMap.LoadMap Method VEMap.Pan Method VEMap.PanToLatLong Method VEMap.PixelToLatLong Method

VEMap.RemoveCustomLayer Method VEMap.Resize Method VEMap.Search Method VEMap.SetAltitude Method VEMap.SetBirdseyeOrientation Method

Name

Description

the specified orientation. VEMap.SetBirdseyeScene Method VEMap.SetCenter Method VEMap.SetCenterAndZoom Method VEMap.SetClientToken Method VEMap.SetCredentials Method VEMap.SetDashboardSize Method VEMap.SetDefaultInfoBoxStyles Method VEMap.SetFailedShapeRequest Method Overloaded. Displays the specified bird's eye image. Centers the map to a specific latitude and longitude. Centers the map to a specific latitude and longitude and sets the zoom level. Sets a Bing Maps token for the VEMap object. Sets the credentials to use to authenticate map service requests. Sets the map dashboard size and type. Sets the info box CSS styles back to their original classes. 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. In 3D mode, sets the compass heading of the current map view. Sets the mode of the map. Sets the style of the map. 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. Specifies whether to zoom to the center of the screen or to the cursor position on the screen. In 3D mode, sets the pitch of the current map view. Sets the print options for the current map. Sets the distance unit (kilometers or miles) for the map scale. Specifies the accuracy in converting shapes
143

VEMap.SetHeading Method VEMap.SetMapMode Method VEMap.SetMapStyle Method VEMap.SetMapView Method

VEMap.SetMouseWheelZoomToCenter Method VEMap.SetPitch Method VEMap.SetPrintOptions Method VEMap.SetScaleBarDistanceUnit Method VEMap.SetShapesAccuracy Method

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. Sets the number of "rings" of map tiles that should be loaded outside of the visible mapview area. Specifies the text shown with the traffic legend, if visible. Sets the view of the map to the specified zoom level. Controls whether or not to show the Birdseye and BirdseyeHybrid map styles when the map mode is set to VEMapMode.Mode3D. In 3D mode, shows the default user interface for controlling the map in 3D mode. By default, this control is shown. Shows all shape layers on the map. Shows the base tile layer of the map. Makes the specified control visible. This method only affects control elements that have been hidden from view using the VEMap.HideControl Method. Shows the default user interface for controlling the map (the compass-and-zoom control). By default, this control is shown. Specifies whether the default disambiguation dialog is displayed when multiple results are returned from a location query. Deprecated. Shows the Find control, which enables users to enter search queries. Shows a shape's custom or default info box. Displays the specified message in a dialog box on the map.
144

VEMap.SetTileBuffer Method

VEMap.SetTrafficLegendText Method VEMap.SetZoomLevel Method VEMap.Show3DBirdseye Method

VEMap.Show3DNavigationControl Method

VEMap.ShowAllShapeLayers Method VEMap.ShowBaseTileLayer Method VEMap.ShowControl Method

VEMap.ShowDashboard Method

VEMap.ShowDisambiguationDialog Method

VEMap.ShowFindControl Method VEMap.ShowInfoBox Method VEMap.ShowMessage Method

Name

Description

VEMap.ShowMiniMap Method VEMap.ShowScalebar Method VEMap.ShowTileLayer Method VEMap.ShowTrafficLegend Method VEMap.StartContinuousPan Method

Displays the mini map at the specified offset from the top left corner of the screen. Displays the scale bar on the map. Shows a tile layer from view. Displays the traffic legend. Moves the map in the specified direction until the VEMap.EndContinuousPan Method is called. Increases the map zoom level by 1. Decreases the map zoom level by 1.

VEMap.ZoomIn Method VEMap.ZoomOut Method

VEMap.AddControl Method Adds a custom control to the map. Syntax VEMap.AddControl(element, zIndex); Parameters
Parameter Description

element zIndex

An HTML element that contains the control to be added 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".
145

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

146

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 Remarks

The VEShapeLayer Class object to add.

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

147

VEMap.AddTileLayer(layerSource, visibleOnLoad); Parameters

Parameter Description

layerSource

The VETileSourceSpecification Class object representing the source of the tile layer. Required. If true, the layer is immediately shown when added to the map. Optional.

visibleOnLoad

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 function

The name of the Map Control event that generates the call. 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
148

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

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

150

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

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

152

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

153

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 Example VirtualEarthSDK#9 See Also VEMap.HideTileLayer Method VEMap.ShowTileLayer Method VEMap.DetachEvent Method

The ID of the layer to be deleted.

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

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.

155

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.

156

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. A VEFindType Enumeration value that specifies the type of search performed. The only currently supported value is VEFindType.Businesses. 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. The beginning index of the results returned. Optional. Default is 0. The number of results to be returned, starting at startIndex. The default is 10, the minimum is 1, and the maximum is 20. A Boolean value that specifies whether the resulting pushpins are visible. Optional. Default is true. 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.

findType

shapeLayer

startIndex numberOfResults

showResults

createResults

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
157

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

callback

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

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

159

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 callback

The query string to match to a location on the map. 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. A VEGeocodeOptions Class object specifying additional options.

options

Return Value
160

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
161

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. A VERouteOptions Class object specifying the routing options.

options

162

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

163

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. A VEImageryMetadataOptions Class object specifying the imagery for which information is returned. Optional.

options

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

164

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
165

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 The ending location. This can be a string value of an address, a place name, or a VELatLong object that specifies the end location

end

166

Parameter

Description

units

A VEDistanceUnit Enumeration value that specifies either miles or kilometers. Optional. Default is VEDistanceUnit.Miles A VERouteType Enumeration value specifying either the shortest route or the quickest route. Optional. Default is VERouteType.Shortest 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.

route_type

callback

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
167

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

168

VEMap.GetTileLayerByID Method Gets a tile layer based upon its identifier. Syntax VEMap.GetTileLayerByID(id); Parameters
Parameter Description

id 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

The unique identifier of the tile layer

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

169

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

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-tobird-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();
171

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

172

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

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 Example VirtualEarthSDK#9 See Also VEMap.DeleteTileLayer Method VEMap.ShowTileLayer Method VEMap.HideTrafficLegend Method Hides the traffic legend.

The ID of the layer to be hidden.

174

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-tobird-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 callback

A VEModelSourceSpecification Class object specifying the model data to import. The name of the function that is called after the data has been imported. See below for the arguments received by the callback. A VELatLong Class object that specifies the point at which to place the origin of the model. A VEModelOrientation Class object that specifies the orientation of the model on the map. A VEModelScale Class object that specifies the scale of the model.

latLong orientation

scale

Return Value

175

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 callback setBestView

A VEShapeSourceSpecification Class object specifying the imported shape data. The function that is called after the data has been imported. A Boolean value that specifies whether the map view is changed to the best view for the layer.

Return Value
176

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
177

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. 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. The name of the function called with the array of corresponding VEPixel objects. Optional.

zoomLevel

callback

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

178

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 zoom style

A VELatLong Class object that represents the center of the map. Optional. The zoom level to display. Valid values range from 1 through 19. Optional. Default is 4. A VEMapStyle Enumeration value specifying the map style. Optional. Default is VEMapStyle.Road. A Boolean value that specifies whether the map view is displayed as a fixed map that the user cannot change. Optional. Default is false. A VEMapMode Enumeration value that specifies whether to load the map in 2D or 3D mode. Optional. Default is VEMapMode.Mode2D. A Boolean value that specifies whether to show the map mode switch on the dashboard control. Optional. Default is true (the switch is displayed). 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. A VEMapOptions Class that specifies other map options to set.

fixed

mode

showSwitch

tileBuffer

mapOptions

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

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 Remarks

Whether to show the traffic flow

The traffic map is only available at zoom levels from 9 through 14, inclusively. Terms of Use

180

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 deltaY

The amount to move the map horizontally, in pixels 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

181

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

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

The width, in pixels, of the map. Optional. The height, in pixels, of the map. Optional.

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

183

Parameter

Description

query callback options

The string to use in the search. The name of the function that the server calls with the search results. 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 Remarks

The altitude, in meters

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
184

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 VEMap.SetBirdseyeScene(veLatLong, orientation, zoomLevel, callback) Method

Displays the bird's eye image specified by the VEBirdseyeScene Class ID 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.
185

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. 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. The level of zoom. Optional. If this parameter is not supplied, the value 1 is used. The name of the function called when the SetBirdseyeScene method completes.

orientation

zoomLevel callback

Return Value The callback function receives a VEBirdseyeScene Class object.

186

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,

187

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 Remarks

A string representing the Bing Maps token.

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.

188

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 Example VirtualEarthSDK#62 VEMap.SetDashboardSize Method Sets the map dashboard size and type. Syntax VEMap.SetDashboardSize(dashboard); Parameters
Parameter

A string that is the Bing Maps Key to set.

Description

dashboardSize

A VEDashboardSize Enumeration representing the dashboard size. Valid values are Normal, Small, and Tiny.

189

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

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

191

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

192

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
193

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
194

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.

195

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

196

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
197

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
198

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-tobird-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
199

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
200

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

left

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
201

VEMap.ShowInfoBox Method Shows an information box for the shape. Syntax VEMap.ShowInfoBox(shape, anchor, offset); Parameters
Parameter Description

shape anchor

The reference to the shape for which an info box is to be shown. Required. 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. If the anchor point is a VELatLong object, this parameter, a VEPixel object, specifies the anchor point's offset from that latlong position. Optional.

offset

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-zerolength 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
202

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 yoffset size

The x coordinate offset as a number of pixels from the top left corner of the screen. Optional The y coordinate offset as a number of pixels from the top left corner of the screen. Optional 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
203

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 Remarks

The ID of the layer to be shown.

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

The x-coordinate of the top-left corner of the

204

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

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

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.

206

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 Mode3 D

Displays the map in the traditional two dimensions 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.
207

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. 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. A Boolean value specifying whether or not to enable the Birdseye map style in the map control. The default value is true. A Boolean value indicating whether the Bing logo on the map is clickable. The default value is false.
TM

VEMapOptions.DashboardColor Property

VEMapOptions.EnableBirdseye Property

VEMapOptions.EnableClickableLogo Property

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. A Boolean value indicating whether to enable TM the Bing hovering search logo on the map. The default value is false. A Boolean value indicating whether or not to load the base map tiles. The default value is true.

VEMapOptions.EnableSearchLogo Property

VEMapOptions.LoadBaseTiles Property

208

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

map.LoadMap( new VELatLong(47.6, -122.3), 10, // zoom level VEMapStyle.Road, // map style false, // fixed map VEMapMode.Mode2D, // map mode true, // show map mode switch // center

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.

210

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. 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. A Boolean value specifying whether or not to enable the Birdseye map style in the map control. The default value is true. A Boolean value indicating whether the Bing logo on the map is clickable. The default value is false.
TM

VEMapOptions.DashboardColor Property

VEMapOptions.EnableBirdseye Property

VEMapOptions.EnableClickableLogo Property

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. A Boolean value indicating whether to enable TM the Bing hovering search logo on the map. The default value is false. A Boolean value indicating whether or not to load the base map tiles. The default value is true.

VEMapOptions.EnableSearchLogo Property

VEMapOptions.LoadBaseTiles Property

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.

211

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

212

VEMapOptions.EnableClickableLogo Property A Boolean value indicating whether the Bing 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 Bing 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.
213
TM TM

logo on the map is clickable. The default value is

hovering search logo on the map. The

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 Shaded Aerial Hybrid Oblique

The road map style The shaded map style, which is a road map with shaded contours. The aerial map style The hybrid map style, which is an aerial map with a label overlay The oblique map style, which is the same as
214

Member

Description

Birdseye Birdseye BirdseyeHybrid The bird's eye (oblique-angle) imagery map style 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);
215

Parameters
Parameter Description

center zoom

A VELatLong Class object that specifies the center point of the map. Required. 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. If VEMapMode Enumeration is set to Mode3D, the altitude of the view, in meters above the geoid. 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. If VEMapMode Enumeration is set to Mode3D, the heading of the view, in compass degrees. A value of 0 or 360 is true north.

altitude

pitch

heading

Remarks

VEMatchCode Enumeration
A match code value as received from the geocoder.

Syntax
VEMatchCode{ None Good Ambiguous UpHierarchy Modified }

Members
Member Description

None Good Ambiguous UpHierarchy

No match was found The match was good The match was ambiguous The match was found by a broader search
216

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 Medium Low

The confidence of a match is high The confidence of a match is medium 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.

217

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. mtllib usemtl vn v vt
218

Additionally, the following OBJ keywords are supported:

f D newmtl map_Ka map_Kd Ka Kd

And the following MTL statements are supported:

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. A floating-point value specifying in decimal degrees the counter-clockwise rotation of the 3D model about the y-axis, looking along the
219

VEModelOrientation.Roll Property

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

tilt

roll

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

VEModelOrientation.Tilt Property

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

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 VEModelScale.Y Property VEModelScale.Z Property

A floating-point value specifying the x-axis scale factor of a 3D model. A floating-point value specifying the y-axis scale factor of a 3D model. A floating-point value specifying the z-axis scale factor of a 3D model.

222

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

A floating-point value specifying the x-axis scale factor of a 3D model. Optional. The default value is 1. A floating-point value specifying the y-axis scale factor of a 3D model. Optional. The default value is 1. 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 xaxis, 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.

223

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 VEModelScale.Y Property VEModelScale.Z Property

A floating-point value specifying the x-axis scale factor of a 3D model. A floating-point value specifying the y-axis scale factor of a 3D model. 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.
224

VEModelScaleUnit Enumeration
An enumeration of scale units.

Syntax
VEModelScaleUnit { Inches, Feet, Yards, Millimeters, Centimeters, Meters }

Members
Member Description

Inches Feet Yards Millimeters Centimeters Meters

Scale is defined in inches. Scale is defined in feet. Scale is defined in yards. Scale is defined in millimeters. Scale is defined in centimeters. 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

225

Name

Description

VEModelSourceSpecification.Format Property

A VEModelFormat Enumeration value specifying the data format of the 3D model being imported. A VEShapeLayer Class specifying the shape layer into which the 3D model will be imported. A string specifying the URL of the 3D model data file.

VEModelSourceSpecification.Layer Property VEModelSourceSpecification.ModelSource Property

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. A string specifying the URL of the 3D model data file. Required. 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.

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

Public Properties
Name Description

VEModelSourceSpecification.Format Property

A VEModelFormat Enumeration value specifying the data format of the 3D model being imported. A VEShapeLayer Class specifying the shape layer into which the 3D model will be imported. A string specifying the URL of the 3D model data file.

VEModelSourceSpecification.Layer Property VEModelSourceSpecification.ModelSource Property

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
227

Member

Description

Success Failed

The 3D model was successfully loaded. 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 South East West

The image was taken looking toward the north. The image was taken looking toward the south. The image was taken looking toward the east. 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

228

Name

Description

VEPixel Constructor

Initializes a new instance of the VEPixel object.

Public Properties
Name Description

VEPixel.x Property VEPixel.y Property

Gets or sets the pixel's x coordinate. 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 y

The pixel's x coordinate. 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

229

Name

Description

VEPixel.x Property VEPixel.y Property

Gets or sets the pixel's x coordinate. 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 VEPlace.Locations Property

Gets a VELatLong Class object that represents the best location of the found result. An array of VEGeocodeLocation Class objects specifying all of the possible match results returned by the geocoder for this place. Gets the String object that represents the unambiguous name for the Bing Maps location.

VEPlace.Name Property

230

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. A VEMatchConfidence Enumeration value specifying the match confidence from the geocoder. This property value is only valid for where-only searches. A VELocationPrecision Enumeration value specifying the match precision from the geocoder for the best result, which is found in the VEPlace.LatLong property.

VEPlace.MatchConfidence Property

VEPlace.Precision 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 VEPlace.Locations Property

Gets or sets a VELatLong Class object that represents the location of the found result. An array of VEGeocodeLocation Class objects specifying all of the possible match results returned by the geocoder for this place. Gets the String object that represents the unambiguous name for the Bing Maps location. A VEMatchCode Enumeration value specifying
231

VEPlace.Name Property VEPlace.MatchCode Property

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. A VELocationPrecision Enumeration value specifying the match precision from the geocoder for the best result, which is found in the VEPlace.LatLong property.

VEPlace.Precision 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;
232

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.

233

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

234

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 VERoute.RouteLegs Property

A floating-point value that specifies the total length of the route. An array of VERouteLeg Class objects that specify the intermediate legs of the route.
235

Name

Description

VERoute.ShapePoints Property VERoute.Time Property

An array of VELatLong Class objects that identify the shape of the route. 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 VERoute.RouteLegs Property VERoute.ShapePoints Property VERoute.Time Property

A floating-point value that specifies the total length of the route. An array of VERouteLeg Class objects that specify the intermediate legs of the route. An array of VELatLong Class objects that identify the shape of the route. 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

236

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

Name

Description

VERouteDeprecated.Itinerary Property

A VERouteItineraryDeprecated Class object that specifies the itinerary (the step-by-step driving directions) of the route. A VERouteLocation Class object that specifies the starting point of the route.

VERouteDeprecated.StartLocation Property

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 VERouteDeprecated.Itinerary Property

A VERouteLocation Class object that specifies the final destination of the route. A VERouteItineraryDeprecated Class object that specifies the itinerary (the step-by-step driving directions) of the route. A VERouteLocation Class object that specifies the starting point of the route.

VERouteDeprecated.StartLocation Property

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
238

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 Kilometer

The route is shown in units of miles 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 VERouteHint.Text Property

A VERouteHintType Enumeration value specifying the type of the hint. A string that describes the route itinerary item
239

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 VERouteHint.Text Property

A VERouteHintType Enumeration value specifying the type of the hint. 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
240

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 NextIntersection Landmark

The hint describes the intersection that comes before the itinerary item. The hint describes the intersection that comes after the itinerary item. 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.
241

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 VERouteItineraryDeprecated.DistanceUnit Property VERouteItineraryDeprecated.RouteType Property VERouteItineraryDeprecated.Segments Property VERouteItineraryDeprecated.Time Property

The total distance of the route. A VEDistanceUnit Enumeration that defines the units (miles or kilometers) used in the route. A VERouteType Enumeration that defines the type of the route. An array of VERouteSegment Class objects, which define each segment of the total route. The total estimated driving time of the route.

242

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 VERouteItineraryDeprecated.DistanceUnit Property VERouteItineraryDeprecated.RouteType Property VERouteItineraryDeprecated.Segments Property VERouteItineraryDeprecated.Time Property

The total distance of the route. A VEDistanceUnit Enumeration that defines the units (miles or kilometers) used in the route. A VERouteType Enumeration that defines the type of the route. An array of VERouteSegment Class objects, which define each segment of the total route. 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.
243

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 VERouteItineraryItem.LatLong Property VERouteItineraryItem.Shape Property VERouteItineraryItem.Text Property VERouteItineraryItem.Time Property VERouteItineraryItem.Warnings Property VERouteItineraryItem.Hints Property

A floating-point number specifying the distance of the step A VELatLong Class object specifying the position of the step A VEShape Class object specifying the shape of the step A String specifying the description of the step An integer specifying the total elapsed time, in seconds, to traverse the route itinerary step. An array of VERouteWarning Class items that correspond to the itinerary item. An array of VERouteHint Class items that correspond to the itinerary item.

244

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 VERouteItineraryItem.LatLong Property VERouteItineraryItem.Shape Property VERouteItineraryItem.Text Property VERouteItineraryItem.Time Property VERouteItineraryItem.Warnings Property VERouteItineraryItem.Hints Property

A floating-point number specifying the distance of the step A VELatLong Class object specifying the position of the step A VEShape Class object specifying the shape of the step A String specifying the description of the step An integer specifying the total elapsed time, in seconds, to traverse the route itinerary step. An array of VERouteWarning Class items that correspond to the itinerary item. 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

245

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

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 VERouteLeg.Itinerary Property VERouteLeg.Time Property

A floating-point number specifying the length of the route leg. A VERouteItinerary Class object specifying the itinerary of the route leg. 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 VERouteLeg.Itinerary Property VERouteLeg.Time Property

A floating-point number specifying the length of the route leg. A VERouteItinerary Class object specifying the itinerary of the route leg. An integer specifying the total elapsed time, in seconds, to traverse the route leg.
247

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 VERouteLocation.LatLong Property

Specifies the street address (as a string) of the location. Specifies the latitude and longitude (as a VELatLong Class object) of the location.

248

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 VERouteLocation.LatLong Property

Specifies the street address (as a string) of the location. 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 Walking

The returned route contains driving directions The returned route contains walking directions

249

VERouteOptimize Enumeration
An enumeration specifying how a route is calculated.

Syntax
VERouteOptimize{ MinimizeTime MinimizeDistance }

Members
Member Description

MinimizeTime MinimizeDistance

The route is calculated to minimize time. 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. 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. The name of the function called when the
250

VERouteOptions.DrawRoute Property

VERouteOptions.RouteCallback Property

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). A VERouteMode Enumeration value specifying the mode of route to return. The default value is VERouteMode.Driving. A VERouteOptimize Enumeration value specifying how the route is optimized. The default value is VERouteOptimize.MinimizeTime. The thickness, in pixels, of the route line. The default value is 6 pixels. The z-index of the route line. The default value is 4. 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.RouteMode Property

VERouteOptions.RouteOptimize Property

VERouteOptions.RouteWeight Property VERouteOptions.RouteZIndex Property VERouteOptions.SetBestMapView Property

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 VERouteOptions.UseMWS Property Whether to show any error messages. The default value is true. A Boolean value specifying whether to use the MapPoint Web Service to generate the route. The default value is false. A Boolean value specifying whether to calculate the route using traffic information. The default value is false.

VERouteOptions.UseTraffic Property

251

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. 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. 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. The VEColor Class object specifying the color of the route line. The default value is default is VEColor(0,169,235,0.7). A VERouteMode Enumeration value specifying the mode of route to return. The default value is VERouteMode.Driving. A VERouteOptimize Enumeration object specifying how the route is optimized. The
252

VERouteOptions.DrawRoute Property

VERouteOptions.RouteCallback Property

VERouteOptions.RouteColor Property

VERouteOptions.RouteMode Property

VERouteOptions.RouteOptimize Property

Property

Description

default value is VERouteOptimize.MinimizeTime. VERouteOptions.RouteWeight Property VERouteOptions.SetBestMapView Property The thickness, in pixels, of the route line. The default value is 6 pixels. 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 VERouteOptions.UseMWS Property Whether to show any error messages. The default value is true. A Boolean value specifying whether to use the MapPoint Web Service to generate the route. The default value is false. A Boolean value specifying whether to calculate the route using traffic information. The default value is false.

VERouteOptions.UseTraffic Property

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

253

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

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

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
256

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 VERouteSegment.Distance Property VERouteSegment.LatLong Property

The driving instructions for this segment of the route. The distance of this segment of the route. A VELatLong Class object of the start point of this segment.

Remarks
The VERouteItineraryDeprecated.Segments Property contains an array of VERouteSegment objects.

257

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 VERouteSegment.Distance Property VERouteSegment.LatLong Property

The driving instructions for this segment of the route. The distance of this segment of the route. 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

258

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 Quickest

Generates the shortest (by distance) route 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 VERouteWarning.Text Property

A VERouteWarningSeverity Enumeration value specifying the severity level of the warning. A String that describes the route warning.

See Also
VERouteItineraryItem.Warnings Property
259

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 VERouteWarning.Text Property

A VERouteWarningSeverity Enumeration value specifying the severity level of the warning. 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.
260

Syntax
VERouteWarningSeverity{ None LowImpact Minor Moderate Serious }

Members
Member Description

None LowImpact Minor Moderate Serious

A warning which has no impact on traffic A warning which has low impact on traffic A minor traffic incident A moderate traffic incident 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. A Boolean value that specifies whether
261

VESearchOptions.CreateResults Property

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. 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. A Boolean value that specifies whether the map control moves the view to the first location match. The default value is true. 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. A Boolean value indicating whether the VEShape objects are visible. Optional. The default value is true. An integer specifying the beginning index of the results returned. Optional. The default value is 0. 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.

VESearchOptions.NumberOfResults Property

VESearchOptions.SetBestMapView Property

VESearchOptions.ShapeLayer Property

VESearchOptions.ShowResults Property

VESearchOptions.StartIndex Property

VESearchOptions.UseDefaultDisambiguation Property

See Also
VEMap.Search Method

VESearchOptions Constructor
Initializes a new instance of the VESearchOptions Class. Syntax var x = new VESearchOptions();
262

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. A Boolean value that specifies whether VEShape objects are created. The default value is true. A VEFindType Enumeration value that specifies the type of search performed. The only supported value is VEFindType.Businesses. 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. A Boolean value that specifies whether the map control moves the view to the first location match. The default value is true. 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. A Boolean value indicating whether the VEShape objects are visible. Optional. The default value is true. An integer specifying the beginning index of the results returned. Optional. The default value is 0.
263

VESearchOptions.CreateResults Property

VESearchOptions.FindType Property

VESearchOptions.NumberOfResults Property

VESearchOptions.SetBestMapView Property

VESearchOptions.ShapeLayer Property

VESearchOptions.ShowResults Property

VESearchOptions.StartIndex Property

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;

264

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

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 VEShape.onenddrag Event VEShape.onstartdrag Event

Occurs when a shape is being dragged across the map. Occurs when a shape drag has stopped. Occurs when the user starts dragging the shape.

Public Methods
Name Description

VEShape.GetAltitude Method VEShape.GetAltitudeMode Method VEShape.GetCustomIcon Method

Returns the altitude for the shape. Gets the mode in which the shape's altitude is represented. Gets the VEShape object's custom icon.
266

Name

Description

VEShape.GetDescription Method VEShape.GetFillColor Method VEShape.GetIconAnchor Method

Gets the description of the VEShape object. Gets the fill color and transparency for a polygon. Gets a VELatLong Class object representing the shape's custom icon anchor point. Gets the internal identifier of the VEShape object. Gets the line color or transparency for a polyline or polygon. Gets whether a line is drawn from the shape to the ground. Gets the line width of a polyline or polygon. Gets the maximum zoom level at which the shape is visible. Gets the minimum zoom level at which the shape is visible. Gets the shape's "more info" URL. Gets the shape's "photo" URL. Returns an array of VELatLong Class objects representing the points that make up the pushpin, polyline, or polygon. Gets the reference to the layer containing the specified VEShape object. Gets the title of the VEShape object. Gets the type of the VEShape object. Gets the z-index of a pushpin shape or pushpin attached to a polyline or polygon. Gets the z-index for a polyline or polygon. Hides the specified VEShape object from view. Hides the icon associated with a polyline or polygon. This method is ignored for

VEShape.GetID Method VEShape.GetLineColor Method VEShape.GetLineToGround Method VEShape.GetLineWidth Method VEShape.GetMaxZoomLevel Method VEShape.GetMinZoomLevel Method VEShape.GetMoreInfoURL Method VEShape.GetPhotoURL Method VEShape.GetPoints Method

VEShape.GetShapeLayer Method VEShape.GetTitle Method VEShape.GetType Method VEShape.GetZIndex Method VEShape.GetZIndexPolyShape Method VEShape.Hide Method VEShape.HideIcon Method

267

Name

Description

pushpins. VEShape.IsModel Method VEShape.SetAltitude Method VEShape.SetAltitudeMode Method VEShape.SetCustomIcon Method VEShape.SetDescription Method VEShape.SetFillColor Method VEShape.SetIconAnchor Method VEShape.SetLineColor Method VEShape.SetLineToGround Method VEShape.SetLineWidth Method VEShape.SetMaxZoomLevel Method VEShape.SetMinZoomLevel Method VEShape.SetMoreInfoURL Method VEShape.SetPhotoURL Method VEShape.SetPoints Method VEShape.SetTitle Method VEShape.SetZIndex Method VEShape.Show Method VEShape.ShowIcon Method Returns whether the shape is a model. Specifies the altitude for the shape. Specifies the mode in which a shape's altitude is represented. Sets the VEShape object's custom icon. Sets the description of the VEShape object. Sets the fill color and transparency of a polygon. Sets the info box anchor of the VEShape object. Sets the line color or transparency for a polyline or polygon. Specifies whether a line is drawn from the shape to the ground. Sets the line width for a polyline or polygon. Sets the maximum zoom level at which the shape is visible. Sets the minimum zoom level at which the shape is visible. Sets the shape's "more info" URL. Sets the shape's "photo" URL. Sets the points of the VEShape object. Sets the title of the VEShape object. Sets the z-index value for a shape. Makes the specified VEShape object visible. Shows the icon associated with a polyline or polygon. This method is ignored for pushpins.

268

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 points

A VEShapeType Enumeration value of type that represents the type of shape. Required. 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.

269

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 VEShape.onenddrag Event VEShape.onstartdrag Event

Occurs when a shape is being dragged across the map. Occurs when a shape drag has stopped. 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 LatLong Remarks

The VEShape object that fired the event. The current VELatLong of the shape.

270

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 LatLong Remarks

The VEShape object that fired the event. The current VELatLong of the shape.

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
271

VEShape.onstartdrag = function_name; Return Value A ShapeDragEventArgs object, which has the following properties:
Property Description

Shape LatLong Remarks

The VEShape object that fired the event. The current VELatLong of the shape.

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 VEShape.GetAltitudeMode Method VEShape.GetCustomIcon Method VEShape.GetDescription Method VEShape.GetFillColor Method VEShape.GetIconAnchor Method

Returns the altitude for the shape. Gets the mode in which the shape's altitude is represented. Gets the VEShape object's custom icon. Gets the description of the VEShape object. Gets the fill color and transparency for a polygon. Gets a VELatLong Class object representing the shape's custom icon anchor point.
272

Name

Description

VEShape.GetID Method VEShape.GetLineColor Method VEShape.GetLineToGround Method VEShape.GetLineWidth Method VEShape.GetMaxZoomLevel Method VEShape.GetMinZoomLevel Method VEShape.GetMoreInfoURL Method VEShape.GetPhotoURL Method VEShape.GetPoints Method

Gets the internal identifier of the VEShape object. Gets the line color or transparency for a polyline or polygon. Gets whether a line is drawn from the shape to the ground. Gets the line width of a polyline or polygon. Gets the maximum zoom level at which the shape is visible. Gets the minimum zoom level at which the shape is visible. Gets the shape's "more info" URL. Gets the shape's "photo" URL. Returns an array of VELatLong Class objects representing the points that make up the pushpin, polyline, or polygon. Gets the reference to the layer containing the specified VEShape object. Gets the title of the VEShape object. Gets the type of the VEShape object. Gets the z-index of a pushpin shape or pushpin attached to a polyline or polygon. Gets the z-index for a polyline or polygon. Hides the specified VEShape object from view. Hides the icon associated with a polyline or polygon. This method is ignored for pushpins. Returns whether the shape is a model. Specifies the altitude for the shape. Specifies the mode in which a shape's altitude is represented.

VEShape.GetShapeLayer Method VEShape.GetTitle Method VEShape.GetType Method VEShape.GetZIndex Method VEShape.GetZIndexPolyShape Method VEShape.Hide Method VEShape.HideIcon Method

VEShape.IsModel Method VEShape.SetAltitude Method VEShape.SetAltitudeMode Method

273

Name

Description

VEShape.SetCustomIcon Method VEShape.SetDescription Method VEShape.SetFillColor Method VEShape.SetIconAnchor Method VEShape.SetLineColor Method VEShape.SetLineToGround Method VEShape.SetLineWidth Method VEShape.SetMaxZoomLevel Method VEShape.SetMinZoomLevel Method VEShape.SetMoreInfoURL Method VEShape.SetPhotoURL Method VEShape.SetPoints Method VEShape.SetTitle Method VEShape.SetZIndex Method VEShape.Show Method VEShape.ShowIcon Method

Sets the VEShape object's custom icon. Sets the description of the VEShape object. Sets the fill color and transparency of a polygon. Sets the info box anchor of the VEShape object. Sets the line color or transparency for a polyline or polygon. Specifies whether a line is drawn from the shape to the ground. Sets the line width for a polyline or polygon. Sets the maximum zoom level at which the shape is visible. Sets the minimum zoom level at which the shape is visible. Sets the shape's "more info" URL. Sets the shape's "photo" URL. Sets the points of the VEShape object. Sets the title of the VEShape object. Sets the z-index value for a shape. Makes the specified VEShape object visible. 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.
274

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

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

276

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

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

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
279

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
280

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

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

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. A VEAltitudeMode Enumeration value specifying the mode in which the shape's altitude is represented.

altitudeMode

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

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

284

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

285

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
286

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
287

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 Remarks

An integer representing the line's width.

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
288

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 Exceptions

An integer specifying the maximum zoom level.

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 Exceptions

An integer specifying the minimum zoom level.

This method throws an exception if the level parameter is either less than 1 or greater than the current maximum zoom level.
289

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

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 Remarks

An array of VELatLong Class objects.

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

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

polyshape

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.

292

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 Route Icon ERO ERO Progress Bar Disambiguation Box Message box Find control Dashboard Minimap Route line Shape Polyshape Copyright Scalebar Logo Traffic tiles Custom tiles Map Road/Aerial/Hybrid tiles VE Container Examples VirtualEarthSDK#46 See Also VEShape.GetZIndex Method VEShape.GetZIndexPolyShape Method VEShape.Show Method

1000 998 500

201

199 100

60 50 31 or 30

30 2 1

Makes the specified VEShape object visible. This method only has an effect if the object was previously hidden using the VEShape.Hide Method. Syntax
293

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

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. Deletes all VEShape objects from the layer. Deletes a VEShape object from the current layer. Returns a best-fit VELatLongRectangle Class object based on the shapes currently present in the layer. Returns an array of VEClusterSpecification Class objects representing the calculated pushpin
295

VEShapeLayer.DeleteAllShapes Method VEShapeLayer.DeleteShape Method VEShapeLayer.GetBoundingRectangle Method VEShapeLayer.GetClusteredShapes Method

Name

Description

clusters. VEShapeLayer.GetDescription Method VEShapeLayer.GetShapeByID Method VEShapeLayer.GetShapeByIndex Method A String object containing the description of the VEShapeLayer object. Retrieves a reference to a VEShape object contained in this layer based on the specified ID. Retrieves a reference to a VEShape object contained in this layer based on the specified index. Returns the total number of shapes in the current layer. Gets the title of the VEShapeLayer object. Returns whether the layer is visible. Hides the layer from view on the map. Sets the method for determining which pushpins are clustered as well as how the cluster is displayed. Sets the description of the VEShapeLayer object. Sets the title of the VEShapeLayer object. Shows the layer on the map.

VEShapeLayer.GetShapeCount Method VEShapeLayer.GetTitle Method VEShapeLayer.IsVisible Method VEShapeLayer.Hide Method VEShapeLayer.SetClusteringConfiguration Method VEShapeLayer.SetDescription Method VEShapeLayer.SetTitle Method VEShapeLayer.Show Method

See Also
VEShapeType Enumeration VEShape Class

VEShapeLayer Constructor
Initializes a new instance of the VEShapeLayer class. Syntax var x = new VEShapeLayer();

296

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. Deletes all VEShape objects from the layer. Deletes a VEShape object from the current layer. Returns a best-fit VELatLongRectangle Class object based on the shapes currently present in the layer. Returns an array of VEClusterSpecification Class objects representing the calculated pushpin clusters. A String object containing the description of the VEShapeLayer object. Retrieves a reference to a VEShape object contained in this layer based on the specified ID. Retrieves a reference to a VEShape object contained in this layer based on the specified index. Returns the total number of shapes in the current layer. Gets the title of the VEShapeLayer object.

VEShapeLayer.DeleteAllShapes Method VEShapeLayer.DeleteShape Method VEShapeLayer.GetBoundingRectangle Method VEShapeLayer.GetClusteredShapes Method

VEShapeLayer.GetDescription Method VEShapeLayer.GetShapeByID Method VEShapeLayer.GetShapeByIndex Method

VEShapeLayer.GetShapeCount Method VEShapeLayer.GetTitle Method

297

Name

Description

VEShapeLayer.IsVisible Method VEShapeLayer.Hide Method VEShapeLayer.SetClusteringConfiguration Method VEShapeLayer.SetDescription Method VEShapeLayer.SetTitle Method VEShapeLayer.Show Method

Returns whether the layer is visible. Hides the layer from view on the map. Sets the method for determining which pushpins are clustered as well as how the cluster is displayed. Sets the description of the VEShapeLayer object. Sets the title of the VEShapeLayer object. 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
298

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

299

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

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 Remarks

The identifier of the VEShape object. Required.

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 Returns

The index of the shape to retrieve. Required.

301

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
302

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, Sets the algorithm for determining which options) Method 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

303

VEShapeLayer.SetClusteringConfiguration(type, options); Parameters

Name Description

type options

A VEClusteringType Enumeration specifying which shapes to cluster. Required. 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. A VEClusteringOptions Class object specifying
304

options

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
305

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 Pushpin

No shapes are accurately converted Only pushpins are accurately converted

306

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. A String specifying the layer source.

VEShapeSourceSpecification.LayerSource Property

VEShapeSourceSpecification.MaxImportedShapes Specifies the maximum number of items that Property 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
307

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 dataSource

A VEDataType Enumeration that specifies the type of data to import. Required. A URL representing the GeoRSS feed or KML data, or a globally-unique identifier (GUID) representing the Live Maps collection. Required. 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.

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

308

Name

Description

VEShape Class objects are contained after importing. VEShapeSourceSpecification.LayerSource Property A String specifying the layer source.

VEShapeSourceSpecification.MaxImportedShapes Specifies the maximum number of items that Property 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
309

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 Polyline Polygon

This represents a Shape object that is a pushpin. This represents a Shape object that is a polyline. 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

310

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. The unique identifier for the layer. Each tile layer on a map must have a unique ID. The maximum zoom level at which to display the custom tile source. The minimum zoom level at which to display the custom tile source. The number of servers on which the tiles are hosted. Specifies the opacity level of the tiles when displayed on the map. The location of the tiles. Specifies the z-index for the tiles.

VETileSourceSpecification.ID Property VETileSourceSpecification.MaxZoomLevel Property VETileSourceSpecification.MinZoomLevel Property VETileSourceSpecification.NumServers Property VETileSourceSpecification.Opacity Property VETileSourceSpecification.TileSource Property VETileSourceSpecification.ZIndex Property

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

311

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. The number of servers on which the tiles are hosted. Optional. The default value is 1. An array of VELatLongRectangle Class objects that specifies the approximate coverage area of the layer. Optional. The minimum zoom level at which to display the custom tile source. Optional. The maximum zoom level at which to display the custom tile source. Optional. When viewing a map in 2D mode, the function that determines the correct file names for the tiles. Optional. The opacity level of the tiles when displayed on the map. Optional. The z-index value for the tiles. Optional.

numServers bounds

minZoom maxZoom getTilePath

opacity zindex

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. The unique identifier for the layer. Each tile layer on a map must have a unique ID. The maximum zoom level at which to display the custom tile source.
312

VETileSourceSpecification.ID Property VETileSourceSpecification.MaxZoomLevel Property

Name

Description

VETileSourceSpecification.MinZoomLevel Property VETileSourceSpecification.NumServers Property VETileSourceSpecification.Opacity Property VETileSourceSpecification.TileSource Property VETileSourceSpecification.ZIndex Property

The minimum zoom level at which to display the custom tile source. The number of servers on which the tiles are hosted. Specifies the opacity level of the tiles when displayed on the map. The location of the tiles. 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.
313

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

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: %1this 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. %2if 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. %4the 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.
315

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%. If the map is not rendering properly, check that you have specified DOCTYPE at the beginning of your HTML page.
316

<body style="position:absolute;width:100%;height:100%;"

<!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 Internet Explorer 8.0 Internet Explorer 9.0 Firefox 2.0 Firefox 3.0 Firefox 3.5 Firefox 3.6 Firefox 4.0 Safari 2 Safari 3 Safari 4 Google Chrome

Supported on the PC Supported on the PC Supported on the PC Supported on the PC Supported on the PC Supported on the PC Supported on the PC Supported on the PC Supported on the Mac Supported on the Mac Supported on the Mac Supported on the PC

Supported on the PC Supported on the PC Supported on the PC Not supported Not supported Supported on the PC Supported on the PC Supported on the PC Not supported Not supported Supported on the Mac 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.
317

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. Select the File menu. Select the Page Setup menu item. Go to the Format and Options tab. Check Print Backgrounds. Select the File menu. Select the Print menu item. Click on the Copies & Pages drop-down box. Select Safari. Check Print Backgrounds.

In Firefox browsers:

In Safari browsers:

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.

318

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 maplic@microsoft.com 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.

319