Contents

• Introduction
  • XMaps Features
  • Red vs Green
  • Browser Compatibility
  • Updates
• Examples
  • Markers of any Shape, Color, and Size, and with Text
  • Adding Markers Fast
  • Long Polylines
  • Segmented Polylines
  • Polylines with Patterns
  • Polylines with Arrows
  • Polylines with Text
  • Polygons
  • Circles
  • Putting it All Together TODO
• Library Overview
  • Using XMaps with the API
  • Markers
  • Icons
  • Styles overview TODO
  • Polylines TODO
  • Polygons TODO
  • Font overview TODO
• Class Reference
  • XMaps
    • Static Methods
    • Static Properties
  • GMap (extension)
    • Methods
      • Overlays
  • GBounds (extension)
    • Static Methods
  • XMarker
    • Static Properties
    • Constructor
    • Methods
    • Events
  • XIcon
    • Static Properties
    • Constructor
    • Properties
      • Style Properties
  • XPolyline
    • Constructor
    • Properties
      • Style Properties
      • Text Foreground / Background Style Properties
  • XArrow
    • Constructor
  • XPolygon
    • Static Methods
    • Constructor
    • Properties
      • Outline Style Properties
      • Fill Style Properties
  • XDistance
    • Static Properties
      • Distance Units
      • Static Methods
    • Constructor
    • Properties
    • Methods
  • XAngle
    • Static Properties
      • Angle Units
    • Static Methods
    • Constructor
    • Properties
    • Methods
  • XModel
    • Static Properties
    • Constructor
    • Methods
  • XUserAgent
    • Static Properties
      • Browser Types
      • Operating Systems
    • Constructor
    • Properties

Introduction

XMaps Features

XMaps includes the following features:

• a method on GMap to speed up adding multiple overlays at once
• a new icon class that allows you to create multi-colored and scaled icons
• a new marker overlay that:
  • has a stripped-down pre-made marker using fewer resources
  • can render arbitrary layers on top of the icon (e.g., text)
  • can render XIcons
• a new polyline overlay that:
  • allows for longer polylines
  • can draw patterns along a polyline (e.g., dotted lines)
  • can draw arrows along a polyline
  • can draw arrows at the head and tail of a polyline
  • can break a polyline into smaller segments for more accurate long-distance polylines
  • can draw text that follows the shape of a polyline
  • can do any combination of these together
• a polygon overlay that:
  • lets you create convex and concave polygons
  • lets you create filled and unfilled polygons
  • lets you specify different colors and opacities for outlines and fills
  • makes use of the existing polyline technology to do all of this

These features all use existing resources required by the Google Maps API and nothing new besides the XMaps javascript file. Specifically, there are no external images or services that are required that Google Maps does not already provide. This is done for maximum portability.

Of course, you can use all of these features with any of the existing features of the Google Maps API.

Here's an snippet that creates a polyline that shows the distance between Seattle and Bellevue. Notice that the arrows on either end of the polyline and the text along it are all built-in features of the XPolyline, turned on by using their corresponding style attributes:

// Create our points.
var downtownSeattle = new GPoint(-122.330360, 47.606395);
var downtownBellevue = new GPoint(-122.198868, 47.610792);

