plotboilerplate 1.20.1 → 1.21.0

package/src/ts/interfaces/DrawLib.ts

@@ -18,6 +18,13 @@
  * @modified 2022-02-03 Added the `lineWidth` param to the `crosshair` function.
  * @modified 2022-02-03 Added the `cross(...)` function.
  * @modified 2022-07-26 Adding `alpha` to the `image(...)` function.
+ * @modified 2023-02-10 The methods `setCurrentClassName` and `setCurrentId` also accept `null` now.
+ * @modified 2023-09-29 Downgrading all `Vertex` param type to the more generic `XYCoords` type in these render functions: line, arrow, texturedPoly, cubicBezier, cubicBezierPath, handle, handleLine, dot, point, circle, circleArc, ellipse, grid, raster.
+ * @modified 2023-09-29 Added the `headLength` parameter to the 'DrawLib.arrow()` function.
+ * @modified 2023-09-29 Added the `arrowHead(...)` function to the 'DrawLib.arrow()` interface.
+ * @modified 2023-09-29 Added the `cubicBezierArrow(...)` function to the 'DrawLib.arrow()` interface.
+ * @modified 2023-09-29 Added the `lineDashes` attribute.
+ * @modified 2023-09-30 Adding `strokeOptions` param to these draw function: line, arrow, cubicBezierArrow, cubicBezier, cubicBezierPath, circle, circleArc, ellipse, square, rect, polygon, polyline.
  **/
 
 import { Bounds } from "../Bounds";
@@ -49,6 +56,20 @@ export interface FontOptions {
   rotation?: number;
 }
 
+/**
+ * Defines a line-dash configuration.
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-dasharray
+ * and https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash
+ * for how line dashes work.
+ *
+ * Setting line-dash to empty array `[]` resets the dashing.
+ */
+export interface StrokeOptions {
+  dashOffset?: number;
+  dashArray?: Array<number>;
+}
+
 /**
  * An interface all drawing libraries must implement to be used with PlotBoilerplate.
  *
@@ -71,6 +92,21 @@ export interface DrawLib<R> {
    */
   setConfiguration: (configuration: DrawLibConfiguration) => void;
 
+  // /**
+  //  * Set or clear the line-dash configuration. Pass `null` for un-dashed lines.
+  //  *
+  //  * See https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-dasharray
+  //  * and https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash
+  //  * for how line dashes work.
+  //  *
+  //  * Setting line-dash to empty array `[]` resets the dashing.
+  //  *
+  //  * @method
+  //  * @param {Array<number> lineDashes - The line-dash array configuration.
+  //  * @returns {void}
+  //  */
+  // setLineDash: (lineDashes: Array<number>) => void;
+
   /**
    * This method shouled be called each time the currently drawn `Drawable` changes.
    * It is used by some libraries for identifying elemente on re-renders.
@@ -79,7 +115,7 @@ export interface DrawLib<R> {
    * @method
    * @param {UID|null} uid - A UID identifying the currently drawn element(s), or null to clear.
    **/
-  setCurrentId: (uid: UID | undefined) => void;
+  setCurrentId: (uid: UID | null) => void;
 
   /**
    * This method shouled be called each time the currently drawn `Drawable` changes.
@@ -87,9 +123,9 @@ export interface DrawLib<R> {
    *
    * @name setCurrentClassName
    * @method
-   * @param {string} className - A class name for further custom use cases.
+   * @param {string|null} className - A class name for further custom use cases.
    **/
-  setCurrentClassName: (className: string | undefined) => void;
+  setCurrentClassName: (className: string | null) => void;
 
   /**
    * Called before each draw cycle.
@@ -119,29 +155,84 @@ export interface DrawLib<R> {
    * Draw the line between the given two points with the specified (CSS-) color.
    *
    * @method line
-   * @param {Vertex} zA - The start point of the line.
-   * @param {Vertex} zB - The end point of the line.
+   * @param {XYCoords} zA - The start point of the line.
+   * @param {XYCoords} zB - The end point of the line.
    * @param {string} color - Any valid CSS color string.
-   * @param {number=1} lineWidth? - [optional] The line's width.
-   * @return {void}
+   * @param {number=1} lineWidth? - (optional) The line's width.
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   * @return {R}
    * @instance
    * @memberof DrawLib
    **/
