补强注释

src/source/app/TetrisLayout.cpp

@@ -1,8 +1,15 @@
 #include "stdafx.h"
+/**
+ * @file TetrisLayout.cpp
+ * @brief 实现窗口缩放布局和各类按钮、卡片、列表项的点击区域计算。
+ */
+
 #include "TetrisAppInternal.h"
 
 /**
  * @brief 将指定滚动偏移按步长调整，并限制在非负范围内。
+ * @param scrollOffset 需要修改的滚动偏移。
+ * @param delta 本次滚动增量。
  */
 void AdjustScrollOffset(int& scrollOffset, int delta)
 {
@@ -19,6 +26,9 @@ void AdjustScrollOffset(int& scrollOffset, int delta)
 
 /**
  * @brief 按当前窗口缩放返回一次滚动操作的像素距离。
+ * @param hWnd 当前窗口句柄。
+ * @param baseStep 设计稿中的基础滚动步长。
+ * @return 缩放后的滚动步长。
  */
 int GetScrollStep(HWND hWnd, int baseStep)
 {
@@ -28,6 +38,8 @@ int GetScrollStep(HWND hWnd, int baseStep)
 
 /**
  * @brief 根据当前窗口大小计算整体界面缩放与偏移。
+ * @param hWnd 当前窗口句柄。
+ * @return 布局缩放、偏移和网格尺寸。
  */
 LayoutMetrics GetLayoutMetrics(HWND hWnd)
 {
@@ -56,6 +68,9 @@ LayoutMetrics GetLayoutMetrics(HWND hWnd)
 
 /**
  * @brief 按当前布局比例缩放一个尺寸值。
+ * @param metrics 当前布局参数。
+ * @param value 设计稿尺寸值。
+ * @return 缩放后的像素尺寸。
  */
 int ScaleValue(const LayoutMetrics& metrics, int value)
 {
@@ -64,6 +79,9 @@ int ScaleValue(const LayoutMetrics& metrics, int value)
 
 /**
  * @brief 按当前布局比例缩放横坐标并叠加窗口偏移。
+ * @param metrics 当前布局参数。
+ * @param value 设计稿横坐标。
+ * @return 实际窗口横坐标。
  */
 int ScaleXValue(const LayoutMetrics& metrics, int value)
 {
@@ -72,12 +90,20 @@ int ScaleXValue(const LayoutMetrics& metrics, int value)
 
 /**
  * @brief 按当前布局比例缩放纵坐标并叠加窗口偏移。
+ * @param metrics 当前布局参数。
+ * @param value 设计稿纵坐标。
+ * @return 实际窗口纵坐标。
  */
 int ScaleYValue(const LayoutMetrics& metrics, int value)
 {
     return metrics.offsetY + MulDiv(value, metrics.scale, 1000);
 }
 
+/**
+ * @brief 获取主菜单中央卡片区域。
+ * @param hWnd 当前窗口句柄。
+ * @return 菜单卡片在窗口中的矩形区域。
+ */
 static RECT GetMenuCardRect(HWND hWnd)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -91,6 +117,12 @@ static RECT GetMenuCardRect(HWND hWnd)
     return rect;
 }
 
+/**
+ * @brief 获取主菜单选项的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @param index 菜单选项序号。
+ * @return 选项在窗口中的矩形区域。
+ */
 RECT GetMenuOptionRect(HWND hWnd, int index)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -106,6 +138,11 @@ RECT GetMenuOptionRect(HWND hWnd, int index)
     return rect;
 }
 
+/**
+ * @brief 获取帮助页卡片区域。
+ * @param hWnd 当前窗口句柄。
+ * @return 帮助卡片在窗口中的矩形区域。
+ */
 static RECT GetRulesCardRect(HWND hWnd)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -119,6 +156,12 @@ static RECT GetRulesCardRect(HWND hWnd)
     return rect;
 }
 
+/**
+ * @brief 获取帮助页首页选项的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @param index 帮助选项序号。
+ * @return 选项在窗口中的矩形区域。
+ */
 RECT GetHelpOptionRect(HWND hWnd, int index)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -143,6 +186,12 @@ RECT GetHelpOptionRect(HWND hWnd, int index)
     return rect;
 }
 
+/**
+ * @brief 获取技能演示列表项的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @param index 技能演示条目序号。
+ * @return 条目在窗口中的矩形区域。
+ */
 RECT GetHelpSkillDemoItemRect(HWND hWnd, int index)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -167,6 +216,11 @@ RECT GetHelpSkillDemoItemRect(HWND hWnd, int index)
     return rect;
 }
 
