feat(docstring):添加部分docstring (#376)

* feat(docstring):添加docstring Signed-off-by: doudou0720 <98651603+doudou0720@users.noreply.github.com> * fix(docstring):修复部分docstring格式错误 Signed-off-by: doudou0720 <98651603+doudou0720@users.noreply.github.com> * fix(docstring):修复部分docstring Signed-off-by: doudou0720 <98651603+doudou0720@users.noreply.github.com> * chore(Docstring):MW_* 前14 * chore(Docstring):MW_* part 2 * chore(Docstring):MW_* part 3 * chore:优化缩进 * fix: 修复数学计算中的潜在除零错误和数值稳定性问题 Signed-off-by: doudou0720 <98651603+doudou0720@users.noreply.github.com> * chore:删除Rebase时多余的OOBE函数 * chore: 更新代码注释和文档格式修复XML文档注释中的格式问题，统一使用<c>和<see>标签更新ConfigHelper类的预留说明，明确未来扩展用途优化TimerDisplayDate_Elapsed方法的注释，说明UI异步更新机制合并重复的注释摘要行，提高文档可读性添加形状识别功能的64位进程限制说明修正视频呈现器设备选择逻辑的文档说明 * chore(IPPTLinkManager): 更新TryEndSlideShow方法的XML注释格式 * chore: 修正代码注释中的术语和格式问题更新多个文件中的XML注释，统一使用<see langword="..."/>标记代替<c>...</c>标记规范术语使用（如"延迟初始化"代替"懒惰初始化"）修正注释中的格式错误和补充说明调整代码区域的注释对齐格式 --------- Signed-off-by: doudou0720 <98651603+doudou0720@users.noreply.github.com>
2026-02-22 10:14:12 +08:00
parent 3e3db27296
commit 656863a7d0
48 changed files with 6220 additions and 192 deletions
@@ -17,17 +17,39 @@ namespace Ink_Canvas
    {
        #region Multi-Touch

+        /// <summary>
+        /// 是否处于多点触控模式
+        /// </summary>
        private bool isInMultiTouchMode;
+        /// <summary>
+        /// 存储触摸设备ID的列表
+        /// </summary>
        private List<int> dec = new List<int>();
+        /// <summary>
+        /// 是否处于单指拖动模式
+        /// </summary>
        private bool isSingleFingerDragMode;
+        /// <summary>
+        /// 中心点坐标
+        /// </summary>
        private Point centerPoint = new Point(0, 0);
+        /// <summary>
+        /// 上次的InkCanvas编辑模式
+        /// </summary>
        private InkCanvasEditingMode lastInkCanvasEditingMode = InkCanvasEditingMode.Ink;
+        /// <summary>
+        /// 上次触摸按下的时间
+        /// </summary>
        private DateTime lastTouchDownTime = DateTime.MinValue;
+        /// <summary>
+        /// 多点触控延迟时间（毫秒）
+        /// </summary>
        private const double MULTI_TOUCH_DELAY_MS = 100;

-        /// </summary> 
+        /// <summary>
        /// 保存画布上的非笔画元素（如图片、媒体元素等）
        /// </summary>
+        /// <returns>返回保存的非笔画元素列表</returns>
        private List<UIElement> PreserveNonStrokeElements()
        {
            var preservedElements = new List<UIElement>();
@@ -164,6 +186,27 @@ namespace Ink_Canvas
            }
        }

+        /// <summary>
+        /// 多点触控模式切换按钮的鼠标抬起事件处理方法
+        /// </summary>
+        /// <param name="sender">事件发送者</param>
+        /// <param name="e">鼠标按钮事件参数</param>
+        /// <remarks>
+        /// 切换多点触控模式和单点触控模式，包括以下步骤：
+        /// 1. 如果当前处于多点触控模式，则切换到单点触控模式
+        ///    - 移除手写笔和触摸事件处理程序
+        ///    - 添加触摸事件处理程序
+        ///    - 设置InkCanvas编辑模式为Ink（如果当前不是橡皮擦模式）
+        ///    - 保存并恢复非笔画元素
+        ///    - 设置isInMultiTouchMode为false
+        /// 2. 如果当前处于单点触控模式，则切换到多点触控模式
+        ///    - 添加手写笔事件处理程序
+        ///    - 添加触摸事件处理程序
+        ///    - 移除触摸事件处理程序
+        ///    - 设置InkCanvas编辑模式为None（如果当前不是橡皮擦模式）
+        ///    - 保存并恢复非笔画元素
+        ///    - 设置isInMultiTouchMode为true
+        /// </remarks>
        private void BorderMultiTouchMode_MouseUp(object sender, MouseButtonEventArgs e)
        {
            if (isInMultiTouchMode)
@@ -208,6 +251,24 @@ namespace Ink_Canvas
            }
        }

