openlayers/lib/OpenLayers/Marker.js

   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. */
   4
   5
   6 /**
   7  * @requires OpenLayers/Events.js
   8  * @requires OpenLayers/Icon.js
   9  */
  10
  11 /**
  12  * Class: OpenLayers.Marker
  13  * Instances of OpenLayers.Marker are a combination of a
  14  * <OpenLayers.LonLat> and an <OpenLayers.Icon>.
  15  *
  16  * Markers are generally added to a special layer called
  17  * <OpenLayers.Layer.Markers>.
  18  *
  19  * Example:
  20  * (code)
  21  * var markers = new OpenLayers.Layer.Markers( "Markers" );
  22  * map.addLayer(markers);
  23  *
  24  * var size = new OpenLayers.Size(10,17);
  25  * var offset = new OpenLayers.Pixel(-(size.w/2), -size.h);
  26  * var icon = new OpenLayers.Icon('http://boston.openguides.org/markers/AQUA.png',size,offset);
  27  * markers.addMarker(new OpenLayers.Marker(new OpenLayers.LonLat(0,0),icon));
  28  * markers.addMarker(new OpenLayers.Marker(new OpenLayers.LonLat(0,0),icon.clone()));
  29  *
  30  * (end)
  31  *
  32  * Note that if you pass an icon into the Marker constructor, it will take
  33  * that icon and use it. This means that you should not share icons between
  34  * markers -- you use them once, but you should clone() for any additional
  35  * markers using that same icon.
  36  */
  37 OpenLayers.Marker = OpenLayers.Class({
  38
  39     /**
  40      * Property: icon
  41      * {<OpenLayers.Icon>} The icon used by this marker.
  42      */
  43     icon: null,
  44
  45     /**
  46      * Property: lonlat
  47      * {<OpenLayers.LonLat>} location of object
  48      */
  49     lonlat: null,
  50
  51     /**
  52      * Property: events
  53      * {<OpenLayers.Events>} the event handler.
  54      */
  55     events: null,
  56
  57     /**
  58      * Property: map
  59      * {<OpenLayers.Map>} the map this marker is attached to
  60      */
  61     map: null,
  62
  63     /**
  64      * Constructor: OpenLayers.Marker
  65      * Parameters:
  66      * lonlat - {<OpenLayers.LonLat>} the position of this marker
  67      * icon - {<OpenLayers.Icon>}  the icon for this marker
  68      */
  69     initialize: function(lonlat, icon) {
  70         this.lonlat = lonlat;
  71
  72         var newIcon = (icon) ? icon : OpenLayers.Marker.defaultIcon();
  73         if (this.icon == null) {
  74             this.icon = newIcon;
  75         } else {
  76             this.icon.url = newIcon.url;
  77             this.icon.size = newIcon.size;
  78             this.icon.offset = newIcon.offset;
  79             this.icon.calculateOffset = newIcon.calculateOffset;
  80         }
  81         this.events = new OpenLayers.Events(this, this.icon.imageDiv, null);
  82     },
  83
  84     /**
  85      * APIMethod: destroy
  86      * Destroy the marker. You must first remove the marker from any
  87      * layer which it has been added to, or you will get buggy behavior.
  88      * (This can not be done within the marker since the marker does not
  89      * know which layer it is attached to.)
  90      */
  91     destroy: function() {
  92         // erase any drawn features
  93         this.erase();
  94
  95         this.map = null;
  96
  97         this.events.destroy();
  98         this.events = null;
  99
 100         if (this.icon != null) {
 101             this.icon.destroy();
 102             this.icon = null;
 103         }
 104     },
 105
 106     /**
 107     * Method: draw
 108     * Calls draw on the icon, and returns that output.
 109     *
 110     * Parameters:
 111     * px - {<OpenLayers.Pixel>}
 112     *
 113     * Returns:
 114     * {DOMElement} A new DOM Image with this marker's icon set at the
 115     * location passed-in
 116     */
 117     draw: function(px) {
 118         return this.icon.draw(px);
 119     },
 120
 121     /**
 122     * Method: erase
 123     * Erases any drawn elements for this marker.
 124     */
 125     erase: function() {
 126         if (this.icon != null) {
 127             this.icon.erase();
 128         }
 129     },
 130
 131     /**
 132     * Method: moveTo
 133     * Move the marker to the new location.
 134     *
 135     * Parameters:
 136     * px - {<OpenLayers.Pixel>} the pixel position to move to
 137     */
 138     moveTo: function (px) {
 139         if ((px != null) && (this.icon != null)) {
 140             this.icon.moveTo(px);
 141         }
 142         this.lonlat = this.map.getLonLatFromLayerPx(px);
 143     },
 144
 145     /**
 146      * APIMethod: isDrawn
 147      *
 148      * Returns:
 149      * {Boolean} Whether or not the marker is drawn.
 150      */
 151     isDrawn: function() {
 152         var isDrawn = (this.icon && this.icon.isDrawn());
 153         return isDrawn;
 154     },
 155
 156     /**
 157      * Method: onScreen
 158      *
 159      * Returns:
 160      * {Boolean} Whether or not the marker is currently visible on screen.
 161      */
 162     onScreen:function() {
 163
 164         var onScreen = false;
 165         if (this.map) {
 166             var screenBounds = this.map.getExtent();
 167             onScreen = screenBounds.containsLonLat(this.lonlat);
 168         }
 169         return onScreen;
 170     },
 171
 172     /**
 173      * Method: inflate
 174      * Englarges the markers icon by the specified ratio.
 175      *
 176      * Parameters:
 177      * inflate - {float} the ratio to enlarge the marker by (passing 2
 178      *                   will double the size).
 179      */
 180     inflate: function(inflate) {
 181         if (this.icon) {
 182             var newSize = new OpenLayers.Size(this.icon.size.w * inflate,
 183                                               this.icon.size.h * inflate);
 184             this.icon.setSize(newSize);
 185         }
 186     },
 187
 188     /**
 189      * Method: setOpacity
 190      * Change the opacity of the marker by changin the opacity of
 191      *   its icon
 192      *
 193      * Parameters:
 194      * opacity - {float}  Specified as fraction (0.4, etc)
 195      */
 196     setOpacity: function(opacity) {
 197         this.icon.setOpacity(opacity);
 198     },
 199
 200     /**
 201      * Method: setUrl
 202      * Change URL of the Icon Image.
 203      *
 204      * url - {String}
 205      */
 206     setUrl: function(url) {
 207         this.icon.setUrl(url);
 208     },
 209
 210     /**
 211      * Method: display
 212      * Hide or show the icon
 213      *
 214      * display - {Boolean}
 215      */
 216     display: function(display) {
 217         this.icon.display(display);
 218     },
 219
 220     CLASS_NAME: "OpenLayers.Marker"
 221 });
 222
 223
 224 /**
 225  * Function: defaultIcon
 226  * Creates a default <OpenLayers.Icon>.
 227  *
 228  * Returns:
 229  * {<OpenLayers.Icon>} A default OpenLayers.Icon to use for a marker
 230  */
 231 OpenLayers.Marker.defaultIcon = function() {
 232     var url = OpenLayers.Util.getImagesLocation() + "marker.png";
 233     var size = new OpenLayers.Size(21, 25);
 234     var calculateOffset = function(size) {
 235                     return new OpenLayers.Pixel(-(size.w/2), -size.h);
 236                  };
 237
 238     return new OpenLayers.Icon(url, size, null, calculateOffset);
 239 };
 240
 241