sciwidgets 0.1.2__py3-none-any.whl

sciwidgets/params/__main__.py

@@ -0,0 +1,81 @@
+"""Demo for the params subpackage: ``python -m sciwidgets.params``."""
+
+import sys
+
+from PySide6.QtWidgets import (
+    QApplication, QFormLayout, QLabel, QVBoxLayout, QWidget,
+)
+
+from sciwidgets.params.combo_box import ParameterComboBox
+from sciwidgets.params.line_edit import ParameterLineEdit
+from sciwidgets.params.numeric_line_edit import NumericLineEdit
+from sciwidgets.params.toggle import ParameterToggle
+from sciwidgets.style import apply_sci_style
+
+
+def _demo_main() -> int:
+    """Run the params demo window.
+
+    Returns:
+        int: Qt application exit code.
+    """
+    app = QApplication(sys.argv)
+    apply_sci_style(app)
+
+    win = QWidget()
+    win.setWindowTitle("Params demo")
+    layout = QVBoxLayout(win)
+
+    # --- NumericLineEdit ------------------------------------------------
+    f_edit = NumericLineEdit(
+        init_val=1.0, val_fmt="{:0.3g}", min_limit=-100.0,
+        width_chars=11, max_length=10,
+    )
+    i_edit = NumericLineEdit(
+        init_val=1, value_is_int=True, min_limit=-100, max_limit=100,
+        width_chars=10, max_length=9,
+    )
+    committed = QLabel("")
+    f_edit.valueChanged.connect(lambda v: committed.setText(f"float: {v}"))
+    i_edit.valueChanged.connect(lambda v: committed.setText(f"int: {v}"))
+
+    form = QFormLayout()
+    form.addRow("Integer [-100, 100]:", i_edit)
+    form.addRow("Float [-100, ∞):", f_edit)
+    form.addRow("Last committed:", committed)
+    layout.addLayout(form)
+    # --- Simple parameter widgets ----------------------------------------
+    t_edit = ParameterLineEdit(
+        label="t", init_val=5, val_fmt="{:0.1f}", unit_label=r"\mathrm{s}",
+        min_limit=0.0, min_limit_inclusive=False, parent=win,
+    )
+    n_edit = ParameterLineEdit(label=r"A_\alpha", init_val=5, value_is_int=True, parent=win)
+    unit = ParameterComboBox(
+        label="t", items=["T₀", "d", "h", "m", "S", "ms", "µs", "ns"], parent=win,
+    )
+    unit.set_value("ns")
+    toggle = ParameterToggle(
+        text="Normalize to max",
+        label_on=r"F = I_\mathrm{res} / \max(I_\mathrm{res}) \times I_\mathrm{scale}",
+        label_off=r"F = I_\mathrm{res} \times I_\mathrm{scale}",
+        parent=win,
+    )
+    plain = ParameterToggle(text="Plain checkbox (no labels)", checked=False, parent=win)
+
+    # Align the name column the way a panel would
+    widgets = [t_edit, n_edit, unit, toggle, plain]
+    name_w = max(w.get_name_width() for w in widgets)
+    for w in widgets:
+        w.set_name_width(name_w)
+        w.valueChanged.connect(lambda v, w=w: print(type(w).__name__, v))
+        layout.addWidget(w)
+
+    layout.addStretch(1)
+
+    win.resize(520, 420)
+    win.show()
+    return app.exec()
+
+
+if __name__ == "__main__":
+    raise SystemExit(_demo_main())

sciwidgets/params/base.py

