Skip to content

Commit 4c341d3

Browse files
Yubo-Caocalixtus
andauthored
Update the walkthrough and quick setting user documentation (#13804)
* docs: Initial developer documentation for the walkthrough * docs: Initial developer documentation for the walkthrough * fix: Apply fix per GitHub action and format markdown * fix: Pass the GitHub Action * fix: Remove trailing spaces --------- Co-authored-by: Carl Christian Snethlage <[email protected]>
1 parent a305085 commit 4c341d3

File tree

8 files changed

+52
-0
lines changed

8 files changed

+52
-0
lines changed

docs/code-howtos/walkthrough.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
parent: Code Howtos
3+
---
4+
5+
# Walkthrough
6+
7+
All walkthroughs are written using the internal declarative API (see `org.jabref.gui.walkthrough.declarative`) and are
8+
defined in the `WalkthroughAction` class. Each walkthrough is a linear series of steps, where each step is either a UI
9+
highlight (`VisibleComponent`) or an invisible side effect (`WalkthroughSideEffect`). The walkthroughs are built using a
10+
builder API (`Walkthrough.Builder`). To launch a walkthrough, simply construct a new `WalkthroughAction` and pass the
11+
name of the desired walkthrough.
12+
13+
The `WalkthroughOverlay` renderer takes the output of the declarative API (`Walkthrough`) and renders it for the user.
14+
At a high level, a walkthrough primarily highlights GUI elements (nodes in the scene graph).
15+
16+
The following step types are supported:
17+
18+
## Highlights
19+
20+
1. `Ring`: Shows a small, accent-colored circle in the upper-right corner of the node to be highlighted.
21+
![A blue, semi-transparent circle highlighting the "Preferences" button](../images/ring.png)
22+
2. `Spotlight`: Highlights the node of interest by darkening the rest of the window.
23+
![The "File" menu item highlighted with a spotlight effect](../images/backdrop.png)
24+
3. `FullScreenDarken`: Darkens the entire window, typically to display a panel in the center.
25+
![The entire application window darkened](../images/fullscreen-darken.png)
26+
27+
## Visual Steps
28+
29+
1. `TooltipStep`: Shows a tooltip next to a specified node. This step must be associated with a node to display
30+
correctly.
31+
![A tooltip pointing to "Use Main File Directory"](../images/tooltip.png)
32+
2. `PanelStep`: Shows a panel with rich text and info boxes on the top, left, bottom, or right of the screen.
33+
![A information panel displayed at the top of the screen.](../images/panel-step.png)
34+
35+
## Side Effects
36+
37+
1. `OpenLibrarySideEffect`: Opens a specified example library.
38+
2. `EnsureSearchSettingsSideEffect`: Forces a search preference into a desired state.
39+
40+
All walkthroughs are currently launched from the `Walkthroughs` component, which is located exclusively on the
41+
`WelcomeTab`.
42+
43+
![The "Walkthroughs" section of the Welcome Tab, showing a list of available walkthroughs](../images/walkthroughs.png)
44+
45+
## Quick Settings
46+
47+
Since walkthroughs are only supposed to highlight UI components and guide the user through JabRef, quick settings are
48+
create so as to provide a convenient entry point for the user to edit the common settings like theme, online services,
49+
and main file directory. All the quick settings items are present in the `org.jabref.gui.welcome.components.QuickSettings`
50+
component, which is visible in the `WelcomeTab`.
51+
52+
![The 'Quick Settings' section of the Welcome Tab, showing options for main file directory, theme, online settings, etc](../images/quicksettings.png)

docs/images/backdrop.png

82.2 KB
Loading

docs/images/fullscreen-darken.png

82.4 KB
Loading

docs/images/panel-step.png

74.7 KB
Loading

docs/images/quicksettings.png

110 KB
Loading

docs/images/ring.png

22.4 KB
Loading

docs/images/tooltip.png

97.1 KB
Loading

docs/images/walkthroughs.png

110 KB
Loading

0 commit comments

Comments
 (0)