feat: paged help window with the four Getting started pages
The pages are Pango markup in a GResource, bundled for the same reason the icons are: udpscope runs straight out of the build tree with no install step, so a runtime search path's failure mode would be a silently empty help window. --c-name=udpscope_help keeps the two generated bundles from colliding. Every page is validated with pango_parse_markup() at load and falls back to a one-line stand-in rather than rendering raw markup or nothing. show_help() reuses help_window.cpp's existing close-request handler, and closes via gtk_window_close() so that handler runs and the pointer is nulled. UDPSCOPE_PROBE_HELP_MS loads and validates every page, opens the help and About windows, closes both and reports; parsed must equal pages.
This commit is contained in:
1 parent
856f538681
commit
04b6181926
9 files changed
+373
No files matched your search
@@ -0,0 +1,26 @@
|
||||
<b>What udpscope is</b>
|
||||
|
||||
udpscope plots a live UDPStreamer source. One window holds up to 8 rows of plots, each
|
||||
with up to 4 traces; every row shares one time axis, so the whole figure scrolls together.
|
||||
Acquisition runs on its own thread and writes a ring buffer sized from --buffer-mb; the
|
||||
drawing thread reads whatever that ring holds when a frame starts.
|
||||
|
||||
<b>How to reach it</b>
|
||||
|
||||
Start the app with a source (<tt>udpscope --server 127.0.0.1 --port 8000</tt>), or start it
|
||||
with no <tt>--server</tt> and pick one from the chooser. The signals arrive disabled; turn
|
||||
one on in the side panel (<tt>s</tt>) and drag it onto a row.
|
||||
|
||||
<b>Worth knowing</b>
|
||||
|
||||
• Nothing is acquired until a signal is enabled. Enabling is what starts acquisition, so a
|
||||
freshly opened scope with an idle side panel is working correctly.
|
||||
• The stream carries its own clock. Every time on screen is a stream timestamp, never the
|
||||
local wall clock, which is why a stalled source freezes the view instead of scrolling it.
|
||||
• The window remembers itself. Rows, traces, the time window, calibration, math channels
|
||||
and measurements are written to a session file per host and port, and reloaded next time.
|
||||
|
||||
<b>Example</b>
|
||||
|
||||
A 3-signal source at 10 kS/s with a 200 MB buffer holds 1677 s of history. Enable all three,
|
||||
drop them on row 1, and the status bar reads <tt>● live · 10.0 kS/s · 2 s window</tt>.
|
||||
@@ -0,0 +1,31 @@
|
||||
<b>Choosing a source</b>
|
||||
|
||||
A source is a host and a port, optionally reached through a multicast group on a named
|
||||
interface. Pass it on the command line, or let udpscope ask.
|
||||
|
||||
<b>How to reach it</b>
|
||||
|
||||
Run with <tt>--server</tt> and the app connects straight away. Run <i>without</i>
|
||||
<tt>--server</tt> and a chooser appears first: the sessions udpscope has stored, newest
|
||||
first, plus a <b>New host…</b> form for one it has not seen. The chooser runs before any
|
||||
buffer is allocated and before any socket is opened, so declining it costs nothing.
|
||||
|
||||
<b>Worth knowing</b>
|
||||
|
||||
• The list is the sessions that <i>named a signal</i>. A session whose streamer was down
|
||||
stores empty slot names and is filtered out, which is what keeps the list the sources you
|
||||
actually configured rather than every port you have ever typed.
|
||||
• A stored row reconnects the way it was reached. The multicast group and the interface are
|
||||
written inside the session file, because the file's name (<tt>host_port.toml</tt>) cannot
|
||||
carry them.
|
||||
• <tt>--multicast</tt> still needs <tt>--server</tt>: the CONFIG message is fetched from the
|
||||
server, not from the group.
|
||||
• The <tt>×</tt> beside a row deletes that session file. Nothing else is removed.
|
||||
|
||||
<b>Example</b>
|
||||
|
||||
<tt>udpscope</tt> with two stored sessions lists
|
||||
<tt>127.0.0.1:8000 plots=1 signals=3</tt> and
|
||||
<tt>10.0.0.5:8001 plots=2 signals=4 multicast=239.1.2.3 interface=10.0.0.9</tt>.
|
||||
Activating the first reports <tt>[sources] picked 127.0.0.1:8000</tt> and continues into
|
||||
the scope with that session's layout already loaded.
|
||||
@@ -0,0 +1,30 @@
|
||||
<b>Signals and calibration</b>
|
||||
|
||||
The source's CONFIG message describes its signals: a name, a unit and a type. udpscope turns
|
||||
each enabled signal into a <i>channel</i> — a ring of values beside the shared time ring —
|
||||
and a channel is what a trace plots. Calibration is a scale and an offset applied at ingest.
|
||||
|
||||
<b>How to reach it</b>
|
||||
|
||||
The side panel (<tt>s</tt>) lists every signal with a switch. The <b>Signal list</b> item in
|
||||
the overflow menu opens the editor where the unit and the calibration live.
|
||||
|
||||
<b>Worth knowing</b>
|
||||
|
||||
• Signals start disabled, and enabling one is what starts acquiring it. A trigger on a signal
|
||||
nobody acquires can never fire, so arming a trigger enables its signal for you.
|
||||
• Calibration is applied <i>at ingest</i>, so changing it re-plans the buffer and drops the
|
||||
history. So does enabling or disabling a signal, and so does a new CONFIG. An empty plot
|
||||
for a second after one of those is the ring refilling, not a fault.
|
||||
• The stream's first signal is usually its <i>timestamp</i>, and that one is never acquired.
|
||||
It cannot be plotted, measured or used as a math source, and udpscope refuses to put it in
|
||||
a row rather than binding a trace that would read nothing for ever.
|
||||
• A signal's colour follows the <i>signal</i>, not the slot, so the same signal on two rows
|
||||
is one colour and the side panel's chip identifies it unambiguously. A signal on no row
|
||||
gets a grey chip rather than none, so the panel's rows keep their height.
|
||||
|
||||
<b>Example</b>
|
||||
|
||||
A source declaring <tt>time</tt>, <tt>sine</tt>, <tt>ramp</tt> and <tt>noise</tt> yields three
|
||||
plottable signals. Enable all three and the exit dump reads <tt>3 signals, 3 channels</tt>;
|
||||
<tt>time</tt> is not among them.
|
||||
@@ -0,0 +1,32 @@
|
||||
<b>Rows, layout and drag & drop</b>
|
||||
|
||||
The figure is a stack of rows, 1 to 8 of them, each holding up to 4 traces. Rows share one
|
||||
time axis and one left gutter, so their y labels line up and their windows cannot drift apart.
|
||||
|
||||
<b>How to reach it</b>
|
||||
|
||||
Drag a signal's chip out of the side panel (<tt>s</tt>) and drop it on a row to add a trace.
|
||||
Press <tt>l</tt>, or pick <b>Layout editor</b> from the overflow menu, to add and remove rows:
|
||||
a <tt>×</tt> appears at the top left of each row and a <tt>+</tt> on each boundary between
|
||||
rows, including above the first and below the last. The editor's own button in the top-right
|
||||
corner leaves it.
|
||||
|
||||
<b>Worth knowing</b>
|
||||
|
||||
• A drop <i>adds</i> a trace to the row's next free slot; it does not replace one. With four
|
||||
traces already on a row the drop is refused.
|
||||
• Inserting a row moves the rows below it <i>with their contents</i>. Inserting above row 1
|
||||
puts what row 1 plotted onto row 2 and leaves the new row empty — the rows are not
|
||||
renumbered under you.
|
||||
• A trace is remembered by the signal's <i>name</i>, not by its channel number, because a new
|
||||
CONFIG or an enable renumbers the channels and an index would silently re-point the trace.
|
||||
• Adding or removing a row rebuilds the figure, which is cheap, but it also re-deals every
|
||||
trace. A frozen trigger event survives the rebuild: the pinned window is restated rather
|
||||
than re-framed on the live edge.
|
||||
|
||||
<b>Example</b>
|
||||
|
||||
With three traces on row 1, pressing <tt>l</tt> shows 3 buttons (one <tt>×</tt>, two
|
||||
<tt>+</tt>). Clicking the <tt>+</tt> above row 1 gives 2 rows and 5 buttons, with the three
|
||||
traces now on row 2 — the layout probe reports exactly this as
|
||||
<tt>rows=2 buttons=5 traces=[0:-|1:sine,ramp,noise]</tt>.
|
||||
@@ -0,0 +1,17 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!--
|
||||
SPDX-License-Identifier: MIT
|
||||
|
||||
The help pages, compiled into the binary for the same reason the icons are: udpscope is
|
||||
run straight out of the build tree and has no install step, so a search path would have
|
||||
to be located at runtime and the failure mode of not locating it is a help window full
|
||||
of missing pages.
|
||||
-->
|
||||
<gresources>
|
||||
<gresource prefix="/org/udpscope/help">
|
||||
<file>01-overview.txt</file>
|
||||
<file>02-source.txt</file>
|
||||
<file>03-signals.txt</file>
|
||||
<file>04-layout.txt</file>
|
||||
</gresource>
|
||||
</gresources>
|
||||
Reference in new issue
Block a user