@@ -0,0 +1,220 @@
+"""Common base class for parameter widgets with value and config signals."""
+
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar
+
+from PySide6.QtCore import Signal
+from PySide6.QtWidgets import QWidget
+
+T = TypeVar("T")
+
+
+class ParameterWidgetBase(QWidget, Generic[T]):
+    """Provide a common interface for parameter widgets.
+
+    Attributes:
+        valueChanged: Emitted when the user changes the value.
+        defaultChanged: Emitted when the user changes the default value.
+        configChanged: Emitted when the user changes the configuration.
+        valueWidthChanged: Emitted when the value display width changes.
+        nameWidthChanged: Emitted when the name display width changes.
+
+    Note:
+        ``valueChanged``, ``defaultChanged`` and ``configChanged`` are for
+        user actions only; programmatic setters such as ``set_value`` and
+        ``set_config`` do not emit them.
+    """
+
+    valueChanged = Signal(object)
+    defaultChanged = Signal(object)
+    configChanged = Signal(object)
+    valueWidthChanged = Signal(int)
+    nameWidthChanged = Signal(int)
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        """Initialize the base parameter widget.
+
+        Args:
+            parent: Optional parent widget.
+        """
+
+        super().__init__(parent)
+        self._name_width: int = 0  # requested via set_name_width
+        self._value_width: int = 0  # requested via set_value_width
+        self._measured_name_width: int = 0  # set by subclasses
+        self._measured_value_width: int = 0  # set by subclasses
+
+    def _update_layout(self) -> None:
+        """Update the widget layout to reflect the current internal state.
+
+        Subclasses should override this method when name or value width changes
+        require a visual layout update.
+        """
+
+        pass
+
+    def get_value(self) -> T:
+        """Return the current widget value.
+
+        Returns:
+            The current typed value stored by the widget.
+
+        Raises:
+            NotImplementedError: If the subclass does not implement value
+                retrieval.
+        """
+
+        raise NotImplementedError
+
+    def set_value(self, value: T) -> None:
+        """Validate and apply a new widget value.
+
+        Args:
+            value: New value to store in the widget.
+        """
+
+        validated = self._validate_value(value)
+        self._apply_value(validated)
+
+    def _validate_value(self, value: T) -> T:
+        """Validate a candidate value before applying it.
+
+        The default implementation returns the value unchanged. Subclasses can
+        override this method to enforce type, range, or domain-specific checks.
+
+        Args:
+            value: Candidate value to validate.
+
+        Returns:
+            Validated value, possibly normalized.
+        """
+
+        return value
+
+    def _apply_value(self, value: T) -> None:
+        """Apply a validated value to the widget state.
+
+        Args:
+            value: Previously validated value to store.
+
+        Raises:
+            NotImplementedError: If the subclass does not implement value
+                application.
+        """
+
+        raise NotImplementedError
+
+    def get_config(self) -> dict[str, Any]:
+        """Return the current configuration mapping.
+
+        Returns:
+            Configuration dictionary for the widget. The base implementation
+            returns an empty mapping.
+        """
+
+        return {}
+
+    def set_config(self, config: dict[str, Any]) -> None:
+        """Validate and apply configuration values.
+
+        Args:
+            config: Partial or complete configuration mapping to apply.
+        """
+
+        validated = self._validate_config(config)
+        self._apply_config(validated)
+
+    def _validate_config(self, config: dict[str, Any]) -> dict[str, Any]:
+        """Validate and normalize a configuration mapping.
+
+        The base implementation requires ``config`` to be a dictionary and
+        merges it with the current configuration, preserving existing values for
+        missing keys.
+
+        Args:
+            config: Candidate configuration mapping.
+
+        Returns:
+            Normalized configuration dictionary.
+
+        Raises:
+            TypeError: If ``config`` is not a dictionary.
+        """
+
+        if not isinstance(config, dict):
+            raise TypeError(f"config must be dict, got {type(config).__name__}")
+        old_config = self.get_config()
+        new_config = {}
+        for k, v in old_config.items():
+            if k not in config:
+                new_config[k] = v
+            else:
+                new_config[k] = config[k]
+        return new_config
+
+    def _apply_config(self, config: dict[str, Any]) -> None:
+        """Apply a validated configuration mapping.
+
+        Subclasses can override this method to store configuration state and
+        update the widget accordingly.
+
+        Args:
+            config: Previously validated configuration mapping.
+        """
+
+        _ = config
+
+    def get_name_width(self) -> int:
+        """Return the measured width of the name label.
+
+        Returns:
+            Width in pixels.
+        """
+        return self._measured_name_width
+
+    def get_value_width(self) -> int:
+        """Return the measured width of the value area.
+
+        Returns:
+            Width in pixels.
+        """
+        return self._measured_value_width
+
+    def _effective_name_width(self) -> int:
+        """Return the width the layout should reserve for the name label."""
+        return max(self._name_width, self._measured_name_width)
+
+    def _effective_value_width(self) -> int:
+        """Return the width the layout should reserve for the value area."""
+        return max(self._value_width, self._measured_value_width)
+
+    def set_name_width(self, width: int) -> None:
+        """Set a requested minimum width for the name label.
+
+        Used to align several widgets in a panel. The layout reserves the
+        larger of this value and the label's own measured width, so a smaller
+        request never cuts the label. ``get_name_width`` still returns the
+        measured width.
+
+        Args:
+            width: Requested minimum width in pixels.
+        """
+
+        self._name_width = int(width)
+        self._update_layout()
+
+    def set_value_width(self, width: int) -> None:
+        """Set a requested minimum width for the value area.
+
+        Used to align several widgets in a panel. The layout reserves the
+        larger of this value and the value area's own measured width, so a
+        smaller request never cuts the value. ``get_value_width`` still
+        returns the measured width.
+
+        Args:
+            width: Requested minimum width in pixels.
+        """
+
+        self._value_width = int(width)
+        self._update_layout()

