sciwidgets 0.1.2__py3-none-any.whl

sciwidgets/params/sliders/__init__.py

@@ -0,0 +1,36 @@
+"""Labeled sliders: single-value, range, and multi-variable."""
+
+from .base import SliderFeature, SliderWidgetBase
+from .multi import MultiVariableSlider
+from .range import (
+    DualHandleSlider,
+    FloatRangeSlider,
+    IntRangeSlider,
+    LabeledRangeSliderBase,
+    NumericRangeSliderBase,
+)
+from .single import (
+    ArraySlider,
+    FloatSlider,
+    IntSlider,
+    LabeledSliderBase,
+    NumericSliderBase,
+    SpecialValue,
+)
+
+__all__ = [
+    "ArraySlider",
+    "DualHandleSlider",
+    "FloatRangeSlider",
+    "FloatSlider",
+    "IntRangeSlider",
+    "IntSlider",
+    "LabeledRangeSliderBase",
+    "LabeledSliderBase",
+    "MultiVariableSlider",
+    "NumericRangeSliderBase",
+    "NumericSliderBase",
+    "SliderFeature",
+    "SliderWidgetBase",
+    "SpecialValue",
+]

sciwidgets/params/sliders/__main__.py

@@ -0,0 +1,215 @@
+"""Demo for the sliders: ``python -m sciwidgets.params.sliders``."""
+
+import sys
+
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import (
+    QApplication,
+    QCheckBox,
+    QComboBox,
+    QGroupBox,
+    QHBoxLayout,
+    QLabel,
+    QPlainTextEdit,
+    QVBoxLayout,
+    QWidget,
+)
+
+from sciwidgets.params.sliders.base import SliderFeature
+from sciwidgets.params.sliders.single import ArraySlider, FloatSlider, IntSlider
+from sciwidgets.params.sliders.range import FloatRangeSlider, IntRangeSlider
+from sciwidgets.params.sliders.multi import MultiVariableSlider
+from sciwidgets.style import apply_sci_style
+
+
+def _demo_main() -> int:
+    """Run a demo of the single-value sliders.
+
+    Returns:
+        int: Qt application exit code.
+    """
+    app = QApplication(sys.argv)
+    apply_sci_style(app)
+
+    win = QWidget()
+    win.setWindowTitle("Sliders demo — right-click a slider for its menu")
+    root = QVBoxLayout(win)
+
+    # --- Signal log -----------------------------------------------------
+    log = QPlainTextEdit()
+    log.setReadOnly(True)
+    log.setMaximumHeight(140)
+
+    def watch(name: str, slider) -> None:
+        """Log the user-action signals of a slider."""
+        slider.valueChanged.connect(lambda v: log.appendPlainText(f"{name}: value → {v}"))
+        slider.defaultChanged.connect(lambda d: log.appendPlainText(f"{name}: default → {d}"))
+        slider.configChanged.connect(lambda c: log.appendPlainText(f"{name}: config → {c}"))
+
+    # --- Horizontal sliders -----------------------------------------------
+    t2 = FloatSlider(  # starts at +inf: "no dephasing"
+        label="T_2", unit=r"\mathrm{ms}", min_val=0.1, max_val=10.0,
+        init_val="+inf", val_fmt="{:.2f}", min_limit=0.0, min_limit_inclusive=False,
+    )
+    h_items = [
+        ("N_z", IntSlider(  # integer, all menu features
+            label="N_z", min_val=10, max_val=1000, init_val=200, min_limit=1,
+        )),
+        ("T_1", FloatSlider(  # float with a strict lower limit
+            label="T_1", unit=r"\mathrm{ms}", min_val=0.1, max_val=10.0, init_val=1.0,
+            val_fmt="{:.2f}", min_limit=0.0, min_limit_inclusive=False,
+            features=SliderFeature.DEFAULTS | SliderFeature.SET_VALUE | SliderFeature.CONFIG,
+        )),
+        ("T_2", t2),
+        ("gamma", FloatSlider(  # custom scientific format
+            label=r"\gamma", unit=r"\mathrm{s^{-1}}", min_val=1e-3, max_val=1e-1,
+            init_val=1e-2, val_fmt="{:.2S}", min_limit=0.0, min_limit_inclusive=False,
+        )),
+        ("Delta_omega", FloatSlider(  # signed values, no ±inf
+            label=r"\Delta\omega", unit=r"\mathrm{MHz}", min_val=-5.0, max_val=5.0,
+            init_val=0.0, val_fmt="{:+.2f}",
+            features=SliderFeature.DEFAULTS | SliderFeature.SET_VALUE | SliderFeature.CONFIG,
+        )),
+        ("z", ArraySlider(  # picks from a grid of positions
+            label="z", unit=r"\mathrm{m}", arr_length=51, min_val=0.0, max_val=1.0,
+            init_index=25, val_fmt="{:.2f}",
+            features=SliderFeature.DEFAULTS | SliderFeature.CONFIG,
+        )),
+        ("seed", IntSlider(  # no menu at all
+            label=r"\mathrm{seed}", min_val=0, max_val=99, init_val=42,
+            features=SliderFeature.NONE,
+        )),
+        ("nu", FloatRangeSlider(  # a frequency band
+            label=r"\nu", unit=r"\mathrm{GHz}", min_val=6.60, max_val=6.75,
+            init_vals=(6.65, 6.70), val_fmt="{:.3f}",
+        )),
+        ("channels", IntRangeSlider(  # integer range
+            label=r"\mathrm{ch}", min_val=0, max_val=1023, init_vals=(100, 900),
+        )),
+        ("I", FloatRangeSlider(  # starts in margins mode, scientific format
+            label="I", unit=r"\mathrm{Jy}", min_val=0.0, max_val=1e3,
+            init_vals=(10.0, 500.0), val_fmt="{:.2S}", min_limit=0.0,
+            use_margins=True, margins=(5, 10),
+        )),
+    ]
+
+    h_box = QGroupBox("Horizontal")
+    h_col = QVBoxLayout(h_box)
+    for name, s in h_items:
+        h_col.addWidget(s)
+        watch(name, s)
+    h_col.addStretch(1)
+
+    def realign(_w: int = 0) -> None:
+        """Align the name and value columns of the horizontal sliders."""
+        sliders = [s for _, s in h_items]
+        name_w = max(s.get_name_width() for s in sliders)
+        value_w = max(s.get_value_width() for s in sliders)
+        for s in sliders:
+            s.set_name_width(name_w)
+            s.set_value_width(value_w)
+
+    for _, s in h_items:
+        s.nameWidthChanged.connect(realign)
+        s.valueWidthChanged.connect(realign)
+    realign()
+
+    # --- Vertical sliders ---------------------------------------------------
+    v_items = [
+        (f"E_{axis}", FloatSlider(
+            label=f"E_{axis}", min_val=-1.0, max_val=1.0, init_val=0.0,
+            val_fmt="{:.2f}", orientation=Qt.Vertical,
+        ))
+        for axis in "xyz"
+    ]
+    v_items.append(("t", FloatRangeSlider(
+        label="t", min_val=0.0, max_val=1.0, init_vals=(0.2, 0.8),
+        val_fmt="{:.2f}", orientation=Qt.Vertical,
+    )))
+    v_box = QGroupBox("Vertical")
+    v_row = QHBoxLayout(v_box)
+    for name, s in v_items:
+        v_row.addWidget(s)
+        watch(name, s)
+
+    top = QHBoxLayout()
+    top.addWidget(h_box, 3)
+    top.addWidget(v_box, 1)
+    root.addLayout(top, 1)
+
+    # --- Multi-variable slider ------------------------------------------------
+    tau = MultiVariableSlider(  # one decay time per spectral component
+        label=r"\tau_k", html_label="τ<sub>k</sub>", unit=r"\mathrm{d}",
+        min_val=0.0, max_val=100.0, init_vals=[10, 25, 40, "+inf", 80],
+        val_fmt="{:.1f}", min_limit=0.0,
+    )
+    idx_combo = QComboBox()
+    idx_combo.addItems([str(i) for i in range(tau.get_arr_length())])
+    idx_combo.currentIndexChanged.connect(tau.set_index)
+    same_cb = QCheckBox("Same value for all")
+    same_cb.toggled.connect(tau.set_use_same_values)
+
+    arr_label = QLabel()
+
+    def show_arr(_=None) -> None:
+        """Show the whole array as the slider stores it."""
+        texts = (tau.get_value_text(i) for i in range(tau.get_arr_length()))
+        arr_label.setText("Array: [" + ", ".join(texts) + "]")
+
+    tau.arrayChanged.connect(show_arr)
+    same_cb.toggled.connect(show_arr)
+    show_arr()
+    watch("tau", tau)
+    tau.arrayChanged.connect(lambda a: log.appendPlainText(f"tau: array → {a}"))
+
+    m_box = QGroupBox("Multi-variable")
+    m_col = QVBoxLayout(m_box)
+    m_row = QHBoxLayout()
+    m_row.addWidget(QLabel("Index:"))
+    m_row.addWidget(idx_combo)
+    m_row.addWidget(same_cb)
+    m_row.addStretch(1)
+    m_col.addLayout(m_row)
+    m_col.addWidget(tau)
+    m_col.addWidget(arr_label)
+    root.addWidget(m_box)
+
+    # --- Programmatic controls ----------------------------------------------
+    all_sliders = [s for _, s in h_items + v_items] + [tau]
+
+    enabled = QCheckBox("Sliders enabled")
+    enabled.setChecked(True)
+    ranges = QCheckBox("Show ranges")
+    ranges.setChecked(True)
+    allow_inf = QCheckBox("Allow T₂ = +inf")
+    allow_inf.setChecked(True)
+
+    def set_enabled(on: bool) -> None:
+        for s in all_sliders:
+            s.setEnabled(on)
+
+    def set_ranges(on: bool) -> None:
+        for s in all_sliders:
+            s.set_show_range(on)
+
+    enabled.toggled.connect(set_enabled)
+    ranges.toggled.connect(set_ranges)
+    allow_inf.toggled.connect(lambda on: t2.set_special_value_allowed("+inf", on))
+
+    controls = QHBoxLayout()
+    for cb in (enabled, ranges, allow_inf):
+        controls.addWidget(cb)
+    controls.addStretch(1)
+    root.addLayout(controls)
+
+    log_box = QGroupBox("Signals (user actions only)")
+    QVBoxLayout(log_box).addWidget(log)
+    root.addWidget(log_box)
+
+    win.resize(1000, 620)
+    win.show()
+    return app.exec()
+
+
+if __name__ == "__main__":
+    raise SystemExit(_demo_main())

