ice-render 0.0.8 → 0.0.9

package/dist/types/event/ICEEventTarget.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @class ICEEventTarget
+ *
+ * - canvas 标签内部没有事件机制，模仿 W3C 定义的 EventTaregt 接口，为 Canvas 内部的组件添加事件机制。
+ * - ICE 内部的大部分组件都是 ICEEventTarget 的子类。
+ * - 部分 API 名称模仿 jQuery ，方便使用者调用。
+ *
+ * TODO:需要完整模拟 W3C 和 jQuery 提供的事件接口，在 API 名称和调用逻辑上保持完全一致。
+ *
+ * listeners 的结构：
+ * {
+ *    "click":[
+ *        {
+ *          callback:fn1,
+ *          scope:window
+ *        },
+ *        {
+ *          callback:fn2,
+ *          scope:component-1
+ *        }
+ *     ],
+ *    "mousemove":[
+ *        {
+ *          callback:fn1,
+ *          scope:window
+ *        },
+ *        {
+ *          callback:fn2,
+ *          scope:component-1
+ *        }
+ *     ]
+ * }
+ *
+ * @abstract
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/EventTarget
+ */
+declare abstract class ICEEventTarget {
+    protected listeners: any;
+    protected suspendedEventNames: any;
+    constructor();
+    /**
+     * @method on
+     * 添加事件监听
+     * @param eventName
+     * @param fn
+     * @param scope
+     */
+    on(eventName: string, fn: Function, scope?: any): void;
+    /**
+     * @method off
+     * 删除事件监听
+     * @param eventName
+     * @param fn
+     * @param scope
+     * @returns
+     */
+    off(eventName: string, fn: Function, scope?: any): void;
+    /**
+     * @method once
+     * 一次性事件，触发一次就自动删除自己。
+     * @param eventName
+     * @param fn
+     */
+    once(eventName: string, fn: Function, scope?: any): void;
+    /**
+     * @method dispatchEvent
+     *
+     * 触发事件。
+     *
+     * 所有事件都会被转换成 ICEEvent 实例。
+     *
+     * @param eventName
+     * @param originalEvent
+     * @param param
+     * @returns
+     */
+    trigger(eventName: string, originalEvent?: any, param?: {}): boolean;
+    /**
+     * @method suspend
+     * 挂起事件。
+     * @param eventName
+     */
+    suspend(eventName: string): void;
+    /**
+     * @method resume
+     * 恢复事件。
+     * @param eventName
+     */
+    resume(eventName: string): void;
+    /**
+     * @method purgeEvents
+     * 清除所有事件。
+     */
+    purgeEvents(): void;
+    /**
+     * @method hasListener
+     * 查询是否带有某个事件监听器。
+     * @param eventName
+     * @param fn
+     * @param scope
+     * @returns
+     */
+    hasListener(eventName: string, fn: Function, scope?: any): boolean;
+}
+export default ICEEventTarget;

package/dist/types/event/MouseEventInterceptor.d.ts

@@ -0,0 +1,7 @@
+export default MouseEventInterceptor;
+declare namespace MouseEventInterceptor {
+    const evtBuses: any[];
+    function start(): void;
+    function regitserEvtBus(evtBus: any): void;
+    function delEvtBus(evtBus: any): void;
+}

package/dist/types/geometry/GeoLine.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2022 大漠穷秋.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+/**
+ * @class GeoLine
+ * A geometrically line, invisible, no dimension, just used for mathematical operations.
+ * This implementation is improved from http://diagramo.com/ .
+ *
+ *
+ * 几何学意义上的直线，它不可见，没有宽度，用来进行数学运算。此实现从 diagramo 改进而来：http://diagramo.com/ 。
+ *
+ * @docauthor 大漠穷秋 <damoqiongqiu@126.com>
+ */
+export default class GeoLine {
+    constructor(startPoint: any, endPoint: any);
+    startPoint: any;
+    endPoint: any;
+    contains(x: any, y: any): boolean;
+}

