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

构建命令

build_x86.bat    # 构建 32 位静态库
build_x64.bat    # 构建 64 位静态库

CMake 构建：

cmake -B build          # 默认静态库
cmake --build build

# 动态库
cmake -B build -DBUILD_SHARED_LIBS=ON

# 仅构建库（不构建 demo）
cmake -B build -DBUILD_DEMO=OFF

# 编译为静态库
cmake --build build/vs2022_x86 --target EzUI --config Debug
cmake --build build/vs2022_x86 --target EzUI --config Release
cmake --build build/vs2022_x64 --target EzUI --config Debug
cmake --build build/vs2022_x64 --target EzUI --config Release

核心架构

窗口类型 (继承层次)

Window - 经典带边框窗口
BorderlessWindow - 无边框带阴影窗口
LayeredWindow - 分层透明窗口，支持异形
PopupWindow - 失焦自动关闭的弹出窗口

控件系统

所有控件继承自 Control 基类，核心控件包括：

基础控件：Label, Button, TextBox, PictureBox
选择控件：CheckBox, RadioButton, ComboBox
数据控件：TableView, TreeView, ListView 系列
布局容器：HLayout, VLayout, HListView, VListView, TileListView, TabLayout, PagedListView
功能控件：ScrollBar, Menu, NotifyIcon, ProgressBar, Spacer, IFrame, ShadowBox
表格控件：TableView
动画：Animation - 类似 Qt 的过渡动画系统

布局系统

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

样式与渲染

UIManager - UI 样式与资源管理，支持 XML 布局加载
UISelector - CSS 选择器匹配系统
Direct2DRender - Direct2D 绘图实现
RenderTypes - 颜色、对齐方式等绘图类型
UIDef - 框架内使用的宏定义集合
EzUI.h - 框架主接口头文件，定义事件类、枚举、全局资源等核心结构

事件系统

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

线程模型

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

资源管理

控件树内存由父控件自动管理：Attach/Detach
图片资源通过 PtrManager 自动释放
XML 布局加载后由 UIManager 管理生命周期
add_resource_package 函数支持资源打包为 .res 文件

调试技巧

在 Debug 模式下运行时，按下 F11 可实时查看布局信息，高亮显示控件边界

Demo 项目

helloWorld - 基础示例
QQ - 仿 QQ 登录界面（含资源打包）
kugou - 酷狗音乐播放器（含 VLC 依赖和资源打包）
ResPackage - 资源打包工具
Adminstor / DemoUi - 管理界面示例

开发约定

头文件位于 include/EzUI/ 目录
源文件位于 sources/ 目录
一切皆控件，纯代码组合 UI
使用 CSS 驱动视觉，结构与样式分离
XML 解析使用 tinyxml 库

3.6 KiB Raw Blame History Unescape Escape