UX: Implement on-boarding tour and revamp the notification system

- Implement on-boarding callouts
- 'Tip of the day': make the reel of hints aware of stream mode
- Coalescent the different non-modal, 'non-urgent' dialogs (floating dialogs, temp Msg, 'toasts'; etc.) into a single queued notification center
- Fix inconsistencies between temp messages, floating toasts, notifications, and errors
- While at it fix Show/hide Path Manager/Fill Manager buttons that for 10+ years have been of the wrong type!

Author: tferr

src/main/java/sc/fiji/snt/BookmarkManager.java

@@ -922,7 +922,7 @@ private JPopupMenu importMenu() {
                 recordCmd("load(rm.getRoisAsArray())");
             });
             menu.addSeparator();
-            jmi = new JMenuItem("From Workspace...", IconFactory.menuIcon('\ue066', true));
+            jmi = new JMenuItem("From Workspace...", IconFactory.menuIcon(IconFactory.GLYPH.HOUSE_LAPTOP));
             menu.add(jmi);
             jmi.addActionListener(e -> {
                 final File workspaceDir = sntui.getOrPromptForWorkspace();
@@ -996,7 +996,7 @@ private JPopupMenu exportMenu() {
                 recordCmd("toRoiManager()");
             });
             menu.addSeparator();
-            jmi = new JMenuItem("To Workspace...", IconFactory.menuIcon('\ue066', true));
+            jmi = new JMenuItem("To Workspace...", IconFactory.menuIcon(IconFactory.GLYPH.HOUSE_LAPTOP));
             menu.add(jmi);
             jmi.addActionListener(e -> {
                 final File workspaceDir = sntui.getOrPromptForWorkspace();

src/main/java/sc/fiji/snt/CurationManager.java

@@ -1277,10 +1277,17 @@ protected void done() {
                     } else {
                         sntui.showStatus(String.format("Full scan completed: %d issue(s) found", warnings.size())
                                 + outOfCropNote, true);
+                        // A full scan can run for a while (network/disk-bound image checks) and, when
+                        // triggered via calibrateFromTrees() after autotracing, without any direct click
+                        GuiUtils.queueNotice(String.format("<HTML><b>Full scan completed: %d issue(s) found.</b><br>" +
+                                        "Click here to review them.", warnings.size()),
+                                null, () -> sntui.selectTab("Assistant"));
                     }
                 } catch (final Exception ex) {
                     SNTUtils.log("Full scan failed: " + ex.getMessage());
                     sntui.showStatus("Full scan failed. See log.", true);
+                    GuiUtils.queueNotice("<HTML><b>Full scan failed.</b><br>Click here for the Assistant tab.",
+                            null, () -> sntui.selectTab("Assistant"));
                 }
             }
         }.execute();
@@ -1368,6 +1375,10 @@ protected void done() {
                     final PlausibilityCalibrator.CalibrationResult result = get();
                     if (result == null) {
                         sntui.showStatus("Auto-calibration failed.", true);
+                        // This chain runs programmatically after autotracing, with no direct click behind it
+                        GuiUtils.queueNotice("<HTML><b>Auto-calibration (after autotracing) failed.</b><br>" +
+                                        "None of the freshly traced data yielded a valid calibration.",
+                                null, () -> sntui.selectTab("Assistant"));
                         return;
                     }
                     SNTUtils.log("PlausibilityCalibrator (auto):\n" + result.toTable());
@@ -1378,11 +1389,14 @@ protected void done() {
                     sntui.selectTab("Assistant");
                     sntui.showStatus(String.format("Calibrated from %d tree(s). Scanning...", result.getTreeCount()), true);
                     // Chain directly into a full scan: all validation guards (parameters selected, paths
-                    // exist, image loaded) should pass since we just calibrated from freshly traced data
+                    // exist, image loaded) should pass since we just calibrated from freshly traced data.
+                    // Its own done() queues a notice of the scan's outcome, so nothing further is needed here
                     runOnDemandAsync();
                 } catch (final Exception ex) {
                     SNTUtils.log("Auto-calibration failed: " + ex.getMessage());
                     sntui.showStatus("Auto-calibration failed. See log.", true);
+                    GuiUtils.queueNotice("<HTML><b>Auto-calibration (after autotracing) failed.</b><br>See log.",
+                            null, () -> sntui.selectTab("Assistant"));
                 }
             }
         }.execute();

src/main/java/sc/fiji/snt/DelineationsManager.java

