Implementation of walkthrough infrastructure

jabgui/src/main/java/org/jabref/gui/JabRefGUI.java

@@ -92,6 +92,7 @@ public static void setup(List<UiCommand> uiCommands,
     @Override
     public void start(Stage stage) {
         this.mainStage = stage;
+        Injector.setModelOrService(Stage.class, mainStage);
 
         FallbackExceptionHandler.installExceptionHandler((exception, thread) -> UiTaskExecutor.runInJavaFXThread(() -> {
             DialogService dialogService = Injector.instantiateModelOrService(DialogService.class);

jabgui/src/main/java/org/jabref/gui/actions/StandardActions.java

@@ -185,6 +185,8 @@ public enum StandardActions implements Action {
     OPEN_DEV_VERSION_LINK(Localization.lang("Development version"), Localization.lang("Opens a link where the current development version can be downloaded")),
     OPEN_CHANGELOG(Localization.lang("View change log"), Localization.lang("See what has been changed in the JabRef versions")),
     OPEN_GITHUB("GitHub", Localization.lang("Opens JabRef's GitHub page"), IconTheme.JabRefIcons.GITHUB),
+    WALKTHROUGH_MENU(Localization.lang("Walkthroughs"), IconTheme.JabRefIcons.BOOK),
+    MAIN_FILE_DIRECTORY_WALKTHROUGH(Localization.lang("Configure main file directory"), IconTheme.JabRefIcons.LATEX_FILE_DIRECTORY),
     DONATE(Localization.lang("Donate to JabRef"), Localization.lang("Donate to JabRef"), IconTheme.JabRefIcons.DONATE),
     OPEN_FORUM(Localization.lang("Community forum"), Localization.lang("Community forum"), IconTheme.JabRefIcons.FORUM),
     ERROR_CONSOLE(Localization.lang("View event log"), Localization.lang("Display all error messages")),

jabgui/src/main/java/org/jabref/gui/frame/JabRefFrame.java

@@ -630,6 +630,7 @@ public void openLastEditedDatabases() {
         getOpenDatabaseAction().openFiles(lastFiles);
     }
 
+    @Deprecated
     public Stage getMainStage() {
         return mainStage;
     }

jabgui/src/main/java/org/jabref/gui/frame/MainMenu.java

@@ -7,6 +7,7 @@
 import javafx.scene.control.MenuBar;
 import javafx.scene.control.MenuItem;
 import javafx.scene.control.SeparatorMenuItem;
+import javafx.stage.Stage;
 
 import org.jabref.gui.ClipBoardManager;
 import org.jabref.gui.DialogService;
@@ -77,6 +78,7 @@
 import org.jabref.gui.undo.UndoAction;
 import org.jabref.gui.util.URLs;
 import org.jabref.gui.util.UiTaskExecutor;
+import org.jabref.gui.walkthrough.WalkthroughAction;
 import org.jabref.logic.ai.AiService;
 import org.jabref.logic.citationstyle.CitationStyleOutputFormat;
 import org.jabref.logic.help.HelpFile;
@@ -90,6 +92,8 @@
 import org.jabref.model.entry.field.SpecialField;
 import org.jabref.model.util.FileUpdateMonitor;
 
+import com.airhacks.afterburner.injection.Injector;
+
 public class MainMenu extends MenuBar {
     private final JabRefFrame frame;
     private final FileHistoryMenu fileHistoryMenu;
@@ -235,7 +239,9 @@ private void createMenu() {
         edit.addEventHandler(ActionEvent.ACTION, event -> {
             // Work around for mac only issue, where cmd+v on a dialogue triggers the paste action of menu item, resulting in addition of the pasted content in the MainTable.
             // If the mainscreen is not focused, the actions captured by menu are consumed.
-            if (OS.OS_X && !frame.getMainStage().focusedProperty().get()) {
+            boolean isStageUnfocused = !Injector.instantiateModelOrService(Stage.class).focusedProperty().get();
+
+            if (OS.OS_X && isStageUnfocused) {
                 event.consume();
             }
         });
@@ -369,6 +375,12 @@ private void createMenu() {
 
                 new SeparatorMenuItem(),
 
+                factory.createSubMenu(StandardActions.WALKTHROUGH_MENU,
+                        factory.createMenuItem(StandardActions.MAIN_FILE_DIRECTORY_WALKTHROUGH, new WalkthroughAction("mainFileDirectory"))
+                ),
+
+                new SeparatorMenuItem(),
+
                 factory.createMenuItem(StandardActions.ERROR_CONSOLE, new ErrorConsoleAction()),
 
                 new SeparatorMenuItem(),

jabgui/src/main/java/org/jabref/gui/preferences/PreferencesDialogView.java

@@ -31,6 +31,7 @@
  */
 public class PreferencesDialogView extends BaseDialog<PreferencesDialogViewModel> {
 
+    public static final String DIALOG_TITLE = Localization.lang("JabRef preferences");
     @FXML private CustomTextField searchBox;
     @FXML private ListView<PreferencesTab> preferenceTabList;
     @FXML private ScrollPane preferencesContainer;
@@ -45,7 +46,7 @@ public class PreferencesDialogView extends BaseDialog<PreferencesDialogViewModel
     private final Class<? extends PreferencesTab> preferencesTabToSelectClass;
 
     public PreferencesDialogView(Class<? extends PreferencesTab> preferencesTabToSelectClass) {
-        this.setTitle(Localization.lang("JabRef preferences"));
+        this.setTitle(DIALOG_TITLE);
         this.preferencesTabToSelectClass = preferencesTabToSelectClass;
 
         ViewLoader.view(this)

jabgui/src/main/java/org/jabref/gui/walkthrough/SingleWindowWalkthroughOverlay.java

@@ -0,0 +1,252 @@
+package org.jabref.gui.walkthrough;
+
+import java.util.Optional;
+
+import javafx.beans.value.ChangeListener;
+import javafx.geometry.Bounds;
+import javafx.geometry.Pos;
+import javafx.scene.Node;
+import javafx.scene.Scene;
+import javafx.scene.layout.ColumnConstraints;
+import javafx.scene.layout.GridPane;
+import javafx.scene.layout.Pane;
+import javafx.scene.layout.Priority;
+import javafx.scene.layout.RowConstraints;
+import javafx.scene.layout.StackPane;
+import javafx.scene.shape.Rectangle;
+import javafx.stage.Window;
+
+import org.jabref.gui.walkthrough.declarative.step.PanelPosition;
+import org.jabref.gui.walkthrough.declarative.step.PanelStep;
+import org.jabref.gui.walkthrough.declarative.step.TooltipPosition;
+import org.jabref.gui.walkthrough.declarative.step.TooltipStep;
+import org.jabref.gui.walkthrough.declarative.step.WalkthroughStep;
+
+import org.controlsfx.control.PopOver;
+import org.jspecify.annotations.Nullable;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Manages the overlay for displaying walkthrough steps in a single window.
+ */
+public class SingleWindowWalkthroughOverlay {
+    private static final Logger LOGGER = LoggerFactory.getLogger(SingleWindowWalkthroughOverlay.class);
+
+    private final Window window;
+    private final GridPane overlayPane;
+    private final Pane originalRoot;
+    private final StackPane stackPane;
+    private final WalkthroughRenderer renderer;
+    private final WalkthroughUpdater updater = new WalkthroughUpdater();
+
+    public SingleWindowWalkthroughOverlay(Window window) {
+        this.window = window;
+        this.renderer = new WalkthroughRenderer();
+
+        overlayPane = new GridPane();
+        overlayPane.getStyleClass().add("walkthrough-overlay");
+        overlayPane.setPickOnBounds(false);
+        overlayPane.setMaxWidth(Double.MAX_VALUE);
+        overlayPane.setMaxHeight(Double.MAX_VALUE);
+
+        Scene scene = window.getScene();
+        // This basically never happens, so only a development time check is needed
+        assert scene != null;
+
+        originalRoot = (Pane) scene.getRoot();
+        stackPane = new StackPane();
+
+        stackPane.getChildren().add(originalRoot);
+        stackPane.getChildren().add(overlayPane);
+
+        scene.setRoot(stackPane);
+    }
+
+    /// Display a walkthrough step without a target node.
+    public void displayStep(WalkthroughStep step, Runnable beforeNavigate, Walkthrough walkthrough) {
+        displayStep(step, null, beforeNavigate, walkthrough);
+    }
+
+    /// Displays a walkthrough step, with or without a target node.
+    public void displayStep(WalkthroughStep step,
+                            @Nullable Node targetNode,
+                            Runnable beforeNavigate,
+                            Walkthrough walkthrough) {
+        hide();
+
+        switch (step) {
+            case TooltipStep tooltipStep -> {
+                Node content = renderer.render(tooltipStep, walkthrough, beforeNavigate);
+                displayTooltipStep(content, targetNode, tooltipStep);
+                hideOverlayPane();
+            }
+            case PanelStep panelStep -> {
+                Node content = renderer.render(panelStep, walkthrough, beforeNavigate);
+                displayPanelStep(content, panelStep);
+                setupClipping(content);
+                overlayPane.toFront();
+            }
+        }
+
+        if (targetNode == null) {
+            return;
+        }
+
+        step.navigationPredicate().ifPresent(predicate -> updater
+                .addCleanupTask(predicate.attachListeners(targetNode, beforeNavigate, walkthrough::nextStep)));
+    }
+
+    /**
+     * Hide the overlay and clean up any resources.
+     */
+    public void hide() {
+        overlayPane.getChildren().clear();
+        overlayPane.setClip(null);
+        overlayPane.setVisible(true);
+        updater.cleanup();
+    }
+
+    /**
+     * Detaches the overlay and restores the original scene root.
+     */
+    public void detach() {
+        hide();
+
+        Scene scene = window.getScene();
+        if (scene != null && originalRoot != null) {
+            stackPane.getChildren().remove(originalRoot);
+            scene.setRoot(originalRoot);
+            LOGGER.debug("Restored original scene root: {}", originalRoot.getClass().getName());
+        }
+    }
+
+    private void displayTooltipStep(Node content, @Nullable Node targetNode, TooltipStep step) {
+        PopOver popover = new PopOver();
+        popover.getScene().getStylesheets().setAll(window.getScene().getStylesheets()); // FIXME: walkaround to prevent popover from not properly inheriting styles
+        popover.setContentNode(content);
+        popover.setDetachable(false);
+        popover.setCloseButtonEnabled(false);
+        popover.setHeaderAlwaysVisible(false);
+        mapToArrowLocation(step.position()).ifPresent(popover::setArrowLocation);
+        popover.setAutoHide(false);
+        popover.setAutoFix(true);
+
+        if (targetNode == null) {
+            popover.show(window);
+            return;
+        }
+
+        popover.show(targetNode);
+        updater.addCleanupTask(popover::hide);
+        Runnable showPopover = () -> {
+            if (WalkthroughUpdater.cannotPositionNode(targetNode)) {
+                return;
+            }
+            popover.show(targetNode);
+        };
+        updater.setupScrollContainerListeners(targetNode, showPopover);
+    }
+
+    private void displayPanelStep(Node content, PanelStep step) {
+        overlayPane.getChildren().clear();
+        overlayPane.getRowConstraints().clear();
+        overlayPane.getColumnConstraints().clear();
+
+        configurePanelLayout(step.position());
+
+        overlayPane.getChildren().add(content);
+        GridPane.setHgrow(content, Priority.NEVER);
+        GridPane.setVgrow(content, Priority.NEVER);
+
+        switch (step.position()) {
+            case LEFT -> {
+                overlayPane.setAlignment(Pos.CENTER_LEFT);
+                GridPane.setVgrow(content, Priority.ALWAYS);
+                GridPane.setFillHeight(content, true);
+            }
+            case RIGHT -> {
+                overlayPane.setAlignment(Pos.CENTER_RIGHT);
+                GridPane.setVgrow(content, Priority.ALWAYS);
+                GridPane.setFillHeight(content, true);
+            }
+            case TOP -> {
+                overlayPane.setAlignment(Pos.TOP_CENTER);
+                GridPane.setHgrow(content, Priority.ALWAYS);
+                GridPane.setFillWidth(content, true);
+            }
+            case BOTTOM -> {
+                overlayPane.setAlignment(Pos.BOTTOM_CENTER);
+                GridPane.setHgrow(content, Priority.ALWAYS);
+                GridPane.setFillWidth(content, true);
+            }
+            default -> {
+                LOGGER.warn("Unsupported position for panel step: {}", step.position());
+                overlayPane.setAlignment(Pos.CENTER);
+            }
+        }
+    }
+
+    private void configurePanelLayout(PanelPosition position) {
+        overlayPane.getRowConstraints().add(switch (position) {
+            case LEFT,
+                 RIGHT -> {
+                RowConstraints rowConstraints = new RowConstraints();
+                rowConstraints.setVgrow(Priority.ALWAYS);
+                yield rowConstraints;
+            }
+            case TOP,
+                 BOTTOM -> {
+                RowConstraints rowConstraints = new RowConstraints();
+                rowConstraints.setVgrow(Priority.NEVER);
+                yield rowConstraints;
+            }
+        });
+        overlayPane.getColumnConstraints().add(switch (position) {
+            case LEFT,
+                 RIGHT -> {
+                ColumnConstraints columnConstraints = new ColumnConstraints();
+                columnConstraints.setHgrow(Priority.NEVER);
+                yield columnConstraints;
+            }
+            case TOP,
+                 BOTTOM -> {
+                ColumnConstraints columnConstraints = new ColumnConstraints();
+                columnConstraints.setHgrow(Priority.ALWAYS);
+                yield columnConstraints;
+            }
+        });
+    }
+
+    private Optional<PopOver.ArrowLocation> mapToArrowLocation(TooltipPosition position) {
+        return Optional.ofNullable(switch (position) {
+            case TOP ->
+                    PopOver.ArrowLocation.BOTTOM_CENTER;
+            case BOTTOM ->
+                    PopOver.ArrowLocation.TOP_CENTER;
+            case LEFT ->
+                    PopOver.ArrowLocation.RIGHT_CENTER;
+            case RIGHT ->
+                    PopOver.ArrowLocation.LEFT_CENTER;
+            case AUTO ->
+                    null;
+        });
+    }
+
+    private void hideOverlayPane() {
+        overlayPane.setVisible(false);
+        updater.addCleanupTask(() -> overlayPane.setVisible(true));
+    }
+
+    private void setupClipping(Node node) {
+        ChangeListener<Bounds> listener = (_, _, bounds) -> {
+            if (bounds != null && bounds.getWidth() > 0 && bounds.getHeight() > 0) {
+                Rectangle clip = new Rectangle(bounds.getMinX(), bounds.getMinY(),
+                        bounds.getWidth(), bounds.getHeight());
+                overlayPane.setClip(clip);
+            }
+        };
+        updater.listen(node.boundsInLocalProperty(), listener);
+        listener.changed(null, null, node.getBoundsInParent());
+    }
+}