plotboilerplate 1.14.0 → 1.17.0

package/src/ts/Vertex.ts

@@ -24,7 +24,11 @@
  * @modified 2021-03-01 Changed the second param `center` in the `rotate` function from Vertex to XYCoords.
  * @modified 2021-12-01 Changed the type of param of `scale` to XYCoords.
  * @modified 2021-12-01 Added function `scaleXY` for non uniform scaling.
- * @version  2.5.0
+ * @modified 2021-12-17 Added the functions `lerp` and `lerpAbs` for linear interpolations.
+ * @modified 2022-01-31 Added `Vertex.utils.arrayToJSON`.
+ * @modified 2022-02-02 Added the `destroy` method.
+ * @modified 2022-02-02 Cleared the `Vertex.toSVGString` function (deprecated). Use `drawutilssvg` instead.
+ * @version  2.7.0
  *
  * @file Vertex
  * @public
@@ -103,6 +107,14 @@ export class Vertex implements XYCoords, SVGSerializable {
    **/
   listeners: VertexListeners;
 
+  /**
+   * @member isDestroyed
+   * @memberof Vertex
+   * @type {boolean}
+   * @instance
+   */
+  isDestroyed: boolean;
+
   /**
    * The constructor for the vertex class.
    *
@@ -421,6 +433,45 @@ export class Vertex implements XYCoords, SVGSerializable {
     return this.scaleXY({ x: factor, y: factor }, center);
   }
 
+  /**
+   * Perform a linear interpolation towards the given target vertex.
+   * The amount value `t` is relative, `t=0.0` means no change, `t=1.0`
+   * means this point will be moved to the exact target position.
+   *
+   * `t=0.5` will move this point to the middle of the connecting
+   * linear segment.
+   *
+   * @param {XYCoords} target - The target position to lerp this vertex to.
+   * @param {number} t - The relative amount, usually in [0..1], but other values will work, too.
+   * @returns
+   */
+  lerp(target: XYCoords, t: number): Vertex {
+    var diff = this.difference(target);
+    // return new Vertex(this.x + diff.x * t, this.y + diff.y * t);
+    this.x += diff.x * t;
+    this.y += diff.y * t;
+    return this;
+  }
+
+  /**
+   * Perform a linear interpolation towards the given target vertex (absolute variant).
+   * The amount value `t` is absolute, which means the lerp amount is a direct distance
+   * value. This point will have move the amount of the passed distance `u`.
+   *
+   * @param {XYCoords} target - The target position to lerp this vertex to.
+   * @param {number} t - The absolute move amount to use to lerping.
+   * @returns
+   */
+  lerpAbs(target: XYCoords, u: number): Vertex {
+    var dist = this.distance(target);
+    var diff = this.difference(target);
+    var step = { x: diff.x / dist, y: diff.y / dist };
+    // return new Vertex(this.x + step.x * u, this.y + step.y * u);
+    this.x += step.x * u;
+    this.y += step.y * u;
+    return this;
+  }
+
   /**
    * This is a vector-like behavior and 'scales' this vertex
    * towards/from a given center by two independent x- and y- scale factors.
@@ -524,27 +575,14 @@ export class Vertex implements XYCoords, SVGSerializable {
   }
 
   /**
-   * Convert this vertex to SVG code.
-   *
-   * @deprecated DEPRECATION Please use the drawutilssvg library and an XMLSerializer instead.
-   * @method toSVGString
-   * @param {object=} options - An optional set of options, like 'className'.
-   * @return {string} A string representing the SVG code for this vertex.
-   * @instance
-   * @memberof Vertex
-   **/
-  toSVGString(options: { className?: string }): string {
-    options = options || {};
-    var buffer = [];
-    buffer.push("<circle");
-    if (options.className) buffer.push(' class="' + options.className + '"');
-    buffer.push(' cx="' + this.x + '"');
-    buffer.push(' cy="' + this.y + '"');
-    buffer.push(' r="2"');
-    buffer.push(" />");
-    return buffer.join("");
+   * This function should invalidate any installed listeners and invalidate this object.
+   * After calling this function the object might not hold valid data any more and
+   * should not be used.
+   */
+  destroy() {
+    this.listeners.removeAllListeners();
+    this.isDestroyed = true;
   }
-  // END Vertex
 
   /**
    * Create a new random vertex inside the given viewport.
@@ -607,6 +645,22 @@ export class Vertex implements XYCoords, SVGSerializable {
       );
 
       return vertices;
+    },
+
+    /**
+     * Convert the given vertices (array) to a JSON string.
+     *
+     * @param {number?} precision - (optional) The numeric precision to be used (number of precision digits).
+     * @returns {string}
+     */
+    arrayToJSON(vertices: Array<XYCoords>, precision?: number) {
+      return JSON.stringify(
+        vertices.map(function (vert) {
+          return typeof precision === undefined
+            ? { x: vert.x, y: vert.y }
+            : { x: Number(vert.x.toFixed(precision)), y: Number(vert.y.toFixed(precision)) };
+        })
+      );
     }
   };
 }

