udpscope/docs/claude/invariants-gtk-and-chrome.md

Invariants: GTK traps, the status bar, the icons and the help

The GTK signal-signature and dialog-lifetime traps this app has already fallen into, plus the status bar's two tiers, the bundled icons and the help pages.

Part of CLAUDE.md. These are rules that cost a defect to learn; read the ones touching the area you are editing before you edit it.

• The status line's per-second fields are measured once a second, not per frame. App::stored_rate/declared_rate and the label's tooltip are refreshed on the same tick as the channel dump; the status line only formats what is already there. The badge's markup is likewise rewritten on a change of phase (twice a second), never on all sixty frames.
• A notify::<prop> handler takes three parameters, a value-changed handler two. GObject::notify passes (GObject*, GParamSpec*, gpointer) while GtkSpinButton::value-changed passes (GtkSpinButton*, gpointer), so one callback cannot serve both: on the notify:: connection the GParamSpec* lands in the user_data slot and the handler dereferences it as its App*. G_CALLBACK is a cast, so nothing warns. That is why the trigger panel's spin buttons and its dropdowns have separate thin entry points (on_trigger_field_changed, on_trigger_drop_changed) onto one publish_trigger_fields(): changing the edge or Normal/Single dropdown used to segfault outright. UDPSCOPE_PROBE_FIELDS_MS is the guard.
• GtkDropDown's notify::selected arrives after the set_selected() that caused it returns, so the updating_panels flag — set around a programmatic write and cleared when it returns — does not suppress it. Where the write is part of a readout the handler reads back, that is a feedback loop: sync_window_display() writes a value rounded for reading into the window entry and picks the unit for it, and the late notify had on_window_unit_changed() re-parse that rounded text, turning a 500 s request into 499.98 s. The guard is App::window_sync_unit — the unit we last synced — and a selection equal to it is ours, since GTK only notifies on a change. Any new control that both writes and reads a GtkDropDown needs the same shape; the flag alone is not enough.
• The header bar's buttons are icon-only, so headless probes must reach them through the App pointers (trigger_toggle, pause_button, …), not via find_labelled_button(). The pane switches are toolbar buttons too (cursors_toggle, measures_toggle, math_toggle -- packed with header_bar_pack_end(), where the first packed is the rightmost, and the bar is an ancestor rather than the parent because packing parents into an internal box), and the cursors pane owns its own Reset button rather than the overflow menu owning one for it. The dump prints panel controls: … ; toolbar, left to right: … to say where they are and in what order. The widget tree's child order is the visual order left to right, so that line reads as the reverse of the pack order -- it is how an arrangement gets checked with no screenshot, and it is what finally settled the pack-order rule above (two comments in build_toolbar() disagreed with each other and one of them with reality): it is computed on the first tick, because the dump runs after the window is destroyed and asking GTK about a widget then is four criticals, which is how the first version of that line earned them. What stays in the menu is what acts on the data (Fit, Export) and the two editors that are not panes (Layout, Signal list). The Arm/Disarm button in the trigger panel still has text.
• Six of this app's icons are its own, and they are a GResource compiled into the binary. No icon theme has a glyph for an oscilloscope trigger, a pair of cursors or a measurement ruler, and the stock names those buttons used to carry said something else entirely: a record dot for the trigger and three different magnifiers for cursors, measurements and math. src/icons/scalable/actions/udpscope-{trigger,cursors,measure,math}-symbolic.svg are the four action icons; beside them in src/icons/scalable/apps/ are the two application icons, org.udpscope.app.svg (128px colour artwork) and org.udpscope.app-symbolic.svg (16px). The apps context is where an icon theme keeps an application's own icon and is where the in-process window icon resolves from; it is also the layout that cmake/install_desktop_entry.cmake mirrors when it copies the same two files into $XDG_DATA_HOME/icons/hicolor/scalable/apps and .../symbolic/apps — those installed copies are what makes Icon=org.udpscope.app in the desktop entry resolve (a desktop shell cannot read a GResource compiled into the binary). All six are bundled by src/icons/udpscope.gresource.xml (CMake runs glib-compile-resources) and reached through one gtk_icon_theme_add_resource_path() in run_ui(), right after adw_init() — not at the top of build_toolbar(), where it used to be: there are two consumers now (the window's own icon, set before the toolbar is built, and the toolbar's buttons) and run_ui() is the one place ahead of both. adw_init() calls gtk_init(), which is what makes gdk_display_get_default() valid there. A resource rather than files beside the binary because udpscope is run straight out of the build tree and has no install step. Five authoring rules, each of which fails quietly:
  • GTK's symbolic recolour only reaches fill on path, rect and circle. It wraps the SVG in a stylesheet for those selectors, so a stroke, a line or a polyline keeps the colour written in the file and stays dark on a dark theme. In a symbolic icon everything is therefore a filled path — including anything that wants to look stroked, which is drawn as a closed band (two offset curves joined) instead. The rule is scoped to symbolic icons on purpose: org.udpscope.app.svg is 128px colour artwork that is never recoloured, so it strokes its sine freely, which is the sane way to draw a smooth one. Do not "fix" one to match the other.
  • Whole-pixel coordinates, because these are drawn at 16 px far more often than not: the first draft placed features on half-pixels and the whole icon was a grey smear at 1x.
  • fill-rule="evenodd" is how the ruler's body is a hole and its ticks still fill -- a tick inside the hole is three crossings deep, which is odd. Nonzero would fill the hole back in.
  • Overlapping subpaths under the default nonzero rule must be wound the same way or they cancel instead of uniting. All of them run clockwise.
  • A malformed SVG is a build error, and that is the only place it can be caught. Every <file> in src/icons/udpscope.gresource.xml carries preprocess="xml-stripblanks", which makes glib-compile-resources pipe it through xmllint — so -- inside an XML comment, which is illegal and which librsvg refuses the whole file for, fails the build with a file, a line and a caret under the offending character (…app-symbolic.svg:5: parser error : Double hyphen within comment). It has to be here because no runtime check can see it: librsvg refuses the file but the icon name still resolves, so gtk_icon_theme_has_icon() returns true and the icon draws nothing. gtk_icon_theme_lookup_icon() cannot tell either (see the app icons: line under Verification), GMarkup accepts the double hyphen because it is a lenient subset parser, and gdk_pixbuf goes through glycin here, which sandboxes a subprocess per load and refuses this project's own icons outright. The cost is that the xmllint binary is a build dependency; it ships with libxml2, which GTK already requires. gtk_icon_theme_has_icon() is checked for every toolbar button and reported by the dump (see toolbar icons: in probe-readings.md): a resource path that was never added does not raise an error, it draws image-missing.
