Map Overlays Overview

Overlays are objects on the map that are tied to latitude/longitude coordinates, so they move when you drag or zoom the map. Overlays reflect objects that you "add" to the map to designate points, lines, or areas.

The Mapplets API has several types of overlays:

• Points on the map are displayed using markers, and often display a custom icon. Markers are objects of type GMarker and may make use of the GIcon type.
• Lines on the map are displayed using polylines (representing a sequence of points). Lines are objects of type GPolyline.
• Areas on the map are displayed either as polygons if they are areas of an arbitrary shape or as ground overlays if they are images. Polygons are similar to polylines in that they consist of a sequence of points forming a closed loop and may take any shape. Ground overlays are often useful for placing an image on top of the map (spanning a given GLatLngBounds).
• The map itself is displayed using a tile overlay. You can add your own set of tiles by using a GTileLayerOverlay.
• The info window is also a special kind of overlay. Note, however, that the info window is added to the map automatically, and that there can only be one object of type GInfoWindow attached to a map.

Overlays can be added to a map using the GMap2.addOverlay() method and removed using the GMap2.removeOverlay() method. (Note that the info window is added by default to the map.)

Markers

Markers identify points on the map. By default, they use use G_DEFAULT_ICON, though you can specify a custom icon. The GMarker constructor takes a GLatLng and an optional GMarkerOptions object as arguments.

Markers are designed to be interactive. By default, they receive "click" events, for example, and are often used with event listeners to bring up info windows.

This example displays 10 markers at random locations.

var map = new GMap2();

map.getBoundsAsync(function(bounds) {
  var southWest = bounds.getSouthWest();
  var northEast = bounds.getNorthEast();
  var lngSpan = northEast.lng() - southWest.lng();
  var latSpan = northEast.lat() - southWest.lat();

  for (var i = 0; i < 10; i++) {
    var point = new GLatLng(southWest.lat() + latSpan * Math.random(),
                            southWest.lng() + lngSpan * Math.random());
    map.addOverlay(new GMarker(point));
  }
});

Run this example (marker-simple.xml)

Draggable Markers

