GUI documentation

copienator_gui/app.py

@@ -60,6 +60,65 @@ ANNOTATION_VARIANT_DIRECTORIES = {
 }
 
 
+class Tooltip:
+    """Small delayed tooltip for Tk and ttk widgets."""
+
+    def __init__(self, widget: tk.Widget, text: str, delay_ms: int = 450) -> None:
+        self.widget = widget
+        self.text = text
+        self.delay_ms = delay_ms
+        self._after_id: str | None = None
+        self.window: tk.Toplevel | None = None
+        widget.bind("<Enter>", self._schedule, add="+")
+        widget.bind("<Leave>", self.hide, add="+")
+        widget.bind("<ButtonPress>", self.hide, add="+")
+
+    def _schedule(self, _event: tk.Event | None = None) -> None:
+        self.hide()
+        self._after_id = self.widget.after(self.delay_ms, self.show)
+
+    def show(self) -> None:
+        self._after_id = None
+        if self.window is not None or not self.widget.winfo_exists():
+            return
+        self.window = tk.Toplevel(self.widget)
+        self.window.wm_overrideredirect(True)
+        self.window.attributes("-topmost", True)
+        x = self.widget.winfo_rootx() + 12
+        y = self.widget.winfo_rooty() + self.widget.winfo_height() + 6
+        self.window.wm_geometry(f"+{x}+{y}")
+        tk.Label(
+            self.window,
+            text=self.text,
+            justify="left",
+            wraplength=430,
+            background="#fffbd8",
+            foreground="#202020",
+            relief="solid",
+            borderwidth=1,
+            padx=8,
+            pady=5,
+        ).pack()
+
+    def hide(self, _event: tk.Event | None = None) -> None:
+        if self._after_id is not None:
+            try:
+                self.widget.after_cancel(self._after_id)
+            except tk.TclError:
+                pass
+            self._after_id = None
+        if self.window is not None:
+            self.window.destroy()
+            self.window = None
+
+
+def attach_tooltip(widget: tk.Widget, text: str) -> Tooltip:
+    tooltip = Tooltip(widget, text)
+    # Keep the tooltip easy to inspect and alive for as long as its widget.
+    widget._copienator_tooltip = tooltip  # type: ignore[attr-defined]
+    return tooltip
+
+
 def copy_pdf_paths(evaluation: Path) -> list[Path]:
     """List the most relevant version of each scanned copy."""
     locations = (evaluation / "Copies", evaluation, evaluation / "Copies Originales")
@@ -231,19 +290,33 @@ class CopienatorApp(tk.Tk):
         )
         environment = ttk.Frame(top)
         environment.grid(row=1, column=2, columnspan=5, sticky="e", pady=(7, 0))
-        ttk.Checkbutton(
+        proxy_toggle = ttk.Checkbutton(
             environment,
             text="Utiliser le proxy HTTPS",
             variable=self.use_proxy_var,
             command=self._toggle_proxy,
-        ).pack(side="left", padx=(0, 6))
+        )
+        proxy_toggle.pack(side="left", padx=(0, 6))
+        attach_tooltip(
+            proxy_toggle,
+            "Active le proxy HTTPS configuré dans le champ voisin pour les commandes lancées par le GUI.",
+        )
         self.proxy_entry = ttk.Entry(environment, textvariable=self.proxy_var, width=28, state="disabled")
         self.proxy_entry.pack(side="left")
-        ttk.Checkbutton(
+        attach_tooltip(
+            self.proxy_entry,
+            "Adresse du proxy HTTPS transmise aux commandes lorsque l’option de proxy est activée.",
+        )
+        verbose_toggle = ttk.Checkbutton(
             environment,
-            text="Afficher les détails en cas d’erreur (--verbose)",
+            text="Détails d’erreur ⓘ",
             variable=self.verbose_var,
-        ).pack(side="left", padx=(10, 0))
+        )
+        verbose_toggle.pack(side="left", padx=(10, 0))
+        attach_tooltip(
+            verbose_toggle,
+            "Ajoute --verbose aux commandes compatibles afin d’afficher la trace complète lorsqu’une erreur inattendue survient.",
+        )
         profile = "standard + personnel" if show_personal_steps else "standard"
         ttk.Label(environment, text=f"Profil : {profile}").pack(side="left", padx=(12, 0))
 
@@ -647,7 +720,9 @@ class CopienatorApp(tk.Tk):
             choices = spec.choices
             if spec.name == "annotation_dir" and step.id in {"export", "import"}:
                 choices, value = self._annotation_directory_choices(step.id)
-            ttk.Label(self.form, text=spec.label).grid(row=row, column=0, sticky="nw", pady=4, padx=(0, 8))
+            argument_label = ttk.Label(self.form, text=f"{spec.label} ⓘ")
+            argument_label.grid(row=row, column=0, sticky="nw", pady=4, padx=(0, 8))
+            attach_tooltip(argument_label, spec.help)
             if spec.kind == "bool":
                 variable: tk.Variable = tk.BooleanVar(value=bool(value))
                 widget = ttk.Checkbutton(self.form, variable=variable)
@@ -672,11 +747,7 @@ class CopienatorApp(tk.Tk):
                     )
             self.arg_vars[spec.name] = variable
             variable.trace_add("write", lambda *_args: self._update_command_preview())
-            if spec.help:
-                ttk.Label(self.form, text=spec.help, foreground="#666666", wraplength=540).grid(
-                    row=row + 1, column=1, sticky="w"
-                )
-                row += 1
+            attach_tooltip(widget, spec.help)
             row += 1
 
         show_extra = bool(step.extra_arguments_help) and (
@@ -684,18 +755,14 @@ class CopienatorApp(tk.Tk):
             or variant.id in step.extra_arguments_variants
         )
         if show_extra and not step.is_manual and step.section != REFAIRE_SECTION:
-            ttk.Label(self.form, text="Arguments supplémentaires").grid(
+            extra_label = ttk.Label(self.form, text="Arguments supplémentaires ⓘ")
+            extra_label.grid(
                 row=row, column=0, sticky="w", pady=(10, 4), padx=(0, 8)
             )
-            ttk.Entry(self.form, textvariable=self.extra_var).grid(row=row, column=1, sticky="ew", pady=(10, 4))
-            row += 1
-            ttk.Label(
-                self.form,
-                text=step.extra_arguments_help,
-                foreground="#666666",
-                wraplength=540,
-                justify="left",
-            ).grid(row=row, column=1, sticky="w")
+            extra_entry = ttk.Entry(self.form, textvariable=self.extra_var)
+            extra_entry.grid(row=row, column=1, sticky="ew", pady=(10, 4))
+            attach_tooltip(extra_label, step.extra_arguments_help)
+            attach_tooltip(extra_entry, step.extra_arguments_help)
             row += 1
 
         if self.show_personal_steps and step.id == "statement":