struct2ui 0.1.0__py3-none-any.whl

struct2ui/ui/widgets.py

@@ -0,0 +1,907 @@
+"""Leaf-widget production and reactive enabling.
+
+WidgetFactory   - Field + value -> editor QWidget (and reverse: QWidget -> value)
+WhenBinder      - collect (dotted_name, widget, when-clause) and wire enable/disable
+
+Adding a new editor widget type only requires adding entries to:
+    _READERS         - QWidget type -> reader function
+    _CHANGE_SIGNALS  - QWidget type -> change-signal name
+plus a builder branch in WidgetFactory if needed.
+"""
+
+from __future__ import annotations
+
+import re
+from decimal import Decimal, InvalidOperation
+from typing import Any, Callable, Dict, List, Tuple
+
+from Qt import QtCore, QtGui, QtWidgets
+
+from ..schema import Field, ScalarField, EnumField, StructField, ArrayField
+
+
+# --------------------------------------------------------------------------- #
+# Centralised widget <-> value mappings (single source of truth)
+# --------------------------------------------------------------------------- #
+
+# Reader: how to extract the current value from each widget type.
+_READERS: Dict[type, Callable[[QtWidgets.QWidget], Any]] = {
+    QtWidgets.QCheckBox:        lambda w: w.isChecked(),
+    QtWidgets.QPushButton:      lambda w: w.isChecked(),
+    QtWidgets.QComboBox:        lambda w: w.currentText(),
+    QtWidgets.QSpinBox:         lambda w: w.value(),
+    QtWidgets.QDoubleSpinBox:   lambda w: w.value(),
+    QtWidgets.QSlider:          lambda w: w.value(),
+    QtWidgets.QDial:            lambda w: w.value(),
+    QtWidgets.QLineEdit:        lambda w: w.text(),
+}
+
+# Change signal name: used by WhenBinder to subscribe to value changes.
+_CHANGE_SIGNALS: Dict[type, str] = {
+    QtWidgets.QCheckBox:        'toggled',
+    QtWidgets.QPushButton:      'toggled',
+    QtWidgets.QComboBox:        'currentTextChanged',
+    QtWidgets.QSpinBox:         'valueChanged',
+    QtWidgets.QDoubleSpinBox:   'valueChanged',
+    QtWidgets.QSlider:          'valueChanged',
+    QtWidgets.QDial:            'valueChanged',
+    QtWidgets.QLineEdit:        'textChanged',
+}
+
+
+def _lookup(mapping: Dict[type, Any], w: QtWidgets.QWidget) -> Any:
+    """Find a mapping entry honouring isinstance (so subclasses are matched).
+
+    Exact-type match wins over isinstance, so subclasses (e.g.
+    `_ScalarArrayLineEdit` extending `QLineEdit`) can register their own
+    reader without being shadowed by the base class entry.
+    """
+    exact = mapping.get(type(w))
+    if exact is not None:
+        return exact
+    for cls, val in mapping.items():
+        if isinstance(w, cls):
+            return val
+    return None
+
+
+# --------------------------------------------------------------------------- #
+# WidgetFactory: stateless builder
+# --------------------------------------------------------------------------- #
+
+class WidgetFactory:
+    """Build an editor widget for a leaf Field (scalar/enum); read its value back."""
+
+    @staticmethod
+    def build(f: Field, value: Any) -> QtWidgets.QWidget:
+        if isinstance(f, ArrayField):
+            return _build_array_value(f, value)
+        if isinstance(f, EnumField):
+            return _build_enum(f, value)
+        if isinstance(f, ScalarField):
+            ui = f.ui_type
+            if ui == 'bool':
+                return _build_bool(f, value)
+            if ui == 'int':
+                return _build_int(f, value)
+            if ui == 'float':
+                return _build_float(f, value)
+            if ui == 'str':
+                return _build_text(value, f)
+        return _build_text(value)
+
+    @staticmethod
+    def read(w: QtWidgets.QWidget) -> Any:
+        reader = _lookup(_READERS, w)
+        return reader(w) if reader else None
+
+
+# ---- per-type small builders (easy to extend) ----------------------------- #
+
+def _build_enum(f: EnumField, value: Any) -> QtWidgets.QComboBox:
+    w = QtWidgets.QComboBox()
+    for k in f.items.keys():
+        w.addItem(k)
+    idx = w.findText(str(value))
+    if idx >= 0:
+        w.setCurrentIndex(idx)
+    return w
+
+
+def _build_bool(f: ScalarField, value: Any) -> QtWidgets.QWidget:
+    if f.meta.get('widget') == 'toggle':
+        w = QtWidgets.QPushButton()
+        w.setCheckable(True)
+        w.setChecked(bool(value))
+        _toggle_refresh_text(w)
+        w.toggled.connect(lambda _=None, b=w: _toggle_refresh_text(b))
+        return w
+    w = QtWidgets.QCheckBox()
+    w.setChecked(bool(value))
+    return w
+
+
+def _toggle_refresh_text(b: QtWidgets.QPushButton) -> None:
+    b.setText('ON' if b.isChecked() else 'OFF')
+
+
+class _RangedSlider(QtWidgets.QSlider):
+    """QSlider that paints only the current value, centered in its own rect.
+
+    Min/max are displayed by the surrounding `_LabeledSliderHolder` via real
+    QLabel widgets, so they are never overlapped by the handle.
+    """
+
+    def __init__(self, parent: QtWidgets.QWidget = None) -> None:
+        super().__init__(QtCore.Qt.Horizontal, parent)
+        f = self.font()
+        f.setPointSizeF(max(7.0, f.pointSizeF() - 1.0))
+        self.setFont(f)
+        self.valueChanged.connect(self.update)
+
+    def paintEvent(self, ev) -> None:  # Qt override
+        super().paintEvent(ev)
+        painter = QtGui.QPainter(self)
+        fm = painter.fontMetrics()
+        rect = self.rect()
+        y = rect.center().y() + fm.ascent() // 2 - 1
+        painter.setPen(self.palette().color(QtGui.QPalette.WindowText))
+        cur_text = str(self.value())
+        cx = rect.center().x() - fm.horizontalAdvance(cur_text) // 2
+        painter.drawText(cx, y, cur_text)
+        painter.end()
+
+
+class _LabeledSliderHolder(QtWidgets.QWidget):
+    """Horizontal composite: [min label] [QSlider] [max label].
+
+    Exposes the inner slider via `.slider` so existing isinstance-based
+    machinery (_READERS / _CHANGE_SIGNALS / WhenBinder) can still reach it.
+    Two registry entries below route reads/signals to this holder directly.
+    """
+
+    def __init__(self, mn: int, mx: int, parent: QtWidgets.QWidget = None) -> None:
+        super().__init__(parent)
+        self.slider = _RangedSlider(self)
+        self.slider.setRange(mn, mx)
+
+        lbl_mn = QtWidgets.QLabel(str(mn), self)
+        lbl_mx = QtWidgets.QLabel(str(mx), self)
+        for lbl in (lbl_mn, lbl_mx):
+            f = lbl.font()
+            f.setPointSizeF(max(7.0, f.pointSizeF() - 1.0))
+            lbl.setFont(f)
+
+        lay = QtWidgets.QHBoxLayout(self)
+        lay.setContentsMargins(0, 0, 0, 0)
+        lay.setSpacing(4)
+        lay.addWidget(lbl_mn)
+        lay.addWidget(self.slider, 1)
+        lay.addWidget(lbl_mx)
+
+    # Convenience pass-throughs so callers can treat the holder like a slider.
+    def value(self) -> int:
+        return self.slider.value()
+
+    def setValue(self, v: int) -> None:
+        self.slider.setValue(int(v))
+
+    def setSingleStep(self, s: int) -> None:
+        self.slider.setSingleStep(int(s))
+
+    @property
+    def valueChanged(self):
+        return self.slider.valueChanged
+
+
+# Register holder so WidgetFactory.read() and WhenBinder see it natively.
+_READERS[_LabeledSliderHolder] = lambda w: w.value()
+_CHANGE_SIGNALS[_LabeledSliderHolder] = 'valueChanged'
+
+
+class _DialPopup(QtWidgets.QWidget):
+    """Floating QDial + centered value label, owned by `_DialSpinBox`.
+
+    Uses `Qt.ToolTip` window flag (instead of `Qt.Popup`) and `Qt.NoFocus`
+    focus policy so it never steals focus from the spin box. The spin box
+    itself decides when to show/hide it via focusIn/focusOut.
+    """
+
+    def __init__(self, mn: int, mx: int, parent: QtWidgets.QWidget = None) -> None:
+        super().__init__(parent, QtCore.Qt.ToolTip | QtCore.Qt.FramelessWindowHint)
+        self.setFocusPolicy(QtCore.Qt.NoFocus)
+        self.setAttribute(QtCore.Qt.WA_ShowWithoutActivating, True)
+
+        self.dial = QtWidgets.QDial(self)
+        self.dial.setFocusPolicy(QtCore.Qt.NoFocus)
+        self.dial.setRange(int(mn), int(mx))
+        self.dial.setNotchesVisible(True)
+        self.dial.setFixedSize(96, 96)
+
+        self.label = QtWidgets.QLabel('0', self.dial)
+        self.label.setAlignment(QtCore.Qt.AlignCenter)
+        self.label.setAttribute(QtCore.Qt.WA_TransparentForMouseEvents, True)
+        f = self.label.font()
+        f.setBold(True)
+        self.label.setFont(f)
+
+        lay = QtWidgets.QVBoxLayout(self)
+        lay.setContentsMargins(6, 6, 6, 6)
+        lay.addWidget(self.dial)
+
+        self.dial.valueChanged.connect(self._on_dial)
+
+    def _on_dial(self, v: int) -> None:
+        self.label.setText(str(v))
+
+    def resizeEvent(self, ev) -> None:  # Qt override
+        super().resizeEvent(ev)
+        self.label.setGeometry(self.dial.rect())
+
+
+class _DialSpinBox(QtWidgets.QSpinBox):
+    """QSpinBox that pops up a floating QDial while it has focus.
+
+    Read path stays trivial: outer widget IS a QSpinBox, so the existing
+    `_READERS[QSpinBox]` and `_CHANGE_SIGNALS[QSpinBox]` entries already work.
+    """
+
+    def __init__(self, mn: int, mx: int, parent: QtWidgets.QWidget = None) -> None:
+        super().__init__(parent)
+        self.setRange(int(mn), int(mx))
+        self._popup = _DialPopup(int(mn), int(mx))
+        self._guard = False
+        self.valueChanged.connect(self._sync_to_dial)
+        self._popup.dial.valueChanged.connect(self._sync_from_dial)
+
+    def _sync_to_dial(self, v: int) -> None:
+        if self._guard:
+            return
+        self._guard = True
+        try:
+            self._popup.dial.setValue(int(v))
+            self._popup.label.setText(str(int(v)))
+        finally:
+            self._guard = False
+
+    def _sync_from_dial(self, v: int) -> None:
+        if self._guard:
+            return
+        self._guard = True
+        try:
+            self.setValue(int(v))
+        finally:
+            self._guard = False
+
+    def _show_popup(self) -> None:
+        self._popup.dial.setValue(self.value())
+        self._popup.label.setText(str(self.value()))
+        self._popup.adjustSize()
+        gp = self.mapToGlobal(QtCore.QPoint(0, self.height()))
+        self._popup.move(gp)
+        self._popup.show()
+
+    def focusInEvent(self, ev) -> None:  # Qt override
+        super().focusInEvent(ev)
+        self._show_popup()
+
+    def focusOutEvent(self, ev) -> None:  # Qt override
+        super().focusOutEvent(ev)
+        self._safe_hide_popup()
+
+    def keyPressEvent(self, ev) -> None:  # Qt override
+        if ev.key() == QtCore.Qt.Key_Escape and self._popup.isVisible():
+            self._popup.hide()
+            return
+        super().keyPressEvent(ev)
+
+    def hideEvent(self, ev) -> None:  # Qt override
+        self._safe_hide_popup()
+        super().hideEvent(ev)
+
+    def _safe_hide_popup(self) -> None:
+        # Qt may have destroyed the popup during interpreter shutdown; guard.
+        try:
+            self._popup.hide()
+        except RuntimeError:
+            pass
+
+
+class _ScalarArrayLineEdit(QtWidgets.QLineEdit):
+    """Whole-array editor: a single QLineEdit holding comma-separated numbers.
+
+    Reading back via _READERS returns a Python list (parsed); subclassing
+    QLineEdit ensures the existing _READERS[QLineEdit] entry does NOT match
+    first - we register an explicit entry for this class below.
+
+    Length validation: turns the text red when the parsed count != f.count.
+    Invalid syntax also turns red. We do not block typing - the user must be
+    able to edit through transient bad states.
+    """
+
+    def __init__(self, f: ArrayField, value: Any,
+                 parent: QtWidgets.QWidget = None) -> None:
+        super().__init__(parent)
+        self._field = f
+        self._is_float = bool(
+            isinstance(f.element, ScalarField) and f.element.ui_type == 'float'
+        )
+        self._is_enum = isinstance(f.element, EnumField)
+        self._enum_keys = (
+            list(f.element.items.keys()) if self._is_enum else []
+        )
+        self.setText(self._format(value))
+        self.textChanged.connect(self._revalidate)
+        self._revalidate(self.text())
+
+    def _format(self, value: Any) -> str:
+        if not isinstance(value, list):
+            return ''
+        parts = []
+        for v in value:
+            if v is None:
+                parts.append(self._enum_keys[0] if self._is_enum else '0')
+            elif self._is_enum:
+                parts.append(str(v))
+            elif self._is_float:
+                parts.append(f'{float(v):g}')
+            else:
+                try:
+                    parts.append(str(int(v)))
+                except Exception:
+                    parts.append(str(v))
+        return ', '.join(parts)
+
+    def parsed(self) -> Any:
+        """Parse current text. Returns list on success, None on syntax error."""
+        txt = self.text().strip()
+        if not txt:
+            return []
+        out: List[Any] = []
+        for tok in txt.split(','):
+            tok = tok.strip()
+            if not tok:
+                return None
+            if self._is_enum:
+                if tok not in self._enum_keys:
+                    return None
+                out.append(tok)
+            else:
+                try:
+                    out.append(float(tok) if self._is_float else int(tok))
+                except ValueError:
+                    return None
+        return out
+
+    def _revalidate(self, _txt: str) -> None:
+        parsed = self.parsed()
+        ok = isinstance(parsed, list) and len(parsed) == self._field.count
+        self.setStyleSheet('' if ok else 'QLineEdit{color:#c33;}')
+        self.setToolTip(
+            '' if ok else f'Expected {self._field.count} comma-separated values'
+        )
+
+
+_READERS[_ScalarArrayLineEdit] = lambda w: w.parsed()
+_CHANGE_SIGNALS[_ScalarArrayLineEdit] = 'textChanged'
+
+
+class _MultilinePopup(QtWidgets.QPlainTextEdit):
+    """浮动多行编辑面板。
+
+    设计要点（参考 dial 的成功经验，避开 Qt.Popup 的坑）：
+
+    * 使用 Qt.Tool | Qt.FramelessWindowHint —— 普通独立浮动窗口，
+      **不抓全局鼠标**，事件分发完全正常，目标控件能直接获得焦点。
+    * 与 dial 不同：multiline 必须接收键盘输入，所以不能用 NoFocus
+      + WA_ShowWithoutActivating。允许它正常获得焦点接收键盘。
+    * 关闭策略不放在 popup 自己身上，而是由宿主 _PopupMultilineArrayEdit
+      通过 QApplication.focusChanged 决定（焦点离开本组合就收起）。
+    * Esc 仍然由 popup 本身处理。
+    """
+
+    closed = QtCore.Signal()
+
+    def __init__(self, parent: QtWidgets.QWidget = None) -> None:
+        super().__init__(parent)
+        self.setWindowFlags(
+            QtCore.Qt.Tool | QtCore.Qt.FramelessWindowHint
+        )
+        self.setLineWrapMode(QtWidgets.QPlainTextEdit.NoWrap)
+
+    def keyPressEvent(self, ev) -> None:  # Qt override
+        if ev.key() == QtCore.Qt.Key_Escape:
+            self.close()
+            return
+        super().keyPressEvent(ev)
+
+    def closeEvent(self, ev) -> None:  # Qt override
+        self.closed.emit()
+        super().closeEvent(ev)
+
+
+class _PopupMultilineArrayEdit(_ScalarArrayLineEdit):
+    """单行外壳 + 弹出多行编辑器。
+
+    行为模仿 dial：聚焦时弹出 popup；popup 失焦/Esc 收回并把内容归一化
+    成 ", " 分隔的单行写回。两边内容通过 textChanged 信号双向同步，
+    用 _guard 防回环。
+
+    所有解析、校验、_READERS 注册都从 _ScalarArrayLineEdit 继承——本类
+    只负责"额外的弹出 UI"，单行控件本身的语义不变。
+    """
+
+    def __init__(self, f: ArrayField, value: Any,
+                 parent: QtWidgets.QWidget = None) -> None:
+        super().__init__(f, value, parent)
+        shape = f.meta.get('shape')
+        self._row_size = (
+            int(shape[-1]) if isinstance(shape, list) and shape else 0
+        )
+        self._popup = _MultilinePopup()
+        self._guard = False
+        self._suppress_popup = False
+        self.textChanged.connect(self._sync_to_popup)
+        self._popup.textChanged.connect(self._sync_from_popup)
+        self._popup.closed.connect(self._on_popup_closed)
+        QtWidgets.QApplication.instance().focusChanged.connect(
+            self._on_focus_changed
+        )
+
+    def _on_focus_changed(self, old, new) -> None:
+        if not self._popup.isVisible():
+            return
+        if new is None:
+            return
+        # 焦点跑到本控件、popup、或 popup 的子控件（viewport 等）上都算"内部"
+        if new is self or new is self._popup:
+            return
+        try:
+            if self._popup.isAncestorOf(new):
+                return
+        except RuntimeError:
+            return
+        self._popup.close()
+
+    def _format_multiline(self, flat_text: str) -> str:
+        """把单行文本按 shape[-1] 折成多行。无 shape 时原样返回。"""
+        if self._row_size <= 0:
+            return flat_text
+        tokens = [t for t in re.split(r'[,\s]+', flat_text) if t]
+        if not tokens:
+            return ''
+        rs = self._row_size
+        lines = [
+            ', '.join(tokens[i:i + rs]) for i in range(0, len(tokens), rs)
+        ]
+        return '\n'.join(lines)
+
+    def _normalize_singleline(self, multi_text: str) -> str:
+        """把多行文本归一化为 ', ' 分隔的单行。"""
+        tokens = [t for t in re.split(r'[,\s]+', multi_text) if t]
+        return ', '.join(tokens)
+
+    def _sync_to_popup(self, _txt: str = '') -> None:
+        if self._guard:
+            return
+        self._guard = True
+        try:
+            self._popup.setPlainText(self._format_multiline(self.text()))
+        finally:
+            self._guard = False
+
+    def _sync_from_popup(self) -> None:
+        if self._guard:
+            return
+        self._guard = True
+        try:
+            self.setText(self._normalize_singleline(self._popup.toPlainText()))
+        finally:
+            self._guard = False
+
+    def _show_popup(self) -> None:
+        self._guard = True
+        try:
+            self._popup.setPlainText(self._format_multiline(self.text()))
+        finally:
+            self._guard = False
+        self._popup.resize(max(self.width(), 320),
+                           self.fontMetrics().lineSpacing() * 8 + 12)
+        gp = self.mapToGlobal(QtCore.QPoint(0, self.height()))
+        self._popup.move(gp)
+        self._popup.show()
+        self._popup.raise_()
+        self._popup.activateWindow()
+        self._popup.setFocus()
+
+    def _on_popup_closed(self) -> None:
+        self._suppress_popup = True
+        self.setText(self._normalize_singleline(self._popup.toPlainText()))
+        QtCore.QTimer.singleShot(0, self._reset_suppress)
+
+    def _reset_suppress(self) -> None:
+        self._suppress_popup = False
+
+    def focusInEvent(self, ev) -> None:  # Qt override
+        super().focusInEvent(ev)
+        if not self._suppress_popup and not self._popup.isVisible():
+            self._show_popup()
+
+    def hideEvent(self, ev) -> None:  # Qt override
+        try:
+            self._popup.hide()
+        except RuntimeError:
+            pass
+        super().hideEvent(ev)
+
+
+_READERS[_PopupMultilineArrayEdit] = lambda w: w.parsed()
+_CHANGE_SIGNALS[_PopupMultilineArrayEdit] = 'textChanged'
+
+
+class _FileArrayWidget(QtWidgets.QWidget):
+    """整数组占位控件：路径 label + "..." 选择按钮。
+
+    "value" 始终是文件路径字符串；文件内容不会进入配置导出，仅在内存里
+    做长度/类型校验，结果以后缀（✓/✗）形式追加显示在 label 上。
+
+    支持的文件格式（用 ``re.split(r'[,\\s]+', text)`` 分词，再过滤空 token）：
+      - 单行逗号分隔：``1,2,3,4,5,6,7,8``
+      - 多行逗号分隔（行尾逗号可有可无）：``1,2,3,4,\\n5,6,7,8``
+      - 每行一个值：``1\\n2\\n3\\n4``
+
+    长度校验策略：
+      - got == expected            → ✓
+      - got <  expected            → ✓ 提示将由下游补默认值
+      - got >  expected            → ✗ （多余数据无处可去，让用户决定）
+    """
+
+    pathChanged = QtCore.Signal(str)
+
+    _PLACEHOLDER_QSS = 'QLabel{color:#888;}'
+    _OK_COLOR = '#2a7d2a'
+    _ERR_COLOR = '#c33'
+
+    def __init__(self, f: ArrayField, value: Any,
+                 parent: QtWidgets.QWidget = None) -> None:
+        super().__init__(parent)
+        self._field = f
+        self._path = str(value) if isinstance(value, str) else ''
+
+        self._label = QtWidgets.QLabel()
+        self._label.setTextInteractionFlags(QtCore.Qt.TextSelectableByMouse)
+
+        self._btn = QtWidgets.QPushButton('...')
+        self._btn.setFixedWidth(28)
+        self._btn.clicked.connect(self._on_browse)
+
+        lay = QtWidgets.QHBoxLayout(self)
+        lay.setContentsMargins(0, 0, 0, 0)
+        lay.setSpacing(4)
+        lay.addWidget(self._label, 1)
+        lay.addWidget(self._btn)
+
+        self._refresh_label()
+
+    # --- 公共接口 --------------------------------------------------------- #
+
+    def value(self) -> str:
+        return self._path
+
+    # --- 私有实现 --------------------------------------------------------- #
+
+    def _on_browse(self) -> None:
+        path, _ = QtWidgets.QFileDialog.getOpenFileName(
+            self, f'Select file for {self._field.name}', self._path or '',
+            'Text files (*.txt);;All files (*.*)')
+        if path:
+            self._path = path
+            self._refresh_label()
+            self.pathChanged.emit(path)
+
+    def _refresh_label(self) -> None:
+        """根据当前路径刷新 label 文本/颜色/tooltip。仅内存视图，不改导出值。"""
+        if not self._path:
+            self._label.setText('(no file)')
+            self._label.setStyleSheet(self._PLACEHOLDER_QSS)
+            self._label.setToolTip('')
+            return
+
+        ok, info = self._validate_file(self._path)
+        mark = '✓' if ok else '✗'
+        color = self._OK_COLOR if ok else self._ERR_COLOR
+        path_html = _html_escape(self._path)
+        info_html = _html_escape(f'{mark} {info}')
+        self._label.setText(
+            f'{path_html}  <span style="color:{color};">{info_html}</span>')
+        self._label.setStyleSheet('')
+        self._label.setToolTip(self._path)
+
+    def _validate_file(self, path: str) -> Tuple[bool, str]:
+        """读取并分词，返回 (是否合法, 状态描述)。"""
+        try:
+            with open(path, 'r', encoding='utf-8') as fp:
+                text = fp.read()
+        except OSError as e:
+            return False, f'read error: {e.strerror or e}'
+
+        tokens = [t for t in re.split(r'[,\s]+', text) if t]
+
+        # 元素类型决定 cast；非 scalar 元素退化为只校验数量。
+        elem = self._field.element
+        ui = elem.ui_type if isinstance(elem, ScalarField) else None
+        if ui == 'int':
+            cast, type_name = int, 'ints'
+        elif ui == 'float':
+            cast, type_name = float, 'floats'
+        else:
+            cast, type_name = None, 'tokens'
+
+        if cast is not None:
+            for i, tok in enumerate(tokens):
+                try:
+                    cast(tok)
+                except ValueError:
+                    return False, f'token #{i + 1} {tok!r} is not {cast.__name__}'
+
+        expected = self._field.count
+        shape = self._field.meta.get('shape')
+        shape_str = ('x'.join(str(d) for d in shape)
+                     if isinstance(shape, list) else str(expected))
+        got = len(tokens)
+        if expected and got > expected:
+            return False, f'expected {shape_str} ({expected}) {type_name}, got {got}'
+        if expected and got < expected:
+            return True, (f'{got}/{expected} {type_name}, '
+                          f'missing {expected - got} (will fill default)')
+        return True, f'{shape_str} {type_name}'
+
+
+def _html_escape(s: str) -> str:
+    """最小 HTML 转义，足以让 QLabel 富文本不把路径里的 & < > 当成标签。"""
+    return s.replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;')
+
+
+_READERS[_FileArrayWidget] = lambda w: w.value()
+_CHANGE_SIGNALS[_FileArrayWidget] = 'pathChanged'
+
+
+def _build_int(f: ScalarField, value: Any) -> QtWidgets.QWidget:
+    mn, mx, sp = f.meta.get('min'), f.meta.get('max'), f.meta.get('step')
+    ui = f.meta.get('widget')
+    if ui == 'slider' and mn is not None and mx is not None:
+        w = _LabeledSliderHolder(int(mn), int(mx))
+    elif ui == 'dial' and mn is not None and mx is not None:
+        w = _DialSpinBox(int(mn), int(mx))
+    else:
+        w = QtWidgets.QSpinBox()
+        w.setRange(_as_int(mn, -2147483648), _as_int(mx, 2147483647))
+    w.setSingleStep(_as_int(sp, 1))
+    w.setValue(_safe_int(value))
+    return w
+
+
+def _build_float(f: ScalarField, value: Any) -> QtWidgets.QDoubleSpinBox:
+    mn, mx, sp = f.meta.get('min'), f.meta.get('max'), f.meta.get('step')
+    w = QtWidgets.QDoubleSpinBox()
+    # QDoubleSpinBox rounds its value to `decimals` places, so too few digits
+    # silently truncates the stored value (e.g. 0.0001 -> 0.0). Honour an
+    # explicit `decimals` meta, else infer enough digits from `step`, else a
+    # generous default that does not lose typical config precision.
+    w.setDecimals(_float_decimals(f.meta.get('decimals'), sp))
+    w.setRange(_as_float(mn, -1e9), _as_float(mx, 1e9))
+    w.setSingleStep(_as_float(sp, 0.1))
+    w.setValue(_safe_float(value))
+    return w
+
+
+def _build_text(value: Any, f: ScalarField = None) -> QtWidgets.QLineEdit:
+    w = QtWidgets.QLineEdit()
+    w.setText('' if value is None else str(value))
+    if f is not None:
+        maxlen = f.meta.get('maxlen')
+        if isinstance(maxlen, int) and maxlen > 0:
+            w.setMaxLength(maxlen)
+    return w
+
+
+def _build_array_value(f: ArrayField, value: Any) -> QtWidgets.QWidget:
+    """把整个数组渲染为单行 leaf 控件。
+
+    三种模式（行高一致都是单行）：
+      widget=file       -> _FileArrayWidget         （路径 + Browse 按钮）
+      widget=multiline  -> _PopupMultilineArrayEdit （单行外壳，聚焦弹多行编辑器）
+      默认              -> _ScalarArrayLineEdit     （逗号分隔单行）
+
+    多维 count（meta.shape）不再决定控件类型 —— 它仅在 widget=multiline
+    时被弹出面板用于折行显示。仅对 leaf 数组（scalar/enum 元素）有效；
+    struct 数组由调用方分派给 table/tree。
+    """
+    wkind = f.meta.get('widget')
+    if wkind == 'file':
+        return _FileArrayWidget(f, value)
+    if wkind == 'multiline':
+        return _PopupMultilineArrayEdit(f, value)
+    return _ScalarArrayLineEdit(f, value)
+
+
+def _safe_int(v: Any) -> int:
+    try:
+        return int(v)
+    except Exception:
+        return 0
+
+
+def _safe_float(v: Any) -> float:
+    try:
+        return float(v)
+    except Exception:
+        return 0.0
+
+
+def _as_int(v: Any, default: int) -> int:
+    return int(v) if v is not None else default
+
+
+def _as_float(v: Any, default: float) -> float:
+    return float(v) if v is not None else default
+
+
+_DEFAULT_FLOAT_DECIMALS = 6
+
+
+def _float_decimals(decimals: Any, step: Any) -> int:
+    """Decide how many decimal places a QDoubleSpinBox should keep.
+
+    Priority: explicit `decimals` meta -> digits implied by `step` -> default.
+    Capped at 10 to stay within QDoubleSpinBox's sane range.
+    """
+    if isinstance(decimals, int) and decimals >= 0:
+        return min(decimals, 10)
+    if step is not None:
+        try:
+            exp = Decimal(str(float(step))).normalize().as_tuple().exponent
+        except (TypeError, ValueError, InvalidOperation):
+            exp = 0
+        if isinstance(exp, int) and exp < 0:
+            return min(max(-exp, _DEFAULT_FLOAT_DECIMALS), 10)
+    return _DEFAULT_FLOAT_DECIMALS
+
+
+# --------------------------------------------------------------------------- #
+# Misc helpers
+# --------------------------------------------------------------------------- #
+
+def decorate_label(name: str, meta: Dict[str, Any]) -> str:
+    """Append unit suffix to a field label, e.g. `gain (dB)`."""
+    unit = meta.get('unit')
+    return f'{name} ({unit})' if unit else name
+
+
+# --------------------------------------------------------------------------- #
+# WhenBinder: declarative enable/disable based on `when` metadata
+# --------------------------------------------------------------------------- #
+
+class WhenBinder:
+    """Collect (dotted_name, widget, when-dict); after `apply()`, dependent
+    widgets are auto-enabled/disabled when their dependencies change.
+
+    Usage:
+        binder = WhenBinder()
+        binder.register('foo.bar', w, field.meta)   # repeat for each leaf
+        binder.apply()                              # wires up signals
+    """
+
+    def __init__(self) -> None:
+        # (dotted, widget, when_dict_or_None)
+        self._rows: List[Tuple[str, QtWidgets.QWidget, Any]] = []
+
+    def register(self, dotted: str, w: QtWidgets.QWidget, meta: Dict[str, Any]) -> None:
+        when = meta.get('when') if isinstance(meta, dict) else None
+        self._rows.append((dotted, w, when if isinstance(when, dict) else None))
+
+    def widget_map(self) -> Dict[str, QtWidgets.QWidget]:
+        """Return a {dotted_name: widget} view of every registered leaf.
+
+        Built from the same `_rows` used for when-binding, so it covers exactly
+        the editable leaves the renderers created. Consumed by
+        `collect_values()` to read the current UI state back into a nested
+        dict/list structure (the entry point for UI -> JSON/.c/.bin export).
+        """
+        return {dotted: w for dotted, w, _ in self._rows}
+
+    def apply(self) -> None:
+        by_name = {n: w for n, w, _ in self._rows}
+        for _name, w, cond in self._rows:
+            if cond:
+                self._wire(w, cond, by_name)
+
+    def _wire(self, target: QtWidgets.QWidget, cond: Dict[str, Any],
+              by_name: Dict[str, QtWidgets.QWidget]) -> None:
+        def evaluate() -> bool:
+            for dep, expected in cond.items():
+                dep_w = by_name.get(dep)
+                if dep_w is None:
+                    return True
+                if WidgetFactory.read(dep_w) != expected:
+                    return False
+            return True
+
+        def update(_=None) -> None:
+            target.setEnabled(evaluate())
+
+        update()
+        for dep in cond.keys():
+            dep_w = by_name.get(dep)
+            if dep_w is None:
+                continue
+            sig_name = _lookup(_CHANGE_SIGNALS, dep_w)
+            if sig_name:
+                getattr(dep_w, sig_name).connect(update)
+
+
+# --------------------------------------------------------------------------- #
+# collect_values: read the live UI state back into a nested dict/list
+# --------------------------------------------------------------------------- #
+
+def collect_values(root: Field,
+                   widget_map: Dict[str, QtWidgets.QWidget]) -> Any:
+    """Walk the schema tree and read every leaf widget into a nested value.
+
+    `widget_map` is the {dotted_name: widget} produced by
+    `WhenBinder.widget_map()`. The dotted names are generated here exactly as
+    the renderers generate them, so the two stay in lock-step:
+
+        struct child         -> '<prefix><name>'
+        scalar/enum array    -> one widget under the array's own dotted name,
+                                whose reader already returns a list
+        struct/nested array  -> per-element '<dotted>[i]...' entries
+
+    Returns:
+        StructField -> dict of child-name -> value
+        ArrayField  -> list of length count
+        leaf        -> the scalar/enum value (or list, for whole-array editors)
+
+    Leaves with no widget in the map (e.g. a struct array rendered with a
+    '<nested>' placeholder) fall back to the field's default so the shape of
+    the returned structure always matches the schema.
+    """
+    return _collect_field(root, '', widget_map)
+
+
+def _collect_field(f: Field, dotted: str,
+                   widget_map: Dict[str, QtWidgets.QWidget]) -> Any:
+    if isinstance(f, ArrayField):
+        # Scalar/enum arrays (and file/multiline variants) are a single
+        # whole-array widget; its reader returns the full list directly.
+        if not isinstance(f.element, StructField):
+            w = widget_map.get(dotted)
+            if w is not None:
+                val = WidgetFactory.read(w)
+                return val if val is not None else _array_default(f)
+            return _array_default(f)
+        # Struct array: one entry per element.
+        return [
+            _collect_field(f.element, f'{dotted}[{i}]', widget_map)
+            for i in range(f.count)
+        ]
+
+    if isinstance(f, StructField):
+        out: Dict[str, Any] = {}
+        prefix = f'{dotted}.' if dotted else ''
+        for child in f.children:
+            out[child.name] = _collect_field(
+                child, f'{prefix}{child.name}', widget_map)
+        return out
+
+    # leaf scalar / enum
+    w = widget_map.get(dotted)
+    if w is not None:
+        return WidgetFactory.read(w)
+    return f.default
+
+
+def _array_default(f: ArrayField) -> List[Any]:
+    elem = f.element
+    base = elem.default if elem is not None else None
+    return [base for _ in range(f.count)]