# vqt6 — Viper 的 Qt6 绑定包

`vqt6` 是 [Viper](https://git.gvsds.com/GVSDS/TransPyC) 语言的 **Qt6 GUI 框架绑定**，是 Viper 包管理器分发的"包"（类似于 Python 的 PyQt6、Node.js 的 node-gtk）。

> 注意：`vqt6` **不是** 包管理器，而是一个**被包管理器管理的包**（库）。
> 包管理器负责下载、预编译、安装；`vqt6` 只负责把 Qt6 C++ API 暴露给 Viper 代码。

## 架构

```
+--------------------+        +-----------------------+        +------------+
|  Viper 用户代码     |  FFI   |  vqt6 桥接层 (libvqt6) |  C++    |  Qt6 C++   |
|  (app.py)          | <----> |  - t.State 声明       | <-----> |  QtCore    |
|                    |        |  - C 桥接函数          |        |  QtGui     |
|  vqt6.QApplication |        |    (extern "C")       |        |  QtWidgets |
|  vqt6.QLabel       |        |  - 静态库 / 动态库     |        |  QtNetwork |
+--------------------+        +-----------------------+        +------------+
```

**FFI 路径**：
1. Viper 编译器把 `t.State` 声明的 `def xxx() -> t.State: pass` 解析为外部函数符号
2. 链接时通过 `libvqt6_bridge.a`（静态）或 `vqt6_bridge.dll`（动态）解析符号
3. 运行时 C 桥接层调用 Qt6 C++ API 完成实际工作

## 链接模式

| 模式 | 产物 | 优点 | 缺点 |
|------|------|------|------|
| **静态**（默认） | `libvqt6_bridge.a` | 部署简单（一个 exe），无需分发 dll | exe 体积较大 |
| **动态** | `vqt6_bridge.dll` | 共享内存，多个程序共用 | 需随 exe 分发 dll |

vqt6 同一套 C 桥接源代码，可同时编译为两种产物。Viper 项目通过 `project.vpj` 切换。

## 目录结构

```
includes/vqt6/
├── README.md           # 本文件
├── __init__.py         # 公共 Pythonic API（用户使用）
├── _types.py           # 公共类型（不透明指针 typedef）
├── _qtcore.py          # QtCore 的 t.State FFI 声明
├── _qtwidgets.py       # QtWidgets 的 t.State FFI 声明
├── _qtgui.py           # QtGui 的 t.State FFI 声明
├── _qtnetwork.py       # QtNetwork 的 t.State FFI 声明
├── _bridge.h           # C 桥接层头文件
├── _bridge.cpp         # C 桥接层实现（extern "C" 包装 Qt6 C++ API）
└── CMakeLists.txt      # 构建脚本（生成 libvqt6_bridge.a）
```

## 使用示例

```python
# App/main.py
import t
import c
import vqt6

# 1. 创建 QApplication
app: vqt6.QApplication | t.CPtr = vqt6.QApplication([])

# 2. 创建窗口
window: vqt6.QWidget | t.CPtr = vqt6.QWidget()
window.setWindowTitle("vqt6 Hello")
window.resize(400, 300)

# 3. 创建标签
label: vqt6.QLabel | t.CPtr = vqt6.QLabel("你好，Viper！", window)
label.move(50, 50)

# 4. 显示并进入事件循环
window.show()
app.exec()
```

## 设计原则

1. **不透明指针**：Viper 端不直接操作 Qt6 C++ 类（`QWidget*`、`QString*` 等），所有操作通过 C 桥接函数 `vqt6_xxx()` 转发。
2. **t.State 声明**：所有 FFI 函数返回 `t.State`，C 桥接层函数实现负责实际操作。
3. **句柄化对象模型**：Viper 端的对象是 `t.CPtr`（不透明指针），C 端管理生命周期（构造函数/析构函数）。
4. **跨平台**：同一套 C 桥接代码可在 Windows / Linux / macOS 编译（差异在 Qt6 安装路径）。

## 当前状态

- [x] 架构设计
- [x] FFI 覆盖：QtCore / QtWidgets / QtGui / QtNetwork
- [x] FFI 粒度：仅暴露 C 桥接函数
- [ ] FFI 声明文件编写中
- [ ] C 桥接层实现
- [ ] CMakeLists.txt 构建脚本
- [ ] Hello World 示例验证