sciwidgets 0.1.2__py3-none-any.whl

sciwidgets/params/sliders/multi.py

@@ -0,0 +1,660 @@
+"""Array-aware slider widget for editing one value from a vector at a time."""
+
+from __future__ import annotations
+import math
+from typing import Literal, Optional, Sequence
+
+import numpy as np
+from PySide6.QtCore import Qt, Signal
+from PySide6.QtWidgets import (
+    QDialog,
+    QDialogButtonBox,
+    QStyle,
+    QTextEdit,
+    QVBoxLayout,
+    QWidget,
+)
+
+from ...dialogs import AskResult
+from ._defaults import SliderBorderState
+from ._dialogs import multi_slider_ask_clamp_value
+from .base import SliderFeature
+from .single import EditConfigDialog, FloatSlider, SpecialValue, normalize_special_value
+
+class MultiVariableSlider(FloatSlider):
+    """Float slider that exposes one element of an internal value array at a time.
+
+    The widget stores per-index current values, default values, and optional
+    special values such as ``+inf`` and ``-inf``. The selected index is shown on
+    the base ``FloatSlider`` interface, and updates to the active slider value
+    are written back to the corresponding array element.
+
+    Attributes:
+        arrayChanged: Emitted when the user changes the stored current-value
+            array (dragging, context menu, dialogs). Programmatic methods such
+            as ``set_arr_values``, ``set_range`` or ``set_use_same_values`` do
+            not emit it. The emitted object is a copy of the array.
+    """
+
+    arrayChanged = Signal(object)
+
+    def __init__(
+            self,
+            label: str,
+            html_label: str,
+            min_val: float,
+            max_val: float,
+            init_vals: Sequence[float | str],
+            init_idx: int = 0,
+            unit: str = "",
+            use_same_values: bool = False,
+            steps: int = 10000,
+            val_fmt: str = "{:.3f}",
+            min_limit: float | None = None,
+            max_limit: float | None = None,
+            min_limit_inclusive: bool = True,
+            max_limit_inclusive: bool = True,
+            show_range: bool = True,
+            orientation: Qt.Orientation = Qt.Horizontal,
+            features: SliderFeature = SliderFeature.ALL,
+            parent: Optional[QWidget] = None,
+    ):
+        """Initialize the multi-variable slider.
+
+        Args:
+            label: LaTeX-style label shown beside the slider.
+            html_label: HTML label used in the values dialog table header.
+            min_val: Minimum editable numeric range.
+            max_val: Maximum editable numeric range.
+            init_vals: Initial per-index values. Entries may be finite numbers or
+                special infinity markers.
+            init_idx: Initial active index in the stored array.
+            unit: Optional unit label shown beside the value.
+            use_same_values: If ``True``, changing one entry propagates the same
+                value to all entries.
+            steps: Integer resolution of the underlying float slider.
+            val_fmt: Display format string for finite values.
+            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.
+            show_range: Initial visibility of range labels and ticks; change
+                later with ``set_show_range``.
+            orientation: Slider orientation.
+            features: Context-menu features offered by the slider.
+                Defaults to ``SliderFeature.ALL``.
+            parent: Optional parent widget.
+
+        Raises:
+            ValueError: If ``init_vals`` is empty, contains a finite value outside
+                the editable range, or contains an infinity marker that is not
+                permitted (missing ``SliderFeature.SPECIAL`` or a conflicting
+                hard limit).
+        """
+        init_vals = list(init_vals)
+        if len(init_vals) == 0:
+            raise ValueError("init_values must not be empty")
+
+        init_special_arr: list[SpecialValue | None] = []
+        finite_init_values: list[float] = []
+
+        for i, v in enumerate(init_vals):
+            sv = normalize_special_value(v)
+            init_special_arr.append(sv)
+            if sv is None:
+                fv = float(v)
+                if not (min_val <= fv <= max_val):
+                    raise ValueError(
+                        f"init_values must all lie within [{min_val}, {max_val}], "
+                        f"but found value {fv} at index {i}"
+                    )
+                finite_init_values.append(fv)
+            else:
+                if SliderFeature.SPECIAL not in features:
+                    raise ValueError(f"init_values[{i}] is {sv!r}, which requires SliderFeature.SPECIAL")
+                if sv == "+inf" and max_limit is not None:
+                    raise ValueError(f"init_values[{i}] cannot be +inf when max_limit is set")
+                if sv == "-inf" and min_limit is not None:
+                    raise ValueError(f"init_values[{i}] cannot be -inf when min_limit is set")
+                finite_init_values.append(max_val if sv == "+inf" else min_val)
+
+        self._arr_length = len(finite_init_values)
+        self._current_idx = init_idx % self._arr_length
+        self._current_arr = np.asarray(finite_init_values.copy())
+        self._default_arr = np.asarray(finite_init_values.copy())
+        self._current_special_arr = init_special_arr.copy()
+        self._use_same_values = False
+
+        init_val = init_special_arr[self._current_idx]
+        if init_val is None:
+            init_val = finite_init_values[self._current_idx]
+
+        super().__init__(
+            label=label,
+            unit=unit,
+            min_val=min_val,
+            max_val=max_val,
+            steps=steps,
+            init_val=init_val,
+            val_fmt=val_fmt,
+            min_limit=min_limit,
+            max_limit=max_limit,
+            min_limit_inclusive=min_limit_inclusive,
+            max_limit_inclusive=max_limit_inclusive,
+            show_range=show_range,
+            orientation=orientation,
+            features=features,
+            parent=parent,
+        )
+
+        self.html_label = html_label
+
+        if SliderFeature.VALUES in self._features:
+            self._right_click_items += [
+                {"id": "sep"},
+                {"id": "show_val", "text": "Show Values..."},
+            ]
+
+        self.set_arr_values(self.get_arr_values(), idx=self._current_idx)
+        self.set_use_same_values(use_same_values)
+
+        self.valueChanged.connect(self._on_single_value_changed)
+        self.defaultChanged.connect(self._on_single_default_changed)
+
+    # ----- internal helpers -----
+    def _arr_value_text(self, idx: int) -> str:
+        """Return the formatted text for the value stored at ``idx``.
+
+        Args:
+            idx: Array index to inspect.
+
+        Returns:
+            Formatted finite value text, ``"+inf"``, or ``"-inf"``.
+        """
+        sv = self._current_special_arr[idx]
+        if sv == "+inf":
+            return "+inf"
+        if sv == "-inf":
+            return "-inf"
+        return self._value_to_text(self._current_arr[idx])
+
+    def _store_active(self) -> None:
+        """Write the active slider state into the stored arrays.
+
+        In same-values mode, every entry receives the active state.
+        """
+        cur = float(self._current_value)
+        dft = float(self._default_value)
+        sv = self._current_special_value
+        if self._use_same_values:
+            self._current_arr[:] = cur
+            self._default_arr[:] = dft
+            self._current_special_arr[:] = [sv] * self._arr_length
+        else:
+            i = self._current_idx
+            self._current_arr[i] = cur
+            self._default_arr[i] = dft
+            self._current_special_arr[i] = sv
+
+    def _update_slider_for_current_idx(self) -> None:
+        """Synchronize the base slider state with the currently selected index."""
+        self._current_value = float(self._current_arr[self._current_idx])
+        self._default_value = float(self._default_arr[self._current_idx])
+        self._current_special_value = self._current_special_arr[self._current_idx]
+
+        self._update_mapping_anchors()
+        with self._quiet_updates():
+            self._apply_range_to_slider()
+            self._slider.setValue(self._value_to_pos(self._current_value))
+
+        if self._current_special_value is not None:
+            self._enter_special_mode(self._current_special_value)
+        else:
+            self._exit_special_mode()
+
+        if self._default_red_marker is not None:
+            self._default_red_marker.update()
+        self._update_all_labels()
+
+    def _on_single_value_changed(self, _value) -> None:
+        """Store the active value after a user change and report the array."""
+        self._store_active()
+        self.arrayChanged.emit(self.get_arr_values())
+
+    def _on_single_default_changed(self, _value) -> None:
+        """Store the active default after a user change."""
+        self._store_active()
+
+    # ----- right click -----
+    def _right_click_requested(self, item_id, checked: bool) -> None:
+        """Handle a context-menu action.
+
+        Args:
+            item_id: Identifier of the selected menu action.
+            checked: Checked state associated with the action.
+        """
+        super()._right_click_requested(item_id, checked)
+        if item_id == "show_val":
+            self._open_show_values_dlg()
+
+    def _open_edit_config_dlg(self) -> None:
+        """Open and apply the configuration dialog for range and format.
+
+        If the new range would exclude current or default array values, the
+        user is asked whether those values should be clamped. Cancelling
+        restores the previous format and values.
+        """
+        dlg = EditConfigDialog(
+            slider_name=self._label_text,
+            value_is_int=self.value_is_int,
+            min_val=self._min_value,
+            max_val=self._max_value,
+            val_fmt=self._val_fmt,
+            min_limit=self._min_limit,
+            max_limit=self._max_limit,
+            min_limit_inclusive=self._min_limit_inclusive,
+            max_limit_inclusive=self._max_limit_inclusive,
+            validate=self._check_new_config,
+            parent=self,
+        )
+        if dlg.exec() != QDialog.Accepted:
+            return
+        new_min, new_max, new_fmt = dlg.get_values()
+
+        # snapshot before set_format rounds anything
+        old_fmt = self._val_fmt
+        old_min, old_max = self._min_value, self._max_value
+        saved_cur_arr = self._current_arr.copy()
+        saved_dft_arr = self._default_arr.copy()
+        saved_cur, saved_dft = self._current_value, self._default_value
+        old_arr_values = self.get_arr_values()
+        old_value = self.get_value()
+
+        self.set_format(new_fmt)
+        new_min = self.evaluate_value(new_min)
+        new_max = self.evaluate_value(new_max)
+
+        # ±inf entries only hold a placeholder, so leave them out of the check
+        finite = np.array([sv is None for sv in self._current_special_arr])
+        cur_vals = self._current_arr[finite]
+        dft_vals = self._default_arr
+
+        cur_out = cur_vals.size > 0 and (cur_vals.min() < new_min or cur_vals.max() > new_max)
+        dft_out = dft_vals.min() < new_min or dft_vals.max() > new_max
+
+        if cur_out or dft_out:
+            self.set_border(SliderBorderState.ERROR)
+            try:
+                result = multi_slider_ask_clamp_value(
+                    proposed_range=f"[{self._value_to_text(new_min)}, {self._value_to_text(new_max)}]",
+                    cur_min=self._value_to_text(cur_vals.min()) if cur_vals.size else "-",
+                    cur_max=self._value_to_text(cur_vals.max()) if cur_vals.size else "-",
+                    dft_min=self._value_to_text(dft_vals.min()),
+                    dft_max=self._value_to_text(dft_vals.max()),
+                    parent=self,
+                )
+            finally:
+                self.set_border(SliderBorderState.OFF)
+            if result != AskResult.YES:
+                self.set_format(old_fmt)
+                self._current_arr, self._default_arr = saved_cur_arr, saved_dft_arr
+                self._current_value, self._default_value = saved_cur, saved_dft
+                self._min_value, self._max_value = old_min, old_max
+                return
+
+        self.set_range(new_min, new_max)
+
+        # report what the user's change did
+        if self.get_value() != old_value:
+            self.valueChanged.emit(self.get_value())  # handler also emits arrayChanged
+        elif not np.array_equal(self.get_arr_values(), old_arr_values):
+            self.arrayChanged.emit(self.get_arr_values())
+        if self._default_value != saved_dft:
+            self.defaultChanged.emit(self._default_value)
+        if (old_min, old_max, old_fmt) != (self._min_value, self._max_value, self._val_fmt):
+            self.configChanged.emit(self.get_config())
+
+    def _values_as_html(self) -> str:
+        """Build an HTML table containing all current values.
+
+        Returns:
+            HTML string for a two-column table showing index and formatted value.
+            The active index is highlighted.
+        """
+        rows = [
+            f"""
+            <tr>
+                <th style="padding:2px 12px 6px 0; text-align:left; border-bottom:1px solid #999;">Index</th>
+                <th style="padding:2px 0 6px 0; text-align:left; border-bottom:1px solid #999;">{self.html_label}</th>
+            </tr>
+            """
+        ]
+        for i in range(self._arr_length):
+            value_text = self._arr_value_text(i)
+            if i == self._current_idx:
+                rows.append(
+                    f"""
+                    <tr style="background-color:#eaf3ff;">
+                        <td style="padding:2px 12px 2px 0; white-space:nowrap;" align="right">{i}:</td>
+                        <td style="padding:2px 0; white-space:nowrap;"><b>{value_text}</b> <span style="color:#888;">&larr; current</span></td>
+                    </tr>
+                    """
+                )
+            else:
+                rows.append(
+                    f"""
+                    <tr>
+                        <td style="padding:2px 12px 2px 0; white-space:nowrap;" align="right">{i}:</td>
+                        <td style="padding:2px 0; white-space:nowrap;"><b>{value_text}</b></td>
+                    </tr>
+                    """
+                )
+
+        return f"""
+        <table cellspacing="0" cellpadding="0">
+            {''.join(rows)}
+        </table>
+        """
+
+    def _open_show_values_dlg(self) -> None:
+        """Open a read-only dialog showing the formatted values table."""
+        dlg = QDialog(self)
+        dlg.setWindowTitle("Values")
+
+        text_box = QTextEdit(dlg)
+        text_box.setReadOnly(True)
+        text_box.setAcceptRichText(True)
+
+        html = self._values_as_html()
+        text_box.setHtml(html)
+
+        btn_box = QDialogButtonBox(QDialogButtonBox.Ok, parent=dlg)
+        btn_box.accepted.connect(dlg.accept)
+
+        layout = QVBoxLayout(dlg)
+        layout.addWidget(text_box)
+        layout.addWidget(btn_box)
+
+        doc = text_box.document()
+        doc.adjustSize()
+
+        doc_w = int(doc.idealWidth())
+        frame_w = 2 * text_box.frameWidth()
+        margins = text_box.contentsMargins().left() + text_box.contentsMargins().right()
+        scrollbar_w = text_box.style().pixelMetric(QStyle.PM_ScrollBarExtent)
+
+        dlg_w = doc_w + frame_w + margins + scrollbar_w + 30
+        dlg_h = min(700, 140 + 22 * self._arr_length)
+
+        dlg.resize(dlg_w, dlg_h)
+        dlg.exec()
+
+    # ----- public API -----
+    def get_value_text(self, idx: int) -> str:
+        """Return the formatted text for the value at a given index.
+
+        Args:
+            idx: Array index. Wrapped modulo the current array length.
+
+        Returns:
+            Formatted value text.
+        """
+        idx %= self._arr_length
+        return self._arr_value_text(idx)
+
+    def set_format(self, val_fmt: str) -> None:
+        """Update the display format and re-evaluate stored values.
+
+        Args:
+            val_fmt: New display format string.
+
+        Note:
+            All stored current and default finite values are rounded to the
+            new format. No signals are emitted.
+        """
+        super().set_format(val_fmt)
+        for i in range(self._arr_length):
+            self._current_arr[i] = self.evaluate_value(self._current_arr[i])
+            self._default_arr[i] = self.evaluate_value(self._default_arr[i])
+
+    def get_index(self) -> int:
+        """Return the currently selected array index.
+
+        Returns:
+            Current active index.
+        """
+        return self._current_idx
+
+    def set_index(self, idx: int) -> None:
+        """Select the active array index.
+
+        Args:
+            idx: New index. Wrapped modulo the current array length.
+        """
+        idx %= self._arr_length
+        self._current_idx = idx
+        self._update_slider_for_current_idx()
+
+    def get_arr_values(self) -> np.ndarray:
+        """Return a copy of the current array values.
+
+        Returns:
+            NumPy array containing finite values or infinities that reflect the
+            stored special-value state.
+        """
+        out = self._current_arr.copy()
+        for i, sv in enumerate(self._current_special_arr):
+            if sv == "+inf":
+                out[i] = math.inf
+            elif sv == "-inf":
+                out[i] = -math.inf
+        return out
+
+    def set_value(self, value, keep_default_value: bool = False) -> None:
+        """Set the active value and store it in the array (no signals)."""
+        super().set_value(value, keep_default_value)
+        self._store_active()
+
+    def set_default_value(self, value: float) -> None:
+        """Set the active default and store it in the array (no signals)."""
+        super().set_default_value(value)
+        self._store_active()
+
+    def set_arr_values(
+            self,
+            values: Sequence[float | str],
+            idx: int = 0,
+            default_preserve_mode: Literal["none", "first", "all"] = "none",
+            same_values_mode: Literal["ignore", "apply"] = "ignore",
+    ) -> None:
+        """Replace the stored current values array.
+
+        Args:
+            values: New values. Entries may be real numbers or ``±inf``
+                markers; each must satisfy the slider's limits and features.
+            idx: Index to select after updating the array. Wrapped modulo the new
+                array length.
+            default_preserve_mode: Policy for preserving old default values.
+
+                - ``"none"``: Reset all default values from ``values``.
+                - ``"first"``: Preserve only the previous default at index 0.
+                - ``"all"``: Preserve all previous defaults where possible.
+            same_values_mode: Policy controlling interaction with same-values
+                mode.
+
+                - ``"ignore"``: Store ``values`` as provided.
+                - ``"apply"``: If same-values mode is enabled, force all entries
+                  (current, default and ±inf state) to match the selected entry.
+
+        Note:
+            All entries are validated before anything changes. If the new
+            values extend beyond the current editable range, the range is
+            expanded to include them. No signals are emitted.
+
+        Raises:
+            ValueError: If ``values`` is empty, an entry violates the limits or
+                is a ±inf marker that is not permitted, or a mode is invalid.
+            TypeError: If an entry is neither a real number nor a ±inf marker.
+        """
+        if default_preserve_mode not in {"none", "first", "all"}:
+            raise ValueError("default_preserve_mode must be one of: 'none', 'first', 'all'")
+        if same_values_mode not in {"ignore", "apply"}:
+            raise ValueError("same_values_mode must be one of: 'ignore', 'apply'")
+
+        N = len(values)
+        if N == 0:
+            raise ValueError("values must not be empty")
+
+        # validate everything before touching the widget
+        new_current: list[float] = []
+        new_special: list[SpecialValue | None] = []
+        for i, v in enumerate(values):
+            sv = normalize_special_value(v)
+            try:
+                if sv is None:
+                    new_current.append(self._validate_value(v))
+                else:
+                    self._check_special_permitted(sv)
+                    new_current.append(self._max_value if sv == "+inf" else self._min_value)
+            except (TypeError, ValueError) as e:
+                raise type(e)(f"values[{i}]: {e}") from None
+            new_special.append(sv)
+
+        selected_idx = idx % N
+        cur_arr = np.asarray(new_current, dtype=float)
+        dft_arr = cur_arr.copy()
+
+        if default_preserve_mode == "first":
+            dft_arr[0] = self._default_arr[0]
+        elif default_preserve_mode == "all":
+            n_copy = min(len(self._default_arr), N)
+            dft_arr[:n_copy] = self._default_arr[:n_copy]
+
+        if same_values_mode == "apply" and self._use_same_values:
+            cur_arr[:] = cur_arr[selected_idx]
+            dft_arr[:] = dft_arr[selected_idx]
+            new_special = [new_special[selected_idx]] * N
+
+        # commit
+        self._arr_length = N
+        self._current_arr = cur_arr
+        self._default_arr = dft_arr
+        self._current_special_arr = new_special
+        self._min_value = min(self._min_value, float(cur_arr.min()))
+        self._max_value = max(self._max_value, float(cur_arr.max()))
+
+        self.set_index(selected_idx)
+        self._update_value_width()
+
+    def set_range(self, min_val: float, max_val: float) -> None:
+        """Set the editable numeric range and clamp stored values if needed.
+
+        Args:
+            min_val: New minimum value.
+            max_val: New maximum value.
+
+        Note:
+            Both the current and default arrays are clamped to the new range. The
+            underlying slider, labels, and layout are refreshed. No signals are
+            emitted.
+
+        Raises:
+            ValueError: If ``min_val >= max_val`` or either bound violates the
+                hard-limit constraints.
+        """
+        new_min_val, new_max_val = self._validate_range(min_val, max_val)
+        self._min_value = new_min_val
+        self._max_value = new_max_val
+        for i in range(self._arr_length):
+            cur_val = self._current_arr[i]
+            dft_val = self._default_arr[i]
+            if cur_val < new_min_val:
+                self._current_arr[i] = new_min_val
+            elif cur_val > new_max_val:
+                self._current_arr[i] = new_max_val
+            if dft_val < new_min_val:
+                self._default_arr[i] = new_min_val
+            elif dft_val > new_max_val:
+                self._default_arr[i] = new_max_val
+
+        self._current_value = float(self._current_arr[self._current_idx])
+        self._default_value = float(self._default_arr[self._current_idx])
+
+        self._update_mapping_anchors()
+        with self._quiet_updates():
+            self._apply_range_to_slider()
+            self._slider.setValue(self._value_to_pos(self._current_value))
+        self._update_all_labels()
+        self._update_value_width()
+        self._update_layout()
+
+    def set_use_same_values(self, same: bool) -> None:
+        """Enable or disable same-values mode.
+
+        When enabled, all entries take the active value, default and special
+        state. No signals are emitted.
+
+        Args:
+            same: Whether all entries should track the currently selected value.
+        """
+        self._use_same_values = bool(same)
+        if same:
+            self._store_active()
+        self._update_slider_for_current_idx()
+
+    def get_arr_length(self) -> int:
+        """Return the number of stored values.
+
+        Returns:
+            Length of the current/default arrays.
+        """
+        return self._arr_length
+
+    def set_arr_length(self, arr_length: int) -> None:
+        """Resize the stored arrays.
+
+        Args:
+            arr_length: New array length. Must be greater than zero.
+
+        Note:
+            When extending the arrays, new entries are filled with the value,
+            default value and ±inf state from index 0. When shrinking, trailing
+            entries are discarded. If the current index becomes invalid after
+            shrinking, the last remaining index is selected. No signals are
+            emitted.
+
+        Raises:
+            ValueError: If ``arr_length <= 0``.
+        """
+        if arr_length <= 0:
+            raise ValueError("arr_length must be > 0")
+
+        old_length = self._arr_length
+        if old_length == arr_length:
+            return
+
+        if old_length < arr_length:
+            fill_cur = self._current_arr[0]
+            fill_dft = self._default_arr[0]
+            fill_cur_sv = self._current_special_arr[0]
+
+            n_add = arr_length - old_length
+            self._current_arr = np.concatenate([
+                self._current_arr,
+                np.full(n_add, fill_cur, dtype=self._current_arr.dtype),
+            ])
+            self._default_arr = np.concatenate([
+                self._default_arr,
+                np.full(n_add, fill_dft, dtype=self._default_arr.dtype),
+            ])
+            self._current_special_arr.extend([fill_cur_sv] * n_add)
+        else:
+            self._current_arr = self._current_arr[:arr_length]
+            self._default_arr = self._default_arr[:arr_length]
+            self._current_special_arr = self._current_special_arr[:arr_length]
+
+        self._arr_length = arr_length
+        if self._current_idx >= self._arr_length:
+            self._current_idx = self._arr_length - 1
+        self._update_slider_for_current_idx()
+        self._update_value_width()