Merge pull request #2217 from elemoine/overlay-offset

Add an offset property to ol.Overlay

externs/olx.js

@@ -203,12 +203,11 @@ olx.MapOptions.prototype.view;
 /**
  * Object literal with config options for the overlay.
  * @typedef {{element: (Element|undefined),
+ *     offset: (Array.<number>|undefined),
  *     position: (ol.Coordinate|undefined),
  *     positioning: (ol.OverlayPositioning|string|undefined),
  *     stopEvent: (boolean|undefined),
- *     insertFirst: (boolean|undefined),
+ *     insertFirst: (boolean|undefined)}}
- *     offsetX: (number|undefined),
- *     offsetY: (number|undefined)}}
  * @todo api
  */
 olx.OverlayOptions;
@@ -221,6 +220,16 @@ olx.OverlayOptions;
 olx.OverlayOptions.prototype.element;
 
 
+/**
+ * Offsets in pixels used when positioning the overlay. The fist element in the
+ * array is the horizontal offset. A positive value shifts the overlay right.
+ * The second element in the array is the vertical offset. A positive value
+ * shifts the overlay down. Default is `[0, 0]`.
+ * @type {Array.<number>|undefined}
+ */
+olx.OverlayOptions.prototype.offset;
+
+
 /**
  * The overlay position in map projection.
  * @type {ol.Coordinate|undefined}
@@ -229,7 +238,10 @@ olx.OverlayOptions.prototype.position;
 
 
 /**
- * Positioning.
+ * Defines how the overlay is actually positioned with respect to its `position`
+ * property. Possible values are `'bottom-left'`, `'bottom-center'`,
+ * `'bottom-right'`, `'center-left'`, `'center-center'`, `'center-right'`,
+ * `'top-left'`, `'top-center'`, and `'top-right'`. Default is `'top-left'`.
  * @type {ol.OverlayPositioning|string|undefined}
  */
 olx.OverlayOptions.prototype.positioning;
@@ -254,22 +266,6 @@ olx.OverlayOptions.prototype.stopEvent;
 olx.OverlayOptions.prototype.insertFirst;
 
 
-/**
- * Horizontal offset in pixels. A positive will shift the overlay right. Default
- * is `0`.
- * @type {number|undefined}
- */
-olx.OverlayOptions.prototype.offsetX;
-
-
-/**
- * Vertical offset in pixels. A positive will shift the overlay down. Default is
- * `0`.
- * @type {number|undefined}
- */
-olx.OverlayOptions.prototype.offsetY;
-
-
 /**
  * Object literal with config options for the Proj4js projection.
  * @typedef {{code: string,

src/ol/overlay.js

@@ -19,6 +19,7 @@ goog.require('ol.Object');
 ol.OverlayProperty = {
   ELEMENT: 'element',
   MAP: 'map',
+  OFFSET: 'offset',
   POSITION: 'position',
   POSITIONING: 'positioning'
 };
@@ -82,18 +83,6 @@ ol.Overlay = function(options) {
    */
   this.stopEvent_ = goog.isDef(options.stopEvent) ? options.stopEvent : true;
 
-  /**
-   * @private
-   * @type {number}
-   */
-  this.offsetX_ = goog.isDef(options.offsetX) ? options.offsetX : 0;
-
-  /**
-   * @private
-   * @type {number}
-   */
-  this.offsetY_ = goog.isDef(options.offsetY) ? options.offsetY : 0;
-
   /**
    * @private
    * @type {Element}
@@ -131,6 +120,10 @@ ol.Overlay = function(options) {
       this, ol.Object.getChangeEventType(ol.OverlayProperty.MAP),
       this.handleMapChanged, false, this);
 
+  goog.events.listen(
+      this, ol.Object.getChangeEventType(ol.OverlayProperty.OFFSET),
+      this.handleOffsetChanged, false, this);
+
   goog.events.listen(
       this, ol.Object.getChangeEventType(ol.OverlayProperty.POSITION),
       this.handlePositionChanged, false, this);
@@ -143,13 +136,16 @@ ol.Overlay = function(options) {
   if (goog.isDef(options.element)) {
     this.setElement(options.element);
   }
+
+  this.setOffset(goog.isDef(options.offset) ? options.offset : [0, 0]);
+
+  this.setPositioning(goog.isDef(options.positioning) ?
+      /** @type {ol.OverlayPositioning} */ (options.positioning) :
+      ol.OverlayPositioning.TOP_LEFT);
+
   if (goog.isDef(options.position)) {
     this.setPosition(options.position);
   }
