91 lines
3.6 KiB
Markdown
91 lines
3.6 KiB
Markdown
# 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 示例验证
|