perf: Add addMultipleAnnotations method

This is primarily faster because of the less events being triggered.
The addAnnotation method can also ask to not trigger events.

Author: manthey

src/annotationLayer.js

@@ -491,18 +491,22 @@ var annotationLayer = function (arg) {
    *    gcs, `null` to use the map gcs, or any other transform.
    * @param {boolean} [update] If `false`, don't update the layer after adding
    *    the annotation.
+   * @param {boolean} [trigger] If `false`, do trigger add_before and add
+   *    events.
    * @returns {this} The current layer.
    * @fires geo.event.annotation.add_before
    * @fires geo.event.annotation.add
    */
-  this.addAnnotation = function (annotation, gcs, update) {
+  this.addAnnotation = function (annotation, gcs, update, trigger) {
     if (m_annotationIds[annotation.id()] === undefined) {
       while (m_this.annotationById(annotation.id())) {
         annotation.newId();
       }
-      m_this.geoTrigger(geo_event.annotation.add_before, {
-        annotation: annotation
-      });
+      if (trigger !== false) {
+        m_this.geoTrigger(geo_event.annotation.add_before, {
+          annotation: annotation
+        });
+      }
       m_annotations.push(annotation);
       m_annotationIds[annotation.id()] = annotation;
       annotation.layer(m_this);
@@ -516,8 +520,43 @@ var annotationLayer = function (arg) {
         m_this.modified();
         m_this.draw();
       }
+      if (trigger !== false) {
+        m_this.geoTrigger(geo_event.annotation.add, {
+          annotation: annotation
+        });
+      }
+    }
+    return m_this;
+  };
+
+  /**
+   * Add multiple annotations to the layer.  The annotations could be in any
+   * state.
+   *
+   * @param {geo.annotation[]} annotations The annotations to add.
+   * @param {string|geo.transform|null} [gcs] `undefined` to use the interface
+   *    gcs, `null` to use the map gcs, or any other transform.
+   * @param {boolean} [update] If `false`, don't update the layer after adding
+   *    the annotation.
+   * @returns {this} The current layer.
+   * @fires geo.event.annotation.add_before
+   * @fires geo.event.annotation.add
+   */
+  this.addMultipleAnnotations = function (annotations, gcs, update) {
+    const added = [];
+    m_this.geoTrigger(geo_event.annotation.add_before, {
+      annotations: annotations
+    });
+    for (let i = 0; i < annotations.length; i += 1) {
+      const annotation = annotations[i];
+      if (m_annotationIds[annotation.id()] === undefined) {
+        this.addAnnotation(annotation, gcs, update, false);
+        added.push(annotation);
+      }
+    }
+    if (added.length) {
       m_this.geoTrigger(geo_event.annotation.add, {
-        annotation: annotation
+        annotations: added
       });
     }
     return m_this;

src/event.js

@@ -656,20 +656,23 @@ geo_event.camera.viewport = 'geo_camera_viewport';
 geo_event.annotation = {};
 
 /**
- * Triggered when an annotation has been added.
+ * Triggered when or more multiple annotations have been added.
  *
  * @event geo.event.annotation.add
  * @type {geo.event.base}
- * @property {geo.annotation} annotation The annotation that was added.
+ * @property {geo.annotation} [annotation] The annotation that was added.
+ * @property {geo.annotation} [annotations] The annotations that were added.
  */
 geo_event.annotation.add = 'geo_annotation_add';
 
 /**
- * Triggered when an annotation is about to be added.
+ * Triggered when one or multiple annotations are about to be added.
  *
  * @event geo.event.annotation.add_before
  * @type {geo.event.base}
- * @property {geo.annotation} annotation The annotation that will be added.
+ * @property {geo.annotation} [annotation] The annotation that will be added.
+ * @property {geo.annotation[]} [annotations] The annotations that will be
+ *   added.
  */
 geo_event.annotation.add_before = 'geo_annotation_add_before';
 

tests/cases/annotationLayer.js

@@ -110,6 +110,18 @@ describe('geo.annotationLayer', function () {
       layer.removeAllAnnotations();
       expect(layer.annotations().length).toBe(0);
     });
+    it('multipleAnnotations', function () {
+      var poly = geo.annotation.polygonAnnotation({
+            state: geo.annotation.state.create, layer: layer}),
+          rect = geo.annotation.rectangleAnnotation({
+            layer: layer,
+            corners: [{x: 0, y: 0}, {x: 1, y: 0}, {x: 1, y: 1}, {x: 0, y: 1}]});
+      expect(layer.annotations().length).toBe(0);
+      layer.addMultipleAnnotations([poly, rect]);
+      expect(layer.annotations().length).toBe(2);
+      expect(layer.annotations()[0]).toBe(poly);
+      expect(layer.annotations()[1]).toBe(rect);
+    });
   });
   describe('Public utility functions', function () {
     var map, layer,