-  if (goog.isDef(options.positioning)) {
-    this.setPositioning(
-        /** @type {ol.OverlayPositioning} */ (options.positioning));
-  }
 
 };
 goog.inherits(ol.Overlay, ol.Object);
@@ -187,6 +183,22 @@ goog.exportProperty(
     ol.Overlay.prototype.getMap);
 
 
+/**
+ * Get the offset of this overlay.
+ * @return {Array.<number>} The offset.
+ * @todo observable
+ * @todo api
+ */
+ol.Overlay.prototype.getOffset = function() {
+  return /** @type {Array.<number>} */ (
+      this.get(ol.OverlayProperty.OFFSET));
+};
+goog.exportProperty(
+    ol.Overlay.prototype,
+    'getOffset',
+    ol.Overlay.prototype.getOffset);
+
+
 /**
  * Get the current position of this overlay.
  * @return {ol.Coordinate|undefined} The spatial point that the overlay is
@@ -206,13 +218,13 @@ goog.exportProperty(
 
 /**
  * Get the current positioning of this overlay.
- * @return {ol.OverlayPositioning|undefined} How the overlay is positioned
+ * @return {ol.OverlayPositioning} How the overlay is positioned
  *     relative to its point on the map.
  * @todo observable
  * @todo api
  */
 ol.Overlay.prototype.getPositioning = function() {
-  return /** @type {ol.OverlayPositioning|undefined} */ (
+  return /** @type {ol.OverlayPositioning} */ (
       this.get(ol.OverlayProperty.POSITIONING));
 };
 goog.exportProperty(
@@ -267,6 +279,14 @@ ol.Overlay.prototype.handleMapPostrender = function() {
 };
 
 
+/**
+ * @protected
+ */
+ol.Overlay.prototype.handleOffsetChanged = function() {
+  this.updatePixelPosition_();
+};
+
+
 /**
  * @protected
  */
@@ -313,6 +333,21 @@ goog.exportProperty(
     ol.Overlay.prototype.setMap);
 
 
+/**
+ * Set the offset for this overlay.
+ * @param {Array.<number>} offset Offset.
+ * @todo observable
+ * @todo api
+ */
+ol.Overlay.prototype.setOffset = function(offset) {
+  this.set(ol.OverlayProperty.OFFSET, offset);
+};
+goog.exportProperty(
+    ol.Overlay.prototype,
+    'setOffset',
+    ol.Overlay.prototype.setOffset);
+
+
 /**
  * Set the position for this overlay.
  * @param {ol.Coordinate|undefined} position The spatial point that the overlay
@@ -331,7 +366,7 @@ goog.exportProperty(
 
 /**
  * Set the positioning for this overlay.
- * @param {ol.OverlayPositioning|undefined} positioning how the overlay is
+ * @param {ol.OverlayPositioning} positioning how the overlay is
  *     positioned relative to its point on the map.
  * @todo observable
  * @todo api
@@ -365,7 +400,11 @@ ol.Overlay.prototype.updatePixelPosition_ = function() {
   var mapSize = map.getSize();
   goog.asserts.assert(goog.isDef(mapSize));
   var style = this.element_.style;
+  var offset = this.getOffset();
+  goog.asserts.assert(goog.isArray(offset));
   var positioning = this.getPositioning();
+  goog.asserts.assert(goog.isDef(positioning));
+
   if (positioning == ol.OverlayPositioning.BOTTOM_RIGHT ||
       positioning == ol.OverlayPositioning.CENTER_RIGHT ||
       positioning == ol.OverlayPositioning.TOP_RIGHT) {
@@ -380,7 +419,7 @@ ol.Overlay.prototype.updatePixelPosition_ = function() {
     if (this.rendered_.right_ !== '') {
       this.rendered_.right_ = style.right = '';
     }
-    var offsetX = -this.offsetX_;
+    var offsetX = -offset[0];
     if (positioning == ol.OverlayPositioning.BOTTOM_CENTER ||
         positioning == ol.OverlayPositioning.CENTER_CENTER ||
         positioning == ol.OverlayPositioning.TOP_CENTER) {
@@ -405,7 +444,7 @@ ol.Overlay.prototype.updatePixelPosition_ = function() {
     if (this.rendered_.bottom_ !== '') {
       this.rendered_.bottom_ = style.bottom = '';
     }
-    var offsetY = -this.offsetY_;
+    var offsetY = -offset[1];
     if (positioning == ol.OverlayPositioning.CENTER_LEFT ||
         positioning == ol.OverlayPositioning.CENTER_CENTER ||
         positioning == ol.OverlayPositioning.CENTER_RIGHT) {