Markers are interactive objects that can be clicked on and dragged to a new location. In this example, we place a draggable marker on the map, and listen to a few of its simpler events. Draggable markers implement several kinds of events: click, dragstart, and dragend to indicate their drag status. (We don't generate drag events as we do in the Maps API during the drag as it would flood the mapplet queue with too many event requests.) By default, markers are clickable but not draggable, so they need to be initialized with the additional marker option draggable set to true. Draggable markers are also bouncy by default. If you don't like this behavior, just set the bouncy option to false and it will drop down gracefully.

var map = new GMap2();
var center = new GLatLng(37.4419, -122.1419);
map.setCenter(center, 13);

var marker = new GMarker(center, {draggable: true, bouncy: true});
map.addOverlay(marker);

GEvent.addListener(marker, "dragstart", function() {
  map.closeInfoWindow();
});

GEvent.addListener(marker, "dragend", function() {
  marker.openInfoWindowHtml("Just bouncing along...");
});

Run this example (marker-drag.xml)

Icons

Markers may define an icon to show in place of the default icon. Defining an icon is complex because of the number of different images that make up a single icon in the Maps API. At a minimum, an icon must define the foreground image, the size (of type GSize), and an icon offset to position the icon.

The simplest icons are based on the G_DEFAULT_ICON type. Creating an icon based on this type allows you to quickly change the default icon by modifying only a few properties.

In the example below, we create an icon using the G_DEFAULT_ICON type, and then modify it to use a different image. (Be careful using different images, as they need to be set up as the correct size as the default image to display properly.)

var map = new GMap2();
map.addControl(new GSmallMapControl());
map.setCenter(new GLatLng(37.4419, -122.1419), 13);

// Create our "tiny" marker icon
var blueIcon = new GIcon(G_DEFAULT_ICON);
blueIcon.image = "http://www.google.com/intl/en_us/mapfiles/ms/micons/blue-dot.png";
		
// Set up our GMarkerOptions object
markerOptions = { icon:blueIcon };

// Add 10 markers to the map at random locations
var bounds = map.getBounds();
var southWest = bounds.getSouthWest();
var northEast = bounds.getNorthEast();
var lngSpan = northEast.lng() - southWest.lng();
var latSpan = northEast.lat() - southWest.lat();
for (var i = 0; i < 10; i++) {
  var point = new GLatLng(southWest.lat() + latSpan * Math.random(),
    southWest.lng() + lngSpan * Math.random());
  map.addOverlay(new GMarker(point, markerOptions));
}

Run this example (icon-simple.xml)

Most icons contain a foreground image and a shadow image. The shadow image should be created at a 45 degree angle (upward and to the right) from the foreground image, and the bottom left corner of the shadow image should align with the bottom-left corner of the icon foreground image. Shadow images should be 24-bit PNG images with alpha transparency so that image boundaries appear correctly on the map.

This example creates a new type of icon, using the Google Ride Finder "mini" markers as an example. We have to specify the foreground image, the shadow image, and the points at which we anchor the icon to the map and anchor the info window to the icon. Note that the icon is passed in options defined in the GMarkerOptions object.

var map = new GMap2();

// Create our "tiny" marker icon
var tinyIcon = new GIcon();
tinyIcon.image = "http://labs.google.com/ridefinder/images/mm_20_red.png";
tinyIcon.shadow = "http://labs.google.com/ridefinder/images/mm_20_shadow.png";
tinyIcon.iconSize = new GSize(12, 20);
tinyIcon.shadowSize = new GSize(22, 20);
tinyIcon.iconAnchor = new GPoint(6, 20);
tinyIcon.infoWindowAnchor = new GPoint(5, 1);

// Add 10 markers to the map at random locations
map.getBoundsAsync(function(bounds) {
  var southWest = bounds.getSouthWest();
  var northEast = bounds.getNorthEast();
  var lngSpan = northEast.lng() - southWest.lng();
  var latSpan = northEast.lat() - southWest.lat();

  for (var i = 0; i < 10; i++) {
    var point = new GLatLng(southWest.lat() + latSpan * Math.random(),
                            southWest.lng() + lngSpan * Math.random());
    map.addOverlay(new GMarker(point, {icon:tinyIcon}));
  }
});

Run this example (icon-complex.xml)

Custom Icons

GIcon objects also have several other properties that you should set to get maximum browser compatibility and functionality from your icons. For example, the imageMap property specifies the shape of the non-transparent parts of the icon image. If you do not set this property in your icon, the entire icon image (including the transparency) will be clickable in Firefox/Mozilla. See the GIcon class reference for more information.

In many cases, your icons may have different foregrounds, but the same shape and shadow. The easiest way to achieve this behavior is to use the copy constructor for the GIcon class, which copies all the properties over to a new icon which you can then customize.

var map = new GMap2();

// Create a base icon for all of our markers that specifies the
// shadow, icon dimensions, etc.
var baseIcon = new GIcon();
baseIcon.shadow = "http://www.google.com/mapfiles/shadow50.png";
baseIcon.iconSize = new GSize(20, 34);
baseIcon.shadowSize = new GSize(37, 34);
baseIcon.iconAnchor = new GPoint(9, 34);
baseIcon.infoWindowAnchor = new GPoint(9, 2);
baseIcon.infoShadowAnchor = new GPoint(18, 25);

// Creates a marker whose info window displays the letter corresponding
// to the given index.
function createMarker(point, index) {
  // Create a lettered icon for this point using our icon class
  var letter = String.fromCharCode("A".charCodeAt(0) + index);
  var letterIcon = new GIcon(baseIcon);
  letterIcon.image = "http://www.google.com/mapfiles/marker" + letter + ".png";
  return new GMarker(point, {icon:letterIcon});
}

// Add markers A - J to the map at random locations
map.getBoundsAsync(function(bounds) {
  var southWest = bounds.getSouthWest();
  var northEast = bounds.getNorthEast();
  var lngSpan = northEast.lng() - southWest.lng();
  var latSpan = northEast.lat() - southWest.lat();

  for (var i = 0; i < 10; i++) {
    var point = new GLatLng(southWest.lat() + latSpan * Math.random(),
                            southWest.lng() + lngSpan * Math.random());
    map.addOverlay(createMarker(point, i));
  }
});

Run this example (icon-custom.xml)

Polylines

GPolyline objects create a linear overlay on the map. A GPolyline consists of a series of points and creates a series of line segments that connect those points in an ordered sequence.

Drawing Polylines

Polylines are drawn as a series of straight segments on the map. You can specify custom colors, weights, and opacities for the line. Colors should be in hexadecimal numeric HTML style, e.g., use #ff0000 instead of red. GPolyline does not understand named colors.

GPolyline objects use the vector drawing capabilities of the browser, if available. In Internet Explorer, Google Maps uses VML (see XHTML and VML) to draw polylines; in other browsers SVG is used if available. In all other circumstances, we request an image of the line from Google servers and overlay that image on the map, refreshing the image as necessary as the map is zoomed and dragged around.

This example displays a polyline with 5 random points. The polyline is red, 5 pixels thick, and has 70% opacity.

var map = new GMap2();

map.getBoundsAsync(function(bounds) {
  var southWest = bounds.getSouthWest();
  var northEast = bounds.getNorthEast();
  var lngSpan = northEast.lng() - southWest.lng();
  var latSpan = northEast.lat() - southWest.lat();

  var points = [];
  for (var i = 0; i < 5; i++) {
    points.push(new GLatLng(southWest.lat() + latSpan * Math.random(),
                            southWest.lng() + lngSpan * Math.random()));
  }

  map.addOverlay(new GPolyline(points, "#ff0000", 5, 0.7));
});

Run this example (polyline-simple.xml)

Geodesic Polylines

Polylines represented on the map are straight lines conforming to the current projection. That is, they appear straight on the map, but may in fact not properly account for the curvature of the earth. If you instead wish to draw a geodesic (a segment of a "great circle" representing the shortest distance between two points on the surface of the earth), you will need to pass geodesic:true in the GPolylineOptions argument of the GPolyline.

The GPolylineOptions object is an example of an object literal. With object literals, you don't construct an object. Instead, you pass the arguments as a series of name/value pairs within curly brackets. Object literals are used often in those cases where instantiating an object is unnecessary.

var map = new GMap2();
map.setCenter(new GLatLng(45.828799,-105.292969), 2);

// Create GPolylineOptions argument as an object literal.
// Note that we don't use a constructor.

var polyOptions = {geodesic:true};
var polyline = new GPolyline([
  new GLatLng(40.65642, -73.7883),
  new GLatLng(61.1699849, -149.944496)
  ], "#ff0000", 10, 1, polyOptions);
map.addOverlay(polyline);

Run this example (polyline-geodesic.xml)

Polygons

GPolygon objects are similar to GPolyline objects in that they consist of a series of points in an ordered sequence. However, instead of being open-ended, polygons are designed to define regions within a closed loop. As with polylines, you can define custom colors, weights, and opacities for the edge of the polygon (the "line") and custom colors and opacities for the fill area within the enclosed region. Colors should be in hexadecimal numeric HTML style.

GPolygon objects, like GPolyline objects, use the vector drawing capabilities of the browser, if available.

This example displays a polygon with 3 random vertices. The outline is is red, 5 pixels thick, and has 70% opacity. The polygon is filled with blue with 40% opacity.

var map = new GMap2();

map.getBoundsAsync(function(bounds) {
  var southWest = bounds.getSouthWest();
  var northEast = bounds.getNorthEast();
  var lngSpan = northEast.lng() - southWest.lng();
  var latSpan = northEast.lat() - southWest.lat();

  var points = [];
  for (var i = 0; i < 3; i++) {
    points.push(new GLatLng(southWest.lat() + latSpan * Math.random(),
                            southWest.lng() + lngSpan * Math.random()));
  }
  points.push(points[0]);   // Close the polygon

  map.addOverlay(new GPolygon(points, "#ff0000", 5, 0.7, "#0000ff", 0.4));
});

Run this example (polygon-simple.xml)

Ground Overlays

Polygons are useful overlays to represent arbitrarily-sized areas, but they cannot display images. If you have an image that you wish to place on a map, you can use a GGroundOverlay object. The constructor for a GGroundOverlay takes a URL of an image and the GLatLngBounds of the image as parameters.

The following example places an antique map of Newark, NJ on the map as an overlay:

var map = new GMap2();
map.setCenter(new GLatLng(40.740, -74.18), 12);
// ground overlay
 
var boundaries = new GLatLngBounds(new GLatLng(40.716216,-74.213393), new GLatLng(40.765641,-74.139235));
var oldmap = new GGroundOverlay("http://www.lib.utexas.edu/maps/historical/newark_nj_1922.jpg", boundaries);
map.addOverlay(oldmap);

Run this example (groundoverlay-simple.xml)

Tile Layer Overlays

Mapplets also may wish to display their own custom tiles over the main map. If the image is a single image, you would use a ground overlay, but you may wish to show many images at different zoom levels. In that case, you may wish to use a tile layer overlay similar to how the main maps tiles are displayed on Google Maps.

Creating a proper set of tile layer overlays involves creating a set of tiles for each zoom level you wish to have them displayed, and then defining a scheme to organize them and display based on the current viewport. Creating such a scheme requires an understanding of Google Maps Coordinates. If you are unfamiliar with Google Maps coordinates, consult that section before proceeding.

Implementing a tile overlay for other than a few simple zoom levels can be an onerous task, as you would need to add logic to determine which particular tile image to serve. Mapplets provides a way to construct GTileLayers based on a template system, passing arguments to the template as an object literal. The tileUrlTemplate property maps tile requests to URLs based on tile coordinates. The constructor for an overlay looks something like this:

var tileLayerOverlay = new GTileLayerOverlay(
  new GTileLayer(null, null, null, {
    tileUrlTemplate: 'http://domain.com/myimage_{Z}_{X}_{Y}.png', 
    isPng:true,
    opacity:1.0
  })
);

map.addOverlay(tileLayerOverlay); 

This template scheme allows you to address a collection of tile images named using tile coordinates as they are done within Google Maps.

Continue on to Mapplet Services.