1 /* Copyright (c) 2006-2008 MetaCarta, Inc., published under the Clear BSD
2 * license. See http://svn.openlayers.org/trunk/openlayers/license.txt for the
3 * full text of the license. */
6 * @requires OpenLayers/Control.js
7 * @requires OpenLayers/BaseTypes.js
8 * @requires OpenLayers/Events.js
12 * Class: OpenLayers.Control.OverviewMap
13 * The OverMap control creates a small overview map, useful to display the
14 * extent of a zoomed map and your main map and provide additional
15 * navigation options to the User. By default the overview map is drawn in
16 * the lower right corner of the main map. Create a new overview map with the
17 * <OpenLayers.Control.OverviewMap> constructor.
20 * - <OpenLayers.Control>
22 OpenLayers.Control.OverviewMap = OpenLayers.Class(OpenLayers.Control, {
26 * {DOMElement} The DOM element that contains the overview map
32 * {<OpenLayers.Map>} A reference to the overview map itself.
38 * {<OpenLayers.Size>} The overvew map size in pixels. Note that this is
39 * the size of the map itself - the element that contains the map (default
40 * class name olControlOverviewMapElement) may have padding or other style
41 * attributes added via CSS.
43 size: new OpenLayers.Size(180, 90),
47 * {Array(<OpenLayers.Layer>)} Ordered list of layers in the overview map.
48 * If none are sent at construction, the base layer for the main map is used.
53 * APIProperty: minRectSize
54 * {Integer} The minimum width or height (in pixels) of the extent
55 * rectangle on the overview map. When the extent rectangle reaches
56 * this size, it will be replaced depending on the value of the
57 * <minRectDisplayClass> property. Default is 15 pixels.
62 * APIProperty: minRectDisplayClass
63 * {String} Replacement style class name for the extent rectangle when
64 * <minRectSize> is reached. This string will be suffixed on to the
65 * displayClass. Default is "RectReplacement".
67 * Example CSS declaration:
69 * .olControlOverviewMapRectReplacement {
72 * background-image: url("img/overview_replacement.gif");
73 * background-repeat: no-repeat;
74 * background-position: center;
78 minRectDisplayClass: "RectReplacement",
81 * APIProperty: minRatio
82 * {Float} The ratio of the overview map resolution to the main map
83 * resolution at which to zoom farther out on the overview map.
88 * APIProperty: maxRatio
89 * {Float} The ratio of the overview map resolution to the main map
90 * resolution at which to zoom farther in on the overview map.
95 * APIProperty: mapOptions
96 * {Object} An object containing any non-default properties to be sent to
97 * the overview map's map constructor. These should include any
98 * non-default options that the main map was constructed with.
103 * APIProperty: autoPan
104 * {Boolean} Always pan the overview map, so the extent marker remains in
105 * the center. Default is false. If true, when you drag the extent
106 * marker, the overview map will update itself so the marker returns
118 * Property: resolutionFactor
124 * Constructor: OpenLayers.Control.OverviewMap
125 * Create a new overview map
128 * object - {Object} Properties of this object will be set on the overview
129 * map object. Note, to set options on the map object contained in this
130 * control, set <mapOptions> as one of the options properties.
132 initialize: function(options) {
135 OpenLayers.Control.prototype.initialize.apply(this, [options]);
140 * Deconstruct the control
142 destroy: function() {
143 if (!this.mapDiv) { // we've already been destroyed
146 this.handlers.click.destroy();
148 this.mapDiv.removeChild(this.extentRectangle);
149 this.extentRectangle = null;
150 this.rectEvents.destroy();
151 this.rectEvents = null;
153 this.ovmap.destroy();
156 this.element.removeChild(this.mapDiv);
159 this.div.removeChild(this.element);
162 if (this.maximizeDiv) {
163 OpenLayers.Event.stopObservingElement(this.maximizeDiv);
164 this.div.removeChild(this.maximizeDiv);
165 this.maximizeDiv = null;
168 if (this.minimizeDiv) {
169 OpenLayers.Event.stopObservingElement(this.minimizeDiv);
170 this.div.removeChild(this.minimizeDiv);
171 this.minimizeDiv = null;
175 "moveend": this.update,
176 "changebaselayer": this.baseLayerDraw,
180 OpenLayers.Control.prototype.destroy.apply(this, arguments);
185 * Render the control in the browser.
188 OpenLayers.Control.prototype.draw.apply(this, arguments);
189 if(!(this.layers.length > 0)) {
190 if (this.map.baseLayer) {
191 var layer = this.map.baseLayer.clone();
192 this.layers = [layer];
194 this.map.events.register("changebaselayer", this, this.baseLayerDraw);
199 // create overview map DOM elements
200 this.element = document.createElement('div');
201 this.element.className = this.displayClass + 'Element';
202 this.element.style.display = 'none';
204 this.mapDiv = document.createElement('div');
205 this.mapDiv.style.width = this.size.w + 'px';
206 this.mapDiv.style.height = this.size.h + 'px';
207 this.mapDiv.style.position = 'relative';
208 this.mapDiv.style.overflow = 'hidden';
209 this.mapDiv.id = OpenLayers.Util.createUniqueID('overviewMap');
211 this.extentRectangle = document.createElement('div');
212 this.extentRectangle.style.position = 'absolute';
213 this.extentRectangle.style.zIndex = 1000; //HACK
214 this.extentRectangle.className = this.displayClass+'ExtentRectangle';
215 this.mapDiv.appendChild(this.extentRectangle);
217 this.element.appendChild(this.mapDiv);
219 this.div.appendChild(this.element);
221 // Optionally add min/max buttons if the control will go in the
223 if(!this.outsideViewport) {
224 this.div.className += " " + this.displayClass + 'Container';
225 var imgLocation = OpenLayers.Util.getImagesLocation();
226 // maximize button div
227 var img = imgLocation + 'layer-switcher-maximize.png';
228 this.maximizeDiv = OpenLayers.Util.createAlphaImageDiv(
229 this.displayClass + 'MaximizeButton',
231 new OpenLayers.Size(18,18),
234 this.maximizeDiv.style.display = 'none';
235 this.maximizeDiv.className = this.displayClass + 'MaximizeButton';
236 OpenLayers.Event.observe(this.maximizeDiv, 'click',
237 OpenLayers.Function.bindAsEventListener(this.maximizeControl,
240 this.div.appendChild(this.maximizeDiv);
242 // minimize button div
243 var img = imgLocation + 'layer-switcher-minimize.png';
244 this.minimizeDiv = OpenLayers.Util.createAlphaImageDiv(
245 'OpenLayers_Control_minimizeDiv',
247 new OpenLayers.Size(18,18),
250 this.minimizeDiv.style.display = 'none';
251 this.minimizeDiv.className = this.displayClass + 'MinimizeButton';
252 OpenLayers.Event.observe(this.minimizeDiv, 'click',
253 OpenLayers.Function.bindAsEventListener(this.minimizeControl,
256 this.div.appendChild(this.minimizeDiv);
258 var eventsToStop = ['dblclick','mousedown'];
260 for (var i=0, len=eventsToStop.length; i<len; i++) {
262 OpenLayers.Event.observe(this.maximizeDiv,
264 OpenLayers.Event.stop);
266 OpenLayers.Event.observe(this.minimizeDiv,
268 OpenLayers.Event.stop);
271 this.minimizeControl();
273 // show the overview map
274 this.element.style.display = '';
276 if(this.map.getExtent()) {
280 this.map.events.register('moveend', this, this.update);
286 * Method: baseLayerDraw
287 * Draw the base layer - called if unable to complete in the initial draw
289 baseLayerDraw: function() {
291 this.map.events.unregister("changebaselayer", this, this.baseLayerDraw);
296 * Handle extent rectangle drag
299 * px - {<OpenLayers.Pixel>} The pixel location of the drag.
301 rectDrag: function(px) {
302 var deltaX = this.handlers.drag.last.x - px.x;
303 var deltaY = this.handlers.drag.last.y - px.y;
304 if(deltaX != 0 || deltaY != 0) {
305 var rectTop = this.rectPxBounds.top;
306 var rectLeft = this.rectPxBounds.left;
307 var rectHeight = Math.abs(this.rectPxBounds.getHeight());
308 var rectWidth = this.rectPxBounds.getWidth();
309 // don't allow dragging off of parent element
310 var newTop = Math.max(0, (rectTop - deltaY));
311 newTop = Math.min(newTop,
312 this.ovmap.size.h - this.hComp - rectHeight);
313 var newLeft = Math.max(0, (rectLeft - deltaX));
314 newLeft = Math.min(newLeft,
315 this.ovmap.size.w - this.wComp - rectWidth);
316 this.setRectPxBounds(new OpenLayers.Bounds(newLeft,
324 * Method: mapDivClick
325 * Handle browser events
328 * evt - {<OpenLayers.Event>} evt
330 mapDivClick: function(evt) {
331 var pxCenter = this.rectPxBounds.getCenterPixel();
332 var deltaX = evt.xy.x - pxCenter.x;
333 var deltaY = evt.xy.y - pxCenter.y;
334 var top = this.rectPxBounds.top;
335 var left = this.rectPxBounds.left;
336 var height = Math.abs(this.rectPxBounds.getHeight());
337 var width = this.rectPxBounds.getWidth();
338 var newTop = Math.max(0, (top + deltaY));
339 newTop = Math.min(newTop, this.ovmap.size.h - height);
340 var newLeft = Math.max(0, (left + deltaX));
341 newLeft = Math.min(newLeft, this.ovmap.size.w - width);
342 this.setRectPxBounds(new OpenLayers.Bounds(newLeft,
346 this.updateMapToRect();
350 * Method: maximizeControl
351 * Unhide the control. Called when the control is in the map viewport.
354 * e - {<OpenLayers.Event>}
356 maximizeControl: function(e) {
357 this.element.style.display = '';
358 this.showToggle(false);
360 OpenLayers.Event.stop(e);
365 * Method: minimizeControl
366 * Hide all the contents of the control, shrink the size,
367 * add the maximize icon
370 * e - {<OpenLayers.Event>}
372 minimizeControl: function(e) {
373 this.element.style.display = 'none';
374 this.showToggle(true);
376 OpenLayers.Event.stop(e);
382 * Hide/Show the toggle depending on whether the control is minimized
385 * minimize - {Boolean}
387 showToggle: function(minimize) {
388 this.maximizeDiv.style.display = minimize ? '' : 'none';
389 this.minimizeDiv.style.display = minimize ? 'none' : '';
394 * Update the overview map after layers move.
397 if(this.ovmap == null) {
401 if(this.autoPan || !this.isSuitableOverview()) {
402 this.updateOverview();
405 // update extent rectangle
406 this.updateRectToMap();
410 * Method: isSuitableOverview
411 * Determines if the overview map is suitable given the extent and
412 * resolution of the main map.
414 isSuitableOverview: function() {
415 var mapExtent = this.map.getExtent();
416 var maxExtent = this.map.maxExtent;
417 var testExtent = new OpenLayers.Bounds(
418 Math.max(mapExtent.left, maxExtent.left),
419 Math.max(mapExtent.bottom, maxExtent.bottom),
420 Math.min(mapExtent.right, maxExtent.right),
421 Math.min(mapExtent.top, maxExtent.top));
423 if (this.ovmap.getProjection() != this.map.getProjection()) {
424 testExtent = testExtent.transform(
425 this.map.getProjectionObject(),
426 this.ovmap.getProjectionObject() );
429 var resRatio = this.ovmap.getResolution() / this.map.getResolution();
430 return ((resRatio > this.minRatio) &&
431 (resRatio <= this.maxRatio) &&
432 (this.ovmap.getExtent().containsBounds(testExtent)));
436 * Method updateOverview
437 * Called by <update> if <isSuitableOverview> returns true
439 updateOverview: function() {
440 var mapRes = this.map.getResolution();
441 var targetRes = this.ovmap.getResolution();
442 var resRatio = targetRes / mapRes;
443 if(resRatio > this.maxRatio) {
444 // zoom in overview map
445 targetRes = this.minRatio * mapRes;
446 } else if(resRatio <= this.minRatio) {
447 // zoom out overview map
448 targetRes = this.maxRatio * mapRes;
451 if (this.ovmap.getProjection() != this.map.getProjection()) {
452 center = this.map.center.clone();
453 center.transform(this.map.getProjectionObject(),
454 this.ovmap.getProjectionObject() );
456 center = this.map.center;
458 this.ovmap.setCenter(center, this.ovmap.getZoomForResolution(
459 targetRes * this.resolutionFactor));
460 this.updateRectToMap();
465 * Construct the map that this control contains
467 createMap: function() {
468 // create the overview map
469 var options = OpenLayers.Util.extend(
470 {controls: [], maxResolution: 'auto',
471 fallThrough: false}, this.mapOptions);
472 this.ovmap = new OpenLayers.Map(this.mapDiv, options);
474 // prevent ovmap from being destroyed when the page unloads, because
475 // the OverviewMap control has to do this (and does it).
476 OpenLayers.Event.stopObserving(window, 'unload', this.ovmap.unloadDestroy);
478 this.ovmap.addLayers(this.layers);
479 this.ovmap.zoomToMaxExtent();
480 // check extent rectangle border width
481 this.wComp = parseInt(OpenLayers.Element.getStyle(this.extentRectangle,
482 'border-left-width')) +
483 parseInt(OpenLayers.Element.getStyle(this.extentRectangle,
484 'border-right-width'));
485 this.wComp = (this.wComp) ? this.wComp : 2;
486 this.hComp = parseInt(OpenLayers.Element.getStyle(this.extentRectangle,
487 'border-top-width')) +
488 parseInt(OpenLayers.Element.getStyle(this.extentRectangle,
489 'border-bottom-width'));
490 this.hComp = (this.hComp) ? this.hComp : 2;
492 this.handlers.drag = new OpenLayers.Handler.Drag(
493 this, {move: this.rectDrag, done: this.updateMapToRect},
496 this.handlers.click = new OpenLayers.Handler.Click(
498 "click": this.mapDivClick
500 "single": true, "double": false,
501 "stopSingle": true, "stopDouble": true,
506 this.handlers.click.activate();
508 this.rectEvents = new OpenLayers.Events(this, this.extentRectangle,
510 this.rectEvents.register("mouseover", this, function(e) {
511 if(!this.handlers.drag.active && !this.map.dragging) {
512 this.handlers.drag.activate();
515 this.rectEvents.register("mouseout", this, function(e) {
516 if(!this.handlers.drag.dragging) {
517 this.handlers.drag.deactivate();
521 if (this.ovmap.getProjection() != this.map.getProjection()) {
522 var sourceUnits = this.map.getProjectionObject().getUnits() ||
523 this.map.units || this.map.baseLayer.units;
524 var targetUnits = this.ovmap.getProjectionObject().getUnits() ||
525 this.ovmap.units || this.ovmap.baseLayer.units;
526 this.resolutionFactor = sourceUnits && targetUnits ?
527 OpenLayers.INCHES_PER_UNIT[sourceUnits] /
528 OpenLayers.INCHES_PER_UNIT[targetUnits] : 1;
533 * Method: updateRectToMap
534 * Updates the extent rectangle position and size to match the map extent
536 updateRectToMap: function() {
537 // If the projections differ we need to reproject
539 if (this.ovmap.getProjection() != this.map.getProjection()) {
540 bounds = this.map.getExtent().transform(
541 this.map.getProjectionObject(),
542 this.ovmap.getProjectionObject() );
544 bounds = this.map.getExtent();
546 var pxBounds = this.getRectBoundsFromMapBounds(bounds);
548 this.setRectPxBounds(pxBounds);
553 * Method: updateMapToRect
554 * Updates the map extent to match the extent rectangle position and size
556 updateMapToRect: function() {
557 var lonLatBounds = this.getMapBoundsFromRectBounds(this.rectPxBounds);
558 if (this.ovmap.getProjection() != this.map.getProjection()) {
559 lonLatBounds = lonLatBounds.transform(
560 this.ovmap.getProjectionObject(),
561 this.map.getProjectionObject() );
563 this.map.panTo(lonLatBounds.getCenterLonLat());
567 * Method: setRectPxBounds
568 * Set extent rectangle pixel bounds.
571 * pxBounds - {<OpenLayers.Bounds>}
573 setRectPxBounds: function(pxBounds) {
574 var top = Math.max(pxBounds.top, 0);
575 var left = Math.max(pxBounds.left, 0);
576 var bottom = Math.min(pxBounds.top + Math.abs(pxBounds.getHeight()),
577 this.ovmap.size.h - this.hComp);
578 var right = Math.min(pxBounds.left + pxBounds.getWidth(),
579 this.ovmap.size.w - this.wComp);
580 var width = Math.max(right - left, 0);
581 var height = Math.max(bottom - top, 0);
582 if(width < this.minRectSize || height < this.minRectSize) {
583 this.extentRectangle.className = this.displayClass +
584 this.minRectDisplayClass;
585 var rLeft = left + (width / 2) - (this.minRectSize / 2);
586 var rTop = top + (height / 2) - (this.minRectSize / 2);
587 this.extentRectangle.style.top = Math.round(rTop) + 'px';
588 this.extentRectangle.style.left = Math.round(rLeft) + 'px';
589 this.extentRectangle.style.height = this.minRectSize + 'px';
590 this.extentRectangle.style.width = this.minRectSize + 'px';
592 this.extentRectangle.className = this.displayClass +
594 this.extentRectangle.style.top = Math.round(top) + 'px';
595 this.extentRectangle.style.left = Math.round(left) + 'px';
596 this.extentRectangle.style.height = Math.round(height) + 'px';
597 this.extentRectangle.style.width = Math.round(width) + 'px';
599 this.rectPxBounds = new OpenLayers.Bounds(
600 Math.round(left), Math.round(bottom),
601 Math.round(right), Math.round(top)
606 * Method: getRectBoundsFromMapBounds
607 * Get the rect bounds from the map bounds.
610 * lonLatBounds - {<OpenLayers.Bounds>}
613 * {<OpenLayers.Bounds>}A bounds which is the passed-in map lon/lat extent
614 * translated into pixel bounds for the overview map
616 getRectBoundsFromMapBounds: function(lonLatBounds) {
617 var leftBottomLonLat = new OpenLayers.LonLat(lonLatBounds.left,
618 lonLatBounds.bottom);
619 var rightTopLonLat = new OpenLayers.LonLat(lonLatBounds.right,
621 var leftBottomPx = this.getOverviewPxFromLonLat(leftBottomLonLat);
622 var rightTopPx = this.getOverviewPxFromLonLat(rightTopLonLat);
624 if (leftBottomPx && rightTopPx) {
625 bounds = new OpenLayers.Bounds(leftBottomPx.x, leftBottomPx.y,
626 rightTopPx.x, rightTopPx.y);
632 * Method: getMapBoundsFromRectBounds
633 * Get the map bounds from the rect bounds.
636 * pxBounds - {<OpenLayers.Bounds>}
639 * {<OpenLayers.Bounds>} Bounds which is the passed-in overview rect bounds
640 * translated into lon/lat bounds for the overview map
642 getMapBoundsFromRectBounds: function(pxBounds) {
643 var leftBottomPx = new OpenLayers.Pixel(pxBounds.left,
645 var rightTopPx = new OpenLayers.Pixel(pxBounds.right,
647 var leftBottomLonLat = this.getLonLatFromOverviewPx(leftBottomPx);
648 var rightTopLonLat = this.getLonLatFromOverviewPx(rightTopPx);
649 return new OpenLayers.Bounds(leftBottomLonLat.lon, leftBottomLonLat.lat,
650 rightTopLonLat.lon, rightTopLonLat.lat);
654 * Method: getLonLatFromOverviewPx
655 * Get a map location from a pixel location
658 * overviewMapPx - {<OpenLayers.Pixel>}
661 * {<OpenLayers.LonLat>} Location which is the passed-in overview map
662 * OpenLayers.Pixel, translated into lon/lat by the overview map
664 getLonLatFromOverviewPx: function(overviewMapPx) {
665 var size = this.ovmap.size;
666 var res = this.ovmap.getResolution();
667 var center = this.ovmap.getExtent().getCenterLonLat();
669 var delta_x = overviewMapPx.x - (size.w / 2);
670 var delta_y = overviewMapPx.y - (size.h / 2);
672 return new OpenLayers.LonLat(center.lon + delta_x * res ,
673 center.lat - delta_y * res);
677 * Method: getOverviewPxFromLonLat
678 * Get a pixel location from a map location
681 * lonlat - {<OpenLayers.LonLat>}
684 * {<OpenLayers.Pixel>} Location which is the passed-in OpenLayers.LonLat,
685 * translated into overview map pixels
687 getOverviewPxFromLonLat: function(lonlat) {
688 var res = this.ovmap.getResolution();
689 var extent = this.ovmap.getExtent();
692 px = new OpenLayers.Pixel(
693 Math.round(1/res * (lonlat.lon - extent.left)),
694 Math.round(1/res * (extent.top - lonlat.lat)));
699 CLASS_NAME: 'OpenLayers.Control.OverviewMap'