# 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`：失焦自动关闭，适用于菜单等临时窗口