-  line: (zA: Vertex, zB: Vertex, color: string, lineWidth?: number) => R;
+  line: (zA: XYCoords, zB: XYCoords, color: string, lineWidth?: number, strokeOptopns?: StrokeOptions) => R;
 
   /**
-   * Draw a line and an arrow at the end (zB) of the given line with the specified (CSS-) color.
+   * Draw a line and an arrow at the end (zB) of the given line width the specified (CSS-) color and size.
    *
    * @method arrow
-   * @param {Vertex} zA - The start point of the arrow-line.
-   * @param {Vertex} zB - The end point of the arrow-line.
+   * @param {XYCoords} zA - The start point of the arrow-line.
+   * @param {XYCoords} zB - The end point of the arrow-line.
    * @param {string} color - Any valid CSS color string.
-   * @param {number=} lineWidth - (optional) The line width to use; default is 1.
-   * @return {void}
+   * @param {number=1} lineWidth - (optional) The line width to use; default is 1.
+   * @param {headLength=8} headLength - (optional) The length of the arrow head (default is 8 units).
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   * @return {R}
    * @instance
    * @memberof DrawLib
    **/
-  arrow: (zA: Vertex, zB: Vertex, color: string, lineWidth?: number) => R;
+  arrow: (zA: XYCoords, zB: XYCoords, color: string, lineWidth?: number, headLength?: number, strokeOptopns?: StrokeOptions) => R;
+
+  /**
+   * Draw a cubic Bézier curve and and an arrow at the end (endControlPoint) of the given line width the specified (CSS-) color and arrow size.
+   *
+   * @method cubicBezierArrow
+   * @param {XYCoords} startPoint - The start point of the cubic Bézier curve
+   * @param {XYCoords} endPoint   - The end point the cubic Bézier curve.
+   * @param {XYCoords} startControlPoint - The start control point the cubic Bézier curve.
+   * @param {XYCoords} endControlPoint   - The end control point the cubic Bézier curve.
+   * @param {string} color - The CSS color to draw the curve with.
+   * @param {number} lineWidth - (optional) The line width to use.
+   * @param {headLength=8} headLength - (optional) The length of the arrow head (default is 8 units).
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
+   * @return {R}
+   * @instance
+   * @memberof DrawLib
+   */
+  cubicBezierArrow: (
+    startPoint: XYCoords,
+    endPoint: XYCoords,
+    startControlPoint: XYCoords,
+    endControlPoint: XYCoords,
+    color: string,
+    lineWidth?: number,
+    headLength?: number,
+    strokeOptopns?: StrokeOptions
+  ) => R;
+
+  /**
+   * Draw just an arrow head a the end of an imaginary line (zB) of the given line width the specified (CSS-) color and size.
+   *
+   * @method arrow
+   * @param {XYCoords} zA - The start point of the arrow-line.
+   * @param {XYCoords} zB - The end point of the arrow-line.
+   * @param {string} color - Any valid CSS color string.
+   * @param {number=1} lineWidth - (optional) The line width to use; default is 1.
+   * @param {number=8} headLength - (optional) The length of the arrow head (default is 8 pixels).
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
+   * @return {R}
+   * @instance
+   * @memberof DrawLib
+   **/
+  arrowHead: (
+    zA: XYCoords,
+    zB: XYCoords,
+    color: string,
+    lineWidth?: number,
+    headLength?: number,
+    strokeOptopns?: StrokeOptions
+  ) => R;
 
   /**
    * Draw an image at the given position with the given size.<br>
@@ -150,14 +241,14 @@ export interface DrawLib<R> {
    *
    * @method image
    * @param {Image} image - The image object to draw.
-   * @param {Vertex} position - The position to draw the the upper left corner at.
-   * @param {Vertex} size - The x/y-size to draw the image with.
+   * @param {XYCoords} position - The position to draw the the upper left corner at.
+   * @param {XYCoords} size - The x/y-size to draw the image with.
    * @param {number=1.0} alpha - (optional, default=0.0) The transparency (1.0=opaque, 0.0=transparent).
-   * @return {void}
+   * @return {R}
    * @instance
    * @memberof DrawLib
    **/
