Nexus/2023/scripts/animation_tools/dwpicker/WINDOW_MANAGEMENT.md

DreamWall Picker - 窗口管理说明

✅ 窗口管理机制

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

核心机制

# 全局单例实例
_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() 函数注销所有回调
   • 清理实例引用

📝 使用方法

基本用法

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

多次调用（安全）

import animation_tools.dwpicker as dwpicker

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

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

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

切换可见性

import animation_tools.dwpicker as dwpicker

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

关闭窗口

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: 窗口实例

示例：

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()

切换窗口显示/隐藏

示例：

import animation_tools.dwpicker as dwpicker

# 切换可见性
dwpicker.toggle()

close()

正确关闭窗口并清理资源

示例：

import animation_tools.dwpicker as dwpicker

# 关闭窗口
dwpicker.close()

current()

获取当前显示的 picker widget

返回：

• Picker widget 或 None

示例：

import animation_tools.dwpicker as dwpicker

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

open_picker_file(filepath)

程序化添加 picker 文件

参数：

• filepath (str): picker 文件路径

示例：

import animation_tools.dwpicker as dwpicker

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

current_namespace()

获取当前 picker 的命名空间

返回：

• str: 命名空间

示例：

import animation_tools.dwpicker as dwpicker

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

🔧 高级功能

上下文管理器 - 禁用回调

import animation_tools.dwpicker as dwpicker

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

图层可见性控制

import animation_tools.dwpicker as dwpicker

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

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

获取形状

import animation_tools.dwpicker as dwpicker

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

✅ 与 MGPicker 的对比

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

🎯 最佳实践

1. 标准启动

import animation_tools.dwpicker as dwpicker
dwpicker.show()

2. 工具架按钮

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

3. 批量操作时禁用回调

import animation_tools.dwpicker as dwpicker

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

4. 程序化加载 pickers

import animation_tools.dwpicker as dwpicker

# 打开窗口
dwpicker.show()

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

✨ 总结

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

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

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

import animation_tools.dwpicker
animation_tools.dwpicker.show()

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