Update

2023/scripts/animation_tools/mgpicker/USAGE.md

@@ -0,0 +1,261 @@
+# MG-Picker Studio - 使用说明
+
+## ✅ 功能特性
+
+### 窗口管理
+- ✅ **自动检测已打开窗口** - 避免重复打开
+- ✅ **智能显示现有窗口** - 如果窗口已打开，自动显示而不是创建新的
+- ✅ **版本兼容性检测** - 自动选择匹配的插件版本
+
+### 版本支持
+- ✅ **Maya 2017-2026+** - 所有版本
+- ✅ **Python 2.7 & 3.x** - 完全兼容
+- ✅ **自动插件选择** - 根据 Maya 版本自动加载对应插件
+
+## 📝 使用方法
+
+### 基本用法
+
+```python
+# 在 Maya Script Editor 中运行
+import animation_tools.mgpicker
+animation_tools.mgpicker.start()
+```
+
+### 指定模式
+
+```python
+import animation_tools.mgpicker as mgpicker
+
+# Animator 模式（默认）
+mgpicker.start(mode=1)
+
+# Designer 模式
+mgpicker.start(mode=0)
+```
+
+### 强制创建新窗口
+
+```python
+import animation_tools.mgpicker as mgpicker
+
+# 强制创建新窗口（不推荐，可能导致版本冲突警告）
+mgpicker.start(force_new=True)
+```
+
+## 🔧 窗口管理
+
+### 自动检测
+
+当你第二次调用 `start()` 时，脚本会：
+
+1. **检测窗口是否已打开**
+   - 检查常见的 MGPicker 窗口名称
+   
+2. **显示现有窗口**
+   - 如果窗口已存在，自动显示并置于前台
+   - 避免创建重复窗口
+   
+3. **避免版本冲突**
+   - 防止出现 "Different versions" 警告
+   - 保持单一窗口实例
+
+### 示例
+
+```python
+import animation_tools.mgpicker as mgpicker
+
+# 第一次调用 - 创建新窗口
+mgpicker.start()
+# 输出: MG-Picker Studio started in animator mode
+
+# 第二次调用 - 显示现有窗口
+mgpicker.start()
+# 输出: MGPicker window already open, bringing to front
+```
+
+## ⚠️ 解决的问题
+
+### 问题：重复打开窗口导致警告
+
+**之前的行为：**
+```
+// Warning: Different versions for the MGPicker scripts detected,
+// to pick up the version other than currently being used,
+// please close existing MGPicker window, restart Maya and try again.
+```
+
+**现在的行为：**
+```
+MGPicker window already open, bringing to front
+```
+
+### 问题：版本兼容性
+
+**自动选择插件：**
+- Maya 2023 → MGPicker_2023x64.mll
+- Maya 2024 → MGPicker_2024x64.mll
+- Maya 2025 → MGPicker_2025x64.mll
+
+如果没有完全匹配的版本，会自动选择最接近的兼容版本。
+
+## 📋 API 参考
+
+### `start(mode=1, force_new=False)`
+
+启动 MG-Picker Studio
+
+**参数：**
+- `mode` (int): 启动模式
+  - `0` - Designer 模式（设计器模式）
+  - `1` - Animator 模式（动画师模式，默认）
+- `force_new` (bool): 是否强制创建新窗口
+  - `False` - 如果窗口已存在则显示现有窗口（默认，推荐）
+  - `True` - 强制创建新窗口（不推荐）
+
+**返回：**
+- 无返回值
+
+**示例：**
+```python
+import animation_tools.mgpicker as mgpicker
+
+# 默认：Animator 模式，自动检测窗口
+mgpicker.start()
+
+# Designer 模式
+mgpicker.start(mode=0)
+
+# 强制新窗口（不推荐）
+mgpicker.start(force_new=True)
+```
+
+### `load_plugin()`
+
+加载 MGPicker 插件
+
+**返回：**
+- `bool` - 成功返回 True，失败返回 False
+
+**示例：**
+```python
+import animation_tools.mgpicker as mgpicker
+
+if mgpicker.load_plugin():
+    print("Plugin loaded successfully")
+else:
+    print("Failed to load plugin")
+```
+
+### `is_window_open()`
+
+检查 MGPicker 窗口是否已打开
+
+**返回：**
+- `bool` - 窗口已打开返回 True
+
+**示例：**
+```python
+import animation_tools.mgpicker as mgpicker
+
+if mgpicker.is_window_open():
+    print("MGPicker window is already open")
+else:
+    print("MGPicker window is not open")
+```
+
+### `show_existing_window()`
+
+显示已存在的 MGPicker 窗口
+
+**返回：**
+- `bool` - 成功显示返回 True
+
+**示例：**
+```python
+import animation_tools.mgpicker as mgpicker
+
+if mgpicker.show_existing_window():
+    print("Existing window shown")
+else:
+    print("No existing window found")
+```
+
+## 🎯 最佳实践
+
+### 1. 使用默认行为
+
+```python
+# 推荐：让脚本自动处理窗口管理
+import animation_tools.mgpicker as mgpicker
+mgpicker.start()
+```
+
+### 2. 检查窗口状态
+
+```python
+import animation_tools.mgpicker as mgpicker
+
+if not mgpicker.is_window_open():
+    mgpicker.start()
+else:
+    print("MGPicker is already running")
+```
+
+### 3. 在工具架中使用
+
+```python
+# 工具架按钮代码
+import animation_tools.mgpicker as mgpicker
+mgpicker.start()  # 简单且安全
+```
+
+## 🐛 故障排除
+
+### 问题：插件加载失败
+
+**检查：**
+1. 插件文件是否存在
+2. Maya 版本是否支持
+3. 插件路径是否正确
+
+**解决：**
+```python
+import animation_tools.mgpicker as mgpicker
+
+# 手动加载插件
+if not mgpicker.load_plugin():
+    print("Plugin load failed, check console for details")
+```
+
+### 问题：窗口无法显示
+
+**解决：**
+```python
+import animation_tools.mgpicker as mgpicker
+
+# 强制创建新窗口
+mgpicker.start(force_new=True)
+```
+
+## 📞 支持
+
+- **官方网站**: https://www.mgland.com/
+- **作者**: Miguel (MG)
+
+## ✨ 总结
+
+MG-Picker Studio 现在具有智能窗口管理功能：
+
+- ✅ 自动检测已打开的窗口
+- ✅ 避免重复创建窗口
+- ✅ 防止版本冲突警告
+- ✅ 兼容所有 Maya 版本
+- ✅ 简单易用的 API
+
+只需一行代码即可启动：
+
+```python
+import animation_tools.mgpicker
+animation_tools.mgpicker.start()
+```