Enhance interactive fitting: add figure-level help text and update example usage to include "help"

CSSFrancis · CSSFrancis · commit 48102dbb19e8 · 2026-04-06T07:13:48.000-05:00
diff --git a/Examples/Interactive/plot_interactive_fitting.py b/Examples/Interactive/plot_interactive_fitting.py
@@ -52,7 +52,11 @@ def gaussian(x, amp, mu, sigma):
 
 # ── Figure ─────────────────────────────────────────────────────────────────
 
-fig, ax = apl.subplots(1, 1, figsize=(720, 380))
+fig, ax = apl.subplots(1, 1, figsize=(720, 380),
+    help="Click a coloured line  →  show/hide its widgets\n"
+         "Drag circle handle     →  move peak center (μ) and amplitude (A)\n"
+         "Drag range edge        →  widen / narrow the width (σ)\n"
+         "press: f               →  run least-squares fit")
 plot = ax.plot(signal, axes=[x], color="#adb5bd", linewidth=1.5,
                alpha=0.6, label="data")
 #
diff --git a/anyplotlib/__init__.py b/anyplotlib/__init__.py
@@ -7,11 +7,17 @@
     VLineWidget, HLineWidget, RangeWidget,
 )
 
+# ── Global help flag ──────────────────────────────────────────────────────
+# Set to False to suppress help badges on all figures in this session.
+# Default True: badges appear whenever a figure has help text set.
+show_help: bool = True
+
 __all__ = [
     "Figure", "GridSpec", "SubplotSpec", "subplots",
     "Axes", "Plot1D", "Plot2D", "PlotMesh", "Plot3D", "PlotBar",
     "CallbackRegistry", "Event",
     "Widget", "RectangleWidget", "CircleWidget", "AnnularWidget",
     "CrosshairWidget", "PolygonWidget", "LabelWidget",
     "VLineWidget", "HLineWidget", "RangeWidget",
+    "show_help",
 ]
diff --git a/anyplotlib/figure.py b/anyplotlib/figure.py
@@ -74,6 +74,9 @@ class Figure(anywidget.AnyWidget):
     event_json     = traitlets.Unicode("{}").tag(sync=True)
     # When True the JS renderer shows a per-panel FPS / frame-time overlay.
     display_stats  = traitlets.Bool(False).tag(sync=True)
+    # Figure-level help text shown in a '?' badge overlay in JS.
+    # Empty string means no badge.  Gated by apl.show_help at the Python level.
+    help_text      = traitlets.Unicode("").tag(sync=True)
     _esm = _ESM_SOURCE
     # Static CSS injected by anywidget alongside _esm.
     # .apl-scale-wrap  — outer container; width:100% means it always fills
@@ -111,7 +114,7 @@ class Figure(anywidget.AnyWidget):
     def __init__(self, nrows=1, ncols=1, figsize=(640, 480),
                  width_ratios=None, height_ratios=None,
                  sharex=False, sharey=False,
-                 display_stats=False, **kwargs):
+                 display_stats=False, help="", **kwargs):
         super().__init__(**kwargs)
         self._nrows = nrows
         self._ncols = ncols
