improving doc

src/help_window.cpp

@@ -40,22 +40,38 @@ struct HelpPage {
   const char* section;   ///< the group heading in the sidebar
   const char* title;     ///< the row's label and the page's heading
   const char* resource;  ///< a path under /org/udpscope/help
+  /// The screenshots shown above the text, as resource paths and a null terminator. A page
+  /// with none is the common case and the reason this is a list rather than one field: the
+  /// overview carries two, the window and a held capture.
+  const char* const* images = nullptr;
 };
 
 /// Adding a page is one .txt file, one <file> line in the manifest and one row here.
 /// The order here is the order the sidebar shows; `section` groups consecutive rows.
+/// How tall a page's screenshots are drawn. They are scaled to fit this *height* and centre
+/// themselves in it, so a 1500x950 capture is readable without a horizontal scrollbar.
+constexpr int kHelpShotHeight = 260;
+
+/// The screenshots each page carries, in the order it shows them.
+constexpr const char* kOverviewShots[] = {"/org/udpscope/help/img/main-window.png",
+                                          "/org/udpscope/help/img/trigger-capture.png",
+                                          nullptr};
+constexpr const char* kTriggerShots[] = {"/org/udpscope/help/img/trigger-capture.png",
+                                         nullptr};
+constexpr const char* kMathShots[] = {"/org/udpscope/help/img/math-editor.png", nullptr};
+
 constexpr HelpPage kPages[] = {
-    {"Getting started", "Overview", "/org/udpscope/help/01-overview.txt"},
+    {"Getting started", "Overview", "/org/udpscope/help/01-overview.txt", kOverviewShots},
     {"Getting started", "Choosing a source", "/org/udpscope/help/02-source.txt"},
     {"Getting started", "Signals and calibration", "/org/udpscope/help/03-signals.txt"},
     {"Getting started", "Rows, layout and drag & drop", "/org/udpscope/help/04-layout.txt"},
     {"Viewing", "Time window", "/org/udpscope/help/05-window.txt"},
     {"Viewing", "Navigating the plot", "/org/udpscope/help/06-navigate.txt"},
     {"Viewing", "Pause and play", "/org/udpscope/help/07-pause.txt"},
-    {"Viewing", "Trigger", "/org/udpscope/help/08-trigger.txt"},
+    {"Viewing", "Trigger", "/org/udpscope/help/08-trigger.txt", kTriggerShots},
     {"Analysis", "Cursors", "/org/udpscope/help/09-cursors.txt"},
     {"Analysis", "Measurements", "/org/udpscope/help/10-measurements.txt"},
-    {"Analysis", "Math channels", "/org/udpscope/help/11-math.txt"},
+    {"Analysis", "Math channels", "/org/udpscope/help/11-math.txt", kMathShots},
     {"Output and state", "Saving and export", "/org/udpscope/help/12-export.txt"},
     {"Output and state", "Sessions and settings", "/org/udpscope/help/13-sessions.txt"},
     {"Output and state", "Status bar and diagnostics", "/org/udpscope/help/14-status.txt"},
@@ -94,6 +110,28 @@ void on_help_row_selected(GtkListBox*, GtkListBoxRow* row, gpointer body_label)
   bool ok = false;
   const std::string body = load_page(kPages[idx], &ok);
   gtk_label_set_markup(GTK_LABEL(body_label), body.c_str());
+  // The screenshots above it, if this page has any. The column is the label's previous sibling
+  // inside the page's box, which is what lets this handler stay a matter of the label alone --
+  // and refilling it is a page *switch*, not a frame, so rebuilding it here is cheap and is
+  // also the only way to be sure the pictures are this page's and not the last one's.
+  GtkWidget* label = GTK_WIDGET(body_label);
+  GtkWidget* parent = gtk_widget_get_parent(label);
+  GtkWidget* shots = parent != nullptr ? gtk_widget_get_first_child(parent) : nullptr;
+  if (shots != nullptr && GTK_IS_BOX(shots)) {
+    while (GtkWidget* old = gtk_widget_get_first_child(shots)) {
+      gtk_box_remove(GTK_BOX(shots), old);
+    }
+    for (const char* const* img = kPages[idx].images; img != nullptr && *img != nullptr; ++img) {
+      GtkWidget* shot = gtk_picture_new_for_resource(*img);
+      gtk_picture_set_can_shrink(GTK_PICTURE(shot), TRUE);
+      // A height, and `CONTAIN` (the default) to fit the image inside it: a picture that may
+      // shrink asks for no height at all in a box, so without this it is allocated nothing and
+      // the page shows its text with a gap where the screenshots should be.
+      gtk_widget_set_size_request(shot, -1, kHelpShotHeight);
+      gtk_box_append(GTK_BOX(shots), shot);
+    }
+    gtk_widget_set_visible(shots, gtk_widget_get_first_child(shots) != nullptr);
+  }
 }
 
 }  // namespace
@@ -180,7 +218,17 @@ void show_help(GtkWindow* parent) {
   GtkWidget* body_scroll = gtk_scrolled_window_new();
   gtk_scrolled_window_set_policy(GTK_SCROLLED_WINDOW(body_scroll), GTK_POLICY_NEVER,
                                  GTK_POLICY_AUTOMATIC);
-  gtk_scrolled_window_set_child(GTK_SCROLLED_WINDOW(body_scroll), body);
+  // The page's own column: its screenshots above its text. Built once and *refilled* by the page
+  // switch, which is why no picture is made here -- one `GtkPicture` per image of the page.
+  GtkWidget* shot_box = gtk_box_new(GTK_ORIENTATION_VERTICAL, 8);
+  gtk_widget_set_margin_start(shot_box, 18);
+  gtk_widget_set_margin_end(shot_box, 18);
+  gtk_widget_set_margin_top(shot_box, 14);
+  gtk_widget_set_visible(shot_box, false);
+  GtkWidget* page_box = gtk_box_new(GTK_ORIENTATION_VERTICAL, 0);
+  gtk_box_append(GTK_BOX(page_box), shot_box);
+  gtk_box_append(GTK_BOX(page_box), body);
+  gtk_scrolled_window_set_child(GTK_SCROLLED_WINDOW(body_scroll), page_box);
   gtk_widget_set_hexpand(body_scroll, TRUE);
 
   GtkWidget* list = gtk_list_box_new();