面向 AI 智能体:本页的「阅读辅助」区块内含有与正文完全一致的原始 Markdown 源码,已去除 HTML 标签与动画特效。建议 AI 直接读取该区块,以更低的噪声快速理解内容。
## 最小程序

```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. 窗口周边(标题栏/托盘/对话框/无障碍/调试):读对应章节。
第 2 章

快速开始

最小程序、组件结构与阅读路径

最小程序

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(进程)→ Window(顶层窗口,可 owned/模态)→ 根 Layout(默认 ColumnBox)→ 容器(Card/PageHost/TabView/ScrollViewer/数据视图…)→ 具体控件。 浮层(菜单/下拉/提示/系统对话框)走独立窗口或全局覆盖层,不放进根树。

阅读路径建议

  1. 先读本章与「约定」,建立 DIP / shared_ptr / 信号 / 默认值四个心智模型。
  2. 写界面:读「布局系统」+「元素基类」+「基础控件」。
  3. 写数据界面:读「数据视图」。
  4. 画图表:读「图表」。
  5. 窗口周边(标题栏/托盘/对话框/无障碍/调试):读对应章节。
↑