1 /*jslint browser: true, confusion: true, sloppy: true, vars: true, nomen: false, plusplus: false, indent: 2 */
2 /*global window,google */
5 * @name MarkerClustererPlus for Google Maps V3
6 * @version 2.0.16 [October 18, 2012]
9 * The library creates and manages per-zoom-level clusters for large amounts of markers.
11 * This is an enhanced V3 implementation of the
12 * <a href="http://gmaps-utility-library-dev.googlecode.com/svn/tags/markerclusterer/"
13 * >V2 MarkerClusterer</a> by Xiaoxi Wu. It is based on the
14 * <a href="http://google-maps-utility-library-v3.googlecode.com/svn/tags/markerclusterer/"
15 * >V3 MarkerClusterer</a> port by Luke Mahe. MarkerClustererPlus was created by Gary Little.
17 * v2.0 release: MarkerClustererPlus v2.0 is backward compatible with MarkerClusterer v1.0. It
18 * adds support for the <code>ignoreHidden</code>, <code>title</code>, <code>printable</code>,
19 * <code>batchSizeIE</code>, and <code>calculator</code> properties as well as support for
20 * four more events. It also allows greater control over the styling of the text that appears
21 * on the cluster marker. The documentation has been significantly improved and the overall
22 * code has been simplified and polished. Very large numbers of markers can now be managed
23 * without causing Javascript timeout errors on Internet Explorer. Note that the name of the
24 * <code>clusterclick</code> event has been deprecated. The new name is <code>click</code>,
25 * so please change your application code now.
29 * Licensed under the Apache License, Version 2.0 (the "License");
30 * you may not use this file except in compliance with the License.
31 * You may obtain a copy of the License at
33 * http://www.apache.org/licenses/LICENSE-2.0
35 * Unless required by applicable law or agreed to in writing, software
36 * distributed under the License is distributed on an "AS IS" BASIS,
37 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
38 * See the License for the specific language governing permissions and
39 * limitations under the License.
44 * @name ClusterIconStyle
45 * @class This class represents the object for values in the <code>styles</code> array passed
46 * to the {@link MarkerClusterer} constructor. The element in this array that is used to
47 * style the cluster icon is determined by calling the <code>calculator</code> function.
49 * @property {string} url The URL of the cluster icon image file. Required.
50 * @property {number} height The height (in pixels) of the cluster icon. Required.
51 * @property {number} width The width (in pixels) of the cluster icon. Required.
52 * @property {Array} [anchor] The anchor position (in pixels) of the label text to be shown on
53 * the cluster icon, relative to the top left corner of the icon.
54 * The format is <code>[yoffset, xoffset]</code>. The <code>yoffset</code> must be positive
55 * and less than <code>height</code> and the <code>xoffset</code> must be positive and less
56 * than <code>width</code>. The default is to anchor the label text so that it is centered
58 * @property {Array} [anchorIcon] The anchor position (in pixels) of the cluster icon. This is the
59 * spot on the cluster icon that is to be aligned with the cluster position. The format is
60 * <code>[yoffset, xoffset]</code> where <code>yoffset</code> increases as you go down and
61 * <code>xoffset</code> increases to the right. The default anchor position is the center of the
63 * @property {string} [textColor="black"] The color of the label text shown on the
65 * @property {number} [textSize=11] The size (in pixels) of the label text shown on the
67 * @property {number} [textDecoration="none"] The value of the CSS <code>text-decoration</code>
68 * property for the label text shown on the cluster icon.
69 * @property {number} [fontWeight="bold"] The value of the CSS <code>font-weight</code>
70 * property for the label text shown on the cluster icon.
71 * @property {number} [fontStyle="normal"] The value of the CSS <code>font-style</code>
72 * property for the label text shown on the cluster icon.
73 * @property {number} [fontFamily="Arial,sans-serif"] The value of the CSS <code>font-family</code>
74 * property for the label text shown on the cluster icon.
75 * @property {string} [backgroundPosition="0 0"] The position of the cluster icon image
76 * within the image defined by <code>url</code>. The format is <code>"xpos ypos"</code>
77 * (the same format as for the CSS <code>background-position</code> property). You must set
78 * this property appropriately when the image defined by <code>url</code> represents a sprite
79 * containing multiple images.
82 * @name ClusterIconInfo
83 * @class This class is an object containing general information about a cluster icon. This is
84 * the object that a <code>calculator</code> function returns.
86 * @property {string} text The text of the label to be shown on the cluster icon.
87 * @property {number} index The index plus 1 of the element in the <code>styles</code>
88 * array to be used to style the cluster icon.
89 * @property {string} title The tooltip to display when the mouse moves over the cluster icon.
90 * If this value is <code>undefined</code> or <code>""</code>, <code>title</code> is set to the
91 * value of the <code>title</code> property passed to the MarkerClusterer.
97 * @extends google.maps.OverlayView
98 * @param {Cluster} cluster The cluster with which the icon is to be associated.
99 * @param {Array} [styles] An array of {@link ClusterIconStyle} defining the cluster icons
100 * to use for various cluster sizes.
103 function ClusterIcon(cluster, styles) {
104 cluster.getMarkerClusterer().extend(ClusterIcon, google.maps.OverlayView);
106 this.cluster_ = cluster;
107 this.className_ = cluster.getMarkerClusterer().getClusterClass();
108 this.styles_ = styles;
112 this.visible_ = false;
114 this.setMap(cluster.getMap()); // Note: this causes onAdd to be called
119 * Adds the icon to the DOM.
121 ClusterIcon.prototype.onAdd = function () {
122 var cClusterIcon = this;
123 var cMouseDownInCluster;
124 var cDraggingMapByCluster;
126 this.div_ = document.createElement("div");
127 this.div_.className = this.className_;
132 this.getPanes().overlayMouseTarget.appendChild(this.div_);
135 this.boundsChangedListener_ = google.maps.event.addListener(this.getMap(), "bounds_changed", function () {
136 cDraggingMapByCluster = cMouseDownInCluster;
139 google.maps.event.addDomListener(this.div_, "mousedown", function () {
140 cMouseDownInCluster = true;
141 cDraggingMapByCluster = false;
144 google.maps.event.addDomListener(this.div_, "click", function (e) {
145 cMouseDownInCluster = false;
146 if (!cDraggingMapByCluster) {
149 var mc = cClusterIcon.cluster_.getMarkerClusterer();
151 * This event is fired when a cluster marker is clicked.
152 * @name MarkerClusterer#click
153 * @param {Cluster} c The cluster that was clicked.
156 google.maps.event.trigger(mc, "click", cClusterIcon.cluster_);
157 google.maps.event.trigger(mc, "clusterclick", cClusterIcon.cluster_); // deprecated name
159 // The default click handler follows. Disable it by setting
160 // the zoomOnClick property to false.
161 if (mc.getZoomOnClick()) {
162 // Zoom into the cluster.
163 mz = mc.getMaxZoom();
164 theBounds = cClusterIcon.cluster_.getBounds();
165 mc.getMap().fitBounds(theBounds);
166 // There is a fix for Issue 170 here:
167 setTimeout(function () {
168 mc.getMap().fitBounds(theBounds);
169 // Don't zoom beyond the max zoom level
170 if (mz !== null && (mc.getMap().getZoom() > mz)) {
171 mc.getMap().setZoom(mz + 1);
176 // Prevent event propagation to the map:
177 e.cancelBubble = true;
178 if (e.stopPropagation) {
184 google.maps.event.addDomListener(this.div_, "mouseover", function () {
185 var mc = cClusterIcon.cluster_.getMarkerClusterer();
187 * This event is fired when the mouse moves over a cluster marker.
188 * @name MarkerClusterer#mouseover
189 * @param {Cluster} c The cluster that the mouse moved over.
192 google.maps.event.trigger(mc, "mouseover", cClusterIcon.cluster_);
195 google.maps.event.addDomListener(this.div_, "mouseout", function () {
196 var mc = cClusterIcon.cluster_.getMarkerClusterer();
198 * This event is fired when the mouse moves out of a cluster marker.
199 * @name MarkerClusterer#mouseout
200 * @param {Cluster} c The cluster that the mouse moved out of.
203 google.maps.event.trigger(mc, "mouseout", cClusterIcon.cluster_);
209 * Removes the icon from the DOM.
211 ClusterIcon.prototype.onRemove = function () {
212 if (this.div_ && this.div_.parentNode) {
214 google.maps.event.removeListener(this.boundsChangedListener_);
215 google.maps.event.clearInstanceListeners(this.div_);
216 this.div_.parentNode.removeChild(this.div_);
225 ClusterIcon.prototype.draw = function () {
227 var pos = this.getPosFromLatLng_(this.center_);
228 this.div_.style.top = pos.y + "px";
229 this.div_.style.left = pos.x + "px";
237 ClusterIcon.prototype.hide = function () {
239 this.div_.style.display = "none";
241 this.visible_ = false;
246 * Positions and shows the icon.
248 ClusterIcon.prototype.show = function () {
250 var pos = this.getPosFromLatLng_(this.center_);
251 this.div_.style.cssText = this.createCss(pos);
252 if (this.cluster_.printable_) {
253 // (Would like to use "width: inherit;" below, but doesn't work with MSIE)
254 this.div_.innerHTML = "<img src='" + this.url_ + "'><div style='position: absolute; top: 0px; left: 0px; width: " + this.width_ + "px;'>" + this.sums_.text + "</div>";
256 this.div_.innerHTML = this.sums_.text;
258 if (typeof this.sums_.title === "undefined" || this.sums_.title === "") {
259 this.div_.title = this.cluster_.getMarkerClusterer().getTitle();
261 this.div_.title = this.sums_.title;
263 this.div_.style.display = "";
265 this.visible_ = true;
270 * Sets the icon styles to the appropriate element in the styles array.
272 * @param {ClusterIconInfo} sums The icon label text and styles index.
274 ClusterIcon.prototype.useStyle = function (sums) {
276 var index = Math.max(0, sums.index - 1);
277 index = Math.min(this.styles_.length - 1, index);
278 var style = this.styles_[index];
279 this.url_ = style.url;
280 this.height_ = style.height;
281 this.width_ = style.width;
282 this.anchor_ = style.anchor;
283 this.anchorIcon_ = style.anchorIcon || [parseInt(this.height_ / 2, 10), parseInt(this.width_ / 2, 10)];
284 this.textColor_ = style.textColor || "black";
285 this.textSize_ = style.textSize || 11;
286 this.textDecoration_ = style.textDecoration || "none";
287 this.fontWeight_ = style.fontWeight || "bold";
288 this.fontStyle_ = style.fontStyle || "normal";
289 this.fontFamily_ = style.fontFamily || "Arial,sans-serif";
290 this.backgroundPosition_ = style.backgroundPosition || "0 0";
295 * Sets the position at which to center the icon.
297 * @param {google.maps.LatLng} center The latlng to set as the center.
299 ClusterIcon.prototype.setCenter = function (center) {
300 this.center_ = center;
305 * Creates the cssText style parameter based on the position of the icon.
307 * @param {google.maps.Point} pos The position of the icon.
308 * @return {string} The CSS style text.
310 ClusterIcon.prototype.createCss = function (pos) {
312 if (!this.cluster_.printable_) {
313 style.push('background-image:url(' + this.url_ + ');');
314 style.push('background-position:' + this.backgroundPosition_ + ';');
317 if (typeof this.anchor_ === 'object') {
318 if (typeof this.anchor_[0] === 'number' && this.anchor_[0] > 0 &&
319 this.anchor_[0] < this.height_) {
320 style.push('height:' + (this.height_ - this.anchor_[0]) +
321 'px; padding-top:' + this.anchor_[0] + 'px;');
323 style.push('height:' + this.height_ + 'px; line-height:' + this.height_ +
326 if (typeof this.anchor_[1] === 'number' && this.anchor_[1] > 0 &&
327 this.anchor_[1] < this.width_) {
328 style.push('width:' + (this.width_ - this.anchor_[1]) +
329 'px; padding-left:' + this.anchor_[1] + 'px;');
331 style.push('width:' + this.width_ + 'px; text-align:center;');
334 style.push('height:' + this.height_ + 'px; line-height:' +
335 this.height_ + 'px; width:' + this.width_ + 'px; text-align:center;');
338 style.push('cursor:pointer; top:' + pos.y + 'px; left:' +
339 pos.x + 'px; color:' + this.textColor_ + '; position:absolute; font-size:' +
340 this.textSize_ + 'px; font-family:' + this.fontFamily_ + '; font-weight:' +
341 this.fontWeight_ + '; font-style:' + this.fontStyle_ + '; text-decoration:' +
342 this.textDecoration_ + ';');
344 return style.join("");
349 * Returns the position at which to place the DIV depending on the latlng.
351 * @param {google.maps.LatLng} latlng The position in latlng.
352 * @return {google.maps.Point} The position in pixels.
354 ClusterIcon.prototype.getPosFromLatLng_ = function (latlng) {
355 var pos = this.getProjection().fromLatLngToDivPixel(latlng);
356 pos.x -= this.anchorIcon_[1];
357 pos.y -= this.anchorIcon_[0];
363 * Creates a single cluster that manages a group of proximate markers.
364 * Used internally, do not call this constructor directly.
366 * @param {MarkerClusterer} mc The <code>MarkerClusterer</code> object with which this
367 * cluster is associated.
369 function Cluster(mc) {
370 this.markerClusterer_ = mc;
371 this.map_ = mc.getMap();
372 this.gridSize_ = mc.getGridSize();
373 this.minClusterSize_ = mc.getMinimumClusterSize();
374 this.averageCenter_ = mc.getAverageCenter();
375 this.printable_ = mc.getPrintable();
379 this.clusterIcon_ = new ClusterIcon(this, mc.getStyles());
384 * Returns the number of markers managed by the cluster. You can call this from
385 * a <code>click</code>, <code>mouseover</code>, or <code>mouseout</code> event handler
386 * for the <code>MarkerClusterer</code> object.
388 * @return {number} The number of markers in the cluster.
390 Cluster.prototype.getSize = function () {
391 return this.markers_.length;
396 * Returns the array of markers managed by the cluster. You can call this from
397 * a <code>click</code>, <code>mouseover</code>, or <code>mouseout</code> event handler
398 * for the <code>MarkerClusterer</code> object.
400 * @return {Array} The array of markers in the cluster.
402 Cluster.prototype.getMarkers = function () {
403 return this.markers_;
408 * Returns the center of the cluster. You can call this from
409 * a <code>click</code>, <code>mouseover</code>, or <code>mouseout</code> event handler
410 * for the <code>MarkerClusterer</code> object.
412 * @return {google.maps.LatLng} The center of the cluster.
414 Cluster.prototype.getCenter = function () {
420 * Returns the map with which the cluster is associated.
422 * @return {google.maps.Map} The map.
425 Cluster.prototype.getMap = function () {
431 * Returns the <code>MarkerClusterer</code> object with which the cluster is associated.
433 * @return {MarkerClusterer} The associated marker clusterer.
436 Cluster.prototype.getMarkerClusterer = function () {
437 return this.markerClusterer_;
442 * Returns the bounds of the cluster.
444 * @return {google.maps.LatLngBounds} the cluster bounds.
447 Cluster.prototype.getBounds = function () {
449 var bounds = new google.maps.LatLngBounds(this.center_, this.center_);
450 var markers = this.getMarkers();
451 for (i = 0; i < markers.length; i++) {
452 bounds.extend(markers[i].getPosition());
459 * Removes the cluster from the map.
463 Cluster.prototype.remove = function () {
464 this.clusterIcon_.setMap(null);
466 delete this.markers_;
471 * Adds a marker to the cluster.
473 * @param {google.maps.Marker} marker The marker to be added.
474 * @return {boolean} True if the marker was added.
477 Cluster.prototype.addMarker = function (marker) {
482 if (this.isMarkerAlreadyAdded_(marker)) {
487 this.center_ = marker.getPosition();
488 this.calculateBounds_();
490 if (this.averageCenter_) {
491 var l = this.markers_.length + 1;
492 var lat = (this.center_.lat() * (l - 1) + marker.getPosition().lat()) / l;
493 var lng = (this.center_.lng() * (l - 1) + marker.getPosition().lng()) / l;
494 this.center_ = new google.maps.LatLng(lat, lng);
495 this.calculateBounds_();
499 marker.isAdded = true;
500 this.markers_.push(marker);
502 mCount = this.markers_.length;
503 mz = this.markerClusterer_.getMaxZoom();
504 if (mz !== null && this.map_.getZoom() > mz) {
505 // Zoomed in past max zoom, so show the marker.
506 if (marker.getMap() !== this.map_) {
507 marker.setMap(this.map_);
509 } else if (mCount < this.minClusterSize_) {
510 // Min cluster size not reached so show the marker.
511 if (marker.getMap() !== this.map_) {
512 marker.setMap(this.map_);
514 } else if (mCount === this.minClusterSize_) {
515 // Hide the markers that were showing.
516 for (i = 0; i < mCount; i++) {
517 this.markers_[i].setMap(null);
529 * Determines if a marker lies within the cluster's bounds.
531 * @param {google.maps.Marker} marker The marker to check.
532 * @return {boolean} True if the marker lies in the bounds.
535 Cluster.prototype.isMarkerInClusterBounds = function (marker) {
536 return this.bounds_.contains(marker.getPosition());
541 * Calculates the extended bounds of the cluster with the grid.
543 Cluster.prototype.calculateBounds_ = function () {
544 var bounds = new google.maps.LatLngBounds(this.center_, this.center_);
545 this.bounds_ = this.markerClusterer_.getExtendedBounds(bounds);
550 * Updates the cluster icon.
552 Cluster.prototype.updateIcon_ = function () {
553 var mCount = this.markers_.length;
554 var mz = this.markerClusterer_.getMaxZoom();
556 if (mz !== null && this.map_.getZoom() > mz) {
557 this.clusterIcon_.hide();
561 if (mCount < this.minClusterSize_) {
562 // Min cluster size not yet reached.
563 this.clusterIcon_.hide();
567 var numStyles = this.markerClusterer_.getStyles().length;
568 var sums = this.markerClusterer_.getCalculator()(this.markers_, numStyles);
569 this.clusterIcon_.setCenter(this.center_);
570 this.clusterIcon_.useStyle(sums);
571 this.clusterIcon_.show();
576 * Determines if a marker has already been added to the cluster.
578 * @param {google.maps.Marker} marker The marker to check.
579 * @return {boolean} True if the marker has already been added.
581 Cluster.prototype.isMarkerAlreadyAdded_ = function (marker) {
583 if (this.markers_.indexOf) {
584 return this.markers_.indexOf(marker) !== -1;
586 for (i = 0; i < this.markers_.length; i++) {
587 if (marker === this.markers_[i]) {
597 * @name MarkerClustererOptions
598 * @class This class represents the optional parameter passed to
599 * the {@link MarkerClusterer} constructor.
600 * @property {number} [gridSize=60] The grid size of a cluster in pixels. The grid is a square.
601 * @property {number} [maxZoom=null] The maximum zoom level at which clustering is enabled or
602 * <code>null</code> if clustering is to be enabled at all zoom levels.
603 * @property {boolean} [zoomOnClick=true] Whether to zoom the map when a cluster marker is
604 * clicked. You may want to set this to <code>false</code> if you have installed a handler
605 * for the <code>click</code> event and it deals with zooming on its own.
606 * @property {boolean} [averageCenter=false] Whether the position of a cluster marker should be
607 * the average position of all markers in the cluster. If set to <code>false</code>, the
608 * cluster marker is positioned at the location of the first marker added to the cluster.
609 * @property {number} [minimumClusterSize=2] The minimum number of markers needed in a cluster
610 * before the markers are hidden and a cluster marker appears.
611 * @property {boolean} [ignoreHidden=false] Whether to ignore hidden markers in clusters. You
612 * may want to set this to <code>true</code> to ensure that hidden markers are not included
613 * in the marker count that appears on a cluster marker (this count is the value of the
614 * <code>text</code> property of the result returned by the default <code>calculator</code>).
615 * If set to <code>true</code> and you change the visibility of a marker being clustered, be
616 * sure to also call <code>MarkerClusterer.repaint()</code>.
617 * @property {boolean} [printable=false] Whether to make the cluster icons printable. Do not
618 * set to <code>true</code> if the <code>url</code> fields in the <code>styles</code> array
619 * refer to image sprite files.
620 * @property {string} [title=""] The tooltip to display when the mouse moves over a cluster
621 * marker. (Alternatively, you can use a custom <code>calculator</code> function to specify a
622 * different tooltip for each cluster marker.)
623 * @property {function} [calculator=MarkerClusterer.CALCULATOR] The function used to determine
624 * the text to be displayed on a cluster marker and the index indicating which style to use
625 * for the cluster marker. The input parameters for the function are (1) the array of markers
626 * represented by a cluster marker and (2) the number of cluster icon styles. It returns a
627 * {@link ClusterIconInfo} object. The default <code>calculator</code> returns a
628 * <code>text</code> property which is the number of markers in the cluster and an
629 * <code>index</code> property which is one higher than the lowest integer such that
630 * <code>10^i</code> exceeds the number of markers in the cluster, or the size of the styles
631 * array, whichever is less. The <code>styles</code> array element used has an index of
632 * <code>index</code> minus 1. For example, the default <code>calculator</code> returns a
633 * <code>text</code> value of <code>"125"</code> and an <code>index</code> of <code>3</code>
634 * for a cluster icon representing 125 markers so the element used in the <code>styles</code>
635 * array is <code>2</code>. A <code>calculator</code> may also return a <code>title</code>
636 * property that contains the text of the tooltip to be used for the cluster marker. If
637 * <code>title</code> is not defined, the tooltip is set to the value of the <code>title</code>
638 * property for the MarkerClusterer.
639 * @property {string} [clusterClass="cluster"] The name of the CSS class defining general styles
640 * for the cluster markers. Use this class to define CSS styles that are not set up by the code
641 * that processes the <code>styles</code> array.
642 * @property {Array} [styles] An array of {@link ClusterIconStyle} elements defining the styles
643 * of the cluster markers to be used. The element to be used to style a given cluster marker
644 * is determined by the function defined by the <code>calculator</code> property.
645 * The default is an array of {@link ClusterIconStyle} elements whose properties are derived
646 * from the values for <code>imagePath</code>, <code>imageExtension</code>, and
647 * <code>imageSizes</code>.
648 * @property {number} [batchSize=MarkerClusterer.BATCH_SIZE] Set this property to the
649 * number of markers to be processed in a single batch when using a browser other than
650 * Internet Explorer (for Internet Explorer, use the batchSizeIE property instead).
651 * @property {number} [batchSizeIE=MarkerClusterer.BATCH_SIZE_IE] When Internet Explorer is
652 * being used, markers are processed in several batches with a small delay inserted between
653 * each batch in an attempt to avoid Javascript timeout errors. Set this property to the
654 * number of markers to be processed in a single batch; select as high a number as you can
655 * without causing a timeout error in the browser. This number might need to be as low as 100
656 * if 15,000 markers are being managed, for example.
657 * @property {string} [imagePath=MarkerClusterer.IMAGE_PATH]
658 * The full URL of the root name of the group of image files to use for cluster icons.
659 * The complete file name is of the form <code>imagePath</code>n.<code>imageExtension</code>
660 * where n is the image file number (1, 2, etc.).
661 * @property {string} [imageExtension=MarkerClusterer.IMAGE_EXTENSION]
662 * The extension name for the cluster icon image files (e.g., <code>"png"</code> or
663 * <code>"jpg"</code>).
664 * @property {Array} [imageSizes=MarkerClusterer.IMAGE_SIZES]
665 * An array of numbers containing the widths of the group of
666 * <code>imagePath</code>n.<code>imageExtension</code> image files.
667 * (The images are assumed to be square.)
670 * Creates a MarkerClusterer object with the options specified in {@link MarkerClustererOptions}.
672 * @extends google.maps.OverlayView
673 * @param {google.maps.Map} map The Google map to attach to.
674 * @param {Array.<google.maps.Marker>} [opt_markers] The markers to be added to the cluster.
675 * @param {MarkerClustererOptions} [opt_options] The optional parameters.
677 function MarkerClusterer(map, opt_markers, opt_options) {
678 // MarkerClusterer implements google.maps.OverlayView interface. We use the
679 // extend function to extend MarkerClusterer with google.maps.OverlayView
680 // because it might not always be available when the code is defined so we
681 // look for it at the last possible moment. If it doesn't exist now then
682 // there is no point going ahead :)
683 this.extend(MarkerClusterer, google.maps.OverlayView);
685 opt_markers = opt_markers || [];
686 opt_options = opt_options || {};
690 this.listeners_ = [];
691 this.activeMap_ = null;
694 this.gridSize_ = opt_options.gridSize || 60;
695 this.minClusterSize_ = opt_options.minimumClusterSize || 2;
696 this.maxZoom_ = opt_options.maxZoom || null;
697 this.styles_ = opt_options.styles || [];
698 this.title_ = opt_options.title || "";
699 this.zoomOnClick_ = true;
700 if (opt_options.zoomOnClick !== undefined) {
701 this.zoomOnClick_ = opt_options.zoomOnClick;
703 this.averageCenter_ = false;
704 if (opt_options.averageCenter !== undefined) {
705 this.averageCenter_ = opt_options.averageCenter;
707 this.ignoreHidden_ = false;
708 if (opt_options.ignoreHidden !== undefined) {
709 this.ignoreHidden_ = opt_options.ignoreHidden;
711 this.printable_ = false;
712 if (opt_options.printable !== undefined) {
713 this.printable_ = opt_options.printable;
715 this.imagePath_ = opt_options.imagePath || MarkerClusterer.IMAGE_PATH;
716 this.imageExtension_ = opt_options.imageExtension || MarkerClusterer.IMAGE_EXTENSION;
717 this.imageSizes_ = opt_options.imageSizes || MarkerClusterer.IMAGE_SIZES;
718 this.calculator_ = opt_options.calculator || MarkerClusterer.CALCULATOR;
719 this.batchSize_ = opt_options.batchSize || MarkerClusterer.BATCH_SIZE;
720 this.batchSizeIE_ = opt_options.batchSizeIE || MarkerClusterer.BATCH_SIZE_IE;
721 this.clusterClass_ = opt_options.clusterClass || "cluster";
723 if (navigator.userAgent.toLowerCase().indexOf("msie") !== -1) {
724 // Try to avoid IE timeout when processing a huge number of markers:
725 this.batchSize_ = this.batchSizeIE_;
730 this.addMarkers(opt_markers, true);
731 this.setMap(map); // Note: this causes onAdd to be called
736 * Implementation of the onAdd interface method.
739 MarkerClusterer.prototype.onAdd = function () {
740 var cMarkerClusterer = this;
742 this.activeMap_ = this.getMap();
747 // Add the map event listeners
749 google.maps.event.addListener(this.getMap(), "zoom_changed", function () {
750 cMarkerClusterer.resetViewport_(false);
751 // Workaround for this Google bug: when map is at level 0 and "-" of
752 // zoom slider is clicked, a "zoom_changed" event is fired even though
753 // the map doesn't zoom out any further. In this situation, no "idle"
754 // event is triggered so the cluster markers that have been removed
755 // do not get redrawn. Same goes for a zoom in at maxZoom.
756 if (this.getZoom() === (this.get("minZoom") || 0) || this.getZoom() === this.get("maxZoom")) {
757 google.maps.event.trigger(this, "idle");
760 google.maps.event.addListener(this.getMap(), "idle", function () {
761 cMarkerClusterer.redraw_();
768 * Implementation of the onRemove interface method.
769 * Removes map event listeners and all cluster icons from the DOM.
770 * All managed markers are also put back on the map.
773 MarkerClusterer.prototype.onRemove = function () {
776 // Put all the managed markers back on the map:
777 for (i = 0; i < this.markers_.length; i++) {
778 if (this.markers_[i].getMap() !== this.activeMap_) {
779 this.markers_[i].setMap(this.activeMap_);
783 // Remove all clusters:
784 for (i = 0; i < this.clusters_.length; i++) {
785 this.clusters_[i].remove();
789 // Remove map event listeners:
790 for (i = 0; i < this.listeners_.length; i++) {
791 google.maps.event.removeListener(this.listeners_[i]);
793 this.listeners_ = [];
795 this.activeMap_ = null;
801 * Implementation of the draw interface method.
804 MarkerClusterer.prototype.draw = function () {};
808 * Sets up the styles object.
810 MarkerClusterer.prototype.setupStyles_ = function () {
812 if (this.styles_.length > 0) {
816 for (i = 0; i < this.imageSizes_.length; i++) {
817 size = this.imageSizes_[i];
819 url: this.imagePath_ + (i + 1) + "." + this.imageExtension_,
828 * Fits the map to the bounds of the markers managed by the clusterer.
830 MarkerClusterer.prototype.fitMapToMarkers = function () {
832 var markers = this.getMarkers();
833 var bounds = new google.maps.LatLngBounds();
834 for (i = 0; i < markers.length; i++) {
835 bounds.extend(markers[i].getPosition());
838 this.getMap().fitBounds(bounds);
843 * Returns the value of the <code>gridSize</code> property.
845 * @return {number} The grid size.
847 MarkerClusterer.prototype.getGridSize = function () {
848 return this.gridSize_;
853 * Sets the value of the <code>gridSize</code> property.
855 * @param {number} gridSize The grid size.
857 MarkerClusterer.prototype.setGridSize = function (gridSize) {
858 this.gridSize_ = gridSize;
863 * Returns the value of the <code>minimumClusterSize</code> property.
865 * @return {number} The minimum cluster size.
867 MarkerClusterer.prototype.getMinimumClusterSize = function () {
868 return this.minClusterSize_;
872 * Sets the value of the <code>minimumClusterSize</code> property.
874 * @param {number} minimumClusterSize The minimum cluster size.
876 MarkerClusterer.prototype.setMinimumClusterSize = function (minimumClusterSize) {
877 this.minClusterSize_ = minimumClusterSize;
882 * Returns the value of the <code>maxZoom</code> property.
884 * @return {number} The maximum zoom level.
886 MarkerClusterer.prototype.getMaxZoom = function () {
887 return this.maxZoom_;
892 * Sets the value of the <code>maxZoom</code> property.
894 * @param {number} maxZoom The maximum zoom level.
896 MarkerClusterer.prototype.setMaxZoom = function (maxZoom) {
897 this.maxZoom_ = maxZoom;
902 * Returns the value of the <code>styles</code> property.
904 * @return {Array} The array of styles defining the cluster markers to be used.
906 MarkerClusterer.prototype.getStyles = function () {
912 * Sets the value of the <code>styles</code> property.
914 * @param {Array.<ClusterIconStyle>} styles The array of styles to use.
916 MarkerClusterer.prototype.setStyles = function (styles) {
917 this.styles_ = styles;
922 * Returns the value of the <code>title</code> property.
924 * @return {string} The content of the title text.
926 MarkerClusterer.prototype.getTitle = function () {
932 * Sets the value of the <code>title</code> property.
934 * @param {string} title The value of the title property.
936 MarkerClusterer.prototype.setTitle = function (title) {
942 * Returns the value of the <code>zoomOnClick</code> property.
944 * @return {boolean} True if zoomOnClick property is set.
946 MarkerClusterer.prototype.getZoomOnClick = function () {
947 return this.zoomOnClick_;
952 * Sets the value of the <code>zoomOnClick</code> property.
954 * @param {boolean} zoomOnClick The value of the zoomOnClick property.
956 MarkerClusterer.prototype.setZoomOnClick = function (zoomOnClick) {
957 this.zoomOnClick_ = zoomOnClick;
962 * Returns the value of the <code>averageCenter</code> property.
964 * @return {boolean} True if averageCenter property is set.
966 MarkerClusterer.prototype.getAverageCenter = function () {
967 return this.averageCenter_;
972 * Sets the value of the <code>averageCenter</code> property.
974 * @param {boolean} averageCenter The value of the averageCenter property.
976 MarkerClusterer.prototype.setAverageCenter = function (averageCenter) {
977 this.averageCenter_ = averageCenter;
982 * Returns the value of the <code>ignoreHidden</code> property.
984 * @return {boolean} True if ignoreHidden property is set.
986 MarkerClusterer.prototype.getIgnoreHidden = function () {
987 return this.ignoreHidden_;
992 * Sets the value of the <code>ignoreHidden</code> property.
994 * @param {boolean} ignoreHidden The value of the ignoreHidden property.
996 MarkerClusterer.prototype.setIgnoreHidden = function (ignoreHidden) {
997 this.ignoreHidden_ = ignoreHidden;
1002 * Returns the value of the <code>imageExtension</code> property.
1004 * @return {string} The value of the imageExtension property.
1006 MarkerClusterer.prototype.getImageExtension = function () {
1007 return this.imageExtension_;
1012 * Sets the value of the <code>imageExtension</code> property.
1014 * @param {string} imageExtension The value of the imageExtension property.
1016 MarkerClusterer.prototype.setImageExtension = function (imageExtension) {
1017 this.imageExtension_ = imageExtension;
1022 * Returns the value of the <code>imagePath</code> property.
1024 * @return {string} The value of the imagePath property.
1026 MarkerClusterer.prototype.getImagePath = function () {
1027 return this.imagePath_;
1032 * Sets the value of the <code>imagePath</code> property.
1034 * @param {string} imagePath The value of the imagePath property.
1036 MarkerClusterer.prototype.setImagePath = function (imagePath) {
1037 this.imagePath_ = imagePath;
1042 * Returns the value of the <code>imageSizes</code> property.
1044 * @return {Array} The value of the imageSizes property.
1046 MarkerClusterer.prototype.getImageSizes = function () {
1047 return this.imageSizes_;
1052 * Sets the value of the <code>imageSizes</code> property.
1054 * @param {Array} imageSizes The value of the imageSizes property.
1056 MarkerClusterer.prototype.setImageSizes = function (imageSizes) {
1057 this.imageSizes_ = imageSizes;
1062 * Returns the value of the <code>calculator</code> property.
1064 * @return {function} the value of the calculator property.
1066 MarkerClusterer.prototype.getCalculator = function () {
1067 return this.calculator_;
1072 * Sets the value of the <code>calculator</code> property.
1074 * @param {function(Array.<google.maps.Marker>, number)} calculator The value
1075 * of the calculator property.
1077 MarkerClusterer.prototype.setCalculator = function (calculator) {
1078 this.calculator_ = calculator;
1083 * Returns the value of the <code>printable</code> property.
1085 * @return {boolean} the value of the printable property.
1087 MarkerClusterer.prototype.getPrintable = function () {
1088 return this.printable_;
1093 * Sets the value of the <code>printable</code> property.
1095 * @param {boolean} printable The value of the printable property.
1097 MarkerClusterer.prototype.setPrintable = function (printable) {
1098 this.printable_ = printable;
1103 * Returns the value of the <code>batchSizeIE</code> property.
1105 * @return {number} the value of the batchSizeIE property.
1107 MarkerClusterer.prototype.getBatchSizeIE = function () {
1108 return this.batchSizeIE_;
1113 * Sets the value of the <code>batchSizeIE</code> property.
1115 * @param {number} batchSizeIE The value of the batchSizeIE property.
1117 MarkerClusterer.prototype.setBatchSizeIE = function (batchSizeIE) {
1118 this.batchSizeIE_ = batchSizeIE;
1123 * Returns the value of the <code>clusterClass</code> property.
1125 * @return {string} the value of the clusterClass property.
1127 MarkerClusterer.prototype.getClusterClass = function () {
1128 return this.clusterClass_;
1133 * Sets the value of the <code>clusterClass</code> property.
1135 * @param {string} clusterClass The value of the clusterClass property.
1137 MarkerClusterer.prototype.setClusterClass = function (clusterClass) {
1138 this.clusterClass_ = clusterClass;
1143 * Returns the array of markers managed by the clusterer.
1145 * @return {Array} The array of markers managed by the clusterer.
1147 MarkerClusterer.prototype.getMarkers = function () {
1148 return this.markers_;
1153 * Returns the number of markers managed by the clusterer.
1155 * @return {number} The number of markers.
1157 MarkerClusterer.prototype.getTotalMarkers = function () {
1158 return this.markers_.length;
1163 * Returns the current array of clusters formed by the clusterer.
1165 * @return {Array} The array of clusters formed by the clusterer.
1167 MarkerClusterer.prototype.getClusters = function () {
1168 return this.clusters_;
1173 * Returns the number of clusters formed by the clusterer.
1175 * @return {number} The number of clusters formed by the clusterer.
1177 MarkerClusterer.prototype.getTotalClusters = function () {
1178 return this.clusters_.length;
1183 * Adds a marker to the clusterer. The clusters are redrawn unless
1184 * <code>opt_nodraw</code> is set to <code>true</code>.
1186 * @param {google.maps.Marker} marker The marker to add.
1187 * @param {boolean} [opt_nodraw] Set to <code>true</code> to prevent redrawing.
1189 MarkerClusterer.prototype.addMarker = function (marker, opt_nodraw) {
1190 this.pushMarkerTo_(marker);
1198 * Adds an array of markers to the clusterer. The clusters are redrawn unless
1199 * <code>opt_nodraw</code> is set to <code>true</code>.
1201 * @param {Array.<google.maps.Marker>} markers The markers to add.
1202 * @param {boolean} [opt_nodraw] Set to <code>true</code> to prevent redrawing.
1204 MarkerClusterer.prototype.addMarkers = function (markers, opt_nodraw) {
1206 for (i = 0; i < markers.length; i++) {
1207 this.pushMarkerTo_(markers[i]);
1216 * Pushes a marker to the clusterer.
1218 * @param {google.maps.Marker} marker The marker to add.
1220 MarkerClusterer.prototype.pushMarkerTo_ = function (marker) {
1221 // If the marker is draggable add a listener so we can update the clusters on the dragend:
1222 if (marker.getDraggable()) {
1223 var cMarkerClusterer = this;
1224 google.maps.event.addListener(marker, "dragend", function () {
1225 if (cMarkerClusterer.ready_) {
1226 this.isAdded = false;
1227 cMarkerClusterer.repaint();
1231 marker.isAdded = false;
1232 this.markers_.push(marker);
1237 * Removes a marker from the cluster. The clusters are redrawn unless
1238 * <code>opt_nodraw</code> is set to <code>true</code>. Returns <code>true</code> if the
1239 * marker was removed from the clusterer.
1241 * @param {google.maps.Marker} marker The marker to remove.
1242 * @param {boolean} [opt_nodraw] Set to <code>true</code> to prevent redrawing.
1243 * @return {boolean} True if the marker was removed from the clusterer.
1245 MarkerClusterer.prototype.removeMarker = function (marker, opt_nodraw) {
1246 var removed = this.removeMarker_(marker);
1248 if (!opt_nodraw && removed) {
1257 * Removes an array of markers from the cluster. The clusters are redrawn unless
1258 * <code>opt_nodraw</code> is set to <code>true</code>. Returns <code>true</code> if markers
1259 * were removed from the clusterer.
1261 * @param {Array.<google.maps.Marker>} markers The markers to remove.
1262 * @param {boolean} [opt_nodraw] Set to <code>true</code> to prevent redrawing.
1263 * @return {boolean} True if markers were removed from the clusterer.
1265 MarkerClusterer.prototype.removeMarkers = function (markers, opt_nodraw) {
1267 var removed = false;
1269 for (i = 0; i < markers.length; i++) {
1270 r = this.removeMarker_(markers[i]);
1271 removed = removed || r;
1274 if (!opt_nodraw && removed) {
1283 * Removes a marker and returns true if removed, false if not.
1285 * @param {google.maps.Marker} marker The marker to remove
1286 * @return {boolean} Whether the marker was removed or not
1288 MarkerClusterer.prototype.removeMarker_ = function (marker) {
1291 if (this.markers_.indexOf) {
1292 index = this.markers_.indexOf(marker);
1294 for (i = 0; i < this.markers_.length; i++) {
1295 if (marker === this.markers_[i]) {
1303 // Marker is not in our list of markers, so do nothing:
1307 marker.setMap(null);
1308 this.markers_.splice(index, 1); // Remove the marker from the list of managed markers
1314 * Removes all clusters and markers from the map and also removes all markers
1315 * managed by the clusterer.
1317 MarkerClusterer.prototype.clearMarkers = function () {
1318 this.resetViewport_(true);
1324 * Recalculates and redraws all the marker clusters from scratch.
1325 * Call this after changing any properties.
1327 MarkerClusterer.prototype.repaint = function () {
1328 var oldClusters = this.clusters_.slice();
1329 this.clusters_ = [];
1330 this.resetViewport_(false);
1333 // Remove the old clusters.
1334 // Do it in a timeout to prevent blinking effect.
1335 setTimeout(function () {
1337 for (i = 0; i < oldClusters.length; i++) {
1338 oldClusters[i].remove();
1345 * Returns the current bounds extended by the grid size.
1347 * @param {google.maps.LatLngBounds} bounds The bounds to extend.
1348 * @return {google.maps.LatLngBounds} The extended bounds.
1351 MarkerClusterer.prototype.getExtendedBounds = function (bounds) {
1352 var projection = this.getProjection();
1354 // Turn the bounds into latlng.
1355 var tr = new google.maps.LatLng(bounds.getNorthEast().lat(),
1356 bounds.getNorthEast().lng());
1357 var bl = new google.maps.LatLng(bounds.getSouthWest().lat(),
1358 bounds.getSouthWest().lng());
1360 // Convert the points to pixels and the extend out by the grid size.
1361 var trPix = projection.fromLatLngToDivPixel(tr);
1362 trPix.x += this.gridSize_;
1363 trPix.y -= this.gridSize_;
1365 var blPix = projection.fromLatLngToDivPixel(bl);
1366 blPix.x -= this.gridSize_;
1367 blPix.y += this.gridSize_;
1369 // Convert the pixel points back to LatLng
1370 var ne = projection.fromDivPixelToLatLng(trPix);
1371 var sw = projection.fromDivPixelToLatLng(blPix);
1373 // Extend the bounds to contain the new bounds.
1382 * Redraws all the clusters.
1384 MarkerClusterer.prototype.redraw_ = function () {
1385 this.createClusters_(0);
1390 * Removes all clusters from the map. The markers are also removed from the map
1391 * if <code>opt_hide</code> is set to <code>true</code>.
1393 * @param {boolean} [opt_hide] Set to <code>true</code> to also remove the markers
1396 MarkerClusterer.prototype.resetViewport_ = function (opt_hide) {
1398 // Remove all the clusters
1399 for (i = 0; i < this.clusters_.length; i++) {
1400 this.clusters_[i].remove();
1402 this.clusters_ = [];
1404 // Reset the markers to not be added and to be removed from the map.
1405 for (i = 0; i < this.markers_.length; i++) {
1406 marker = this.markers_[i];
1407 marker.isAdded = false;
1409 marker.setMap(null);
1416 * Calculates the distance between two latlng locations in km.
1418 * @param {google.maps.LatLng} p1 The first lat lng point.
1419 * @param {google.maps.LatLng} p2 The second lat lng point.
1420 * @return {number} The distance between the two points in km.
1421 * @see http://www.movable-type.co.uk/scripts/latlong.html
1423 MarkerClusterer.prototype.distanceBetweenPoints_ = function (p1, p2) {
1424 var R = 6371; // Radius of the Earth in km
1425 var dLat = (p2.lat() - p1.lat()) * Math.PI / 180;
1426 var dLon = (p2.lng() - p1.lng()) * Math.PI / 180;
1427 var a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
1428 Math.cos(p1.lat() * Math.PI / 180) * Math.cos(p2.lat() * Math.PI / 180) *
1429 Math.sin(dLon / 2) * Math.sin(dLon / 2);
1430 var c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
1437 * Determines if a marker is contained in a bounds.
1439 * @param {google.maps.Marker} marker The marker to check.
1440 * @param {google.maps.LatLngBounds} bounds The bounds to check against.
1441 * @return {boolean} True if the marker is in the bounds.
1443 MarkerClusterer.prototype.isMarkerInBounds_ = function (marker, bounds) {
1444 return bounds.contains(marker.getPosition());
1449 * Adds a marker to a cluster, or creates a new cluster.
1451 * @param {google.maps.Marker} marker The marker to add.
1453 MarkerClusterer.prototype.addToClosestCluster_ = function (marker) {
1454 var i, d, cluster, center;
1455 var distance = 40000; // Some large number
1456 var clusterToAddTo = null;
1457 for (i = 0; i < this.clusters_.length; i++) {
1458 cluster = this.clusters_[i];
1459 center = cluster.getCenter();
1461 d = this.distanceBetweenPoints_(center, marker.getPosition());
1464 clusterToAddTo = cluster;
1469 if (clusterToAddTo && clusterToAddTo.isMarkerInClusterBounds(marker)) {
1470 clusterToAddTo.addMarker(marker);
1472 cluster = new Cluster(this);
1473 cluster.addMarker(marker);
1474 this.clusters_.push(cluster);
1480 * Creates the clusters. This is done in batches to avoid timeout errors
1481 * in some browsers when there is a huge number of markers.
1483 * @param {number} iFirst The index of the first marker in the batch of
1484 * markers to be added to clusters.
1486 MarkerClusterer.prototype.createClusters_ = function (iFirst) {
1489 var cMarkerClusterer = this;
1494 // Cancel previous batch processing if we're working on the first batch:
1497 * This event is fired when the <code>MarkerClusterer</code> begins
1498 * clustering markers.
1499 * @name MarkerClusterer#clusteringbegin
1500 * @param {MarkerClusterer} mc The MarkerClusterer whose markers are being clustered.
1503 google.maps.event.trigger(this, "clusteringbegin", this);
1505 if (typeof this.timerRefStatic !== "undefined") {
1506 clearTimeout(this.timerRefStatic);
1507 delete this.timerRefStatic;
1511 // Get our current map view bounds.
1512 // Create a new bounds object so we don't affect the map.
1514 // See Comments 9 & 11 on Issue 3651 relating to this workaround for a Google Maps bug:
1515 if (this.getMap().getZoom() > 3) {
1516 mapBounds = new google.maps.LatLngBounds(this.getMap().getBounds().getSouthWest(),
1517 this.getMap().getBounds().getNorthEast());
1519 mapBounds = new google.maps.LatLngBounds(new google.maps.LatLng(85.02070771743472, -178.48388434375), new google.maps.LatLng(-85.08136444384544, 178.00048865625));
1521 var bounds = this.getExtendedBounds(mapBounds);
1523 var iLast = Math.min(iFirst + this.batchSize_, this.markers_.length);
1525 for (i = iFirst; i < iLast; i++) {
1526 marker = this.markers_[i];
1527 if (!marker.isAdded && this.isMarkerInBounds_(marker, bounds)) {
1528 if (!this.ignoreHidden_ || (this.ignoreHidden_ && marker.getVisible())) {
1529 this.addToClosestCluster_(marker);
1534 if (iLast < this.markers_.length) {
1535 this.timerRefStatic = setTimeout(function () {
1536 cMarkerClusterer.createClusters_(iLast);
1539 delete this.timerRefStatic;
1542 * This event is fired when the <code>MarkerClusterer</code> stops
1543 * clustering markers.
1544 * @name MarkerClusterer#clusteringend
1545 * @param {MarkerClusterer} mc The MarkerClusterer whose markers are being clustered.
1548 google.maps.event.trigger(this, "clusteringend", this);
1554 * Extends an object's prototype by another's.
1556 * @param {Object} obj1 The object to be extended.
1557 * @param {Object} obj2 The object to extend with.
1558 * @return {Object} The new extended object.
1561 MarkerClusterer.prototype.extend = function (obj1, obj2) {
1562 return (function (object) {
1564 for (property in object.prototype) {
1565 this.prototype[property] = object.prototype[property];
1568 }).apply(obj1, [obj2]);
1573 * The default function for determining the label text and style
1574 * for a cluster icon.
1576 * @param {Array.<google.maps.Marker>} markers The array of markers represented by the cluster.
1577 * @param {number} numStyles The number of marker styles available.
1578 * @return {ClusterIconInfo} The information resource for the cluster.
1582 MarkerClusterer.CALCULATOR = function (markers, numStyles) {
1585 var count = markers.length.toString();
1589 dv = parseInt(dv / 10, 10);
1593 index = Math.min(index, numStyles);
1603 * The number of markers to process in one batch.
1608 MarkerClusterer.BATCH_SIZE = 2000;
1612 * The number of markers to process in one batch (IE only).
1617 MarkerClusterer.BATCH_SIZE_IE = 500;
1621 * The default root name for the marker cluster images.
1626 MarkerClusterer.IMAGE_PATH = "http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclustererplus/images/m";
1630 * The default extension name for the marker cluster images.
1635 MarkerClusterer.IMAGE_EXTENSION = "png";
1639 * The default array of sizes for the marker cluster images.
1641 * @type {Array.<number>}
1644 MarkerClusterer.IMAGE_SIZES = [53, 56, 66, 78, 90];