# 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 样式系统和弹性布局。

## 构建命令

```bash
# 生成 Visual Studio 项目（推荐）
cmake -S . -B build_x86 -A Win32      # 32位 VS 项目
cmake -S . -B build_x64 -A x64        # 64位 VS 项目

# 或使用现有的批处理脚本
build_x86.bat    # 生成 32 位项目并打开
build_x64.bat    # 生成 64 位项目并打开
```

CMake 构建：
```bash
cmake -B build
cmake --build build
```

静态库/动态库切换：
```bash
cmake -B build -DBUILD_SHARED_LIBS=ON  # 动态库
cmake -B build -DBUILD_SHARED_LIBS=OFF # 静态库（默认）
```

## 核心架构

### 窗口类型 (继承层次)
- `Window` - 经典带边框窗口
- `BorderlessWindow` - 无边框带阴影窗口
- `LayeredWindow` - 分层透明窗口，支持异形
- `PopupWindow` - 失焦自动关闭的弹出窗口

### 控件系统
所有控件继承自 `Control` 基类，核心控件包括：
- 基础控件：`Label`, `Button`, `TextBox`, `PictureBox`
- 选择控件：`CheckBox`, `RadioButton`, `ComboBox`
- 布局容器：`HLayout`, `VLayout`, `HListView`, `VListView`, `TileListView`, `TabLayout`
- 功能控件：`ScrollBar`, `Menu`, `NotifyIcon`, `ProgressBar`, `TreeView`, `Spacer`, `TableView`, `IFrame`

### 布局系统
- **尺寸优先级**：比例尺寸 (`SetRateWidth/Height`) > 绝对尺寸 (`SetFixedSize`) > 控件内容大小
- **自动布局**：`SetAutoWidth/Height` 让控件根据内容自动调整大小
- **停靠布局**：`SetDockStyle` 支持 Fill/Vertical/Horizontal 停靠
- **布局状态**：`TryPendLayout`/`ResumeLayout` 批量添加控件后统一布局

### 样式与渲染
- `UIManager` - UI 样式与资源管理，支持 XML 布局加载
- `UISelector` - CSS 选择器匹配系统
- `Direct2DRender` - Direct2D 绘图实现
- `RenderTypes` - 颜色、对齐方式等绘图类型

### 事件系统
- 支持事件冒泡机制，可实现事件捕获与穿透
- `NotifyFlags` 控制控件哪些事件需要通知窗口
- `Event` 枚举定义所有事件类型，支持位运算组合
- Debug 模式下按 F11 可查看布局信息和控件边界

### 线程模型
- UI 线程：`Application::Run` 启动消息循环
- 跨线程调用：`BeginInvoke`（异步）/ `Invoke`（同步）
- 全局隐藏窗口 `__EzUI_MessageWnd` 用于线程通讯

### 动画系统
- `Animation` 类支持类似 Qt 的过渡动画
- 可用于控件属性（位置、大小、透明度等）的平滑过渡

### 资源管理
- 控件树内存由父控件自动管理：`Attach`/`Detach`
- 图片资源通过 `PtrManager` 自动释放
- XML 布局加载后由 `UIManager` 管理生命周期
- `ResPackage.exe` 工具用于打包资源文件

## Demo 示例

Demo 位于 `demo/` 目录：
- `helloWorld` - 基础 HelloWorld 示例
- `QQ` - 仿 QQ 登录界面
- `kugou` - 仿酷狗音乐播放器（需要 VLC 解码库）

Demo 新版位于 `demoEx/` 目录：
- `Adminstor` - 用户管理 界面示例

## 开发约定

- 头文件位于 `include/EzUI/` 目录
- 源文件位于 `sources/` 目录
- 一切皆控件，纯代码组合 UI
- 使用 CSS 驱动视觉，结构与样式分离
- 中文注释，中文沟通
- 每次编码完毕无需编译，让用户自行编译验证