View¶

class ActionButton(QtW.QPushButton):
    """A ``QPushButton`` that carries ``Action`` metadata.

    Automatically updates its label based on toggle state using the action's
    ``toggle_states`` attribute.

    Parameters
    ----------
    action : Action
        The action to associate with this button.
    parent : QtWidgets.QWidget | None, optional
        The parent widget. Default is ``None``.

    Attributes
    ----------
    action : Action
        The action associated with this button.
    """

    def __init__(self, action: Action, parent: QtW.QWidget | None = None) -> None:
        self.name_capital = action.name.capitalize()
        super().__init__(self.name_capital, parent)
        self.action = action

        if action.description:
            self.setToolTip(action.description)

        if action.togglable:
            self.setCheckable(True)
            self.toggled.connect(self._update_text)
            self._update_text(False)

    def _update_text(self, checked: bool) -> None:
        """Update button text based on toggle state."""
        state_text = (
            self.action.toggle_states[1] if checked else self.action.toggle_states[0]
        )
        self.setText(f"{self.name_capital} ({state_text})")

class PlanInfoDialog(QtW.QDialog):
    """Dialog to provide information to the user.

    Parameters
    ----------
    title : str
        The title of the dialog window.
    text : str
        The text to display in the text edit area (rendered as Markdown).
    parent : QtWidgets.QWidget | None, optional
        The parent widget, by default ``None``.
    """

    def __init__(
        self,
        title: str,
        text: str,
        parent: QtW.QWidget | None = None,
    ) -> None:
        super().__init__(parent)

        self.setWindowTitle(title)
        self.resize(500, 300)

        layout = QtW.QVBoxLayout(self)

        self.text_edit = QtW.QTextEdit()
        self.text_edit.setReadOnly(True)
        self.text_edit.setMarkdown(text)
        layout.addWidget(self.text_edit)

        self.ok_button = QtW.QPushButton("OK")
        self.ok_button.setDefault(True)
        self.ok_button.clicked.connect(self.accept)

        button_layout = QtW.QHBoxLayout()
        button_layout.addStretch()
        button_layout.addWidget(self.ok_button)
        layout.addLayout(button_layout)

        self.setLayout(layout)

    @classmethod
    def show_dialog(
        cls, title: str, text: str, parent: QtW.QWidget | None = None
    ) -> int:
        """Create and show the dialog in one step.

        Parameters
        ----------
        title : str
            The title of the dialog window.
        text : str
            The text to display in the text edit area.
        parent : QtWidgets.QWidget | None, optional
            The parent widget, by default ``None``.

        Returns
        -------
        int
            Dialog result code (``QDialog.Accepted`` or ``QDialog.Rejected``).
        """
        dialog = cls(title, text, parent)
        return dialog.exec()

