## 最小程序
```cpp
#include "ZufyUI.h"
#include "ZufyUIWidgets.h"
using namespace ZufyUI;
int APIENTRY wWinMain(HINSTANCE, HINSTANCE, LPWSTR, int) { // Windows 子系统(/SUBSYSTEM:WINDOWS)
Application app = Application::Instance();
auto win = app.CreateWindow(900, 600, L"Hello ZufyUI");
auto root = win->GetRootColumnBox(); // 默认根是 ColumnBox,margin(20),spacing 10
auto btn = std::make_shared<Button>(L"点我");
btn->Connect(btn->Clicked, [] { /* ... */ });
root->AddChild(btn);
win->Show(); // Create 不会自动 Show(v1.8.0 起)
return app.Run();
}
```
###block_red_start
**易错**
- GUI 程序用 `wWinMain` + `/SUBSYSTEM:WINDOWS`。若坚持用 `int main()`,请把子系统设为控制台 `/SUBSYSTEM:CONSOLE`,或加 `#pragma comment(linker, "/SUBSYSTEM:WINDOWS /ENTRY:mainCRTStartup")`,否则链接会找不到入口。
###block_red_end
## 事件循环与线程模型
- `Application::Run()` 跑唯一消息循环;**所有窗口/控件必须在同一 UI 线程创建与操作**。
- 后台线程改 UI:用信号的 `ConnectionThread::UIThread`,或 `detail::PostToUIThread`。
## 组件结构(从外到内)
`Application`(进程)→ `Window`(顶层窗口,可 owned/模态)→ 根 `Layout`(默认 `ColumnBox`)→ 容器(`Card`/`PageHost`/`TabView`/`ScrollViewer`/数据视图…)→ 具体控件。
浮层(菜单/下拉/提示/系统对话框)走独立窗口或全局覆盖层,不放进根树。
## 阅读路径建议
1. 先读本章与「约定」,建立 DIP / shared_ptr / 信号 / 默认值四个心智模型。
2. 写界面:读「布局系统」+「元素基类」+「基础控件」。
3. 写数据界面:读「数据视图」。
4. 画图表:读「图表」。
5. 窗口周边(标题栏/托盘/对话框/无障碍/调试):读对应章节。快速开始
最小程序、组件结构与阅读路径
最小程序
cpp
#include "ZufyUI.h"
#include "ZufyUIWidgets.h"
using namespace ZufyUI;
int APIENTRY wWinMain(HINSTANCE, HINSTANCE, LPWSTR, int) { // Windows 子系统(/SUBSYSTEM:WINDOWS)
Application app = Application::Instance();
auto win = app.CreateWindow(900, 600, L"Hello ZufyUI");
auto root = win->GetRootColumnBox(); // 默认根是 ColumnBox,margin(20),spacing 10
auto btn = std::make_shared<Button>(L"点我");
btn->Connect(btn->Clicked, [] { /* ... */ });
root->AddChild(btn);
win->Show(); // Create 不会自动 Show(v1.8.0 起)
return app.Run();
}
易错
- GUI 程序用
wWinMain+/SUBSYSTEM:WINDOWS。若坚持用int main(),请把子系统设为控制台/SUBSYSTEM:CONSOLE,或加#pragma comment(linker, "/SUBSYSTEM:WINDOWS /ENTRY:mainCRTStartup"),否则链接会找不到入口。
事件循环与线程模型
Application::Run()跑唯一消息循环;所有窗口/控件必须在同一 UI 线程创建与操作。- 后台线程改 UI:用信号的
ConnectionThread::UIThread,或detail::PostToUIThread。
组件结构(从外到内)
Application(进程)→ Window(顶层窗口,可 owned/模态)→ 根 Layout(默认 ColumnBox)→ 容器(Card/PageHost/TabView/ScrollViewer/数据视图…)→ 具体控件。
浮层(菜单/下拉/提示/系统对话框)走独立窗口或全局覆盖层,不放进根树。
阅读路径建议
- 先读本章与「约定」,建立 DIP / shared_ptr / 信号 / 默认值四个心智模型。
- 写界面:读「布局系统」+「元素基类」+「基础控件」。
- 写数据界面:读「数据视图」。
- 画图表:读「图表」。
- 窗口周边(标题栏/托盘/对话框/无障碍/调试):读对应章节。