Walkthrough

All walkthroughs are written using the internal declarative API (see org.jabref.gui.walkthrough.declarative) and are defined in the WalkthroughAction class. Each walkthrough is a linear series of steps, where each step is either a UI highlight (VisibleComponent) or an invisible side effect (WalkthroughSideEffect). The walkthroughs are built using a builder API (Walkthrough.Builder). To launch a walkthrough, simply construct a new WalkthroughAction and pass the name of the desired walkthrough.

The WalkthroughOverlay renderer takes the output of the declarative API (Walkthrough) and renders it for the user. At a high level, a walkthrough primarily highlights GUI elements (nodes in the scene graph).

The following step types are supported:

Highlights

  1. Ring: Shows a small, accent-colored circle in the upper-right corner of the node to be highlighted. A blue, semi-transparent circle highlighting the "Preferences" button
  2. Spotlight: Highlights the node of interest by darkening the rest of the window. The "File" menu item highlighted with a spotlight effect
  3. FullScreenDarken: Darkens the entire window, typically to display a panel in the center. The entire application window darkened

Visual Steps

  1. TooltipStep: Shows a tooltip next to a specified node. This step must be associated with a node to display correctly. A tooltip pointing to "Use Main File Directory"
  2. PanelStep: Shows a panel with rich text and info boxes on the top, left, bottom, or right of the screen. A information panel displayed at the top of the screen.

Where overlays are rendered

Every walkthrough overlay is drawn into the WalkthroughPane of the window it belongs to. That pane is a child of a parent the window already has, installed while the window is built and kept for the window’s lifetime:

  • the main window adds one to its PowerPane (JabRefGUI),
  • every dialog adds one to its DialogPane (BaseDialog, FXDialog, and the input dialogs of JabRefDialogService),
  • popups – context menus a walkthrough steps into – are not JabRef’s to build, so they are given one on the first lookup.

WalkthroughPane.of(Window) is how the walkthrough gets at the pane of the window it is working on.

Do not host an overlay by replacing the scene root. Three parties already claim that root: JavaFX’s Dialog reassigns it on every show and swaps in a placeholder on close, ControlsFX injects its DecorationPane on the first validation decoration, and an overlay wrapping it would be the third. Any two of them colliding drop the third’s contribution. Replacing the root of a visible window also invalidates the CSS of the whole scene graph and makes Scenic View re-attach from scratch, losing the selection of whoever is debugging.

Tooltips are the exception: a TooltipStep renders into a ControlsFX PopOver, which brings its own window and scene. The pane still carries that step’s quit button.

Side Effects

  1. OpenLibrarySideEffect: Opens a specified example library.
  2. EnsureSearchSettingsSideEffect: Forces a search preference into a desired state.

All walkthroughs are currently launched from the Walkthroughs component, which is located exclusively on the WelcomeTab.

The "Walkthroughs" section of the Welcome Tab, showing a list of available walkthroughs

Quick Settings

Since walkthroughs are only supposed to highlight UI components and guide the user through JabRef, quick settings are create so as to provide a convenient entry point for the user to edit the common settings like theme, online services, and main file directory. All the quick settings items are present in the org.jabref.gui.welcome.components.QuickSettings component, which is visible in the WelcomeTab.

The 'Quick Settings' section of the Welcome Tab, showing options for main file directory, theme, online settings, etc