sciwidgets/params/sliders/_defaults.py

@@ -0,0 +1,36 @@
+"""Default sizes and slider border styling used by the parameter widgets."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+SLIDER_LABEL_SIZE = 20
+"""Default font size, in points, for slider name labels."""
+
+UNIT_LABEL_SIZE = 18
+"""Default font size, in points, for unit labels."""
+
+SLIDER_BORDER_STYLE_SHEET = """
+        QWidget#labeled_slider[borderState="normal"] {
+            border: 1px solid gray;
+            border-radius: 3px;
+            background: transparent;
+        }
+        QWidget#labeled_slider[borderState="error"] {
+            border: 1px solid red;
+            border-radius: 3px;
+            background: transparent;
+        }
+        QWidget#labeled_slider[borderState="off"] {
+            border: 0px;
+        }
+        """
+"""Style sheet fragment used for custom slider border states."""
+
+
+class SliderBorderState(str, Enum):
+    """State values used when drawing custom slider borders."""
+
+    OFF = "off"
+    NORMAL = "normal"
+    ERROR = "error"

sciwidgets/params/sliders/_dialogs.py

@@ -0,0 +1,174 @@
+"""Out-of-range questions shown by the slider widgets."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from PySide6.QtWidgets import QWidget
+
+from ...dialogs import AskResult, ask_question
+
+
+def slider_ask_clamp_value(
+    proposed_range: str,
+    old_cur: str,
+    new_cur: str,
+    old_dft: str,
+    new_dft: str,
+    parent: Optional[QWidget] = None,
+) -> AskResult:
+    """Ask whether a slider value should be clamped to a proposed range.
+
+    Args:
+        proposed_range: Proposed allowed range.
+        old_cur: Previous current value.
+        new_cur: Clamped current value.
+        old_dft: Previous default value.
+        new_dft: Clamped default value.
+        parent: Optional parent widget.
+
+    Returns:
+        User's selected answer.
+    """
+
+    return ask_question(
+        "Out of range",
+        "<b>Current</b>/<b>default</b> value is outside the proposed range.",
+        f"<b>Proposed range:</b> <code>{proposed_range}</code><br>"
+        f"<b>Current:</b> <code>{old_cur}</code> → <code>{new_cur}</code><br>"
+        f"<b>Default:</b> <code>{old_dft}</code> → <code>{new_dft}</code><br><br>"
+        "Press <b>OK</b> to clamp values to the proposed range, or <b>Cancel</b> to abort.",
+        yes_btn_label="OK",
+        cancel_btn_label="Cancel",
+        parent=parent,
+    )
+
+
+def range_slider_ask_clamp_value(
+    proposed_range: str,
+    old_cur: str,
+    new_cur: str,
+    old_dft: str,
+    new_dft: str,
+    parent: Optional[QWidget] = None,
+) -> AskResult:
+    """Ask whether range-slider values should be clamped to proposed limits.
+
+    Args:
+        proposed_range: Proposed allowed range limits.
+        old_cur: Previous current range.
+        new_cur: Clamped current range.
+        old_dft: Previous default range.
+        new_dft: Clamped default range.
+        parent: Optional parent widget.
+
+    Returns:
+        User's selected answer.
+    """
+
+    return ask_question(
+        "Out of range",
+        "<b>Current</b>/<b>default</b> values are outside the proposed range limits.",
+        f"<b>Proposed range limits:</b> <code>{proposed_range}</code><br>"
+        f"<b>Current:</b> <code>{old_cur}</code> → <code>{new_cur}</code><br>"
+        f"<b>Default:</b> <code>{old_dft}</code> → <code>{new_dft}</code><br><br>"
+        "Press <b>OK</b> to clamp values to the proposed range, or <b>Cancel</b> to abort.",
+        yes_btn_label="OK",
+        cancel_btn_label="Cancel",
+        parent=parent,
+    )
+
+
+def multi_slider_ask_clamp_value(
+    proposed_range: str,
+    cur_min: str,
+    cur_max: str,
+    dft_min: str,
+    dft_max: str,
+    parent: Optional[QWidget] = None,
+) -> AskResult:
+    """Ask whether array-slider values should be clamped to a proposed range.
+
+    Args:
+        proposed_range: Proposed allowed range.
+        cur_min: Minimum current value.
+        cur_max: Maximum current value.
+        dft_min: Minimum default value.
+        dft_max: Maximum default value.
+        parent: Optional parent widget.
+
+    Returns:
+        User's selected answer.
+    """
+
+    return ask_question(
+        "Out of range",
+        "<b>Current</b>/<b>default</b> values are outside the proposed range.",
+        f"<b>Proposed range:</b> <code>{proposed_range}</code><br>"
+        f"<b>Current values range:</b> <code>[{cur_min}, {cur_max}]</code><br>"
+        f"<b>Default values range:</b> <code>[{dft_min}, {dft_max}]</code><br><br>"
+        "Press <b>OK</b> to clamp values to the proposed range, or <b>Cancel</b> to abort.",
+        yes_btn_label="OK",
+        cancel_btn_label="Cancel",
+        parent=parent,
+    )
+
+
+def slider_ask_extend_range(
+    proposed_val: str,
+    old_range: str,
+    new_range: str,
+    parent: Optional[QWidget] = None,
+) -> AskResult:
+    """Ask whether a slider range should be extended to include a new value.
+
+    Args:
+        proposed_val: Proposed new value.
+        old_range: Existing range.
+        new_range: Extended range.
+        parent: Optional parent widget.
+
+    Returns:
+        User's selected answer.
+    """
+
+    return ask_question(
+        "Out of range",
+        "The proposed <b>value</b> is outside the current range.",
+        f"<b>Proposed value:</b> <code>{proposed_val}</code><br>"
+        f"<b>Range:</b> <code>{old_range}</code> → <code>{new_range}</code><br><br>"
+        "Press <b>OK</b> to extend the range to include this value, or <b>Cancel</b> to abort.",
+        yes_btn_label="OK",
+        cancel_btn_label="Cancel",
+        parent=parent,
+    )
+
+
+def range_slider_ask_extend_range(
+    proposed_vals: str,
+    old_range: str,
+    new_range: str,
+    parent: Optional[QWidget] = None,
+) -> AskResult:
+    """Ask whether a range-slider range should be extended for new values.
+
+    Args:
+        proposed_vals: Proposed new range values.
+        old_range: Existing range.
+        new_range: Extended range.
+        parent: Optional parent widget.
+
+    Returns:
+        User's selected answer.
+    """
+
+    return ask_question(
+        "Out of range",
+        "The proposed <b>values</b> are outside the current range limits.",
+        f"<b>Proposed values:</b> <code>{proposed_vals}</code><br>"
+        f"<b>Range:</b> <code>{old_range}</code> → <code>{new_range}</code><br><br>"
+        "Press <b>OK</b> to extend the range to include these values, or <b>Cancel</b> to abort.",
+        yes_btn_label="OK",
+        cancel_btn_label="Cancel",
+        parent=parent,
+    )