-  image: (image: HTMLImageElement, position: Vertex, size: Vertex, alpha?: number) => R;
+  image: (image: HTMLImageElement, position: XYCoords, size: XYCoords, alpha?: number) => R;
 
   /**
    * Draw an image at the given position with the given size.<br>
@@ -168,7 +259,7 @@ export interface DrawLib<R> {
    * @param {Image} textureImage - The image object to draw.
    * @param {Bounds} textureSize - The texture size to use; these are the original bounds to map the polygon vertices to.
    * @param {Polygon} polygon - The polygon to use as clip path.
-   * @param {Vertex} polygonPosition - The polygon's position (relative), measured at the bounding box's center.
+   * @param {XYCoords} polygonPosition - The polygon's position (relative), measured at the bounding box's center.
    * @param {number} rotation - The rotation to use for the polygon (and for the texture).
    * @return {void}
    * @instance
@@ -178,7 +269,7 @@ export interface DrawLib<R> {
     textureImage: HTMLImageElement,
     textureSize: Bounds,
     polygon: Polygon,
-    polygonPosition: Vertex,
+    polygonPosition: XYCoords,
     rotation: number
   ) => R;
 
@@ -186,23 +277,26 @@ export interface DrawLib<R> {
    * Draw the given (cubic) bézier curve.
    *
    * @method cubicBezier
-   * @param {Vertex} startPoint - The start point of the cubic Bézier curve
-   * @param {Vertex} endPoint   - The end point the cubic Bézier curve.
-   * @param {Vertex} startControlPoint - The start control point the cubic Bézier curve.
-   * @param {Vertex} endControlPoint   - The end control point the cubic Bézier curve.
+   * @param {XYCoords} startPoint - The start point of the cubic Bézier curve
+   * @param {XYCoords} endPoint   - The end point the cubic Bézier curve.
+   * @param {XYCoords} startControlPoint - The start control point the cubic Bézier curve.
+   * @param {XYCoords} endControlPoint   - The end control point the cubic Bézier curve.
    * @param {string} color - The CSS color to draw the curve with.
    * @param {number} lineWidth - (optional) The line width to use.
-   * @return {void}
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
   cubicBezier: (
-    startPoint: Vertex,
-    endPoint: Vertex,
-    startControlPoint: Vertex,
-    endControlPoint: Vertex,
+    startPoint: XYCoords,
+    endPoint: XYCoords,
+    startControlPoint: XYCoords,
+    endControlPoint: XYCoords,
     color: string,
-    lineWidth?: number
+    lineWidth?: number,
+    strokeOptopns?: StrokeOptions
   ) => R;
 
   /**
@@ -213,14 +307,16 @@ export interface DrawLib<R> {
    * <pre> [ point1, point1_startControl, point2_endControl, point2, point2_startControl, point3_endControl, point3, ... pointN_endControl, pointN ]</pre>
    *
    * @method cubicBezierPath
-   * @param {Vertex[]} path - The cubic bezier path as described above.
+   * @param {XYCoords[]} path - The cubic bezier path as described above.
    * @param {string} color - The CSS colot to draw the path with.
    * @param {number=1} lineWidth - (optional) The line width to use.
-   * @return {void}
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
-  cubicBezierPath: (path: Array<Vertex>, color: string, lineWidth?: number) => R;
+  cubicBezierPath: (path: Array<XYCoords>, color: string, lineWidth?: number, strokeOptopns?: StrokeOptions) => R;
 
   /**
    * Draw the given handle and handle point (used to draw interactive Bézier curves).
@@ -228,49 +324,49 @@ export interface DrawLib<R> {
    * The colors for this are fixed and cannot be specified.
    *
    * @method handle
-   * @param {Vertex} startPoint - The start of the handle.
-   * @param {Vertex} endPoint - The end point of the handle.
-   * @return {void}
+   * @param {XYCoords} startPoint - The start of the handle.
+   * @param {XYCoords} endPoint - The end point of the handle.
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
-  handle: (startPoint: Vertex, endPoint: Vertex) => R;
+  handle: (startPoint: XYCoords, endPoint: XYCoords) => R;
 
   /**
    * Draw a handle line (with a light grey).
    *
    * @method handleLine
-   * @param {Vertex} startPoint - The start point to draw the handle at.
-   * @param {Vertex} endPoint - The end point to draw the handle at.
-   * @return {void}
+   * @param {XYCoords} startPoint - The start point to draw the handle at.
+   * @param {XYCoords} endPoint - The end point to draw the handle at.
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
-  handleLine: (startPoint: Vertex, endPoint: Vertex) => R;
+  handleLine: (startPoint: XYCoords, endPoint: XYCoords) => R;
 
   /**
    * Draw a 1x1 dot with the specified (CSS-) color.
    *
    * @method dot
-   * @param {Vertex} p - The position to draw the dot at.
+   * @param {XYCoords} p - The position to draw the dot at.
    * @param {string} color - The CSS color to draw the dot with.
-   * @return {void}
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
-  dot: (p: Vertex, color: string) => R;
+  dot: (p: XYCoords, color: string) => R;
 
   /**
    * Draw the given point with the specified (CSS-) color and radius 3.
    *
    * @method point
-   * @param {Vertex} p - The position to draw the point at.
-   * @param {string} color - The CSS color to draw the point with.
-   * @return {void}
+   * @param {XYCoords} p - The position to draw the point at.
+   * @param {XYCoords} color - The CSS color to draw the point with.
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
-  point: (p: Vertex, color: string) => R;
+  point: (p: XYCoords, color: string) => R;
 
   /**
    * Draw a circle with the specified (CSS-) color and radius.<br>
@@ -278,47 +374,69 @@ export interface DrawLib<R> {
    * Note that if the x- and y- scales are different the result will be an ellipse rather than a circle.
    *
    * @method circle
-   * @param {Vertex} center - The center of the circle.
+   * @param {XYCoords} center - The center of the circle.
    * @param {number} radius - The radius of the circle.
    * @param {string} color - The CSS color to draw the circle with.
    * @param {number=} lineWidth - (optional) The line width to use; default is 1.
-   * @return {void}
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
-  circle: (center: Vertex, radius: number, color: string, lineWidth?: number) => R;
+  circle: (center: XYCoords, radius: number, color: string, lineWidth?: number, strokeOptions?: StrokeOptions) => R;
 
   /**
    * Draw a circular arc (section of a circle) with the given CSS color.
    *
    * @method circleArc
-   * @param {Vertex} center - The center of the circle.
+   * @param {XYCoords} center - The center of the circle.
    * @param {number} radius - The radius of the circle.
    * @param {number} startAngle - The angle to start at.
    * @param {number} endAngle - The angle to end at.
    * @param {string} color - The CSS color to draw the circle with.
    * @param {number=} lineWidth - (optional) The line width to use; default is 1.
-   * @return {void}
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
-  circleArc: (center: Vertex, radius: number, startAngle: number, endAngle: number, color: string, lineWidth?: number) => R;
+  circleArc: (
+    center: XYCoords,
+    radius: number,
+    startAngle: number,
+    endAngle: number,
+    color: string,
+    lineWidth?: number,
+    strokeOptions?: StrokeOptions
+  ) => R;
 
   /**
    * Draw an ellipse with the specified (CSS-) color and thw two radii.
    *
    * @method ellipse
-   * @param {Vertex} center - The center of the ellipse.
+   * @param {XYCoords} center - The center of the ellipse.
    * @param {number} radiusX - The radius of the ellipse.
    * @param {number} radiusY - The radius of the ellipse.
    * @param {string} color - The CSS color to draw the ellipse with.
    * @param {number=} lineWidth - (optional) The line width to use; default is 1.
    * @param {number=} rotation - (optional, default=0) The rotation of the ellipse.
-   * @return {void}
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
-  ellipse: (center: Vertex, radiusX: number, radiusY: number, color: string, lineWidth?: number, rotation?: number) => R;
+  ellipse: (
+    center: XYCoords,
+    radiusX: number,
+    radiusY: number,
+    color: string,
+    lineWidth?: number,
+    rotation?: number,
+    strokeOptions?: StrokeOptions
+  ) => R;
 
   /**
    * Draw square at the given center, size and with the specified (CSS-) color.<br>
@@ -330,11 +448,13 @@ export interface DrawLib<R> {
    * @param {number} size - The size of the square.
    * @param {string} color - The CSS color to draw the square with.
    * @param {number=} lineWidth - (optional) The line width to use; default is 1.
-   * @return {void}
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
-  square: (center: XYCoords, size: number, color: string, lineWidth?: number) => R;
+  square: (center: XYCoords, size: number, color: string, lineWidth?: number, strokeOptions?: StrokeOptions) => R;
 
   /**
    * Draw a rectangle at the given left upper corner, with, height; and with the specified line width and (CSS-) color.<br>
@@ -345,27 +465,36 @@ export interface DrawLib<R> {
    * @param {number} height - The height of the rectangle.
    * @param {string} color - The CSS color to draw the rectangle with.
    * @param {number=} lineWidth - (optional) The line width to use; default is 1.
-   * @return {void}
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
-  rect: (upperLeft: XYCoords, width: number, height: number, color: string, lineWidth?: number) => R;
+  rect: (
+    upperLeft: XYCoords,
+    width: number,
+    height: number,
+    color: string,
+    lineWidth?: number,
+    strokeOptions?: StrokeOptions
+  ) => R;
 
   /**
    * Draw a grid of horizontal and vertical lines with the given (CSS-) color.
    *
    * @method grid
-   * @param {Vertex} center - The center of the grid.
+   * @param {XYCoords} center - The center of the grid.
    * @param {number} width - The total width of the grid (width/2 each to the left and to the right).
    * @param {number} height - The total height of the grid (height/2 each to the top and to the bottom).
    * @param {number} sizeX - The horizontal grid size.
    * @param {number} sizeY - The vertical grid size.
    * @param {string} color - The CSS color to draw the grid with.
-   * @return {void}
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
-  grid: (center: Vertex, width: number, height: number, sizeX: number, sizeY: number, color: string) => R;
+  grid: (center: XYCoords, width: number, height: number, sizeX: number, sizeY: number, color: string) => R;
 
   /**
    * Draw a raster of crosshairs in the given grid.<br>
@@ -373,17 +502,17 @@ export interface DrawLib<R> {
    * This works analogue to the grid() function
    *
    * @method raster
-   * @param {Vertex} center - The center of the raster.
+   * @param {XYCoords} center - The center of the raster.
    * @param {number} width - The total width of the raster (width/2 each to the left and to the right).
    * @param {number} height - The total height of the raster (height/2 each to the top and to the bottom).
    * @param {number} sizeX - The horizontal raster size.
    * @param {number} sizeY - The vertical raster size.
    * @param {string} color - The CSS color to draw the raster with.
-   * @return {void}
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
-  raster: (center: Vertex, width: number, height: number, sizeX: number, sizeY: number, color: string) => R;
+  raster: (center: XYCoords, width: number, height: number, sizeX: number, sizeY: number, color: string) => R;
 
   /**
    * Draw a diamond handle (square rotated by 45°) with the given CSS color.
@@ -393,14 +522,14 @@ export interface DrawLib<R> {
    * as even shaped diamonds.
    *
    * @method diamondHandle
-   * @param {Vertex} center - The center of the diamond.
-   * @param {Vertex} size - The x/y-size of the diamond.
+   * @param {XYCoords} center - The center of the diamond.
+   * @param {number} size - The x/y-size of the diamond.
    * @param {string} color - The CSS color to draw the diamond with.
-   * @return {void}
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
-  diamondHandle: (center: Vertex, size: number, color: string) => R;
+  diamondHandle: (center: XYCoords, size: number, color: string) => R;
 
   /**
    * Draw a square handle with the given CSS color.<br>
@@ -410,14 +539,14 @@ export interface DrawLib<R> {
    * as even shaped squares.
    *
    * @method squareHandle
-   * @param {Vertex} center - The center of the square.
-   * @param {Vertex} size - The x/y-size of the square.
+   * @param {XYCoords} center - The center of the square.
+   * @param {number} size - The x/y-size of the square.
    * @param {string} color - The CSS color to draw the square with.
-   * @return {void}
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
-  squareHandle: (center: Vertex, size: number, color: string) => R;
+  squareHandle: (center: XYCoords, size: number, color: string) => R;
 
   /**
    * Draw a circle handle with the given CSS color.<br>
@@ -427,14 +556,14 @@ export interface DrawLib<R> {
    * as even shaped circles.
    *
    * @method circleHandle
-   * @param {Vertex} center - The center of the circle.
+   * @param {XYCoords} center - The center of the circle.
    * @param {number} radius - The radius of the circle.
    * @param {string} color - The CSS color to draw the circle with.
-   * @return {void}
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
-  circleHandle: (center: Vertex, size: number, color: string) => R;
+  circleHandle: (center: XYCoords, size: number, color: string) => R;
 
   /**
    * Draw a crosshair with given radius and color at the given position.<br>
@@ -446,7 +575,7 @@ export interface DrawLib<R> {
    * @param {number} radius - The radius of the crosshair.
    * @param {string} color - The CSS color to draw the crosshair with.
    * @param {number=0.5} lineWidth - (optional, default=0.5) The line width to use.
-   * @return {void}
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
@@ -462,7 +591,7 @@ export interface DrawLib<R> {
    * @param {number} radius - The radius of the crosshair.
    * @param {string} color - The CSS color to draw the crosshair with.
    * @param {number=1} lineWidth - (optional, default=1.0) The line width to use.
-   * @return {void}
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
@@ -474,25 +603,30 @@ export interface DrawLib<R> {
    * @method polygon
    * @param {Polygon} polygon - The polygon to draw.
    * @param {string} color - The CSS color to draw the polygon with.
-   * @return {void}
+   * @param {number=} lineWidth - The line width to draw this polygon with.
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
-  polygon: (polygon: Polygon, color: string, lineWidth?: number) => R;
+  polygon: (polygon: Polygon, color: string, lineWidth?: number, strokeOptions?: StrokeOptions) => R;
 
   /**
    * Draw a polygon line (alternative function to the polygon).
    *
    * @method polyline
-   * @param {Vertex[]} vertices - The polygon vertices to draw.
+   * @param {XYCoords[]} vertices - The polygon vertices to draw.
    * @param {boolan}   isOpen   - If true the polyline will not be closed at its end.
    * @param {string}   color    - The CSS color to draw the polygon with.
    * @param {number=} lineWidth - (optional) The line width to use; default is 1.
-   * @return {void}
+   * @param {StrokeOptions=} strokeOptions - (optional) Stroke settings to use.
+   *
+   * @return {R}
    * @instance
    * @memberof DrawLib
    */