+        /// <summary>
+        /// 主窗口的触摸按下事件处理方法
+        /// </summary>
+        /// <param name="sender">事件发送者</param>
+        /// <param name="e">触摸事件参数</param>
+        /// <remarks>
+        /// 处理触摸按下事件，包括以下逻辑：
+        /// 1. 如果当前处于橡皮擦模式或选择模式，则直接返回
+        /// 2. 如果当前没有隐藏子面板，则隐藏子面板
+        /// 3. 如果当前处于图形绘制模式，则：
+        ///    - 设置InkCanvas编辑模式为None
+        ///    - 设置触摸状态为按下
+        ///    - 禁用浮动栏和黑板UI网格的命中测试
+        ///    - 设置起始点坐标
+        ///    - 直接返回
+        /// 4. 否则，设置触摸按下点的编辑模式为None
+        /// 5. 如果当前不是橡皮擦模式，则设置InkCanvas编辑模式为None
+        /// </remarks>
        private void MainWindow_TouchDown(object sender, TouchEventArgs e)
        {

@@ -244,6 +305,26 @@ namespace Ink_Canvas
            }
        }

+        /// <summary>
+        /// 主窗口的手写笔按下事件处理方法
+        /// </summary>
+        /// <param name="sender">事件发送者</param>
+        /// <param name="e">手写笔按下事件参数</param>
+        /// <remarks>
+        /// 处理手写笔按下事件，包括以下逻辑：
+        /// 1. 检查手写笔点击是否发生在浮动栏区域，如果是则允许事件传播到浮动栏按钮并返回
+        /// 2. 根据手写笔是否倒置自动切换橡皮擦/画笔模式：
+        ///    - 如果手写笔倒置，设置编辑模式为EraseByPoint
+        ///    - 如果手写笔正常：
+        ///       - 如果当前处于图形绘制模式，设置编辑模式为None，设置触摸状态为按下，禁用浮动栏和黑板UI网格的命中测试，设置起始点坐标并返回
+        ///       - 如果当前不是线擦模式，设置编辑模式为Ink
+        ///       - 否则，保持当前线擦模式
+        /// 3. 捕获手写笔输入
+        /// 4. 禁用浮动栏和黑板UI网格的命中测试
+        /// 5. 根据编辑模式设置光标
+        /// 6. 如果当前处于橡皮擦模式或选择模式，则直接返回
+        /// 7. 设置触摸按下点的编辑模式为None
+        /// </remarks>
        private void MainWindow_StylusDown(object sender, StylusDownEventArgs e)
        {
            // 检查手写笔点击是否发生在浮动栏区域，如果是则允许事件传播到浮动栏按钮
@@ -301,6 +382,30 @@ namespace Ink_Canvas
            TouchDownPointsList[e.StylusDevice.Id] = InkCanvasEditingMode.None;
        }

+        /// <summary>
+        /// 主窗口的手写笔抬起事件处理方法
+        /// </summary>
+        /// <param name="sender">事件发送者</param>
+        /// <param name="e">手写笔事件参数</param>
+        /// <remarks>
+        /// 处理手写笔抬起事件，包括以下逻辑：
+        /// 1. 如果当前处于图形绘制模式：
+        ///    - 重置触摸状态
+        ///    - 启用浮动栏和黑板UI网格的命中测试
+        ///    - 对于双曲线等需要多步绘制的图形，根据当前步骤决定是进入下一步还是完成绘制
+        ///    - 对于其他单步绘制的图形，直接完成绘制
+        ///    - 直接返回
+        /// 2. 否则，尝试获取并处理笔画：
+        ///    - 获取笔画视觉对象的笔画
+        ///    - 如果笔画不为空，将其添加到InkCanvas，移除视觉画布，并触发笔画收集事件
+        ///    - 如果笔画为空，仅移除视觉画布
+        /// 3. 清理相关资源：
+        ///    - 从StrokeVisualList、VisualCanvasList和TouchDownPointsList中移除当前手写笔设备ID
+        ///    - 如果列表为空，清除所有手写笔预览相关的Canvas并清空列表
+        /// 4. 释放手写笔捕获
+        /// 5. 启用浮动栏和黑板UI网格的命中测试
+        /// 6. 根据编辑模式设置光标
+        /// </remarks>
        private async void MainWindow_StylusUp(object sender, StylusEventArgs e)
        {
            if (drawingShapeMode != 0)
@@ -396,6 +501,22 @@ namespace Ink_Canvas
            SetCursorBasedOnEditingMode(inkCanvas);
        }

