openlayers/lib/OpenLayers/BaseTypes/LonLat.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/Console.js
   7  */
   8
   9 /**
  10  * Class: OpenLayers.LonLat
  11  * This class represents a longitude and latitude pair
  12  */
  13 OpenLayers.LonLat = OpenLayers.Class({
  14
  15     /**
  16      * APIProperty: lon
  17      * {Float} The x-axis coodinate in map units
  18      */
  19     lon: 0.0,
  20
  21     /**
  22      * APIProperty: lat
  23      * {Float} The y-axis coordinate in map units
  24      */
  25     lat: 0.0,
  26
  27     /**
  28      * Constructor: OpenLayers.LonLat
  29      * Create a new map location.
  30      *
  31      * Parameters:
  32      * lon - {Number} The x-axis coordinate in map units.  If your map is in
  33      *     a geographic projection, this will be the Longitude.  Otherwise,
  34      *     it will be the x coordinate of the map location in your map units.
  35      * lat - {Number} The y-axis coordinate in map units.  If your map is in
  36      *     a geographic projection, this will be the Latitude.  Otherwise,
  37      *     it will be the y coordinate of the map location in your map units.
  38      */
  39     initialize: function(lon, lat) {
  40         this.lon = OpenLayers.Util.toFloat(lon);
  41         this.lat = OpenLayers.Util.toFloat(lat);
  42     },
  43
  44     /**
  45      * Method: toString
  46      * Return a readable string version of the lonlat
  47      *
  48      * Returns:
  49      * {String} String representation of OpenLayers.LonLat object.
  50      *           (ex. <i>"lon=5,lat=42"</i>)
  51      */
  52     toString:function() {
  53         return ("lon=" + this.lon + ",lat=" + this.lat);
  54     },
  55
  56     /**
  57      * APIMethod: toShortString
  58      *
  59      * Returns:
  60      * {String} Shortened String representation of OpenLayers.LonLat object.
  61      *         (ex. <i>"5, 42"</i>)
  62      */
  63     toShortString:function() {
  64         return (this.lon + ", " + this.lat);
  65     },
  66
  67     /**
  68      * APIMethod: clone
  69      *
  70      * Returns:
  71      * {<OpenLayers.LonLat>} New OpenLayers.LonLat object with the same lon
  72      *                       and lat values
  73      */
  74     clone:function() {
  75         return new OpenLayers.LonLat(this.lon, this.lat);
  76     },
  77
  78     /**
  79      * APIMethod: add
  80      *
  81      * Parameters:
  82      * lon - {Float}
  83      * lat - {Float}
  84      *
  85      * Returns:
  86      * {<OpenLayers.LonLat>} A new OpenLayers.LonLat object with the lon and
  87      *                       lat passed-in added to this's.
  88      */
  89     add:function(lon, lat) {
  90         if ( (lon == null) || (lat == null) ) {
  91             var msg = OpenLayers.i18n("lonlatAddError");
  92             OpenLayers.Console.error(msg);
  93             return null;
  94         }
  95         return new OpenLayers.LonLat(this.lon + lon, this.lat + lat);
  96     },
  97
  98     /**
  99      * APIMethod: equals
 100      *
 101      * Parameters:
 102      * ll - {<OpenLayers.LonLat>}
 103      *
 104      * Returns:
 105      * {Boolean} Boolean value indicating whether the passed-in
 106      *           <OpenLayers.LonLat> object has the same lon and lat
 107      *           components as this.
 108      *           Note: if ll passed in is null, returns false
 109      */
 110     equals:function(ll) {
 111         var equals = false;
 112         if (ll != null) {
 113             equals = ((this.lon == ll.lon && this.lat == ll.lat) ||
 114                       (isNaN(this.lon) && isNaN(this.lat) && isNaN(ll.lon) && isNaN(ll.lat)));
 115         }
 116         return equals;
 117     },
 118
 119     /**
 120      * APIMethod: transform
 121      * Transform the LonLat object from source to dest. This transformation is
 122      *    *in place*: if you want a *new* lonlat, use .clone() first.
 123      *
 124      * Parameters:
 125      * source - {<OpenLayers.Projection>} Source projection.
 126      * dest   - {<OpenLayers.Projection>} Destination projection.
 127      *
 128      * Returns:
 129      * {<OpenLayers.LonLat>} Itself, for use in chaining operations.
 130      */
 131     transform: function(source, dest) {
 132         var point = OpenLayers.Projection.transform(
 133             {'x': this.lon, 'y': this.lat}, source, dest);
 134         this.lon = point.x;
 135         this.lat = point.y;
 136         return this;
 137     },
 138
 139     /**
 140      * APIMethod: wrapDateLine
 141      *
 142      * Parameters:
 143      * maxExtent - {<OpenLayers.Bounds>}
 144      *
 145      * Returns:
 146      * {<OpenLayers.LonLat>} A copy of this lonlat, but wrapped around the
 147      *                       "dateline" (as specified by the borders of
 148      *                       maxExtent)
 149      */
 150     wrapDateLine: function(maxExtent) {
 151
 152         var newLonLat = this.clone();
 153
 154         if (maxExtent) {
 155             //shift right?
 156             while (newLonLat.lon < maxExtent.left) {
 157                 newLonLat.lon +=  maxExtent.getWidth();
 158             }
 159
 160             //shift left?
 161             while (newLonLat.lon > maxExtent.right) {
 162                 newLonLat.lon -= maxExtent.getWidth();
 163             }
 164         }
 165
 166         return newLonLat;
 167     },
 168
 169     CLASS_NAME: "OpenLayers.LonLat"
 170 });
 171
 172 /**
 173  * Function: fromString
 174  * Alternative constructor that builds a new <OpenLayers.LonLat> from a
 175  *     parameter string
 176  *
 177  * Parameters:
 178  * str - {String} Comma-separated Lon,Lat coordinate string.
 179  *                 (ex. <i>"5,40"</i>)
 180  *
 181  * Returns:
 182  * {<OpenLayers.LonLat>} New <OpenLayers.LonLat> object built from the
 183  *                       passed-in String.
 184  */
 185 OpenLayers.LonLat.fromString = function(str) {
 186     var pair = str.split(",");
 187     return new OpenLayers.LonLat(parseFloat(pair[0]),
 188                                  parseFloat(pair[1]));
 189 };