Add initial implementation of walkthrough #13182

Yubo-Cao · 2025-05-29T04:28:22Z

Closes N/A

Initial implementation of the walkthrough feature. See this Google Drive video for demonstration: https://drive.google.com/file/d/19sUz1XoSjP0UkuhUvKQE-MZjmVASy2ot/view?usp=sharing

The completion of the walkthrough is also tracked through modifying the preferences class.

This refs #12664

Mandatory checks

I own the copyright of the code submitted and I license it under the MIT license
Change in CHANGELOG.md described in a way that is understandable for the average user (if change is visible to the user)
Tests created for changes (if applicable)
Manually tested changed features in running JabRef (always required)
Screenshots added in PR description (if change is visible to the user)
Checked developer's documentation: Is the information available and up to date? If not, I outlined it in this pull request.
Checked documentation: Is the information available and up to date? If not, I created an issue at https://github.com/JabRef/user-documentation/issues or, even better, I submitted a pull request to the documentation repository.

jabgui/src/main/java/org/jabref/gui/util/component/PulseAnimateIndicator.java

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

jabgui/src/main/java/org/jabref/gui/walkthrough/declarative/InfoBlockContentBlock.java

jabgui/src/main/java/org/jabref/gui/walkthrough/declarative/StepType.java

jabgui/src/main/java/org/jabref/gui/walkthrough/declarative/WalkthroughContentBlock.java

jabgui/src/main/java/org/jabref/gui/walkthrough/declarative/WalkthroughStep.java

trag-bot · 2025-05-29T04:41:45Z

jablib/src/main/java/org/jabref/logic/preferences/CliPreferences.java

@@ -113,5 +113,7 @@ public interface CliPreferences {

    LastFilesOpenedPreferences getLastFilesOpenedPreferences();

+    WalkthroughPreferences getWalkthroughPreferences();


The new method 'getWalkthroughPreferences' should not return 'null'. It should use 'java.util.Optional' to handle the absence of a value, ensuring better null safety and avoiding potential null pointer exceptions.

Siedlerchr · 2025-05-29T14:52:03Z

So far I like the idea.
Discussion points for Friday would be:

How many steps we want
Going back one step?
content of the steps
Additional steps like adding stuff to groups or creating a new entry or library

koppor · 2025-05-30T15:10:31Z

This refs #12664 somehow :)

jablib/src/main/resources/l10n/JabRef_en.properties

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

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

jabgui/src/main/java/org/jabref/gui/walkthrough/declarative/NodeResolverFactory.java

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

jablib/src/main/java/org/jabref/logic/preferences/JabRefCliPreferences.java

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

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

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

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

jabgui/src/main/java/org/jabref/gui/walkthrough/declarative/NodeResolverFactory.java

jabgui/src/main/java/org/jabref/gui/walkthrough/declarative/TextContentBlock.java

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

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

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

subhramit · 2025-06-20T22:52:58Z

@Yubo-Cao can you fix the failing tests - should be simple, both are related to localization.

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

jabgui/src/main/java/org/jabref/gui/walkthrough/declarative/step/PanelStep.java

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

calixtus

First half of first iteration through review. More to come on the weekend.

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

calixtus · 2025-06-27T13:51:37Z

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

+        int currentIndex = walkthrough.currentStepProperty().get();
+
+        for (int i = currentIndex - 1; i >= 0; i--) {
+            WalkthroughStep previousStep = walkthrough.getStepAtIndex(i);


Why would dealing with an optional here force you to do something incorrect?

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

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

calixtus · 2025-06-27T15:50:07Z

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

+    private final Stage stage;
+    private final WalkthroughHighlighter walkthroughHighlighter;
+    private final Walkthrough walkthrough;
+    private @Nullable Timeline nodePollingTimeline;


Im not yet convinced that we have to do polling and that this is not solvable by an event being fired by javafx. Polling takes unnecessary resources.

calixtus · 2025-06-27T15:55:13Z

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

+ */
+public class WalkthroughUpdater {
+    private final List<Runnable> cleanupTasks = new ArrayList<>(); // has to be mutable
+    private final Timeline updateTimeline = new Timeline();


About polling...

Siedlerchr · 2025-06-27T19:22:27Z

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

+        overlay.displayStep(step);
+    }
+
+    public WalkthroughStep getStepAtIndex(int index) {


What If I call it with -1?

Array index out of bounds.

…on of control to the JabRefFrame

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

Co-authored-by: Subhramit Basu <subhramit.bb@live.in>

trag-bot · 2025-06-28T12:28:57Z

@trag-bot didn't find any issues in the code! ✅✨

feat: add initial implementation of walkthrough

5babec2