sciwidgets/params/combo_box.py

@@ -0,0 +1,106 @@
+"""Discrete parameter widget backed by a combo box."""
+
+from __future__ import annotations
+
+from typing import List
+
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import QComboBox, QGridLayout, QWidget
+
+from ..labels import MathLabel
+from .base import ParameterWidgetBase
+
+
+class ParameterComboBox(ParameterWidgetBase[str]):
+    """Parameter widget that exposes a discrete choice through a combo box."""
+
+    def __init__(
+        self,
+        label: str,
+        items: List[str],
+        parent: QWidget | None = None,
+    ) -> None:
+        """Initialize the parameter combo-box widget.
+
+        Args:
+            label: Parameter name displayed to the left of the combo box.
+            items: Ordered list of selectable string values.
+            parent: Optional parent widget.
+        """
+
+        super().__init__(parent)
+
+        self._label = MathLabel(f"{label}=", alignment=Qt.AlignRight | Qt.AlignVCenter)
+        self._measured_name_width = self._label.sizeHint().width()
+        combo = QComboBox(self)
+        for v in items:
+            combo.addItem(v)
+        combo.activated.connect(self._on_activated)
+        self._combo = combo
+        self._last_value = combo.currentText()
+
+        self._make_layout()
+
+    def _make_layout(self) -> None:
+        """Create and assign the grid layout used by this widget."""
+
+        gl = QGridLayout(self)
+        gl.setSpacing(0)
+        gl.addWidget(self._label, 0, 0)
+        gl.addWidget(self._combo, 0, 1)
+        gl.setColumnStretch(0, 0)
+        gl.setColumnStretch(1, 0)
+        gl.setColumnStretch(2, 1)
+        self._gl = gl
+        self._update_layout()
+
+    def _update_layout(self) -> None:
+        """Reserve the effective name width for the label column."""
+
+        self._gl.setColumnMinimumWidth(0, self._effective_name_width())
+
+    def _on_activated(self, _index: int) -> None:
+        """Emit the value after the user picks a different item."""
+        value = self.get_value()
+        if value != self._last_value:
+            self._last_value = value
+            self.valueChanged.emit(value)
+
+    def get_value(self) -> str:
+        """Return the currently selected combo-box text.
+
+        Returns:
+            Selected string value.
+        """
+
+        return self._combo.currentText()
+
+    def _validate_value(self, value: str) -> str:
+        """Validate a value before applying it to the combo box.
+
+        Args:
+            value: Proposed combo-box text.
+
+        Returns:
+            Validated combo-box text.
+
+        Raises:
+            TypeError: If ``value`` is not a string.
+            ValueError: If no combo-box item matches ``value``.
+        """
+
+        if not isinstance(value, str):
+            raise TypeError("'value' must be a string")
+        if self._combo.findText(value) < 0:
+            raise ValueError(f"No combo item found for text={value!r}")
+        return value
+
+    def _apply_value(self, value: str) -> None:
+        """Apply a validated value by selecting the matching combo item.
+
+        Args:
+            value: Combo-box text to select.
+        """
+        self._combo.setCurrentIndex(self._combo.findText(value))
+        self._last_value = value
+

sciwidgets/params/line_edit.py

