flextool 4.0.0__py3-none-any.whl

flextool/gui/dialogs/group_picker.py

@@ -0,0 +1,299 @@
+"""Modal dialog for picking parameter_group names to include in an export.
+
+Used by :class:`AddDialog` when the user adds an empty FlexTool input
+Excel: the dialog shows every parameter_group from the source DB as a
+checkbox row, with the *required* groups highlighted at the top and a
+hover tooltip explaining why they matter.
+
+Theming
+-------
+The dialog reads the active ttk theme's background/foreground colours
+(via :class:`ttk.Style`) and applies them to the plain ``tk`` widgets it
+uses for the row list, so it stays readable under both light and dark
+themes — the rest of the FlexTool GUI uses the same pattern.
+"""
+from __future__ import annotations
+
+import tkinter as tk
+from tkinter import messagebox, ttk
+from typing import Sequence
+
+from flextool.gui.hover_tooltip import attach_tooltip
+
+
+_REQUIRED_TOOLTIP = (
+    "Required for a functioning FlexTool model.\n"
+    "You can still uncheck this — a working model can be assembled by "
+    "combining data from multiple input sources in Spine Toolbox."
+)
+
+# Highlight tints chosen to read well on top of light and dark theme
+# surfaces.  Both keep enough luminance for the forced-black text on
+# required rows to stay legible.
+_HIGHLIGHT_LIGHT = "#fff4c2"
+_HIGHLIGHT_DARK = "#e8d488"
+
+
+class GroupPickerDialog(tk.Toplevel):
+    """Modal picker for parameter_group selection.
+
+    After the dialog closes, ``self.result`` is one of:
+
+    * ``None`` — user cancelled, do not export.
+    * ``"all"`` — every group was checked; caller should pass
+      ``include_groups=None`` to ``export_to_excel`` (preserves the
+      original unfiltered semantics, including any ungrouped params).
+    * ``list[str]`` — the explicitly selected group names.
+    """
+
+    def __init__(
+        self,
+        parent: tk.Misc,
+        groups: Sequence[dict],
+        required: Sequence[str],
+    ) -> None:
+        super().__init__(parent)
+        self.title("Choose parameter groups")
+        self.transient(parent)
+        self.grab_set()
+        self.resizable(False, True)
+
+        self.result: list[str] | str | None = None
+
+        # Pull theme colours so plain tk widgets match dark / light mode.
+        style = ttk.Style(self)
+        self._theme_bg = (
+            style.lookup("TFrame", "background")
+            or self.cget("background")
+        )
+        self._theme_fg = style.lookup("TLabel", "foreground") or "black"
+        self._highlight_bg = (
+            _HIGHLIGHT_DARK
+            if _is_dark_color(self, self._theme_bg)
+            else _HIGHLIGHT_LIGHT
+        )
+
+        # Build display order: required first (in YAML order), then
+        # remaining groups sorted by priority then name.
+        by_name = {g["name"]: g for g in groups}
+        required_present = [name for name in required if name in by_name]
+        required_set = set(required_present)
+        remaining = [g for g in groups if g["name"] not in required_set]
+        remaining.sort(key=lambda g: (g.get("priority") or 999, g["name"]))
+        ordered: list[dict] = [by_name[n] for n in required_present] + remaining
+
+        self._vars: dict[str, tk.BooleanVar] = {
+            g["name"]: tk.BooleanVar(value=True) for g in ordered
+        }
+        self._all_names: list[str] = [g["name"] for g in ordered]
+
+        self._build_ui(ordered, required_set)
+
+        self.protocol("WM_DELETE_WINDOW", self._on_cancel)
+        self._center_on_parent(parent)
+        parent.wait_window(self)
+
+    # ------------------------------------------------------------------
+    # UI construction
+    # ------------------------------------------------------------------
+
+    def _build_ui(
+        self, ordered: list[dict], required_set: set[str],
+    ) -> None:
+        # Outer container — ttk.Frame inherits theme automatically.
+        outer = ttk.Frame(self, padding=10)
+        outer.pack(fill="both", expand=True)
+
+        intro = ttk.Label(
+            outer,
+            text=(
+                "Select which parameter groups to include in the new Excel "
+                "file.\nHighlighted rows are required for a functioning "
+                "FlexTool model."
+            ),
+            justify="left",
+        )
+        intro.pack(anchor="w", pady=(0, 8))
+
+        # Bulk action row
+        bulk = ttk.Frame(outer)
+        bulk.pack(fill="x", pady=(0, 6))
+        ttk.Button(
+            bulk, text="Select all", command=self._on_select_all,
+        ).pack(side="left", padx=(0, 4))
+        ttk.Button(
+            bulk, text="Required only",
+            command=lambda: self._on_required_only(required_set),
+        ).pack(side="left", padx=(0, 4))
+        ttk.Button(
+            bulk, text="Clear all", command=self._on_clear_all,
+        ).pack(side="left")
+
+        # Scrollable group list — uses tk.Frame/Canvas so we can colour
+        # the highlight rows.  Background pulled from the ttk theme.
+        list_frame = tk.Frame(
+            outer, bg=self._theme_bg, highlightthickness=1,
+            highlightbackground="#888888",
+        )
+        list_frame.pack(fill="both", expand=True)
+
+        # Canvas size derived from font metrics so the dialog scales with
+        # the user's font size instead of being pinned at 360×570 px.
+        from flextool.gui.ui_metrics import get_metrics
+        _m = get_metrics(self)
+        canvas = tk.Canvas(
+            list_frame, bg=self._theme_bg, highlightthickness=0,
+            width=_m.cw * 36, height=_m.lh * 30,
+        )
+        canvas.pack(side="left", fill="both", expand=True)
+
+        sb = ttk.Scrollbar(list_frame, orient="vertical", command=canvas.yview)
+        sb.pack(side="right", fill="y")
+        canvas.configure(yscrollcommand=sb.set)
+
+        rows_frame = tk.Frame(canvas, bg=self._theme_bg)
+        canvas.create_window((0, 0), window=rows_frame, anchor="nw")
+
+        def _on_rows_configure(_event: tk.Event) -> None:  # type: ignore[type-arg]
+            canvas.configure(scrollregion=canvas.bbox("all"))
+
+        rows_frame.bind("<Configure>", _on_rows_configure)
+
+        # Mouse wheel scroll
+        def _on_mousewheel(event: tk.Event) -> None:  # type: ignore[type-arg]
+            canvas.yview_scroll(-int(event.delta / 120), "units")
+
+        canvas.bind("<Enter>", lambda _e: canvas.bind_all("<MouseWheel>", _on_mousewheel))
+        canvas.bind("<Leave>", lambda _e: canvas.unbind_all("<MouseWheel>"))
+
+        # Render rows
+        for g in ordered:
+            self._make_row(rows_frame, g, g["name"] in required_set)
+
+        # OK / Cancel
+        btn_row = ttk.Frame(outer)
+        btn_row.pack(fill="x", pady=(10, 0))
+        ttk.Button(btn_row, text="Cancel", command=self._on_cancel).pack(side="right")
+        ttk.Button(btn_row, text="OK", command=self._on_ok).pack(side="right", padx=(0, 6))
+
+    def _make_row(
+        self, parent: tk.Widget, group: dict, is_required: bool,
+    ) -> None:
+        bg = self._highlight_bg if is_required else self._theme_bg
+        # On highlight rows we also override the foreground so text stays
+        # readable on the yellow tint regardless of the parent theme.
+        fg = "#000000" if is_required else self._theme_fg
+
+        row = tk.Frame(parent, bg=bg)
+        row.pack(fill="x")
+
+        # Color swatch
+        swatch_color = _normalise_color(group.get("color"))
+        swatch_frame = tk.Frame(row, bg=bg, width=22, height=22)
+        swatch_frame.pack_propagate(False)
+        swatch_frame.pack(side="left", padx=(8, 6), pady=2)
+        swatch = tk.Frame(
+            swatch_frame, bg=swatch_color or "#cccccc",
+            highlightthickness=1, highlightbackground="#888888",
+        )
+        swatch.place(x=4, y=4, width=14, height=14)
+
+        cb = tk.Checkbutton(
+            row,
+            text=group["name"],
+            variable=self._vars[group["name"]],
+            bg=bg, fg=fg,
+            activebackground=bg, activeforeground=fg,
+            selectcolor=bg,           # checkbox indicator interior
+            highlightthickness=0,
+            anchor="w",
+        )
+        cb.pack(side="left", fill="x", expand=True, padx=(0, 8))
+
+        if is_required:
+            attach_tooltip(row, _REQUIRED_TOOLTIP)
+            attach_tooltip(cb, _REQUIRED_TOOLTIP)
+            attach_tooltip(swatch, _REQUIRED_TOOLTIP)
+
+    # ------------------------------------------------------------------
+    # Button handlers
+    # ------------------------------------------------------------------
+
+    def _on_select_all(self) -> None:
+        for v in self._vars.values():
+            v.set(True)
+
+    def _on_clear_all(self) -> None:
+        for v in self._vars.values():
+            v.set(False)
+
+    def _on_required_only(self, required_set: set[str]) -> None:
+        for name, v in self._vars.items():
+            v.set(name in required_set)
+
+    def _on_ok(self) -> None:
+        selected = [n for n in self._all_names if self._vars[n].get()]
+        if not selected:
+            messagebox.showwarning(
+                "No groups selected",
+                "Select at least one group, or press Cancel.",
+                parent=self,
+            )
+            return
+        if len(selected) == len(self._all_names):
+            self.result = "all"
+        else:
+            self.result = selected
+        self.destroy()
+
+    def _on_cancel(self) -> None:
+        self.result = None
+        self.destroy()
+
+    # ------------------------------------------------------------------
+    # Layout helpers
+    # ------------------------------------------------------------------
+
+    def _center_on_parent(self, parent: tk.Misc) -> None:
+        self.update_idletasks()
+        try:
+            pw = parent.winfo_width()
+            ph = parent.winfo_height()
+            px = parent.winfo_rootx()
+            py = parent.winfo_rooty()
+        except tk.TclError:
+            return
+        dw = self.winfo_width()
+        dh = self.winfo_height()
+        self.geometry(f"+{px + (pw - dw) // 2}+{py + (ph - dh) // 2}")
+
+
+def _normalise_color(value: str | None) -> str | None:
+    """Coerce a hex colour string to '#rrggbb' form for Tk, else None."""
+    if not value:
+        return None
+    s = str(value).strip()
+    if not s:
+        return None
+    if s.startswith("#"):
+        return s
+    if len(s) in (6, 8) and all(c in "0123456789abcdefABCDEF" for c in s):
+        return f"#{s[:6]}"
+    return None
+
+
+def _is_dark_color(widget: tk.Widget, color: str) -> bool:
+    """Return True when *color* is a dark surface (so we should use a
+    dark-theme highlight tint).
+
+    Uses Tk's built-in colour parser so it accepts hex, rgb tuples,
+    and X11 / system colour names.  Falls back to "light" on parse
+    failure.
+    """
+    try:
+        r, g, b = widget.winfo_rgb(color)
+    except tk.TclError:
+        return False
+    # winfo_rgb returns 16-bit channels (0..65535).
+    luminance = 0.299 * r + 0.587 * g + 0.114 * b
+    return luminance < 32768

