figureone 0.15.10 → 1.0.0

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

@@ -0,0 +1,587 @@
+import { Transform, Point, Line } from '../../tools/g2';
+import type { TypeParsablePoint, TypeParsableBuffer, TypeBorder, TypeXAlign, TypeYAlign } from '../../tools/g2';
+import { FigureElementCollection, FigureElementPrimitive } from '../Element';
+import EquationLabel from './EquationLabel';
+import type { TypeLabelOrientation, TypeLabelLocation, TypeLabelSubLocation } from './EquationLabel';
+import { Equation } from '../Equation/Equation';
+import type { TypeWhen } from '../TimeKeeper';
+import type { OBJ_LineArrows, OBJ_LineArrow, TypeArrowHead } from '../geometries/arrow';
+import type { OBJ_Pulse, FigureElement } from '../Element';
+import type { EQN_Equation } from '../Equation/Equation';
+import * as animation from '../Animation/Animation';
+import type { OBJ_CustomAnimationStep, OBJ_TriggerAnimationStep } from '../Animation/Animation';
+import type { TypeColor, TypeDash, OBJ_Font } from '../../tools/types';
+import type { OBJ_Collection } from '../FigurePrimitives/FigurePrimitiveTypes';
+import type FigureCollections from './FigureCollections';
+/**
+ * Width pulse options object.
+ *
+ * @property {number} [line] width scale
+ * @property {number | OBJ_Pulse} [label] label pulse options or scale. Use
+ * the options object for more control of how the label is pulsed (for example
+ * if the label should be pulsed from its bottom rather than its center).
+ * @property {number} [arrow] arrow pulse scale
+ * @property {function(): void} [done] execute when pulsing is finished
+ * @property {number} [duration] pulse duration in seconds
+ * @property {number} [frequency] pulse frequency in pulses per second
+ * @property {TypeWhen} [when] when to start the pulse (`'nextFrame'`)
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_PulseWidth = {
+    line?: number;
+    label?: number | OBJ_Pulse;
+    arrow?: number;
+    done?: (() => void) | null | undefined;
+    duration?: number;
+    when?: TypeWhen;
+    frequency?: number;
+};
+/**
+ * Collections line label options object.
+ *
+ * A line can be annotated with a label using the `text` property and can be:
+ * - text (`string`, or Array<`string`)
+ * - an equation (`Equation`, `EQN_Equation`)
+ * - real length of line (`null`)
+ *
+ * In all cases, an actual {@link Equation} is created as the label. The
+ * equation can have multiple forms, which can be set using the `showForm`
+ * method.
+ *
+ * If `text`: `string`, then an equation with a single form named `base` will
+ * be created with a single element being the string text.
+ *
+ * If `text`: `Array<string>`, then an equation with a form for each element
+ * of the array is created. Each form is named '0', '1', '2'... corresponding
+ * with the index of the array. Each form is has a single element, being the
+ * text at that index.
+ *
+ * Use `text`: `Equation` or `EQN_Equation` to create completely custom
+ * equations with any forms desirable.
+ *
+ * If the label text is the real length of the line (`null`), then the number
+ * of decimal places can be selected with `precision`.
+ *
+ * The space between the line and the label is defined with `offset`. An
+ * `offset` of 0 puts the center of the label on the line. Any
+ * positive or negative value of offset will move the label so no part of the
+ * label overlaps the line, and then the closest part of the label is separated
+ * from the line by `offset`.
+ *
+ * To situate the label on the line, use `linePosition`, `location` and
+ * `subLocation`. By default the label will be a percentage `linePosition`
+ * along the line. `location` then defines which side of the line the label is
+ * on, while `subLocation` defines the backup location for invalid cases of
+ * `location`. See {@link TypeLabelLocation} and
+ * {@link TypeLabelSubLocation}. `location` can additionaly place the
+ * labels off the ends of the line.
+ *
+ * To automatically update the label location and orientation as the line
+ * transform (translation, rotation or scale) changes then use `update: true`.
+ *
+ * @see {@link COL_Line}
+ *
+ * @property {null | string | Array<string> | Equation | EQN_Equation } text
+ * @property {number} [precision]
+ * @property {number} [offset]
+ * @property {number} [linePosition]
+ * @property {TypeLabelLocation} [location]
+ * @property {TypeLabelSubLocation} [subLocation]
+ * @property {TypeLabelOrientation} [orientation]
+ * @property {boolean} [update] (`false`)
+ * @property {number} [scale] size of the label
+ * @property {TypeColor} [color]
+ * @property {OBJ_Font} [font] default font for label
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_LineLabel = {
+    text: null | string | Array<string> | Equation | EQN_Equation;
+    precision?: number;
+    offset?: number;
+    linePosition?: number;
+    location?: TypeLabelLocation;
+    subLocation?: TypeLabelSubLocation;
+    orientation?: TypeLabelOrientation;
+    update?: boolean;
+    scale?: number;
+    color?: TypeColor;
+    font?: OBJ_Font;
+};
+/**
+ * Line move options object.
+ *
+ * The `'centerTranslateEndRotation`' movement will move the line
+ * when touched within the `middleLength` percentage of the line
+ * and rotate it otherwise.
+ *
+ * @property {boolean} [movable] `true` to make movable (`true`)
+ * @property {'translation' | 'rotation' | 'centerTranslateEndRotation' | 'scale'} [type]
+ * @property {number} [middleLength] length of the middle section of line that
+ * allows for translation movement in percent of total length (`0.333`)
+ * @property {boolean} [includeLabelInTouchBoundary] `true` to include the
+ * line's label in the touch boundary for `'centerTranslateEndRotation'`
+ * ('false`)
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_LineMove = {
+    type?: 'translation' | 'rotation' | 'centerTranslateEndRotation' | 'scale';
+    middleLength?: number;
+    includeLabelInTouchBoundary?: boolean;
+};
+/**
+ * setMovable options object for {@link COL_Line}.
+ *
+ * @extends OBJ_LineMove
+ *
+ * @property {boolean} [movable] `true` to make movable (`true`)
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_MovableLine = {
+    movable?: boolean;
+} & OBJ_LineMove;
+/**
+ * {@link CollectionsLine} options object that extends {@link OBJ_Collection}
+ * options object (without `parent`).
+ *
+ *
+ * The Collections Line is a convient and powerful line
+ * {@link FigureElementCollection} that includes the line, arrows, a label
+ * annotation and some methods to make it convient to use dynamically.
+ *
+ * A line can either be defined by its two end points (`p1`, `p2`), or a
+ * point (`p1`), `length` and `angle`.
+ *
+ * `offset` can be used to draw the line some offset away from the line
+ * definition where a positive offset is on the side of the line that the line
+ * rotates toward when rotating in the positive direction. This is especially
+ * useful for creating lines that show dimensions of shapes.
+ *
+ * The line also has a control point which is positioned on the line with the
+ * `align` property. The control point is the line's center of rotation, and
+ * fixes the point from which the line changes length. This is also the point
+ * where the line collection position will be if `getPosition` is called on the
+ * element.
+ *
+ * For instance, setting the control point at `align: 'start'` will mean that
+ * if the line can rotate, it will rotate around `p1`, and if the length is
+ * changed, then `p1` will remain fixed while `p2` changes.
+ *
+ * `width` sets the width of the line. Setting the width to 0 will hide the
+ * line itself, but if arrows or a label are defined they will still be
+ * displayed.
+ *
+ * Use the `label` property to define and position a label relative to the line.
+ * The label can be any string, equation or the actual length of the line and
+ * be oriented relative to the line or always be horizontal.
+ *
+ * Use the `arrow` and `dash` properties to define arrows and the line style.
+ *
+ * Pulsing this collection normally would pulse both the length and width of
+ * the line. If it often desirable to pulse a line without changing its length,
+ * and so this collection provides a method `pulseWidth` to allow this. This
+ * options object can define the default values for pulseWidth if desired.
+ *
+ * Default pulse values can then be specified with the `pulse` property.
+ *
+ * @extends OBJ_Collection
+ *
+ * @property {TypeParsablePoint} [p1] First point of line
+ * @property {TypeParsablePoint} [p2] Will override `length`/`angle` definition
+ * @property {number} [angle] line angle
+ * @property {number} [length]  line length
+ * @property {number} [offset] line offset
+ * @property {'start' | 'end' | 'center' | number} [align] rotation center of
+ * line (only needed if rotating line)
+ * @property {number} [width] line width
+ * @property {OBJ_LineLabel} [label] label annotation
+ * @property {OBJ_LineArrows | TypeArrowHead} [arrow] line arrow(s)
+ * @property {TypeDash} [dash] make the line dashed
+ * @property {OBJ_PulseWidth} [pulseWidth] default options for pulseWidth pulse
+ * @property {OBJ_Pulse} [pulse] default options for normal pulse
+ * @property {OBJ_LineMove} [move] line move options
+ * @interface
+ * @group 2D Shape Collections
+ */
+export type COL_Line = {
+    p1?: TypeParsablePoint;
+    p2?: TypeParsablePoint;
+    length?: number;
+    angle?: number;
+    offset?: number;
+    align?: 'start' | 'end' | 'center' | number;
+    width?: number;
+    label?: OBJ_LineLabel;
+    arrow?: OBJ_LineArrows | TypeArrowHead;
+    dash?: TypeDash;
+    pulseWidth?: OBJ_PulseWidth;
+    pulse?: OBJ_Pulse;
+    move?: OBJ_LineMove;
+} & OBJ_Collection;
+declare class LineLabel extends EquationLabel {
+    offset: number;
+    location: TypeLabelLocation;
+    subLocation: TypeLabelSubLocation;
+    orientation: TypeLabelOrientation;
+    linePosition: number;
+    precision: number;
+    constructor(collections: FigureCollections, labelText: string | Equation | EQN_Equation | Array<string>, color: TypeColor, offset: number, location: TypeLabelLocation | undefined, subLocation: TypeLabelSubLocation | undefined, orientation: TypeLabelOrientation | undefined, linePosition: number | undefined, // number where 0 is end1, and 1 is end2
+    scale: number | undefined, precision: number | undefined, font: OBJ_Font);
+}
+/**
+ * Grow line animation step.
+ *
+ * @property {number} [start] line length to grow from (`current length`)
+ * @property {number} [target] line length to grow to (`current length`)
+ * @extends OBJ_CustomAnimationStep
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_LengthAnimationStep = {
+    start?: number;
+    target?: number;
+} & OBJ_CustomAnimationStep;
+/**
+ * Pulse Width animation step.
+ *
+ *
+ * @property {number} [line] width scale
+ * @property {number | OBJ_Pulse} [label] label pulse options or scale. Use
+ * the options object for more control of how the label is pulsed (for example
+ * if the label should be pulsed from its bottom rather than its center).
+ * @property {number} [arrow] arrow pulse scale
+ * @property {function(): void} [done] execute when pulsing is finished
+ * @property {number} [duration] pulse duration in seconds
+ * @property {number} [frequency] pulse frequency in pulses per second
+ * @extends OBJ_TriggerAnimationStep
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_PulseWidthAnimationStep = {
+    line?: number;
+    label?: number | OBJ_Pulse;
+    arrow?: number;
+    done?: (() => void) | null | undefined;
+    duration?: number;
+    frequency?: number;
+} & OBJ_TriggerAnimationStep;
+/**
+ * {@link FigureElementCollection} representing a line.
+ *
+ * <p class="inline_gif"><img src="./apiassets/advline_pulse.gif" class="inline_gif_image"></p>
+ *
+ * <p class="inline_gif"><img src="./apiassets/advline_grow.gif" class="inline_gif_image"></p>
+ *
+ * <p class="inline_gif"><img src="./apiassets/advline_multimove.gif" class="inline_gif_image"></p>
+ *
+ * This object defines a convient and powerful line
+ * {@link FigureElementCollection} that includes a solid or dashed line,
+ * arrows, a label annotation that can self align with line orientation, and
+ * some methods to make it convient to use dynamically.
+ *
+ * See {@link COL_Line} for the options that can be used when creating the line.
+ *
+ * The object contains a two additional animation steps. `length`
+ * animates changing the line length, and `pulseWidth` animates the
+ * `pulseWidth` method. The animation steps are available in
+ * the animation manager ({@link FigureElement}.animations),
+ * and in the animation builder
+ * (<a href="#animationmanagernew">animations.new</a>
+ * and <a href="#animationmanagerbuilder">animations.builder</a>).
+ *
+ * Some of the useful methods included in an collections line are:
+ * - <a href="#collectionslinepulsewidth">pulseWidth</a> - pulses the line without
+ *   changing its length
+ * - <a href="#collectionslinegrow">grow</a> - starts and animation that executes
+ *   a single `length` animation
+ *    step
+ * - <a href="#collectionslinesetmovable">grow</a> - overrides
+ *    <a href="#figureelementsetmovable">FigureElement.setMovable</a> and
+ *    allowing for more complex move options.
+ *
+ * @see See {@link OBJ_LengthAnimationStep} for angle animation step options.
+ *
+ * See {@link OBJ_PulseWidthAnimationStep} for pulse angle animation step
+ * options.
+ *
+ * To test examples below, append them to the
+ * <a href="#drawing-boilerplate">boilerplate</a>.
+ *
+ *
+ * @example
+ * // Pulse an annotated line
+ * figure.add({
+ *   name: 'l',
+ *   make: 'collections.line',
+ *   p1: [-1, 0],
+ *   p2: [1, 0],
+ *   arrow: 'triangle',
+ *   label: {
+ *     text: 'length',
+ *     offset: 0.04,
+ *   },
+ * });
+ *
+ * figure.elements._l.pulseWidth({ duration: 2 });
+ *
+ * @example
+ * // Animate growing a line while showing it's length
+ * figure.add({
+ *   name: 'l',
+ *   make: 'collections.line',
+ *   p1: [-1, 0],
+ *   p2: [-0.5, 0],
+ *   align: 'start',
+ *   arrow: { end: { head: 'barb', scale: 2 } },
+ *   label: {
+ *     text: null,
+ *     offset: 0.03,
+ *     precision: 2,
+ *     location: 'start'
+ *   },
+ * });
+ *
+ * const l = figure.elements._l;
+ * l.animations.new()
+ *   .length({ start: 0.5, target: 2, duration: 2 })
+ *   .start();
+ *
+ * @example
+ * // Example showing dashed line with an equation label that stays horizontal
+ * const l = figure.collections.line({
+ *   p1: [0, 0],
+ *   p2: [1.4, 0],
+ *   align: 'start',
+ *   label: {
+ *     text: {                             // label text is an equation
+ *       elements: {
+ *         twopi: '2\u03C0',
+ *       },
+ *       forms: {
+ *         base: ['twopi', ' ', { frac: ['a', 'vinculum', 'b'] } ]
+ *       },
+ *     },
+ *     offset: 0.03,
+ *     orientation: 'horizontal',          // keep label horizontal
+ *     location: 'top',                    // keep label on top of line
+ *   },
+ *   dash: [0.08, 0.02, 0.02, 0.02],
+ * });
+ * figure.add('l', l);
+ * l.setMovable({ type: 'centerTranslateEndRotation'})
+ * l.setAutoUpdate();
+ *
+ * @group 2D Shape Collections
+ */
+export default class CollectionsLine extends FigureElementCollection {
+    _line: FigureElementPrimitive | null | undefined;
+    _movePad: FigureElementPrimitive | null | undefined;
+    _rotPad: FigureElementPrimitive | null | undefined;
+    _startPad: FigureElementPrimitive | null | undefined;
+    _arrow1: FigureElementPrimitive | null | undefined;
+    _arrow2: FigureElementPrimitive | null | undefined;
+    _label: null | {
+        _base: FigureElementPrimitive;
+    } & FigureElementCollection;
+    label: LineLabel | null | undefined;
+    arrow1: {
+        height: number;
+    } | null | undefined;
+    arrow2: {
+        height: number;
+    } | null | undefined;
+    line: Line;
+    width: number;
+    localXPosition: number;
+    alignDraw: 'start' | 'end' | 'center' | number;
+    dash: TypeDash;
+    arrow: {
+        start?: OBJ_LineArrow;
+        end?: OBJ_LineArrow;
+    } | null | undefined;
+    showRealLength: boolean;
+    autoUpdateSubscriptionId: number;
+    shapes: Record<string, any>;
+    equation: Record<string, any>;
+    isTouchDevice: boolean;
+    scaleTransformMethodName: string;
+    animateLengthToStepFunctionName: string;
+    animateLengthToDoneFunctionName: string;
+    pulseWidthDoneCallbackName: string;
+    pulseWidthDefaults: {
+        line: number;
+        label: number;
+        arrow: number;
+        duration: number;
+        frequency: number;
+    };
+    multiMove: {
+        midLength: number;
+        includeLabelInTouchBoundary: boolean;
+    };
+    animateLengthToOptions: {
+        initialLength: number;
+        deltaLength: number;
+        callback: string | (() => void) | null | undefined;
+        onStepCallback: string | ((p1: number, p2: number) => void) | null | undefined;
+        finishOnCancel: boolean;
+    };
+    pulseWidthOptions: {
+        oldCallback: string | (() => void) | null | undefined;
+        oldTransformMethod: string | ((p1: number, p2: Point | null | undefined) => Transform) | null | undefined;
+    };
+    animations: {
+        length: (...opt: Array<OBJ_LengthAnimationStep>) => animation.CustomAnimationStep;
+        pulseWidth: (...opt: Array<OBJ_PulseWidth>) => animation.TriggerAnimationStep;
+    } & animation.AnimationManager;
+    lastParentRotationOffset: number;
+    /**
+     * @hideconstructor
+     */
+    constructor(collections: FigureCollections, isTouchDevice: boolean, options?: COL_Line);
+    fontUpdated(): void;
+    /** A line has:
+     *    - length
+     *    - p1, p2
+     *    - angle
+     *    - position
+     *    - reference alignment
+     *
+     * Two ways to define a line:
+     *  - p1, p2
+     *  - position, align, length, angle
+     *
+     * Line is defined by:
+     *  - primitive line: full length, angle = 0, aligned in draw space with align
+     *  - transform.translate: moves align position
+     *  - transform.rotate: changes angle
+     */
+    transformToLine(): void;
+    _getStateProperties(options: Record<string, any>): string[];
+    _fromState(state: Record<string, any>): this;
+    stateSet(): void;
+    pulseWidthDone(): void;
+    /**
+     * Pulse the line so that it's width pulses and its length doesn't change.
+     *
+     * The pulse scales of the line, label and arrows can all be defined
+     * separately.
+     */
+    pulseWidth(options?: OBJ_PulseWidth): void;
+    addArrow(lineEnd: 'start' | 'end'): void;
+    /**
+     * Use this method to enable or disable movability of the line.
+     *
+     * @param {OBJ_MovableLine | boolean} [movableOrOptions] `true` to
+     * make movable, `false` to make not movable or use options to
+     * set different kinds of movability.
+     */
+    setMove(movableOrOptions?: any): void;
+    setMultiMovable(middleLengthPercent: number): void;
+    moved(value: Point | number): void;
+    /**
+     * Use this to manually update the rotation of the line collection.
+     */
+    updateMoveTransform(t?: Transform): void;
+    addLabel(labelText: string | Equation | EQN_Equation | Array<string>, offset: number, location: TypeLabelLocation | undefined, subLocation: TypeLabelSubLocation | undefined, orientation: TypeLabelOrientation | undefined, linePosition: number | undefined, // number where 0 is end1, and 1 is end2
+    scale: number | undefined, color: TypeColor | undefined, precision: number | undefined, update: boolean | undefined, font: OBJ_Font, otherOptions?: {
+        isTouchable?: boolean;
+        touchBorder?: TypeParsableBuffer | TypeBorder;
+        onClick?: null | string | (() => void);
+    }): void;
+    /**
+     * Turn on and off auto label location and orientation updates when line
+     * transform changes. When a line is created with a label, auto update
+     * is turned off by default.
+     */
+    setAutoUpdate(update?: boolean): void;
+    /**
+     * Get line length
+     * @return {number}
+     */
+    getLength(): number;
+    /**
+     * Get line angle
+     * @param {'deg' | 'rad'} [units]
+     * @return {number}
+     */
+    getAngle(units?: 'deg' | 'rad'): number;
+    /**
+     * Change the text of the label
+     */
+    setLabel(text: string): void;
+    /**
+     * Get the text of the label
+     */
+    getLabel(): string;
+    /**
+     * Set the label to be the real length of the line
+     */
+    setLabelToRealLength(): void;
+    /**
+     * Manually update the label orientations with a custom rotation offset.
+     *
+     * Automatic updating can be done with
+     * <a href="collectionsline#setautoupdate">setAutoUpdate</a>
+     * @param {number | null} rotationOffset
+     */
+    updateLabel(rotationOffset?: number | null): void;
+    /**
+     * Set the length of the line
+     */
+    setLength(length: number, align?: 'start' | 'end' | 'center' | number): void;
+    setupLine(): void;
+    updateMovePads(): void;
+    /**
+     * Change the line position, length and angle using end points and an offset.
+     *
+     * For most lines, an offset of 0 will be desired, as this will position the
+     * line ends to be at `p1` and `p2`.
+     *
+     * A non-positive offset will position the line in parallel with `p1` and `p2`
+     * but some offset away. A positive offset will position the line on the side
+     * it will rotate toward with positive rotation.
+     */
+    setEndPoints(p1: TypeParsablePoint, p2: TypeParsablePoint, offset?: number): void;
+    pointFromTo(from: {
+        element: FigureElement;
+        xAlign: TypeXAlign;
+        yAlign: TypeYAlign;
+        space: number;
+    }, to: {
+        element: FigureElement;
+        xAlign: TypeXAlign;
+        yAlign: TypeYAlign;
+        space: number;
+    }, autoOutside?: boolean): void;
+    /**
+     * Create a new animation that executes a single grow animation step.
+     */
+    grow(options: OBJ_LengthAnimationStep): void;
+    showLineOnly(): void;
+    /**
+     * Return a geometric {@link Line} object that represents the line
+     * @return {Line}
+     */
+    getLine(): Line;
+    /**
+     * Return the start point of the line
+     * @return {Point}
+     */
+    getP1(): Point;
+    /**
+     * Return the end point of the line
+     * @return {Point}
+     */
+    getP2(): Point;
+}
+export type TypeLabelledLine = {
+    _line: FigureElementPrimitive;
+    _label: {
+        _base: FigureElementPrimitive;
+    } & Equation;
+} & CollectionsLine;
+export {};