Parcourir la source

base:docs> 添加注释
draw:docs> 添加注释

sybotan il y a 4 ans
Parent
commit
c3ca55b2b7

+ 7 - 5
persagy-web-base/src/SMatrix.ts

@@ -309,8 +309,8 @@ export class SMatrix {
      * 旋转变形
      *
      * @param rotX  绕 X 轴旋转角度(单位角度 度)
-     * @param rotY  绕 X 轴旋转角度(单位角度 度)
-     * @param rotZ  绕 X 轴旋转角度(单位角度 度)
+     * @param rotY  绕 Y 轴旋转角度(单位角度 度)
+     * @param rotZ  绕 Z 轴旋转角度(单位角度 度)
      * @return 返回自身
      */
     rotate(rotX: number, rotY: number, rotZ: number): SMatrix;
@@ -319,12 +319,14 @@ export class SMatrix {
      * 旋转变形
      *
      * @param rotX  绕 Z 轴旋转角度 | 绕 X 轴旋转角度(单位度)
-     * @param rotY  绕 X 轴旋转角度(单位度)
-     * @param rotZ  绕 X 轴旋转角度(单位度)
+     * @param rotY  绕 Y 轴旋转角度(单位度)
+     * @param rotZ  绕 Z 轴旋转角度(单位度)
      * @return 返回自身
      */
     rotate(rotX: number, rotY?: number, rotZ?: number): SMatrix {
         const matZ = new SMatrix();
+
+        // 重载实现了 rotate(rotX: number, rotY: number, rotZ: number): SMatrix;
         if (rotY != undefined && rotZ != undefined) {
             const matX = new SMatrix();
             matX.m22 = Math.cos((rotX * Math.PI) / 180);
@@ -346,7 +348,7 @@ export class SMatrix {
             matZ.m22 = Math.cos((rotZ * Math.PI) / 180);
             this.multiply(matZ);
             return this;
-        } else {
+        } else { // 重载实现了 rotate(angle: number): SMatrix;
             matZ.m11 = Math.cos((rotX * Math.PI) / 180);
             matZ.m21 = -Math.sin((rotX * Math.PI) / 180);
             matZ.m12 = Math.sin((rotX * Math.PI) / 180);

+ 3 - 1
persagy-web-base/src/SMouseEvent.ts

@@ -79,6 +79,8 @@ export class SMouseEvent {
         this.ctrlKey = event.ctrlKey;
         this.shiftKey = event.shiftKey;
         this.buttons = event.buttons;
+
+        // 如果是图形引擎定义的鼠标事件
         if (event instanceof SMouseEvent) {
             this.x = event.x;
             this.y = event.y;
@@ -98,7 +100,7 @@ export class SMouseEvent {
             this.matrix.m42 = event.matrix.m42;
             this.matrix.m43 = event.matrix.m43;
             this.matrix.m44 = event.matrix.m44;
-        } else {
+        } else { // 否则是浏览器 canvas 鼠标事件
             this.x = event.offsetX;
             this.y = event.offsetY;
         }

+ 16 - 2
persagy-web-base/src/SObject.ts

@@ -49,12 +49,15 @@ export class SObject {
     connect(name: string, receiver: any, callback: Function): void {
         // @ts-ignore
         let observerList = this.listeners[name];
+
+        // 如果观察者队列为空
         if (!observerList) {
             // @ts-ignore
             this.listeners[name] = [];
-        } else {
-            // 如果已经连接,则返回
+        } else { // 否则
+            // 遍历观察者队列
             for (let observer of observerList) {
+                // 如果已经连接,则返回
                 if (observer.compar(receiver)) {
                     return;
                 }
@@ -75,18 +78,26 @@ export class SObject {
     disconnect(name: string, receiver: any): void {
         // @ts-ignore
         let observerList = this.listeners[name];
+
+        // 如果观察者队列为空
         if (!observerList) {
             return;
         }
 
         let length = observerList.length;
+
+        // 遍历观察者队列
         for (let i = 0; i < length; i++) {
             let observer = observerList[i];
+
+            // 如果已经连接,则返回
             if (observer.compar(receiver)) {
                 observerList.splice(i, 1);
                 break;
             }
         }
+
+        // 如果观察者队列为空
         if (observerList.length == 0) {
             // @ts-ignore
             delete this.listeners[name];
@@ -103,10 +114,13 @@ export class SObject {
     $emit(name: string, ...args: any): void {
         // @ts-ignore
         let observerList = this.listeners[name];
+
+        // 如果观察者队列为空
         if (!observerList) {
             return;
         }
 
+        // 遍历观察者队列
         for (let observer of observerList) {
             observer.notify(this, args);
         }

+ 8 - 4
persagy-web-base/src/undo/SUndoStack.ts

@@ -55,8 +55,8 @@ export class SUndoStack extends SObject {
      * 执行 redo 操作
      */
     redo(): void {
+        // 不能执行 redo ,直接返回
         if (!this.canRedo()) {
-            // 不能执行 redo ,直接返回
             return;
         }
 
@@ -69,8 +69,8 @@ export class SUndoStack extends SObject {
      * 执行 undo 操作
      */
     undo(): void {
+        // 不能执行 undo ,直接返回
         if (!this.canUndo()) {
-            // 不能执行 undo ,直接返回
             return;
         }
 
@@ -112,9 +112,8 @@ export class SUndoStack extends SObject {
      * @param index     命令在栈中的索引
      */
     command(index: number): SUndoCommand | null {
+        // 如果索引越界,返回 null
         if (index < 0 || index >= this.cmdStack.length) {
-            // 如果索引越界
-            // 返回null
             return null;
         }
 
@@ -135,6 +134,8 @@ export class SUndoStack extends SObject {
      */
     push(cmd: SUndoCommand): void {
         this.cmdStack.length = this._index + 1;
+
+        // 索引有效而且可以合并命令
         if (this._index >= 0 && cmd.mergeWith(this.cmdStack[this._index])) {
             return;
         }
@@ -149,6 +150,8 @@ export class SUndoStack extends SObject {
      */
     toLog(): SCommandLog[] {
         let stackList: SCommandLog[] = [];
+
+        // 遍历命令堆栈
         for (let i = 0; i <= this.index; i++) {
             stackList.push({
                 command: this.cmdStack[i].command,
@@ -156,6 +159,7 @@ export class SUndoStack extends SObject {
                 detail: this.cmdStack[i].toString()
             });
         }
+
         return stackList;
     }
 }

+ 4 - 3
persagy-web-draw/src/SBrush.ts

@@ -88,17 +88,18 @@ export class SBrush {
      * @param brush     画笔
      */
     constructor(brush?: SColor | SGradient | SBrush) {
+        // 实现重载 constructor();
         if (brush == undefined) {
             return;
         }
 
-        // 如果是渐变类型
+        // 实现重载 constructor(gradient: SGradient);
         if (brush instanceof SGradient) {
             this.gradient = brush;
-        } else if (brush instanceof SBrush) {
+        } else if (brush instanceof SBrush) { // 实现重载 constructor(brush: SBrush);
             this.type = brush.type;
             this.color = new SColor(brush.color);
-        } else {
+        } else { // 实现重载 constructor(color: SColor);
             this.color = new SColor(brush);
         }
     }

+ 30 - 13
persagy-web-draw/src/SCanvasView.ts

@@ -65,9 +65,11 @@ export class SCanvasView extends SObject {
         return this._origin;
     }
     set origin(v: SPoint) {
+        // 如果不可移动
         if (!this.moveable) {
             return;
         }
+
         this._origin.x = v.x;
         this._origin.y = v.y;
         this._needDraw = true;
@@ -81,9 +83,11 @@ export class SCanvasView extends SObject {
         return this._scale;
     }
     set scale(v: number) {
+        // 如果不可缩放
         if (!this.scalable) {
             return;
         }
+
         this._scale = v;
         this._needDraw = true;
     }
@@ -116,8 +120,6 @@ export class SCanvasView extends SObject {
         this.canvasView.style.cursor = v;
     }
 
-    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-    //
     /**
      * 构造函数
      *
@@ -191,21 +193,21 @@ export class SCanvasView extends SObject {
      * @param y0          缩放计算的中心点 Y 坐标
      */
     scaleByPoint(zoom: number, x0: number, y0: number): void {
+        // 如果不可缩放
         if (!this.scalable) {
             return;
         }
 
         let z = zoom;
-        /**
-         * 缩放比例在最小比例和最大比例范围内
-         */
+
+        // 缩放比例大于等于最大缩放比例
         if (this.scale * zoom >= this.maxScale) {
             z = this.maxScale / this.scale;
             this.scale = this.maxScale;
-        } else if (this.scale * zoom <= this.minScale) {
+        } else if (this.scale * zoom <= this.minScale) { // 缩放比例小于等于最小缩放比例
             z = this.minScale / this.scale;
             this.scale = this.minScale;
-        } else {
+        } else { // 缩放比例在最小比例和最大比例范围内
             this.scale *= zoom;
         }
 
@@ -213,19 +215,17 @@ export class SCanvasView extends SObject {
         this.origin.y = y0 - (y0 - this.origin.y) * z;
     }
 
-    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-    //
     /**
      * 循环
      */
     protected loop(): void {
-        /** painter 对象 */
-        let ctx = this.canvas;
-        if (null != ctx && this._needDraw) {
+        // 存在 canvas 对象,并且需要刷新
+        if (null != this.canvas && this._needDraw) {
             this._needDraw = false;
             let painter = new SPainter(this);
             this.onDraw(painter);
         }
+
         this.requestAnimationFrame(this.loop.bind(this));
     }
 
@@ -257,6 +257,8 @@ export class SCanvasView extends SObject {
      */
     protected onMouseDown(event: MouseEvent): void {
         let se = new SMouseEvent(event);
+
+        // 按下鼠标中键
         if (se.buttons & SMouseButton.MidButton) {
             this._midKeyPos.x = se.x;
             this._midKeyPos.y = se.y;
@@ -273,6 +275,8 @@ export class SCanvasView extends SObject {
         if (this.moveable) {
             // 按中键移动
             let se = new SMouseEvent(event);
+
+            // 按下鼠标中键
             if (se.buttons & SMouseButton.MidButton) {
                 this.origin.x += se.x - this._midKeyPos.x;
                 this.origin.y += se.y - this._midKeyPos.y;
@@ -304,9 +308,10 @@ export class SCanvasView extends SObject {
      * @param event       事件参数
      */
     protected onMouseWheel(event: WheelEvent): void {
+        // TODO: hanjianlong 补
         if (event.deltaY < 0) {
             this.scaleByPoint(this.wheelZoom, event.offsetX, event.offsetY);
-        } else {
+        } else { // TODO: hanjianlong 补
             this.scaleByPoint(1 / this.wheelZoom, event.offsetX, event.offsetY);
         }
     }
@@ -339,10 +344,14 @@ export class SCanvasView extends SObject {
      */
     protected onTouchStart(event: TouchEvent): void {
         let touches = event.touches;
+
+        // 单点触摸
         if (touches.length == 1) {
             this._touchPoint.x = event.touches[0].clientX;
             this._touchPoint.y = event.touches[0].clientY;
         }
+
+        // 两点触摸
         if (touches.length == 2) {
             this._touchState = STouchState.Zoom;
             this._beforeLength = this.getDistance(event);
@@ -356,12 +365,16 @@ export class SCanvasView extends SObject {
      */
     protected onTouchMove(event: TouchEvent): void {
         let touches = event.touches;
+
+        // 单点触摸移动
         if (touches.length == 1) {
             this.origin.x += event.touches[0].clientX - this._touchPoint.x;
             this.origin.y += event.touches[0].clientY - this._touchPoint.y;
             this._touchPoint.x = event.touches[0].clientX;
             this._touchPoint.y = event.touches[0].clientY;
         }
+
+        // 两点触摸缩放
         if (touches.length == 2) {
             this.viewZoom(event);
         }
@@ -433,11 +446,14 @@ export class SCanvasView extends SObject {
      * @param event       触摸事件
      */
     private viewZoom(event: TouchEvent): boolean {
+        // 如果是缩放
         if (this._touchState == STouchState.Zoom) {
             // 获取两点的距离
             this._afterLength = this.getDistance(event);
             // 变化的长度;
             let gapLenght = this._afterLength - this._beforeLength;
+
+            // 两指操作变化距离超过 5 缩放(防抖)
             if (Math.abs(gapLenght) > 5 && this._beforeLength != 0.0) {
                 // 求的缩放的比例
                 let tempScale = this._afterLength / this._beforeLength;
@@ -457,6 +473,7 @@ export class SCanvasView extends SObject {
      * @return 两手指之间的距离
      */
     private getDistance(event: TouchEvent): number {
+        // 两指操作距离小于 2 不做处理
         if (event.touches.length < 2) {
             return 0;
         }

+ 7 - 7
persagy-web-draw/src/SColor.ts

@@ -94,7 +94,6 @@ export class SColor {
         return new SColor(r, g, b, a);
     }
 
-    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
     // 属性定义
     /** 红色分量 */
     get red(): number {
@@ -138,20 +137,20 @@ export class SColor {
         return "#" + SStringUtil.num2Hex(this._value, 8);
     }
     set value(v: string) {
+        // 传入值不是"#"开头,无效值返回
         if (v.substr(0, 1) != "#") {
             return;
         }
 
         // 先去“#”,再转换16进制数
         this._value = parseInt(v.substr(1), 16);
+
         // 如果未写alpha值,则左移8位+0xff;
         if (v.length == 7) {
             this._value = (this._value << 8) + 0xff;
         }
     }
 
-    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-    // 构造函数
     /**
      * 构造函数
      */
@@ -204,15 +203,16 @@ export class SColor {
         b?: number,
         a?: number
     ) {
+        // 重载 constructor();
         if (r == undefined) {
             this._value = 0xff;
-        } else if (typeof r == "string") {
+        } else if (typeof r == "string") { // 重载 constructor(color: string);
             this.value = r;
-        } else if (r instanceof SColor) {
+        } else if (r instanceof SColor) { // 重载 constructor(color: SColor);
             this._value = r._value;
-        } else if (a == undefined) {
+        } else if (a == undefined) { // 重载 constructor(r: number, g: number, b: number);
             this.setRgb(r as number, g as number, b as number);
-        } else {
+        } else { // 重载 constructor(r: number, g: number, b: number, a: number);
             this.setRgba(r as number, g as number, b as number, a as number);
         }
     }