@@ -125,8 +128,37 @@ def __init__(self, nrows=1, ncols=1, figsize=(640, 480),
             self.fig_width     = figsize[0]
             self.fig_height    = figsize[1]
             self.display_stats = display_stats
+            self.help_text     = self._resolve_help(help)
         self._push_layout()
 
+    @staticmethod
+    def _resolve_help(text: str) -> str:
+        """Return *text* if ``apl.show_help`` is True (default), else ``""``."""
+        try:
+            import anyplotlib as _apl
+            if not getattr(_apl, "show_help", True):
+                return ""
+        except ImportError:
+            pass
+        return text or ""
+
+    def set_help(self, text: str) -> None:
+        """Set (or clear) the figure-level help text shown in the **?** badge.
+
+        Parameters
+        ----------
+        text : str
+            Help string displayed when the user clicks the **?** badge.
+            Pass an empty string (or ``""`` ) to remove the badge entirely.
+            Newlines (``\\n``) are respected in the card.
+
+        Examples
+        --------
+        >>> fig.set_help("Drag peak: move μ/A\\nPress f: least-squares fit")
+        >>> fig.set_help("")   # hide the badge
+        """
+        self.help_text = self._resolve_help(text)
+
     # ── subplot creation ──────────────────────────────────────────────────────
     def add_subplot(self, spec) -> Axes:
         """Add a subplot cell and return its :class:`Axes`.
@@ -347,7 +379,8 @@ def subplots(nrows=1, ncols=1, *,
              width_ratios=None,
              height_ratios=None,
              gridspec_kw=None,
-             display_stats=False):
+             display_stats=False,
+             help=""):
     """Create a :class:`Figure` and a grid of :class:`~anyplotlib.figure_plots.Axes`.
 
     Mirrors :func:`matplotlib.pyplot.subplots`.
@@ -369,6 +402,13 @@ def subplots(nrows=1, ncols=1, *,
     gridspec_kw : dict, optional
         Extra keyword arguments forwarded to :class:`GridSpec`.
         Recognised keys: ``width_ratios``, ``height_ratios``.
+    display_stats : bool, optional
+        Show per-panel FPS / frame-time overlay.  Default False.
+    help : str, optional
+        Help text shown when the user clicks the **?** badge on the figure.
+        Newlines (``\\n``) create separate lines in the card.  The badge is
+        hidden when *help* is empty (default).  Suppressed globally when
+        ``apl.show_help = False``.
 
     Returns
     -------
@@ -398,6 +438,7 @@ def subplots(nrows=1, ncols=1, *,
         width_ratios=width_ratios, height_ratios=height_ratios,
         sharex=sharex, sharey=sharey,
         display_stats=display_stats,
+        help=help,
     )
     # Build the GridSpec from the Figure's own stored ratios so there is
     # exactly one source of truth.
diff --git a/anyplotlib/figure_esm.js b/anyplotlib/figure_esm.js
@@ -189,7 +189,81 @@ function render({ model, el }) {
     'color:white;font-size:11px;border-radius:4px;display:none;pointer-events:none;z-index:21;';
   outerDiv.appendChild(sizeLabel);
 
-  // Tooltip (shared across all panels)
+  // ── Help badge (figure-level) ─────────────────────────────────────────────
+  // A small '?' button in the top-right corner of the figure.
+  //   • Hidden until the mouse enters outerDiv (plot "active").
+  //   • Stays visible while the help card is open, even after mouse-leave.
+  //   • Rounded square, tucked into the right padding band so it never
+  //     overlaps plot content.
+  //   • Clicking toggles the help card; click again (or mouse-leave with
+  //     card closed) hides the button again.
+  const _BTN_BG        = 'rgba(100,100,120,0.72)';
+  const _BTN_BG_ACTIVE = 'rgba(75,120,210,0.92)';
+
+  const helpBtn = document.createElement('div');
+  helpBtn.style.cssText =
+    'position:absolute;top:9px;right:6px;width:20px;height:20px;' +
+    'border-radius:4px;background:' + _BTN_BG + ';color:#fff;' +
+    'font-size:12px;font-weight:bold;font-family:sans-serif;' +
+    'display:none;align-items:center;justify-content:center;' +
+    'cursor:pointer;z-index:50;user-select:none;line-height:1;' +
+    'box-shadow:0 1px 4px rgba(0,0,0,0.35);';
+  helpBtn.textContent = '?';
+  helpBtn.title = 'Show help';
+  outerDiv.appendChild(helpBtn);
+
+  const helpCard = document.createElement('div');
+  helpCard.style.cssText =
+    'position:absolute;top:33px;right:6px;padding:10px 14px;' +
+    'background:rgba(28,28,38,0.95);color:#e0e0e8;font-size:12px;' +
+    'font-family:sans-serif;border-radius:6px;line-height:1.7;' +
+    'white-space:pre-wrap;max-width:300px;display:none;z-index:51;' +
+    'box-shadow:0 4px 14px rgba(0,0,0,0.55);pointer-events:none;' +
+    'border:1px solid rgba(120,120,160,0.3);';
+  outerDiv.appendChild(helpCard);
+
+  let _helpExists  = false;   // true when help_text is non-empty
+  let _helpHovered = false;   // true while mouse is inside outerDiv
+  let _helpOpen    = false;   // true while the card is shown
+
+  function _updateHelp() {
+    const txt = model.get('help_text') || '';
+    _helpExists          = !!txt;
+    helpCard.textContent = txt;
+    if (!txt) {
+      // Help removed — hide everything immediately.
+      helpBtn.style.display    = 'none';
+      helpCard.style.display   = 'none';
+      helpBtn.style.background = _BTN_BG;
+      _helpOpen = false;
+    } else if (_helpHovered || _helpOpen) {
+      // Already hovered or card open — make badge visible.
+      helpBtn.style.display = 'flex';
+    }
+  }
+  _updateHelp();
+
+  outerDiv.addEventListener('mouseenter', () => {
+    _helpHovered = true;
+    if (_helpExists) helpBtn.style.display = 'flex';
+  });
+
+  outerDiv.addEventListener('mouseleave', () => {
+    _helpHovered = false;
+    // Only hide the button if the card is also closed.
+    if (!_helpOpen) helpBtn.style.display = 'none';
+  });
+
+  helpBtn.addEventListener('click', (e) => {
+    e.stopPropagation();
+    _helpOpen = !_helpOpen;
+    helpCard.style.display   = _helpOpen ? 'block' : 'none';
+    helpBtn.style.background = _helpOpen ? _BTN_BG_ACTIVE : _BTN_BG;
+    // If closing the card while the mouse has already left, hide the button too.
+    if (!_helpOpen && !_helpHovered) helpBtn.style.display = 'none';
+  });
+
+  model.on('change:help_text', _updateHelp);
   const tooltip = document.createElement('div');
   tooltip.style.cssText =
     'position:fixed;padding:5px 9px;font-size:12px;font-family:sans-serif;' +