+        /// <summary>
+        /// 主窗口的手写笔移动事件处理方法
+        /// </summary>
+        /// <param name="sender">事件发送者</param>
+        /// <param name="e">手写笔事件参数</param>
+        /// <remarks>
+        /// 处理手写笔移动事件，包括以下逻辑：
+        /// 1. 如果当前处于图形绘制模式且触摸状态为按下：
+        ///    - 获取手写笔在InkCanvas上的位置
+        ///    - 调用MouseTouchMove方法处理移动
+        ///    - 直接返回
+        /// 2. 如果触摸按下点的编辑模式不是None，则直接返回
+        /// 3. 尝试检查手写笔按钮状态，如果第二个按钮被按下，则直接返回
+        /// 4. 否则，获取笔画视觉对象，添加手写笔点，并重新绘制
+        /// 5. 捕获并忽略所有异常
+        /// </remarks>
        private void MainWindow_StylusMove(object sender, StylusEventArgs e)
        {
            try
@@ -427,6 +548,20 @@ namespace Ink_Canvas
            catch (Exception ex) { System.Diagnostics.Debug.WriteLine(ex); }
        }

+        /// <summary>
+        /// 获取笔画视觉对象方法
+        /// </summary>
+        /// <param name="id">设备ID</param>
+        /// <returns>返回笔画视觉对象</returns>
+        /// <remarks>
+        /// 根据设备ID获取笔画视觉对象，如果不存在则创建新的：
+        /// 1. 尝试从StrokeVisualList中获取笔画视觉对象
+        /// 2. 如果不存在，创建新的StrokeVisual实例，使用InkCanvas的默认绘制属性的克隆
+        /// 3. 将新的笔画视觉对象添加到StrokeVisualList
+        /// 4. 创建新的VisualCanvas实例，将其设置为笔画视觉对象的视觉画布
+        /// 5. 将新的视觉画布添加到VisualCanvasList和InkCanvas的子元素中
+        /// 6. 返回笔画视觉对象
+        /// </remarks>
        private StrokeVisual GetStrokeVisual(int id)
        {
            if (StrokeVisualList.TryGetValue(id, out var visual)) return visual;
@@ -441,20 +576,45 @@ namespace Ink_Canvas
            return strokeVisual;
        }

+        /// <summary>
+        /// 获取视觉画布方法
+        /// </summary>
+        /// <param name="id">设备ID</param>
+        /// <returns>返回视觉画布对象，如果不存在则返回null</returns>
+        /// <remarks>
+        /// 根据设备ID从VisualCanvasList中获取视觉画布对象
+        /// </remarks>
        private VisualCanvas GetVisualCanvas(int id)
        {
            return VisualCanvasList.TryGetValue(id, out var visualCanvas) ? visualCanvas : null;
        }

+        /// <summary>
+        /// 获取触摸按下点的编辑模式方法
+        /// </summary>
+        /// <param name="id">设备ID</param>
+        /// <returns>返回触摸按下点的编辑模式，如果不存在则返回InkCanvas的当前编辑模式</returns>
+        /// <remarks>
+        /// 根据设备ID从TouchDownPointsList中获取触摸按下点的编辑模式
+        /// </remarks>
        private InkCanvasEditingMode GetTouchDownPointsList(int id)
        {
            return TouchDownPointsList.TryGetValue(id, out var inkCanvasEditingMode) ? inkCanvasEditingMode : inkCanvas.EditingMode;
        }

+        /// <summary>
+        /// 触摸按下点的编辑模式字典，键为设备ID，值为编辑模式
+        /// </summary>
        private Dictionary<int, InkCanvasEditingMode> TouchDownPointsList { get; } =
            new Dictionary<int, InkCanvasEditingMode>();

+        /// <summary>
+        /// 笔画视觉对象字典，键为设备ID，值为笔画视觉对象
+        /// </summary>
        private Dictionary<int, StrokeVisual> StrokeVisualList { get; } = new Dictionary<int, StrokeVisual>();
+        /// <summary>
+        /// 视觉画布字典，键为设备ID，值为视觉画布对象
+        /// </summary>
        private Dictionary<int, VisualCanvas> VisualCanvasList { get; } = new Dictionary<int, VisualCanvas>();

        #endregion
@@ -464,6 +624,26 @@ namespace Ink_Canvas

        private Point iniP = new Point(0, 0);

