feat: the help is a submenu, with a contextual-help layer and a guided tour
The hamburger menu's help rows were three flat entries and a window. They are a **`Help` submenu** now, which is where every GNOME menu keeps them, with the four things a first run cannot find: - Keyboard shortcuts Ctrl+/ (the existing overview, `show_shortcuts()`) - Documentation F1 (the existing manual, `show_help()`) - Guided tour Ctrl+T (new) - Enable contextual help (new, a stateful row: its check *is* the setting) The submenu *replaces* the menu's rows rather than floating beside them, the same shape and the same reason as the plot's right-click menu: a submenu torn out of the menu it belongs to is a second thing to dismiss, and the `GtkMenuButton` that owned one toggled itself out of sync the moment anything else closed its popover. It is the pages of a `GtkStack`, not a rebuild of the box and not a swap of the popover's child: the main view holds `app.layout_toggle`, which the tick's `sync_layout_editor()` and the `L` accel read, so rebuilding would leave that pointer on a destroyed widget, and a swapped child would leave the view that is not showing without an owner. **The contextual help is one table and a "?" per surface** (`src/ui_context_help.cpp`): the plot, the trigger, the cursors, the measurements, the math channels, the signals, the event history, the time window, the status line, and the math editor's identity row. Each row names the *heading box* its button joins -- a sibling of the title, never an overlay child on a corner, which is what would cover the switch or the [edit] button already there -- so adding a surface is a row and a widget pointer. Off means *gone*, not greyed: the buttons are removed, and they are found by a data key rather than a list of pointers because the math editor's heading is built afresh on every opening and a list would go stale one dialog later. `contextual_help` and `tour_seen` are keys of `settings.toml`, written through the same `Settings`/`load_settings()`/`save_settings()` the Preferences dialog uses, whose own rows start from `load_settings()` and so carry them through untouched. **The guided tour is five steps on a `GtkOverlay`** above the window's content: the plot, the side panel, the trigger, the signals and the status line. There is no popover in it and therefore no pointer grab to leak -- four dim rectangles around the hole are what make it modal -- and the probe asserts that as a reading (`controllers=` against the count taken before it opened) rather than as a claim. Everything is placed from `gtk_widget_compute_bounds()` re-read on every frame, because a widget's allocation is 0 on the frame it is first shown and a window resize moves it under a one-shot measurement; the hole is kept from the last frame that could measure the target, because a frame that lands between two layout passes would otherwise empty it and make the spotlight jump. `Skip`, `Finish` and `Escape` all hide every child and leave nothing behind. A first run gets the tour once, decided by `tour_seen` and not by "the settings file did not exist" (a user who changed the theme has a file and has still never seen it), and the flag is written when the tour *starts* rather than when it finishes: a user who skips it in the first second has still seen it. `UDPSCOPE_PROBE_HELPUI_MS` drives all of it -- the auto-start, the menu's seven rows and the submenu's five, the toggle's effect read as a count of affordances on either side of it, and the tour started, stepped forwards and back and dismissed -- and the exit dump gains `help layer:` and `help figures:`, the latter being the ten surfaces' window-coordinate rectangles that the manual's annotated screenshots crop their boxes from. Two of them are what the D-Bus-free headless run can still not decide, and both are limitations rather than defects: export carries no "?" (it is a menu action with no surface of its own, and a popover inside the menu's popover is the nested-popover trap the invariants already warn about), and the tour card cannot miss its target when the target is the whole content -- which is what the plot is at the window's 756 px minimum, where the split view overlays the side panel instead of putting it beside the plot. The probe prints both rectangles rather than asserting a placement, so that case reads as the geometry it is. Also fixed while it was found: `gtk_widget_measure()` includes the widget's own margins (measured: a 280 px box with `margin-start 453` reports 733), so a measure that is used to *place* the widget is a feedback loop -- that is what made the tour card walk between the corner and the target from frame to frame.
This commit is contained in:
1 parent
c1460a6977
commit
1baa58b8fd
20 files changed
+1558
-30
No files matched your search
@@ -462,3 +462,64 @@ Part of [CLAUDE.md](../../CLAUDE.md). These are rules that cost a defect to lear
|
||||
is why every documented probe (all of them pass `--server`) is on exactly the path it was before --
|
||||
and a `--server` run never had a window to lose, so the post-present notice is the right place for it.
|
||||
`loading_hide()` is a no-op when none is up, so `run_ui()` needs no notion of which path it is on.
|
||||
|
||||
## The help affordance layer
|
||||
|
||||
The `Help` submenu, the contextual help's "?" and the guided tour, and the traps each of them met.
|
||||
|
||||
- **`gtk_widget_measure()` includes the widget's own margins.** Measured: a box whose natural width
|
||||
is 280 and whose `margin-start` is 453 reports `natural = 733`. That matters wherever a measure is
|
||||
used to *place* the widget and the margin *is* the placement: the width the widget was placed at
|
||||
comes back as its width, and the card of the guided tour walked between the bottom-right corner and
|
||||
the left of the target from frame to frame because of it (a `place_natural()` that set no size
|
||||
request did not help -- the margin alone was the loop). Take the margins off a measure that feeds a
|
||||
position back. `hdl`/`bd`-style CSS padding is *not* part of it, and neither is the other axis's
|
||||
margin, so it is `margin-start + margin-end` on the horizontal and top/bottom on the vertical.
|
||||
- **The overflow menu's `Help` submenu is a two-page `GtkStack`, and neither of the obvious
|
||||
alternatives works.** Rebuilding the rows -- the plot menu's own shape -- destroys
|
||||
`app.layout_toggle`, which points into the main view and which `sync_layout_editor()` and the `L`
|
||||
accel read; swapping the *popover's child* instead leaves whichever view is not showing with the
|
||||
popover as its only owner, so it is finalized the moment it is swapped out. The popover's child is a
|
||||
stack, the visible child is the view, and `gtk_popover_present()` re-measures a popover that is
|
||||
already up. `UDPSCOPE_PROBE_MENUS_MS` walks the *visible page*, which is the one line the stack cost
|
||||
the probe.
|
||||
- **A "?" joins its surface's heading row as a sibling, not as an overlay child.** An overlay child
|
||||
sits *on* whatever is under it -- and every panel heading already has a switch or an [edit] button in
|
||||
a corner. `src/ui_context_help.cpp` is a table of (id, title, body, shortcut, host) where the host is
|
||||
the *heading box*, so a new surface is a row and nothing else. The one exception is the plot, which
|
||||
has no heading: its "?" is an overlay child of the overlay the layout editor already uses, and its
|
||||
corner is free. The icon is `dialog-question-symbolic` -- `help-about-symbolic` is *already* the
|
||||
status bar's information button, and two "help" glyphs meaning different things on the same line is
|
||||
the trap the seven app icons exist to avoid; the dump reads the name back through the theme for the
|
||||
same reason the pane [edit] buttons do.
|
||||
- **Off is gone, not greyed, and the buttons are found by a data key rather than kept in a list.** The
|
||||
list is what the math editor cannot survive: its heading lives in a builder that is dropped and
|
||||
rebuilt on every opening, so a stored pointer into it would go stale one dialog later. A key on the
|
||||
button (`udpscope-help-hint`, carrying the surface's id) is both the mark that says "this is a hint"
|
||||
and the name the probe and the dump report it by, and removing a hint is `gtk_widget_unparent()`,
|
||||
which means the same thing for a box and for the plot's overlay.
|
||||
- **The guided tour takes no grab, and that is the whole reason it is an overlay.** Four dim
|
||||
rectangles around the hole are ordinary widgets that swallow the clicks that land on them and
|
||||
nothing else; `Skip`, `Finish` and `Escape` hide them, and there is no popover, no gesture and no
|
||||
grab to leak. The probe asserts it as a reading -- `controllers=` against the count taken before the
|
||||
tour opened -- rather than as a claim, because "no lingering grab" is exactly the sort of thing a
|
||||
later change can add back without noticing.
|
||||
- **The hole is kept from the last frame that could measure the target.** `gtk_widget_compute_bounds()`
|
||||
answers nothing on a frame that lands between two layout passes, and letting the hole empty there
|
||||
made the spotlight and the card jump to the corner and back; a *target that is not visible* is the
|
||||
different case (a genuinely absent surface) and is what empties it. The placement is also
|
||||
re-measured on **every frame**, never once at the start: a widget's allocation is 0 on the frame it
|
||||
is first shown, and a window resize moves it under a one-shot measurement.
|
||||
- **The first-run tour is a `settings.toml` key (`tour_seen`), written when the tour *starts*.** Not
|
||||
"the settings file did not exist": a user who has already changed the theme has a file and has still
|
||||
never seen the tour. Written on the way *in*, because a user who skips it in the first second has
|
||||
still seen it. The auto-start is a 1.5 s timer from `on_activate()`, so the window is up and laid out
|
||||
before anything points at it.
|
||||
- **The `help figures:` line is captured on the tick, like every other size the dump prints.** It names
|
||||
ten surfaces' window-coordinate rectangles for the help's annotated figures, and the dump runs after
|
||||
the window is destroyed -- a `gtk_widget_compute_bounds()` there is the "no `gtk_widget_*` call in the
|
||||
dump" rule again. `is_visible()`, not `get_visible()`: a widget under a hidden parent -- the trigger
|
||||
summary while the pane is in configuration mode -- keeps its own flag true and reads 0x0, and a crop
|
||||
box drawn from that is a box over the wrong thing. Its numbers depend on the *window's* size, which
|
||||
under the documented `xvfb-run` is the window's 756x894 minimum (a 640x480 screen), so a run on a
|
||||
larger screen gives different rectangles for the same panels.
|
||||
Reference in new issue
Block a user