package/dist/types/geometry/GeoPoint.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Copyright (c) 2022 大漠穷秋.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+/**
+ * @class GeoPoint
+ * A geometrically point, invisible, no dimension, just used for mathematical operations.
+ * This implementation is improved from http://diagramo.com/ .
+ *
+ *
+ * 几何学意义上的点，它不可见，没有大小，用来进行数学运算。此实现从 diagramo 改进而来：http://diagramo.com/ 。
+ *
+ * @docauthor 大漠穷秋 <damoqiongqiu@126.com>
+ */
+export default class GeoPoint {
+    /**
+     *
+     * @method load
+     * Creates a {GeoPoint} out of JSON parsed object.
+     *
+     *
+     * 从 JSON 对象创建 {GeoPoint} 实例。
+     * @param {JSONObject} o the JSON parsed object
+     * @return {GeoPoint} a newly constructed GeoPoint
+     */
+    static load(o: JSONObject): GeoPoint;
+    /**
+     *
+     * @method cloneArray
+     * Clones an array of points.
+     *
+     *
+     * 克隆一组点。
+     * @param {Array} v - the array of {GeoPoint}s
+     * @return an {Array} of {GeoPoint}s
+     */
+    static cloneArray(v: any[]): any[];
+    /**
+     * @constructor GeoPoint
+     * @param {*} x
+     * @param {*} y
+     */
+    constructor(x?: any, y?: any);
+    x: any;
+    y: any;
+    /**
+     * @method equals
+     * Tests if this point is equals to other point.
+     *
+     *
+     * 测试当前点是否与另一个点相等。
+     * @param {GeoPoint} anotherPoint - the other point
+     */
+    equals(anotherPoint: GeoPoint): boolean;
+    /**
+     * @method clone
+     * Clone current GeoPoint.
+     *
+     *
+     * 克隆当前点。
+     */
+    clone(): GeoPoint;
+}

package/dist/types/geometry/GeoUtil.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2022 大漠穷秋.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+export default class GeoUtil {
+    constructor();
+    /**
+     *
+     * 已知向量原点和向量坐标值，求向量相对于 X 轴正向的旋转角度。
+     *
+     * 两个点需要处于同一个坐标系中。
+     *
+     * rotateAngle 的数值范围限定在 [0,360] 度之间，闭区间。
+     *
+     * @param x
+     * @param y
+     * @param originX
+     * @param originY
+     * @returns
+     */
+    static calcRotateAngle(x: any, y: any, originX: any, originY: any): number;
+}

package/dist/types/geometry/ICEBoundingBox.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @class ICEBoundingBox 用4点法描述的边界盒子。
+ *
+ * - 边界盒子一定是矩形。
+ * - 边界盒子总是绘制在全局坐标系中。
+ * - 边界盒子总是通过自身的坐标点进行变换，而不是变换 canvas.ctx 。
+ * - 边界盒子总是通过组件的参数计算出来的，直接修改边界盒子不影响组件本身的参数。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class ICEBoundingBox {
+    tl: number[];
+    tr: number[];
+    bl: number[];
+    br: number[];
+    tc: number[];
+    rc: number[];
+    bc: number[];
+    lc: number[];
+    center: number[];
+    constructor(props?: Array<number>);
+    /**
+     * 从指定的 top/left/width/height 构建 ICEBoundingBox。
+     * @param left
+     * @param top
+     * @param width
+     * @param height
+     * @returns
+     */
+    static fromDimension(left: any, top: any, width: any, height: any): ICEBoundingBox;
+    /**
+     * 判断指定的坐标点是否位于边界矩形内部，向右水平射线法。
+     * 这里参考了 fabricjs 的实现方式。
+     * @see http://fabricjs.com/
+     * @param point
+     * @returns
+     */
+    containsPoint(point: any): boolean;
+    /**
+     * 获取边界盒子的边所构成的线段，由于边界盒子总是被定义成 4 边形，这里直接简化处理。
+     */
+    private getBoundingLines;
+    /**
+     * 获取边界盒子 x,y 的最大和最小值
+     * @returns
+     */
+    getMinAndMaxPoint(): any;
+    /**
+     * FIXME:需要实现
+     * 另一个边界盒子是否完全位于当前盒子内部。
+     * @param box
+     * @returns
+     */
+    containsBox(box: ICEBoundingBox): boolean;
+    /**
+     * 是否与另一个盒子存在相交的部分。
+     * @param box
+     * @returns
+     */
+    isIntersect(box: ICEBoundingBox): boolean;
+    /**
+     * @param matrix
+     * @returns A new ICEBoundingBox instance.
+     */
+    transform(matrix: any): ICEBoundingBox;
+    /**
+     * @param box
+     * @returns A new ICEBoundingBox instance.
+     */
+    union(box: ICEBoundingBox): ICEBoundingBox;
+    get width(): number;
+    get height(): number;
+    get left(): number;
+    private set left(value);
+    get top(): number;
+    private set top(value);
+    get centerX(): number;
+    get centerY(): number;
+    get centerPoint(): number[];
+}
+export default ICEBoundingBox;

