openlayers/lib/OpenLayers/Feature.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/Util.js
   8  * @requires OpenLayers/Marker.js
   9  * @requires OpenLayers/Popup/AnchoredBubble.js
  10  */
  11
  12 /**
  13  * Class: OpenLayers.Feature
  14  * Features are combinations of geography and attributes. The OpenLayers.Feature
  15  *     class specifically combines a marker and a lonlat.
  16  */
  17 OpenLayers.Feature = OpenLayers.Class({
  18
  19     /**
  20      * Property: layer
  21      * {<OpenLayers.Layer>}
  22      */
  23     layer: null,
  24
  25     /**
  26      * Property: id
  27      * {String}
  28      */
  29     id: null,
  30
  31     /**
  32      * Property: lonlat
  33      * {<OpenLayers.LonLat>}
  34      */
  35     lonlat: null,
  36
  37     /**
  38      * Property: data
  39      * {Object}
  40      */
  41     data: null,
  42
  43     /**
  44      * Property: marker
  45      * {<OpenLayers.Marker>}
  46      */
  47     marker: null,
  48
  49     /**
  50      * APIProperty: popupClass
  51      * {<OpenLayers.Class>} The class which will be used to instantiate
  52      *     a new Popup. Default is <OpenLayers.Popup.AnchoredBubble>.
  53      */
  54     popupClass: OpenLayers.Popup.AnchoredBubble,
  55
  56     /**
  57      * Property: popup
  58      * {<OpenLayers.Popup>}
  59      */
  60     popup: null,
  61
  62     /**
  63      * Constructor: OpenLayers.Feature
  64      * Constructor for features.
  65      *
  66      * Parameters:
  67      * layer - {<OpenLayers.Layer>}
  68      * lonlat - {<OpenLayers.LonLat>}
  69      * data - {Object}
  70      *
  71      * Returns:
  72      * {<OpenLayers.Feature>}
  73      */
  74     initialize: function(layer, lonlat, data) {
  75         this.layer = layer;
  76         this.lonlat = lonlat;
  77         this.data = (data != null) ? data : {};
  78         this.id = OpenLayers.Util.createUniqueID(this.CLASS_NAME + "_");
  79     },
  80
  81     /**
  82      * Method: destroy
  83      * nullify references to prevent circular references and memory leaks
  84      */
  85     destroy: function() {
  86
  87         //remove the popup from the map
  88         if ((this.layer != null) && (this.layer.map != null)) {
  89             if (this.popup != null) {
  90                 this.layer.map.removePopup(this.popup);
  91             }
  92         }
  93
  94         this.layer = null;
  95         this.id = null;
  96         this.lonlat = null;
  97         this.data = null;
  98         if (this.marker != null) {
  99             this.destroyMarker(this.marker);
 100             this.marker = null;
 101         }
 102         if (this.popup != null) {
 103             this.destroyPopup(this.popup);
 104             this.popup = null;
 105         }
 106     },
 107
 108     /**
 109      * Method: onScreen
 110      *
 111      * Returns:
 112      * {Boolean} Whether or not the feature is currently visible on screen
 113      *           (based on its 'lonlat' property)
 114      */
 115     onScreen:function() {
 116
 117         var onScreen = false;
 118         if ((this.layer != null) && (this.layer.map != null)) {
 119             var screenBounds = this.layer.map.getExtent();
 120             onScreen = screenBounds.containsLonLat(this.lonlat);
 121         }
 122         return onScreen;
 123     },
 124
 125
 126     /**
 127      * Method: createMarker
 128      * Based on the data associated with the Feature, create and return a marker object.
 129      *
 130      * Returns:
 131      * {<OpenLayers.Marker>} A Marker Object created from the 'lonlat' and 'icon' properties
 132      *          set in this.data. If no 'lonlat' is set, returns null. If no
 133      *          'icon' is set, OpenLayers.Marker() will load the default image.
 134      *
 135      *          Note - this.marker is set to return value
 136      *
 137      */
 138     createMarker: function() {
 139
 140         if (this.lonlat != null) {
 141             this.marker = new OpenLayers.Marker(this.lonlat, this.data.icon);
 142         }
 143         return this.marker;
 144     },
 145
 146     /**
 147      * Method: destroyMarker
 148      * Destroys marker.
 149      * If user overrides the createMarker() function, s/he should be able
 150      *   to also specify an alternative function for destroying it
 151      */
 152     destroyMarker: function() {
 153         this.marker.destroy();
 154     },
 155
 156     /**
 157      * Method: createPopup
 158      * Creates a popup object created from the 'lonlat', 'popupSize',
 159      *     and 'popupContentHTML' properties set in this.data. It uses
 160      *     this.marker.icon as default anchor.
 161      *
 162      *  If no 'lonlat' is set, returns null.
 163      *  If no this.marker has been created, no anchor is sent.
 164      *
 165      *  Note - the returned popup object is 'owned' by the feature, so you
 166      *      cannot use the popup's destroy method to discard the popup.
 167      *      Instead, you must use the feature's destroyPopup
 168      *
 169      *  Note - this.popup is set to return value
 170      *
 171      * Parameters:
 172      * closeBox - {Boolean} create popup with closebox or not
 173      *
 174      * Returns:
 175      * {<OpenLayers.Popup>} Returns the created popup, which is also set
 176      *     as 'popup' property of this feature. Will be of whatever type
 177      *     specified by this feature's 'popupClass' property, but must be
 178      *     of type <OpenLayers.Popup>.
 179      *
 180      */
 181     createPopup: function(closeBox) {
 182
 183         if (this.lonlat != null) {
 184
 185             var id = this.id + "_popup";
 186             var anchor = (this.marker) ? this.marker.icon : null;
 187
 188             if (!this.popup) {
 189                 this.popup = new this.popupClass(id,
 190                                                  this.lonlat,
 191                                                  this.data.popupSize,
 192                                                  this.data.popupContentHTML,
 193                                                  anchor,
 194                                                  closeBox);
 195             }
 196             if (this.data.overflow != null) {
 197                 this.popup.contentDiv.style.overflow = this.data.overflow;
 198             }
 199
 200             this.popup.feature = this;
 201         }
 202         return this.popup;
 203     },
 204
 205
 206     /**
 207      * Method: destroyPopup
 208      * Destroys the popup created via createPopup.
 209      *
 210      * As with the marker, if user overrides the createPopup() function, s/he
 211      *   should also be able to override the destruction
 212      */
 213     destroyPopup: function() {
 214         if (this.popup) {
 215             this.popup.feature = null;
 216             this.popup.destroy();
 217             this.popup = null;
 218         }
 219     },
 220
 221     CLASS_NAME: "OpenLayers.Feature"
 222 });