figureone 0.15.10 → 1.0.0

package/types/js/figure/FigureCollections/PolyLine.d.ts

@@ -0,0 +1,487 @@
+import { Point, RangeBounds, RectBounds } from '../../tools/g2';
+import type { OBJ_RangeBounds, OBJ_RectBounds } from '../../tools/geometry/Bounds';
+import type { OBJ_Font } from '../../tools/types';
+import { FigureElementCollection, FigureElementPrimitive } from '../Element';
+import type { COL_Line } from './Line';
+import type { COL_Angle } from './Angle';
+import type FigureCollections from './FigureCollections';
+import type { OBJ_Collection } from '../FigurePrimitives/FigurePrimitiveTypes';
+import type { OBJ_Polyline, OBJ_Polygon } from '../FigurePrimitives/FigurePrimitiveTypes2D';
+/**
+ * Collections Polyline pad addition options.
+ *
+ * Each pad is associated with a point of the polyline.
+ *
+ * @extends OBJ_Polygon
+ *
+ * @property {boolean} [isMovable] `true` allows moving the pad and the
+ * associated polyline point (`false`)
+ * @property {OBJ_RangeBounds | OBJ_RectBounds | RangeBounds | RectBounds | 'figure'} [boundary]
+ * boundary the pad can move within
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_PolylinePadSingle = {
+    isMovable?: boolean;
+    boundary?: OBJ_RangeBounds | OBJ_RectBounds | RangeBounds | RectBounds | 'figure';
+};
+/**
+  * @extends OBJ_PolylinePadSingle
+  * @extends OBJ_PolylineCustomization
+ * @group Misc Shapes
+ */
+export type OBJ_PolylinePad = {};
+/**
+ * Polyline side, angle and pad customization options object
+ *
+ * ![](./apiassets/polylinecustomization_ex1.png)
+ *
+ * ![](./apiassets/polylinecustomization_ex2.png)
+ *
+ * Side annotations, angle annotations and movable pads in an
+ * {@link CollectionsPolyline} are defined with the options objects {@link COL_Line},
+ * {@link COL_Angle} and ({@link OBJ_Polygon} & {@link OBJ_PolylinePadSingle})
+ * respectively.
+ *
+ * The properties in this object can be used in the side, angle and movable
+ * pad object definitions to allow for customization of specific sides,
+ * angles and movable pads.
+ *
+ * Each side, angle and movable pad has an 0 based index associated with it.
+ * The zero index pad is associated with the first point of the polyline. The
+ * zero index side is between the first and second point of the polyline, and
+ * the zero index angle is between the first, second and third point of the
+ * polyline.
+ *
+ * By default, any properties defined for <a href="adv_polyline#pad">pad</a>
+ * will be applied to all pads of the polyline. To customize the first pad in
+ * the polyline, an object property with name `'0'` can be used with a value
+ * that includes the options object properties that should be customized.
+ * Similary, for side and angle annotations, keys with the index name can be
+ * used in their options objects to customize specific sides and angles.
+ *
+ * The `show` and `hide` properties can be used to show and hide specific sides
+ * and angles.
+ *
+ * See {@link OBJ_PulseWidthAnimationStep} for pulse angle animation step
+ * options.
+ *
+ * @property {Array<number>} [show] list of indexes to show
+ * @property {Array<number>} [hide] list of indexes to hide
+ * @property {COL_Angle | COL_Line | OBJ_PolylinePadSingle} [_index]
+ * Customizations of annotation or pad by index where `_index` should be an
+ * object key name that is the index
+ *
+ * @example
+ * // Hide pad 0, and make pad 2 blue and not filled
+ * figure.add({
+ *   name: 'p',
+ *   make: 'collections.polyline',
+ *   points: [[0, 0], [2, 0], [2, 2], [-2, 1]],
+ *   pad: {
+ *     radius: 0.2,            // OBJ_Polygon
+ *     color: [1, 0, 0, 1],    // OBJ_Polygon
+ *     touchBorder: 0.1,       // OBJ_Polygon
+ *     isMovable: true,
+ *     hide: [0],
+ *     2: {                    // Custom pad 2 properties
+ *       color: [0, 0, 1, 1],  // Make blue
+ *       line: { width: 0.01 } // Use an outline instead of a fill
+ *     },
+ *   }
+ * });
+ *
+ * @example
+ * // Customization of side and angle annotations
+ * figure.add({
+ *   name: 'p',
+ *   make: 'collections.polyline',
+ *   points: [[0, 0], [1, 0], [1, 1], [0, 1]],
+ *   close: true,
+ *   side: {
+ *     showLine: false,
+ *     label: {
+ *       text: null,                 // By default, sides are length values
+ *       location: 'negative',
+ *     },
+ *     0: { label: { text: 'a' } },  // Side 0 is 'a' instead of length
+ *   },
+ *   angle: {
+ *     label: {
+ *       text: '?',
+ *       offset: 0.05,
+ *     },
+ *     curve: {
+ *       radius: 0.25,
+ *     },
+ *     direction: 'negative',
+ *     show: [2],                   // Only show angle annotation for angle 2
+ *   },
+ * });
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_PolylineCustomization = {
+    show?: Array<number>;
+    hide?: Array<number>;
+    _padIndex: OBJ_Polygon;
+};
+/**
+ * When shapes get too small, angle and side annotations can start to draw on
+ * each other. This object defines thresholds for when the angle and side
+ * annotations should be hidden.
+ *
+ * @property {null | number} [minAngle]
+ * @property {null | number} [maxAngle]
+ * @property {null | number} [minSide]
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_ValidShapeHideThresholds = {
+    minAngle?: number | null | undefined;
+    maxAngle?: number | null | undefined;
+    minSide?: number | null | undefined;
+};
+/**
+ * Makes the sides and angles of a closed polyline consistent. Also reverses
+ * the point order if angles are on outside of shape instead of inside.
+ *
+ * Floating point rounding errors will sometimes result in angles
+ * and side lengths being slightly larger or smaller than is possible.
+ * For instance, for a triangle, there may be a rare case where the three
+ * angles add up to 181ª instead of 180ª as a result of rounding the angle
+ * labels to no decimal places.
+ *
+ * Making a shape consistent will go through all the side and angle labels
+ * and correct them, displaying a value without rounding error.
+ *
+ * Currently, only `'triangle'` is supported.
+ *
+ * In addition, the angle and side annotations can be hidden if minimum
+ * or maximum thresholds of angle and side values are crossed. For example,
+ * for small triangles angle annotations may start to draw on top of each other
+ * being messy.
+ *
+ * @property {'triangle'} [shape]
+ * @property {OBJ_ValidShapeHideThresholds} [hide]
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_ValidShape = {
+    shape?: 'triangle';
+    hide?: OBJ_ValidShapeHideThresholds;
+};
+/**
+ * @extends COL_Angle
+ * @extends OBJ_PolylineCustomization
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_PolylineAngle = {};
+/**
+ * @extends COL_Line
+ * @extends OBJ_PolylineCustomization
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_PolylineSide = {};
+/**
+ * {@link CollectionsPolyline} options object that extends
+ * {@link OBJ_Polyline} and {@link OBJ_Collection}
+ * options object (without `parent`).
+ *
+ * The Collections Polyline is a convient and powerful polyline
+ * {@link FigureElementCollection} that includes the polyline,
+ * angle annotations, side label and arrow annotations, and movable
+ * pads on each polyline point for the user to adjust dynamically.
+ *
+ * The polyline itself is defined with an {@link OBJ_Polyline} options Object.
+ *
+ * Angle and side annotations can be defined as {@link COL_Angle} and
+ * {@link COL_Line}, and movable pads defined with
+ * ({@link OBJ_Polygon} & {@link OBJ_PolylinePad}).
+ *
+ * Angles, sides and pads can all be defined either as an options object
+ * or an array of options objects. If an array, then each element in the
+ * array will correspond with a pad on the polyline. If there are less
+ * elements in the array than pads on the polyline, then the elements
+ * will recycle from the start.
+ *
+ * Using object definitions allows for a definition of all angles, sides and
+ * pads. To customize for specific side, angle or pad indexes use =
+ * {@link OBJ_PolylineCustomization}.
+ *
+ * @extends OBJ_Polyline
+ * @extends OBJ_Collection
+ *
+ * @property {boolean} [showLine] `false` will hide the polyline's line (`true`)
+ * @property {OBJ_PolylineAngle | Array<COL_Angle>} [angle] angle annotations - leave undefined for no angle annotations
+ * @property {OBJ_PolylineSide | Array<COL_Line>} [side]
+ * side annotations - leave undefined for no side annotations
+ * @property {OBJ_PolylinePad | Array<OBJ_PolylinePadSingle>} [pad]
+ * move pad - leave undefined for no move pads
+ * @property {null | OBJ_ValidShape} [makeValid] if defined, whenever
+ * points are updated the shape will be checked to ensure consistency with
+ * displayed labels of angles and sides.
+ * @property {OBJ_Font} [font] default font to use for labels
+ * @interface
+ * @group 2D Shape Collections
+ */
+export type COL_Polyline = {
+    showLine?: boolean;
+    angle?: OBJ_PolylineAngle | Array<COL_Angle>;
+    side?: OBJ_PolylineSide | Array<COL_Line>;
+    pad?: OBJ_PolylinePad | Array<OBJ_PolylinePadSingle>;
+    makeValid?: OBJ_ValidShape | null | undefined;
+    font?: OBJ_Font;
+} & OBJ_Polyline & OBJ_Collection;
+/**
+ * `'updatePoints'` subscription published whenever the Collections Polyline
+ * points are updated. No payload is passed to subscriber.
+ *
+ * @typedef SUB_PolylineUpdatePoints
+ * @interface
+ * @group Misc Shapes
+ */
+export type SUB_PolylineUpdatePoints = [];
+/**
+ * {@link FigureElementCollection} representing a polyline.
+ *
+ * ![](./apiassets/advpolyline_examples.png)
+ *
+ * <p class="inline_gif"><img src="./apiassets/advpolyline_movepolyline.gif" class="inline_gif_image"></p>
+ *
+ * <p class="inline_gif"><img src="./apiassets/advpolyline_movetri.gif" class="inline_gif_image"></p>
+ *
+ * This object defines a convient and powerful polyline
+ * {@link FigureElementCollection} that includes a solid or dashed,
+ * open or closed polyline, arrows, angle annotations for polyline corners,
+ * side annotations for straight lines between points and move pads at polyline
+ * points to dynamically adjust the polyline.
+ *
+ * See {@link COL_Polyline} for the options that can be used when creating the
+ * line.
+ *
+ * Available notifications:
+ *   - `'updatePoints'`: {@link SUB_PolylineUpdatePoints}
+ *
+ * @see
+ * To test examples below, append them to the
+ * <a href="#drawing-boilerplate">boilerplate</a>.
+ *
+ *
+ * @example
+ * // Polyline with angle annotations
+ * figure.add({
+ *   name: 'p',
+ *   make: 'collections.polyline',
+ *   points: [[1, 0], [0, 0], [0.5, 1], [1.5, 1]],
+ *   arrow: 'triangle',
+ *   angle: {
+ *     label: null,
+ *     curve: {
+ *       radius: 0.3,
+ *     },
+ *   }
+ * });
+ *
+ * @example
+ * // Triangle with unknown angle
+ * figure.add({
+ *   name: 'p',
+ *   make: 'collections.polyline',
+ *   points: [[1, 1], [1, 0], [0, 0]],
+ *   close: true,
+ *   side: {
+ *     label: null,
+ *   },
+ *   angle: {
+ *     label: {
+ *       text: '?',
+ *       offset: 0.05,
+ *     },
+ *     curve: {
+ *       radius: 0.4,
+ *     },
+ *     show: [1],
+ *   },
+ * });
+ *
+ * @example
+ * // Dimensioned square
+ * figure.add({
+ *   name: 'p',
+ *   make: 'collections.polyline',
+ *   points: [[0, 1], [1, 1], [1, 0], [0, 0]],
+ *   close: true,
+ *   side: {
+ *     showLine: true,
+ *     offset: 0.2,
+ *     color: [0, 0, 1, 1],
+ *     arrow: 'barb',
+ *     width: 0.01,
+ *     label: null,
+ *     dash: [0.05, 0.02],
+ *     0: { label: { text: 'a' } },    // Customize side 0
+ *   },
+ *   angle: {
+ *     curve: {
+ *       autoRightAngle: true,
+ *       radius: 0.3,
+ *     },
+ *   },
+ * });
+ *
+ * @example
+ * // User adjustable polyline
+ * figure.add({
+ *   name: 'p',
+ *   make: 'collections.polyline',
+ *   points: [[-0.5, 1], [1, 1], [0, 0], [1, -0.5]],
+ *   dash: [0.05, 0.02],
+ *   pad: {
+ *     radius: 0.2,
+ *     color: [1, 0, 0, 0.5],    // make alpha 0 to hide pad
+ *     isMovable: true,
+ *   },
+ * });
+ *
+ * @example
+ * // Annotations that automatically updates as user changes triangle
+ * figure.add({
+ *   name: 'p',
+ *   make: 'collections.polyline',
+ *   points: [[-1, 1], [1, 1], [0, 0]],
+ *   close: true,
+ *   makeValid: {
+ *     shape: 'triangle',
+ *     hide: {
+ *       minAngle: Math.PI / 8,
+ *     },
+ *   },
+ *   side: {
+ *     showLine: true,
+ *     offset: 0.2,
+ *     color: [0.3, 0.6, 1, 1],
+ *     arrow: 'barb',
+ *     width: 0.01,
+ *     label: {
+ *       text: null,
+ *     },
+ *   },
+ *   angle: {
+ *     label: null,
+ *     curve: { radius: 0.25 },
+ *   },
+ *   pad: {
+ *     radius: 0.4,
+ *     color: [1, 0, 0, 0.005],
+ *     isMovable: true,
+ *   },
+ * });
+ * @group 2D Shape Collections
+ */
+export default class CollectionsPolyline extends FigureElementCollection {
+    collections: FigureCollections;
+    animateNextFrame: () => void;
+    isTouchDevice: boolean;
+    largerTouchBorder: boolean;
+    position: Point;
+    points: Array<Point>;
+    close: boolean;
+    _line: FigureElementPrimitive | null | undefined;
+    options: COL_Polyline;
+    updatePointsCallback: string | (() => void) | null | undefined;
+    reverse: boolean;
+    makeValid: {
+        shape: 'triangle';
+        hide: {
+            minAngle: number | null | undefined;
+            maxAngle: number | null | undefined;
+            minSide: number | null | undefined;
+        };
+    } | null | undefined;
+    defaultFont: OBJ_Font;
+    /**
+     * @hideconstructor
+     */
+    constructor(collections: FigureCollections, isTouchDevice: boolean, animateNextFrame: () => void, options?: COL_Polyline);
+    addPads(pad: Record<string, any>): void;
+    addAngles(angle: Record<string, any>, close: boolean): void;
+    addSides(side: Record<string, any>, close: boolean): void;
+    _getStateProperties(options: Record<string, any>): string[];
+    _fromState(state: Record<string, any>): this;
+    updateSideLabels(rotationOffset?: number): void;
+    updateAngleLabels(rotationOffset?: number): void;
+    /**
+     * Update the polyline with new point locations.
+     *
+     * Will publish {@link SUB_PolylineUpdatePoints} unless
+     * `doNotPublishUpdatePoints` is `true`.
+     */
+    updatePoints(newPointsIn: Array<Point>, doNotPublishUpdatePoints?: boolean): void;
+    updateAngles(): void;
+    updateRotation(rotationOffset?: number): void;
+    /**
+     * Reverse points in the polyline.
+     *
+     * Will publish {@link SUBSCRIPTION_PolylineUpdatePoints} unless
+     * `doNotPublishUpdatePoints` is `true`.
+     *
+     * @param {boolean} doNotPublishUpdatePoints if `true` the `updatePoints`
+     * subscription will not be published.
+     */
+    reversePoints(doNotPublishUpdatePoints?: boolean): void;
+    /**
+     * The Collections Polyline is a {@link FigureElementCollection}, with a
+     * transform that includes a translation, or position, transform element.
+     *
+     * Changing the position element of the transform would normally move
+     * everything in the collection. This method instead changes the position
+     * without moving everything by updating the polyline points with an
+     * offset that is the opposite new position.
+     *
+     * As an example, if a rotation around the second point of a polyline is
+     * desired, then setPositionWithoutMoving at the point before rotating.
+     */
+    setPositionWithoutMoving(newPositionPointOrX: Point | number, newPositionY?: number): void;
+    /**
+     * The Collections Polyline is a {@link FigureElementCollection}, with a
+     * transform that includes a rotation transform element.
+     *
+     * Changing the rotation element of the transform would normally rotate
+     * everything in the collection. This method instead changes the rotation
+     * without rotating everything by updating the polyline points with a
+     * rotation that is the negative of the `newRotation`.
+     */
+    setRotationWithoutMoving(newRotation: number): void;
+    /**
+     * The Collections Polyline is a {@link FigureElementCollection}, with a
+     * transform that includes a scale transform element.
+     *
+     * Changing the scale element of the transform would normally scale
+     * everything in the collection. This method instead changes the scale
+     * without scaling everything by updating the polyline points with a
+     * scale that is the inverse of the new scale.
+     */
+    setScaleWithoutMoving(newScalePointOrX: Point | number, newScaleY?: number): void;
+    setShow(name: string, show: boolean): void;
+    /**
+     * Hide all angle annotations.
+     */
+    hideAngles(): void;
+    /**
+     * Hide all side annotations.
+     */
+    hideSides(): void;
+    /**
+     * Show all angle annotations.
+     */
+    showAngles(): void;
+    /**
+     * Hide all side annotations.
+     */
+    showSides(): void;
+    updateLabels(rotationOffset?: number): void;
+    makeValidTriangle(): void;
+}