openlayers/lib/OpenLayers/Icon.js

/* Copyright (c) 2006 MetaCarta, Inc., published under a modified BSD license.
 * See http://svn.openlayers.org/trunk/openlayers/repository-license.txt 
 * for the full text of the license. */


/**
 * Class: OpenLayers.Icon
 */
OpenLayers.Icon = OpenLayers.Class.create();
OpenLayers.Icon.prototype = {
    
    /** 
	 * Property: url 
	 * {String}  image url
	 */
	url: null,
    
    /** 
	 * Property: size 
	 * {<OpenLayers.Size>} 
	 */
	size: null,

    /** 
	 * Property: offset 
	 * {<OpenLayers.Pixel>} distance in pixels to offset the image when being rendered
	 */
	offset: null,    
    
    /** 
	 * Property: calculateOffset 
	 * {<OpenLayers.Pixel>} Function to calculate the offset (based on the size) 
	 */
	calculateOffset: null,    
    
    /** 
	 * Property: imageDiv 
	 * {DOMElement} 
	 */
	imageDiv: null,

    /** 
	 * Property: px 
	 * {<OpenLayers.Pixel>} 
	 */
	px: null,
    
    /** 
    * Constructor: OpenLayers.Icon
    * Creates an icon, which is an image tag in a div.  
    *
    * url - {String} 
    * size - {<OpenLayers.Size>} 
    * calculateOffset - {Function} 
    */
    initialize: function(url, size, offset, calculateOffset) {
        this.url = url;
        this.size = (size) ? size : new OpenLayers.Size(20,20);
        this.offset = offset ? offset : new OpenLayers.Pixel(-(this.size.w/2), -(this.size.h/2));
        this.calculateOffset = calculateOffset;

        var id = OpenLayers.Util.createUniqueID("OL_Icon_");
        this.imageDiv = OpenLayers.Util.createAlphaImageDiv(id);
    },
    
    /** 
     * Method: destroy
     * nullify references to prevent circular references and memory leaks
     */
    destroy: function() {
        OpenLayers.Event.stopObservingElement(this.imageDiv.firstChild); 
        this.imageDiv.innerHTML = "";
        this.imageDiv = null;
    },

    /** 
    * Method: clone
    * 
    * Returns:
    * {<OpenLayers.Icon>} A fresh copy of the icon.
    */
    clone: function() {
        return new OpenLayers.Icon(this.url, 
                                   this.size, 
                                   this.offset, 
                                   this.calculateOffset);
    },
    
    /**
     * Method: setSize
     * 
     * size - {<OpenLayers.Size>} 
     */
    setSize: function(size) {
        if (size != null) {
            this.size = size;
        }
        this.draw();
    },

    /** 
    * Method: draw
    * Move the div to the given pixel.
    * 
    * Parameters:
    * px - {<OpenLayers.Pixel>} 
    * 
    * Returns:
    * {DOMElement} A new DOM Image of this icon set at the location passed-in
    */
    draw: function(px) {
        OpenLayers.Util.modifyAlphaImageDiv(this.imageDiv, 
                                            null, 
                                            null, 
                                            this.size, 
                                            this.url, 
                                            "absolute");
        this.moveTo(px);
        return this.imageDiv;
    }, 

    
    /** 
     * Method: setOpacity
     * Change the icon's opacity
     *
     * Parameters:
     * opacity - {float} 
     */
    setOpacity: function(opacity) {
        OpenLayers.Util.modifyAlphaImageDiv(this.imageDiv, null, null, null, 
                                            null, null, null, null, opacity);

    },
    
    /**
    * Method: moveTo
    * move icon to passed in px.
    *
    * Parameters:
    * px - {<OpenLayers.Pixel>} 
    */
    moveTo: function (px) {
        //if no px passed in, use stored location
        if (px != null) {
            this.px = px;
        }

        if (this.imageDiv != null) {
            if (this.px == null) {
                this.display(false);
            } else {
                if (this.calculateOffset) {
                    this.offset = this.calculateOffset(this.size);  
                }
                var offsetPx = this.px.offset(this.offset);
                OpenLayers.Util.modifyAlphaImageDiv(this.imageDiv, null, offsetPx);
            }
        }
    },
    
    /** 
     * Method: display
     * Hide or show the icon
     *
     * Parameters:
     * display - {Boolean} 
     */
    display: function(display) {
        this.imageDiv.style.display = (display) ? "" : "none"; 
    },
    
    /** @final @type String */
    CLASS_NAME: "OpenLayers.Icon"
};