@@ -1523,7 +1523,7 @@ private JButton colorButton() {
         private void updateWidget() {
             clearButton.setEnabled(roi != null);
             revealButton.setEnabled(roi != null && roi != DUMMY_ROI);
-            final Color color = (roi == null) ? IconFactory.defaultColor() : IconFactory.selectedColor();
+            final Color color = (roi == null) ? IconFactory.secondaryColor() : IconFactory.selectedColor();
             assignButton.setIcon(IconFactory.buttonIcon('\uf359', true, color));
         }
 

src/main/java/sc/fiji/snt/PathAndFillManager.java

@@ -3172,7 +3172,7 @@ private void checkForAppropriateImageDimensions() {
             if (!pluginBoundingBox.contains(boundingBox)) {
                 plugin.getPrefs().setTemp(SNTPrefs.RESIZE_REQUIRED, true);
                 SNTUtils.warn("Some nodes lay outside the image volume: you may need to "
-                        + "adjust import options or resize current image canvas");
+                        + "adjust import options, scale paths, or check for mismatched files");
             }
         }
     }

src/main/java/sc/fiji/snt/PathManagerUI.java

@@ -150,6 +150,7 @@ public PathManagerUI(final SNT plugin) {
         tree.setDoubleBuffered(true);
         tree.addTreeSelectionListener(this);
         SNTUI.InternalUtils.addHoldToToggleKeyListener(tree, plugin);
+
         proofReadingToolBar = new ProofReadingTagsToolBar();
         add(proofReadingToolBar, BorderLayout.PAGE_START);
 
@@ -473,7 +474,6 @@ public PathManagerUI(final SNT plugin) {
         jmi.addActionListener(multiPathListener);
         advanced.add(jmi);
 
-
         final JPopupMenu popup = new JPopupMenu();
         popup.putClientProperty("owner", this); // see SNTCommandFinder#revealMenuItem()
         popup.add(getDeleteMenuItem(multiPathListener));
@@ -542,6 +542,27 @@ public void windowClosing(final WindowEvent ignored) {
             }
         });
         pack();
