Escolar Documentos
Profissional Documentos
Cultura Documentos
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
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
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">
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
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.
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
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
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
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.
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
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
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
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.
<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>
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
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.
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.
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>
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
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>
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.
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
= 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";
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.
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
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
The link to the installation program for the Bing Maps 3D software (and its prerequisites) is http://go.microsoft.com/fwlink/?LinkId=72623.
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.
Parameters
The following table contains available parameters for the map control handler.
Parameter Values Description
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
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
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
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
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 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
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
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
// 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);
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
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
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
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
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
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
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
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
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
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
Description
VEMap.onLoadMap Property
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
Description
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
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
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.GetShapeByID Method
VEShapeLayer.GetShapeByIndex Method
<html> <head> <title>Core Map Control Sample</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<script type="text/javascript">
</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
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";
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
<script type="text/javascript">
var map
= null;
CallRestService(geocodeRequest); 52
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
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
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.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.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
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
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
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
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
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
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
Public Properties
Name Description
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
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
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
Public Properties
Name Description
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
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
Public Properties
Name Description
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
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
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
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
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
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
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
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
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.
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.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
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
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
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
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
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
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
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
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
Public Methods
Name Description
VELatLong.SetAltitude Method
Public Properties
Name Description
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
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
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
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
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
VELatLongRectangle Class
Contains VELatLong Class objects that define the boundaries of the current map view.
Constructor
93
Name
Description
VELatLongRectangle Constructor
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
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.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
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
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
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
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
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.GetCenter Method
VEMap.GetDirections Method
VEMap.GetLeft Method VEMap.GetMapMode Method VEMap.GetMapStyle Method VEMap.GetMapView Method VEMap.GetPitch Method VEMap.GetRoute 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
101
Name
Description
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.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.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
Increases the map zoom level by 1. Decreases the map zoom level by 1.
Public Properties
Name Description
VEMap.onLoadMap Property
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
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
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.
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
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
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.
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
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
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.
Property
Description
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
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.
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
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.
117
Property
Description
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
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
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
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
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.
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
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
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
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
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 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
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
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
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
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
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
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
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.
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
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
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
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; } }
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
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.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
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.GetCenter Method
VEMap.GetDirections 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.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.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.Show3DNavigationControl Method
VEMap.ShowDashboard Method
VEMap.ShowDisambiguationDialog 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.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
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
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
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
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
/* 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 */
/* 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 */
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
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
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
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
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
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
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
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
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
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.
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
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
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.
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
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
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
object
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
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
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 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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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">
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
</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.
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
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
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
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
No match was found The match was good The match was ambiguous The match was found by a broader search
216
Member
Description
Modified
See Also
VEPlace.MatchCode Property
VEMatchConfidence Enumeration
A match confidence value as received from the geocoder.
Syntax
VEMatchConfidence{ High Medium Low }
Members
Member Description
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
Member
Description
Large
See Also
VEMap.ShowMiniMap Method
VEModelFormat Enumeration
An enumeration of 3D model formats.
Syntax
VEModelFormat{ OBJ }
Members
Member Description
OBJ
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
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
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
Public Properties
Name Description
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
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
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
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.
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.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
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
Public Properties
Name Description
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
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
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
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
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
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
Public Properties
Name Description
VEPrintOptions.EnablePrinting Property
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
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
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
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
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
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
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
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
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
VERouteLeg Class
Specifies the intermediate legs of the route.
Public Properties
Name Description
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
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
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
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
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.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
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
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
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
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
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
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
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
Public Events
Name Description
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
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%;"
If routes are not displaying on the map, check that charset is set to UTF-8 in the meta tag of your HTML page.
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.
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.
In Firefox browsers:
In Safari browsers:
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.
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