package/dist/types/geometry/ICEMatrix.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) 2022 大漠穷秋.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+export default class ICEMatrix {
+    constructor();
+    /**
+     * 从变换矩阵计算旋转角度。
+     * @param matrix
+     * @returns 角度
+     */
+    static calcRotateAngleFromMatrix(matrix: any): number;
+    /**
+     * 从变换矩阵计算缩放参数。
+     * @param matrix
+     * @returns 缩放数组
+     */
+    static calcScaleFromMatrix(matrix: any): Array<number>;
+}

package/dist/types/graphic/ICEComponent.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Copyright (c) 2022 大漠穷秋.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import { mat2d } from 'gl-matrix';
+import EventBus from '../event/EventBus';
+import ICEEventTarget from '../event/ICEEventTarget';
+import ICEBoundingBox from '../geometry/ICEBoundingBox';
+import ICE from '../ICE';
+/**
+ * @class ICEComponent
+ *
+ * 最顶级的抽象类，Canvas 内部所有可见的组件都是它的子类。
+ *
+ * @abstract
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare abstract class ICEComponent extends ICEEventTarget {
+    ice: ICE;
+    root: any;
+    ctx: any;
+    evtBus: EventBus;
+    parentNode: any;
+    protected static instanceCounter: number;
+    protected __dirty: boolean;
+    /**
+     * @cfg
+     * {
+     *   id: 'ICE_XXXXXXX',                                      //UUID
+     *   left: 0,                                                //x 坐标相对于父组件的偏移量
+     *   top: 0,                                                 //y 坐标相对于父组件的偏移量
+     *   width: 0,                                               //原始宽度，没有经过变换
+     *   height: 0,                                              //原始高度，没有经过变换
+     *   style: {
+     *     fillStyle: 'red',
+     *     strokeStyle: 'blue',
+     *     lineWidth: 1,
+     *   },
+     *   fill:true,                                              //是否填充
+     *   stroke:true,                                            //是否描边
+     *   animations: {},                                         //动画
+     *   transform: {                                            //组件自身的变换参数，不包含父组件
+     *     translate: [0, 0],                                    //平移，像素
+     *     scale: [1, 1],                                        //X轴缩放倍数，Y轴缩放倍数
+     *     skew: [0, 0],                                         //X轴扭曲角度，Y轴扭曲角度
+     *     rotate: 0,                                            //旋转角度
+     *   },
+     *   linearMatrix: [],                            //线性变换矩阵，不含平移，按照 gl-matrix 的格式定义
+     *   composedMatrix: [],                          //复合变换矩阵，包含所有祖先节点的平移、原点移动、线性变换计算，composedMatrix 不会实时更新，如果需要获取当前最新的变换矩阵，需要调用 composeMatrix() 方法。按照 gl-matrix 的格式定义
+     *   origin:'localCenter',
+     *   localOrigin: [0,0],                          //相对于组件本地坐标系（组件内部的左上角为 [0,0] 点）计算的原点坐标
+     *   absoluteOrigin: [0,0],                       //相对于全局坐标系（canvas 的左上角 [0,0] 点）计算的原点坐标
+     *   zIndex: ICEComponent.instanceCounter++,      //类似于 CSS 中的 zIndex
+     *   display:true,                                //如果 display 为 false ， Renderer 不会调用其 render 方法，对象在内存中存在，但是不会被渲染出来。如果 display 为 false ，所有子组件也不会被渲染出来。
+     *   draggable:true,                              //是否可以拖动
+     *   transformable:true,                          //是否可以进行变换：scale/rotate/skew ，以及 resize ，但是不控制拖动
+     *   linkable:true,                               //组件是否可以用连接线连接起来，如果此状态为 true ，ICELinkSlotManager 在运行时会动态在组件上创建连接插槽 ICELinkSlot 的实例
+     *   interactive: true,                           //是否可以进行用户交互操作，如果此参数为 false ， draggable, transformable TODO:动画运行过程中不允许选中，不能进行交互？？？
+     *   showMinBoundingBox:true,                     //是否显示最小包围盒，开发时打开，主要用于 debug
+     *   showMaxBoundingBox:true,                     //是否显示最大包围盒，开发时打开，主要用于 debug
+     * }
+     * @param props
+     */
+    props: any;
+    /**
+     * 在 ICE 引擎中，所有对象都可以启用动画效果，所以对象的 state 随时可能发生变化。
+     * props 与 state 之间的关系与行为模式借鉴自 React 框架，概念模型完全一致。
+     * @see https://reactjs.org/docs/components-and-props.html
+     */
+    state: any;
+    constructor(props?: any);
+    /**
+     * 子类需要提供自己的实现。
+     */
+    protected initEvents(): void;
+    /**
+     * !Important: 核心方法，FrameManager 会调度此方法进行实际的渲染操作。
+     * !Important: 这些方法调用有顺序
+     */
+    render(): void;
+    protected applyStyleToCtx(): void;
+    /**
+     * 计算原始的宽高、位置，此时没有经过任何变换，也没有移动坐标原点。
+     * 此方法不能依赖原点位置和 transform 矩阵。
+     * 在计算组件的原始尺寸时还没有确定原点坐标，所以只能基于组件本地坐标系的左上角 (0,0) 点进行计算。
+     * @returns
+     */
+    calcComponentParams(): {
+        width: any;
+        height: any;
+    };
+    /**
+     * 计算本地原点坐标，相对于组件本地坐标系。
+     * 此方法依赖于 width/height ，需要先计算组件的尺寸，然后才能调用此方法。
+     * @returns
+     */
+    protected calcLocalOrigin(): number[];
+    /**
+     * 根据原点位置描述计算原点坐标值。
+     * 移动坐标原点后，组件内部所有的坐标点数值、边界盒子的坐标，都会受到影响。
+     * 计算出的原点数值已经包含了所有父层的移位和变换。
+     * @method calcAbsoluteOrigin
+     */
+    calcAbsoluteOrigin(): number[];
+    /**
+     * 计算线性变换矩阵，此矩阵不包含平移操作。
+     * 线性变换顺序：旋转->错切->缩放
+     * 由于矩阵变换有顺序，这里采用符合自然理解的顺序进行。
+     * @method calcLinearMatrix
+     * @returns
+     */
+    protected calcLinearMatrix(): mat2d;
+    /**
+     * 复合所有祖先节点的线性变换矩阵，获得相对于全局 canvas 对象的变换矩阵。
+     * @returns
+     */
+    protected calcAbsoluteLinearMatrix(): mat2d;
+    /**
+     * 仿射变换由2步完成：
+     * - ctx 平移到指定的原点。
+     * - ctx 进行线性变换。
+     *
+     * Canvas 绘图过程中的仿射变换动作与线性代数中的规则有差异：
+     * - Canvas 的 Y 坐标轴方向是向下的。
+     * - Canvas 在做仿射变换时，变换的是 ctx 本身，而不是组件对象，相当于画布本身是具有弹性的可变形对象。
+     *
+     * @method composeMatrix
+     * @returns
+     */
+    protected composeMatrix(): mat2d;
+    /**
+     * 把变换矩阵应用到 this.ctx 上
+     */
+    protected applyTransformToCtx(): void;
+    /**
+     * 所有子类都应该提供具体的实现。
+     * @method doRender
+     */
+    protected doRender(): void;
+    /**
+     * 获取组件的最小包围盒，此盒子的变换矩阵与组件自身完全相同。
+     * 此方法需要在 render() 之后调用，组件没有渲染时无法计算最小包围盒。
+     * @returns
+     */
+    getMinBoundingBox(refresh?: boolean): ICEBoundingBox;
+    /**
+     * 获取组件的最大包围盒：
+     * - 盒子保持水平和竖直，不旋转、不错切。
+     * - 盒子的4边在全局坐标 X/Y 轴上的投影范围与组件完全一致。
+     * @returns
+     */
+    getMaxBoundingBox(refresh?: boolean): ICEBoundingBox;
+    /**
+     * setState 仅仅修改参数，不会立即导致重新渲染，需要等待 FrameManager 调度，最小延迟时间约为 1/60=16.67 ms 。
+     * @param newState
+     */
+    setState(newState: any): void;
+    set dirty(flag: boolean);
+    get dirty(): boolean;
+    /**
+     * 相对于父组件的坐标系和原点。
+     * @param left
+     * @param top
+     * @param evt
+     */
+    setPosition(left: number, top: number, evt?: any): void;
+    /**
+     * 在全局空间(canvas)中移动指定的位移。
+     * 注意：此方法用于直接设置组件在全局空间中的位移，而不是相对于其它坐标系。
+     * @param tx
+     * @param ty
+     * @param evt
+     */
+    moveGlobalPosition(tx: number, ty: number, evt?: any): void;
+    /**
+     * 直接设置在全局空间 (canvas) 中的位置。
+     * 注意：此方法用于直接设置组件在全局空间中的位置，而不是相对于其它坐标系。
+     * @param left
+     * @param top
+     * @param evt
+     */
+    setGlobalPosition(left: number, top: number, evt?: any): void;
+    /**
+     * 在全局空间(canvas)中旋转指定的角度。
+     * 注意：此方法用于直接设置组件在全局空间中的旋转角，而不是相对于其它坐标系。
+     * @param rotateAngle
+     */
+    setGlobalRotate(rotateAngle: any): void;
+    /**
+     * 组件局部坐标系中的点转换成全局空间(canvas)中的点，包含移动原点的操作。
+     * @param localX
+     * @param localY
+     * @returns
+     */
+    localToGlobal(localX: number, localY: number): number[];
+    /**
+     * 全局空间(canvas)中的点转换成组件局部坐标系中的点，包含移动原点的操作。
+     * @param globalX
+     * @param globalY
+     * @returns
+     */
+    globalToLocal(globalX: number, globalY: number): number[];
+    /**
+     * 根据变换矩阵计算组件在全局空间(canvas)中的旋转角度。
+     * @returns
+     */
+    getRotateAngle(): number;
+    getLocalLeftTop(): {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    containsPoint(x: number, y: number): boolean;
+    /**
+     * @method destory
+     * 销毁组件
+     * - FIXME:立即停止组件上的所有动画效果
+     * - 需要清理绑定的事件
+     * - 带有子节点的组件需要先销毁子节点，然后再销毁自身。
+     */
+    destory(): void;
+}
+export default ICEComponent;

