Merge pull request #7516 from ahocevar/overflow

Deprecate exceedLength and replace with overflow

changelog/upgrade-notes.md

@@ -1,5 +1,11 @@
 ## Upgrade notes
 
+### Next release
+
+#### Renamed `exceedLength` option of `ol.style.Text` to `overflow`
+
+To update your applications, simply replace `exceedLength` with `overflow`.
+
 ### v4.5.0
 
 #### Removed GeoJSON crs workaround for GeoServer

examples/vector-label-decluttering.html

@@ -5,7 +5,7 @@ shortdesc: Label decluttering with a custom renderer.
 resources:
   - https://cdn.polyfill.io/v2/polyfill.min.js?features=Set"
 docs: >
-  Decluttering is used to avoid overlapping labels with `exceedLength: true` set on the text style. For MultiPolygon geometries, only the widest polygon is selected in a custom `geometry` function.
+  Decluttering is used to avoid overlapping labels with `overflow: true` set on the text style. For MultiPolygon geometries, only the widest polygon is selected in a custom `geometry` function.
 tags: "vector, decluttering, labels"
 ---
 <div id="map" class="map"></div>

examples/vector-label-decluttering.js

@@ -37,7 +37,7 @@ var labelStyle = new ol.style.Style({
   },
   text: new ol.style.Text({
     font: '12px Calibri,sans-serif',
-    exceedLength: true,
+    overflow: true,
     fill: new ol.style.Fill({
       color: '#000'
     }),

examples/vector-labels.html

@@ -95,7 +95,7 @@ tags: "geojson, vector, openstreetmap, label"
     </select>
     <br />
     <label>Exceed Len: </label>
-    <select disabled id="points-exceedlength">
+    <select disabled id="points-overflow">
       <option value="true">True</option>
       <option value="false" selected="selected">False</option>
     </select>
@@ -204,7 +204,7 @@ tags: "geojson, vector, openstreetmap, label"
     </select>
     <br />
     <label>Exceed Len: </label>
-    <select id="lines-exceedlength">
+    <select id="lines-overflow">
       <option value="true">True</option>
       <option value="false" selected="selected">False</option>
     </select>
@@ -313,7 +313,7 @@ tags: "geojson, vector, openstreetmap, label"
     </select>
     <br />
     <label>Exceed Len: </label>
-    <select id="polygons-exceedlength">
+    <select id="polygons-overflow">
       <option value="true">True</option>
       <option value="false" selected="selected">False</option>
     </select>

examples/vector-labels.js

@@ -38,7 +38,7 @@ var myDom = {
     weight: document.getElementById('lines-weight'),
     placement: document.getElementById('lines-placement'),
     maxangle: document.getElementById('lines-maxangle'),
-    exceedlength: document.getElementById('lines-exceedlength'),
+    overflow: document.getElementById('lines-overflow'),
     size: document.getElementById('lines-size'),
     offsetX: document.getElementById('lines-offset-x'),
     offsetY: document.getElementById('lines-offset-y'),
@@ -56,7 +56,7 @@ var myDom = {
     weight: document.getElementById('polygons-weight'),
     placement: document.getElementById('polygons-placement'),
     maxangle: document.getElementById('polygons-maxangle'),
-    exceedlength: document.getElementById('polygons-exceedlength'),
+    overflow: document.getElementById('polygons-overflow'),
     size: document.getElementById('polygons-size'),
     offsetX: document.getElementById('polygons-offset-x'),
     offsetY: document.getElementById('polygons-offset-y'),
@@ -95,7 +95,7 @@ var createTextStyle = function(feature, resolution, dom) {
   var weight = dom.weight.value;
   var placement = dom.placement ? dom.placement.value : undefined;
   var maxAngle = dom.maxangle ? parseFloat(dom.maxangle.value) : undefined;
-  var exceedLength = dom.exceedlength ? (dom.exceedlength.value == 'true') : undefined;
+  var overflow = dom.overflow ? (dom.overflow.value == 'true') : undefined;
   var rotation = parseFloat(dom.rotation.value);
   if (dom.font.value == '\'Open Sans\'' && !openSansAdded) {
     var openSans = document.createElement('link');
@@ -120,7 +120,7 @@ var createTextStyle = function(feature, resolution, dom) {
     offsetY: offsetY,
     placement: placement,
     maxAngle: maxAngle,
-    exceedLength: exceedLength,
+    overflow: overflow,
     rotation: rotation
   });
 };

externs/olx.js

@@ -7853,6 +7853,7 @@ olx.style.StrokeOptions.prototype.width;
  *     maxAngle: (number|undefined),
  *     offsetX: (number|undefined),
  *     offsetY: (number|undefined),
+ *     overflow: (boolean|undefined),
  *     placement: (ol.style.TextPlacement|string|undefined),
  *     scale: (number|undefined),
  *     rotateWithView: (boolean|undefined),
@@ -7870,10 +7871,13 @@ olx.style.TextOptions;
 
 
 /**
+ * **Deprecated**. Use the `overflow` option instead.
+ *
  * For polygon labels or when `placement` is set to `'line'`, allow text to
- * exceed the width of the polygon at the the label position or the length of
+ * exceed the width of the polygon at the label position or the length of
  * the path that it follows. Default is `false`.
  * @type {boolean|undefined}
+ * @deprecated
  * @api
  */
 olx.style.TextOptions.prototype.exceedLength;
@@ -7917,6 +7921,16 @@ olx.style.TextOptions.prototype.offsetX;
 olx.style.TextOptions.prototype.offsetY;
 
 
+/**
+ * For polygon labels or when `placement` is set to `'line'`, allow text to
+ * exceed the width of the polygon at the label position or the length of
+ * the path that it follows. Default is `false`.
+ * @type {boolean|undefined}
+ * @api
+ */
+olx.style.TextOptions.prototype.overflow;
+
+
 /**
  * Text placement.
  * @type {ol.style.TextPlacement|undefined}

src/ol/render/canvas/replay.js

@@ -691,7 +691,7 @@ ol.render.canvas.Replay.prototype.replay_ = function(
         var end = /** @type {number} */ (instruction[2]);
         var baseline = /** @type {number} */ (instruction[3]);
         declutterGroup = /** @type {ol.DeclutterGroup} */ (instruction[4]);
-        var exceedLength = /** @type {number} */ (instruction[5]);
+        var overflow = /** @type {number} */ (instruction[5]);
         var fillKey = /** @type {string} */ (instruction[6]);
         var maxAngle = /** @type {number} */ (instruction[7]);
         var measure = /** @type {function(string):number} */ (instruction[8]);
@@ -704,7 +704,7 @@ ol.render.canvas.Replay.prototype.replay_ = function(
 
         var pathLength = ol.geom.flat.length.lineString(pixelCoordinates, begin, end, 2);
         var textLength = measure(text);
-        if (exceedLength || textLength <= pathLength) {
+        if (overflow || textLength <= pathLength) {
           var textAlign = /** @type {ol.render.canvas.TextReplay} */ (this).textStates[textKey].textAlign;
           var startM = (pathLength - textLength) * ol.render.replay.TEXT_ALIGN[textAlign];
           var parts = ol.geom.flat.textpath.lineString(

src/ol/render/canvas/textreplay.js

@@ -239,7 +239,7 @@ ol.render.canvas.TextReplay.prototype.drawText = function(geometry, feature) {
         break;
       case ol.geom.GeometryType.POLYGON:
         flatCoordinates = /** @type {ol.geom.Polygon} */ (geometry).getFlatInteriorPoint();
-        if (!textState.exceedLength && flatCoordinates[2] / this.resolution < width) {
+        if (!textState.overflow && flatCoordinates[2] / this.resolution < width) {
           return;
         }
         stride = 3;
@@ -248,7 +248,7 @@ ol.render.canvas.TextReplay.prototype.drawText = function(geometry, feature) {
         var interiorPoints = /** @type {ol.geom.MultiPolygon} */ (geometry).getFlatInteriorPoints();
         flatCoordinates = [];
         for (i = 0, ii = interiorPoints.length; i < ii; i += 3) {
-          if (textState.exceedLength || interiorPoints[i + 2] / this.resolution >= width) {
+          if (textState.overflow || interiorPoints[i + 2] / this.resolution >= width) {
             flatCoordinates.push(interiorPoints[i], interiorPoints[i + 1]);
           }
         }
@@ -434,7 +434,7 @@ ol.render.canvas.TextReplay.prototype.drawChars_ = function(begin, end, declutte
   }
   this.instructions.push([ol.render.canvas.Instruction.DRAW_CHARS,
     begin, end, baseline, declutterGroup,
-    textState.exceedLength, fillKey, textState.maxAngle,
+    textState.overflow, fillKey, textState.maxAngle,
     function(text) {
       var width = widths[text];
       if (!width) {
@@ -446,7 +446,7 @@ ol.render.canvas.TextReplay.prototype.drawChars_ = function(begin, end, declutte
   ]);
   this.hitDetectionInstructions.push([ol.render.canvas.Instruction.DRAW_CHARS,
     begin, end, baseline, declutterGroup,
-    textState.exceedLength, fillKey, textState.maxAngle,
+    textState.overflow, fillKey, textState.maxAngle,
     function(text) {
       var width = widths[text];
       if (!width) {
@@ -510,7 +510,7 @@ ol.render.canvas.TextReplay.prototype.setTextStyle = function(textStyle, declutt
     var font = textStyle.getFont() || ol.render.canvas.defaultFont;
     ol.render.canvas.checkFont(font);
     var textScale = textStyle.getScale();
-    textState.exceedLength = textStyle.getExceedLength();
+    textState.overflow = textStyle.getOverflow();
     textState.font = font;
     textState.maxAngle = textStyle.getMaxAngle();
     textState.placement = textStyle.getPlacement();

src/ol/style/text.js

@@ -82,7 +82,7 @@ ol.style.Text = function(opt_options) {
    * @private
    * @type {boolean}
    */
-  this.exceedLength_ = options.exceedLength !== undefined ? options.exceedLength : false;
+  this.overflow_ = options.overflow !== undefined ? options.overflow : false;
 
   /**
    * @private
@@ -142,7 +142,7 @@ ol.style.Text.prototype.clone = function() {
     font: this.getFont(),
     placement: this.getPlacement(),
     maxAngle: this.getMaxAngle(),
-    exceedLength: this.getExceedLength(),
+    overflow: this.getOverflow(),
     rotation: this.getRotation(),
     rotateWithView: this.getRotateWithView(),
     scale: this.getScale(),
@@ -158,12 +158,12 @@ ol.style.Text.prototype.clone = function() {
 
 
 /**
- * Get the `exceedLength` configuration.
- * @return {boolean} Let text exceed the length of the path they follow.
+ * Get the `overflow` configuration.
+ * @return {boolean} Let text overflow the length of the path they follow.
  * @api
  */
-ol.style.Text.prototype.getExceedLength = function() {
-  return this.exceedLength_;
+ol.style.Text.prototype.getOverflow = function() {
+  return this.overflow_;
 };
 
 
@@ -328,13 +328,13 @@ ol.style.Text.prototype.getPadding = function() {
 
 
 /**
- * Set the `exceedLength` property.
+ * Set the `overflow` property.
  *
- * @param {boolean} exceedLength Let text exceed the path that it follows.
+ * @param {boolean} overflow Let text overflow the path that it follows.
  * @api
  */
-ol.style.Text.prototype.setExceedLength = function(exceedLength) {
-  this.exceedLength_ = exceedLength;
+ol.style.Text.prototype.setOverflow = function(overflow) {
+  this.overflow_ = overflow;
 };
 
 

test/rendering/ol/style/text.test.js

@@ -382,7 +382,7 @@ describe('ol.rendering.style.Text', function() {
           text: 'Hello world',
           font: 'bold 24px sans-serif',
           placement: 'line',
-          exceedLength: true
+          overflow: true
         })
       }));
       vectorSource.addFeature(feature);
@@ -406,7 +406,7 @@ describe('ol.rendering.style.Text', function() {
           text: 'Hello world',
           font: 'bold 24px sans-serif',
           placement: 'line',
-          exceedLength: true
+          overflow: true
         })
       }));
       vectorSource.addFeature(feature);