EG/demo/GUI预览窗口使用说明.md

# 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集成中的显示问题。