openlayers/lib/OpenLayers/Icon.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  * Class: OpenLayers.Icon
   8  *
   9  * The icon represents a graphical icon on the screen.  Typically used in
  10  * conjunction with a <OpenLayers.Marker> to represent markers on a screen.
  11  *
  12  * An icon has a url, size and position.  It also contains an offset which
  13  * allows the center point to be represented correctly.  This can be
  14  * provided either as a fixed offset or a function provided to calculate
  15  * the desired offset.
  16  *
  17  */
  18 OpenLayers.Icon = OpenLayers.Class({
  19
  20     /**
  21      * Property: url
  22      * {String}  image url
  23      */
  24     url: null,
  25
  26     /**
  27      * Property: size
  28      * {<OpenLayers.Size>}
  29      */
  30     size: null,
  31
  32     /**
  33      * Property: offset
  34      * {<OpenLayers.Pixel>} distance in pixels to offset the image when being rendered
  35      */
  36     offset: null,
  37
  38     /**
  39      * Property: calculateOffset
  40      * {<OpenLayers.Pixel>} Function to calculate the offset (based on the size)
  41      */
  42     calculateOffset: null,
  43
  44     /**
  45      * Property: imageDiv
  46      * {DOMElement}
  47      */
  48     imageDiv: null,
  49
  50     /**
  51      * Property: px
  52      * {<OpenLayers.Pixel>}
  53      */
  54     px: null,
  55
  56     /**
  57      * Constructor: OpenLayers.Icon
  58      * Creates an icon, which is an image tag in a div.
  59      *
  60      * url - {String}
  61      * size - {<OpenLayers.Size>}
  62      * offset - {<OpenLayers.Pixel>}
  63      * calculateOffset - {Function}
  64      */
  65     initialize: function(url, size, offset, calculateOffset) {
  66         this.url = url;
  67         this.size = (size) ? size : new OpenLayers.Size(20,20);
  68         this.offset = offset ? offset : new OpenLayers.Pixel(-(this.size.w/2), -(this.size.h/2));
  69         this.calculateOffset = calculateOffset;
  70
  71         var id = OpenLayers.Util.createUniqueID("OL_Icon_");
  72         this.imageDiv = OpenLayers.Util.createAlphaImageDiv(id);
  73     },
  74
  75     /**
  76      * Method: destroy
  77      * Nullify references and remove event listeners to prevent circular
  78      * references and memory leaks
  79      */
  80     destroy: function() {
  81         // erase any drawn elements
  82         this.erase();
  83
  84         OpenLayers.Event.stopObservingElement(this.imageDiv.firstChild);
  85         this.imageDiv.innerHTML = "";
  86         this.imageDiv = null;
  87     },
  88
  89     /**
  90      * Method: clone
  91      *
  92      * Returns:
  93      * {<OpenLayers.Icon>} A fresh copy of the icon.
  94      */
  95     clone: function() {
  96         return new OpenLayers.Icon(this.url,
  97                                    this.size,
  98                                    this.offset,
  99                                    this.calculateOffset);
 100     },
 101
 102     /**
 103      * Method: setSize
 104      *
 105      * Parameters:
 106      * size - {<OpenLayers.Size>}
 107      */
 108     setSize: function(size) {
 109         if (size != null) {
 110             this.size = size;
 111         }
 112         this.draw();
 113     },
 114
 115     /**
 116      * Method: setUrl
 117      *
 118      * Parameters:
 119      * url - {String}
 120      */
 121     setUrl: function(url) {
 122         if (url != null) {
 123             this.url = url;
 124         }
 125         this.draw();
 126     },
 127
 128     /**
 129      * Method: draw
 130      * Move the div to the given pixel.
 131      *
 132      * Parameters:
 133      * px - {<OpenLayers.Pixel>}
 134      *
 135      * Returns:
 136      * {DOMElement} A new DOM Image of this icon set at the location passed-in
 137      */
 138     draw: function(px) {
 139         OpenLayers.Util.modifyAlphaImageDiv(this.imageDiv,
 140                                             null,
 141                                             null,
 142                                             this.size,
 143                                             this.url,
 144                                             "absolute");
 145         this.moveTo(px);
 146         return this.imageDiv;
 147     },
 148
 149     /**
 150      * Method: erase
 151      * Erase the underlying image element.
 152      *
 153      */
 154     erase: function() {
 155         if (this.imageDiv != null && this.imageDiv.parentNode != null) {
 156             OpenLayers.Element.remove(this.imageDiv);
 157         }
 158     },
 159
 160     /**
 161      * Method: setOpacity
 162      * Change the icon's opacity
 163      *
 164      * Parameters:
 165      * opacity - {float}
 166      */
 167     setOpacity: function(opacity) {
 168         OpenLayers.Util.modifyAlphaImageDiv(this.imageDiv, null, null, null,
 169                                             null, null, null, null, opacity);
 170
 171     },
 172
 173     /**
 174      * Method: moveTo
 175      * move icon to passed in px.
 176      *
 177      * Parameters:
 178      * px - {<OpenLayers.Pixel>}
 179      */
 180     moveTo: function (px) {
 181         //if no px passed in, use stored location
 182         if (px != null) {
 183             this.px = px;
 184         }
 185
 186         if (this.imageDiv != null) {
 187             if (this.px == null) {
 188                 this.display(false);
 189             } else {
 190                 if (this.calculateOffset) {
 191                     this.offset = this.calculateOffset(this.size);
 192                 }
 193                 var offsetPx = this.px.offset(this.offset);
 194                 OpenLayers.Util.modifyAlphaImageDiv(this.imageDiv, null, offsetPx);
 195             }
 196         }
 197     },
 198
 199     /**
 200      * Method: display
 201      * Hide or show the icon
 202      *
 203      * Parameters:
 204      * display - {Boolean}
 205      */
 206     display: function(display) {
 207         this.imageDiv.style.display = (display) ? "" : "none";
 208     },
 209
 210
 211     /**
 212      * APIMethod: isDrawn
 213      *
 214      * Returns:
 215      * {Boolean} Whether or not the icon is drawn.
 216      */
 217     isDrawn: function() {
 218         // nodeType 11 for ie, whose nodes *always* have a parentNode
 219         // (of type document fragment)
 220         var isDrawn = (this.imageDiv && this.imageDiv.parentNode &&
 221                        (this.imageDiv.parentNode.nodeType != 11));
 222
 223         return isDrawn;
 224     },
 225
 226     CLASS_NAME: "OpenLayers.Icon"
 227 });