UI 重构 P0+P1：新增布局/控件基础层与离屏回归网（对产品像素零影响）
新增 Components/Shared 下的 UI 基础层： - UiLayout：矩形原语 / 对齐 / 设备像素内侧对齐 / Stack / Flow / 布局缓存（deque 保证引用稳定、 定向失效、按最久未命中淘汰）。 - UiWidget：控件树基类。两段式布局（Measure 自下而上带缓存、Arrange 自上而下）、 脏区下探绘制（dirty 为空=全画；与子树矩形无交集=整棵跳过；有效裁剪=祖先裁剪切∩自身∩脏区）、 只沿命中链派发的冒泡模型（绝不分发给同层兄弟）、capture/modal/hover/focus 仲裁、 光标认领链、统一动画 tick、内容指纹入口。 新增 Tools/uicheck 离屏回归网（62 项断言，全程不创建窗口、不注入输入）： - 布局数学：对齐/STRETCH/超尺寸夹取、Stack 固定与自动均分且绝不产生负尺寸、Flow 换行与 overflow。 - 缓存：引用稳定、定向失效、容量淘汰。 - 绘制：全画 / 子树跳过 / 裁剪收窄 / 不可见跳过 / 失效冒泡。 - 派发：重叠子节点只投最上层、hit-transparent 穿透、消费不上抛、capture 越过边界仍投递、 仅持有者可释放、modal 屏蔽其余子树、祖先兜底、光标由最上层认领、键盘沿焦点链。 - 动画：时间戳统一下发、活跃状态汇总。 过程中修正自身两处缺陷：补齐 AdvanceAnimationSelf/AnimationActiveSelf 声明； 把"遍历同层兄弟"改为"只沿命中链派发 + 祖先兜底"（否则一次点击可能被视觉上位于下方的控件也处理）。 验证：make release TARGET_FILE_NAME=TargetCheck 零警告（873,984 B，低于 900KB 阈值）； Tools/uicheck 62 passed / 0 failed。 本提交不改动任何现有组件，Toolbar/TabBar/SignalPanel/PlotView 仍走旧路径，产品像素零变化。 文档：Documents/UI_Refactor_Plan.md（蓝图）、Documents/UI_Refactor_Progress.md（台账）。
This commit is contained in:
DeepSeek V4.1 Flash committed
1 parent
4e51b41a42
commit
3529c7b44f
6 files changed
+1906
No files matched your search
@@ -0,0 +1,220 @@
|
||||
#ifndef __UI_LAYOUT_HPP__
|
||||
#define __UI_LAYOUT_HPP__
|
||||
|
||||
#include <windows.h>
|
||||
#include <objidl.h>
|
||||
#include <gdiplus.h>
|
||||
|
||||
#include <cstdint>
|
||||
#include <cstddef>
|
||||
#include <deque>
|
||||
#include <vector>
|
||||
|
||||
#include "Theme.hpp"
|
||||
|
||||
namespace jdi
|
||||
{
|
||||
|
||||
/**
|
||||
* @brief 布局方向。
|
||||
*/
|
||||
enum class UiAxis : int
|
||||
{
|
||||
HORIZONTAL = 0, /**< 主轴为水平（从左到右排列）。 */
|
||||
VERTICAL = 1 /**< 主轴为垂直（从上到下排列）。 */
|
||||
};
|
||||
|
||||
/**
|
||||
* @brief 在容器中的对齐方式（单一方向）。
|
||||
*
|
||||
* `STRETCH` = 占满该方向可用空间（尺寸由容器决定，忽略自身期望尺寸）。
|
||||
*/
|
||||
enum class UiAlign : int
|
||||
{
|
||||
BEGIN = 0, /**< 起始边（左 / 上）。 */
|
||||
CENTER = 1, /**< 居中。 */
|
||||
END = 2, /**< 结束边（右 / 下）。 */
|
||||
STRETCH = 3 /**< 拉伸占满。 */
|
||||
};
|
||||
|
||||
/**
|
||||
* @brief 四边内边距（逻辑像素，使用时由调用方乘缩放系数）。
|
||||
*/
|
||||
struct UiInsets
|
||||
{
|
||||
float left = 0.0f; /**< 左内边距。 */
|
||||
float top = 0.0f; /**< 上内边距。 */
|
||||
float right = 0.0f; /**< 右内边距。 */
|
||||
float bottom = 0.0f; /**< 下内边距。 */
|
||||
|
||||
/** @brief 四边同值。 */
|
||||
static UiInsets All(float value);
|
||||
/** @brief 左右 / 上下分别指定。 */
|
||||
static UiInsets Symmetric(float horizontal, float vertical);
|
||||
/** @brief 按缩放系数放大（DPR 1.25 等）。 */
|
||||
UiInsets Scaled(float scale) const;
|
||||
/** @brief 水平方向占用量。 */
|
||||
float Horizontal() const { return left + right; }
|
||||
/** @brief 垂直方向占用量。 */
|
||||
float Vertical() const { return top + bottom; }
|
||||
};
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// 矩形原语
|
||||
// ------------------------------------------------------------------
|
||||
|
||||
/** @brief 矩形是否有面积（宽度与高度都 > 0）。 */
|
||||
bool UiRectHasArea(const gd::RectF& rect);
|
||||
|
||||
/** @brief 两个矩形的交集；无交集时输出空矩形并返回 false。 */
|
||||
bool UiRectIntersect(const gd::RectF& a, const gd::RectF& b, gd::RectF& out);
|
||||
|
||||
/** @brief 两个矩形的并集（任一为空时直接返回另一个）。 */
|
||||
gd::RectF UiRectUnion(const gd::RectF& a, const gd::RectF& b);
|
||||
|
||||
/** @brief 内缩（结果可能为空矩形）。 */
|
||||
gd::RectF UiRectDeflate(const gd::RectF& rect, const UiInsets& insets);
|
||||
|
||||
/**
|
||||
* @brief 把矩形对齐到**设备像素整数边界**（上界 `floor`、下界 `ceil`）。
|
||||
*
|
||||
* ⚠️ 离屏位图（图层 / 装饰层 / 面板层）必须用这个结果做贴图源矩形：
|
||||
* 直接对浮点矩形取整会让补丁多算一行，从而盖到相邻网格的分界线上（历史 1px 接缝 BUG）。
|
||||
*/
|
||||
gd::RectF UiRectSnapInward(const gd::RectF& rect, float scale);
|
||||
|
||||
/** @brief 把一个 `size` 的盒子按对齐方式放进 `outer`（`STRETCH` 时返回 `outer` 本身）。 */
|
||||
gd::RectF UiAlignInRect(const gd::RectF& outer, float width, float height, UiAlign horizontal,
|
||||
UiAlign vertical, float offsetX = 0.0f, float offsetY = 0.0f);
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// 布局：Stack（一维流）/ Flow（换行流）/ Abs（绝对）
|
||||
// ------------------------------------------------------------------
|
||||
|
||||
/** @brief 尺寸未知（由剩余空间均分）。 */
|
||||
constexpr float kUiSizeAuto = -1.0f;
|
||||
|
||||
/**
|
||||
* @brief 一维栈布局的**期望尺寸**。
|
||||
* @param [IN] sizes 各项主尺寸（`kUiSizeAuto` 表示由剩余空间均分，不参与求和）。
|
||||
* @param [IN] gap 项间距。
|
||||
* @return 主尺寸合计（含间距）。
|
||||
*/
|
||||
float UiStackExtent(const std::vector<float>& sizes, float gap);
|
||||
|
||||
/**
|
||||
* @brief 一维栈布局：把 `area` 沿主轴依次切分给各项。
|
||||
*
|
||||
* * 固定尺寸项按给定值取用；
|
||||
* * `kUiSizeAuto` 项均分**剩余**空间（剩余为负时按 0 处理，避免负尺寸）；
|
||||
* * 交叉轴一律占满 `area`（需要单独对齐时调用方再 `UiAlignInRect`）。
|
||||
*
|
||||
* @param [IN] area 可用区域。
|
||||
* @param [IN] axis 主轴方向。
|
||||
* @param [IN] sizes 各项主尺寸（可含 `kUiSizeAuto`）。
|
||||
* @param [IN] gap 项间距。
|
||||
* @param [OUT] out 逐项矩形（数量与 `sizes` 一致）。
|
||||
* @param [OUT] usedExtent 实际占用主尺寸（含间距），可为空。
|
||||
*/
|
||||
void UiStackRects(const gd::RectF& area, UiAxis axis, const std::vector<float>& sizes, float gap,
|
||||
std::vector<gd::RectF>& out, float* usedExtent = nullptr);
|
||||
|
||||
/**
|
||||
* @brief 换行流布局（图例条目、工具栏按钮组）。
|
||||
*
|
||||
* 沿主轴依次摆放，放不下时**换到下一行/列**；放不下的项（含之后的所有项）
|
||||
* 不再输出，其下标通过 `overflow` 返回 —— 调用方据此绘制 `+N` 之类的省略提示。
|
||||
*
|
||||
* @param [IN] area 可用区域。
|
||||
* @param [IN] axis 主轴方向（通常是水平）。
|
||||
* @param [IN] sizes 各项 (宽, 高)。
|
||||
* @param [IN] gap 项间距（主轴与交叉轴相同）。
|
||||
* @param [OUT] out 已放下的项矩形。
|
||||
* @param [OUT] overflow 首个未放下的项下标；全部放下时为 `sizes.size()`。
|
||||
* @return 实际占用的交叉轴尺寸（行数 × 行高）。
|
||||
*/
|
||||
float UiFlowRects(const gd::RectF& area, UiAxis axis, const std::vector<gd::SizeF>& sizes, float gap,
|
||||
std::vector<gd::RectF>& out, std::size_t& overflow);
|
||||
|
||||
/** @brief 绝对布局：`outer` 左上角偏移 `(dx, dy)` 后取 `width × height`。 */
|
||||
gd::RectF UiAbsRect(const gd::RectF& outer, float dx, float dy, float width, float height);
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// 布局缓存
|
||||
// ------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* @brief 一份被缓存下来的布局结果。
|
||||
*
|
||||
* `rects` / `values` 的含义由调用方约定（例如浮动面板的"标题栏 / ✕ / 徽标 / 逐行矩形"）。
|
||||
*/
|
||||
struct UiLayoutResult
|
||||
{
|
||||
std::uint64_t key = 0; /**< 布局键（由调用方构造，必须覆盖**全部**影响几何的输入）。 */
|
||||
gd::RectF bounds; /**< 整体矩形。 */
|
||||
std::vector<gd::RectF> rects; /**< 逐项矩形。 */
|
||||
std::vector<float> values; /**< 附带数值（列宽 / 行高 / 内容总高等）。 */
|
||||
std::uint64_t stamp = 0; /**< 最近一次命中序号（用于淘汰最久未用项）。 */
|
||||
};
|
||||
|
||||
/**
|
||||
* @brief 布局结果缓存（把"每帧被反复询问的几何"降到只算一次）。
|
||||
*
|
||||
* 设计要点：
|
||||
* * 用 `std::deque` 存条目 ⇒ `Store` 之后**已有元素引用依然有效**（`vector` 扩容会失效）；
|
||||
* * 条目数量很小（面板种类 × 网格数），线性查找比哈希更快，也避免哈希碰撞带来的诡异行为；
|
||||
* * **定向失效**：几何改变的那条路径必须显式 `Invalidate(key)`，
|
||||
* **禁止**为了让缓存命中率好看而整体 `Clear()`（会让所有面板在同一帧全部重算）。
|
||||
*/
|
||||
class UiLayoutCache
|
||||
{
|
||||
public:
|
||||
explicit UiLayoutCache(std::size_t capacity = 32);
|
||||
|
||||
/**
|
||||
* @brief 查找命中项。
|
||||
* @param [IN] key 布局键。
|
||||
* @return 命中返回条目指针（**内容不可修改**），未命中返回 nullptr。
|
||||
* @note 命中会刷新该条目的使用序号（因此本函数不是 `const`）。
|
||||
*/
|
||||
const UiLayoutResult* Find(std::uint64_t key);
|
||||
|
||||
/**
|
||||
* @brief 存入（同键覆盖）并返回稳定引用。
|
||||
* @param [IN] result 待存条目（`key` 必须已填）。
|
||||
* @return 缓存内条目的引用（有效期到下一次 `Store` 引发淘汰为止）。
|
||||
*/
|
||||
const UiLayoutResult& Store(UiLayoutResult result);
|
||||
|
||||
/** @brief 定向失效。 */
|
||||
void Invalidate(std::uint64_t key);
|
||||
|
||||
/** @brief 全部清空（只在"数据层结构变化"这类场景使用）。 */
|
||||
void Clear();
|
||||
|
||||
/** @brief 当前条目数（探针用）。 */
|
||||
std::size_t Size() const { return m_entries.size(); }
|
||||
|
||||
private:
|
||||
std::size_t m_capacity; /**< 条目上限。 */
|
||||
std::uint64_t m_stamp = 0; /**< 递增使用序号。 */
|
||||
std::deque<UiLayoutResult> m_entries; /**< 条目（deque 保证引用稳定）。 */
|
||||
|
||||
/** @brief 淘汰最久未使用的条目，直到不超过上限。 */
|
||||
void Trim();
|
||||
};
|
||||
|
||||
/**
|
||||
* @brief 组合布局键（FNV-1a 风格的增量混合）。
|
||||
*
|
||||
* ⚠️ 键必须覆盖**全部**影响几何的输入；漏一个字段的症状是"布局不更新"
|
||||
* （与历史上"缓存键漏混字段 ⇒ 贴旧像素"是同一类 BUG）。
|
||||
*/
|
||||
std::uint64_t UiMixKey(std::uint64_t seed, std::uint64_t value);
|
||||
|
||||
/** @brief 浮点参与成键（按 1/1024 量化，避免亚像素抖动导致键频繁变化）。 */
|
||||
std::uint64_t UiMixKeyFloat(std::uint64_t seed, float value);
|
||||
|
||||
} // namespace jdi
|
||||
|
||||
#endif // __UI_LAYOUT_HPP__
|
||||
@@ -0,0 +1,325 @@
|
||||
#ifndef __UI_WIDGET_HPP__
|
||||
#define __UI_WIDGET_HPP__
|
||||
|
||||
#include <windows.h>
|
||||
#include <objidl.h>
|
||||
#include <gdiplus.h>
|
||||
|
||||
#include <cstdint>
|
||||
#include <memory>
|
||||
#include <vector>
|
||||
|
||||
#include "Theme.hpp"
|
||||
#include "UiLayout.hpp"
|
||||
|
||||
namespace jdi
|
||||
{
|
||||
|
||||
struct Theme;
|
||||
struct UiFonts;
|
||||
|
||||
/**
|
||||
* @brief 布局测量上下文（由根节点统一下发，子节点只读）。
|
||||
*/
|
||||
struct UiMeasureContext
|
||||
{
|
||||
const Theme* theme = nullptr; /**< 主题（子节点可能需要配色相关的尺寸）。 */
|
||||
const UiFonts* fonts = nullptr; /**< 字体（文本尺寸测量必需）。 */
|
||||
float scale = 1.0f; /**< 缩放系数（逻辑像素 → 设备像素）。 */
|
||||
float availableWidth = -1.0f; /**< 父给出的宽度上限（<0 表示不限）。 */
|
||||
float availableHeight = -1.0f; /**< 父给出的高度上限（<0 表示不限）。 */
|
||||
};
|
||||
|
||||
/**
|
||||
* @brief 绘制上下文。
|
||||
*
|
||||
* ⚠️ **`dirty` 的语义（重要）**：空矩形表示"脏区未知 ⇒ 全画"；非空表示"只需保证这一块被更新"。
|
||||
* 基类在进入子节点前会把 `dirty` 与子节点矩形求交，为空即**整棵子树跳过** ——
|
||||
* 这是本框架唯一真正省时间的机制，禁止任何派生类把它退化成"父脏 ⇒ 子树全脏"。
|
||||
*/
|
||||
struct UiPaintContext
|
||||
{
|
||||
gd::Graphics* g = nullptr; /**< 绘图上下文（共享的后备缓冲/离屏位图）。 */
|
||||
gd::RectF dirty; /**< 需要重绘的区域（客户区坐标）。 */
|
||||
gd::RectF clip; /**< 当前有效裁剪矩形（= 祖先与本节点矩形的交集）。 */
|
||||
float scale = 1.0f; /**< 缩放系数。 */
|
||||
bool fastFrame = false; /**< 交互帧：允许降级（**几何不得改变**，只允许关抗锯齿等）。 */
|
||||
|
||||
/** @brief 取与给定矩形求交后的绘制上下文（子节点用）。 */
|
||||
UiPaintContext WithClip(const gd::RectF& rect) const;
|
||||
};
|
||||
|
||||
/**
|
||||
* @brief 事件类型。
|
||||
*/
|
||||
enum class UiEventKind : int
|
||||
{
|
||||
NONE = 0,
|
||||
MOUSE_MOVE, /**< 鼠标移动（可能带按键）。 */
|
||||
MOUSE_DOWN, /**< 鼠标按下。 */
|
||||
MOUSE_UP, /**< 鼠标抬起。 */
|
||||
MOUSE_DOUBLE_CLICK, /**< 双击（**只有确实有双击语义的控件才应处理它**）。 */
|
||||
MOUSE_WHEEL, /**< 滚轮。 */
|
||||
MOUSE_LEAVE, /**< 指针离开该控件。 */
|
||||
KEY_DOWN, /**< 键盘按下。 */
|
||||
CHAR, /**< 字符输入。 */
|
||||
QUERY_CURSOR /**< 询问光标形态（结果写回 `cursor`）。 */
|
||||
};
|
||||
|
||||
/** @brief 鼠标按键（与 `UiEventKind` 组合使用）。 */
|
||||
enum class UiMouseButton : int
|
||||
{
|
||||
NONE = 0,
|
||||
LEFT = 1,
|
||||
MIDDLE = 2,
|
||||
RIGHT = 3
|
||||
};
|
||||
|
||||
/**
|
||||
* @brief 一个 UI 事件（客户区坐标）。
|
||||
*/
|
||||
struct UiEvent
|
||||
{
|
||||
UiEventKind kind = UiEventKind::NONE; /**< 事件类型。 */
|
||||
int x = 0; /**< 鼠标横坐标。 */
|
||||
int y = 0; /**< 鼠标纵坐标。 */
|
||||
UiMouseButton button = UiMouseButton::NONE; /**< 涉及的按键。 */
|
||||
int wheelDelta = 0; /**< 滚轮增量（1 格 = 120）。 */
|
||||
bool shift = false; /**< Shift 是否按下。 */
|
||||
bool control = false; /**< Ctrl 是否按下。 */
|
||||
WPARAM key = 0; /**< 虚拟键码（`KEY_DOWN`）。 */
|
||||
wchar_t character = 0; /**< 字符（`CHAR`）。 */
|
||||
HCURSOR cursor = nullptr; /**< `QUERY_CURSOR` 的输出（nullptr = 未认领）。 */
|
||||
};
|
||||
|
||||
/**
|
||||
* @brief 事件处理结果。
|
||||
*
|
||||
* 与旧架构（返回 `bool 要不要重绘`）的关键差别：**"消费"与"重绘"是两件事**。
|
||||
* 消费决定是否继续上抛；`dirty` 参与本帧脏区并集（为空表示"未知 ⇒ 取自身矩形"）。
|
||||
*/
|
||||
struct UiEventResult
|
||||
{
|
||||
bool consumed = false; /**< 事件已被消费。 */
|
||||
bool redraw = false; /**< 需要重绘。 */
|
||||
gd::RectF dirty; /**< 需要重绘的矩形（客户区坐标；空 + `redraw` ⇒ 取自身矩形）。 */
|
||||
|
||||
/** @brief 构造"已消费且需要重绘自身"的结果。 */
|
||||
static UiEventResult Handled();
|
||||
/** @brief 构造"已消费但不需重绘"的结果（例如纯状态查询）。 */
|
||||
static UiEventResult Swallowed();
|
||||
};
|
||||
|
||||
/**
|
||||
* @brief UI 控件基类：树结构 + 两段式布局 + 脏区下探绘制 + 冒泡派发 + 交互仲裁。
|
||||
*
|
||||
* ## 为什么要这一层
|
||||
*
|
||||
* 旧架构是"并列大组件 + 手写优先级链"，每个叠加层都要把"几何 / 命中 / 绘制 / 缓存键"
|
||||
* 各写一遍（`PlotView` 已有 310 个方法 / 203 个成员）。这里把这些重复收敛成基类契约：
|
||||
*
|
||||
* * **布局只算一次**：`Measure` 自下而上、`Arrange` 自上而下；命中/绘制/光标读同一份 `m_bounds`。
|
||||
* * **裁剪契约统一**：`Paint` 进入时收紧 GDI+ 裁剪（`ctx.clip`），派生类必须把它传给
|
||||
* `UiTextClipped` 等**GDI 绘制辅助函数**（GDI 文本不认 GDI+ 裁剪区，这是本项目反复踩到的坑）。
|
||||
* * **脏区下探**：`dirty ∩ bounds` 为空 ⇒ 整棵子树跳过。
|
||||
* * **交互仲裁**：capture / 模态 / 悬停链 / 光标链由基类提供，派生类只写自己的手势。
|
||||
*
|
||||
* ## 三条硬约束（改代码前先读）
|
||||
*
|
||||
* 1. **禁止"父脏 ⇒ 子树全脏"**：会把"只重绘一个网格/一个面板"打回整块重绘。
|
||||
* 2. **禁止把数据→像素管线（网格/曲线/采样点）做成控件节点**：布局与虚调用会进每帧热路径。
|
||||
* 3. **禁止每个控件自持位图**：内存按面积线性增长（128 网格已是 ≈250MB 量级）。
|
||||
*/
|
||||
class UiWidget
|
||||
{
|
||||
public:
|
||||
UiWidget();
|
||||
virtual ~UiWidget();
|
||||
|
||||
UiWidget(const UiWidget&) = delete;
|
||||
UiWidget& operator=(const UiWidget&) = delete;
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// 树结构
|
||||
// ------------------------------------------------------------------
|
||||
|
||||
/** @brief 追加子节点（**追加到末尾 = 最上层**，绘制与命中都按此顺序）。 */
|
||||
UiWidget& AddChild(std::unique_ptr<UiWidget> child);
|
||||
/** @brief 移除子节点（不存在时无操作）。 */
|
||||
void RemoveChild(UiWidget* child);
|
||||
/** @brief 子节点集合（顺序 = z 序，末尾最上层）。 */
|
||||
const std::vector<std::unique_ptr<UiWidget>>& Children() const { return m_children; }
|
||||
/** @brief 父节点（根节点为 nullptr）。 */
|
||||
UiWidget* Parent() const { return m_parent; }
|
||||
/** @brief 根节点。 */
|
||||
UiWidget* Root();
|
||||
/** @brief 根节点（const）。 */
|
||||
const UiWidget* Root() const;
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// 布局
|
||||
// ------------------------------------------------------------------
|
||||
|
||||
/** @brief 标记"期望尺寸"失效（会向根冒泡。只失效自己与**祖先**，不影响兄弟）。 */
|
||||
void InvalidateMeasure();
|
||||
|
||||
/**
|
||||
* @brief 自下而上求期望尺寸（带缓存）。
|
||||
* @param [IN] ctx 测量上下文。
|
||||
* @return 期望尺寸（**含**自身内边距；不含外边距 —— 本项目没有外边距概念）。
|
||||
*/
|
||||
gd::SizeF Measure(const UiMeasureContext& ctx);
|
||||
|
||||
/** @brief 定位：写入自身矩形并回调 `OnArrange()`（派生容器在其中摆放子节点）。 */
|
||||
void Arrange(const gd::RectF& bounds);
|
||||
|
||||
/** @brief 当前矩形（客户区坐标，整像素对齐由调用方保证）。 */
|
||||
const gd::RectF& Bounds() const { return m_bounds; }
|
||||
/** @brief 上一帧测量得到的期望尺寸。 */
|
||||
gd::SizeF DesiredSize() const { return m_desiredSize; }
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// 绘制
|
||||
// ------------------------------------------------------------------
|
||||
|
||||
/** @brief 绘制自身与全部子节点（内部处理裁剪下探与脏区跳过）。 */
|
||||
void Paint(UiPaintContext& ctx);
|
||||
|
||||
/** @brief 局部失效：与自身矩形求交后向根冒泡。 */
|
||||
virtual void Invalidate(const gd::RectF& rect);
|
||||
/** @brief 整棵子树失效。 */
|
||||
void InvalidateAll();
|
||||
|
||||
/** @brief 取走累计的脏区（根节点用）。空矩形表示"无失效"。 */
|
||||
gd::RectF TakeDirty();
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// 事件
|
||||
// ------------------------------------------------------------------
|
||||
|
||||
/** @brief 派发事件：捕获/模态路由 → 命中链（自最深向上冒泡）→ 自身 `OnEvent`。 */
|
||||
UiEventResult Dispatch(UiEvent& event);
|
||||
|
||||
/** @brief 点是否落在自身矩形内（不含可见性/透明判断）。 */
|
||||
bool Contains(int x, int y) const;
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// 交互仲裁
|
||||
// ------------------------------------------------------------------
|
||||
|
||||
/** @brief 请求独占鼠标（根节点记录；等价于 `SetCapture`）。 */
|
||||
void CaptureMouse();
|
||||
/** @brief 释放独占（**只有当前的捕获者**才会成功，避免错误释放别人的捕获）。 */
|
||||
void ReleaseMouse();
|
||||
/** @brief 当前持有捕获的控件（无则 nullptr）。 */
|
||||
UiWidget* MouseCaptureWidget() const;
|
||||
|
||||
/** @brief 设为模态子树：根节点只向它派发事件（菜单/拾色器等浮层用）。 */
|
||||
void SetModal(bool modal);
|
||||
/** @brief 当前模态子树（无则 nullptr）。 */
|
||||
UiWidget* ModalWidget() const;
|
||||
/** @brief 是否处于模态（向上查找到根）。 */
|
||||
bool IsModalActive() const { return ModalWidget() != nullptr; }
|
||||
|
||||
/** @brief 设为"命中透明"（纯装饰元素：不参与命中与光标链）。 */
|
||||
void SetHitTransparent(bool value) { m_hitTransparent = value; }
|
||||
/** @brief 是否命中透明。 */
|
||||
bool HitTransparent() const { return m_hitTransparent; }
|
||||
|
||||
/** @brief 设置可见性（不可见 = 不参与绘制与命中，**但不影响布局**）。 */
|
||||
void SetVisible(bool visible) { m_visible = visible; }
|
||||
/** @brief 是否可见。 */
|
||||
bool Visible() const { return m_visible; }
|
||||
|
||||
/** @brief 当前悬停的控件（根节点维护）。 */
|
||||
UiWidget* HoverWidget() const;
|
||||
|
||||
/** @brief 请求键盘焦点（根节点记录；键盘/字符事件沿焦点链派发）。 */
|
||||
void RequestFocus();
|
||||
/** @brief 释放焦点（**只有当前的焦点持有者**才会成功）。 */
|
||||
void ReleaseFocus();
|
||||
/** @brief 当前持有焦点的控件（无则 nullptr）。 */
|
||||
UiWidget* FocusWidget() const;
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// 动画
|
||||
// ------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* @brief 推进动画。
|
||||
* @param [IN] nowMs 当前时间（`GetTickCount64()`）。
|
||||
* @return 仍有动画进行中返回 true（宿主据此保持定时器）。
|
||||
*/
|
||||
bool AdvanceAnimation(std::int64_t nowMs);
|
||||
/** @brief 是否仍有动画（不推进）。 */
|
||||
bool AnimationActive() const;
|
||||
|
||||
protected:
|
||||
/** @brief 推进**自身**动画（派生类覆写；返回"我这一层是否仍需继续推进"）。 */
|
||||
virtual bool AdvanceAnimationSelf(std::int64_t nowMs) { (void)nowMs; return false; }
|
||||
/** @brief **自身**是否仍有动画（派生类覆写）。 */
|
||||
virtual bool AnimationActiveSelf() const { return false; }
|
||||
|
||||
/** @brief 计算期望尺寸（派生类实现；**不得**修改子节点集合或自身矩形）。 */
|
||||
virtual gd::SizeF OnMeasure(const UiMeasureContext& ctx) = 0;
|
||||
/** @brief 自身矩形已更新：派生容器在这里摆放子节点。 */
|
||||
virtual void OnArrange() {}
|
||||
/** @brief 绘制自身（**不要**在这里遍历子节点；基类会负责）。 */
|
||||
virtual void OnPaint(UiPaintContext& ctx) = 0;
|
||||
/** @brief 自身处理事件（子节点都未消费时才会被调用）。 */
|
||||
virtual UiEventResult OnEvent(UiEvent& event) { (void)event; return UiEventResult(); }
|
||||
/** @brief 该位置的光标形态（nullptr = 不认领，交给下层/宿主）。 */
|
||||
virtual HCURSOR OnQueryCursor(int x, int y) { (void)x; (void)y; return nullptr; }
|
||||
|
||||
/**
|
||||
* @brief 内容指纹（缓存键的**唯一来源**）。
|
||||
*
|
||||
* 派生类必须把"会改变像素的**全部**状态"混进来；父层只负责聚合子节点的键。
|
||||
* 漏字段的症状是"贴旧像素"（本项目历史上至少 4 次真实 BUG 都是这个原因）。
|
||||
*/
|
||||
virtual std::uint64_t ContentKey() const { return 0; }
|
||||
/** @brief 基类能提供的那部分键（矩形/可见性）。 */
|
||||
std::uint64_t BaseContentKey() const;
|
||||
|
||||
/** @brief 把子节点 `Measure` 一遍（派生容器在 `OnMeasure` 里调用）。 */
|
||||
void MeasureChildren(const UiMeasureContext& ctx);
|
||||
/** @brief 子节点的期望尺寸（需先 `MeasureChildren`）。 */
|
||||
gd::SizeF ChildDesiredSize(std::size_t index) const;
|
||||
|
||||
/** @brief 命中测试：返回最上层（z 序末尾）且包含该点的子孙控件。 */
|
||||
UiWidget* HitTestDeep(int x, int y);
|
||||
/** @brief 悬停链变化通知（默认无操作；需要"指针进入/离开"语义的控件可覆写）。 */
|
||||
virtual void OnHoverChanged(bool entered) { (void)entered; }
|
||||
|
||||
private:
|
||||
/** @brief 沿命中链派发（位置事件）；非位置事件沿子树顺序派发。 */
|
||||
UiEventResult DispatchAlongHitPath(UiEvent& event);
|
||||
/**
|
||||
* @brief 命中链（自**最深**的命中节点开始，逐个回溯到本节点）。
|
||||
*
|
||||
* 只把事件交给"鼠标真正压住的那一条路径"，**绝不**分发给同层兄弟 ——
|
||||
* 否则一个点击可能同时被视觉上位于下方的控件处理（两层都改状态）。
|
||||
*/
|
||||
void CollectHitChain(int x, int y, std::vector<UiWidget*>& chain);
|
||||
/** @brief 更新悬停链（只在根节点调用）。 */
|
||||
void UpdateHover(int x, int y);
|
||||
/** @brief 是否需要重绘（脏区与自身矩形求交）。 */
|
||||
bool DirtyIntersects(const gd::RectF& dirty) const;
|
||||
|
||||
UiWidget* m_parent = nullptr; /**< 父节点。 */
|
||||
std::vector<std::unique_ptr<UiWidget>> m_children; /**< 子节点（顺序 = z 序）。 */
|
||||
gd::RectF m_bounds; /**< 当前矩形（客户区坐标）。 */
|
||||
gd::SizeF m_desiredSize; /**< 期望尺寸。 */
|
||||
gd::RectF m_dirty; /**< 累计脏区（自身坐标系）。 */
|
||||
bool m_visible = true; /**< 是否可见。 */
|
||||
bool m_hitTransparent = false; /**< 是否命中透明。 */
|
||||
bool m_measureValid = false; /**< 期望尺寸是否有效。 */
|
||||
|
||||
// 根节点专用状态。
|
||||
UiWidget* m_capture = nullptr; /**< 鼠标捕获者。 */
|
||||
UiWidget* m_modal = nullptr; /**< 模态子树。 */
|
||||
UiWidget* m_hover = nullptr; /**< 当前悬停控件。 */ UiWidget* m_focus = nullptr; /**< 键盘焦点控件。 */ };
|
||||
|
||||
} // namespace jdi
|
||||
|
||||
#endif // __UI_WIDGET_HPP__
|
||||
@@ -0,0 +1,357 @@
|
||||
#include "UiLayout.hpp"
|
||||
|
||||
#include <algorithm>
|
||||
#include <cmath>
|
||||
|
||||
namespace jdi
|
||||
{
|
||||
|
||||
UiInsets UiInsets::All(float value)
|
||||
{
|
||||
UiInsets insets;
|
||||
insets.left = value;
|
||||
insets.top = value;
|
||||
insets.right = value;
|
||||
insets.bottom = value;
|
||||
return insets;
|
||||
}
|
||||
|
||||
UiInsets UiInsets::Symmetric(float horizontal, float vertical)
|
||||
{
|
||||
UiInsets insets;
|
||||
insets.left = horizontal;
|
||||
insets.right = horizontal;
|
||||
insets.top = vertical;
|
||||
insets.bottom = vertical;
|
||||
return insets;
|
||||
}
|
||||
|
||||
UiInsets UiInsets::Scaled(float scale) const
|
||||
{
|
||||
UiInsets insets;
|
||||
insets.left = left * scale;
|
||||
insets.top = top * scale;
|
||||
insets.right = right * scale;
|
||||
insets.bottom = bottom * scale;
|
||||
return insets;
|
||||
}
|
||||
|
||||
bool UiRectHasArea(const gd::RectF& rect)
|
||||
{
|
||||
return rect.Width > 0.0f && rect.Height > 0.0f;
|
||||
}
|
||||
|
||||
bool UiRectIntersect(const gd::RectF& a, const gd::RectF& b, gd::RectF& out)
|
||||
{
|
||||
if (!UiRectHasArea(a) || !UiRectHasArea(b))
|
||||
{
|
||||
out = gd::RectF();
|
||||
return false;
|
||||
}
|
||||
const float left = std::max(a.X, b.X);
|
||||
const float top = std::max(a.Y, b.Y);
|
||||
const float right = std::min(a.X + a.Width, b.X + b.Width);
|
||||
const float bottom = std::min(a.Y + a.Height, b.Y + b.Height);
|
||||
if (right <= left || bottom <= top)
|
||||
{
|
||||
out = gd::RectF();
|
||||
return false;
|
||||
}
|
||||
out = gd::RectF(left, top, right - left, bottom - top);
|
||||
return true;
|
||||
}
|
||||
|
||||
gd::RectF UiRectUnion(const gd::RectF& a, const gd::RectF& b)
|
||||
{
|
||||
if (!UiRectHasArea(a))
|
||||
{
|
||||
return b;
|
||||
}
|
||||
if (!UiRectHasArea(b))
|
||||
{
|
||||
return a;
|
||||
}
|
||||
const float left = std::min(a.X, b.X);
|
||||
const float top = std::min(a.Y, b.Y);
|
||||
const float right = std::max(a.X + a.Width, b.X + b.Width);
|
||||
const float bottom = std::max(a.Y + a.Height, b.Y + b.Height);
|
||||
return gd::RectF(left, top, right - left, bottom - top);
|
||||
}
|
||||
|
||||
gd::RectF UiRectDeflate(const gd::RectF& rect, const UiInsets& insets)
|
||||
{
|
||||
const float width = rect.Width - insets.Horizontal();
|
||||
const float height = rect.Height - insets.Vertical();
|
||||
if (width <= 0.0f || height <= 0.0f)
|
||||
{
|
||||
return gd::RectF();
|
||||
}
|
||||
return gd::RectF(rect.X + insets.left, rect.Y + insets.top, width, height);
|
||||
}
|
||||
|
||||
gd::RectF UiRectSnapInward(const gd::RectF& rect, float scale)
|
||||
{
|
||||
const float safeScale = (scale > 0.0f) ? scale : 1.0f;
|
||||
const float x0 = std::ceil(rect.X * safeScale - 0.001f) / safeScale;
|
||||
const float y0 = std::ceil(rect.Y * safeScale - 0.001f) / safeScale;
|
||||
const float x1 = std::floor((rect.X + rect.Width) * safeScale + 0.001f) / safeScale;
|
||||
const float y1 = std::floor((rect.Y + rect.Height) * safeScale + 0.001f) / safeScale;
|
||||
if (x1 <= x0 || y1 <= y0)
|
||||
{
|
||||
return gd::RectF();
|
||||
}
|
||||
return gd::RectF(x0, y0, x1 - x0, y1 - y0);
|
||||
}
|
||||
|
||||
gd::RectF UiAlignInRect(const gd::RectF& outer, float width, float height, UiAlign horizontal,
|
||||
UiAlign vertical, float offsetX, float offsetY)
|
||||
{
|
||||
float boxWidth = width;
|
||||
float boxHeight = height;
|
||||
if (horizontal == UiAlign::STRETCH)
|
||||
{
|
||||
boxWidth = outer.Width;
|
||||
}
|
||||
if (vertical == UiAlign::STRETCH)
|
||||
{
|
||||
boxHeight = outer.Height;
|
||||
}
|
||||
boxWidth = std::min(boxWidth, outer.Width);
|
||||
boxHeight = std::min(boxHeight, outer.Height);
|
||||
|
||||
float x = outer.X;
|
||||
switch (horizontal)
|
||||
{
|
||||
case UiAlign::CENTER:
|
||||
x = outer.X + (outer.Width - boxWidth) * 0.5f;
|
||||
break;
|
||||
case UiAlign::END:
|
||||
x = outer.X + outer.Width - boxWidth;
|
||||
break;
|
||||
default:
|
||||
break;
|
||||
}
|
||||
float y = outer.Y;
|
||||
switch (vertical)
|
||||
{
|
||||
case UiAlign::CENTER:
|
||||
y = outer.Y + (outer.Height - boxHeight) * 0.5f;
|
||||
break;
|
||||
case UiAlign::END:
|
||||
y = outer.Y + outer.Height - boxHeight;
|
||||
break;
|
||||
default:
|
||||
break;
|
||||
}
|
||||
return gd::RectF(x + offsetX, y + offsetY, boxWidth, boxHeight);
|
||||
}
|
||||
|
||||
float UiStackExtent(const std::vector<float>& sizes, float gap)
|
||||
{
|
||||
float total = 0.0f;
|
||||
std::size_t fixedCount = 0;
|
||||
for (float size : sizes)
|
||||
{
|
||||
if (size >= 0.0f)
|
||||
{
|
||||
total += size;
|
||||
++fixedCount;
|
||||
}
|
||||
}
|
||||
if (fixedCount > 0 && sizes.size() > 1)
|
||||
{
|
||||
total += gap * static_cast<float>(sizes.size() - 1);
|
||||
}
|
||||
return total;
|
||||
}
|
||||
|
||||
void UiStackRects(const gd::RectF& area, UiAxis axis, const std::vector<float>& sizes, float gap,
|
||||
std::vector<gd::RectF>& out, float* usedExtent)
|
||||
{
|
||||
out.clear();
|
||||
if (sizes.empty())
|
||||
{
|
||||
if (usedExtent != nullptr)
|
||||
{
|
||||
*usedExtent = 0.0f;
|
||||
}
|
||||
return;
|
||||
}
|
||||
const bool horizontal = (axis == UiAxis::HORIZONTAL);
|
||||
const float totalExtent = horizontal ? area.Width : area.Height;
|
||||
const float totalGap = (sizes.size() > 1) ? gap * static_cast<float>(sizes.size() - 1) : 0.0f;
|
||||
const float fixedExtent = UiStackExtent(sizes, gap) - totalGap;
|
||||
|
||||
std::size_t autoCount = 0;
|
||||
for (float size : sizes)
|
||||
{
|
||||
if (size < 0.0f)
|
||||
{
|
||||
++autoCount;
|
||||
}
|
||||
}
|
||||
// 剩余空间不足时按 0 处理（**不允许**出现负尺寸：负宽高的矩形会画出反向的线）。
|
||||
const float remaining = std::max(0.0f, totalExtent - fixedExtent - totalGap);
|
||||
const float autoExtent = (autoCount > 0) ? (remaining / static_cast<float>(autoCount)) : 0.0f;
|
||||
|
||||
float cursor = horizontal ? area.X : area.Y;
|
||||
out.reserve(sizes.size());
|
||||
for (std::size_t index = 0; index < sizes.size(); ++index)
|
||||
{
|
||||
const float extent = (sizes[index] < 0.0f) ? autoExtent : std::max(0.0f, sizes[index]);
|
||||
if (horizontal)
|
||||
{
|
||||
out.push_back(gd::RectF(cursor, area.Y, extent, area.Height));
|
||||
}
|
||||
else
|
||||
{
|
||||
out.push_back(gd::RectF(area.X, cursor, area.Width, extent));
|
||||
}
|
||||
cursor += extent;
|
||||
if (index + 1 < sizes.size())
|
||||
{
|
||||
cursor += gap;
|
||||
}
|
||||
}
|
||||
if (usedExtent != nullptr)
|
||||
{
|
||||
*usedExtent = cursor - (horizontal ? area.X : area.Y);
|
||||
}
|
||||
}
|
||||
|
||||
float UiFlowRects(const gd::RectF& area, UiAxis axis, const std::vector<gd::SizeF>& sizes, float gap,
|
||||
std::vector<gd::RectF>& out, std::size_t& overflow)
|
||||
{
|
||||
out.clear();
|
||||
overflow = sizes.size();
|
||||
if (sizes.empty())
|
||||
{
|
||||
return 0.0f;
|
||||
}
|
||||
const bool horizontal = (axis == UiAxis::HORIZONTAL);
|
||||
const float mainExtent = horizontal ? area.Width : area.Height;
|
||||
const float crossExtent = horizontal ? area.Height : area.Width;
|
||||
|
||||
float main = 0.0f; // 当前行内已用主轴长度
|
||||
float cross = 0.0f; // 当前行起点（交叉轴）
|
||||
float lineCross = 0.0f; // 当前行最大交叉尺寸
|
||||
out.reserve(sizes.size());
|
||||
|
||||
for (std::size_t index = 0; index < sizes.size(); ++index)
|
||||
{
|
||||
const float itemMain = horizontal ? sizes[index].Width : sizes[index].Height;
|
||||
const float itemCross = horizontal ? sizes[index].Height : sizes[index].Width;
|
||||
const float needed = (main > 0.0f) ? (main + gap + itemMain) : itemMain;
|
||||
if (needed > mainExtent && main > 0.0f)
|
||||
{
|
||||
// 换行
|
||||
cross += lineCross + gap;
|
||||
main = 0.0f;
|
||||
lineCross = 0.0f;
|
||||
}
|
||||
if (itemMain > mainExtent || cross + itemCross > crossExtent)
|
||||
{
|
||||
overflow = index;
|
||||
break;
|
||||
}
|
||||
const float offset = (main > 0.0f) ? (main + gap) : 0.0f;
|
||||
const float x = horizontal ? (area.X + offset) : (area.X + cross);
|
||||
const float y = horizontal ? (area.Y + cross) : (area.Y + offset);
|
||||
out.push_back(gd::RectF(x, y, horizontal ? itemMain : itemCross,
|
||||
horizontal ? itemCross : itemMain));
|
||||
main += offset + itemMain;
|
||||
lineCross = std::max(lineCross, itemCross);
|
||||
}
|
||||
return cross + lineCross;
|
||||
}
|
||||
|
||||
gd::RectF UiAbsRect(const gd::RectF& outer, float dx, float dy, float width, float height)
|
||||
{
|
||||
return gd::RectF(outer.X + dx, outer.Y + dy, std::max(0.0f, width), std::max(0.0f, height));
|
||||
}
|
||||
|
||||
std::uint64_t UiMixKey(std::uint64_t seed, std::uint64_t value)
|
||||
{
|
||||
// FNV-1a 64 位的一份变体：与项目里其它指纹（SceneContentHash 等）同一风格。
|
||||
seed ^= value + 0x9E3779B97F4A7C15ull + (seed << 6) + (seed >> 2);
|
||||
return seed;
|
||||
}
|
||||
|
||||
std::uint64_t UiMixKeyFloat(std::uint64_t seed, float value)
|
||||
{
|
||||
// 量化到 1/1024 逻辑像素：亚像素抖动不应该让布局缓存反复失效。
|
||||
const long long quantized = static_cast<long long>(std::llround(value * 1024.0f));
|
||||
return UiMixKey(seed, static_cast<std::uint64_t>(quantized));
|
||||
}
|
||||
|
||||
UiLayoutCache::UiLayoutCache(std::size_t capacity)
|
||||
: m_capacity(std::max<std::size_t>(1, capacity))
|
||||
{
|
||||
}
|
||||
|
||||
const UiLayoutResult* UiLayoutCache::Find(std::uint64_t key)
|
||||
{
|
||||
for (UiLayoutResult& entry : m_entries)
|
||||
{
|
||||
if (entry.key == key)
|
||||
{
|
||||
entry.stamp = ++m_stamp;
|
||||
return &entry;
|
||||
}
|
||||
}
|
||||
return nullptr;
|
||||
}
|
||||
|
||||
const UiLayoutResult& UiLayoutCache::Store(UiLayoutResult result)
|
||||
{
|
||||
for (UiLayoutResult& entry : m_entries)
|
||||
{
|
||||
if (entry.key == result.key)
|
||||
{
|
||||
entry = std::move(result);
|
||||
entry.stamp = ++m_stamp;
|
||||
return entry;
|
||||
}
|
||||
}
|
||||
result.stamp = ++m_stamp;
|
||||
m_entries.push_back(std::move(result));
|
||||
Trim();
|
||||
// 淘汰只会从队首进行，而新条目在队尾 ⇒ 刚存入的条目一定仍然有效。
|
||||
return m_entries.back();
|
||||
}
|
||||
|
||||
void UiLayoutCache::Invalidate(std::uint64_t key)
|
||||
{
|
||||
for (auto iterator = m_entries.begin(); iterator != m_entries.end(); ++iterator)
|
||||
{
|
||||
if (iterator->key == key)
|
||||
{
|
||||
m_entries.erase(iterator);
|
||||
return;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
void UiLayoutCache::Clear()
|
||||
{
|
||||
m_entries.clear();
|
||||
}
|
||||
|
||||
void UiLayoutCache::Trim()
|
||||
{
|
||||
while (m_entries.size() > m_capacity)
|
||||
{
|
||||
// 淘汰"最久未被命中"的条目（stamp 最小）。
|
||||
auto oldest = m_entries.begin();
|
||||
for (auto iterator = m_entries.begin(); iterator != m_entries.end(); ++iterator)
|
||||
{
|
||||
if (iterator->stamp < oldest->stamp)
|
||||
{
|
||||
oldest = iterator;
|
||||
}
|
||||
}
|
||||
m_entries.erase(oldest);
|
||||
}
|
||||
}
|
||||
|
||||
} // namespace jdi
|
||||
@@ -0,0 +1,614 @@
|
||||
#include "UiWidget.hpp"
|
||||
|
||||
#include <algorithm>
|
||||
#include <cmath>
|
||||
|
||||
namespace jdi
|
||||
{
|
||||
|
||||
UiEventResult UiEventResult::Handled()
|
||||
{
|
||||
UiEventResult result;
|
||||
result.consumed = true;
|
||||
result.redraw = true;
|
||||
return result;
|
||||
}
|
||||
|
||||
UiEventResult UiEventResult::Swallowed()
|
||||
{
|
||||
UiEventResult result;
|
||||
result.consumed = true;
|
||||
result.redraw = false;
|
||||
return result;
|
||||
}
|
||||
|
||||
UiPaintContext UiPaintContext::WithClip(const gd::RectF& rect) const
|
||||
{
|
||||
UiPaintContext child = *this;
|
||||
gd::RectF intersection;
|
||||
if (UiRectIntersect(clip, rect, intersection))
|
||||
{
|
||||
child.clip = intersection;
|
||||
}
|
||||
else
|
||||
{
|
||||
child.clip = gd::RectF();
|
||||
}
|
||||
return child;
|
||||
}
|
||||
|
||||
UiWidget::UiWidget() = default;
|
||||
|
||||
UiWidget::~UiWidget()
|
||||
{
|
||||
// 子节点析构前先把"指向自己的根级状态"清掉：否则根的 m_capture / m_modal / m_hover
|
||||
// 会留下悬空指针（子节点被移除后又被派发事件 = 访问违例）。
|
||||
UiWidget* root = Root();
|
||||
if (root != nullptr && root != this)
|
||||
{
|
||||
if (root->m_capture == this)
|
||||
{
|
||||
root->m_capture = nullptr;
|
||||
}
|
||||
if (root->m_modal == this)
|
||||
{
|
||||
root->m_modal = nullptr;
|
||||
}
|
||||
if (root->m_hover == this)
|
||||
{
|
||||
root->m_hover = nullptr;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// 树结构
|
||||
// ------------------------------------------------------------------
|
||||
|
||||
UiWidget& UiWidget::AddChild(std::unique_ptr<UiWidget> child)
|
||||
{
|
||||
if (child == nullptr)
|
||||
{
|
||||
return *this;
|
||||
}
|
||||
UiWidget* raw = child.get();
|
||||
raw->m_parent = this;
|
||||
m_children.push_back(std::move(child));
|
||||
// 子节点的期望尺寸会影响自己 ⇒ 向上失效。
|
||||
InvalidateMeasure();
|
||||
return *this;
|
||||
}
|
||||
|
||||
void UiWidget::RemoveChild(UiWidget* child)
|
||||
{
|
||||
if (child == nullptr)
|
||||
{
|
||||
return;
|
||||
}
|
||||
for (auto iterator = m_children.begin(); iterator != m_children.end(); ++iterator)
|
||||
{
|
||||
if (iterator->get() == child)
|
||||
{
|
||||
(*iterator)->m_parent = nullptr;
|
||||
m_children.erase(iterator);
|
||||
InvalidateMeasure();
|
||||
return;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
UiWidget* UiWidget::Root()
|
||||
{
|
||||
UiWidget* node = this;
|
||||
while (node->m_parent != nullptr)
|
||||
{
|
||||
node = node->m_parent;
|
||||
}
|
||||
return node;
|
||||
}
|
||||
|
||||
const UiWidget* UiWidget::Root() const
|
||||
{
|
||||
const UiWidget* node = this;
|
||||
while (node->m_parent != nullptr)
|
||||
{
|
||||
node = node->m_parent;
|
||||
}
|
||||
return node;
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// 布局
|
||||
// ------------------------------------------------------------------
|
||||
|
||||
void UiWidget::InvalidateMeasure()
|
||||
{
|
||||
if (!m_measureValid)
|
||||
{
|
||||
// 已经失效 ⇒ 不必继续上溯（祖先此前也一定被失效过）。
|
||||
return;
|
||||
}
|
||||
m_measureValid = false;
|
||||
if (m_parent != nullptr)
|
||||
{
|
||||
m_parent->InvalidateMeasure();
|
||||
}
|
||||
}
|
||||
|
||||
gd::SizeF UiWidget::Measure(const UiMeasureContext& ctx)
|
||||
{
|
||||
const gd::SizeF size = m_measureValid ? m_desiredSize : OnMeasure(ctx);
|
||||
m_desiredSize = size;
|
||||
m_measureValid = true;
|
||||
return m_desiredSize;
|
||||
}
|
||||
|
||||
void UiWidget::Arrange(const gd::RectF& bounds)
|
||||
{
|
||||
m_bounds = bounds;
|
||||
OnArrange();
|
||||
}
|
||||
|
||||
void UiWidget::MeasureChildren(const UiMeasureContext& ctx)
|
||||
{
|
||||
for (const std::unique_ptr<UiWidget>& child : m_children)
|
||||
{
|
||||
if (child == nullptr || !child->m_visible)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
child->Measure(ctx);
|
||||
}
|
||||
}
|
||||
|
||||
gd::SizeF UiWidget::ChildDesiredSize(std::size_t index) const
|
||||
{
|
||||
if (index >= m_children.size() || m_children[index] == nullptr)
|
||||
{
|
||||
return gd::SizeF(0.0f, 0.0f);
|
||||
}
|
||||
return m_children[index]->m_desiredSize;
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// 绘制
|
||||
// ------------------------------------------------------------------
|
||||
|
||||
bool UiWidget::DirtyIntersects(const gd::RectF& dirty) const
|
||||
{
|
||||
gd::RectF intersection;
|
||||
return UiRectIntersect(dirty, m_bounds, intersection);
|
||||
}
|
||||
|
||||
void UiWidget::Paint(UiPaintContext& ctx)
|
||||
{
|
||||
if (!m_visible || ctx.g == nullptr || !UiRectHasArea(m_bounds))
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
// (1) 与脏区求交：**脏区为空表示"未知 ⇒ 全画"**。
|
||||
gd::RectF effectiveDirty = ctx.dirty;
|
||||
if (UiRectHasArea(effectiveDirty) && !DirtyIntersects(effectiveDirty))
|
||||
{
|
||||
// 本节点及其整棵子树都不在脏区内 ⇒ 直接跳过（这是本框架唯一真正省时间的机制）。
|
||||
return;
|
||||
}
|
||||
|
||||
// (2) 裁剪 = 祖先裁剪切 ∩ 自身矩形；脏区非空时再与脏区求交（只更新需要更新的部分）。
|
||||
UiPaintContext local = ctx;
|
||||
gd::RectF clip;
|
||||
if (!UiRectIntersect(ctx.clip, m_bounds, clip))
|
||||
{
|
||||
return; // 完全被祖先裁掉
|
||||
}
|
||||
if (UiRectHasArea(effectiveDirty))
|
||||
{
|
||||
gd::RectF clipWithDirty;
|
||||
if (!UiRectIntersect(clip, effectiveDirty, clipWithDirty))
|
||||
{
|
||||
return;
|
||||
}
|
||||
clip = clipWithDirty;
|
||||
}
|
||||
local.clip = clip;
|
||||
|
||||
// (3) 收紧 GDI+ 裁剪。⚠️ 这里**只**约束 GDI+ 矢量绘制；GDI 绘制（`UiText` /
|
||||
// `UiFillRect` 的快路径 / `UiDrawSolidLines`）**不受**该裁剪约束 ⇒ 派生类必须把
|
||||
// `local.clip` 传给 `UiTextClipped` 一类带 `ETO_CLIPPED` 的辅助函数，
|
||||
// 否则文字会画到本节点之外（本项目"滚动时文字串到标题栏/工具栏"就是这类 BUG）。
|
||||
const int saveState = ctx.g->Save();
|
||||
ctx.g->SetClip(local.clip, gd::CombineModeIntersect);
|
||||
|
||||
local.dirty = UiRectHasArea(effectiveDirty) ? clip : gd::RectF();
|
||||
OnPaint(local);
|
||||
|
||||
// (4) 子节点：顺序 = z 序（末尾最上层），脏区向下取交集。
|
||||
for (const std::unique_ptr<UiWidget>& child : m_children)
|
||||
{
|
||||
if (child == nullptr)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
UiPaintContext childContext = local.WithClip(child->m_bounds);
|
||||
childContext.dirty = local.dirty;
|
||||
child->Paint(childContext);
|
||||
}
|
||||
|
||||
ctx.g->Restore(saveState);
|
||||
}
|
||||
|
||||
void UiWidget::Invalidate(const gd::RectF& rect)
|
||||
{
|
||||
if (!UiRectHasArea(rect))
|
||||
{
|
||||
return;
|
||||
}
|
||||
m_dirty = UiRectUnion(m_dirty, rect);
|
||||
if (m_parent != nullptr)
|
||||
{
|
||||
// 向上冒泡的是"客户区坐标"的同一块矩形；父层只并集，**不清空**子节点的脏区。
|
||||
m_parent->Invalidate(rect);
|
||||
}
|
||||
}
|
||||
|
||||
void UiWidget::InvalidateAll()
|
||||
{
|
||||
m_dirty = m_bounds;
|
||||
if (m_parent != nullptr)
|
||||
{
|
||||
m_parent->Invalidate(m_bounds);
|
||||
}
|
||||
for (const std::unique_ptr<UiWidget>& child : m_children)
|
||||
{
|
||||
if (child != nullptr)
|
||||
{
|
||||
child->InvalidateAll();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
gd::RectF UiWidget::TakeDirty()
|
||||
{
|
||||
const gd::RectF dirty = m_dirty;
|
||||
m_dirty = gd::RectF();
|
||||
return dirty;
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// 事件
|
||||
// ------------------------------------------------------------------
|
||||
|
||||
bool UiWidget::Contains(int x, int y) const
|
||||
{
|
||||
if (!m_visible || m_hitTransparent || !UiRectHasArea(m_bounds))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
const float fx = static_cast<float>(x);
|
||||
const float fy = static_cast<float>(y);
|
||||
return fx >= m_bounds.X && fx < m_bounds.X + m_bounds.Width && fy >= m_bounds.Y &&
|
||||
fy < m_bounds.Y + m_bounds.Height;
|
||||
}
|
||||
|
||||
UiWidget* UiWidget::HitTestDeep(int x, int y)
|
||||
{
|
||||
if (!Contains(x, y))
|
||||
{
|
||||
return nullptr;
|
||||
}
|
||||
// 反 z 序：末尾（最上层）优先。
|
||||
for (auto iterator = m_children.rbegin(); iterator != m_children.rend(); ++iterator)
|
||||
{
|
||||
if (*iterator == nullptr)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
if (UiWidget* hit = (*iterator)->HitTestDeep(x, y))
|
||||
{
|
||||
return hit;
|
||||
}
|
||||
}
|
||||
return this;
|
||||
}
|
||||
|
||||
UiEventResult UiWidget::Dispatch(UiEvent& event)
|
||||
{
|
||||
UiWidget* root = Root();
|
||||
if (root == nullptr)
|
||||
{
|
||||
return UiEventResult();
|
||||
}
|
||||
|
||||
const bool mouseEvent = (event.kind == UiEventKind::MOUSE_MOVE ||
|
||||
event.kind == UiEventKind::MOUSE_DOWN ||
|
||||
event.kind == UiEventKind::MOUSE_UP ||
|
||||
event.kind == UiEventKind::MOUSE_DOUBLE_CLICK ||
|
||||
event.kind == UiEventKind::MOUSE_WHEEL ||
|
||||
event.kind == UiEventKind::QUERY_CURSOR);
|
||||
|
||||
// (1) 捕获优先：拖拽期间所有鼠标事件直接投给捕获者（与 Windows `SetCapture` 同义）。
|
||||
if (mouseEvent && root->m_capture != nullptr)
|
||||
{
|
||||
return root->m_capture->OnEvent(event);
|
||||
}
|
||||
|
||||
// (2) 模态：只向模态子树派发（菜单/拾色器等浮层）。
|
||||
if (root->m_modal != nullptr)
|
||||
{
|
||||
return root->m_modal->DispatchAlongHitPath(event);
|
||||
}
|
||||
|
||||
// (3) 悬停链（只在根节点维护：鼠标移动会改变悬停者）。
|
||||
if (event.kind == UiEventKind::MOUSE_MOVE || event.kind == UiEventKind::MOUSE_LEAVE)
|
||||
{
|
||||
root->UpdateHover(event.x, event.y);
|
||||
}
|
||||
|
||||
// (4) 键盘/字符：沿焦点链派发（无焦点时交给根，保证宿主级快捷键仍可用）。
|
||||
if (event.kind == UiEventKind::KEY_DOWN || event.kind == UiEventKind::CHAR)
|
||||
{
|
||||
UiWidget* node = (root->m_focus != nullptr) ? root->m_focus : root;
|
||||
for (; node != nullptr; node = node->m_parent)
|
||||
{
|
||||
UiEventResult result = node->OnEvent(event);
|
||||
if (result.consumed)
|
||||
{
|
||||
return result;
|
||||
}
|
||||
}
|
||||
return UiEventResult();
|
||||
}
|
||||
|
||||
return DispatchAlongHitPath(event);
|
||||
}
|
||||
|
||||
void UiWidget::CollectHitChain(int x, int y, std::vector<UiWidget*>& chain)
|
||||
{
|
||||
if (!Contains(x, y))
|
||||
{
|
||||
return;
|
||||
}
|
||||
chain.push_back(this);
|
||||
// 反 z 序：末尾（最上层）优先；只进入**真正命中**的那一个子节点。
|
||||
for (auto iterator = m_children.rbegin(); iterator != m_children.rend(); ++iterator)
|
||||
{
|
||||
if (*iterator == nullptr)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
if ((*iterator)->Contains(x, y))
|
||||
{
|
||||
(*iterator)->CollectHitChain(x, y, chain);
|
||||
return;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
UiEventResult UiWidget::DispatchAlongHitPath(UiEvent& event)
|
||||
{
|
||||
if (!m_visible)
|
||||
{
|
||||
return UiEventResult();
|
||||
}
|
||||
|
||||
const bool positional = (event.kind == UiEventKind::MOUSE_MOVE ||
|
||||
event.kind == UiEventKind::MOUSE_DOWN ||
|
||||
event.kind == UiEventKind::MOUSE_UP ||
|
||||
event.kind == UiEventKind::MOUSE_DOUBLE_CLICK ||
|
||||
event.kind == UiEventKind::MOUSE_WHEEL ||
|
||||
event.kind == UiEventKind::QUERY_CURSOR);
|
||||
|
||||
if (!positional)
|
||||
{
|
||||
// 非位置事件（理论上已被 `Dispatch` 分流）：自身优先，再逐个子节点。
|
||||
UiEventResult result = OnEvent(event);
|
||||
if (result.consumed)
|
||||
{
|
||||
return result;
|
||||
}
|
||||
for (const std::unique_ptr<UiWidget>& child : m_children)
|
||||
{
|
||||
if (child == nullptr || !child->m_visible)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
result = child->DispatchAlongHitPath(event);
|
||||
if (result.consumed)
|
||||
{
|
||||
return result;
|
||||
}
|
||||
}
|
||||
return UiEventResult();
|
||||
}
|
||||
|
||||
std::vector<UiWidget*> chain;
|
||||
CollectHitChain(event.x, event.y, chain);
|
||||
if (chain.empty())
|
||||
{
|
||||
return UiEventResult();
|
||||
}
|
||||
|
||||
// 自最深的命中节点向上冒泡：命中者优先，未消费才交给祖先（合法的"兜底"语义）。
|
||||
for (UiWidget* node : chain)
|
||||
{
|
||||
if (event.kind == UiEventKind::QUERY_CURSOR)
|
||||
{
|
||||
if (HCURSOR cursor = node->OnQueryCursor(event.x, event.y))
|
||||
{
|
||||
event.cursor = cursor;
|
||||
return UiEventResult::Swallowed();
|
||||
}
|
||||
continue;
|
||||
}
|
||||
UiEventResult result = node->OnEvent(event);
|
||||
if (result.consumed)
|
||||
{
|
||||
return result;
|
||||
}
|
||||
}
|
||||
if (event.kind == UiEventKind::QUERY_CURSOR && event.cursor != nullptr)
|
||||
{
|
||||
return UiEventResult::Swallowed();
|
||||
}
|
||||
return UiEventResult();
|
||||
}
|
||||
|
||||
void UiWidget::UpdateHover(int x, int y)
|
||||
{
|
||||
UiWidget* target = (m_visible) ? HitTestDeep(x, y) : nullptr;
|
||||
if (target == m_hover)
|
||||
{
|
||||
return;
|
||||
}
|
||||
UiWidget* previous = m_hover;
|
||||
m_hover = target;
|
||||
if (previous != nullptr)
|
||||
{
|
||||
previous->OnHoverChanged(false);
|
||||
previous->Invalidate(previous->m_bounds);
|
||||
}
|
||||
if (target != nullptr)
|
||||
{
|
||||
target->OnHoverChanged(true);
|
||||
target->Invalidate(target->m_bounds);
|
||||
}
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// 交互仲裁
|
||||
// ------------------------------------------------------------------
|
||||
|
||||
void UiWidget::CaptureMouse()
|
||||
{
|
||||
UiWidget* root = Root();
|
||||
if (root != nullptr)
|
||||
{
|
||||
root->m_capture = this;
|
||||
}
|
||||
}
|
||||
|
||||
void UiWidget::ReleaseMouse()
|
||||
{
|
||||
UiWidget* root = Root();
|
||||
if (root != nullptr && root->m_capture == this)
|
||||
{
|
||||
root->m_capture = nullptr;
|
||||
}
|
||||
}
|
||||
|
||||
UiWidget* UiWidget::MouseCaptureWidget() const
|
||||
{
|
||||
const UiWidget* root = Root();
|
||||
return (root != nullptr) ? root->m_capture : nullptr;
|
||||
}
|
||||
|
||||
void UiWidget::SetModal(bool modal)
|
||||
{
|
||||
UiWidget* root = Root();
|
||||
if (root == nullptr)
|
||||
{
|
||||
return;
|
||||
}
|
||||
if (modal)
|
||||
{
|
||||
root->m_modal = this;
|
||||
}
|
||||
else if (root->m_modal == this)
|
||||
{
|
||||
root->m_modal = nullptr;
|
||||
}
|
||||
}
|
||||
|
||||
UiWidget* UiWidget::ModalWidget() const
|
||||
{
|
||||
const UiWidget* root = Root();
|
||||
return (root != nullptr) ? root->m_modal : nullptr;
|
||||
}
|
||||
|
||||
UiWidget* UiWidget::HoverWidget() const
|
||||
{
|
||||
const UiWidget* root = Root();
|
||||
return (root != nullptr) ? root->m_hover : nullptr;
|
||||
}
|
||||
|
||||
void UiWidget::RequestFocus()
|
||||
{
|
||||
UiWidget* root = Root();
|
||||
if (root == nullptr || root->m_focus == this)
|
||||
{
|
||||
return;
|
||||
}
|
||||
if (root->m_focus != nullptr)
|
||||
{
|
||||
root->m_focus->Invalidate(root->m_focus->m_bounds);
|
||||
}
|
||||
root->m_focus = this;
|
||||
Invalidate(m_bounds);
|
||||
}
|
||||
|
||||
void UiWidget::ReleaseFocus()
|
||||
{
|
||||
UiWidget* root = Root();
|
||||
if (root != nullptr && root->m_focus == this)
|
||||
{
|
||||
root->m_focus = nullptr;
|
||||
Invalidate(m_bounds);
|
||||
}
|
||||
}
|
||||
|
||||
UiWidget* UiWidget::FocusWidget() const
|
||||
{
|
||||
const UiWidget* root = Root();
|
||||
return (root != nullptr) ? root->m_focus : nullptr;
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// 动画
|
||||
// ------------------------------------------------------------------
|
||||
|
||||
bool UiWidget::AdvanceAnimation(std::int64_t nowMs)
|
||||
{
|
||||
bool active = AdvanceAnimationSelf(nowMs);
|
||||
for (const std::unique_ptr<UiWidget>& child : m_children)
|
||||
{
|
||||
if (child != nullptr && child->AdvanceAnimation(nowMs))
|
||||
{
|
||||
active = true;
|
||||
}
|
||||
}
|
||||
return active;
|
||||
}
|
||||
|
||||
bool UiWidget::AnimationActive() const
|
||||
{
|
||||
if (AnimationActiveSelf())
|
||||
{
|
||||
return true;
|
||||
}
|
||||
for (const std::unique_ptr<UiWidget>& child : m_children)
|
||||
{
|
||||
if (child != nullptr && child->AnimationActive())
|
||||
{
|
||||
return true;
|
||||
}
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------
|
||||
// 缓存键
|
||||
// ------------------------------------------------------------------
|
||||
|
||||
std::uint64_t UiWidget::BaseContentKey() const
|
||||
{
|
||||
std::uint64_t key = 0xCBF29CE484222325ull;
|
||||
key = UiMixKeyFloat(key, m_bounds.X);
|
||||
key = UiMixKeyFloat(key, m_bounds.Y);
|
||||
key = UiMixKeyFloat(key, m_bounds.Width);
|
||||
key = UiMixKeyFloat(key, m_bounds.Height);
|
||||
key = UiMixKey(key, m_visible ? 1u : 0u);
|
||||
return key;
|
||||
}
|
||||
|
||||
} // namespace jdi
|
||||
@@ -0,0 +1,304 @@
|
||||
# UI 重构计划（UI_Refactor 分支）
|
||||
|
||||
> 目标读者：本项目的后续 Agent（可能是另一台设备 / 另一个模型）。
|
||||
> 本文是**唯一施工蓝图**；实时进度见 `Documents/UI_Refactor_Progress.md`，最终结论见 `Documents/UI_Refactor_Report.md`。
|
||||
> 硬约束的权威来源仍是 `Documents/agent_mem.md`（§11.2）；本文与之冲突时**以 agent_mem.md 为准**。
|
||||
|
||||
---
|
||||
|
||||
## 0. 为什么要重构（量化基线）
|
||||
|
||||
| 指标 | 现状 | 出处 |
|
||||
| --- | --- | --- |
|
||||
| `PlotViewPaint.cpp` | **9 080 行**（注释 1 295 / 空行 517 / 仅大括号 2 026 / **有效代码 5 242**） | `Get-Content \| Measure-Object` |
|
||||
| `PlotView.hpp` | 3 649 行、**310 个方法**、**203 个成员变量**、31 个嵌套类型 | 同上 |
|
||||
| `EdgePanelLayoutFor` | **651 行**、**19 个调用点**，每帧被命中/层序/光标/绘制各算一遍 | `Select-String` |
|
||||
| `Application.cpp` 的 `InvalidateRect` | **56 处** + 手写 `m_chromeDirty` / `m_panelDirty` / `panelOnly` / `fullFrame` 组合 | 同上 |
|
||||
| 动画 | **5 套**手写动画散在 3 个组件，共用一个 10ms 定时器 | 同上 |
|
||||
| 自动化 UI 探针 | **0**（`.preflight` 已被删除且被 gitignore） | 仓库现状 |
|
||||
|
||||
`PlotViewPaint.cpp` 里混住四类内容：真绘制 ≈3.5k / 光栅化缓存 ≈2.5k / 缓存键 ≈1.1k / **布局与命中几何 ≈1.3k**。
|
||||
|
||||
**五条根因**
|
||||
|
||||
1. 上次拆 13 695 行大文件时按**函数名**（"带 `Paint` 前缀"）而非**关注点**分片 ⇒ 缓存、缓存键、面板布局、命中几何全被倒进 paint 分片。
|
||||
2. 没有控件抽象 ⇒ 每个叠加层自带"几何 + 命中 + 绘制 + 缓存键"四份重复；5 个实验性面板各 800~1 200 行，靠 10 多个平行数组（`rowRefs/rowChecks/rowPoints/rowOrder/rowLevelTracks/...`）下标对齐"假装"成树。
|
||||
3. GDI / GDI+ 双栈妥协被**每个绘制点重复支付**（GDI 文本不认 GDI+ 裁剪、`UiFillRect` 的 GDI 快路径绕过裁剪、GDI 文本忽略 alpha…）。
|
||||
4. "必须混进缓存键，否则贴旧像素"这条不变量**没有归属**（4 套手写 key + 一堆 `Collect*` ≈1.1k 行；历史 ≥4 次真实 BUG 是"忘了混一个字段"）。
|
||||
5. 1 295 行硬核"为什么"注释让行数虚高 —— **保留，不删**（多 Agent 协作防回归的核心资产）。
|
||||
|
||||
---
|
||||
|
||||
## 1. 设计目标与非目标
|
||||
|
||||
### 1.1 目标（必须达成）
|
||||
|
||||
1. **几何只算一次**：布局是"按需失效的 pass"，命中/绘制/光标共用同一份结果。
|
||||
2. **失效从布尔变矩形**：`dirty ∩ bounds` 为空 ⇒ 整棵子树跳过（这是唯一真正省钱的层次）。
|
||||
3. **裁剪契约统一**：`Paint` 进入时同时收紧 GDI 裁剪与 GDI+ 裁剪，根治"文字画到图例/工具栏上"这类已出现 3 次的 BUG。
|
||||
4. **缓存键有归属**：由"持有该内容的节点"产生，父层只聚合。
|
||||
5. **事件派发显式化**：`{consumed, redraw, dirtyRect}` 代替 `bool 要不要重绘`；capture / 模态 / hover / 焦点 / 光标仲裁由基类提供。
|
||||
6. **动画统一 tick**：一个动画列表 + 现有 `kScrollTimerId` 推进。
|
||||
7. **零行为变更的先行阶段**：先拆文件、补回归网，再动语义。
|
||||
|
||||
### 1.2 非目标（明确不做，写进禁区）
|
||||
|
||||
| 禁区 | 原因 |
|
||||
| --- | --- |
|
||||
| ❌ 波形数据→像素管线控件化（网格/曲线/采样点不做成节点） | 布局与虚调用会进每帧热路径；采样/顶点量与控件无关 |
|
||||
| ❌ 每个控件自持位图 | 内存按面积线性增长：逐网格图层已是屏幕面积 2 倍（5 网格 ≈16MB，**128 网格 ≈250MB**） |
|
||||
| ❌ "父脏 ⇒ 子树全脏" | 会把"只重绘一个网格/一个面板"打回整块重绘（历史最易发生的退化） |
|
||||
| ❌ 多线程光栅 | GDI+ 内部串行，实测 **1.03x**；且后台改写 `m_area`/`ViewMin` 会覆盖用户平移（第一代已因此回退） |
|
||||
| ❌ 逐控件细粒度像素缓存 | 画一个按钮 20~80µs vs 贴图 5~10µs ⇒ 净亏损，还要付"忘混键"的风险 |
|
||||
| ❌ 引入属性对象体系（学 Blink） | 那是为 Blink 规模准备的；本项目用"节点产生 key"即可 |
|
||||
|
||||
### 1.3 借鉴来源与取舍
|
||||
|
||||
| 借鉴 | 采纳 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| Chromium `views::View` 的**失效驱动布局 pass** | ✅ 全采纳 | 对应 §3 的 `UiWidget::Measure/Arrange` + `UiLayoutCache` |
|
||||
| `views::View::PaintChildren` 的**脏矩形下探** | ✅ 全采纳 | 对应 §4 的 `PaintContext.dirty` |
|
||||
| `SetPaintToLayer()` 只提升**少数**子树 | ✅ 保持现状量级（4 层） | 不再新增层 |
|
||||
| `cc` 的**记录-光栅分离 / tiling / checkerboarding / 每帧预算** | ✅ 已具备，不改 | `PolylineCacheEntry`、宽基底+补条、贴过期但位置正确、`RenderPendingLaneRebuilds(1)` |
|
||||
| `cc` 的**多线程光栅 / GPU 合成** | ❌ 不采纳 | GDI+ 无 GPU 路径；并行实测 1.03x |
|
||||
| Dear ImGui 的**每帧全量重画** | ❌ 不采纳 | 本项目整幅重绘 ≈80ms，必须走失效 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标架构
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
H[UiHost<br/>持有 app-sized 32bpp top-down DIB<br/>z 序 · 脏区并集 · 一次 BitBlt 回送 · 动画 tick]
|
||||
H --> R[UiRoot : UiWidget]
|
||||
R --> D{脏区树<br/>dirty ∩ bounds 空 ⇒ 整棵子树 return}
|
||||
D --> A[普通控件：直接画进共享缓冲<br/>按钮 / 文本 / 列表行 / 时间轴 / 图例]
|
||||
D --> B[高成本叶子：自持位图，完成即 BitBlt 贴回<br/>波形网格 / 装饰层 / 光晕 / 浮动面板]
|
||||
A --> S[SurfaceView{ dc, rect, stride, bits, version }]
|
||||
B --> S
|
||||
```
|
||||
|
||||
**分层原则**
|
||||
|
||||
- **共享一张缓冲**：省内存、免分配抖动、合成顺序天然确定。
|
||||
- **只有高成本叶子自持缓冲**：这是"把重画换成贴图"的唯一手段。
|
||||
- **脏区向下取交集**（不是并集）。
|
||||
- **布局由下往上、每帧最多一轮 Measure**；尺寸由内容反推（`EdgePanelWidth` 就是这种）。
|
||||
|
||||
### 2.1 新增文件
|
||||
|
||||
| 文件 | 职责 | 依赖 |
|
||||
| --- | --- | --- |
|
||||
| `Components/Shared/Inc/UiLayout.hpp` / `Src/UiLayout.cpp` | 纯几何：`UiInsets`、栈/流/锚点/对齐、`UiLayoutCache` | 仅 `Theme.hpp`（`gd::RectF`） |
|
||||
| `Components/Shared/Inc/UiWidget.hpp` / `Src/UiWidget.cpp` | 控件基类：树、Measure/Arrange、双栈裁剪 Paint、事件派发、失效、capture/模态/hover/焦点/光标、动画 tick | `UiLayout.hpp`、`PaintUtil.hpp` |
|
||||
| `Components/Shared/Inc/UiHost.hpp` / `Src/UiHost.cpp` | 宿主：共享 DIB + `SurfaceView` + 脏区并集 + 回送 + 消息翻译 + 动画定时器 | `UiWidget.hpp` |
|
||||
| `Tools/uicheck/`（入库） | 离屏回归网（`SW_HIDE` + 注入消息 + 从 `m_backDc` 取帧） | `Build/Release/*.o` |
|
||||
|
||||
> ⚠️ `Components/Shared` 已在 `Makefile` 的 `CXX_INCLUDES_PATHS` / `CXX_SOURCES_PATHS` 中 ⇒ 新增 `.cpp` **无需改 Makefile**（按 basename 自动收集）。
|
||||
|
||||
---
|
||||
|
||||
## 3. 布局层设计（`UiLayout`）
|
||||
|
||||
### 3.1 为什么不是简单的"宽高字段"
|
||||
|
||||
基类若只有 `width/height`，会在三处立刻失效：
|
||||
|
||||
1. 所有坐标是**逻辑像素 × scale**（本机 DPR 1.25），控件必须知道缩放；
|
||||
2. 面板宽度是**由内容反推**（`EdgePanelWidth` = 列宽 max + 行 ✕ + 滚动条预留）；
|
||||
3. 离屏位图要求**设备像素整数对齐**（`floor`/`ceil` 方向错了就留 1px 接缝 —— 样式补丁曾踩过）。
|
||||
|
||||
⇒ 采用 **`Measure(约束) → 期望尺寸` / `Arrange(最终矩形) → 实际矩形`** 两段式。
|
||||
|
||||
### 3.2 需要的布局种类（按实际用量排序）
|
||||
|
||||
| 布局 | 用途 | 备注 |
|
||||
| --- | --- | --- |
|
||||
| **Abs（绝对）** | 绘图区叠加物主力：光标线、取值胶囊、吸附环、越界三角、固定点、面板初始位置、滚动条 | 保留"自由布局"，但它是**主力**而非备选 |
|
||||
| **Anchor（四边贴合）** | 工具栏整体靠右、时间轴贴底、滚动条贴右、面板夹在 `m_plotRect` 内 | 讨论中缺失，必须补 |
|
||||
| **Stack（竖向流）** | 信号列表行、分组行、面板条目（名称行 + 参数行 + 滑块行） | 需支持"行高由内容决定 + 吸顶(sticky) + 滚动视口" |
|
||||
| **Flow（横向流 + 溢出）** | 图例条目 + 空间不足的 `+N`、工具栏按钮组 | 讨论中缺失，必须补 |
|
||||
| **Measure-driven** | 面板宽度按实测文本撑开、列宽 `max(缺省, 内容, 列标题)` | 必须有，否则又回到"绘制侧省略号" |
|
||||
| Grid | **用不上**（绘图区不是表格） | 不实现 |
|
||||
| Card | 只是"面板皮肤" | 作为 `UiPanelSkin` 绘制样式，不是布局 |
|
||||
|
||||
### 3.3 `UiLayoutCache`（本次最关键的性能点）
|
||||
|
||||
`EdgePanelLayoutFor` 的 19 个调用点全部来自"同一份几何被反复问"。做法：
|
||||
|
||||
```cpp
|
||||
class UiLayoutCache
|
||||
{
|
||||
public:
|
||||
// key 由调用方提供（例如 laneIndex + kind + 面板宽 + 缩放 + 条目数）
|
||||
const LayoutEntry* Find(std::uint64_t key) const;
|
||||
const LayoutEntry& Store(std::uint64_t key, LayoutEntry&& entry);
|
||||
void Invalidate(std::uint64_t key); // 定向失效
|
||||
void Clear();
|
||||
};
|
||||
```
|
||||
|
||||
**硬约束**：`Invalidate` 必须由"改变几何的那条路径"**显式**调用（与 `m_edgeScans` 的定向失效同一纪律），**禁止**为了让缓存命中率好看而整体 `Clear()`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 控件基类设计（`UiWidget`）
|
||||
|
||||
### 4.1 接口骨架
|
||||
|
||||
```cpp
|
||||
struct UiEventResult
|
||||
{
|
||||
bool consumed = false; // 事件已被消费（不再下传/上抛）
|
||||
bool redraw = false; // 需要重绘
|
||||
gd::RectF dirty; // 需要重绘的矩形（客户区坐标；空 = 未知 ⇒ 取自身 bounds）
|
||||
};
|
||||
|
||||
class UiWidget
|
||||
{
|
||||
public:
|
||||
virtual ~UiWidget();
|
||||
|
||||
// ---- 树 ----
|
||||
void AddChild(std::unique_ptr<UiWidget> child);
|
||||
void RemoveChild(UiWidget* child);
|
||||
const std::vector<std::unique_ptr<UiWidget>>& Children() const;
|
||||
|
||||
// ---- 布局（两段式，各自带失效）----
|
||||
void InvalidateMeasure(); // 向上冒泡到根
|
||||
void InvalidateArrange();
|
||||
gd::SizeF Measure(const UiMeasureContext& ctx); // 自下而上，命中缓存则直接返回
|
||||
void Arrange(const gd::RectF& bounds); // 自上而下；bounds 一定 > 0
|
||||
|
||||
// ---- 绘制（双栈裁剪 + 脏区下探）----
|
||||
void Paint(UiPaintContext& ctx); // 内部：与 dirty 求交 → OnPaint → 递归子节点
|
||||
virtual void Invalidate(const gd::RectF& rect); // 局部失效（向上冒泡并入）
|
||||
|
||||
// ---- 事件 ----
|
||||
UiEventResult Dispatch(UiEvent& event); // 命中 → 子节点（反 z 序）→ OnEvent
|
||||
|
||||
// ---- 命中 / 光标 ----
|
||||
bool Contains(int x, int y) const;
|
||||
virtual HCURSOR QueryCursor(int x, int y) { return nullptr; }
|
||||
|
||||
// ---- 交互仲裁（由 Host 调用）----
|
||||
UiWidget* Capture(); void SetCapture(); void ReleaseCapture();
|
||||
void SetModal(bool modal); // 模态子树：Host 只向它派发
|
||||
void SetHitTransparent(bool value); // 装饰元素：不参与命中
|
||||
|
||||
// ---- 动画 ----
|
||||
virtual bool AdvanceAnimation(std::int64_t nowMs) { return false; }
|
||||
|
||||
protected:
|
||||
virtual gd::SizeF OnMeasure(const UiMeasureContext& ctx) = 0;
|
||||
virtual void OnArrange() {}
|
||||
virtual void OnPaint(UiPaintContext& ctx) = 0;
|
||||
virtual UiEventResult OnEvent(UiEvent& event) { return {}; }
|
||||
virtual std::uint64_t ContentKey() const; // 缓存键的来源（父层只聚合）
|
||||
};
|
||||
```
|
||||
|
||||
### 4.2 `Paint` 的硬契约（必须由基类保证，不是"每个控件记得"）
|
||||
|
||||
1. **双栈裁剪**：进入时 `SaveDC + IntersectClipRect`（GDI）+ `Graphics::SetClip(Intersect)`（GDI+），退出时还原。这一条一次性消灭"滚动时文字串到标题栏""全选高亮溢出输入框""选区画到工具栏上"。
|
||||
2. **脏区下探**：`ctx.dirty = ctx.dirty ∩ bounds`；若为空 ⇒ **整棵子树直接 return**（不调 `OnPaint`、不遍历子节点）。
|
||||
3. **绘制顺序 = 子节点顺序 = z 序**；命中/事件 = **反 z 序**（与现在 `m_panelOrder` + `TopPanelAtPoint` 反向遍历等价，但不再靠人工维护）。
|
||||
4. **禁止**在 `OnPaint` 内改 `bounds`/子节点集合（会与本帧的 dirty 不一致）。
|
||||
|
||||
### 4.3 事件派发的硬契约
|
||||
|
||||
- **`consumed`** 决定是否上抛；**`dirty`** 参与本帧脏区并集。
|
||||
- **capture**：抓取期间所有鼠标事件**直接投给抓取者**（跳过命中），与 Windows `SetCapture` 语义一致。本项目硬约束：中键平移与左键拖拽**共用同一个 capture**，松左键**不能**无条件 `ReleaseCapture()`。
|
||||
- **模态**：菜单打开时 Host 只向模态子树派发，且"取消底层拖拽"时必须**排除菜单自己的 `EDIT_FIELD`**。
|
||||
- **hover**：Host 维护 hover 链，跨节点 `leave/enter`；悬停是**跨组件**的（面板行 → 网格固定点高亮；列表行 → 曲线光晕）⇒ 通过 Host 级"悬停信号总线"广播，不靠父子关系。
|
||||
- **双击消歧**：窗口带 `CS_DBLCLKS`；没有双击语义的位置必须在 `DoubleClickIsPlainPress()` 返回 true，由 Host 改走普通按下（否则"连点丢一半"）。
|
||||
|
||||
### 4.4 失效契约
|
||||
|
||||
- 节点持 `m_dirty`（自身坐标系）+ `m_dirtyChildren`；
|
||||
- `Invalidate(rect)` 并入自身并**向上冒泡**（父层只并集矩形，**绝不**把子树的 dirty 清零）；
|
||||
- Root 暴露 `TakeDirty()` 给 Host，Host 再与窗口更新区域取并集。
|
||||
|
||||
---
|
||||
|
||||
## 5. 宿主层设计（`UiHost`）
|
||||
|
||||
1. **单一 app-sized 32bpp top-down DIB**（替换现在的 `CreateCompatibleBitmap`）：
|
||||
```cpp
|
||||
struct SurfaceView
|
||||
{
|
||||
HDC dc; // 共享 HDC（GDI/GDI+ 都画这个）
|
||||
gd::RectF rect; // 本节点在 Holder 坐标系中的矩形（设备像素，整数对齐）
|
||||
int stride; // 行字节数（**不可**假设 = width*4）
|
||||
std::uint32_t* bits; // rect 左上角那一像素（不是位图首地址）
|
||||
std::uint64_t version; // 位图代次；失配 ⇒ 句柄作废
|
||||
};
|
||||
```
|
||||
⚠️ **绝不能缓存裸指针**：`EnsureBackBuffer` 在 `WM_SIZE` / `WM_DPICHANGED` 会重建位图。
|
||||
⚠️ `bits` 只在 **CPU 侧直写**（memcpy/alpha）时用；GDI/GDI+ 绘制只需 `dc + rect`。
|
||||
2. **脏区并集**：把现在 56 处 `InvalidateRect` 收敛为 `Host::Invalidate(rect)`，一次回送。
|
||||
⚠️ 回送仍必须**有无条件 `else`**（历史：某分支缺兜底 ⇒ 窗口一个像素都不回送，用户看到三个不同症状）。
|
||||
3. **动画 tick**：`AdvanceAnimation` 遍历树，任一为 true 就保持 `kScrollTimerId`（10ms）。
|
||||
4. **消息翻译**：`WM_*` → `UiEvent`，并把 `WM_SETCURSOR` 交给 `QueryCursor` 链（从 z 顶向下、首个非 null 生效）。
|
||||
|
||||
---
|
||||
|
||||
## 6. 落地阶段（每阶段一个可独立回滚的提交）
|
||||
|
||||
| 阶段 | 内容 | 交付判据 |
|
||||
| --- | --- | --- |
|
||||
| **P0** | 离屏回归网 `Tools/uicheck`（入库）+ 现有 20+ 条硬约束的断言骨架 | 能一键跑；对现版本全绿 |
|
||||
| **P1** | `UiLayout` + `UiWidget` 基础层（本次） | 编译零警告；`uicheck` 覆盖布局数学 + 派发/裁剪/脏区/动画 |
|
||||
| **P2** | 零行为变更分片：`PlotViewPaint.cpp` 拆成 `Paint`（只画）/ `Raster`（缓存与预算）/ `CacheKey`（指纹）/ `Geometry`（面板与命中）；`EdgePanelLayoutFor`、`ProbeFreeMarker` 迁回交互侧 | **逐像素 0 差异**（用 P0 的场景哈希断言） |
|
||||
| **P3** | 迁移 chrome：Toolbar → TabBar → PopupMenu → ColorPicker → SignalPanel 行（**一次一个组件、每完成一个跑全量探针**） | 每个组件迁移后 `uicheck` 全绿 + 手工契约断言 |
|
||||
| **P4** | 迁移 5 个浮动面板（`EdgePanelLayoutFor` 651 行 → 真控件；消掉平行数组） | 同上；`EdgePanelLayoutFor` 行数下降 >60% |
|
||||
| **P5** | 波形管线包成叶子 surface（**只包不改**）+ 共享 DIB 落地 | `uicheck` 全绿；`Target.exe` ≤ 900KB |
|
||||
|
||||
**P2 之前禁止改任何行为**。P2 是唯一的"免费"阶段，别顺手改语义。
|
||||
|
||||
---
|
||||
|
||||
## 7. 验证策略（不占用用户鼠标/键盘/屏幕）
|
||||
|
||||
1. **离屏 harness**：`SW_HIDE` 窗口 + 直接 `app.HandleMessage(...)` 注入 + 从 `m_backDc` 用 `GetDIBits` 取帧。
|
||||
2. **进程/线程优先级 `BELOW_NORMAL`**；从不用 `SetCursorPos` / `SendInput` / 截屏。
|
||||
3. **A/B 反证**：每条新断言都要能被"还原旧实现"证伪，否则不算通过。
|
||||
4. **像素判据要选对区域**：验证"某交互不应改变外观"时，只对**不受影响**的区域取哈希。
|
||||
5. **已知陷阱**（全部来自历史 BUG）：
|
||||
- 探针消息泵必须丢弃 `WM_MOUSELEAVE`（离屏窗口会立刻兑现它）；
|
||||
- 注入按下后立即 `ReleaseCapture()`（避免抢真实鼠标）；
|
||||
- `CycleCursorMode()` 是**循环**，多组用例里重复调用会把光标关掉；
|
||||
- `PlotView` 的嵌套类型（`LaneVisual`/`LegendHit`/`EdgePanelLayout`）使用时要写 `PlotView::` 前缀。
|
||||
|
||||
---
|
||||
|
||||
## 8. 协作纪律（多 Agent）
|
||||
|
||||
1. **文件所有权**：同一时刻**一个 Agent 只改一个文件的同一区域**；跨阶段并行时按下表分工，禁止交叉。
|
||||
2. **每阶段一个提交**，提交信息写清"改了什么 / 为什么 / 怎么验证"。
|
||||
3. **先写断言再改代码**。
|
||||
4. `main` / `dev` 只接受全绿；`UI_Refactor` 内允许临时红，但**不许跨轮次累积红**。
|
||||
5. 任何"规则变更"必须同步进 `Documents/agent_mem.md`（§11.2 追加编号），否则另一端看不到。
|
||||
6. 体积红线 **900KB**（到达即提醒用户，不是禁止超过）。
|
||||
|
||||
### 8.1 并行分工建议（若启用多个 Agent）
|
||||
|
||||
| Agent | 独占文件 | 禁止触碰 |
|
||||
| --- | --- | --- |
|
||||
| A（基础层） | `UiLayout.*`、`UiWidget.*`、`UiHost.*`、`Tools/uicheck/*` | 任何现有组件 |
|
||||
| B（分片） | `PlotViewPaint.cpp` → 新分片文件、`PlotViewInternal.hpp` 的 include 段 | `UiWidget.*`、面板逻辑 |
|
||||
| C（面板迁移） | `PlotViewFeatures.cpp` 的面板段、新建 `PlotViewPanels.cpp` | `PlotViewPaint.cpp`、`UiLayout.*` |
|
||||
|
||||
> 冲突高发点：`Makefile`（新增目录时才需要改）、`agent_mem.md`（追加编号必须串行）。
|
||||
|
||||
---
|
||||
|
||||
## 9. 风险与回滚
|
||||
|
||||
| 风险 | 触发条件 | 回滚 |
|
||||
| --- | --- | --- |
|
||||
| 迁移后"连点丢一半" | `DoubleClickIsPlainPress` 语义漏实现 | 单组件提交可独立 revert |
|
||||
| 迁移后"拖动卡住" | capture 共用被拆成两套 | 同上 |
|
||||
| 面板失效不全（贴旧像素） | `ContentKey()` 漏字段 | P4 里每个面板配一条"改 X 后像素必须变"的断言 |
|
||||
| 体积超 900KB | 新框架代码量 | 每阶段结束量一次；超阈值先报告用户 |
|
||||
| 布局级联死循环 | Measure 里改子节点 | 单元测试固定"Measure 一轮即收敛" |
|
||||
@@ -0,0 +1,86 @@
|
||||
# UI 重构进度（UI_Refactor 分支）
|
||||
|
||||
> 本文件是**跨会话/跨 Agent 的交接台账**。每次提交前更新；每一行都要能对应到一个可复跑的验证结果。
|
||||
> 计划见 `Documents/UI_Refactor_Plan.md`；硬约束见 `Documents/agent_mem.md` §11.2。
|
||||
|
||||
## 分支状态
|
||||
|
||||
| 分支 | 基线 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| `main` | `df715a0` | 可发布，**不受本次重构影响** |
|
||||
| `dev` | `4e51b41`（删除过时报告 `refactor_report_2026-10-16.md`） | 日常开发基线 |
|
||||
| `UI_Refactor` | 从 `dev` 切出 | 本次 UI 重构（全部提交只留在本地） |
|
||||
|
||||
## 阶段看板
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
| --- | --- | --- |
|
||||
| **P0** | 离屏回归网 `Tools/uicheck`（入库） | ✅ 完成（62 项断言全绿） |
|
||||
| **P1** | `UiLayout` + `UiWidget` 基础层 | ✅ 完成（编译零警告，`uicheck` 覆盖） |
|
||||
| **P2** | `PlotViewPaint.cpp` 零行为分片 | ⏳ 待做 |
|
||||
| **P3** | 迁移 chrome（Toolbar / TabBar / 菜单 / 拾色器 / 列表行） | ⏳ 待做 |
|
||||
| **P4** | 迁移 5 个浮动面板 | ⏳ 待做 |
|
||||
| **P5** | 波形管线包成叶子 surface + 共享 DIB | ⏳ 待做 |
|
||||
|
||||
---
|
||||
|
||||
## 提交记录
|
||||
|
||||
### 1. `P0 + P1`：UI 基础层与离屏回归网
|
||||
|
||||
**新增文件**
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
| --- | --- | --- |
|
||||
| `Components/Shared/Inc/UiLayout.hpp` | ~250 | 布局原语 + `UiLayoutCache` |
|
||||
| `Components/Shared/Src/UiLayout.cpp` | ~300 | 矩形原语 / 对齐 / Stack / Flow / 缓存 |
|
||||
| `Components/Shared/Inc/UiWidget.hpp` | ~330 | 控件基类接口与设计说明 |
|
||||
| `Components/Shared/Src/UiWidget.cpp` | ~560 | 树 / Measure·Arrange / Paint（脏区+裁剪）/ 派发 / 仲裁 / 动画 |
|
||||
| `Tools/uicheck/main.cpp` | ~570 | 离屏回归网（62 项断言） |
|
||||
| `Tools/uicheck/build.ps1` | ~70 | 链接 `Build/<Config>/*.o`（排除 `Main.o`） |
|
||||
|
||||
**已实现并验证的行为**
|
||||
|
||||
- 布局：`UiAlignInRect`（含 `STRETCH`、超尺寸夹取、偏移后置）、`UiRectSnapInward`（设备像素内侧对齐）、
|
||||
`UiStackRects`（固定 / `kUiSizeAuto` 均分 / **绝不产生负尺寸**）、`UiFlowRects`（换行 + `overflow` 下标）。
|
||||
- 缓存：`UiLayoutCache` 用 `std::deque` 保证**引用稳定**；容量淘汰按"最久未命中"；`Invalidate` 为**定向**失效。
|
||||
- 布局 pass：`Measure` 命中缓存不重复调用 `OnMeasure`；`InvalidateMeasure` **只**沿祖先链失效（兄弟不重算）。
|
||||
- 绘制：`dirty` 为空 = 全画；与子树矩形无交集 ⇒ **整棵子树跳过**；有效裁剪 = 祖先裁剪切 ∩ 自身矩形 ∩ 脏区；
|
||||
不可见节点跳过。
|
||||
- 派发：**只沿命中链**（最深的命中节点 → 祖先冒泡），**绝不分发给同层兄弟**；`capture` 期间事件直投捕获者；
|
||||
`modal` 只向模态子树派发；`hit-transparent` 让事件穿透；`QUERY_CURSOR` 由最上层认领者返回；
|
||||
键盘/字符沿**焦点链**派发（无焦点交给根，保证宿主级快捷键可用）。
|
||||
- 动画：`AdvanceAnimation` 逐节点下发同一时间戳并汇总"是否仍有动画"。
|
||||
- 悬停：进入 / 离开各只触发一次，跨子节点迁移时正确配对。
|
||||
|
||||
**过程中修掉的两个自身缺陷**
|
||||
|
||||
1. `UiWidget` 缺 `AdvanceAnimationSelf` / `AnimationActiveSelf` 两个 protected 虚函数（`.cpp` 已引用、头文件漏声明）。
|
||||
2. 最初的派发实现是"遍历同层兄弟、未消费就继续" ⇒ **一个点击可能同时被视觉上位于下方的控件处理**；
|
||||
已改为"只沿命中链派发 + 祖先兜底"。回归网里对应的断言从"绝对次数"改为**增量断言**
|
||||
（绝对次数会被前面用例计数污染，本轮踩过一次）。
|
||||
|
||||
**验证**
|
||||
|
||||
```
|
||||
make release TARGET_FILE_NAME=TargetCheck # 零警告
|
||||
powershell -File Tools/uicheck/build.ps1 # 链接 Build/Release/*.o（排除 Main.o）
|
||||
Tools/uicheck/uicheck.exe # 62 passed, 0 failed
|
||||
```
|
||||
|
||||
**未做（有意）**
|
||||
|
||||
- 未改动任何现有组件（Toolbar / TabBar / SignalPanel / PlotView 仍走旧路径），因此**本提交对产品像素零影响**。
|
||||
- 未把 `UiWidget` 接入 `Application`，避免在 P2 之前引入行为差异。
|
||||
|
||||
---
|
||||
|
||||
## 下一步（接手者请从这里开始）
|
||||
|
||||
1. **P2：`PlotViewPaint.cpp` 零行为分片**（9 080 行）
|
||||
- 目标分片：`Paint`（只画）/ `Raster`（缓存与预算）/ `CacheKey`（指纹）/ `Geometry`（面板与命中几何）。
|
||||
- 做法：**机械搬移函数定义**，不改一行逻辑；`PlotViewInternal.hpp` 里的 `pvdetail` 全是 `inline`，跨分片安全。
|
||||
- 判据：`make release` 零警告 + `Target.exe` 体积变化 < 1KB + 场景哈希/像素快照与迁移前一致。
|
||||
- ⚠️ 搬移后务必确认没有残留的 `static` 文件级变量（只在 `PlotViewPaint.cpp` 内可见的辅助函数要一并搬走）。
|
||||
2. **P3：Toolbar 优先**（最小、最容易验证的组件），迁移后跑 `uicheck` + 新旧像素对比。
|
||||
3. 每个阶段单独提交，提交信息写清"改了什么 / 为什么 / 怎么验证"。
|
||||
Reference in new issue
Block a user