• A shortcut table row's accel is GTK accelerator syntax, and a pointer gesture has none. src/shortcuts.cpp's strings are handed to AdwShortcutsItem, which parses them with gtk_accelerator_parse() — so they are "space", "<Control>e", "<Control>slash", "plus minus" (a space-separated pair is the "either of these" form the label draws as + / -), never the prose "Ctrl+E" or "+ / -". Neither GTK's syntax nor libadwaita's knows a wheel or a drag: "Wheel" costs a Failed to parse warning and draws an empty cell. Those six rows therefore carry accel = "" and put the prose in subtitle, which is the one field that is free text. A row added with a parse error is otherwise silent — the overview still opens and the row is simply blank — so read the probe run's stderr for Failed to parse after touching either table.
• The status bar is two tiers, and the dump reads the detail one. format_glance() writes the bar and format_detail() writes both the popover's prose and App::status_detail, which is what exit_probe_step3/exit_probe_step2 copy into dbg_mode_live/dbg_mode_triggered. Those two used to read the label, and the label no longer carries packets, gaps, plot 1: or the buffer figures — so a gtk_label_get_text() there would silently reduce every documented mode …: assertion to four fields. The glance line's state field is one word from a fixed set (connecting, live, paused, armed, capturing, event held, disarmed) for the layout reason above; a word wider than the widest already there, or a field whose width tracks the stream, breaks the row the plot is laid out under. The set may grow — connecting was added for the no-CONFIG state — but only on that condition, and the check is the dump's max_glance_chars. connecting is derived from have_config alone and sits ahead of every other branch, including the display mode's: with no signal list, every other word claims something that does not exist yet. The mode prose branches the same way for the same reason, which is what keeps the two tiers from disagreeing.
• The ⓘ popover's widgets are built once and only their text is set. It is visible when the tick updates it, so a rebuild is a per-frame relayout of a widget on screen. update_status_popover() only ever calls gtk_label_set_text(), and popover_rebuilds in the dump is the assertion.
• The About dialog, the help window and the shortcut overview are opened by show_about(), show_help() and show_shortcuts(), and each closes with the matching call. There is exactly one GtkWindow among the three — the paged help window. It closes with gtk_window_close(), which emits close-request so the handler that nulls the file-scope pointer runs. gtk_window_destroy() does not emit that signal and must not be used — the math dialog fell into exactly this trap, and the pointer then points at a dead widget until the next attempt to open the same window. The other two — the About dialog (an AdwAboutDialog) and the shortcut overview (an AdwShortcutsDialog) — are AdwDialogs and not GtkWindows: they close with adw_dialog_close() and clear on ::closed, there being no ::close-request on an AdwDialog. Both share one on_dialog_closed() handler keyed by a pointer to the pointer it must null (&g_about, &g_shortcuts), which is what keeps one handler honest for two dialogs. One GtkWidget* (or AdwDialog*) per window, nulled in its own close handler, is the shape that prevents the double-open defect across all three.
• build_info.cpp is generated, never committed. cmake/write_build_info.cmake runs at configure time (so add_executable can name the file) and again on every build through udpscope_build_info (so the commit and the timestamp belong to the binary that is running). git absent leaves kCommit at "unknown" and the build succeeds. The About dialog and the [help] probe both read kVersion, kCommit and kTimestamp from it; settings= in the probe reads config_dir(), which is the path the session file is written to.
• The keyboard zoom's modifiers are not the wheel's. +/- with Ctrl restricts to x and with Alt to y, while the wheel keeps upstream's Shift = x / Ctrl = y convention. The two cannot agree: Shift is unusable on the keyboard path because key_from() folds '+' and '=' onto kKeyZoomIn — + is Shift+= on common layouts, so a bare zoom-in already arrives with Mod::Shift set. Ctrl+Alt together zooms neither axis, which needs no special case. The guards are deps/plotter's own ctrl_plus_zooms_only_x and alt_plus_zooms_only_y tests, plus UDPSCOPE_PROBE_ZOOMKEYS_MS.
• A help page is one .txt, one <file> line in the GResource manifest, and one kPages row. The bodies are Pango markup in a second GResource (--c-name=udpscope_help, so its generated symbols cannot collide with the icons'), validated with pango_parse_markup() at load; a page that fails either lookup or parse renders a one-line stand-in and is excluded from parsed. UDPSCOPE_PROBE_HELP_MS's parsed must equal pages. A page may also carry screenshots (HelpPage::images, a null-terminated list of resources). They are GtkPictures with a height request: one created can_shrink asks for no height at all inside a box, so without the request it is allocated nothing and the page renders its text with a silent gap where its screenshots should be — which is what the first version did.
• find_accel() masks the modifiers before comparing. Lock, Num-Lock and the pointer buttons all arrive in GdkModifierType, so an unmasked compare matches no table row at all once Caps Lock is on.