7.1 KiB
7.1 KiB
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
项目概述
EzUI 是一个基于原生 Win32 消息机制和 Direct2D 的 C++ 桌面 UI 框架，提供类似 Web 前端的 CSS 样式系统和弹性布局。
核心特性：
- 基于 Win32 消息机制，轻量无依赖
- Direct2D 硬件加速渲染，支持高 DPI
- CSS 风格样式系统，支持伪类和选择器
- 弹性布局系统，支持自动尺寸和停靠
- 事件冒泡机制，灵活的事件处理
- 控件组合与继承，一切皆控件
快速开始
#include "EzUI/UIManager.h"
#include "EzUI/Window.h"
#include "EzUI/Application.h"
using namespace ezui;
class TestForm : public Window {
private:
UIManager umg;
public:
TestForm() : Window(800, 600) {
umg.LoadXmlData("<vbox><label text=\"hello world\"></label></vbox>");
umg.SetupUI(this);
}
};
int APIENTRY wWinMain(HINSTANCE hInstance, HINSTANCE, LPWSTR, int nCmdShow) {
Application app;
TestForm form;
form.SetText(L"窗口标题");
form.Show(nCmdShow);
return app.Exec();
}
构建命令
批处理脚本 (快速构建)：
build_x86.bat # 生成 32 位并构建 Debug/Release
build_x64.bat # 生成 64 位并构建 Debug/Release
build_all.bat # 同时构建 32 位和 64 位
CMake 完整构建流程：
# 配置阶段
cmake -S . -B build -A Win32 # 32 位配置
cmake -S . -B build -A x64 # 64 位配置
cmake -S . -B build -DBUILD_SHARED_LIBS=ON # 构建动态库
cmake -S . -B build -DBUILD_DEMO=OFF # 不构建 demo 项目
# 编译阶段
cmake --build build --config Debug # Debug 版本
cmake --build build --config Release # Release 版本
# 单独构建 EzUI 库
cmake --build build --target EzUI --config Debug
cmake --build build --target EzUI --config Release
核心架构
窗口类型 (继承层次)
Window- 经典带边框窗口BorderlessWindow- 无边框带阴影窗口LayeredWindow- 分层透明窗口，支持异形PopupWindow- 失焦自动关闭的弹出窗口
控件系统
所有控件继承自 Control 基类，核心控件包括：
基础控件：
Label- 文本标签Button- 标准按钮TextBox- 文本输入框（支持多行）PictureBox- 图片显示（支持 GIF 动画）
选择控件：
CheckBox- 复选框RadioButton- 单选按钮ComboBox- 下拉选择框
数据控件：
TableView- 表格视图TreeView- 树形视图ListView系列：HListView（横向列表）、VListView（纵向列表）、TileListView（瓦片式）、PagedListView（分页列表）
布局容器：
HLayout/HBox- 水平布局容器VLayout/VBox- 垂直布局容器TabLayout- 选项卡切换容器Spacer- 弹性/固定间距占位符
功能控件：
ScrollBar/HScrollBar/VScrollBar- 滚动条Menu- 菜单系统NotifyIcon- 系统托盘图标ProgressBar- 进度条IFrame- 内嵌框架（类似 HTML iframe）ShadowBox- 阴影容器
动画系统：
Animation- 类似 Qt 的属性过渡动画
布局系统
- 尺寸优先级：比例尺寸 (
SetRateWidth/Height) > 绝对尺寸 (SetFixedSize) > 控件内容大小 - 自动布局：
SetAutoWidth/Height让控件根据内容自动调整大小 - 停靠布局：
SetDockStyle支持 Fill/Vertical/Horizontal 停靠 - 布局状态：
TryPendLayout/ResumeLayout批量添加控件后统一布局
样式与渲染
UIManager- UI 样式与资源管理，支持 XML 布局加载UISelector- CSS 选择器匹配系统（支持类选择器、ID 选择器、组合选择器）Direct2DRender- Direct2D 绘图实现，支持硬件加速RenderTypes- 颜色、对齐方式等绘图类型定义UIDef- 框架内使用的宏定义集合EzUI.h- 框架主接口头文件，定义事件类、枚举、全局资源等核心结构
CSS 样式特性：
- 伪类支持：
:hover、:active、:checked、:disabled - 样式属性：width、height、background-color、border、color、font 等
- 选择器类型：标签选择器、类选择器、ID 选择器、组合选择器
事件系统
- 支持事件冒泡机制，可实现事件捕获与穿透
NotifyFlags控制控件哪些事件需要通知窗口Event枚举定义所有事件类型（鼠标、键盘、绘制等），支持位运算组合- 事件穿透控制：通过
m_hitTestEnabled控制命中测试 - Debug 模式下按 F11 可查看布局信息和控件边界
线程模型
- UI 线程：
Application::Run启动消息循环 - 跨线程调用：
BeginInvoke（异步）/Invoke（同步） - 全局隐藏窗口
__EzUI_MessageWnd用于线程通讯
资源管理
- 控件树内存由父控件自动管理：
Attach/Detach - 图片资源通过
PtrManager自动释放 - XML 布局加载后由
UIManager管理生命周期 - 资源打包系统：通过
add_resource_packageCMake 函数将资源打包为.res文件
资源打包流程：
- 在 demo 的 CMakeLists.txt 中调用
add_resource_package(target source_dir output_file) - 构建时会自动运行
ResPackage.exe工具 - 生成的
.res文件可以在运行时通过Resource.h中的函数加载 - 支持本地文件和资源文件的自动加载（通过
add_resource_package函数）
调试技巧
- 在 Debug 模式下运行时，按下
F11可实时查看布局信息，高亮显示控件边界
Demo 项目
helloWorld- 基础示例，演示最简单的窗口创建ResPackage- 资源打包工具，用于将资源文件打包为.res格式QQ- 仿 QQ 登录界面，展示资源打包和 XML 布局加载kugou- 酷狗音乐播放器，演示 VLC 集成和复杂 UI 交互（需要额外依赖）TableViewDemo- 表格控件演示，展示 LayeredWindow + VLayout + TableView + 右键菜单的组合使用
CMake Demo 目标：
- 所有 demo 都使用
add_executable(... WIN32 ...)创建 - 通过
add_resource_package(target source_dir output_file)自动打包资源 - 资源文件通过
source_group组织到 VS 的 "res" 筛选项下
开发约定
目录结构：
- 头文件：
include/EzUI/目录 - 源文件：
sources/目录 - Demo 项目：
demo/目录
核心理念：
- 一切皆控件，纯代码组合 UI
- 使用 CSS 驱动视觉，结构与样式分离
- XML 布局通过
UIManager::LoadXmlFile()或LoadXmlData()加载
CMake 自定义命令：
add_resource_package(target source_dir output_file)- 打包资源文件为.res格式target需要与add_executable的项目名匹配- 资源会在构建时自动打包，程序通过
Resource.h提供的函数访问 - 需要先构建
ResPackage工具（位于demo/ResPackage）
窗口绘制机制：
Window/BorderlessWindow：Windows 自动发送WM_PAINT消息LayeredWindow：需手动发送WM_PAINT消息进行绘制（支持实时重绘）PopupWindow：失焦自动关闭，适用于菜单等临时窗口