struct2ui 0.1.0__py3-none-any.whl

struct2ui/ui/__init__.py

@@ -0,0 +1,36 @@
+"""UI package: schema → Qt widget rendering.
+
+Layered design:
+    widgets.py   - leaf editor factory (WidgetFactory) + when-binding (WhenBinder)
+    tables.py    - QTableWidget rendering for arrays (style + cell wrapping)
+    renderers.py - FormRenderer / TreeRenderer + dispatcher (pick_renderer)
+
+Public API (stable; safe to import from outside):
+    pick_renderer, FormRenderer, TreeRenderer
+    WidgetFactory, WhenBinder
+    build_array_table
+
+Internal helpers (prefixed with _) are not part of the public API.
+"""
+
+from .widgets import (
+    WidgetFactory, WhenBinder, decorate_label, collect_values,
+)
+from .tables import build_array_table
+from .renderers import (
+    FormRenderer, TreeRenderer, pick_renderer, make_collapsible,
+    collect_view_values,
+)
+
+__all__ = [
+    'WidgetFactory',
+    'WhenBinder',
+    'decorate_label',
+    'collect_values',
+    'build_array_table',
+    'FormRenderer',
+    'TreeRenderer',
+    'pick_renderer',
+    'make_collapsible',
+    'collect_view_values',
+]

struct2ui/ui/renderers.py

