Includes enterprise licensing and support
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:
|
GMarker
and may make use of the GIcon type.GPolyline.GLatLngBounds).GTileLayerOverlay.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 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)
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)
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)
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)
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.
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)
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)
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)
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)
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.