package/dist/types/graphic/ICEDotPath.d.ts

@@ -0,0 +1,59 @@
+import ICEPath from './ICEPath';
+/**
+ * @class ICEDotPath
+ *
+ * 基于一系列点进行绘制的路径。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+export default abstract class ICEDotPath extends ICEPath {
+    /**
+     * @cfg
+     * {
+     *   dots: [],       //点状路径的点集
+     *   closePath:true, //是否闭合
+     * }
+     *
+     * @param props
+     */
+    constructor(props: any);
+    /**
+     * 计算原始的宽高、位置，此时没有经过任何变换，也没有移动坐标原点。
+     * 由于点状路径可能是不规则的形状，所以宽高需要手动计算，特殊形状的子类需要覆盖此方法提供自己的实现。
+     * 在计算组件的原始尺寸时还没有确定原点坐标，所以只能基于组件本地坐标系的左上角 (0,0) 点进行计算。
+     * @overwrite
+     * @returns
+     */
+    calcComponentParams(): {
+        width: any;
+        height: any;
+    };
+    /**
+     * 点状路径在重新计算本地原点坐标之后，需要移动内部所有点的位置。
+     * @overwrite
+     * @returns
+     */
+    protected calcLocalOrigin(): number[];
+    /**
+     * @returns
+     */
+    protected createPathObject(): Path2D;
+    /**
+     * 计算路径上的关键点:
+     * - 默认的坐标原点是 (0,0) 位置。
+     * - 这些点没有经过 transform 矩阵变换。
+     * this.calcComponentParams() 会依赖此方法，在计算尺寸时还没有确定原点坐标，所以 calcDots() 方法内部不能依赖原点坐标，只能基于组件本地坐标系的左上角 (0,0) 点进行计算。
+     * @returns
+     */
+    protected calcDots(): any;
+    /**
+     *
+     * 计算4个顶点：
+     * - 相对于组件本地的坐标系，原点位于左上角，没有经过矩阵变换。
+     * - 返回值用于计算组件的原始 width/height 。
+     *
+     * @returns
+     */
+    protected calc4VertexPoints(): any[][];
+    protected getTransformedDots(): any[];
+}

package/dist/types/graphic/ICEImage.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) 2022 大漠穷秋.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import ICEComponent from './ICEComponent';
+/**
+ * @class ICEImage
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class ICEImage extends ICEComponent {
+    constructor(props?: any);
+    protected doRender(): void;
+}
+export default ICEImage;

package/dist/types/graphic/ICEPath.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Copyright (c) 2022 大漠穷秋.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import ICEComponent from './ICEComponent';
+/**
+ * @class ICEPath
+ *
+ * 路径
+ *
+ * @abstract
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare abstract class ICEPath extends ICEComponent {
+    path2D: Path2D;
+    /**
+     * @cfg
+     * {
+     *   dots:[]  //可选参数，路径上的点。
+     * }
+     * @param props
+     */
+    constructor(props?: any);
+    /**
+     * @method doRender
+     * @overwrite
+     */
+    protected doRender(): void;
+    /**
+     * @method createPathObject
+     * 创建 Path2D 对象，子类需要提供具体实现，此方法仅创建对象实例，不会立即绘制到画布上，绘制过程由 Renderer 进行调度。
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/Path2D/Path2D
+     */
+    protected abstract createPathObject(): Path2D;
+}
+export default ICEPath;