package/src/ts/VertexListeners.ts

@@ -16,300 +16,282 @@ import { Vertex } from "./Vertex";
 import { XMouseParams, XMouseEvent } from "./MouseHandler";
 
 export interface VertEventParams extends XMouseParams {
-    vertex : Vertex;
+  vertex: Vertex;
 }
 
 export interface VertEvent {
-    params : VertEventParams;
+  params: VertEventParams;
 }
 
-export type VertListener = (e:VertEvent) => void;
-
+export type VertListener = (e: VertEvent) => void;
 
 /**
- * @classdesc An event listeners wrapper. This is just a set of three listener 
+ * @classdesc An event listeners wrapper. This is just a set of three listener
  *              queues (drag, dragStart, dragEnd) and their respective firing
  *              functions.
  *
  */
 export class VertexListeners {
+  private click: Array<VertListener>;
+  private drag: Array<VertListener>;
+  private dragStart: Array<VertListener>;
+  private dragEnd: Array<VertListener>;
 
-    private click:Array<VertListener>;
-    private drag:Array<VertListener>;
-    private dragStart:Array<VertListener>;
-    private dragEnd:Array<VertListener>;
-    
-    private vertex:Vertex;
-    
-    
-    /**
-     * The constructor.
-     *
-     * @constructor
-     * @name VertexListeners
-     * @param {Vertex} vertex - The vertex to use these listeners on (just a backward reference).
-     **/
-    constructor( vertex:Vertex ) {
-	this.click = [];
-	this.drag = [];
-	this.dragStart = [];
-	this.dragEnd = [];
-	this.vertex = vertex;
-    };
-
-
-    /**
-     * Add a click listener.
-     *
-     * @method addClickListener
-     * @param {VertexListeners~dragListener} listener - The click listener to add (a callback).
-     * @return {VertexListeners} this (for chaining)
-     * @instance
-     * @memberof VertexListeners
-     **/
-    addClickListener( listener:VertListener ) : VertexListeners {
-	VertexListeners._addListener( this.click, listener );
-	return this;
-    };
-    /**
-     * The click listener is a function with a single drag event param.
-     * @callback VertexListeners~clickListener
-     * @param {Event} e - The (extended) click event.
-     */
-    
+  private vertex: Vertex;
 
-    /**
-     * Remove a drag listener.
-     *
-     * @method removeDragListener
-     * @param {VertexListeners~dragListener} listener - The drag listener to remove (a callback).
-     * @return {VertexListeners} this (for chaining)
-     * @instance
-     * @memberof VertexListeners
-     **/
-    removeClickListener( listener:VertListener ) : VertexListeners {
-	this.click = VertexListeners._removeListener( this.click, listener );
-	return this;
-    };
-    /**
-     * The click listener is a function with a single drag event param.
-     * @callback VertexListeners~clickListener
-     * @param {Event} e - The (extended) click event.
-     */
-    
+  /**
+   * The constructor.
+   *
+   * @constructor
+   * @name VertexListeners
+   * @param {Vertex} vertex - The vertex to use these listeners on (just a backward reference).
+   **/
+  constructor(vertex: Vertex) {
+    this.click = [];
+    this.drag = [];
+    this.dragStart = [];
+    this.dragEnd = [];
+    this.vertex = vertex;
+  }
 
-    /**
-     * Add a drag listener.
-     *
-     * @method addDragListener
-     * @param {VertexListeners~dragListener} listener - The drag listener to add (a callback).
-     * @return {VertexListeners} this (for chaining)
-     * @instance
-     * @memberof VertexListeners
-     **/
-    addDragListener( listener:VertListener ) : VertexListeners {
-	VertexListeners._addListener( this.drag, listener );
-	return this;
-    };
-    /**
-     * The drag listener is a function with a single drag event param.
-     * @callback VertexListeners~dragListener
-     * @param {Event} e - The (extended) drag event.
-     */
-    
+  /**
+   * Add a click listener.
+   *
+   * @method addClickListener
+   * @param {VertexListeners~dragListener} listener - The click listener to add (a callback).
+   * @return {VertexListeners} this (for chaining)
+   * @instance
+   * @memberof VertexListeners
+   **/
+  addClickListener(listener: VertListener): VertexListeners {
+    VertexListeners._addListener(this.click, listener);
+    return this;
+  }
+  /**
+   * The click listener is a function with a single drag event param.
+   * @callback VertexListeners~clickListener
+   * @param {Event} e - The (extended) click event.
+   */
 
-    /**
-     * Remove a drag listener.
-     *
-     * @method removeDragListener
-     * @param {VertexListeners~dragListener} listener - The drag listener to remove (a callback).
-     * @return {VertexListeners} this (for chaining)
-     * @instance
-     * @memberof VertexListeners
-     **/
-    removeDragListener( listener:VertListener ) : VertexListeners {
-	this.drag = VertexListeners._removeListener( this.drag, listener );
-	return this;
-    };
-    
-    
-    /**
-     * Add a dragStart listener.
-     *
-     * @method addDragListener
-     * @param {VertexListeners~dragStartListener} listener - The drag-start listener to add (a callback).
-     * @return {VertexListeners} this (for chaining)
-     * @instance
-     * @memberof VertexListeners
-     **/
-    addDragStartListener( listener:VertListener) : VertexListeners {
-	VertexListeners._addListener( this.dragStart, listener );
-	return this;
-    };
-    /**
-     * The drag-start listener is a function with a single drag event param.
-     * @callback VertexListeners~dragStartListener
-     * @param {Event} e - The (extended) drag event.
-     */
+  /**
+   * Remove a drag listener.
+   *
+   * @method removeDragListener
+   * @param {VertexListeners~dragListener} listener - The drag listener to remove (a callback).
+   * @return {VertexListeners} this (for chaining)
+   * @instance
+   * @memberof VertexListeners
+   **/
+  removeClickListener(listener: VertListener): VertexListeners {
+    this.click = VertexListeners._removeListener(this.click, listener);
+    return this;
+  }
+  /**
+   * The click listener is a function with a single drag event param.
+   * @callback VertexListeners~clickListener
+   * @param {Event} e - The (extended) click event.
+   */
 
+  /**
+   * Add a drag listener.
+   *
+   * @method addDragListener
+   * @param {VertexListeners~dragListener} listener - The drag listener to add (a callback).
+   * @return {VertexListeners} this (for chaining)
+   * @instance
+   * @memberof VertexListeners
+   **/
+  addDragListener(listener: VertListener): VertexListeners {
+    VertexListeners._addListener(this.drag, listener);
+    return this;
+  }
+  /**
+   * The drag listener is a function with a single drag event param.
+   * @callback VertexListeners~dragListener
+   * @param {Event} e - The (extended) drag event.
+   */
 
-    /**
-     * Remove a dragStart listener.
-     *
-     * @method addDragStartListener
-     * @param {VertexListeners~dragListener} listener - The drag listener to remove (a callback).
-     * @return {VertexListeners} this (for chaining)
-     * @instance
-     * @memberof VertexListeners
-     **/
-    removeDragStartListener( listener:VertListener ) : VertexListeners {
-	this.dragStart= VertexListeners._removeListener( this.dragStart, listener );
-	return this;
-    };
-    
- 
-    /**
-     * Add a dragEnd listener.
-     *
-     * @method addDragListener
-     * @param {VertexListeners~dragEndListener} listener - The drag-end listener to add (a callback).
-     * @return {VertexListeners} this (for chaining)
-     * @instance
-     * @memberof VertexListeners
-     **/
-    addDragEndListener( listener:(e:VertEvent)=>void ) : VertexListeners {
-	// this.dragEnd.push( listener );
-	VertexListeners._addListener( this.dragEnd, listener );
-	return this;
-    };
-    /**
-     * The drag-end listener is a function with a single drag event param.
-     * @callback VertexListeners~dragEndListener
-     * @param {Event} e - The (extended) drag event.
-     */
+  /**
+   * Remove a drag listener.
+   *
+   * @method removeDragListener
+   * @param {VertexListeners~dragListener} listener - The drag listener to remove (a callback).
+   * @return {VertexListeners} this (for chaining)
+   * @instance
+   * @memberof VertexListeners
+   **/
+  removeDragListener(listener: VertListener): VertexListeners {
+    this.drag = VertexListeners._removeListener(this.drag, listener);
+    return this;
+  }
 
+  /**
+   * Add a dragStart listener.
+   *
+   * @method addDragListener
+   * @param {VertexListeners~dragStartListener} listener - The drag-start listener to add (a callback).
+   * @return {VertexListeners} this (for chaining)
+   * @instance
+   * @memberof VertexListeners
+   **/
+  addDragStartListener(listener: VertListener): VertexListeners {
+    VertexListeners._addListener(this.dragStart, listener);
+    return this;
+  }
+  /**
+   * The drag-start listener is a function with a single drag event param.
+   * @callback VertexListeners~dragStartListener
+   * @param {Event} e - The (extended) drag event.
+   */
 
-     /**
-     * Remove a drag listener.
-     *
-     * @method removeDragEndListener
-     * @param {VertexListeners~clickListener} listener - The drag listener to remove (a callback).
-     * @return {VertexListeners} this (for chaining)
-     * @instance
-     * @memberof VertexListeners
-     **/
-    removeDragEndListener( listener:(e:VertEvent)=>void ) : VertexListeners {
-	// this.drag.push( listener );
-	this.dragEnd = VertexListeners._removeListener( this.dragEnd, listener );
-	return this;
-    };
+  /**
+   * Remove a dragStart listener.
+   *
+   * @method addDragStartListener
+   * @param {VertexListeners~dragListener} listener - The drag listener to remove (a callback).
+   * @return {VertexListeners} this (for chaining)
+   * @instance
+   * @memberof VertexListeners
+   **/
+  removeDragStartListener(listener: VertListener): VertexListeners {
+    this.dragStart = VertexListeners._removeListener(this.dragStart, listener);
+    return this;
+  }
 
-    
-     
-    /**
-     * Fire a click event with the given event instance to all
-     * installed click listeners.
-     *
-     * @method fireClickEvent
-     * @param {VertEvent|XMouseEvent} e - The click event itself to be fired to all installed drag listeners.
-     * @return {void}
-     * @instance
-     * @memberof VertexListeners
-     **/
-    fireClickEvent( e:VertEvent|XMouseEvent ) {
-	VertexListeners._fireEvent(this,this.click,e);
-    };
+  /**
+   * Add a dragEnd listener.
+   *
+   * @method addDragListener
+   * @param {VertexListeners~dragEndListener} listener - The drag-end listener to add (a callback).
+   * @return {VertexListeners} this (for chaining)
+   * @instance
+   * @memberof VertexListeners
+   **/
+  addDragEndListener(listener: (e: VertEvent) => void): VertexListeners {
+    // this.dragEnd.push( listener );
+    VertexListeners._addListener(this.dragEnd, listener);
+    return this;
+  }
+  /**
+   * The drag-end listener is a function with a single drag event param.
+   * @callback VertexListeners~dragEndListener
+   * @param {Event} e - The (extended) drag event.
+   */
 
- 
-    /**
-     * Fire a drag event with the given event instance to all
-     * installed drag listeners.
-     *
-     * @method fireDragEvent
-     * @param {VertEvent|XMouseEvent} e - The drag event itself to be fired to all installed drag listeners.
-     * @return {void}
-     * @instance
-     * @memberof VertexListeners
-     **/
-    fireDragEvent( e:VertEvent|XMouseEvent ) {
-	VertexListeners._fireEvent(this,this.drag,e);
-    };
+  /**
+   * Remove a drag listener.
+   *
+   * @method removeDragEndListener
+   * @param {VertexListeners~clickListener} listener - The drag listener to remove (a callback).
+   * @return {VertexListeners} this (for chaining)
+   * @instance
+   * @memberof VertexListeners
+   **/
+  removeDragEndListener(listener: (e: VertEvent) => void): VertexListeners {
+    // this.drag.push( listener );
+    this.dragEnd = VertexListeners._removeListener(this.dragEnd, listener);
+    return this;
+  }
 
+  /**
+   * Fire a click event with the given event instance to all
+   * installed click listeners.
+   *
+   * @method fireClickEvent
+   * @param {VertEvent|XMouseEvent} e - The click event itself to be fired to all installed drag listeners.
+   * @return {void}
+   * @instance
+   * @memberof VertexListeners
+   **/
+  fireClickEvent(e: VertEvent | XMouseEvent) {
+    VertexListeners._fireEvent(this, this.click, e);
+  }
 
-    
-    /**
-     * Fire a dragStart event with the given event instance to all
-     * installed drag-start listeners.
-     *
-     * @method fireDragStartEvent
-     * @param {VertEvent|XMouseEvent} e - The drag-start event itself to be fired to all installed dragStart listeners.
-     * @return {void}
-     * @instance
-     * @memberof VertexListeners
-     **/
-    fireDragStartEvent( e:VertEvent|XMouseEvent ) {
-	VertexListeners._fireEvent(this,this.dragStart,e);
-    };
+  /**
+   * Fire a drag event with the given event instance to all
+   * installed drag listeners.
+   *
+   * @method fireDragEvent
+   * @param {VertEvent|XMouseEvent} e - The drag event itself to be fired to all installed drag listeners.
+   * @return {void}
+   * @instance
+   * @memberof VertexListeners
+   **/
+  fireDragEvent(e: VertEvent | XMouseEvent) {
+    VertexListeners._fireEvent(this, this.drag, e);
+  }
 
+  /**
+   * Fire a dragStart event with the given event instance to all
+   * installed drag-start listeners.
+   *
+   * @method fireDragStartEvent
+   * @param {VertEvent|XMouseEvent} e - The drag-start event itself to be fired to all installed dragStart listeners.
+   * @return {void}
+   * @instance
+   * @memberof VertexListeners
+   **/
+  fireDragStartEvent(e: VertEvent | XMouseEvent) {
+    VertexListeners._fireEvent(this, this.dragStart, e);
+  }
 
-    
-    /**
-     * Fire a dragEnd event with the given event instance to all
-     * installed drag-end listeners.
-     *
-     * @method fireDragEndEvent
-     * @param {VertEvent|XMouseEvent} e - The drag-end event itself to be fired to all installed dragEnd listeners.
-     * @return {void}
-     * @instance
-     * @memberof VertexListeners
-     **/
-    fireDragEndEvent( e:VertEvent|XMouseEvent ) {
-	VertexListeners._fireEvent(this,this.dragEnd,e);
-    };
+  /**
+   * Fire a dragEnd event with the given event instance to all
+   * installed drag-end listeners.
+   *
+   * @method fireDragEndEvent
+   * @param {VertEvent|XMouseEvent} e - The drag-end event itself to be fired to all installed dragEnd listeners.
+   * @return {void}
+   * @instance
+   * @memberof VertexListeners
+   **/
+  fireDragEndEvent(e: VertEvent | XMouseEvent) {
+    VertexListeners._fireEvent(this, this.dragEnd, e);
+  }
 
+  /**
+   * Removes all listeners from this listeners object.
+   */
+  removeAllListeners() {
+    this.click = [];
+    this.drag = [];
+    this.dragStart = [];
+    this.dragEnd = [];
+  }
 
-    
-    /**
-     * @private
-     **/
-    private static _fireEvent( _self:VertexListeners,
-			       listeners:Array<(e:VertEvent)=>void>,
-			       e:VertEvent|XMouseEvent
-			     ) : void {
-	const ve : VertEvent = (e as unknown) as VertEvent;
-	if( typeof ve.params == 'undefined' )
-	    ve.params = ({ vertex : _self.vertex } as unknown) as VertEventParams;
-	else
-	    ve.params.vertex = _self.vertex; 
-	for( var i in listeners ) {
-	    listeners[i]( ve );
-	}
-    };
+  /**
+   * @private
+   **/
+  private static _fireEvent(_self: VertexListeners, listeners: Array<(e: VertEvent) => void>, e: VertEvent | XMouseEvent): void {
+    const ve: VertEvent = e as unknown as VertEvent;
+    if (typeof ve.params == "undefined") ve.params = { vertex: _self.vertex } as unknown as VertEventParams;
+    else ve.params.vertex = _self.vertex;
+    for (var i in listeners) {
+      listeners[i](ve);
+    }
+  }
 
-    /**
-     * @private
-     */
-    private static _addListener( listeners:Array<(e:VertEvent)=>void>,
-				 newListener:(e:VertEvent)=>void
-			       ) : boolean {
-	for( var i in listeners ) {
-	    if( listeners[i] == newListener )
-		return false;
-	}
-	listeners.push( newListener );
-	return true;
-    };
+  /**
+   * @private
+   */
+  private static _addListener(listeners: Array<(e: VertEvent) => void>, newListener: (e: VertEvent) => void): boolean {
+    for (var i in listeners) {
+      if (listeners[i] == newListener) return false;
+    }
+    listeners.push(newListener);
+    return true;
+  }
 
-    /**
-     * @private
-     */
-    private static _removeListener( listeners:Array<(e:VertEvent)=>void>,
-				    oldListener:(e:VertEvent)=>void
-			       ) : Array<(e:VertEvent)=>void> {
-	for( var i = 0; i < listeners.length; i++ ) {
-	    if( listeners[i] == oldListener )
-		return listeners.splice( i, 1 );
-	}
-	return listeners;
-    };
+  /**
+   * @private
+   */
+  private static _removeListener(
+    listeners: Array<(e: VertEvent) => void>,
+    oldListener: (e: VertEvent) => void
+  ): Array<(e: VertEvent) => void> {
+    for (var i = 0; i < listeners.length; i++) {
+      if (listeners[i] == oldListener) return listeners.splice(i, 1);
+    }
+    return listeners;
+  }
 }