169 lines
5.0 KiB
Markdown
169 lines
5.0 KiB
Markdown
# GUI预览窗口使用说明
|
||
|
||
## 概述
|
||
|
||
GUI预览窗口是一个独立的Panda3D窗口，专门用于正确显示2D GUI元素，解决Qt集成中DirectGUI显示的问题。
|
||
|
||
## 主要特性
|
||
|
||
### ✅ 解决的问题
|
||
- **2D GUI显示问题**: 在Qt集成的主窗口中，DirectGUI元素可能无法正确显示
|
||
- **独立渲染环境**: 提供纯Panda3D环境，确保GUI元素正确渲染
|
||
- **实时同步**: 自动与主程序中的GUI元素保持同步
|
||
|
||
### 🚀 核心功能
|
||
- **独立窗口**: 完全独立的Panda3D窗口，不受Qt影响
|
||
- **自动同步**: 每0.5秒自动检测主程序GUI元素变化
|
||
- **支持所有GUI类型**: 按钮、标签、输入框、滑块、3D文本、虚拟屏幕
|
||
- **交互预览**: 在预览窗口中可以真实地与GUI元素交互
|
||
|
||
## 使用方式
|
||
|
||
### 1. 在主程序中使用
|
||
|
||
```python
|
||
from gui_preview_window import GUIPreviewWindow
|
||
|
||
# 创建预览窗口
|
||
preview = GUIPreviewWindow()
|
||
|
||
# 连接到主程序world对象
|
||
preview.set_main_world(your_world_object)
|
||
|
||
# 预览窗口会自动同步显示GUI元素
|
||
```
|
||
|
||
### 2. 通过GUI编辑模式
|
||
|
||
1. 在主程序中点击菜单："GUI" → "进入GUI编辑模式"
|
||
2. 预览窗口会自动弹出
|
||
3. 使用主程序的工具栏创建GUI元素
|
||
4. 在预览窗口中实时查看效果
|
||
|
||
### 3. 工具栏快速创建
|
||
|
||
主程序提供了便捷的工具栏按钮：
|
||
- **创建按钮**: 在场景中创建可点击按钮
|
||
- **创建标签**: 创建文本标签
|
||
- **3D文本**: 创建3D空间文本
|
||
|
||
## 支持的GUI元素类型
|
||
|
||
### 2D GUI元素 (DirectGUI)
|
||
| 类型 | 说明 | 在预览窗口中的表现 |
|
||
|------|------|-------------------|
|
||
| 按钮 | DirectButton | 完全可交互，支持点击 |
|
||
| 标签 | DirectLabel | 正确显示文本内容 |
|
||
| 输入框 | DirectEntry | 支持文本输入和提交 |
|
||
| 滑块 | DirectSlider | 支持值调整交互 |
|
||
|
||
### 3D GUI元素
|
||
| 类型 | 说明 | 在预览窗口中的表现 |
|
||
|------|------|-------------------|
|
||
| 3D文本 | TextNode | 3D空间中的文本，支持广告牌效果 |
|
||
| 虚拟屏幕 | CardMaker + TextNode | 带背景的虚拟显示屏 |
|
||
|
||
## 技术实现
|
||
|
||
### 自动同步机制
|
||
```python
|
||
def sync_with_main(self, task):
|
||
"""每0.5秒检测GUI元素变化"""
|
||
if self.main_world and hasattr(self.main_world, 'gui_elements'):
|
||
main_count = len(self.main_world.gui_elements)
|
||
preview_count = len(self.gui_elements)
|
||
|
||
if main_count != preview_count:
|
||
self.refresh_all_gui() # 自动刷新
|
||
|
||
return task.again
|
||
```
|
||
|
||
### 窗口配置
|
||
```python
|
||
loadPrcFileData("", """
|
||
win-size 800 600
|
||
window-title GUI预览窗口 - 2D GUI专用显示
|
||
framebuffer-multisample 1
|
||
multisamples 2
|
||
audio-library-name null
|
||
notify-level-audio error
|
||
""")
|
||
```
|
||
|
||
## 操作说明
|
||
|
||
### 鼠标控制
|
||
- **滚轮**: 缩放视图
|
||
- **右键拖拽**: 旋转视角 (未来版本)
|
||
|
||
### 状态显示
|
||
预览窗口底部会显示当前状态：
|
||
- "等待GUI元素..." - 尚未同步到任何GUI
|
||
- "已同步 N 个GUI元素" - 正在显示N个GUI元素
|
||
|
||
## 优势对比
|
||
|
||
### 与嵌入式方案对比
|
||
| 特性 | 独立预览窗口 | Qt嵌入式 |
|
||
|------|-------------|-----------|
|
||
| 2D GUI显示 | ✅ 完美支持 | ❌ 显示问题 |
|
||
| 性能 | ✅ 原生性能 | ⚠️ 集成开销 |
|
||
| 交互性 | ✅ 完全交互 | ⚠️ 部分限制 |
|
||
| 开发复杂度 | ✅ 简单 | ❌ 复杂 |
|
||
|
||
### 与独立编辑器对比
|
||
| 特性 | 预览窗口 | 独立编辑器 |
|
||
|------|----------|------------|
|
||
| 操作流程 | ✅ 简化 | ❌ 复杂 |
|
||
| 学习成本 | ✅ 低 | ❌ 高 |
|
||
| 实时性 | ✅ 自动同步 | ⚠️ 手动刷新 |
|
||
| 代码维护 | ✅ 简单 | ❌ 复杂 |
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
**Q: 预览窗口没有显示GUI元素**
|
||
A: 检查是否正确连接到主程序world对象，确保调用了`set_main_world()`
|
||
|
||
**Q: GUI元素显示位置不正确**
|
||
A: 2D GUI使用屏幕坐标系，3D GUI使用世界坐标系，检查创建时的坐标参数
|
||
|
||
**Q: 预览窗口无法交互**
|
||
A: 确保预览窗口有焦点，尝试点击窗口使其获得焦点
|
||
|
||
### 调试信息
|
||
预览窗口会在控制台输出详细的调试信息：
|
||
```
|
||
✓ GUI预览窗口已创建 - 专用于显示2D GUI元素
|
||
预览窗口已连接到主程序
|
||
检测到GUI元素变化: 主程序1个, 预览0个
|
||
预览窗口创建元素: button - 测试按钮
|
||
```
|
||
|
||
## 未来扩展
|
||
|
||
### 计划功能
|
||
- [ ] 预览窗口中直接编辑GUI属性
|
||
- [ ] 鼠标右键拖拽旋转视角
|
||
- [ ] GUI元素高亮和选择
|
||
- [ ] 布局网格显示
|
||
- [ ] 多视角预览（正交、透视）
|
||
|
||
### API扩展
|
||
```python
|
||
# 未来可能的API
|
||
preview.set_view_mode("orthographic") # 设置正交视图
|
||
preview.enable_grid(True) # 显示网格
|
||
preview.highlight_element(gui_element) # 高亮元素
|
||
```
|
||
|
||
## 总结
|
||
|
||
GUI预览窗口提供了一个简洁高效的解决方案，让开发者能够：
|
||
1. **在主程序中直接编辑** - 不需要额外的编辑器窗口
|
||
2. **在独立窗口中预览** - 确保GUI元素正确显示
|
||
3. **实时同步更新** - 无需手动刷新，自动保持同步
|
||
|
||
这种设计大大简化了GUI开发流程，同时解决了Qt集成中的显示问题。 |