flextool/gui/dialogs/migration_consent_dialog.py

@@ -0,0 +1,106 @@
+"""Consent dialog for migrating externally-referenced FlexTool databases."""
+from __future__ import annotations
+
+import tkinter as tk
+from pathlib import Path
+from tkinter import ttk
+from typing import Literal
+
+
+def ask_external_migration_consent(
+    parent: tk.Misc,
+    external_files: list[tuple[str, Path, int, int]],
+) -> Literal["in_place", "copy_to_project", "cancel"]:
+    """Ask the user how to migrate external (non-project) input source files.
+
+    ``external_files`` is a list of ``(source_name, abs_path,
+    current_version, target_version)`` tuples; all entries share the
+    same target version.
+
+    Returns:
+        ``"in_place"`` to migrate the external files where they live,
+        ``"copy_to_project"`` to copy them into the project folder and
+        migrate the copies, or ``"cancel"`` to abort.
+    """
+    target_version = external_files[0][3]
+
+    dlg = tk.Toplevel(parent)
+    dlg.title("External database migration")
+    dlg.transient(parent)
+    dlg.grab_set()
+    dlg.resizable(False, False)
+
+    result: Literal["in_place", "copy_to_project", "cancel"] = "cancel"
+
+    msg = (
+        "The following input source file(s) are stored OUTSIDE the "
+        f"project folder and need to be migrated to FlexTool DB "
+        f"version {target_version}:"
+    )
+    lbl = ttk.Label(dlg, text=msg, wraplength=480, justify="left")
+    lbl.pack(padx=16, pady=(16, 8), anchor="w")
+
+    list_frame = ttk.Frame(dlg, borderwidth=1, relief="sunken")
+    list_frame.pack(padx=16, pady=(0, 8), fill="x")
+
+    height = min(6, len(external_files))
+    listbox = tk.Listbox(list_frame, height=height, activestyle="none")
+    h_scroll = ttk.Scrollbar(
+        list_frame, orient="horizontal", command=listbox.xview,
+    )
+    listbox.configure(xscrollcommand=h_scroll.set)
+
+    for source_name, abs_path, current_version, _t in external_files:
+        listbox.insert(
+            "end",
+            f"{source_name}  —  {abs_path}  "
+            f"(v{current_version} → v{target_version})",
+        )
+
+    listbox.pack(side="top", fill="x")
+    h_scroll.pack(side="bottom", fill="x")
+
+    note = ttk.Label(
+        dlg,
+        text="Migration modifies the file in place. Choose how to proceed:",
+        wraplength=480,
+        justify="left",
+    )
+    note.pack(padx=16, pady=(0, 8), anchor="w")
+
+    btn_frame = ttk.Frame(dlg)
+    btn_frame.pack(padx=16, pady=(4, 16))
+
+    def _choose(choice: Literal["in_place", "copy_to_project", "cancel"]) -> None:
+        nonlocal result
+        result = choice
+        dlg.destroy()
+
+    ttk.Button(
+        btn_frame, text="Migrate in place",
+        command=lambda: _choose("in_place"),
+    ).pack(side="left", padx=4)
+    ttk.Button(
+        btn_frame, text="Copy all to project and migrate",
+        command=lambda: _choose("copy_to_project"),
+    ).pack(side="left", padx=4)
+    ttk.Button(
+        btn_frame, text="Cancel",
+        command=lambda: _choose("cancel"),
+    ).pack(side="left", padx=4)
+
+    dlg.protocol("WM_DELETE_WINDOW", lambda: _choose("cancel"))
+    dlg.bind("<Escape>", lambda _e: _choose("cancel"))
+
+    # Center on parent
+    dlg.update_idletasks()
+    pw = parent.winfo_width()
+    ph = parent.winfo_height()
+    px = parent.winfo_rootx()
+    py = parent.winfo_rooty()
+    dw = dlg.winfo_width()
+    dh = dlg.winfo_height()
+    dlg.geometry(f"+{px + (pw - dw) // 2}+{py + (ph - dh) // 2}")
+
+    parent.wait_window(dlg)
+    return result

