Refactor selection testing namings and structure [1852]

- Renaming because since click-to-select, selections not only
  can be defined by polygons, but also by point numbers.
  Up until now code was centered around polygons being
  the sole means to define a selection. Renamed
  identifiers to be more general.
- Extract `multitester` to new module `lib/select.js` because
  `multitester` is no longer to been seen in the
  sole context of polygons.

Author: rmoestl

src/lib/polygon.js

@@ -174,34 +174,31 @@ polygon.tester = function tester(ptsIn) {
     };
 };
 
+// TODO Somewhat redundant to multiTester in 'lib/select.js'
 /**
  * Test multiple polygons
  */
 polygon.multitester = function multitester(list) {
     var testers = [],
-        xmin = list[0].contains ? 0 : list[0][0][0],
+        xmin = list[0][0][0],
         xmax = xmin,
-        ymin = list[0].contains ? 0 : list[0][0][1],
+        ymin = list[0][0][1],
         ymax = ymin;
 
     for(var i = 0; i < list.length; i++) {
-        if(list[i].contains) {
-            testers.push(list[i]);
-        } else {
-            var tester = polygon.tester(list[i]);
-            tester.subtract = list[i].subtract;
-            testers.push(tester);
-            xmin = Math.min(xmin, tester.xmin);
-            xmax = Math.max(xmax, tester.xmax);
-            ymin = Math.min(ymin, tester.ymin);
-            ymax = Math.max(ymax, tester.ymax);
-        }
+        var tester = polygon.tester(list[i]);
+        tester.subtract = list[i].subtract;
+        testers.push(tester);
+        xmin = Math.min(xmin, tester.xmin);
+        xmax = Math.max(xmax, tester.xmax);
+        ymin = Math.min(ymin, tester.ymin);
+        ymax = Math.max(ymax, tester.ymax);
     }
 
-    function contains(pt, arg, pointNumber, searchInfo) {
+    function contains(pt, arg) {
         var yes = false;
         for(var i = 0; i < testers.length; i++) {
-            if(testers[i].contains(pt, arg, pointNumber, searchInfo)) {
+            if(testers[i].contains(pt, arg)) {
                 // if contained by subtract polygon - exclude the point
                 yes = testers[i].subtract === false;
             }

src/lib/select.js

@@ -0,0 +1,116 @@
+/**
+* Copyright 2012-2018, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+
+'use strict';
+
+var polygon = require('./polygon');
+
+var select = module.exports = {};
+
+/**
+ * Constructs a new point selection definition.
+ *
+ * @param pointNumber the point number of the point as in `data`
+ * @param searchInfo identifies the trace the point is contained in
+ * @param subtract true if the selection definition should mark a deselection
+ * @return {{pointNumber: Number, searchInfo: Object, subtract: boolean}}
+ */
+select.pointSelectionDef = function(pointNumber, searchInfo, subtract) {
+    return {
+        pointNumber: pointNumber,
+        searchInfo: searchInfo,
+        subtract: subtract
+    };
+};
+
+function isPointSelectionDef(o) {
+    return 'pointNumber' in o && 'searchInfo' in o;
+}
+
+function pointNumberTester(pointSelectionDef) {
+    return {
+        xmin: 0,
+        xmax: 0,
+        ymin: 0,
+        ymax: 0,
+        pts: [],
+        contains: function(pt, omitFirstEdge, pointNumber, searchInfo) {
+            return searchInfo.cd[0].trace._expandedIndex === pointSelectionDef.searchInfo.cd[0].trace._expandedIndex &&
+              pointNumber === pointSelectionDef.pointNumber;
+        },
+        isRect: false,
+        degenerate: false,
+        subtract: pointSelectionDef.subtract
+    };
+}
+
+/**
+ * Wraps multiple selection testers.
+ *
+ * @param list an array of selection testers
+ *
+ * @return a selection tester object with a contains function
+ * that can be called to evaluate a point against all wrapped
+ * selection testers that were passed in list.
+ */
+select.multiTester = function multiTester(list) {
+    var testers = [];
+    var xmin = isPointSelectionDef(list[0]) ? 0 : list[0][0][0];
+    var xmax = xmin;
+    var ymin = isPointSelectionDef(list[0]) ? 0 : list[0][0][1];
+    var ymax = ymin;
+
+    for(var i = 0; i < list.length; i++) {
+        if(isPointSelectionDef(list[i])) {
+            testers.push(pointNumberTester(list[i]));
+        } else {
+            var tester = polygon.tester(list[i]);
+            tester.subtract = list[i].subtract;
+            testers.push(tester);
+            xmin = Math.min(xmin, tester.xmin);
+            xmax = Math.max(xmax, tester.xmax);
+            ymin = Math.min(ymin, tester.ymin);
+            ymax = Math.max(ymax, tester.ymax);
+        }
+    }
+
+    // TODO Consider making signature of contains more lean
+    /**
+     * Tests if the given point is within this tester.
+     *
+     * @param pt an object having an `x` and a `y` property defining the location
+     *        of the point
+     * @param arg parameter to pass additional arguments down to wrapped testers
+     * @param pointNumber the point number of the point
+     * @param searchInfo identifies the trace the point is contained in
+     * @return {boolean}
+     */
+    function contains(pt, arg, pointNumber, searchInfo) {
+        var yes = false;
+        for(var i = 0; i < testers.length; i++) {
+            if(testers[i].contains(pt, arg, pointNumber, searchInfo)) {
+                // if contained by subtract tester - exclude the point
+                yes = testers[i].subtract === false;
+            }
+        }
+
+        return yes;
+    }
+
+    return {
+        xmin: xmin,
+        xmax: xmax,
+        ymin: ymin,
+        ymax: ymax,
+        pts: [],
+        contains: contains,
+        isRect: false,
+        degenerate: false
+    };
+};

src/plots/cartesian/select.js

@@ -16,6 +16,7 @@ var Color = require('../../components/color');
 var Fx = require('../../components/fx');
 
 var polygon = require('../../lib/polygon');
+var select = require('../../lib/select');
 var throttle = require('../../lib/throttle');
 var makeEventData = require('../../components/fx/helpers').makeEventData;
 var getFromId = require('./axis_ids').getFromId;
@@ -26,7 +27,8 @@ var MINSELECT = constants.MINSELECT;
 
 var filteredPolygon = polygon.filter;
 var polygonTester = polygon.tester;
-var multipolygonTester = polygon.multitester;
+var pointSelectionDef = select.pointSelectionDef;
+var multiTester = select.multiTester;
 
 function getAxId(ax) { return ax._id; }
 
@@ -50,7 +52,7 @@ function prepSelect(e, startX, startY, dragOptions, mode) {
     var allAxes = dragOptions.xaxes.concat(dragOptions.yaxes);
     var subtract = e.altKey;
 
-    var filterPoly, testPoly, mergedPolygons, currentPolygon;
+    var filterPoly, selectionTester, mergedPolygons, currentPolygon;
     var i, searchInfo, eventData;
 
     coerceSelectionsCache(e, gd, dragOptions);
@@ -185,14 +187,14 @@ function prepSelect(e, startX, startY, dragOptions, mode) {
         }
 
         // create outline & tester
-        if(dragOptions.polygons && dragOptions.polygons.length) {
+        if(dragOptions.selectionDefs && dragOptions.selectionDefs.length) {
             mergedPolygons = mergePolygons(dragOptions.mergedPolygons, currentPolygon, subtract);
             currentPolygon.subtract = subtract;
-            testPoly = multipolygonTester(dragOptions.polygons.concat([currentPolygon]));
+            selectionTester = multiTester(dragOptions.selectionDefs.concat([currentPolygon]));
         }
         else {
             mergedPolygons = [currentPolygon];
-            testPoly = polygonTester(currentPolygon);
+            selectionTester = polygonTester(currentPolygon);
         }
 
         // draw selection
@@ -209,7 +211,7 @@ function prepSelect(e, startX, startY, dragOptions, mode) {
                 for(i = 0; i < searchTraces.length; i++) {
                     searchInfo = searchTraces[i];
 
-                    traceSelection = searchInfo._module.selectPoints(searchInfo, testPoly);
+                    traceSelection = searchInfo._module.selectPoints(searchInfo, selectionTester);
                     traceSelections.push(traceSelection);
 
                     thisSelection = fillSelectionItem(traceSelection, searchInfo);
@@ -276,10 +278,10 @@ function prepSelect(e, startX, startY, dragOptions, mode) {
             throttle.clear(throttleID);
             dragOptions.gd.emit('plotly_selected', eventData);
 
-            if(currentPolygon && dragOptions.polygons) {
+            if(currentPolygon && dragOptions.selectionDefs) {
                 // save last polygons
                 currentPolygon.subtract = subtract;
-                dragOptions.polygons.push(currentPolygon);
+                dragOptions.selectionDefs.push(currentPolygon);
 
                 // we have to keep reference to arrays container
                 dragOptions.mergedPolygons.length = 0;
@@ -296,8 +298,8 @@ function selectOnClick(evt, gd, xAxes, yAxes, subplot, dragOptions, polygonOutli
     var selection = [];
     var searchTraces;
     var searchInfo;
-    var currentPolygon;
-    var testPoly;
+    var currentSelectionDef;
+    var selectionTester;
     var traceSelection;
     var thisTracesSelection;
     var pointOrBinSelected;
@@ -338,13 +340,13 @@ function selectOnClick(evt, gd, xAxes, yAxes, subplot, dragOptions, polygonOutli
               (pointOrBinSelected !== undefined ?
                 pointOrBinSelected :
                 isPointOrBinSelected(clickedPtInfo));
-            currentPolygon = createPtNumTester(clickedPtInfo.pointNumber, clickedPtInfo.searchInfo, subtract);
+            currentSelectionDef = pointSelectionDef(clickedPtInfo.pointNumber, clickedPtInfo.searchInfo, subtract);
 
-            var concatenatedPolygons = dragOptions.polygons.concat([currentPolygon]);
-            testPoly = multipolygonTester(concatenatedPolygons);
+            var allSelectionDefs = dragOptions.selectionDefs.concat([currentSelectionDef]);
+            selectionTester = multiTester(allSelectionDefs);
 
             for(i = 0; i < searchTraces.length; i++) {
-                traceSelection = searchTraces[i]._module.selectPoints(searchTraces[i], testPoly);
+                traceSelection = searchTraces[i]._module.selectPoints(searchTraces[i], selectionTester);
                 thisTracesSelection = fillSelectionItem(traceSelection, searchTraces[i]);
 
                 if(selection.length) {
@@ -358,8 +360,8 @@ function selectOnClick(evt, gd, xAxes, yAxes, subplot, dragOptions, polygonOutli
             eventData = {points: selection};
             updateSelectedState(gd, searchTraces, eventData);
 
-            if(currentPolygon && dragOptions) {
-                dragOptions.polygons.push(currentPolygon);
+            if(currentSelectionDef && dragOptions) {
+                dragOptions.selectionDefs.push(currentSelectionDef);
             }
 
             if(polygonOutlines) drawSelection(dragOptions.mergedPolygons, polygonOutlines);
@@ -384,11 +386,11 @@ function coerceSelectionsCache(evt, gd, dragOptions) {
     if(
       selectingOnSameSubplot &&
       (evt.shiftKey || evt.altKey) &&
-      (plotinfo.selection && plotinfo.selection.polygons) &&
-      !dragOptions.polygons
+      (plotinfo.selection && plotinfo.selection.selectionDefs) &&
+      !dragOptions.selectionDefs
     ) {
-        // take over selection polygons from prev mode, if any
-        dragOptions.polygons = plotinfo.selection.polygons;
+        // take over selection definitions from prev mode, if any
+        dragOptions.selectionDefs = plotinfo.selection.selectionDefs;
         dragOptions.mergedPolygons = plotinfo.selection.mergedPolygons;
     } else if(
       (!evt.shiftKey && !evt.altKey) ||
@@ -408,7 +410,7 @@ function clearSelectionsCache(dragOptions) {
     var plotinfo = dragOptions.plotinfo;
 
     plotinfo.selection = {};
-    plotinfo.selection.polygons = dragOptions.polygons = [];
+    plotinfo.selection.selectionDefs = dragOptions.selectionDefs = [];
     plotinfo.selection.mergedPolygons = dragOptions.mergedPolygons = [];
 }
 
@@ -515,24 +517,6 @@ function extractClickedPtInfo(hoverData, searchTraces) {
     };
 }
 
-function createPtNumTester(wantedPointNumber, wantedSearchInfo, subtract) {
-    return {
-        xmin: 0,
-        xmax: 0,
-        ymin: 0,
-        ymax: 0,
-        pts: [],
-        // TODO Consider making signature of contains more lean
-        contains: function(pt, omitFirstEdge, pointNumber, searchInfo) {
-            return searchInfo.cd[0].trace._expandedIndex === wantedSearchInfo.cd[0].trace._expandedIndex &&
-                pointNumber === wantedPointNumber;
-        },
-        isRect: false,
-        degenerate: false,
-        subtract: subtract
-    };
-}
-
 function isPointOrBinSelected(clickedPtInfo) {
     var trace = clickedPtInfo.searchInfo.cd[0].trace;
     var ptNum = clickedPtInfo.pointNumber;

src/traces/bar/select.js

@@ -8,14 +8,14 @@
 
 'use strict';
 
-module.exports = function selectPoints(searchInfo, polygon) {
+module.exports = function selectPoints(searchInfo, selectionTester) {
     var cd = searchInfo.cd;
     var xa = searchInfo.xaxis;
     var ya = searchInfo.yaxis;
     var selection = [];
     var i;
 
-    if(polygon === false) {
+    if(selectionTester === false) {
         // clear selection
         for(i = 0; i < cd.length; i++) {
             cd[i].selected = 0;
@@ -24,7 +24,7 @@ module.exports = function selectPoints(searchInfo, polygon) {
         for(i = 0; i < cd.length; i++) {
             var di = cd[i];
 
-            if(polygon.contains(di.ct, false, i, searchInfo)) {
+            if(selectionTester.contains(di.ct, false, i, searchInfo)) {
                 selection.push({
                     pointNumber: i,
                     x: xa.c2d(di.x),

src/traces/box/select.js

@@ -8,14 +8,14 @@
 
 'use strict';
 
-module.exports = function selectPoints(searchInfo, polygon) {
+module.exports = function selectPoints(searchInfo, selectionTester) {
     var cd = searchInfo.cd;
     var xa = searchInfo.xaxis;
     var ya = searchInfo.yaxis;
     var selection = [];
     var i, j;
 
-    if(polygon === false) {
+    if(selectionTester === false) {
         for(i = 0; i < cd.length; i++) {
             for(j = 0; j < (cd[i].pts || []).length; j++) {
                 // clear selection
@@ -29,7 +29,7 @@ module.exports = function selectPoints(searchInfo, polygon) {
                 var x = xa.c2p(pt.x);
                 var y = ya.c2p(pt.y);
 
-                if(polygon.contains([x, y], null, pt.i, searchInfo)) {
+                if(selectionTester.contains([x, y], null, pt.i, searchInfo)) {
                     selection.push({
                         pointNumber: pt.i,
                         x: xa.c2d(pt.x),

src/traces/choropleth/select.js

@@ -8,15 +8,15 @@
 
 'use strict';
 
-module.exports = function selectPoints(searchInfo, polygon) {
+module.exports = function selectPoints(searchInfo, selectionTester) {
     var cd = searchInfo.cd;
     var xa = searchInfo.xaxis;
     var ya = searchInfo.yaxis;
     var selection = [];
 
     var i, di, ct, x, y;
 
-    if(polygon === false) {
+    if(selectionTester === false) {
         for(i = 0; i < cd.length; i++) {
             cd[i].selected = 0;
         }
@@ -30,7 +30,7 @@ module.exports = function selectPoints(searchInfo, polygon) {
             x = xa.c2p(ct);
             y = ya.c2p(ct);
 
-            if(polygon.contains([x, y], null, i, searchInfo)) {
+            if(selectionTester.contains([x, y], null, i, searchInfo)) {
                 selection.push({
                     pointNumber: i,
                     lon: ct[0],