sciwidgets/params/sliders/_right_click_overlay.py

@@ -0,0 +1,115 @@
+"""Transparent overlay that translates clicks into context-menu actions."""
+
+from __future__ import annotations
+
+from PySide6.QtCore import QPoint, Qt
+from PySide6.QtWidgets import QWidget
+
+
+class RightClickOverlay(QWidget):
+    """Transparent overlay that forwards clicks as context-menu requests.
+
+    The overlay is positioned over a target widget when needed. Mouse input on the
+    overlay is consumed so the underlying widget does not receive it directly. A
+    right-click release is translated into a context-menu request on the owner
+    widget.
+    """
+
+    def __init__(
+            self,
+            target_widget: QWidget,
+            owner_widget: QWidget,
+            parent: QWidget | None = None,
+    ) -> None:
+        """Initialize the overlay.
+
+        Args:
+            target_widget: Widget whose geometry is mirrored by the overlay.
+            owner_widget: Widget that handles the forwarded context-menu request.
+            parent: Parent widget that contains the overlay.
+        """
+        super().__init__(parent)
+        self._target_widget = target_widget
+        self._owner_widget = owner_widget
+
+        self.setAttribute(Qt.WA_NoSystemBackground, True)
+        self.raise_()
+
+    def sync_to_target(self) -> None:
+        """Sync the overlay geometry and visibility with the target widget.
+
+        The overlay is hidden when no target widget is available or when the
+        target widget is enabled. Otherwise, the overlay is resized and moved to
+        cover the target widget within the parent coordinate system.
+        """
+        if self._target_widget is None or self._target_widget.isEnabled():
+            self.hide()
+            return
+
+        parent = self.parentWidget()
+        if parent is None:
+            return
+
+        pos = self._target_widget.mapTo(parent, QPoint(0, 0))
+        self.setGeometry(
+            pos.x(),
+            pos.y(),
+            self._target_widget.width(),
+            self._target_widget.height(),
+        )
+        self.raise_()
+        self.show()
+
+    def mouseReleaseEvent(self, event) -> None:
+        """Handle mouse-release events on the overlay.
+
+        Args:
+            event: Qt mouse event received by the overlay.
+
+        A right-button release is forwarded to the owner widget as a context-menu
+        request using the global cursor position.
+        """
+        if event.button() == Qt.RightButton:
+            self._owner_widget._show_context_menu(event.globalPosition().toPoint())
+        event.accept()
+
+    def paintEvent(self, event) -> None:
+        """Handle paint events for the overlay.
+
+        Args:
+            event: Qt paint event.
+
+        The overlay is intentionally transparent and does not draw any content.
+        """
+        pass
+
+    def mousePressEvent(self, event) -> None:
+        """Handle mouse-press events on the overlay.
+
+        Args:
+            event: Qt mouse event.
+
+        The event is accepted so the underlying widget does not process it.
+        """
+        event.accept()
+
+    def mouseDoubleClickEvent(self, event) -> None:
+        """Handle mouse double-click events on the overlay.
+
+        Args:
+            event: Qt mouse event.
+
+        The event is accepted so the underlying widget does not process it.
+        """
+        event.accept()
+
+    def contextMenuEvent(self, event) -> None:
+        """Handle context-menu events on the overlay.
+
+        Args:
+            event: Qt context-menu event.
+
+        The event is accepted because context-menu handling is managed through the
+        mouse-release forwarding logic.
+        """
+        event.accept()