flextool/gui/dialogs/migration_progress_dialog.py

@@ -0,0 +1,237 @@
+"""Modal progress dialog for the automatic FlexTool DB migration."""
+from __future__ import annotations
+
+import queue
+import tkinter as tk
+from tkinter import ttk
+
+# Mirrors flextool.gui.main_window._SPINNER_FRAMES; duplicated to keep this
+# dialog free of dependencies on main_window.
+_SPINNER_FRAMES = ["◐", "◓", "◑", "◒"]  # rotating circle (Geometric Shapes; render on Windows Tk, unlike the old U+29D6/7 hourglasses)
+
+
+class MigrationProgressDialog(tk.Toplevel):
+    """Modal progress dialog for the automatic DB migration.
+
+    The caller runs the migration in a worker thread. This dialog drives
+    the spinner from the Tk main thread via ``after`` and exposes:
+
+      - ``update_status(text: str)`` — thread-safe; schedules a label
+        update on the main thread.
+      - ``mark_finished()`` — thread-safe; schedules dialog close.
+      - ``cancel_requested`` — read-only ``bool`` property; True after
+        the user clicked Cancel (worker polls this via ``cancel_check``).
+
+    The dialog is shown by constructing it and then calling
+    ``parent.wait_window(self)``.  It does not spawn the worker thread
+    itself — the caller is responsible for that.
+    """
+
+    def __init__(
+        self,
+        parent: tk.Misc,
+        title: str = "Migrating database…",
+        initial_status: str = "Preparing…",
+    ) -> None:
+        super().__init__(parent)
+        self.title(title)
+        self.transient(parent)
+        self.resizable(False, False)
+
+        self._cancel_requested: bool = False
+        self._finished: bool = False
+        # The ``after`` ids must be read/written from the main thread only.
+        self._spinner_after_id: str | None = None
+        self._pump_after_id: str | None = None
+        self._spinner_idx: int = 0
+        # Worker threads enqueue updates here; a main-thread pump applies them.
+        # tkinter is not thread-safe (even ``after`` fails off the main thread
+        # on macOS), so the public methods must not touch Tk.
+        self._ui_queue: queue.Queue = queue.Queue()
+
+        self._status_var = tk.StringVar(value=initial_status)
+        status_lbl = ttk.Label(
+            self,
+            textvariable=self._status_var,
+            wraplength=440,
+            justify="left",
+        )
+        status_lbl.pack(padx=16, pady=(16, 8), anchor="w", fill="x")
+
+        self._spinner_var = tk.StringVar(value=_SPINNER_FRAMES[0])
+        spinner_lbl = ttk.Label(
+            self,
+            textvariable=self._spinner_var,
+            font=("TkDefaultFont", 16),
+            justify="left",
+        )
+        spinner_lbl.pack(padx=16, pady=(0, 8), anchor="w")
+
+        note_lbl = ttk.Label(
+            self,
+            text=(
+                "The interface is locked until the migration finishes. "
+                "Detailed progress is shown in the Execution window. "
+                "Click Cancel to stop after the current step — a cancelled "
+                "database is restored to its original state."
+            ),
+            wraplength=440,
+            justify="left",
+        )
+        note_lbl.pack(padx=16, pady=(0, 8), anchor="w", fill="x")
+
+        btn_frame = ttk.Frame(self)
+        btn_frame.pack(padx=16, pady=(4, 16), fill="x")
+
+        self._cancel_btn = ttk.Button(
+            btn_frame, text="Cancel", command=self._on_cancel,
+        )
+        self._cancel_btn.pack(side="right")
+
+        self.protocol("WM_DELETE_WINDOW", self._on_cancel)
+        self.bind("<Escape>", lambda _e: self._on_cancel())
+
+        # Center on parent
+        self.update_idletasks()
+        pw = parent.winfo_width()
+        ph = parent.winfo_height()
+        px = parent.winfo_rootx()
+        py = parent.winfo_rooty()
+        dw = self.winfo_width()
+        dh = self.winfo_height()
+        self.geometry(f"+{px + (pw - dw) // 2}+{py + (ph - dh) // 2}")
+
+        # Kick off the spinner animation and the worker-update pump.
+        self._spinner_after_id = self.after(200, self._tick_spinner)
+        self._pump_after_id = self.after(50, self._pump_queue)
+
+        # Grab input once the window is actually mapped. ``grab_set`` raises
+        # "grab failed: window not viewable" if called before Tk has mapped
+        # the Toplevel — which happens when this dialog is constructed from
+        # inside another Tk callback (e.g. the project-combo selection).
+        self._install_grab()
+
+    def _install_grab(self) -> None:
+        """Grab input once the window is viewable, retrying on the main thread."""
+        if self._finished or not self.winfo_exists():
+            return
+        if self.winfo_viewable():
+            try:
+                self.grab_set()
+            except tk.TclError:
+                pass
+            return
+        self.after(50, self._install_grab)
+
+    # ── Public API (thread-safe wrappers) ───────────────────────────
+
+    @property
+    def cancel_requested(self) -> bool:
+        """Whether the user has requested cancellation."""
+        return self._cancel_requested
+
+    def update_status(self, text: str) -> None:
+        """Thread-safe: enqueue a status-label update (no Tk call here)."""
+        self._ui_queue.put(("status", text))
+
+    def mark_finished(self) -> None:
+        """Thread-safe: enqueue dialog close (no Tk call here)."""
+        self._ui_queue.put(("finish", None))
+
+    # ── Main-thread helpers ─────────────────────────────────────────
+
+    def _pump_queue(self) -> None:
+        """Apply queued worker updates on the main thread, then reschedule.
+
+        Drains the whole queue each tick, applying only the most recent status
+        (intermediate ones are stale) and closing if a finish was requested.
+        """
+        if self._finished:
+            return
+        latest_status: str | None = None
+        finish = False
+        try:
+            while True:
+                kind, payload = self._ui_queue.get_nowait()
+                if kind == "status":
+                    latest_status = payload
+                elif kind == "finish":
+                    finish = True
+        except queue.Empty:
+            pass
+
+        if latest_status is not None:
+            self._set_status(latest_status)
+        if finish:
+            self._finish()
+            return
+        self._pump_after_id = self.after(50, self._pump_queue)
+
+    def _set_status(self, text: str) -> None:
+        if self._finished:
+            return
+        try:
+            self._status_var.set(text)
+        except tk.TclError:
+            pass
+
+    def _finish(self) -> None:
+        if self._finished:
+            return
+        self._finished = True
+        if self._spinner_after_id is not None:
+            try:
+                self.after_cancel(self._spinner_after_id)
+            except tk.TclError:
+                pass
+            self._spinner_after_id = None
+        if self._pump_after_id is not None:
+            try:
+                self.after_cancel(self._pump_after_id)
+            except tk.TclError:
+                pass
+            self._pump_after_id = None
+        try:
+            self.grab_release()
+        except tk.TclError:
+            pass
+        try:
+            self.destroy()
+        except tk.TclError:
+            pass
+
+    def _tick_spinner(self) -> None:
+        if self._finished:
+            return
+        self._spinner_idx = (self._spinner_idx + 1) % len(_SPINNER_FRAMES)
+        try:
+            self._spinner_var.set(_SPINNER_FRAMES[self._spinner_idx])
+        except tk.TclError:
+            return
+        self._spinner_after_id = self.after(200, self._tick_spinner)
+
+    def _on_cancel(self) -> None:
+        if self._cancel_requested:
+            return
+        self._cancel_requested = True
+        try:
+            self._cancel_btn.configure(
+                state="disabled", text="Cancelling…",
+            )
+        except tk.TclError:
+            pass
+
+    def destroy(self) -> None:  # noqa: D401 - override for cleanup
+        if self._spinner_after_id is not None:
+            try:
+                self.after_cancel(self._spinner_after_id)
+            except tk.TclError:
+                pass
+            self._spinner_after_id = None
+        if self._pump_after_id is not None:
+            try:
+                self.after_cancel(self._pump_after_id)
+            except tk.TclError:
+                pass
+            self._pump_after_id = None
+        super().destroy()