PushPins

Moving on from simply panning, zooming and generally controlling the map view it is also possible to add Pushpin markers. If you used the earlier version of Virtual Earth you will need to learn a slightly different way of doing the same job in Bing Maps V7.

There is an EntityCollection class which is the container for all of the graphical objects you might want to show on the map. For example to create a pushpin you first create PushPin object and then add it to the map's EntityCollection.

For example, first create a PushPin object at a specified location;

var pin=new  Microsoft.Maps.Pushpin(
 new Microsoft.Maps.Location(55, -1.5));

As before you don't have to create the Location object in the call you can re-use the one created earlier:

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

Once you have the push pin you can use its setOptions method to customise it. For example:

pin.setOptions( 
   {text:"MyPin",
    width:100,
    height:100});

sets the text displayed at the pins location and sets the area the pin occupies to 100x100. Notice that the display area set is used for the icon and the text.

Finally you need to add the pin to the map object:  

map.entities.push(pin);

If you want to see this in action change the button's event handler to read:

function Button1_onclick() 
{
 var Loc=new Microsoft.Maps.Location(55,-1.5);
 var viewOptions={center: Loc, zoom:5};
 var pin=new  Microsoft.Maps.Pushpin(Loc);
 pin.setOptions(
  {text:"MyPin",width:100,height:100});
 map.entities.push(pin);
 map.setView( viewOptions);
}

You can use a custom graphic for the push pin simply by setting the icon property to a URL that designates the file to be loaded. Notice also that you can specify the setOptions object as a second parameter when the pin is first created.

Shapes and entities

As well as Pushpin objects you can also use Polyline and Polygon objects to draw more complex shapes.  For example, the Polyline object accepts an array of locations and draws lines joining the points. For example to draw a closed triangle:

var positions=new Array(
 new Microsoft.Maps.Location(55, -2),
 new Microsoft.Maps.Location(54, 0),
 new Microsoft.Maps.Location(54, -1),
 new Microsoft.Maps.Location(55, -2)); 
var poly=new Microsoft.Maps.Polyline(
                             positions);
map.entities.push(poly);

You can also specify a second parameter as a PolylineOptions object which can be used to set strokeColor, strokeThickness and visibility.  For example to draw black lines you would use:

var poly=new Microsoft.Maps.Polyline(
 positions,
 {strokeColor:
   new Microsoft.Maps.Color(255,0,0,0)});

The Color object is used repeatedly to set the color of graphics entities.

The Polygon object works in the same way but it creates a filled area and you can specify a Fillcolor property.

The key to doing more complicated things with the Map control is to realise that the Entity collection is more sophisticated than it first appears.

You need to think of it as a list of graphics objects to be drawn on the map. The push method adds the graphical entity to the end of the list. Similarly the pop method removes the last item from the end of the list and returns it. So:

map.entities.push(poly);
var poly2=map.entities.pop();

first adds the Polygon to the EntityCollection and then removes it.

Each item in the collection has an index number, starting from zero, according to the order that they have been added in. So for example:

map.entities.indexOf(pin);

returns zero if pin was the first entity added.  Similarly getLength returns the number of entities in the collection. The removeAt(index) will remove the entity at the specified index and remove(entity) removes the entity without knowing its index - both methods return the removed entity. Similarly insert(entity,index) will insert the entity at the specified index location. Using these methods you can see that it is fairly easy to manipulate the EntityCollection.

There is one more sophistication to the way the  EntityCollection can be used.  You can create a new EntityCollection object, add entities to it and then add it as a single entity to the map. This is the way you can create groups of entities and control them. You can use the EntityCollectionsOptions object to set the entire collection visible and change its zIndex i.e. whether it is in front or behind other items.

For example: you can create a new EntityCollection and add a Polygon and a pin to it and then add it i.e. both the Polygon and the pin to the map:

var group1=
  new Microsoft.Maps.EntityCollection();
group1.push(poly);
group1.push(pin);
map.entities.push(group1);

Following this you can make the poly and the pin object invisible in one operation:

group1.setOptions({visible:false});

Using EntityCollections to organise your mapping activities is a big simplification.

<ASIN:1846288266>

<ASIN:1590597079>

<ASIN:3868020373>