197 lines
7.1 KiB
Markdown
197 lines
7.1 KiB
Markdown
# 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 风格样式系统，支持伪类和选择器
|
||
- 弹性布局系统，支持自动尺寸和停靠
|
||
- 事件冒泡机制，灵活的事件处理
|
||
- 控件组合与继承，一切皆控件
|
||
|
||
## 快速开始
|
||
|
||
```cpp
|
||
#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();
|
||
}
|
||
```
|
||
|
||
## 构建命令
|
||
|
||
**批处理脚本 (快速构建)：**
|
||
```bash
|
||
build_x86.bat # 生成 32 位并构建 Debug/Release
|
||
build_x64.bat # 生成 64 位并构建 Debug/Release
|
||
build_all.bat # 同时构建 32 位和 64 位
|
||
```
|
||
|
||
**CMake 完整构建流程：**
|
||
```bash
|
||
# 配置阶段
|
||
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_package` CMake 函数将资源打包为 `.res` 文件
|
||
|
||
**资源打包流程：**
|
||
1. 在 demo 的 CMakeLists.txt 中调用 `add_resource_package(target source_dir output_file)`
|
||
2. 构建时会自动运行 `ResPackage.exe` 工具
|
||
3. 生成的 `.res` 文件可以在运行时通过 `Resource.h` 中的函数加载
|
||
4. 支持本地文件和资源文件的自动加载（通过 `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`：失焦自动关闭，适用于菜单等临时窗口
|
||
|