sliderpy 0.0.0

No project description provided

SliderPy

SliderPy 是一个开箱即用、自动布局、支持持久化、跨平台兼容的 tkinter 滑动条管理器，让你用几行代码就能构建专业级的参数调节界面。

🌟 核心功能亮点

1. 一键创建滑动条

• 通过 add_slider(name, from_, to, initial, command, resolution) 快速添加带标签的滑块
• 支持整数、浮点数（通过 resolution 控制精度）
• 滑块名称自动显示在标签上，实时更新当前值

2. 自动窗口布局管理

• ✅ 自动调整窗口高度：每添加一个滑块，窗口自动伸缩以完美包裹内容
• ✅ 固定宽度 + 禁止手动拉伸：保持界面整洁统一
• ✅ 启动时自动居中：在屏幕中央打开，提升用户体验

3. 灵活的事件回调

• 每个滑块可绑定独立回调函数，响应值变化
• 回调函数接收字符串值（符合 tkinter 规范），可自由处理

4. 重置与恢复

• 🔁 重置为默认初始值：reset_all_sliders()
• 🔙 重置为最近保存的配置：reset_to_saved()

5. 配置持久化（JSON）

• 💾 保存当前参数到 JSON 文件
  • 默认保存到用户目录：~/.slider_app/config.json（跨平台）
  • 也支持手动选择保存路径
• 📂 从 JSON 加载配置
  • 自动裁剪非法值到合法范围
  • 提示缺失/多余参数
  • 可选：将加载的配置设为下次启动默认值

6. 启动自动恢复

• ✅ 程序启动时自动加载上次保存的配置
  • 无需用户操作，参数状态无缝延续
  • 配置文件不存在则静默跳过，无报错

7. 安全与健壮性

• 🛡️ 防止重复滑块名称：添加时检查唯一性
• 🛡️ 值范围保护：加载或设置时自动 clamp 到 [from_, to]
• 🛡️ 异常处理：文件读写错误弹窗提示，不崩溃
• 🛡️ 中文支持：JSON 使用 ensure_ascii=False，支持中文参数名

8. 开发者友好

• 📊 get_values()：一键获取所有参数字典，便于调试或集成
• 🧱 面向对象封装：所有状态和方法集中管理，易于扩展
• 🧩 模块化设计：可轻松嵌入到更大项目中作为参数面板

9. 用户交互体验

• 🖱️ 图形化文件选择对话框（保存/加载）
• 💬 操作成功/失败均有弹窗反馈
• 🎨 界面简洁清晰，标签+滑块垂直排列，一目了然

📦 典型应用场景

• 🎨 图像/视频处理软件的参数调节（亮度、对比度、饱和度…）
• 🎵 音频合成器或均衡器控制
• 🧪 科研实验中的超参数调试
• 🤖 机器人或仿真环境的实时控制面板
• 🛠️ 任何需要快速构建“数值调节 UI”的 Python 工具

🚀 快速开始

def on_brightness(val):
    print(f"亮度变化: {val}")

def on_volume(val):
    print(f"音量: {float(val):.2f}")

app = SliderApp(base_width=500)

app.add_slider("亮度", 0, 100, initial=70, command=on_brightness)
app.add_slider("音量", 0, 1, resolution=0.01, initial=0.6, command=on_volume)
app.add_slider("对比度", 50, 150, initial=100)
app.add_slider("色温(K)", 2000, 10000, initial=6500)

app.finish_add()
# app.run()  # blockingly run the app
while True:
    if not app.update():
        break
print("应用已关闭。")