+        /// <summary>
+        /// 主网格的触摸按下事件处理方法
+        /// </summary>
+        /// <param name="sender">事件发送者</param>
+        /// <param name="e">触摸事件参数</param>
+        /// <remarks>
+        /// 处理主网格的触摸按下事件，包括以下逻辑：
+        /// 1. 检查触摸是否发生在浮动栏区域，如果是则允许事件传播到浮动栏按钮并返回
+        /// 2. 根据编辑模式设置光标
+        /// 3. 捕获触摸输入
+        /// 4. 如果当前处于点擦模式，则直接返回
+        /// 5. 如果当前处于图形绘制模式：
+        ///    - 设置编辑模式为None
+        ///    - 设置触摸状态为按下
+        ///    - 禁用浮动栏和黑板UI网格的命中测试
+        ///    - 设置起始点坐标
+        ///    - 直接返回
+        /// 6. 如果当前处于选择模式、墨水模式或线擦模式，则直接返回
+        /// 7. 如果当前不是橡皮擦模式，则设置编辑模式为Ink
+        /// </remarks>
        private void Main_Grid_TouchDown(object sender, TouchEventArgs e)
        {
            // 检查触摸是否发生在浮动栏区域，如果是则允许事件传播到浮动栏按钮
@@ -518,6 +698,19 @@ namespace Ink_Canvas
            }
        }

+        /// <summary>
+        /// 获取触摸边界宽度方法
+        /// </summary>
+        /// <param name="e">触摸事件参数</param>
+        /// <returns>返回触摸边界宽度</returns>
+        /// <remarks>
+        /// 根据触摸事件参数计算触摸边界宽度，包括以下逻辑：
+        /// 1. 获取触摸点的边界
+        /// 2. 如果不是四边红外屏幕，使用边界宽度
+        /// 3. 如果是四边红外屏幕，使用边界宽度和高度的平方根
+        /// 4. 如果是特殊屏幕，乘以触摸倍数
+        /// 5. 返回计算得到的触摸边界宽度
+        /// </remarks>
        public double GetTouchBoundWidth(TouchEventArgs e)
        {
            var args = e.GetTouchPoint(null).Bounds;
@@ -528,6 +721,25 @@ namespace Ink_Canvas
            return value;
        }

+        /// <summary>
+        /// InkCanvas的预览触摸按下事件处理方法
+        /// </summary>
+        /// <param name="sender">事件发送者</param>
+        /// <param name="e">触摸事件参数</param>
+        /// <remarks>
+        /// 处理InkCanvas的预览触摸按下事件，包括以下逻辑：
+        /// 1. 捕获触摸输入
+        /// 2. 禁用浮动栏和黑板UI网格的命中测试
+        /// 3. 将触摸设备ID添加到dec列表中
+        /// 4. 当只有一个触摸设备时：
+        ///    - 记录中心点坐标
+        ///    - 记录第一根手指点击时的StrokeCollection
+        /// 5. 当有两个或以上触摸设备，或者处于单指拖动模式，或者禁用了双指手势时：
+        ///    - 如果处于多点触控模式或禁用了双指手势，则直接返回
+        ///    - 如果当前编辑模式为None或Select，则直接返回
+        ///    - 记录当前的编辑模式
+        ///    - 设置编辑模式为None，关闭画笔功能
+        /// </remarks>
        private void InkCanvas_PreviewTouchDown(object sender, TouchEventArgs e)
        {
            inkCanvas.CaptureTouch(e.TouchDevice);
@@ -555,10 +767,40 @@ namespace Ink_Canvas
            }
        }

+        /// <summary>
+        /// InkCanvas的预览触摸移动事件处理方法
+        /// </summary>
+        /// <param name="sender">事件发送者</param>
+        /// <param name="e">触摸事件参数</param>
+        /// <remarks>
+        /// 空方法，预留用于处理InkCanvas的预览触摸移动事件
+        /// </remarks>
        private void InkCanvas_PreviewTouchMove(object sender, TouchEventArgs e)
        {
        }

