openlayers/lib/OpenLayers/Renderer.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  * Class: OpenLayers.Renderer
   7  * This is the base class for all renderers.
   8  *
   9  * This is based on a merger code written by Paul Spencer and Bertil Chapuis.
  10  * It is largely composed of virtual functions that are to be implemented
  11  * in technology-specific subclasses, but there is some generic code too.
  12  *
  13  * The functions that *are* implemented here merely deal with the maintenance
  14  *  of the size and extent variables, as well as the cached 'resolution'
  15  *  value.
  16  *
  17  * A note to the user that all subclasses should use getResolution() instead
  18  *  of directly accessing this.resolution in order to correctly use the
  19  *  cacheing system.
  20  *
  21  */
  22 OpenLayers.Renderer = OpenLayers.Class({
  23
  24     /**
  25      * Property: container
  26      * {DOMElement}
  27      */
  28     container: null,
  29
  30     /**
  31      * Property: root
  32      * {DOMElement}
  33      */
  34     root: null,
  35
  36     /**
  37      * Property: extent
  38      * {<OpenLayers.Bounds>}
  39      */
  40     extent: null,
  41
  42     /**
  43      * Property: locked
  44      * {Boolean} If the renderer is currently in a state where many things
  45      *     are changing, the 'locked' property is set to true. This means
  46      *     that renderers can expect at least one more drawFeature event to be
  47      *     called with the 'locked' property set to 'true': In some renderers,
  48      *     this might make sense to use as a 'only update local information'
  49      *     flag.
  50      */
  51     locked: false,
  52
  53     /**
  54      * Property: size
  55      * {<OpenLayers.Size>}
  56      */
  57     size: null,
  58
  59     /**
  60      * Property: resolution
  61      * {Float} cache of current map resolution
  62      */
  63     resolution: null,
  64
  65     /**
  66      * Property: map
  67      * {<OpenLayers.Map>} Reference to the map -- this is set in Vector's setMap()
  68      */
  69     map: null,
  70
  71     /**
  72      * Constructor: OpenLayers.Renderer
  73      *
  74      * Parameters:
  75      * containerID - {<String>}
  76      * options - {Object} options for this renderer. See sublcasses for
  77      *     supported options.
  78      */
  79     initialize: function(containerID, options) {
  80         this.container = OpenLayers.Util.getElement(containerID);
  81     },
  82
  83     /**
  84      * APIMethod: destroy
  85      */
  86     destroy: function() {
  87         this.container = null;
  88         this.extent = null;
  89         this.size =  null;
  90         this.resolution = null;
  91         this.map = null;
  92     },
  93
  94     /**
  95      * APIMethod: supported
  96      * This should be overridden by specific subclasses
  97      *
  98      * Returns:
  99      * {Boolean} Whether or not the browser supports the renderer class
 100      */
 101     supported: function() {
 102         return false;
 103     },
 104
 105     /**
 106      * Method: setExtent
 107      * Set the visible part of the layer.
 108      *
 109      * Resolution has probably changed, so we nullify the resolution
 110      * cache (this.resolution) -- this way it will be re-computed when
 111      * next it is needed.
 112      * We nullify the resolution cache (this.resolution) if resolutionChanged
 113      * is set to true - this way it will be re-computed on the next
 114      * getResolution() request.
 115      *
 116      * Parameters:
 117      * extent - {<OpenLayers.Bounds>}
 118      * resolutionChanged - {Boolean}
 119      */
 120     setExtent: function(extent, resolutionChanged) {
 121         this.extent = extent.clone();
 122         if (resolutionChanged) {
 123             this.resolution = null;
 124         }
 125     },
 126
 127     /**
 128      * Method: setSize
 129      * Sets the size of the drawing surface.
 130      *
 131      * Resolution has probably changed, so we nullify the resolution
 132      * cache (this.resolution) -- this way it will be re-computed when
 133      * next it is needed.
 134      *
 135      * Parameters:
 136      * size - {<OpenLayers.Size>}
 137      */
 138     setSize: function(size) {
 139         this.size = size.clone();
 140         this.resolution = null;
 141     },
 142
 143     /**
 144      * Method: getResolution
 145      * Uses cached copy of resolution if available to minimize computing
 146      *
 147      * Returns:
 148      * The current map's resolution
 149      */
 150     getResolution: function() {
 151         this.resolution = this.resolution || this.map.getResolution();
 152         return this.resolution;
 153     },
 154
 155     /**
 156      * Method: drawFeature
 157      * Draw the feature.  The optional style argument can be used
 158      * to override the feature's own style.  This method should only
 159      * be called from layer.drawFeature().
 160      *
 161      * Parameters:
 162      * feature - {<OpenLayers.Feature.Vector>}
 163      * style - {<Object>}
 164      *
 165      * Returns:
 166      * {Boolean} true if the feature has been drawn completely, false if not,
 167      *     undefined if the feature had no geometry
 168      */
 169     drawFeature: function(feature, style) {
 170         if(style == null) {
 171             style = feature.style;
 172         }
 173         if (feature.geometry) {
 174             var bounds = feature.geometry.getBounds();
 175             if(bounds) {
 176                 if (!bounds.intersectsBounds(this.extent)) {
 177                     style = {display: "none"};
 178                 }
 179                 var rendered = this.drawGeometry(feature.geometry, style, feature.id);
 180                 if(style.display != "none" && style.label && rendered !== false) {
 181                     this.drawText(feature.id, style, feature.geometry.getCentroid());
 182                 } else {
 183                     this.removeText(feature.id);
 184                 }
 185                 return rendered;
 186             }
 187         }
 188     },
 189
 190
 191     /**
 192      * Method: drawGeometry
 193      *
 194      * Draw a geometry.  This should only be called from the renderer itself.
 195      * Use layer.drawFeature() from outside the renderer.
 196      * virtual function
 197      *
 198      * Parameters:
 199      * geometry - {<OpenLayers.Geometry>}
 200      * style - {Object}
 201      * featureId - {<String>}
 202      */
 203     drawGeometry: function(geometry, style, featureId) {},
 204
 205     /**
 206      * Method: drawText
 207      * Function for drawing text labels.
 208      * This method is only called by the renderer itself.
 209      *
 210      * Parameters:
 211      * featureId - {String}
 212      * style -
 213      * location - {<OpenLayers.Geometry.Point>}
 214      */
 215     drawText: function(featureId, style, location) {},
 216
 217     /**
 218      * Method: removeText
 219      * Function for removing text labels.
 220      * This method is only called by the renderer itself.
 221      *
 222      * Parameters:
 223      * featureId - {String}
 224      */
 225     removeText: function(featureId) {},
 226
 227     /**
 228      * Method: clear
 229      * Clear all vectors from the renderer.
 230      * virtual function.
 231      */
 232     clear: function() {},
 233
 234     /**
 235      * Method: getFeatureIdFromEvent
 236      * Returns a feature id from an event on the renderer.
 237      * How this happens is specific to the renderer.  This should be
 238      * called from layer.getFeatureFromEvent().
 239      * Virtual function.
 240      *
 241      * Parameters:
 242      * evt - {<OpenLayers.Event>}
 243      *
 244      * Returns:
 245      * {String} A feature id or null.
 246      */
 247     getFeatureIdFromEvent: function(evt) {},
 248
 249     /**
 250      * Method: eraseFeatures
 251      * This is called by the layer to erase features
 252      *
 253      * Parameters:
 254      * features - {Array(<OpenLayers.Feature.Vector>)}
 255      */
 256     eraseFeatures: function(features) {
 257         if(!(features instanceof Array)) {
 258             features = [features];
 259         }
 260         for(var i=0, len=features.length; i<len; ++i) {
 261             this.eraseGeometry(features[i].geometry);
 262             this.removeText(features[i].id);
 263         }
 264     },
 265
 266     /**
 267      * Method: eraseGeometry
 268      * Remove a geometry from the renderer (by id).
 269      * virtual function.
 270      *
 271      * Parameters:
 272      * geometry - {<OpenLayers.Geometry>}
 273      */
 274     eraseGeometry: function(geometry) {},
 275
 276     /**
 277      * Method: moveRoot
 278      * moves this renderer's root to a (different) renderer.
 279      * To be implemented by subclasses that require a common renderer root for
 280      * feature selection.
 281      *
 282      * Parameters:
 283      * renderer - {<OpenLayers.Renderer>} target renderer for the moved root
 284      */
 285     moveRoot: function(renderer) {},
 286
 287     /**
 288      * Method: getRenderLayerId
 289      * Gets the layer that this renderer's output appears on. If moveRoot was
 290      * used, this will be different from the id of the layer containing the
 291      * features rendered by this renderer.
 292      *
 293      * Returns:
 294      * {String} the id of the output layer.
 295      */
 296     getRenderLayerId: function() {
 297         return this.container.id;
 298     },
 299
 300     CLASS_NAME: "OpenLayers.Renderer"
 301 });