bubbleUI 0.4.4a1__py3-none-any.whl

bubble/levels/manager.py

@@ -0,0 +1,334 @@
+"""pyside6_levels.manager —— “组件层级（level）”核心实现。
+
+术语
+====
+- contribution（层级贡献）：一个组件为它的**子控件**增加的层级，默认 0。
+  内置按钮等普通控件贡献为 0；自制卡片组件通常贡献为 1。
+- raw / base level（基础层级）：控件自身的层级 = 祖先链上所有组件贡献之和。
+  组件**自己的贡献不计入自身**，只作用于后代。
+- defined levels（断点）：用户在 QSS 里通过 ``[level="N"]`` 声明过的层级集合，
+  永远包含 0（默认配色）。
+- style level（样式层级）：按“就近向下填充”规则映射后的层级，写入控件的
+  动态属性 ``level``，供 QSS 选择器匹配；真实层级写入 ``rawLevel`` 便于调试。
+
+填充规则
+========
+对某个断点集合 D（例如 {0, 1, 3}）和控件的基础层级 r：
+
+    style(r) = max { d ∈ D | d <= r }
+
+即：层级 1、3 有定义时，2 使用 1 的配色，4 使用 3 的配色；D 中只有 0
+（用户没写任何额外断点）时，所有层级都落到 0，也就是默认规则。
+
+为什么必须运行时计算
+====================
+QSS 没有“最近的更低断点”选择器；``[level=1]`` 这种**不带引号的数字值**
+在 Qt 的 CSS 解析器里是非法语法，会导致整份样式表解析失败。因此本模块在
+``setStyleSheet()`` 中把 ``[level=1]`` 规范化为 ``[level="1"]``，再把每个
+控件解析后的样式层级写进 ``level`` 动态属性并重新 polish，从而让用户仍可
+用自然写法书写选择器。
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable, Optional
+
+from PySide6.QtCore import QEvent, QObject, Qt, QTimer, Signal
+from PySide6.QtWidgets import QApplication, QWidget
+
+__all__ = [
+    "LevelManager",
+    "normalize_level_selectors",
+    "parse_defined_levels",
+]
+
+# 私有状态挂在控件实例上（不用动态属性，避免污染 QSS 选择器命名空间）
+_CONTRIB_ATTR = "_pyside6_level_contribution"
+_OVERRIDE_ATTR = "_pyside6_level_override"
+_MANAGER_ATTR = "_pyside6_level_manager"
+
+#: 不带引号的层级选择器（Qt 不接受，需要规范化）
+_UNQUOTED_LEVEL_RE = re.compile(r"\[\s*level\s*=\s*(-?\d+)\s*\]")
+#: 任意写法的层级选择器（用于收集断点）
+_LEVEL_VALUE_RE = re.compile(
+    r"""\[\s*level\s*=\s*(?:"(-?\d+)"|'(-?\d+)'|(-?\d+))\s*\]"""
+)
+_QSS_COMMENT_RE = re.compile(r"/\*.*?\*/", re.S)
+
+
+def _strip_comments(qss: str) -> str:
+    """去掉 QSS 注释，避免把注释里的示例选择器当成断点。"""
+    return _QSS_COMMENT_RE.sub("", qss)
+
+
+def normalize_level_selectors(qss: str) -> str:
+    """把 Qt 不接受的 ``[level=1]`` 改写成 ``[level="1"]``。
+
+    对已经带引号、以及非 level 的属性选择器不做任何改动。
+    """
+    return _UNQUOTED_LEVEL_RE.sub(
+        lambda m: '[level="%d"]' % max(0, int(m.group(1))), qss
+    )
+
+
+def parse_defined_levels(qss: str) -> "list[int]":
+    """从 QSS 文本中收集所有 ``[level=N]`` 断点，排序并保证包含 0。"""
+    text = _strip_comments(qss)
+    levels = {0}
+    for match in _LEVEL_VALUE_RE.finditer(text):
+        for group in match.groups():
+            if group is not None:
+                levels.add(max(0, int(group)))
+                break
+    return sorted(levels)
+
+
+class LevelManager(QObject):
+    """应用级单例：维护控件层级、解析断点、刷新 QSS 样式。"""
+
+    #: 任意控件的层级或断点变化、并完成一次重算后发出（可用于调试面板刷新）
+    levels_changed = Signal()
+
+    def __init__(self, app: Optional[QApplication] = None) -> None:
+        app = app or QApplication.instance()
+        if app is None:
+            raise RuntimeError("请先创建 QApplication，再使用 LevelManager")
+        super().__init__(app)
+        self._app: QApplication = app
+        self._levels: "list[int]" = [0]
+        self._raw_stylesheet: str = ""
+        self._in_recompute: bool = False
+        self._pending: bool = False
+
+        self._timer = QTimer(self)
+        self._timer.setSingleShot(True)
+        self._timer.setInterval(0)
+        self._timer.timeout.connect(self.recompute)
+
+        app.installEventFilter(self)
+        # 接管之前已经创建的控件
+        self.recompute()
+
+    # ------------------------------------------------------------------ 单例
+    @classmethod
+    def instance(cls) -> "LevelManager":
+        """取得（必要时创建）当前 QApplication 对应的管理器。"""
+        app = QApplication.instance()
+        if app is None:
+            raise RuntimeError("请先创建 QApplication，再使用 LevelManager")
+        manager = getattr(app, _MANAGER_ATTR, None)
+        if manager is None:
+            manager = cls(app)
+            setattr(app, _MANAGER_ATTR, manager)
+        return manager
+
+    # ------------------------------------------------------------ 样式表/断点
+    @property
+    def stylesheet(self) -> str:
+        """最近一次通过 :meth:`setStyleSheet` 传入的原始 QSS。"""
+        return self._raw_stylesheet
+
+    def defined_levels(self) -> "tuple[int, ...]":
+        """当前断点集合（升序，必含 0）。"""
+        return tuple(self._levels)
+
+    def set_defined_levels(self, levels: Iterable[int]) -> None:
+        """手动指定断点集合。
+
+        适用于样式表不由 :meth:`setStyleSheet` 管理、或需要额外断点的场景。
+        调用 :meth:`setStyleSheet` 会以 QSS 中解析出的断点**替换**本集合。
+        """
+        new_levels = sorted({0} | {max(0, int(level)) for level in levels})
+        if new_levels != self._levels:
+            self._levels = new_levels
+            self.recompute()
+
+    def setStyleSheet(self, qss: str) -> None:
+        """设置应用样式表：收集断点 → 规范化选择器 → 设置样式表 → 重算。
+
+        这是推荐的唯一入口。若直接调用 ``app.setStyleSheet()``，管理器无法
+        知道断点，也无法把 ``[level=1]`` 规范化成 Qt 认识的写法。
+        """
+        self._raw_stylesheet = qss
+        normalized = normalize_level_selectors(qss)
+        self._levels = parse_defined_levels(normalized)
+        # Qt 在 setStyleSheet 时会对已有控件整体重新应用样式；随后 recompute
+        # 把新算出的 level 写进控件，并对发生变化的控件重新 polish。
+        self._app.setStyleSheet(normalized)
+        self.recompute()
+
+    # ------------------------------------------------------------------ 层级
+    def contribution(self, widget: QWidget) -> int:
+        """控件为其子控件增加的层级（默认 0）。"""
+        return int(getattr(widget, _CONTRIB_ATTR, 0))
+
+    def set_contribution(self, widget: QWidget, contribution: int) -> None:
+        """设置控件的层级贡献（≥0）。自制组件一般在 ``__init__`` 里调用。"""
+        contribution = max(0, int(contribution))
+        if getattr(widget, _CONTRIB_ATTR, None) != contribution:
+            setattr(widget, _CONTRIB_ATTR, contribution)
+            self.schedule()
+
+    def override(self, widget: QWidget) -> Optional[int]:
+        """控件的绝对基础层级覆盖；未设置时为 None。"""
+        return getattr(widget, _OVERRIDE_ATTR, None)
+
+    def set_override(self, widget: QWidget, level: Optional[int]) -> None:
+        """强制指定控件的基础层级（绝对覆盖，不看父链）。
+
+        典型用途：
+        - 独立创建、尚无 parent 的控件；
+        - 挂在主窗口下、但视觉上属于另一个层级的弹窗/浮层；
+        - 组件内单独调整某个子控件的层级。
+        传 ``None`` 取消覆盖。
+        """
+        if level is None:
+            if getattr(widget, _OVERRIDE_ATTR, None) is not None:
+                delattr(widget, _OVERRIDE_ATTR)
+                self.schedule()
+            return
+        level = max(0, int(level))
+        if getattr(widget, _OVERRIDE_ATTR, None) != level:
+            setattr(widget, _OVERRIDE_ATTR, level)
+            self.schedule()
+
+    def raw_level(self, widget: QWidget) -> int:
+        """控件自身的基础层级（祖先贡献之和；覆盖优先；不含自身贡献）。"""
+        return self._raw_level(widget, {})
+
+    def style_level(self, raw_level: int) -> int:
+        """把基础层级按断点填充规则映射为样式层级。"""
+        raw_level = max(0, int(raw_level))
+        result = 0
+        for level in self._levels:
+            if level <= raw_level:
+                result = level
+            else:
+                break
+        return result
+
+    def level(self, widget: QWidget) -> int:
+        """控件当前应使用的样式层级（实时计算，不依赖事件循环）。"""
+        return self.style_level(self.raw_level(widget))
+
+    # ------------------------------------------------------------------ 刷新
+    def schedule(self) -> None:
+        """请求一次合并重算（0ms 单次定时器，适合 parent 尚未设置等异步场景）。"""
+        if not self._timer.isActive():
+            self._timer.start()
+
+    def flush(self) -> None:
+        """立即执行挂起的重算（测试、截图、需要同步读取 ``level`` 属性时使用）。"""
+        self._timer.stop()
+        self._pending = False
+        self.recompute()
+
+    def recompute(self) -> None:
+        """重算所有控件的 rawLevel / level 动态属性，并在变化时重新 polish。"""
+        if self._in_recompute:
+            self._pending = True
+            return
+        self._timer.stop()
+        self._in_recompute = True
+        changed_widgets: "list[QWidget]" = []
+        try:
+            raw_cache: "dict[int, int]" = {}
+            for widget in QApplication.allWidgets():
+                try:
+                    raw = self._raw_level(widget, raw_cache)
+                    target = self.style_level(raw)
+                    old_raw = widget.property("rawLevel")
+                    old_level = widget.property("level")
+                    if old_raw != raw:
+                        widget.setProperty("rawLevel", raw)
+                    if old_level != target:
+                        widget.setProperty("level", target)
+                    if old_raw != raw or old_level != target:
+                        changed_widgets.append(widget)
+                except RuntimeError:  # 底层 C++ 对象已销毁
+                    continue
+        finally:
+            self._in_recompute = False
+
+        if changed_widgets:
+            # 除控件自身外，还要刷新它的后代：祖先的属性可能参与
+            # `QFrame[level="1"] QPushButton` 这类后代选择器。
+            self._refresh_styles(changed_widgets)
+            self.levels_changed.emit()
+        if self._pending:
+            self._pending = False
+            self.schedule()
+
+    def _refresh_styles(self, changed_widgets: "list[QWidget]") -> None:
+        """对“自身或祖先发生变化、且已经 polish 过”的控件重新 polish。
+
+        从未 polish 过的控件不用处理：首次 show / 挂载 / grab 时的 polish
+        会读到最新的 ``level`` 属性。遍历整棵控件树一次，避免逐个子树重复遍历。
+        """
+        changed_ids = {id(widget) for widget in changed_widgets}
+        children: "dict[int, list[QWidget]]" = {}
+        roots: "list[QWidget]" = []
+        for widget in QApplication.allWidgets():
+            try:
+                parent = widget.parentWidget()
+            except RuntimeError:
+                continue
+            if parent is None:
+                roots.append(widget)
+            else:
+                children.setdefault(id(parent), []).append(widget)
+
+        stack = [(root, False) for root in roots]
+        while stack:
+            widget, ancestor_changed = stack.pop()
+            dirty = ancestor_changed or id(widget) in changed_ids
+            if dirty:
+                try:
+                    if widget.testAttribute(Qt.WidgetAttribute.WA_WState_Polished):
+                        self._repolish(widget)
+                except RuntimeError:
+                    continue
+            for child in children.get(id(widget), ()):
+                stack.append((child, dirty))
+
+    # ------------------------------------------------------------------ 内部
+    def _raw_level(self, widget: QWidget, cache: "dict[int, int]") -> int:
+        key = id(widget)
+        cached = cache.get(key)
+        if cached is not None:
+            return cached
+        override = self.override(widget)
+        if override is not None:
+            value = override
+        else:
+            parent = widget.parentWidget()
+            if parent is None:
+                value = 0
+            else:
+                value = self._raw_level(parent, cache) + self.contribution(parent)
+        cache[key] = value
+        return value
+
+    @staticmethod
+    def _repolish(widget: QWidget) -> None:
+        """动态属性变化后必须重新 polish，QSS 属性选择器才会重新匹配。"""
+        try:
+            style = widget.style()
+            style.unpolish(widget)
+            style.polish(widget)
+            widget.update()
+        except RuntimeError:
+            pass
+
+    # ------------------------------------------------------------------ 事件
+    def eventFilter(self, watched: QObject, event: QEvent) -> bool:
+        # parent 变化、子控件增删都会改变层级；用 0ms 定时器合并，避免构造期抖动
+        event_type = event.type()
+        if event_type in (
+            QEvent.Type.ParentChange,
+            QEvent.Type.ChildAdded,
+            QEvent.Type.ChildRemoved,
+        ):
+            self.schedule()
+        return False

bubble/styles.py

@@ -0,0 +1,282 @@
+'''
+组件样式
+'''
+import json
+import re
+from enum import Enum
+from .QUI import *
+
+__all__ = ['StyleReplaceMode', 'StyleSheet', 'styles', 'indexes', 'maps', 'style_path']
+
+class StyleReplaceMode(Enum):
+    '''
+    特殊样式替换模式
+    '''
+    ALL = 'all'  # 全部替换
+
+class StyleSheet:
+    '''CSS序列化工具类，支持CSS与JSON互相转换'''
+    
+    def __init__(self, css_text):
+        '''
+        初始化CSS序列化器
+        
+        Args:
+            css_text: CSS文本
+        '''
+        # 编译正则表达式以提高性能
+        self.property_pattern = re.compile(r'\s*([^:]+)\s*:\s*([^;]+)\s*(?:;|$)')
+        self.comment_pattern = re.compile(r'/\*.*?\*/', re.DOTALL)
+        self.empty_line_pattern = re.compile(r'\n\s*\n')
+        
+        # 变量
+        self.css_text = css_text
+        self.css_data = self.serialize(css_text)
+    
+    def _clean_css(self, css: str) -> str:
+        '''
+        清理CSS：移除注释、多余空格和空行
+        
+        Args:
+            css: 原始CSS字符串
+            
+        Returns:
+            清理后的CSS字符串
+        '''
+        # 移除CSS注释
+        css = self.comment_pattern.sub('', css)
+        
+        # 移除多余空格（保留必要的空格，如属性值中的空格）
+        # 这里我们只移除选择器和属性名周围的空格
+        css = css.strip()
+        
+        # 移除空行
+        css = self.empty_line_pattern.sub('\n', css)
+        
+        return css
+
+    def _parse_rule(self, selector: str, rule_body: str) -> dict[str, str]:
+        '''
+        解析单个CSS规则体
+        
+        Args:
+            selector: CSS选择器
+            rule_body: 规则体内容
+            
+        Returns:
+            解析后的属性字典
+        '''
+        properties = {}
+
+        # 查找所有属性
+        matches = self.property_pattern.findall(rule_body)
+        
+        for prop_name, prop_value in matches:
+            # 清理属性名和值
+            prop_name = prop_name.strip()
+            prop_value = prop_value.strip()
+            
+            if prop_name and prop_value:
+                properties[prop_name] = prop_value
+        
+        return properties
+    
+    def _get_value_by_indices(self, indices, multi_list):
+        '''
+        根据索引列表逐层访问多维列表
+        
+        Args:
+            indices: 一维索引列表，如 [0, 1]
+            multi_list: 多维列表，如 [[1, 2], [3, 4]]
+        
+        Returns:
+            对应位置的值
+        '''
+        result = multi_list
+        for index in indices:
+            result = result[index]
+        return result
+    
+    def _update_nested_dict(self, keys, nested_dict, new_value):
+        '''
+        根据键列表更新嵌套字典中的值，中间层级不存在时会自动创建
+        
+        Args:
+            keys: 键列表，如 ['a', 'b']
+            nested_dict: 嵌套字典，如 {'a': {'b': 'c'}}
+            new_value: 要设置的新值，如 'd'
+        
+        Returns:
+            修改后的字典（原字典不会被修改）
+        '''
+        result = nested_dict.copy()
+        current = result
+        
+        # 遍历到倒数第二个键，缺失时自动创建
+        for key in keys[:-1]:
+            child = current.get(key)
+            if not isinstance(child, dict):
+                child = {}
+            else:
+                child = child.copy()
+            current[key] = child
+            current = child
+        
+        # 用最后一个键设置新值
+        current[keys[-1]] = new_value
+        
+        return result
+    
+    def serialize_to_jsonstr(self, css: str, indent: None | int = None) -> str:
+        '''
+        将CSS序列化为JSON字符串
+        
+        Args:
+            css: CSS字符串
+            indent: JSON缩进，None表示不缩进
+            
+        Returns:
+            JSON格式字符串
+        '''
+        result = {}
+
+        # 清理CSS
+        css = self._clean_css(css)
+        
+        # 分割规则块
+        # 查找所有规则：选择器 { 规则体 }
+        rule_start = 0
+        depth = 0  # 花括号深度
+        current_selector = None
+        current_rule_start = 0
+        
+        for i, char in enumerate(css):
+            if char == '{':
+                if depth == 0:
+                    # 找到选择器
+                    selector_text = css[rule_start:i].strip()
+                    if selector_text:
+                        current_selector = selector_text
+                        current_rule_start = i + 1
+                depth += 1
+            elif char == '}':
+                depth -= 1
+                if depth == 0 and current_selector:
+                    # 规则结束
+                    rule_body = css[current_rule_start:i]
+                    
+                    # 解析规则
+                    properties = self._parse_rule(current_selector, rule_body)
+                    if properties:
+                        # 处理多个选择器（如 'p, a, div'）
+                        selectors = [s.strip() for s in current_selector.split(',')]
+                        for selector in selectors:
+                            if selector:
+                                if selector in result:
+                                    # 合并重复选择器的属性
+                                    result[selector].update(properties)
+                                else:
+                                    result[selector] = properties.copy()
+                    
+                    # 重置
+                    current_selector = None
+                    rule_start = i + 1
+        
+        return json.dumps(result, indent=indent)
+    
+    def serialize(self, css: str) -> dict:
+        '''
+        将CSS序列化为字典
+        
+        Args:
+            css: CSS字符串
+            
+        Returns:
+            序列化后的字典
+        '''
+        json_str = self.serialize_to_jsonstr(css)
+        try:
+            return json.loads(json_str)
+        except json.JSONDecodeError:
+            raise ValueError(f'无效的JSON格式: {json_str}')
+    
+    def deserialize(
+        self, 
+        json_input: str | dict, 
+    ) -> str:
+        '''
+        将JSON反序列化为CSS
+        
+        Args:
+            json_input: JSON字符串或字典
+            style: CSS格式化样式
+            indent: 缩进空格数（仅当style为PRETTY时有效）
+            
+        Returns:
+            CSS字符串
+        '''
+        try:
+            # 解析JSON输入
+            if isinstance(json_input, str):
+                data = json.loads(json_input)
+            elif isinstance(json_input, dict):
+                data = json_input
+            else:
+                raise ValueError('输入必须是JSON字符串或字典')
+            
+            css_rules = []
+            
+            for selector, properties in data.items():
+                if not isinstance(properties, dict):
+                    continue
+
+                # 最小化格式：无空格
+                rule = f'{selector}{{'
+                rule += ';'.join([f'{prop}:{value}' for prop, value in properties.items()])
+                rule += ';}'
+                css_rules.append(rule)
+            return ''.join(css_rules)            
+        except json.JSONDecodeError as e:
+            raise ValueError(f'无效的JSON格式: {e}')
+        
+    def refresh(self, css_text: str):
+        '''
+        刷新CSS文本并重新解析
+        
+        Args:
+            css_text: 新的CSS文本
+        '''
+        self.css_text = css_text
+        self.css_data = self.serialize(css_text)
+        
+    def replace(self, index, old_value: str | StyleReplaceMode, new_value: str, output_json: bool = True) -> dict:
+        '''
+        替换CSS数据中的值
+        
+        Args:
+            index: 要替换值的索引
+            old_value: 旧值；为 StyleReplaceMode.ALL 时直接覆盖，键不存在时自动创建
+            new_value: 新值
+            output_json: True 返回字典，False 返回 StyleSheet
+            
+        Returns:
+            新的CSS数据字典或 StyleSheet
+        '''
+        data = self.css_data.copy()
+        
+        if old_value == StyleReplaceMode.ALL:
+            # 全匹配：即使键不存在也会创建
+            new_data = self._update_nested_dict(index, data, new_value)
+            if output_json:
+                return new_data
+            return StyleSheet(self.deserialize(new_data))
+        
+        value = self._get_value_by_indices(index, data)
+        
+        if not isinstance(value, str):
+            raise ValueError(f'索引{index}处的值不是字符串')
+        
+        new_data = self._update_nested_dict(index, data, value.replace(old_value, new_value))
+        if output_json:
+            return new_data
+        return StyleSheet(self.deserialize(new_data))