+        /// <summary>
+        /// InkCanvas的预览触摸抬起事件处理方法
+        /// </summary>
+        /// <param name="sender">事件发送者</param>
+        /// <param name="e">触摸事件参数</param>
+        /// <remarks>
+        /// 处理InkCanvas的预览触摸抬起事件，包括以下逻辑：
+        /// 1. 释放所有触摸捕获
+        /// 2. 启用浮动栏和黑板UI网格的命中测试
+        /// 3. 如果有多个触摸设备且当前编辑模式为None，则切回之前的编辑模式
+        /// 4. 从dec列表中移除当前触摸设备ID
+        /// 5. 当没有触摸设备时：
+        ///    - 重置单指拖动模式和等待下一次触摸按下的标志
+        ///    - 如果当前不是图形绘制模式且编辑模式不是橡皮擦或选择模式，则切回之前的编辑模式
+        /// 6. 如果当前处于图形绘制模式：
+        ///    - 重置触摸状态
+        ///    - 启用浮动栏和黑板UI网格的命中测试
+        ///    - 对于双曲线等需要多步绘制的图形，根据当前步骤决定是进入下一步还是完成绘制
+        ///    - 对于其他单步绘制的图形，直接完成绘制
+        /// 7. 设置InkCanvas的透明度为1
+        /// 8. 当没有触摸设备且笔画数量发生变化，且不是绘制长方体的第一次触摸时，保存笔画集合
+        /// </remarks>
        private void InkCanvas_PreviewTouchUp(object sender, TouchEventArgs e)
        {
            inkCanvas.ReleaseAllTouchCaptures();
@@ -635,13 +877,41 @@ namespace Ink_Canvas
                }
        }

+        /// <summary>
+        /// InkCanvas的操作开始事件处理方法
+        /// </summary>
+        /// <param name="sender">事件发送者</param>
+        /// <param name="e">操作开始事件参数</param>
+        /// <remarks>
+        /// 设置操作模式为所有模式
+        /// </remarks>
        private void InkCanvas_ManipulationStarting(object sender, ManipulationStartingEventArgs e)
        {
            e.Mode = ManipulationModes.All;
        }

+        /// <summary>
+        /// InkCanvas的操作惯性开始事件处理方法
+        /// </summary>
+        /// <param name="sender">事件发送者</param>
+        /// <param name="e">操作惯性开始事件参数</param>
+        /// <remarks>
+        /// 空方法，预留用于处理InkCanvas的操作惯性开始事件
+        /// </remarks>
        private void InkCanvas_ManipulationInertiaStarting(object sender, ManipulationInertiaStartingEventArgs e) { }

+        /// <summary>
+        /// 主网格的操作完成事件处理方法
+        /// </summary>
+        /// <param name="sender">事件发送者</param>
+        /// <param name="e">操作完成事件参数</param>
+        /// <remarks>
+        /// 处理主网格的操作完成事件，包括以下逻辑：
+        /// 1. 当没有操作器时：
+        ///    - 清除dec列表
+        ///    - 重置单指拖动模式标志
+        ///    - 如果当前不是图形绘制模式且编辑模式不是橡皮擦或选择模式，则设置编辑模式为Ink
+        /// </remarks>
        private void Main_Grid_ManipulationCompleted(object sender, ManipulationCompletedEventArgs e)
        {
            if (e.Manipulators.Count() == 0)
@@ -663,6 +933,33 @@ namespace Ink_Canvas
            }
        }

+        /// <summary>
+        /// 主网格的操作增量事件处理方法
+        /// </summary>
+        /// <param name="sender">事件发送者</param>
+        /// <param name="e">操作增量事件参数</param>
+        /// <remarks>
+        /// 处理主网格的操作增量事件，包括以下逻辑：
+        /// 1. 如果当前处于多点触控模式或禁用了双指手势，则直接返回
+        /// 2. 检查是否有多个操作器
+        /// 3. 检查是否应该使用双指手势
+        /// 4. 如果应该使用双指手势：
+        ///    - 获取位移矢量
+        ///    - 创建矩阵变换
+        ///    - 如果启用了双指平移，则应用平移变换
+        ///    - 计算中心点（用于缩放和旋转）
+        ///    - 如果启用了双指平移或旋转，则应用旋转变换
+        ///    - 如果启用了双指缩放，则应用缩放变换
+        ///    - 处理选中的笔画：
+        ///       - 对每个选中的笔画应用变换
+        ///       - 对圆形笔画更新半径和中心点
+        ///       - 如果启用了双指缩放，更新笔画的宽度和高度
+        ///    - 处理未选中的笔画：
+        ///       - 对所有笔画应用变换
+        ///       - 如果启用了双指缩放，更新笔画的宽度和高度
+        ///       - 同时变换画布上的图片元素
+        ///       - 对所有圆形笔画更新半径和中心点
+        /// </remarks>
        private void Main_Grid_ManipulationDelta(object sender, ManipulationDeltaEventArgs e)
        {
            if (isInMultiTouchMode || !Settings.Gesture.IsEnableTwoFingerGesture) return;