Adding Shapes to a Map

Article
08/26/2013

You are not viewing the latest version of the AJAX control. Bing Maps AJAX V7 is the recommended JavaScript control for Bing Maps. If you need this documentation, it is available in as a CHM or PDF download.

You can use shapes for tasks such as marking locations, highlighting geographical boundaries, and displaying information on a map.

Shape Basics

There are three types of shapes: pushpins, polylines, and polygons. These correspond to a point, a line, and a polygon, respectively, on a map. With the release of Version 5, all shape objects are consolidated under the VEShape Class. You can add shapes directly to the base layer of a map, or use the VEShapeLayer Class to create shape layers, which you can then use to create and manage arbitrary groups of shapes. Once the shape objects are added, you can set and get shape properties by calling methods against each object directly.

VEMap Shape Methods

Use the VEMap Class to add shapes to a map's base layer. This method adds an existing VEShape object to the base layer of the map. Use the VEMap.DeleteShape Method to delete a single shape from the base layer, and VEMap.DeleteAllShapes Method to delete all shape objects from the base layer.

VEShapeLayer Shape Methods

Use the VEShapeLayer.AddShape Method to add a shape. Use the VEShapeLayer.DeleteShape Method to delete a single shape from a layer, and VEShapeLayer.DeleteAllShapes Method method to delete all shape objects from a layer.

Setting and Getting VEShape Object Properties

Once a shape has been added to a map, use the methods of the VEShape class to set and get the shape's properties. These properties control aspects of the shape such as line color and width, fill color and transparency, custom icon, image file, Latitude/Longitude coordinates, and more. As of Version 5, the title and description properties can contain custom HTML, which you can use to further extend and modify your shapes.

Adding a Shape to a Map

Adding a shape to a map consists of the following steps:

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

Create the VEShape object. The following code creates a new polygon shape, "myPolygon", at the specified coordinates.
```
var myPolygon = new VEShape(VEShapeType.Polygon, points);
```
Add the VEShape object named "myPolygon" to the map.
```
var myPolygon = map.AddShape(myPolygon);
```

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" https://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="https://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),
         new VELatLong(41.01929,-104.06, 0, VEAltitudeMode. RelativeToGround),
         new VELatLong(41.003,-111.05878, 0, VEAltitudeMode. RelativeToGround)
      );

      function GetMap()
      {
         map = new VEMap('myMap');
         map.LoadMap();
         var myPolygon = new VEShape(VEShapeType.Polygon, points);
         map.AddShape(myPolygon);
         myPolygon.SetTitle("My Polygon");
         myPolygon.SetDescription("This is the description for my polygon.");
      }
      </script>
   </head>
   <body onload="GetMap();">
      <div id='myMap' style="position:relative; width:400px; height:400px;"></div>
   </body>
</html>

Adding a Shape Layer to a Map

Shape layers make it possible to create and manage multiple collections of shapes within a single map. Adding a shape to a shape layer consists of the following steps.

Initialize a new instance of the VEShapeLayer classVEShapeLayer Class.
```
var myShapeLayer = new VEShapeLayer();
```
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.

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

Create a VEShape object to add to the map.

var myShape = new VEShape(VEShapeType.Polygon, points);

Use the VEShapeLayer.AddShape method to add the shape to the shape layer.

myShapeLayer.AddShape(myShape);