#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
水质参数反演分析系统 - UI样式系统文档

Modern UI Stylesheet System Documentation
================================================================================

1. 概述
------
本系统采用现代化的扁平设计风格，提供了一套完整的样式表和主题管理系统。
所有UI组件都遵循统一的设计规范，确保整体的视觉一致性和用户体验。

2. 颜色系统
-----------
主要颜色定义在 ModernStylesheet.COLORS 中：

- main_bg (#F0F0F0)：主窗口背景，浅灰色
- panel_bg (#FFFFFF)：面板/容器背景，纯白色
- text_primary (#000000)：主文字颜色，黑色
- text_secondary (#666666)：辅助文字颜色，灰色
- border (#D0D0D0)：边框颜色，浅灰
- border_light (#E8E8E8)：浅边框颜色
- accent (#007BFF)：强调色，蓝色
- success (#28A745)：成功绿
- error (#DC3545)：错误红
- warning (#FFC107)：警告黄
- hover (#E8E8E8)：悬停背景色
- selected (#0056B3)：选中色

3. 按钮样式
-----------
系统提供了四种预定义的按钮样式：

a) 普通按钮（normal）
   background-color: 白色
   border: 1px 灰色边框
   border-radius: 7px
   用法: ModernStylesheet.get_button_stylesheet('normal')

b) 主按钮（primary）- 蓝色
   background-color: 蓝色 (#007BFF)
   color: 白色
   border-radius: 7px
   用法: ModernStylesheet.get_button_stylesheet('primary')

c) 成功按钮（success）- 绿色
   background-color: 绿色 (#28A745)
   color: 白色
   border-radius: 7px
   用法: ModernStylesheet.get_button_stylesheet('success')
   常用于：独立运行、确认操作等

d) 危险按钮（danger）- 红色
   background-color: 红色 (#DC3545)
   color: 白色
   border-radius: 7px
   用法: ModernStylesheet.get_button_stylesheet('danger')
   常用于：停止、删除操作等

示例代码：
---------
from src.gui.styles import ModernStylesheet

# 创建成功按钮
run_btn = QPushButton("运行")
run_btn.setStyleSheet(ModernStylesheet.get_button_stylesheet('success'))

# 创建危险按钮
stop_btn = QPushButton("停止")
stop_btn.setStyleSheet(ModernStylesheet.get_button_stylesheet('danger'))

4. 输入框样式
-------------
所有输入框（QLineEdit, QComboBox, QSpinBox等）都采用统一样式：
- background-color: 白色
- border: 1px 灰色边框
- border-radius: 5-10px（圆角）
- 焦点时：边框变为蓝色（accent color）

5. 分组框（QGroupBox）
----------------------
分组框采用简洁的设计：
- background-color: 白色
- border: 无or仅下边框（1px 浅灰）
- border-radius: 0
- 内边距: 9px

6. 复选框和单选框
-----------------
复选框和单选框保持默认样式，具有以下特性：
- 大小: 16x16px
- 选中时：蓝色背景（accent color）
- 边框: 1px 灰色

7. 应用样式表
--------------
主样式表通过 apply_stylesheet() 方法应用到整个应用：

    self.setStyleSheet(ModernStylesheet.get_main_stylesheet())

专用样式表可按需应用：

    # 工具栏样式
    toolbar_widget.setStyleSheet(ModernStylesheet.get_toolbar_stylesheet())
    
    # 边栏样式
    sidebar_widget.setStyleSheet(ModernStylesheet.get_sidebar_stylesheet())

8. 布局特点
-----------
应用的主要布局特点：

a) 顶部工具栏
   - 白色背景
   - 下边框 1px 浅灰
   - 包含logo、模块切换按钮、窗口控制按钮

b) 左侧导航栏（宽度：~280px）
   - 白色背景
   - 右边框 1px 浅灰
   - 包含步骤列表、运行/停止按钮
   - 步骤列表支持选中状态显示

c) 右侧内容区
   - 浅灰背景
   - 包含标签页、日志区、进度条
   - 标签页支持切换

d) 底部状态栏
   - 白色背景
   - 上边框 1px 浅灰
   - 显示当前状态和进度信息

9. 自定义样式
--------------
如需为某个组件应用自定义样式，建议：

a) 简单修改（如颜色）：
   widget.setStyleSheet(f"background-color: {ModernStylesheet.COLORS['panel_bg']};")

b) 复杂修改：
   添加新方法到 ModernStylesheet 类
   
   @staticmethod
    def get_custom_stylesheet():
        return "..."

c) 一次性样式：
   直接在widget.setStyleSheet中定义
   注意：保持与整体风格的一致性

10. 最佳实践
--------------

✓ DO:
  - 使用 ModernStylesheet 中的颜色常量
  - 使用预定义的样式表方法
  - 维持一致的间距和圆角半径
  - 使用适当的按钮类型（success/danger等）
  - 为交互元素提供hover和pressed状态反馈

✗ DON'T:
  - 直接使用硬编码颜色值
  - 混合不同的设计风格
  - 过度使用渐变和阴影
  - 忽视focus和disabled状态
  - 使用过小或过大的字体

11. 响应式设计
---------------
系统支持基本的响应式布局：
- 导航栏最大宽度: 280px
- 内容区域自动调整
- 步骤面板自动滚动

12. 字体设置
-----------
主要字体：
- 界面标题：Arial, 13-14pt, Bold
- 普通文本：系统默认, 11-12pt
- 等宽字体（日志）：Courier New, 10pt, Monospace

13. 性能优化
-----------
- 样式表在应用启动时加载
- 避免频繁修改样式表
- 使用CSS类而非硬编码样式
- 合理使用selector优化渲染

14. 常见问题
-----------
Q: 如何改变全局字体大小？
A: 修改 ModernStylesheet 类中的样式表定义

Q: 如何添加新的按钮类型？
A: 在 ModernStylesheet 类中添加新方法

Q: 如何支持深色模式？
A: 创建新的样式类，定义深色配色方案

Q: 标签页标签栏消失了怎么办？
A: 检查QTabBar::tab的height设置，确保高度大于0

================================================================================

更新历史：
- v1.0: 初始版本，实现现代化扁平设计风格
- v1.1: 改进导航栏和日志区域样式
- v1.2: 添加专用样式表方法（工具栏、边栏等）

================================================================================
"""

# 快速参考表
QUICK_REFERENCE = """
┌─ 快速参考 ─────────────────────────────────────────────────────────────┐
│                                                                           │
│ 按钮样式:                                                                │
│   正常: ModernStylesheet.get_button_stylesheet('normal')                 │
│   主要: ModernStylesheet.get_button_stylesheet('primary')                │
│   成功: ModernStylesheet.get_button_stylesheet('success')                │
│   危险: ModernStylesheet.get_button_stylesheet('danger')                 │
│                                                                           │
│ 颜色引用:                                                                │
│   ModernStylesheet.COLORS['main_bg']      # #F0F0F0 浅灰               │
│   ModernStylesheet.COLORS['panel_bg']     # #FFFFFF 白色               │
│   ModernStylesheet.COLORS['text_primary'] # #000000 黑色               │
│   ModernStylesheet.COLORS['accent']       # #007BFF 蓝色               │
│   ModernStylesheet.COLORS['success']      # #28A745 绿色               │
│   ModernStylesheet.COLORS['error']        # #DC3545 红色               │
│                                                                           │
│ 样式表应用:                                                              │
│   self.setStyleSheet(ModernStylesheet.get_main_stylesheet())             │
│   widget.setStyleSheet(ModernStylesheet.get_toolbar_stylesheet())        │
│   widget.setStyleSheet(ModernStylesheet.get_sidebar_stylesheet())        │
│                                                                           │
└───────────────────────────────────────────────────────────────────────┘
"""

if __name__ == "__main__":
    print(QUICK_REFERENCE)