# DreamWall Picker - 窗口管理说明

## ✅ 窗口管理机制

DreamWall Picker 已经实现了完善的单例模式和窗口管理机制，**无需额外修改**。

### 核心机制

```python
# 全局单例实例
_dwpicker = None

def show():
    global _dwpicker
    if not _dwpicker:
        # 第一次调用：创建新实例
        _dwpicker = DwPicker(...)
    
    # 已存在实例：直接显示
    _dwpicker.show(dockable=True)
```

### 特性

1. **单例模式**
   - 使用全局变量 `_dwpicker` 存储唯一实例
   - 多次调用 `show()` 不会创建多个窗口

2. **智能显示**
   - 如果窗口已存在，直接显示
   - 如果窗口被关闭，重新创建

3. **错误恢复**
   - 捕获 `RuntimeError`（workspace control 已存在）
   - 自动清理并重新显示

4. **正确清理**
   - `close()` 函数注销所有回调
   - 清理实例引用

## 📝 使用方法

### 基本用法

```python
# 在 Maya Script Editor 中运行
import animation_tools.dwpicker
animation_tools.dwpicker.show()
```

### 多次调用（安全）

```python
import animation_tools.dwpicker as dwpicker

# 第一次调用 - 创建窗口
dwpicker.show()

# 第二次调用 - 显示已存在的窗口（不会创建新的）
dwpicker.show()

# 第三次调用 - 仍然是同一个窗口
dwpicker.show()
```

### 切换可见性

```python
import animation_tools.dwpicker as dwpicker

# 切换窗口显示/隐藏
dwpicker.toggle()
```

### 关闭窗口

```python
import animation_tools.dwpicker as dwpicker

# 正确关闭窗口（清理所有回调）
dwpicker.close()
```

## 🎯 API 参考

### `show(editable=True, pickers=None, ignore_scene_pickers=False, ...)`

显示 DreamWall Picker 窗口

**参数：**
- `editable` (bool): 是否允许编辑（默认 True）
- `pickers` (list[str]): 要打开的 picker 文件路径列表
- `ignore_scene_pickers` (bool): 是否忽略场景中的 pickers
- `replace_namespace_function` (callable): 自定义命名空间替换函数
- `list_namespaces_function` (callable): 自定义命名空间列表函数

**返回：**
- `DwPicker`: 窗口实例

**示例：**
```python
import animation_tools.dwpicker as dwpicker

# 默认模式
window = dwpicker.show()

# 只读模式
window = dwpicker.show(editable=False)

# 打开特定 picker 文件
window = dwpicker.show(pickers=['/path/to/picker.json'])

# 忽略场景中的 pickers
window = dwpicker.show(ignore_scene_pickers=True)
```

### `toggle()`

切换窗口显示/隐藏

**示例：**
```python
import animation_tools.dwpicker as dwpicker

# 切换可见性
dwpicker.toggle()
```

### `close()`

正确关闭窗口并清理资源

**示例：**
```python
import animation_tools.dwpicker as dwpicker

# 关闭窗口
dwpicker.close()
```

### `current()`

获取当前显示的 picker widget

**返回：**
- Picker widget 或 None

**示例：**
```python
import animation_tools.dwpicker as dwpicker

picker = dwpicker.current()
if picker:
    print("Current picker:", picker)
```

### `open_picker_file(filepath)`

程序化添加 picker 文件

**参数：**
- `filepath` (str): picker 文件路径

**示例：**
```python
import animation_tools.dwpicker as dwpicker

dwpicker.open_picker_file('/path/to/picker.json')
```

### `current_namespace()`

获取当前 picker 的命名空间

**返回：**
- str: 命名空间

**示例：**
```python
import animation_tools.dwpicker as dwpicker

namespace = dwpicker.current_namespace()
print("Current namespace:", namespace)
```

## 🔧 高级功能

### 上下文管理器 - 禁用回调

```python
import animation_tools.dwpicker as dwpicker

# 临时禁用 picker 回调（提高性能）
with dwpicker.disable():
    # 执行大量选择操作
    for obj in objects:
        cmds.select(obj, add=True)
# 回调自动恢复
```

### 图层可见性控制

```python
import animation_tools.dwpicker as dwpicker

# 设置图层可见性
dwpicker.set_layer_visible('layer_name', visible=True)

# 切换图层可见性
dwpicker.toggle_layer_visibility('layer_name')
```

### 获取形状

```python
import animation_tools.dwpicker as dwpicker

# 通过 ID 获取形状
shape = dwpicker.get_shape('shape_id')
```

## ✅ 与 MGPicker 的对比

| 特性 | DreamWall Picker | MGPicker |
|------|-----------------|----------|
| 单例模式 | ✅ 内置 | ✅ 已添加 |
| 窗口检测 | ✅ 自动 | ✅ 已添加 |
| 错误恢复 | ✅ 自动 | ⚠️ 手动 |
| 回调管理 | ✅ 完善 | N/A |
| 上下文管理器 | ✅ 支持 | N/A |

## 🎯 最佳实践

### 1. 标准启动

```python
import animation_tools.dwpicker as dwpicker
dwpicker.show()
```

### 2. 工具架按钮

```python
# 简单切换
import animation_tools.dwpicker as dwpicker
dwpicker.toggle()
```

### 3. 批量操作时禁用回调

```python
import animation_tools.dwpicker as dwpicker

with dwpicker.disable():
    # 批量操作
    for obj in objects:
        cmds.select(obj, add=True)
```

### 4. 程序化加载 pickers

```python
import animation_tools.dwpicker as dwpicker

# 打开窗口
dwpicker.show()

# 加载 picker 文件
dwpicker.open_picker_file('/path/to/picker.json')
```

## ✨ 总结

DreamWall Picker 的窗口管理机制已经非常完善：

- ✅ **单例模式** - 防止重复创建窗口
- ✅ **智能显示** - 自动处理已存在的窗口
- ✅ **错误恢复** - 自动处理 workspace control 冲突
- ✅ **正确清理** - 完善的资源管理
- ✅ **丰富 API** - 提供多种控制方法

**无需任何修改，可以直接使用！**

```python
import animation_tools.dwpicker
animation_tools.dwpicker.show()
```

多次调用不会出现任何问题或警告！