-  polyline: (vertices: Array<Vertex>, isOpen: boolean, color: string, lineWidth?: number) => R;
+  polyline: (vertices: Array<XYCoords>, isOpen: boolean, color: string, lineWidth?: number, strokeOptions?: StrokeOptions) => R;
 
   /**
    * Draw a text at the given relative position.
@@ -538,11 +672,14 @@ export interface DrawLib<R> {
    * @param {string=null} color - (optional) The color to draw this path with (default is null).
    * @param {number=1} lineWidth - (optional) the line width to use (default is 1).
    * @param {boolean=false} options.inplace - (optional) If set to true then path transforamtions (scale and translate) will be done in-place in the array. This can boost the performance.
+   * @param {number=} options.dashOffset - See `StrokeOptions`.
+   * @param {number[]=} options.dashArray - See `StrokeOptions`.
+   *
    * @instance
    * @memberof DrawLib
    * @return {R} An instance representing the drawn path.
    */
-  path: (pathData: SVGPathParams, color?: string, lineWidth?: number, options?: { inplace?: boolean }) => R;
+  path: (pathData: SVGPathParams, color?: string, lineWidth?: number, options?: { inplace?: boolean } & StrokeOptions) => R;
 
   /**
    * Due to gl compatibility there is a generic 'clear' function required