Merge pull request #369 from seethroughtrees/feature/findWhere

add option to pass fn as a selector in find method instead of a string.

konva.d.ts

@@ -5,15 +5,34 @@ declare namespace Konva {
   var isDragReady: () => boolean;
   var DD: any;
 
-  type globalCompositeOperationType = '' |
+  type globalCompositeOperationType =
-    'source-over' | 'source-in' | 'source-out' | 'source-atop' |
+    | ''
-    'destination-over' | 'destination-in' | 'destination-out' | 'destination-atop' |
+    | 'source-over'
-    'lighter' | 'copy' | 'xor' | 'multiply' |
+    | 'source-in'
-    'screen' | 'overlay' | 'darken' | 'lighten' |
+    | 'source-out'
-    'color-dodge' | 'color-burn' | 'hard-light' | 'soft-light' |
+    | 'source-atop'
-    'difference' | 'exclusion' | 'hue' | 'saturation' |
+    | 'destination-over'
-    'color' | 'luminosity'
+    | 'destination-in'
-  ;
+    | 'destination-out'
+    | 'destination-atop'
+    | 'lighter'
+    | 'copy'
+    | 'xor'
+    | 'multiply'
+    | 'screen'
+    | 'overlay'
+    | 'darken'
+    | 'lighten'
+    | 'color-dodge'
+    | 'color-burn'
+    | 'hard-light'
+    | 'soft-light'
+    | 'difference'
+    | 'exclusion'
+    | 'hue'
+    | 'saturation'
+    | 'color'
+    | 'luminosity';
 
   export class Util {
     static getRandomColor(): string;
@@ -323,7 +342,7 @@ declare namespace Konva {
     clipFunc(): (ctx: CanvasRenderingContext2D) => void;
     clipFunc(ctx: CanvasRenderingContext2D | undefined | null): void;
     destroyChildren(): void;
-    find(selector?: string): Collection;
+    find(selector?: string | ((Node) => boolean)): Collection;
     findOne<T extends Node>(selector: string): T;
     getAllIntersections(pos: Vector2d): Shape[];
     hasChildren(): boolean;

src/Container.js

@@ -141,14 +141,18 @@
       return this;
     },
     /**
-     * return a {@link Konva.Collection} of nodes that match the selector.  Use '#' for id selections
+     * return a {@link Konva.Collection} of nodes that match the selector.
-     * and '.' for name selections.  You can also select by type or class name. Pass multiple selectors
+     * You can provide a string with '#' for id selections and '.' for name selections.
+     * Or a function that will return true/false when a node is passed through.  See example below.
+     * With strings you can also select by type or class name. Pass multiple selectors
      * separated by a space.
      * @method
      * @memberof Konva.Container.prototype
-     * @param {String} selector
+     * @param {String | Function} selector
      * @returns {Collection}
      * @example
+     *
+     * Passing a string as a selector
      * // select node with id foo
      * var node = stage.find('#foo');
      *
@@ -163,8 +167,47 @@
      *
      * // select node with an id of foo or a name of bar inside layer
      * var nodes = layer.find('#foo, .bar');
+     *
+     * Passing a function as a selector
+     *
+     * // get all Groups
+     * var groups = stage.find(node => {
+     *  return node.getType() === 'Group';
+     * });
+     *
+     * // get only Nodes with partial opacity
+     * var alphaNodes = layer.find(node => {
+     *  return node.getType() === 'Node' && node.getAbsoluteOpacity() < 1;
+     * });
      */
     find: function(selector) {
+      var retArr = [];
+
+      if (typeof selector === 'string') {
+        retArr = this._findByString(selector);
+      } else if (typeof selector === 'function') {
+        retArr = this._findByFunction(selector);
+      }
+
+      return Konva.Collection.toCollection(retArr);
+    },
+    /**
+     * return a first node from `find` method
+     * @method
+     * @memberof Konva.Container.prototype
+     * @param {String} selector
+     * @returns {Konva.Node}
+     * @example
+     * // select node with id foo
+     * var node = stage.findOne('#foo');
+     *
+     * // select node with name bar inside layer
+     * var nodes = layer.findOne('.bar');
+     */
+    findOne: function(selector) {
+      return this.find(selector)[0];
+    },
+    _findByString: function(selector) {
       var retArr = [],
         selectorArr = selector.replace(/ /g, '').split(','),
         len = selectorArr.length,
@@ -209,23 +252,27 @@
         }
       }
 
-      return Konva.Collection.toCollection(retArr);
+      return retArr;
     },
-    /**
+    _findByFunction: function(fn) {
-     * return a first node from `find` method
+      var retArr = [];
-     * @method
+
-     * @memberof Konva.Container.prototype
+      var addItems = function(el) {
-     * @param {String} selector
+        var children = el.getChildren();
-     * @returns {Konva.Node}
+        var clen = children.length;
-     * @example
+
-     * // select node with id foo
+        if (fn(el)) {
-     * var node = stage.findOne('#foo');
+          retArr = retArr.concat(el);
-     *
+        }
-     * // select node with name bar inside layer
+
-     * var nodes = layer.findOne('.bar');
+        for (var i = 0; i < clen; i++) {
-     */
+          addItems(children[i]);
-    findOne: function(selector) {
+        }
-      return this.find(selector)[0];
+      };
+
+      addItems(this);
+
+      return retArr;
     },
     _getNodeById: function(key) {
       var node = Konva.ids[key];

test/unit/Container-test.js

@@ -406,6 +406,37 @@ suite('Container', function() {
     );
   });
 
+  // ======================================================
+  test('select shape by function', function() {
+    var stage = addStage();
+    var layer = new Konva.Layer();
+
+    var rect = new Konva.Rect({
+      x: 300,
+      y: 100,
+      width: 100,
+      height: 50,
+      fill: 'purple',
+      stroke: 'black',
+      strokeWidth: 4,
+      name: 'myRect'
+    });
+
+    layer.add(rect);
+    stage.add(layer);
+
+    var fn = function(node) {
+      return node.nodeType === 'Shape';
+    };
+
+    var noOp = function(node) {
+      return false;
+    };
+
+    assert.equal(stage.find(fn)[0], rect);
+    assert.equal(stage.find(noOp).length, 0);
+  });
+
   // ======================================================
   test('set x on an array of nodes', function() {
     var stage = addStage();