+/**
+ * @brief 获取帮助页底部返回提示的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @return 返回提示在窗口中的矩形区域。
+ */
 RECT GetHelpBackHintRect(HWND hWnd)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -181,6 +235,12 @@ RECT GetHelpBackHintRect(HWND hWnd)
     return rect;
 }
 
+/**
+ * @brief 获取致谢页左右箭头按钮区域。
+ * @param hWnd 当前窗口句柄。
+ * @param direction 小于 0 为左箭头，大于 0 为右箭头。
+ * @return 箭头按钮在窗口中的矩形区域。
+ */
 RECT GetCreditArrowRect(HWND hWnd, int direction)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -201,6 +261,11 @@ RECT GetCreditArrowRect(HWND hWnd, int direction)
     return rect;
 }
 
+/**
+ * @brief 获取升级选择覆盖层区域。
+ * @param hWnd 当前窗口句柄。
+ * @return 覆盖层在窗口中的矩形区域。
+ */
 static RECT GetUpgradeOverlayRect(HWND hWnd)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -214,6 +279,12 @@ static RECT GetUpgradeOverlayRect(HWND hWnd)
     return rect;
 }
 
+/**
+ * @brief 获取升级选择卡片的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @param index 强化卡片序号。
+ * @return 卡片在窗口中的矩形区域。
+ */
 RECT GetUpgradeCardRect(HWND hWnd, int index)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -242,6 +313,11 @@ RECT GetUpgradeCardRect(HWND hWnd, int index)
     return rect;
 }
 
+/**
+ * @brief 获取暂停或结束提示覆盖层区域。
+ * @param hWnd 当前窗口句柄。
+ * @return 覆盖层在窗口中的矩形区域。
+ */
 static RECT GetGameOverlayRect(HWND hWnd)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -260,6 +336,13 @@ static RECT GetGameOverlayRect(HWND hWnd)
     return rect;
 }
 
+/**
+ * @brief 获取暂停或结束覆盖层按钮的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @param index 按钮序号。
+ * @param buttonCount 当前覆盖层按钮总数。
+ * @return 按钮在窗口中的矩形区域。
+ */
 RECT GetOverlayButtonRect(HWND hWnd, int index, int buttonCount)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -274,6 +357,11 @@ RECT GetOverlayButtonRect(HWND hWnd, int index, int buttonCount)
     return rect;
 }
 
+/**
+ * @brief 获取左上角返回按钮的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @return 返回按钮在窗口中的矩形区域。
+ */
 RECT GetBackButtonRect(HWND hWnd)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -287,6 +375,11 @@ RECT GetBackButtonRect(HWND hWnd)
     return rect;
 }
 
+/**
+ * @brief 获取右下角音乐按钮的点击区域。
+ * @param hWnd 当前窗口句柄。
+ * @return 音乐按钮在窗口中的矩形区域。
+ */
 RECT GetMusicButtonRect(HWND hWnd)
 {
     LayoutMetrics metrics = GetLayoutMetrics(hWnd);
@@ -316,6 +409,13 @@ RECT GetMusicButtonRect(HWND hWnd)
     return buttonRect;
 }
 
+/**
+ * @brief 判断点坐标是否落在矩形内部。
+ * @param rect 待判断矩形。
+ * @param x 点的横坐标。
+ * @param y 点的纵坐标。
+ * @return 点在矩形内返回 true，否则返回 false。
+ */
 bool IsPointInRect(const RECT& rect, int x, int y)
 {
     return x >= rect.left && x < rect.right && y >= rect.top && y < rect.bottom;