+        addCallOuts();
+    }
+
+    private void addCallOuts() { // group callouts by "plugin" (similarly to SNTUI), see CalloutManager#groupFor
+        final String group = CalloutManager.groupFor(plugin);
+        int n = CalloutManager.size() + 1;
+        CalloutManager.add(this, CalloutManager.AUTO,
+                "Traced paths are listed here. The Path Manager allows you<br>" +
+                        "to select, tag, measure, and analyze groups of paths.", group, n++);
+        CalloutManager.add(menuBar, CalloutManager.AUTO,
+                "These menu commands apply to selected<br>" +
+                        "paths or <i>all</i> paths if none are selected.", group, n++);
+        CalloutManager.add(proofReadingToolBar, CalloutManager.AUTO,
+                "The <i>Proofreading Toolbar</i> allows you<br>" +
+                        "to tag paths by completion level.", group, n++);
+        CalloutManager.add(navToolbar, CalloutManager.AUTO,
+                "The <i>Navigation Toolbar</i> allows you to select<br>" +
+                        "structures and zoom into path selections.", group, n++);
+        CalloutManager.add(searchableBar, CalloutManager.AUTO,
+                "The <i>Filtering Toolbar</i> allows you to select paths based<br>" +
+                        "on morphological, locational, or annotation criteria.", group, n);
     }
 
     private JMenu getSpineUtilsMenu(final MultiPathActionListener multiPathListener) {
@@ -2750,7 +2771,7 @@ public void actionPerformed(final ActionEvent e) {
                         if (s.trim().isEmpty()) {
                             p.setName("");
                         } else if (getPathAndFillManager().getPathFromName(s, false) != null) {
-                            displayTmpMsg("There is already a path named:\n('" + s + "')");
+                            guiUtils.error("There is already a path named:\n('" + s + "')");
                             return;
                         } else {// Otherwise this is OK, change the name:
                             p.setName(s);
@@ -4209,7 +4230,7 @@ public void execute(List<Path> selectedPaths, String cmd) {
                     if (replacements > 0) {
                         refreshManager(false, false, selectedPaths);
                         plugin.setUnsavedChanges(true);
-                        guiUtils.floatingMsg(String.format("%d/%d path(s) renamed.", replacements, selectedPaths.size()), true);
+                        displayTmpMsg(String.format("%d/%d path(s) renamed.", replacements, selectedPaths.size()));
                     } else {
                         guiUtils.error(String.format("None of the %d paths matched the specified pattern.", selectedPaths.size()));
                     }
@@ -4311,7 +4332,7 @@ public void execute(final List<Path> selectedPaths, String cmd) {
                     navToolbar.restoreFullModelState();
                 }
                 applyActiveTags(selectedPaths);
-                guiUtils.tempMsg("Command finished.");
+                displayTmpMsg("Command finished.");
                 plugin.updateAllViewers();
                 plugin.setUnsavedChanges(true);
             }
@@ -4353,7 +4374,7 @@ public void execute(List<Path> selectedPaths, String cmd) {
                     if (!p.isFittedVersionOfAnotherPath()) p.setRadius(userRad);
                 });
                 removeOrReapplyDefaultTag(selectedPaths, MultiPathActionListener.MEAN_RADIUS_TAG_CMD, !noRadius, false);
-                guiUtils.tempMsg("Command finished. Fitted path(s) ignored.");
+                displayTmpMsg("Command finished. Fitted path(s) ignored.");
                 plugin.updateAllViewers();
                 plugin.setUnsavedChanges(true);
             }
@@ -5245,9 +5266,9 @@ private void applyZCorrection(final List<Path> selectedPaths) {
             if (factor == 1d) return;
 
             // Warn if corrected Z values would exceed image bounds
+            int oobNodes = 0;
             if (plugin.accessToValidImageData()) {
                 final double maxZ = plugin.depth - 1;
-                int oobNodes = 0;
                 for (final Path p : selectedPaths) {
                     final Path pathToUse = p.getUseFitted() ? p.getFitted() : p;
                     for (int node = 0; node < pathToUse.size(); node++) {
@@ -5270,7 +5291,14 @@ private void applyZCorrection(final List<Path> selectedPaths) {
             }
             plugin.updateAllViewers();
             plugin.setUnsavedChanges(true);
-            guiUtils.tempMsg("Z-correction applied (×" + SNTUtils.formatDouble(factor, 3) + ")");
+            if (oobNodes > 0) {
+                // Mirror the same handling used by PathAndFillManager#checkForAppropriateImageDimensions():
+                // flag the canvas as needing a resize, and log/queue a WARN notice
+                plugin.getPrefs().setTemp(SNTPrefs.RESIZE_REQUIRED, true);
+                SNTUtils.warn(oobNodes + " node(s) now lay outside the image volume after Z-correction (×"
+                        + SNTUtils.formatDouble(factor, 3) + ")");
+            }
+            displayTmpMsg("Z-correction applied (×" + SNTUtils.formatDouble(factor, 3) + ")");
         }
 
         private class ResetFitsCommand implements PathCommand {

src/main/java/sc/fiji/snt/SNTPrefs.java

@@ -109,6 +109,7 @@ public class SNTPrefs { // TODO: Adopt PrefService
 	private static final String WORKSPACE_KEY = "tracing.snt.workspace";
 	private static final String NEXT_IMG_FILTER_KEY = "tracing.snt.nextimg";
 	private static final String FAST_CROP_MATERIALIZATION_KEY = "tracing.snt.fastcropmat";
+	private static final String FIRST_RUN_KEY = "tracing.snt.firstrun";
 
 	/** recent directory */
 	private static File recentDir;
@@ -466,6 +467,18 @@ public static boolean firstRunAfterUpdate() {
 		return lastVersion == null || VersionUtils.compare(SNTUtils.VERSION, lastVersion) > 0;
 	}
 
+	/**
+	 * Checks if SNT has ever been run before on this system, consuming the check in the process: the very first
+	 * call ever made to this method returns {@code true}; every call after that returns {@code false}.
+	 *
+	 * @return true only the very first time this is ever called (or after preferences have been cleared)
+	 */
+	public static boolean firstRun() {
+		final boolean first = !Prefs.get(FIRST_RUN_KEY, false);
+		if (first) Prefs.set(FIRST_RUN_KEY, true);
+		return first;
+	}
+
 	/**
 	 * Sets the number of threads to use for multi-threaded operations.
 	 *
@@ -551,6 +564,7 @@ public static void clearAll() {
 		Prefs.set(FILTERED_IMG_PATH, null);
 		Prefs.set(NEXT_IMG_FILTER_KEY, null);
 		Prefs.set(WORKSPACE_KEY, null);
+		Prefs.set(FIRST_RUN_KEY, null);
 		setLookAndFeel(null);
 		setThreads(0);
 		wipeSessionPrefs();