@@ -0,0 +1,304 @@
+"""Top-level renderers: turn a StructField tree into a single QWidget.
+
+Two renderers are provided:
+
+  FormRenderer   - flat QFormLayout, suitable for shallow non-nested structs.
+                   Nested groups use a QToolButton ▼/▶ collapser.
+  TreeRenderer   - QTreeWidget with native expand/collapse; suitable for any
+                   schema, including deeply nested structs and struct arrays.
+
+Dispatch:
+  pick_renderer() returns TreeRenderer by default. FormRenderer is opt-in via
+  speech.json: `"render": "form"` on the section spec.
+
+Adding a new renderer:
+  1. Subclass nothing — just provide a `render(root, values) -> QWidget` method.
+  2. Extend pick_renderer() to return it under some condition (override string,
+     schema shape, etc).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from Qt import QtCore, QtWidgets
+
+from ..schema import (
+    Field, ScalarField, EnumField, StructField, ArrayField,
+    array_dims_suffix,
+)
+
+from .widgets import (
+    WidgetFactory, WhenBinder, decorate_label, collect_values,
+)
+from .tables import build_array_table, is_flat_struct_array
+
+
+# --------------------------------------------------------------------------- #
+# Value read-back: let callers pull the live UI state back out of a rendered
+# view as a nested dict/list (entry point for UI -> JSON/.c/.bin export).
+# --------------------------------------------------------------------------- #
+
+_COLLECTOR_ATTR = '_params_collector'
+
+
+def _attach_collector(widget: QtWidgets.QWidget, root: StructField,
+                      binder: WhenBinder) -> None:
+    """Stash a zero-arg callable on the rendered widget that, when called,
+    reads the current editor values into a nested dict via collect_values()."""
+    setattr(widget, _COLLECTOR_ATTR,
+            lambda: collect_values(root, binder.widget_map()))
+
+
+def collect_view_values(widget: QtWidgets.QWidget) -> Optional[Dict[str, Any]]:
+    """Return the live values of a rendered view, or None if it carries no
+    collector (e.g. an error/summary panel rather than a parameter form)."""
+    collector = getattr(widget, _COLLECTOR_ATTR, None)
+    return collector() if collector is not None else None
+
+
+# --------------------------------------------------------------------------- #
+# Collapsible toolbutton (used by FormRenderer)
+# --------------------------------------------------------------------------- #
+
+def make_collapsible(title: str) -> tuple[QtWidgets.QWidget, QtWidgets.QFormLayout]:
+    """Return (wrapper_widget, inner_form_layout). Click the title to collapse."""
+    wrapper = QtWidgets.QWidget()
+    v = QtWidgets.QVBoxLayout(wrapper)
+    v.setContentsMargins(0, 0, 0, 0)
+    v.setSpacing(2)
+    btn = QtWidgets.QToolButton()
+    btn.setText('\u25bc  ' + title)
+    btn.setCheckable(True)
+    btn.setChecked(True)
+    btn.setAutoRaise(True)
+    btn.setToolButtonStyle(QtCore.Qt.ToolButtonTextOnly)
+    btn.setStyleSheet('QToolButton{font-weight:bold; text-align:left;}')
+    content = QtWidgets.QFrame()
+    content.setFrameShape(QtWidgets.QFrame.StyledPanel)
+    inner = QtWidgets.QFormLayout(content)
+    inner.setLabelAlignment(QtCore.Qt.AlignLeft)
+    inner.setContentsMargins(12, 4, 4, 4)
+    v.addWidget(btn)
+    v.addWidget(content)
+
+    def _on_toggled(checked: bool, b=btn, c=content, t=title) -> None:
+        b.setText(('\u25bc  ' if checked else '\u25b6  ') + t)
+        c.setVisible(checked)
+
+    btn.toggled.connect(_on_toggled)
+    return wrapper, inner
+
+
+# --------------------------------------------------------------------------- #
+# FormRenderer
+# --------------------------------------------------------------------------- #
+
+class FormRenderer:
+    """Render a StructField via QFormLayout. Best for shallow/flat data."""
+
+    def render(self, root: StructField, values: Dict[str, Any]) -> QtWidgets.QWidget:
+        container = QtWidgets.QWidget()
+        layout = QtWidgets.QFormLayout(container)
+        layout.setLabelAlignment(QtCore.Qt.AlignLeft)
+        binder = WhenBinder()
+        self._render_struct(layout, root, values, prefix='', binder=binder)
+        binder.apply()
+        _attach_collector(container, root, binder)
+        return container
+
+    def _render_struct(self, layout: QtWidgets.QFormLayout, node: StructField,
+                       values: Dict[str, Any], prefix: str, binder: WhenBinder) -> None:
+        for child in node.children:
+            dotted = f'{prefix}{child.name}'
+            sub_val = values.get(child.name) if isinstance(values, dict) else None
+            self._render_field(layout, child, sub_val, dotted, binder)
+
+    def _render_field(self, layout: QtWidgets.QFormLayout, f: Field,
+                      value: Any, dotted: str, binder: WhenBinder) -> None:
+        if isinstance(f, ArrayField):
+            if not isinstance(f.element, StructField):
+                self._add_leaf_row(layout, f, value, dotted, binder,
+                                   label_text=decorate_label(f.name, f.meta))
+                return
+            wrapper, inner = make_collapsible(f'{f.name}{array_dims_suffix(f)}')
+            tbl = build_array_table(f, value, dotted, binder)
+            inner.addRow(tbl)
+            layout.addRow(wrapper)
+            return
+        if isinstance(f, StructField):
+            wrapper, inner = make_collapsible(f.name)
+            self._render_struct(inner, f, value or {}, prefix=f'{dotted}.', binder=binder)
+            layout.addRow(wrapper)
+            return
+        # leaf
+        self._add_leaf_row(layout, f, value, dotted, binder,
+                           label_text=decorate_label(f.name, f.meta))
+
+    @staticmethod
+    def _add_leaf_row(layout: QtWidgets.QFormLayout, f: Field, value: Any,
+                      dotted: str, binder: WhenBinder, label_text: str) -> None:
+        """One QFormLayout row: label + editor widget + tooltip + binder."""
+        label = QtWidgets.QLabel(label_text)
+        w = WidgetFactory.build(f, value)
+        tip = f.meta.get('tip')
+        if tip:
+            w.setToolTip(str(tip))
+            label.setToolTip(str(tip))
+        layout.addRow(label, w)
+        binder.register(dotted, w, f.meta)
+
+
+# --------------------------------------------------------------------------- #
+# TreeRenderer
+# --------------------------------------------------------------------------- #
+
+class TreeRenderer:
+    """Render a StructField via QTreeWidget.
+
+    Layout:
+        col 0 = field name (with native ▶/▼ expand arrow on parent rows)
+        col 1 = value editor widget (empty for parent rows; QTableWidget for
+                flat struct arrays)
+        col 2 = unit (read-only)
+    """
+
+    HEADERS = ('Name', 'Value', 'Unit')
+
+    def render(self, root: StructField, values: Dict[str, Any]) -> QtWidgets.QWidget:
+        tree = QtWidgets.QTreeWidget()
+        tree.setColumnCount(len(self.HEADERS))
+        tree.setHeaderLabels(self.HEADERS)
+        tree.setAlternatingRowColors(True)
+        tree.setUniformRowHeights(False)
+        tree.header().setStretchLastSection(False)
+        tree.header().setSectionResizeMode(0, QtWidgets.QHeaderView.ResizeToContents)
+        tree.header().setSectionResizeMode(1, QtWidgets.QHeaderView.Stretch)
+        tree.header().setSectionResizeMode(2, QtWidgets.QHeaderView.ResizeToContents)
+
+        binder = WhenBinder()
+        self._populate_struct(tree.invisibleRootItem(), root, values, prefix='',
+                              tree=tree, binder=binder)
+        tree.expandAll()
+        binder.apply()
+        _attach_collector(tree, root, binder)
+        return tree
+
+    def _populate_struct(self, parent_item: QtWidgets.QTreeWidgetItem,
+                         node: StructField, values: Dict[str, Any], prefix: str,
+                         tree: QtWidgets.QTreeWidget, binder: WhenBinder) -> None:
+        for child in node.children:
+            dotted = f'{prefix}{child.name}'
+            sub_val = values.get(child.name) if isinstance(values, dict) else None
+            self._add_field(parent_item, child, sub_val, dotted, tree, binder)
+
+    def _add_field(self, parent_item: QtWidgets.QTreeWidgetItem, f: Field,
+                   value: Any, dotted: str, tree: QtWidgets.QTreeWidget,
+                   binder: WhenBinder) -> None:
+        if isinstance(f, ArrayField):
+            self._add_array(parent_item, f, value, dotted, tree, binder)
+            return
+        if isinstance(f, StructField):
+            row = QtWidgets.QTreeWidgetItem(parent_item, [f.name, '', ''])
+            self._populate_struct(row, f, value or {}, prefix=f'{dotted}.',
+                                  tree=tree, binder=binder)
+            return
+        # leaf scalar/enum
+        self._make_leaf_row(parent_item, tree, binder,
+                            label=f.name, meta=f.meta, dotted=dotted,
+                            widget=WidgetFactory.build(
+                                f, value if value is not None else f.default))
+
+    def _add_array(self, parent_item: QtWidgets.QTreeWidgetItem, f: ArrayField,
+                   value: Any, dotted: str, tree: QtWidgets.QTreeWidget,
+                   binder: WhenBinder) -> None:
+        # Scalar/enum array -> render the whole array as one leaf widget
+        # (default: comma-separated QLineEdit; widget=file -> path + Browse).
+        if not isinstance(f.element, StructField):
+            self._make_leaf_row(parent_item, tree, binder,
+                                label=f'{f.name}{array_dims_suffix(f)}',
+                                meta=f.meta,
+                                dotted=dotted,
+                                widget=WidgetFactory.build(f, value))
+            return
+
+        row = QtWidgets.QTreeWidgetItem(
+            parent_item, [f'{f.name}{array_dims_suffix(f)}', '', ''])
+
+        if self._should_render_as_table(f):
+            table = build_array_table(f, value if isinstance(value, list) else None,
+                                      dotted, binder)
+            holder = QtWidgets.QTreeWidgetItem(row, [''])
+            holder.setFirstColumnSpanned(True)
+            tree.setItemWidget(holder, 0, table)
+            # _polish_table locks maximumHeight to the exact pixel-perfect
+            # height (header + rows + border). Use it directly so the tree
+            # row reserves no extra space below the table.
+            holder.setSizeHint(0, QtCore.QSize(0, table.maximumHeight()))
+            return
+
+        # Otherwise expand each element as a tree branch.
+        elem = f.element
+        for i in range(f.count):
+            elem_val = value[i] if isinstance(value, list) and i < len(value) else None
+            idx_label = f'[{i}]'
+            if isinstance(elem, StructField):
+                elem_item = QtWidgets.QTreeWidgetItem(row, [idx_label, '', ''])
+                self._populate_struct(elem_item, elem, elem_val or {},
+                                      prefix=f'{dotted}[{i}].',
+                                      tree=tree, binder=binder)
+            elif isinstance(elem, ArrayField):
+                self._add_field(row, elem, elem_val, f'{dotted}[{i}]', tree, binder)
+            else:
+                self._make_leaf_row(row, tree, binder,
+                                    label=idx_label, meta=elem.meta,
+                                    dotted=f'{dotted}[{i}]',
+                                    widget=WidgetFactory.build(
+                                        elem,
+                                        elem_val if elem_val is not None
+                                        else elem.default))
+
+    @staticmethod
+    def _should_render_as_table(f: ArrayField) -> bool:
+        """Decide table-vs-tree for a struct array.
+
+        - meta.render='table' forces table iff the array is flat
+        - meta.render='tree'  forces tree
+        - otherwise auto: table iff flat
+        """
+        render = f.meta.get('render')
+        if render == 'tree':
+            return False
+        if render == 'table':
+            return is_flat_struct_array(f)
+        return is_flat_struct_array(f)
+
+    @staticmethod
+    def _make_leaf_row(parent_item: QtWidgets.QTreeWidgetItem,
+                       tree: QtWidgets.QTreeWidget, binder: WhenBinder,
+                       label: str, meta: Dict[str, Any], dotted: str,
+                       widget: QtWidgets.QWidget) -> None:
+        """One tree row hosting a single editor widget in column 1."""
+        unit = meta.get('unit', '') or ''
+        row = QtWidgets.QTreeWidgetItem(parent_item, [label, '', unit])
+        tip = meta.get('tip')
+        if tip:
+            row.setToolTip(0, str(tip))
+            row.setToolTip(1, str(tip))
+        tree.setItemWidget(row, 1, widget)
+        binder.register(dotted, widget, meta)
+
+
+# --------------------------------------------------------------------------- #
+# Dispatcher
+# --------------------------------------------------------------------------- #
+
+def pick_renderer(root: StructField, override: Optional[str] = None):
+    """Return a renderer instance.
+
+    Default: TreeRenderer (visually consistent across flat and nested data).
+    Opt-in to FormRenderer with `"render": "form"` in speech.json.
+    """
+    if override == 'form':
+        return FormRenderer()
+    return TreeRenderer()

struct2ui/ui/tables.py

@@ -0,0 +1,207 @@
+"""Render an ArrayField as a QTableWidget.
+
+Layout policy (single source of truth, encoded in two tuples):
+
+    NON_KEYBOARD_TYPES  - controls that should auto-fit column to their content
+                          (CheckBox, ComboBox). Other columns share remaining
+                          width via Stretch.
+
+    CENTERED_TYPES      - controls that look odd when stretched (CheckBox).
+                          They are wrapped in a centering container so the
+                          control itself keeps its sizeHint width.
+
+Adding a new editor type:
+  - Want auto-fit column?         add it to NON_KEYBOARD_TYPES
+  - Want it centered, not filled? add it to CENTERED_TYPES
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional, TYPE_CHECKING
+
+from Qt import QtCore, QtWidgets
+
+from ..schema import ArrayField, StructField
+from .widgets import WidgetFactory
+
+if TYPE_CHECKING:
+    from .widgets import WhenBinder
+
+
+# --------------------------------------------------------------------------- #
+# Style policies (extension points)
+# --------------------------------------------------------------------------- #
+
+# Column-width auto-fit: ResizeToContents applied to columns whose first cell
+# (after unwrapping any centering container) is one of these widget types.
+NON_KEYBOARD_TYPES = (QtWidgets.QCheckBox, QtWidgets.QComboBox)
+
+# Cells whose widget should NOT stretch to fill — instead centered in cell.
+CENTERED_TYPES = (QtWidgets.QCheckBox,)
+
+ROW_HEIGHT = 26
+HEADER_BORDER_PAD = 4
+
+
+# --------------------------------------------------------------------------- #
+# Public API
+# --------------------------------------------------------------------------- #
+
+def build_array_table(arr: ArrayField, values: Optional[List[Any]],
+                      dotted: str, binder: 'WhenBinder') -> QtWidgets.QTableWidget:
+    """Render `arr` (ArrayField) as a QTableWidget.
+
+    - flat struct array      -> multi-column (one column per struct child)
+    - scalar/enum array      -> single column
+    - elements that are themselves struct/array -> '<nested>' placeholder
+      (caller should detect via `is_flat_struct_array` and avoid this path)
+
+    Used by both FormRenderer and TreeRenderer.
+    """
+    elem = arr.element
+    if not isinstance(elem, StructField):
+        return _build_scalar_array(arr, values, dotted, binder)
+    return _build_struct_array(arr, values, dotted, binder)
+
+
+def is_flat_struct_array(arr: ArrayField) -> bool:
+    """True iff `arr` is a single-layer struct array (every struct child is a leaf).
+
+    This is the precondition for `build_array_table` producing a clean
+    multi-column table.
+    """
+    elem = arr.element
+    if not isinstance(elem, StructField):
+        return False
+    return all(not isinstance(c, (StructField, ArrayField)) for c in elem.children)
+
+
+# --------------------------------------------------------------------------- #
+# Builders
+# --------------------------------------------------------------------------- #
+
+def _build_scalar_array(arr: ArrayField, values: Optional[List[Any]],
+                        dotted: str, binder: 'WhenBinder') -> QtWidgets.QTableWidget:
+    elem = arr.element
+    tbl = QtWidgets.QTableWidget(arr.count, 1)
+    tbl.setHorizontalHeaderLabels([elem.name if elem else 'value'])
+    for i in range(arr.count):
+        v = values[i] if values and i < len(values) else (
+            elem.default if elem and elem.default is not None else None)
+        cell = WidgetFactory.build(elem, v)
+        _put_cell(tbl, i, 0, cell)
+        binder.register(f'{dotted}[{i}]', cell, elem.meta if elem else {})
+    _polish_table(tbl)
+    return tbl
+
+
+def _build_struct_array(arr: ArrayField, values: Optional[List[Any]],
+                        dotted: str, binder: 'WhenBinder') -> QtWidgets.QTableWidget:
+    elem: StructField = arr.element  # type: ignore[assignment]
+    cols = [c.name for c in elem.children]
+    tbl = QtWidgets.QTableWidget(arr.count, len(cols))
+    tbl.setHorizontalHeaderLabels(cols)
+    for i in range(arr.count):
+        row_val = values[i] if values and i < len(values) else {}
+        if not isinstance(row_val, dict):
+            row_val = {}
+        for col, child in enumerate(elem.children):
+            if isinstance(child, (StructField, ArrayField)):
+                # Caller should have used is_flat_struct_array() to avoid this.
+                tbl.setCellWidget(i, col, QtWidgets.QLabel('<nested>'))
+                continue
+            cv = row_val.get(child.name, child.default)
+            cell = WidgetFactory.build(child, cv)
+            _put_cell(tbl, i, col, cell)
+            binder.register(f'{dotted}[{i}].{child.name}', cell, child.meta)
+    _polish_table(tbl)
+    return tbl
+
+
+# --------------------------------------------------------------------------- #
+# Cell wrapping (centering policy)
+# --------------------------------------------------------------------------- #
+
+def _put_cell(tbl: QtWidgets.QTableWidget, row: int, col: int,
+              w: QtWidgets.QWidget) -> None:
+    """Place `w` into a cell, applying centering policy."""
+    if isinstance(w, CENTERED_TYPES):
+        tbl.setCellWidget(row, col, _wrap_centered(w))
+    else:
+        tbl.setCellWidget(row, col, w)
+
+
+def _wrap_centered(w: QtWidgets.QWidget) -> QtWidgets.QWidget:
+    """Wrap `w` in a horizontal layout with stretch on both sides.
+
+    Special case: text-less QCheckBox has a tiny sizeHint (indicator width
+    only), making it look clipped at the right edge. We bump its minimumWidth
+    using QStyle.PM_IndicatorWidth so it stays comfortably visible.
+    """
+    if isinstance(w, QtWidgets.QCheckBox) and not w.text():
+        ind_w = w.style().pixelMetric(QtWidgets.QStyle.PM_IndicatorWidth, None, w)
+        w.setMinimumWidth(ind_w + 12)
+
+    holder = QtWidgets.QWidget()
+    lay = QtWidgets.QHBoxLayout(holder)
+    lay.setContentsMargins(4, 0, 4, 0)
+    lay.setSpacing(0)
+    w.setSizePolicy(QtWidgets.QSizePolicy.Fixed, QtWidgets.QSizePolicy.Preferred)
+    lay.addStretch(1)
+    lay.addWidget(w)
+    lay.addStretch(1)
+    return holder
+
+
+# --------------------------------------------------------------------------- #
+# Table polish (column-width strategy + visual frame)
+# --------------------------------------------------------------------------- #
+
+def _polish_table(tbl: QtWidgets.QTableWidget) -> None:
+    """Apply uniform appearance and column-width strategy to a fresh table."""
+    tbl.verticalHeader().setVisible(False)
+    tbl.verticalHeader().setDefaultSectionSize(ROW_HEIGHT)
+    tbl.setSelectionMode(QtWidgets.QAbstractItemView.NoSelection)
+    tbl.setEditTriggers(QtWidgets.QAbstractItemView.NoEditTriggers)
+
+    # Force an explicit 1px solid frame: some themes draw the default
+    # StyledPanel frame too faintly, making the leftmost vertical edge
+    # appear missing.
+    tbl.setFrameShape(QtWidgets.QFrame.Box)
+    tbl.setFrameShadow(QtWidgets.QFrame.Plain)
+    tbl.setLineWidth(1)
+    tbl.setShowGrid(True)
+    tbl.setGridStyle(QtCore.Qt.SolidLine)
+
+    header = tbl.horizontalHeader()
+    header.setStretchLastSection(False)
+    for col in range(tbl.columnCount()):
+        if _column_is_keyboard(tbl, col):
+            header.setSectionResizeMode(col, QtWidgets.QHeaderView.Stretch)
+        else:
+            header.setSectionResizeMode(col, QtWidgets.QHeaderView.ResizeToContents)
+
+    # Lock height so the table never shows an internal vertical scrollbar.
+    h = header.height() + tbl.rowCount() * ROW_HEIGHT + HEADER_BORDER_PAD
+    tbl.setMinimumHeight(h)
+    tbl.setMaximumHeight(h)
+
+
+def _column_is_keyboard(tbl: QtWidgets.QTableWidget, col: int) -> bool:
+    """True if the first cell in `col` looks like a keyboard-input control.
+
+    Look-up logic:
+      - ComboBox cell        -> holder is the ComboBox itself  (non-keyboard)
+      - CheckBox cell        -> holder is a centering container; descend into
+                                its children to find the CheckBox  (non-keyboard)
+      - SpinBox/LineEdit/... -> keyboard column (gets Stretch)
+    """
+    holder = tbl.cellWidget(0, col)
+    if holder is None:
+        return True  # be safe: stretch
+    if isinstance(holder, NON_KEYBOARD_TYPES):
+        return False
+    for ch in holder.findChildren(QtWidgets.QWidget):
+        if isinstance(ch, NON_KEYBOARD_TYPES):
+            return False
+    return True