openlayers/lib/OpenLayers/Layer/Image.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  * @requires OpenLayers/Layer.js
   7  * @requires OpenLayers/Tile/Image.js
   8  */
   9
  10 /**
  11  * Class: OpenLayers.Layer.Image
  12  * Instances of OpenLayers.Layer.Image are used to display data from a web
  13  * accessible image as a map layer.  Create a new image layer with the
  14  * <OpenLayers.Layer.Image> constructor.  Inherits from <OpenLayers.Layer>.
  15  */
  16 OpenLayers.Layer.Image = OpenLayers.Class(OpenLayers.Layer, {
  17
  18     /**
  19      * Property: isBaseLayer
  20      * {Boolean} The layer is a base layer.  Default is true.  Set this property
  21      * in the layer options
  22      */
  23     isBaseLayer: true,
  24
  25     /**
  26      * Property: url
  27      * {String} URL of the image to use
  28      */
  29     url: null,
  30
  31     /**
  32      * Property: extent
  33      * {<OpenLayers.Bounds>} The image bounds in map units.  This extent will
  34      *     also be used as the default maxExtent for the layer.  If you wish
  35      *     to have a maxExtent that is different than the image extent, set the
  36      *     maxExtent property of the options argument (as with any other layer).
  37      */
  38     extent: null,
  39
  40     /**
  41      * Property: size
  42      * {<OpenLayers.Size>} The image size in pixels
  43      */
  44     size: null,
  45
  46     /**
  47      * Property: tile
  48      * {<OpenLayers.Tile.Image>}
  49      */
  50     tile: null,
  51
  52     /**
  53      * Property: aspectRatio
  54      * {Float} The ratio of height/width represented by a single pixel in the
  55      * graphic
  56      */
  57     aspectRatio: null,
  58
  59     /**
  60      * Constructor: OpenLayers.Layer.Image
  61      * Create a new image layer
  62      *
  63      * Parameters:
  64      * name - {String} A name for the layer.
  65      * url - {String} Relative or absolute path to the image
  66      * extent - {<OpenLayers.Bounds>} The extent represented by the image
  67      * size - {<OpenLayers.Size>} The size (in pixels) of the image
  68      * options - {Object} Hashtable of extra options to tag onto the layer
  69      */
  70     initialize: function(name, url, extent, size, options) {
  71         this.url = url;
  72         this.extent = extent;
  73         this.maxExtent = extent;
  74         this.size = size;
  75         OpenLayers.Layer.prototype.initialize.apply(this, [name, options]);
  76
  77         this.aspectRatio = (this.extent.getHeight() / this.size.h) /
  78                            (this.extent.getWidth() / this.size.w);
  79     },
  80
  81     /**
  82      * Method: destroy
  83      * Destroy this layer
  84      */
  85     destroy: function() {
  86         if (this.tile) {
  87             this.removeTileMonitoringHooks(this.tile);
  88             this.tile.destroy();
  89             this.tile = null;
  90         }
  91         OpenLayers.Layer.prototype.destroy.apply(this, arguments);
  92     },
  93
  94     /**
  95      * Method: clone
  96      * Create a clone of this layer
  97      *
  98      * Paramters:
  99      * obj - {Object} An optional layer (is this ever used?)
 100      *
 101      * Returns:
 102      * {<OpenLayers.Layer.Image>} An exact copy of this layer
 103      */
 104     clone: function(obj) {
 105
 106         if(obj == null) {
 107             obj = new OpenLayers.Layer.Image(this.name,
 108                                                this.url,
 109                                                this.extent,
 110                                                this.size,
 111                                                this.options);
 112         }
 113
 114         //get all additions from superclasses
 115         obj = OpenLayers.Layer.prototype.clone.apply(this, [obj]);
 116
 117         // copy/set any non-init, non-simple values here
 118
 119         return obj;
 120     },
 121
 122     /**
 123      * APIMethod: setMap
 124      *
 125      * Parameters:
 126      * map - {<OpenLayers.Map>}
 127      */
 128     setMap: function(map) {
 129         /**
 130          * If nothing to do with resolutions has been set, assume a single
 131          * resolution determined by ratio*extent/size - if an image has a
 132          * pixel aspect ratio different than one (as calculated above), the
 133          * image will be stretched in one dimension only.
 134          */
 135         if( this.options.maxResolution == null ) {
 136             this.options.maxResolution = this.aspectRatio *
 137                                          this.extent.getWidth() /
 138                                          this.size.w;
 139         }
 140         OpenLayers.Layer.prototype.setMap.apply(this, arguments);
 141     },
 142
 143     /**
 144      * Method: moveTo
 145      * Create the tile for the image or resize it for the new resolution
 146      *
 147      * Parameters:
 148      * bounds - {<OpenLayers.Bounds>}
 149      * zoomChanged - {Boolean}
 150      * dragging - {Boolean}
 151      */
 152     moveTo:function(bounds, zoomChanged, dragging) {
 153         OpenLayers.Layer.prototype.moveTo.apply(this, arguments);
 154
 155         var firstRendering = (this.tile == null);
 156
 157         if(zoomChanged || firstRendering) {
 158
 159             //determine new tile size
 160             this.setTileSize();
 161
 162             //determine new position (upper left corner of new bounds)
 163             var ul = new OpenLayers.LonLat(this.extent.left, this.extent.top);
 164             var ulPx = this.map.getLayerPxFromLonLat(ul);
 165
 166             if(firstRendering) {
 167                 //create the new tile
 168                 this.tile = new OpenLayers.Tile.Image(this, ulPx, this.extent,
 169                                                       null, this.tileSize);
 170                 this.addTileMonitoringHooks(this.tile);
 171             } else {
 172                 //just resize the tile and set it's new position
 173                 this.tile.size = this.tileSize.clone();
 174                 this.tile.position = ulPx.clone();
 175             }
 176             this.tile.draw();
 177         }
 178     },
 179
 180     /**
 181      * Set the tile size based on the map size.
 182      */
 183     setTileSize: function() {
 184         var tileWidth = this.extent.getWidth() / this.map.getResolution();
 185         var tileHeight = this.extent.getHeight() / this.map.getResolution();
 186         this.tileSize = new OpenLayers.Size(tileWidth, tileHeight);
 187     },
 188
 189     /**
 190      * Method: addTileMonitoringHooks
 191      * This function takes a tile as input and adds the appropriate hooks to
 192      *     the tile so that the layer can keep track of the loading tiles.
 193      *
 194      * Parameters:
 195      * tile - {<OpenLayers.Tile>}
 196      */
 197     addTileMonitoringHooks: function(tile) {
 198         tile.onLoadStart = function() {
 199             this.events.triggerEvent("loadstart");
 200         };
 201         tile.events.register("loadstart", this, tile.onLoadStart);
 202
 203         tile.onLoadEnd = function() {
 204             this.events.triggerEvent("loadend");
 205         };
 206         tile.events.register("loadend", this, tile.onLoadEnd);
 207         tile.events.register("unload", this, tile.onLoadEnd);
 208     },
 209
 210     /**
 211      * Method: removeTileMonitoringHooks
 212      * This function takes a tile as input and removes the tile hooks
 213      *     that were added in <addTileMonitoringHooks>.
 214      *
 215      * Parameters:
 216      * tile - {<OpenLayers.Tile>}
 217      */
 218     removeTileMonitoringHooks: function(tile) {
 219         tile.unload();
 220         tile.events.un({
 221             "loadstart": tile.onLoadStart,
 222             "loadend": tile.onLoadEnd,
 223             "unload": tile.onLoadEnd,
 224             scope: this
 225         });
 226     },
 227
 228     /**
 229      * APIMethod: setUrl
 230      *
 231      * Parameters:
 232      * newUrl - {String}
 233      */
 234     setUrl: function(newUrl) {
 235         this.url = newUrl;
 236         this.tile.draw();
 237     },
 238
 239     /**
 240      * APIMethod: getURL
 241      * The url we return is always the same (the image itself never changes)
 242      *     so we can ignore the bounds parameter (it will always be the same,
 243      *     anyways)
 244      *
 245      * Parameters:
 246      * bounds - {<OpenLayers.Bounds>}
 247      */
 248     getURL: function(bounds) {
 249         return this.url;
 250     },
 251
 252     CLASS_NAME: "OpenLayers.Layer.Image"
 253 });