class DescriptorTreeView(QtWidgets.QTreeWidget):
    """Two-column property tree for browsing and editing device settings.

    Modelled after the pyqtgraph ``ParameterTree``: uses ``setItemWidget``
    to place editor/display widgets permanently in the *Value* column, so
    there are no popup editors and no delegate geometry issues.

    The device-name root level is omitted — use one widget per device,
    e.g. inside a ``QTabWidget``.

    Example
    -------

    ```python
        view = DescriptorTreeView(
            device.describe_configuration(),
            device.read_configuration(),
            parent,
        )
        view.sigPropertyChanged.connect(on_property_changed)
    ```

    Parameters
    ----------
    descriptors: dict[str, Descriptor]
        Flat ``describe_configuration()`` dict keyed by
        ``name-property`` canonical keys.
    readings: dict[str, Reading[Any]]
        Flat ``read_configuration()`` dict matching the same keys.
    parent: QtWidgets.QWidget | None
        Optional parent widget.

    Signals
    -------
    sigPropertyChanged: Signal[str, Any]
        Emitted when the user commits an edit.
        Carries ``(key: str, value: Any)``.
    """

    sigPropertyChanged: Signal = Signal(str, object)

    def __init__(
        self,
        descriptors: dict[str, Descriptor],
        readings: dict[str, Reading[Any]],
        parent: QtWidgets.QWidget | None = None,
    ) -> None:
        super().__init__(parent)

        self._descriptors = descriptors
        self._readings: dict[str, Any] = {k: v["value"] for k, v in readings.items()}
        self._pending: dict[str, Any] = {}  # key -> old value
        # key -> the widget embedded in the Value column
        self._widgets: dict[str, QtWidgets.QWidget] = {}

        self.setColumnCount(2)
        self.setHeaderLabels(["Setting", "Value"])
        self.setHeaderHidden(True)
        _hdr = self.header()
        if _hdr is not None:
            _hdr.setSectionResizeMode(
                0, QtWidgets.QHeaderView.ResizeMode.ResizeToContents
            )
            _hdr.setSectionResizeMode(1, QtWidgets.QHeaderView.ResizeMode.Stretch)
        self.setRootIsDecorated(False)
        self.setIndentation(12)
        self.setAlternatingRowColors(True)
        self.setVerticalScrollMode(
            QtWidgets.QAbstractItemView.ScrollMode.ScrollPerPixel
        )
        self.setSelectionMode(QtWidgets.QAbstractItemView.SelectionMode.NoSelection)
        self.setFocusPolicy(QtCore.Qt.FocusPolicy.NoFocus)

        self._build()

    def update_reading(self, key: str, reading: Reading[Any]) -> None:
        """Push a live value update for *key* into the corresponding widget.

        Parameters
        ----------
        key:
            Canonical ``name-property`` key.
        reading:
            New reading dict; only ``reading["value"]`` is used.
        """
        value = reading["value"]
        self._readings[key] = value
        widget = self._widgets.get(key)
        if widget is not None:
            desc = self._descriptors.get(key)
            if desc is not None:
                _update_widget_value(widget, value, desc)

    def confirm_change(self, key: str, success: bool) -> None:
        """Confirm or revert a pending user edit.

        Parameters
        ----------
        key:
            Canonical key of the setting that was attempted.
        success:
            ``True`` → keep the new value; ``False`` → revert to the
            pre-edit value and refresh the widget.
        """
        old = self._pending.pop(key, None)
        if old is None:
            return
        if not success:
            self._readings[key] = old
            widget = self._widgets.get(key)
            desc = self._descriptors.get(key)
            if widget is not None and desc is not None:
                _update_widget_value(widget, old, desc)
            _log.info("Reverted '%s' to previous value.", key)

    def get_keys(self) -> set[str]:
        """Return the set of all descriptor keys in this view."""
        return set(self._descriptors.keys())

    def _on_changed(self, key: str, value: Any) -> None:
        """Slot wired to every editor widget's change signal."""
        self._pending[key] = self._readings.get(key)
        self._readings[key] = value
        self.sigPropertyChanged.emit(key, value)

    def _build(self) -> None:
        """Populate the tree from ``self._descriptors`` and ``self._readings``.

        Groups descriptors by ``source`` (stripping the optional
        ``:readonly`` suffix), then creates one bold top-level
        ``QTreeWidgetItem`` per group and one child item per setting.
        """
        self.clear()
        self._widgets.clear()

        # group by source: source -> [(full_key, prop_name, descriptor, readonly)]
        groups: dict[str, list[tuple[str, str, Descriptor, bool]]] = {}
        for full_key, desc in self._descriptors.items():
            # strip the device prefix  (name\\property → prop)
            prop = full_key.split("-", 1)[-1] if "-" in full_key else full_key

            source_raw: str = desc.get("source", "unknown")
            parts = source_raw.split(":", 1)
            source = parts[0]
            readonly = len(parts) > 1 and parts[1] == "readonly"

            groups.setdefault(source, []).append((full_key, prop, desc, readonly))

        for source, leaves in groups.items():
            # --- group header row ---
            group_item = QtWidgets.QTreeWidgetItem([source.title()])
            group_item.setFirstColumnSpanned(True)
            font = group_item.font(0)
            font.setBold(True)
            group_item.setFont(0, font)
            group_item.setExpanded(True)
            self.addTopLevelItem(group_item)

            # --- leaf rows ---
            for full_key, prop, desc, readonly in leaves:
                child = QtWidgets.QTreeWidgetItem()
                child.setText(0, prop)
                child.setTextAlignment(
                    0,
                    QtCore.Qt.AlignmentFlag.AlignLeft
                    | QtCore.Qt.AlignmentFlag.AlignVCenter,
                )
                # tooltip
                tip_parts = [f"dtype: {desc.get('dtype', '?')}"]
                if "units" in desc:
                    tip_parts.append(f"units: {desc['units']}")
                if readonly:
                    tip_parts.append("(read-only)")
                child.setToolTip(0, " | ".join(tip_parts))
                child.setToolTip(1, " | ".join(tip_parts))

                group_item.addChild(child)

                # build the value widget
                initial = self._readings.get(full_key)
                widget = _make_value_widget(
                    full_key,
                    desc,
                    initial,
                    self._on_changed,
                    readonly,
                    self,
                )
                self.setItemWidget(child, 1, widget)
                self._widgets[full_key] = widget

        self.expandAll()
        self.resizeColumnToContents(0)