@@ -0,0 +1,132 @@
+"""Text and scalar parameter widget backed by a line edit."""
+
+from __future__ import annotations
+
+import numbers
+from typing import Optional, Union
+
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import QWidget, QGridLayout
+
+from ..labels import MathLabel
+from .base import ParameterWidgetBase
+from .numeric_line_edit import NumericLineEdit
+
+Num = Union[int, float]
+
+
+class ParameterLineEdit(ParameterWidgetBase[Num]):
+    """Parameter widget that exposes a numeric value through a line edit."""
+
+    def __init__(
+            self,
+            label: str,
+            init_val: Num,
+            val_fmt: str = "{:0.6g}",
+            value_is_int: bool = False,
+            unit_label: str = "",
+            min_limit: Num | None = None,
+            max_limit: Num | None = None,
+            min_limit_inclusive: bool = True,
+            max_limit_inclusive: bool = True,
+            max_length: Optional[int] = None,
+            width_chars: Optional[int] = None,
+            parent: Optional[QWidget] = None,
+    ) -> None:
+        """Initialize the parameter line edit.
+
+        Args:
+            label: Parameter name displayed to the left of the line edit.
+            init_val: Initial value.
+            val_fmt: Display format string.
+            value_is_int: Whether the value is an integer.
+            unit_label: Optional unit shown to the right, as LaTeX.
+            min_limit: Optional lower hard limit.
+            max_limit: Optional upper hard limit.
+            min_limit_inclusive: Whether the lower hard limit is inclusive.
+            max_limit_inclusive: Whether the upper hard limit is inclusive.
+            max_length: Optional maximum number of characters.
+            width_chars: Optional width of the line edit in characters.
+            parent: Optional parent widget.
+        """
+
+        super().__init__(parent)
+
+        self._value_is_int = value_is_int
+        self._parse = int if value_is_int else float
+        self._label = MathLabel(f"{label}=", alignment=Qt.AlignRight | Qt.AlignVCenter)
+        self._measured_name_width = self._label.sizeHint().width()
+        self._unit_label: MathLabel | None = None
+        if unit_label:
+            self._unit_label = MathLabel(f"({unit_label})")
+        self._line_edit = NumericLineEdit(
+            init_val=init_val,
+            value_is_int=value_is_int,
+            val_fmt=val_fmt,
+            min_limit=min_limit,
+            max_limit=max_limit,
+            min_limit_inclusive=min_limit_inclusive,
+            max_limit_inclusive=max_limit_inclusive,
+            place_holder_text="Enter an int" if value_is_int else "Enter a float",
+            max_length=max_length,
+            width_chars=width_chars,
+        )
+        self._line_edit.valueChanged.connect(self._on_values_changed)
+
+        self._make_layout()
+
+    def _make_layout(self) -> None:
+        """Create the layout used by this widget."""
+
+        gl = QGridLayout(self)
+        gl.setSpacing(0)
+        gl.addWidget(self._label, 0, 0)
+        gl.addWidget(self._line_edit, 0, 1)
+        if self._unit_label is not None:
+            gl.addWidget(self._unit_label, 0, 2)
+            gl.setColumnStretch(3, 1)
+        else:
+            gl.setColumnStretch(2, 1)
+        self._gl = gl
+        self._update_layout()
+
+    def _update_layout(self) -> None:
+        """Reserve the effective name width for the label column."""
+
+        self._gl.setColumnMinimumWidth(0, self._effective_name_width())
+
+    # ----- internal helpers -----
+    def _on_values_changed(self) -> None:
+        """Handle the values changed event."""
+
+        self.valueChanged.emit(self.get_value())
+
+    # ----- public API -----
+    def get_value(self) -> Num:
+        """Return the current value."""
+
+        return self._line_edit.get_value()
+
+    def _validate_value(self, value: Num) -> Num:
+        """Validate a value before applying it.
+
+        Args:
+            value: Proposed value.
+
+        Returns:
+            Validated value.
+
+        Raises:
+            TypeError: If ``value`` is not a number, or not an integer on an
+                integer line edit. ``bool`` is rejected.
+        """
+        if isinstance(value, bool) or not isinstance(value, numbers.Real):
+            raise TypeError(f"value must be a number, not {type(value).__name__}")
+        if self._value_is_int and not isinstance(value, numbers.Integral):
+            raise TypeError(f"value must be an int, not {type(value).__name__}")
+        return value
+
+    def _apply_value(self, value: Num) -> None:
+        """Apply a validated value to the widget state."""
+
+        self._line_edit.set_value(self._parse(value))