4.8 KiB
4.8 KiB
新增功能模块 / 模块重构
适用场景:新增模块、重大模块重构、核心架构能力演进。 不适用场景:小接口或轻量功能变更,请使用“功能变更”模板。
基本信息
- 模块 ID:Module-20260409-0001
- 模块名称:Window 托管重绘与覆盖合成机制
- 状态:已完成 / 待持续回归
- 类型:架构演进
- 所属系统 / 子系统:Window / Control / Dialog 重绘链
- 版本 / 分支:
master - 环境:Windows + EasyX + VS2022
- 负责人:Codex 协作修改
背景与目标
- 背景:
- 初始框架以控件局部即时重绘为主,非模态对话框与底层控件重叠时,容易出现底层先画、对话框后补的层级问题。
- 当前痛点:
- 对话框遮挡下的 hover / click / tooltip / 分页等交互容易闪烁
- 底层控件和上层对话框在事件里分离绘制,顺序不可控
- 目标:
- 将“事件改状态”和“绘制提交”拆开,由
Window在事件尾统一提交重绘。
- 将“事件改状态”和“绘制提交”拆开,由
- 非目标:[可选]
- 暂不做真正像素级脏区裁剪
- 暂不统一布局系统
模块边界
- 职责:
- 在
Window主循环里托管控件重绘请求 - 选择安全的重绘 root
- 在提交阶段维护普通控件与非模态
Dialog的正确层级
- 在
- 不负责什么:
- 模态
Dialog自己的内部事件循环 - 布局语义统一
- 字符集问题
- 模态
- 外部依赖:
- EasyX 绘制接口
- 各控件自身的快照恢复能力
- 对外能力 / API:
Window::requestManagedRepaint(Control* source)Window::flushManagedRepaint()Control::getManagedRepaintRoot()Control::commitManagedRepaint()
- 关键数据 / 状态:
managedDispatchActivemanagedSceneDirtymanagedRepaintItems
设计说明
- 核心流程:
Window::runEventLoop()开始输入分发前,进入managedDispatchActive = true- 控件在
handleEvent()中只改状态并通过requestRepaint()上报 Window::requestManagedRepaint(source)把 source 转换成root + coverage- 事件收口时
flushManagedRepaint()按层级提交 root - 最后补画和脏区相交的非模态
Dialog
- 关键对象 / 类关系:
Window:重绘调度中心Control:提供宿主窗口回溯与 root 选择语义Canvas / TabControl / Dialog:作为安全重绘 root 的主要容器
- 生命周期:
- 托管重绘项只存在于当前分发轮次
clearManagedRepaintState()在 flush、resize 收口、对话框开关后的整场景重绘后清空
- 事件 / 渲染 / 数据流:
- 事件:Dialog 优先,普通控件其次
- 渲染:受影响普通 root 先画,Dialog 后补
- 数据流:leaf control -> requestRepaint -> Window registry -> flush
- 关键不变量:
- 分发期不直接提交托管重绘
- 顶层普通控件的提交顺序必须服从
Window::controls的 z-order - 对话框始终绘制在普通控件之上
- 降级 / 回退策略:[可选]
resize、对话框打开/关闭等全局变化仍走整场景重绘
实现与影响
- 关键实现点:
Control增加hostWindow、getManagedRepaintRoot()、commitManagedRepaint()Window增加ManagedRepaintItem队列Canvas / TabControl / Dialog提供局部可提交与升级为整 root 重画的判断
- 涉及文件 / 类 / 函数:
Window.h / Window.cppControl.h / Control.cppCanvas.h / Canvas.cppTabControl.h / TabControl.cppDialog.h / Dialog.cpp
- 兼容性影响:
- 行为层面更严格,底层控件不再依赖旧的“即时局部重绘”副作用
- 性能影响:
- 相比整场景重绘更细
- 相比纯即时局部重绘更稳定
- 在全局变化场景仍保留整场景兜底
- 风险点:
- root 选择错误会导致局部重绘不完整
- 嵌套容器组合场景需持续回归
测试与验证
- 测试范围:
- 非模态遮挡下的按钮 hover / click
Canvas / TabControl / Table组合场景- 模态与非模态对话框 coexist 场景
- 验证步骤:
- 编译
Control / Canvas / TabControl / Dialog / Window相关源文件。 - 回归
KEY == 2 / 3 / 4的对话框与遮挡场景。 - 检查对话框关闭、resize、hover 清理和局部重绘顺序。
- 验证结果:
- 第二阶段架构已落地,核心编译通过,主问题链路已被压住。
- 已知限制 / 遗留问题:[可选]
- 快速划过多个按钮时偶发一帧双高亮,当前接受为底层限制
- 仍未推进到真正像素级脏区裁剪
落地信息
- 关联功能变更 ID:[可选]
Feature-20260409-0002Feature-20260409-0003
- 关联 BUG / Fix:[可选]
BUG-20260409-0001Fix-BUG-20260409-0001
- Commit:
b07a4ec77a8fe5- 当前工作区未提交阶段
- PR:[可选]
- 发布版本:[可选]
- 相关文档:[可选]
00-修改总览-20260409.md