// Create a map centered on Seattle.
var map = new GMap(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.centerAndZoom(new GPoint(-122.256546, 47.608246), 5);

// Set the end points of our polyline and determine the distance between them.
var points = [downtownSeattle, downtownBellevue];
var distance = XDistance.between(points[0], points[1]);
var distanceToShow = Math.round(distance.toMeters());

// Set up a red polyline with arrows on both ends, and displaying the distance.
var style = { color: '#ff0000',
              beginArrow: true,
              endArrow: true,
              text: distanceToShow + ' m' };

// Add our polyline to the map.
map.addOverlay(new XPolyline(points, style));

You can see this example (simple.html) here.

Red vs Green

In case you were wondering, green class names, method names, and event names indicate existing parts of the API, whereas red is something added by this library. All original code snippets are shown in red, as well.

Browser Compatibility

I actively debugged XMaps on Firefox, successfully tested it on IE, and I have not tried it on any other browser. I don't see why it should not work on other browsers, but I do not have them around so I can't try them out. If you find bugs in other browsers, I will try to fix them, but I may not be able to fix them at this time. If you can fix any bugs you see in other browsers, I will gladly integrate those fixes to XMaps.

Updates

I will be updating XMaps as I have time for it. The priority of new features will be based on how much I think I'll use them, though you're welcome to ask for features, and I'll do my best to add ones that are useful for everyone.

New releases of the XMaps javascript file will be labeled in the filename similar to how the API has been numbered. The current release is number 1: xmaps.1a.js. Note that XMaps probably still has a number of bugs, so saying that the relase number equals the version number is not really the case. I'd say the version number is ~0.1.

Examples

Markers of any Shape, Color, and Size, and with Text

Lets you click to add new dynamically-generated markers of random colors and increasing numbers.

var clickCount = 0;
var shapeNames = ['default', 'rounded-box', 'left-top-box', 'right-top-box', 'circle'];

function onLoad() {
  // Text Marker
  //

  // Center the map on Seattle
  var map = new GMap(document.getElementById("map"));
  map.addControl(new GSmallMapControl());
  map.addControl(new GMapTypeControl());
  map.centerAndZoom(new GPoint(-122.330360, 47.606163), 5);

  // Add 4 markers.
  var bounds = map.getBoundsLatLng();
  var width = bounds.maxX - bounds.minX;
  var height = bounds.maxY - bounds.minY;
  var markers = [];
  for (var i = 0; i < 4; i++) {
    var point = new GPoint(bounds.minX + width * Math.random(),
                           bounds.minY + height * Math.random());

    var icon = new XIcon('rounded-box', { fillColor: nextColor(), fillOpacity: 0.8, outlineWeight: 2 });
    var num = ++clickCount + '';
    var marker = new XMarker(point, icon, num, "sample mouseover", "You just made " + num + " disappear!");
    markers.push(marker);
  }

  map.addOverlays(markers);

  GEvent.addListener(map, 'click', function(overlay, point) {
    if (overlay) {
      map.removeOverlay(overlay);
    } else if (point) {
      var shapeName = shapeNames[Math.floor(Math.random() * shapeNames.length)];
      var icon = new XIcon(shapeName, { scale: 0.5 + Math.random() * 1.5, fillColor: nextColor(), fillOpacity: 0.8, outlineWeight: 2 });
      var marker = new XMarker(point, icon, ++clickCount + '');
      map.addOverlay(marker);
    }
  });
}

var colors = [null, '#68bf4c', '#4a8cc1', '#b449c2'];
var colorIndex = 0;
function nextColor() {
    if (colorIndex >= colors.length) {
        var r = (Math.round(Math.random() * 255)).toHexStr().substring(6);
        var g = (Math.round(Math.random() * 255)).toHexStr().substring(6);
        var b = (Math.round(Math.random() * 255)).toHexStr().substring(6);
        return '#' + r + g + b;
    } else {
        return colors[colorIndex++];
    }
}

View example (textmarker.html)

Adding Markers Fast

Adds 200 random markers with a single call to the map to avoid having to sort the overlays each time a marker is added.

// Center the map on Seattle
var map = new GMap(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.centerAndZoom(new GPoint(-122.330360, 47.606163), 5);

// Add 400 random markers in the map viewport using a stripped-down default icon
var bounds = map.getBoundsLatLng();
var width = bounds.maxX - bounds.minX;
var height = bounds.maxY - bounds.minY;
var markers = [];
for (var i = 0; i < 400; i++) {
    var point = new GPoint(bounds.minX + width * Math.random(),
                           bounds.minY + height * Math.random());
    var marker = new XMarker(point);
    markers.push(marker);
}

map.addOverlays(markers);

View example (addfast.html)

Long Polylines

GPolylines on browsers other than IE are restricted by URL length. XPolyline breaks up polylines into multiple images if they are too long for one image.

// Center the map on Seattle
var map = new GMap(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.centerAndZoom(new GPoint(-122.330360, 47.606163), 5);

// Create a polyline with 1000 random points.
var bounds = map.getBoundsLatLng();
var width = bounds.maxX - bounds.minX;
var height = bounds.maxY - bounds.minY;
var points = [];
var curr = new GPoint(bounds.minX + width / 2, bounds.minY + height / 2);
for (var x = 0; x < 1000; x++) {
    var point = new GPoint(curr.x + width / 50 * Math.random(),
                           curr.y + height / 50 * Math.random());
    points.push(point);
    curr = point;
}

map.addOverlay(new XPolyline(points));

View example (longpolyline.html)

Segmented Polylines

Polylines that are very long may show a straight line, but will that straight line does not necessarily follow the surface of the Earth, which is curved. To remedy this problem, XPolylines can be segmented to approximate following the Earth's surface.

// Center the map on the northern hemisphere
var map = new GMap(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.centerAndZoom(new GPoint(0, 47.606163), 16);

// Create a polyline with 1000 random points.
var bounds = map.getBoundsLatLng();
var width = bounds.maxX - bounds.minX;
var height = bounds.maxY - bounds.minY;
var points = [];
for (var x = 0; x < 4; x++) {
        var point = new GPoint(bounds.minX + width * Math.random(),
                               bounds.minY + height * Math.random());
    map.addOverlay(new XMarker(point));
    points.push(point);
}

var style = { segmentCount: 20 };

map.addOverlay(new XPolyline(points, style));

View example (segmented.html)

Polylines with Patterns

With XPolyline, you can create patterns for your polylines so that they are dotted, dashed, or practically any pattern you want.

The pattern is specified by a series of alternating numbers. Each even number specifies the number of pixels to show. Each odd number specifies the number of pixels to hide. Pattern arrays must have an even number of entries.

// Center the map on Seattle
var map = new GMap(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.centerAndZoom(new GPoint(-122.330360, 47.606163), 5);

// Create a polyline with 4 random points.
var bounds = map.getBoundsLatLng();
var width = bounds.maxX - bounds.minX;
var height = bounds.maxY - bounds.minY;
var points = [];
for (var i = 0; i < 4; i++) {
    var point = new GPoint(bounds.minX + width * Math.random(),
                           bounds.minY + height * Math.random());
    points.push(point);
}
points.sort(function(p1, p2) { return p1.x - p2.x; });

var style = { pattern: [20, 10, 5, 10] };

map.addOverlay(new XPolyline(points, style));

View example (pattern.html)

Polylines with Arrows

Arrows can be be specified to appear along a polyline every x number of pixels, or at the beginning or end of a polyline, or any combination of these.

Arrows are created as pre-made polylines to allow for colors other than the blue arrows used on maps.google.com.

// Center the map on Seattle
var map = new GMap(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.centerAndZoom(new GPoint(-122.330360, 47.606163), 5);

// Create a polyline with 4 random points.
var bounds = map.getBoundsLatLng();
var width = bounds.maxX - bounds.minX;
var height = bounds.maxY - bounds.minY;
var points = [];
for (var i = 0; i < 4; i++) {
    var point = new GPoint(bounds.minX + width * Math.random(),
                           bounds.minY + height * Math.random());
    points.push(point);
}
points.sort(function(p1, p2) { return p1.x - p2.x; });

var style = { arrowsEvery: 200 };

map.addOverlay(new XPolyline(points, style));

points = [];
for (var i = 0; i < 2; i++) {
    var point = new GPoint(bounds.minX + width * Math.random(),
                           bounds.minY + height * Math.random());
    points.push(point);
}
var distance = XDistance.between(points[0], points[1]);
var distanceInMeters = Math.round(distance.toMeters());

style = {
    color: '#ff7777',
    opacity: 1,
    beginArrow: true,
    endArrow: true,
    text: distanceInMeters + ' m',
    textEvery: 50 };

map.addOverlay(new XPolyline(points, style));

View example (arrows.html)

Polylines with Text

XPolylines allow for text to be drawn along the length of the polyline. This text can be repeated at a certain pixel interval.

Text is rendered as two separate polylines, one for the foreground, and one for the background. The "font" used can be chosen from the wide selection of the 1 font provided (unless you create your own!). Fonts are specified in pixels as coordinates around a center point so that characters can be rotated. Text weight can be specified to create a kind of bold typeface. If you hack the text rendering code, I bet you can make it shear like an italic typeface. =)

// Center the map on Seattle.
var map = new GMap(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.centerAndZoom(new GPoint(-122.330360, 47.606163), 5);

// Create a polyline in the shape of an ellipse with some text on it.
var bounds = map.getBoundsLatLng();
var width = bounds.maxX - bounds.minX;
var height = bounds.maxY - bounds.minY;
var points = [];
for (var i = 0; i <= 100; i++) {
    var point = new GPoint(bounds.minX + width / 2 + width / 3 * Math.cos(i / 100 * 2 * Math.PI),
                           bounds.minY + height / 2 + height / 3 * Math.sin(i / 100 * 2 * Math.PI));
    points.push(point);
}

var style = { text: "* ABC xyz 123 *", color: '#ff7777', textFgStyle: { color: '#ffffff' } };

map.addOverlay(new XPolyline(points, style));

View example (text.html)

Polygons

XPolygon can create convex and concave polygons. Outlines and fills can be specified separately.

XPolygon will automatically add the last segment to close a polygon.

Polygon fills are rendered using an XPolyline, and thus have rounded edges. To hide these edges, polygons should have outlines. Polygon outlines are rendered as normal XPolylines. To correctly hide the rounded caps of polygon fills, the fill will be rendered with the same weight as the outline (unless specified otherwise). This means that polygons with smaller weights will take more time to render. The default weight is 5.

// Center the map on Seattle
var map = new GMap(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.centerAndZoom(new GPoint(-122.330360, 47.606163), 5);

// Create a polygon with 4 random points.
var bounds = map.getBoundsLatLng();
var width = bounds.maxX - bounds.minX;
var height = bounds.maxY - bounds.minY;
var points = [];
for (var i = 0; i < 4; i++) {
    var point = new GPoint(bounds.minX + width * Math.random(),
                           bounds.minY + height * Math.random());
    points.push(point);
}
points.sort(function(p1, p2) { return p1.x - p2.x; });

var outlineStyle = { pattern: [20, 10, 5, 10] };
var fillStyle = {};

map.addOverlay(new XPolygon(points, outlineStyle, fillStyle));

View example (polygon.html)

Circles

XCircles can be created two main ways. One way is to specify two points, the center and a point on the radius. The other is to specify the center and a radius (with an associated distance type).

// Center the map on Seattle
var map = new GMap(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.centerAndZoom(new GPoint(-122.330360, 47.606163), 5);

// Create a circle by specifying a radius.
var center = new GPoint(-122.330360, 47.606163);
var radius = new XDistance(1, XDistance.KM);
var outlineStyle = {};
var fillStyle = {};
map.addOverlay(XPolygon.createRegularPolygonFromRadius(center, radius, 36, 0, outlineStyle, fillStyle));

// Create a circle by specifying a point on the edge.
center = new GPoint(-122.330360, 47.606163);
var spaceNeedle = new GPoint(-122.349222, 47.620498);
outlineStyle = { pattern: [20, 10, 5, 10], opacity: 0.45 };
fillStyle = null;
map.addOverlay(XPolygon.createRegularPolygonFromPoint(center, spaceNeedle, 36, outlineStyle, fillStyle));

View example (circle.html)

Putting it All Together

Here we put some of the above elements together to show some information about the first atomic bomb, which was detonated on July 16, 1945, 60 years ago to the day from when I wrote this example. We use circles with text that show the radius of the circles to show how far some of the effects were seen.

// atomic bomb example TODO!

View example (alltogether.html)

Library Overview

Using XMaps with the API

XMaps extends the features of the Google Maps API both by extending existing classes and introducing new classes.

The additions and changes in XMaps are designed to cause a minimal impact on your coding. If you are already familiar with the Google Maps API, then this library should seem very natural to use. This is especially true with overlays. XMaps adds three new overlays to your arsenal and each one uses the same interface as existing overlays.

To get started using the XMaps library, just inlcude a script tag linking to the current release of the library after your script tag for the API.

<script src="http://xmaps.busmonster.com/script/xmaps.1a.js"></script>

Please realize that I depend on some features of the Google Maps API that are not currently documented and so may change when the API script is updated. I have tried to minimize dependencies like this that may break some of XMaps when Google Maps API updates change underneath this library, but I cannot guarantee that there will be no problems from minor update to minor update. I will, of course, try to fix any problems that occur when updates happen.

Markers

GMarkers are limited in that they can have one icon with one image, and that's it. XMarker fixes this by allowing any HTML string or HTML DOM element to be added to the marker as a part of its display. Here's a simple example that writes my name at the marker's point:

var myMarker = new XMarker(new GPoint(-122, 45), null, "Chris Smoak");

Icons

GIcons are limited in that you must have the images used for the icon pre-rendered on a server somewhere. XIcon fixes this by giving you a very versatile icon generation tool. Say we wanted icons that were in the shape of a triangle, pointing down at the point specified. Here's how we woould go about adding this icon:

First, we'll create the icon's shape. I've decided to create a triangle approximately 30 pixels on a side. This shape has a number of properties that we'll need to determine in order for the icon to render correctly. Here's our triangle shape:

var triShape = {
    iconAnchor: new GPoint(15, 26),
    infoWindowAnchor: new GPoint(15, 0),
    shadow: true,
    contentAnchor: new GPoint(0, 0),
    contentSize: new GSize(31, 20),
    points: [0,0,15,26,30,0]
};

Here's an explanation for each property:

iconAnchor is the pixel on the icon's image which should be tied to the point on the map

infoWindowAnchor is the pixel on the icon's image which should be tied to the bottom point of the info window

shadow determines if we want a shadow for this icon (the shadow is created automatically for us)

contentAnchor is the top left pixel on the icon's image that should be used for any HTML content on top of the icon, like text

contentSize is the size, in pixels, of the box in which HTML content is allowed

points is an array of x/y pairs that define the shape of the icon. In this case, these three pairs define an upside-down triangle

Now, we are ready to put our shape into the shape hash. This is done so that our shape can be referred to by name so that we can cache our shape for better performance. Here's what we need to do:

XIcon.shapes['triangle'] = triShape;

Ok, so now we have our shape 'registered', and we are ready to use it. When we instantiate it, we have a number of properties we can specify. Each of these has defaults, so you don't always have to specify all of them, but I will here to show you an example of each property:

var triStyle = {
    scale: 1.5,
    outlineColor: '#ffffff',
    outlineWeight: 2,
    fillColor: '#7f00ff',
    fillOpacity: 0.5
};

Ok, so here's what each property does:

scale specifies how big we want our icon. Since I specified 1.5, we will end up with a triangle with approximately 30 * 1.5 = 45 pixels per side.

outlineColor specifies the color for the outline of the icon. Here, we're using a white outline

outlineWeight specifies the width, in pixels, of the icon's outline

fillColor specifies the color of the interior of the icon

fillOpacity specifies the opacity of the interior of the icon, and must be in the range 0 to 1

So, now we're ready to instantiate our icon. Here's the statement:

var triIcon = new XIcon('triangle', triStyle);

Now we have an icon we can use with any XMarker. Here, we'll plot one:

var triMarker = new XMarker(new GPoint(-71.542969, 27.371767), triIcon, "?", "The Bermuda Triangle");
map.addOverlay(triMarker);

And there you go, a brand new icon that we can use over and over. Here's the example we just created:

View Example (triangle.html)

More Documentation here... TODO

Class Reference

XMaps

The XMaps class is a collection of generally useful methods and global (gasp) variables. This class is not meant to be instantiated and is initialized with defaults. Many of the methods exposed by this class are copies or near-copies of functions in the Google Maps API that are not exposed anywhere but that I felt should be.

Static Properties

Property	Description
defaultFont	The default font for use with text along polylines.
falseFunction	Returns a function that always returns false
imageBaseUrl	The base of marker images used by XMarker.
model	A model of the planet earth, of type XModel, to allow for distance calculations. Changing this property's value will affect how segmented polylines are created and how distances are calculated.
userAgent	An XUserAgent object with properties describing the current user's browser.

Static Methods

Method	Description
addClassName(element, className)	A method to add the class name className to the style attribute of element.
combineStyles(overridingStyle, baseStyle, outStyle?)	Returns a new object (or outStyle, if specified) with all properties of baseStyle, overridden with any properties in overridingStyle
getElementById(id)	A generalized way of getting an element by its id attribute. Currently, there is nothing really generalized or special about this method.
integerCompare(a, b)	A comparator for sorting numbers. a and b are both numbers.
toPixelString(pixels)	A silly method to round the number pixels and return a string with 'px' appended to the end of it.

GMap (extension)

One method on GMap is added to allow for multiple overlays to be added at once.

Methods

Overlays

Method	Description
addOverlays(overlays)	Adds each of the given overlays in the array to the map

GBounds (extension)

This extension of the GBounds class consists of methods to create new extensible bounds.

Static Methods

Method	Description
createMinBounds()	Factory method to create an instance of the minimal bounds possible so that virtually any call to extend will extend these bounds.
createMaxBounds()	Factory method to create an instance of the maximum bounds possible so that virtually any call to intersection will reduce these bounds.

XMarker

XMarker is a marker overlay which is interchangeable with a GMarker once created, but allows for the added ability to display an XIcon, and the ability to add html on top of the icon, allowing for text or other images to be layered on the marker. Tooltips are also supported.

Static Properties

Constructor	Description
defaultIcon	A lightweight version of the default Google Maps icon that is not suitable for printing
defaultPrintableIcon	An exposed version of the default Google Maps icon in case you want to use it
noIcon	An icon with nothing visible. This is useful for using just layers to display a marker

Constructor

Constructor

Description

XMarker(point, icon?, iconContent?, hoverContent?, infoWindowContent?)

Creates a marker with the given icon at the given point. If iconContent is specified and the icon is an XIcon, the content will be displayed within the icon. If hoverContent is specified, then a mouseover will be set up on the icon. If infoWindowContent is specified, then a click trigger will be set up to display that content in the info window when the icon is clicked. iconContent, hoverContent, and infoWindowContent can be either an HTML DOM element, a string of HTML, or a function that takes the marker instance and returns either an HTML DOM element or a string of HTML. icon should be an XIcon or a GIcon. If no icon is given, a lightweight version of the default Google Maps icon is used (not suitable for printing or iconContent).

Methods

Method	Description
openInfoWindow(htmlElem)	Opens an info window with the given HTML content over this marker. htmlElem should be an HTML DOM element.
openInfoWindowHtml(htmlStr)	Like openInfoWindow, but takes an HTML string rather than an HTML DOM element
openInfoWindowXslt(xmlElem, xsltUri)	Like openInfoWindow, but takes an XML element and the URI of an XSLT document to produce the content of the info window. The first time a URI is given, it is downloaded with GXmlHttp and subsequently cached.
showMapBlowup(zoomLevel?, mapType?)	Shows a blowup of the map over this marker. We use a default zoom level of 1 and the current map type if the zoomLevel and mapType parameters are not given.

Events

Event	Arguments	Description
click	none	Triggered when the user clicks on this marker
infowindowopen	none	Triggered when the info window is opened above this marker with one of the methods above
infowindowclose	none	Triggered when the info window above this marker is closed
onmouseover	none	Triggered when the mouse hovers over the marker's icon
onmouseout	none	Triggered when a mouse hover over the marker's icon ends

XPolyline

XPolyline provides a richer polyline overlay for use with Google Maps. XPolyline increases the maximum number of points a polyline can have by breaking up long polylines into multiple images on non-IE browsers. A number of effects can be used with an XPolyline:

• Patterns (e.g., dashed lines)
• Arrows along the polyline
• Arrows at the beginning and/or end of the polyline
• Text along a polyline
• Approximations of the great circle path of the polyline

Any combination of these effects can be used together on a single polyline, and no changes to the polyline's set of points is required; each effect is performed internally during the rendering of the polyline.

Polyline options such as color, weight, opacity, and effects used are specified in a generic style object. The available properties of this style object are listed below.

Patterns are specified by a sequence of numbers specifying alternating numbers of pixels to draw and hide. For example, the pattern [20, 10, 5, 10] will display 20 pixels along the polyline, then hide the next 10, then display the next 5, then hid the next 10, and then repeat for the length of the polyline. Pattern arrays must be of even length.

Arrows can be displayed along the polyline at a specified pixel interval. Arrows are displayed in the direction of the polyline at that point and they have the same color and opacity as the polyline.

Arrows may also be displayed at the beginning and/or end of a polyline, facing outwards.

Text can be displayed along the length of a polyline at a specified pixel interval. Text is attempted to be written the right way up. A background mask of the text is created to increase readability. Any string of characters that are supported by the font being used can be drawn. The default (and unless you create one, only) font has lowercase and uppercase english letters, numbers, and some punctuation.

A great circle path is the shortest paths between two places on the earth, and may not be straight when plotted on the Mercator projection that Google Maps currently uses. An approximation of the great circle path will break your polyline into a specified number of segments and display this approximation between each consecutive point in the polyline.

Constructor

Constructor	Description
XPolyline(points, style?)	Constructs a polyline from the given array of lat/lng points. style is discussed below, and will default to the same color, opacity, and weight as the standard GPolyline.

Properties

Style Properties

Property	Description
color	The color of the polyline as a hex string.
weight	The width, in pixels, of the polyline.
opacity	The opaqueness of the polyline, represented as a number between 0 and 1 with 1 being completely opaque.
pattern	An even length array of integers, specifying alternating numbers of pixels to show or hide along the path of the polyline.
segmentCount	The number of segments to be used in each approximation of a great circle path.
beginArrow	A boolean value specifying whether an arrow is to be displayed at the first point of the polyline.
endArrow	A boolean value specifying whether an arrow is to be displayed at the last point of the polyline.
arrowsEvery	The number of pixels between each arrow displayed along the path of the polyline.
zIndex	The initial z-index of the polyline.
font	An object conforming to the font specification.
text	The text to display along the polyline.
textEvery	The number of pixels between each rendering of the text along the polyline.
textFgStyle	The text foreground style object, described below.
textBgStyle	The text background style object, described below.

Text Foreground / Background Style Properties

Property	Description
color	The color of the polyline as a hex string.
weight	The width, in pixels, of the polyline.
opacity	The opaqueness of the polyline, represented as a number between 0 and 1 with 1 being completely opaque.
zIndex	The initial z-index of the text layer.

XIcon

An XIcon is an icon that is specified by a shape describing the outline of the icon. From this shape, the icon and its shadow (if specified) images are created and cached for performance. When instantiated, styles can be applied to shapes to set the size, color, and opacity of the icon. A few shapes are provided:

• default - The default Google Maps icon
• rounded-box - A rounded box bubble made to look like the icons The Piggy Bank uses
• left-top-box - A box above and to the left of the point
• right-top-box - A box above and to the right of the point
• circle - A circle centered on the point (with no shadow)

Additional shapes can be made and added to the XIcon.shapes hash.

Static Properties

Property	Description
shapes	A hash of the various shapes with the shape name as the key and the object describing shape properties as the value. The default shape is in this hash be default

Constructor

Constructor	Description
XIcon(shapeName?, style?)	Creates a new icon, using the specified shape and style. The shape defaults to the default Google Maps icon shape if no name is given or it is null.

Properties

Style Properties

Property	Description
scale	The scale of the icon, with 1 being the default size and reasonable sizes being within the range 0.5 to 2
outlineColor	A hex string representing the color of the icon's border
outlineWeight	A positive integer representing the pixel width of the border
fillColor	A hex string representing the color of the interior of the icon
fillOpacity	A number from 0 to 1 representing the opacity of the interior of the icon

XArrow

An arrow is an overlay that points in a direction given by two points. Arrows are a more generic version of the arrow used by Google Maps using maplinedraw, and can be of various colors and sizes. An arrow is rendered as a triangle using a specialized version of the polygon-drawing algorithm used by XPolygon and so creates an image using maplinedraw.

Constructor

Constructor	Description
XArrow(from, to, at, color?, opacity?, size?, weight?)	Creates an arrow overlay pointing from the point from, to the point to at the point specified by at. Color is a hex string and opacity is a float between 0 and 1. Size determines the width, in pixels, of a side, and weight determines the width of the line used to draw the outline of the triangle.

XPolygon

A polygon represents a closed shape overlay on the map. Polygons are drawn using separate XPolylines for the outline and the fill of the overlay. Outline polylines may have any of the features normal XPolylines may have, but fill polylines are not as extensible.

Due to the current implementation method for polygons, filled polygons may suffer performance problems. Filled polygons that take up a large amount of the screen or filled polygons that have a small outline weight (the default is 5) may render slowly. This problem is being worked on, though the true solution to this is probably to wait until Google comes out with a polygon overlay that uses server-side rendering for non-IE browsers.

If polygon outlines make use of the segmented effect, fills will not be accurate.

Static Methods

Method	Description
createRegularPolygonFromRadius(center, radius, numPoints?, startAngle?, outlineStyle?, fillStyle?)	Creates a regular polygon specified by its center and radius. center is a GPoint. radius is an XDistance or a number representing the radius in meters. numPoints should be an integer larger than 2. To approximate a circle, try numbers larger than 30 for numPoints. startAngle is either an XAngle or an number representing an angle in radians, and specifies at what angle off of 0 should the first point be placed. The style arguments work like other styles and properties of these styles are discussed below.
createRegularPolygonFromPoint(center, point, numPoints?, outlineStyle?, fillStyle?)	Creates a regular polygon specified by the center and one of its points. center is a GPoint. radius is an XDistance or a number representing the radius in meters. numPoints should be an integer larger than 2. To approximate a circle, try numbers larger than 30 for numPoints. The style arguments work like other styles and properties of these styles are discussed below.

Constructor

Constructor

Description

XPolygon(points, outlineStyle?, fillStyle?)

Creates an overlay with the array of lat/lng points specified. The last point of the points array does not need to be a repeat of the first point to close the polygon. If outlineStyle is not null, and outline will be drawn. If fillStyle is not null, the polygon will be filled. Due to the way polygons are rendered, it is recommended to always use an outline with an opacity of 1 and a weight no less than 5. To see how styles work, see the styles guide.

Properties

Outline Style Properties

See XPolyline style properties

Fill Style Properties

Property	Description
color	The color of the polyline as a hex string.
weight	The width, in pixels, of the polyline.
opacity	The opaqueness of the polyline, represented as a number between 0 and 1 with 1 being completely opaque.
zIndex	The initial z-index of the polyline.

XDistance

XDistance represents a specific distance and unit of length. The units currently defined are:

• meters - XDistance.M
• kilometers - XDistance.KM
• feet - XDistance.FT
• miles - XDistance.MI
• nautical miles - XDistance.NM

An XDistance's measurement can be converted to any of these units by calling its corresponding "to" method. For example, a distance created as var d = new XDistance(12, XDistance.MI) represents a distance of 12 miles, and its length in meters can be found by doing d.toMeters(), which in this case, will return the number 19312.128.

Static Properties

Distance Units

Property	Description
M	Represents a meters unit of measurement
KM	Represents a kilometers unit of measurement
FT	Represents a feet unit of measurement
MI	Represents a miles unit of measurement
NM	Represents a nautical miles unit of measurement

Static Methods

Method	Description
between(point1, point2)	Returns a number representing the distance in meters
convert(value, fromUnits, toUnits)	Returns a number representing the distance in the specified units

Constructor

Constructor	Description
XDistance(value, units)	Creates a new distance with the given value and units. value is a number and units is one of the pre-defined constants.

Properties

Property	Description
value	The distance measurement
units	The measurement units

Methods

Method	Description
convert(toUnits)	Returns a number representing the distance in the specified units
toMeters()	Returns a number representing the distance in meters
toKilometers()	Returns a number representing the distance in kilometers
toFeet()	Returns a number representing the distance in feet
toMiles()	Returns a number representing the distance in miles
toNauticalMiles()	Returns a number representing the distance in nautical miles

XAngle

XAngle represents a specific angle and unit of angle. The units currently defined are:

• radians - XAngle.RAD
• degrees - XAngle.DEG

An XAngle's measurement can be converted to the other unit by calling its corresponding "to" method. For example, a distance created as var a = new XAngle(Math.PI, XAngle.RAD) represents a distance of PI radians, and its corresponding measure in degrees can be found by calling a.toDegrees(), which in this case, will return the number 180.

Static Properties

Property	Description
radToDeg	The factor needed to convert radians to degrees
degToRad	The factor needed to convert degrees to radians

Angle Units

Property	Description
RAD	Represents a radians unit of measurement
DEG	Represents a degrees unit of measurement

Static Methods

Method	Description
convert(value, fromUnits, toUnits)	Returns a number representing the angle in the specified units
radiansToDegrees(radians)	Returns a number representing the radians value in degrees. radians is a number.
degreesToRadians(degrees)	Returns a number representing the radians value in degrees. degrees is a number.
normalizeRadians(radians)	Returns a equivalent radians value satisfying: 0 <= radians < 2 * Math.PI
normalizeDegrees(degrees)	Returns a equivalent degrees value satisfying: 0 <= degrees < 360

Constructor

Constructor	Description
XAngle(value, units)	Creates a new angle with the given value and units. value is a number and units is one of the pre-defined constants.

Properties

Property	Description
value	The angle measurement
units	The measurement units

Methods

Method	Description
convert(toUnits)	Returns a number representing the angle in the specified units
toRadians()	Returns a number representing the angle in radians
toDegrees()	Returns a number representing the angle in degrees
normalize()	Ensures that the value is within the equivalent of 0 <= deg < 360 where deg is in degrees

XModel

A model describes a mathematical model of a planet such that distances on the surface of the planet can be calculated. XMaps.model is the model used by various library functions, and by default this is set to the only included model, that of the earth.

Static Properties

Property	Description
earth	A model of the earth using the WGS84 specification

Constructor

Constructor	Description
XModel(flatteningFactor, semimajorAxis)	Creates a new model of a planet. The flattening factor is the oblateness of the earth and is a number. The semi-major axis is a XDistance specifying the largest distance from the center of the earth to the surface.

Methods

Method	Description
getDistanceAndAngle(from, to, distance?, angle?, distanceAndAngle?)	Returns a

XUserAgent

XUserAgent is a class that describes the user's browser. This class exists in the Google Maps API, but is only used internally and is not exposed.

Static Properties

Browser Types

Property	Description
IE	Represents a browser of type Internet Explorer
MOZILLA	Represents a browser of type Mozilla
SAFARI	Represents a browser of type Safari
OPERA	Represents a browser of type Opera

Operating Systems

Property	Description
WIN	Represents a browser running on Windows
NIX	Represents a browser running on a *NIX environment (i think?)
MAC	Represents a browser running on an Apple computer

Constructor

Constructor	Description
XUserAgent()	Creates a new user agent instance

Properties

Property	Description
type	The type of the user's browser. See Browser Types
os	The operating system of the user's browser. See Operating Systems
version	The version number of the browser