Martino Ferrari
bdf0ff7ddc
A batch of view and instrument work, with the probes and docs for each. - **Full screen per figure row**: a toggle on each row's top-right corner, revealed by pointer proximity (`kMaximizeRevealPx` around its placed rect, per row, read from an overlay-level motion controller so a revealed button under the pointer cannot flicker); the plot menu offers the same as *Full screen this figure* / *Restore the layout*. The arrangement is saved and restored through `RowState`, so nothing plotted moves. A layout of one figure carries no toggle. - **Second window**: `open_scope_window()` copies a figure (cells, width shares, signals in their colours) or opens an empty one, with its own `RowSet` and `PlotArea`; the main window's tick binds, acquires and repaints it, mirroring the time window and pin. Entries: the plot menu's *Open this plot in a new window* and the overflow menu's *New scope window*. - **Layout editor from the plot**: the plot menu gains *Edit the layout...* / *Done editing the layout*, flipping the app's one toggle. - **Measurements gate**: `MeasureOptions::gate` restricts a measurement to the held/pause snapshot (live falls back to the live ring), persisted with the session and shown in the measure dialog. - **Crosshair axis badges**: a preference (`crosshair_axis_labels`, on by default) and the plotter's badges where the lines meet the axes, in the axes' own formats; the plot menu and the probe read them. - **Event cache per configuration**: `EventStore` is keyed `<source>/<configuration>/`, `retarget_event_store()` follows every configuration switch, and a pre-configuration cache (loose files) is adopted into the configuration's folder on first start. - **GTK4 lifecycle**: the main window's handlers move from the non-existent `"destroy"` signal to `close-request`; scope windows are closed with it and the application quits explicitly (the exit run's hang). The exit probe closes with `gtk_window_close()`. - Probes: `[maximize-probe]` (single-figure rule and the corner reveal), `[scope-probe]`, `[split-probe]` cell crosshair leg, `[prefs-probe]` store keying, `[configs]` store key, `[rowmenu]` layout-editor entry; docs, help pages, README and AGENT.md updated. Also fixes a probe-only use-after-free: `toggle_maximize_figure_row` replaces the figure object, so the area must be re-pointed (the button's path does; the probe's raw call did not).
122 lines
6.6 KiB
Plaintext
122 lines
6.6 KiB
Plaintext
<page xmlns="http://projectmallard.org/1.0/"
|
||
type="topic" style="task"
|
||
id="layout">
|
||
|
||
<info>
|
||
<link type="guide" xref="index#main"/>
|
||
<link type="seealso" xref="signals"/>
|
||
<desc>How the figure's rows, plots and traces are arranged, how to drop a signal onto a plot, and
|
||
how the layout editor adds and removes rows and splits a row into plots side by side.</desc>
|
||
<credit type="author copyright">
|
||
<name>Martino Ferrari</name>
|
||
</credit>
|
||
</info>
|
||
|
||
<title>Rows, layout and drag & drop</title>
|
||
|
||
<p>The figure is a stack of rows holding 1 to 8 plots in all, and a row can be split into up
|
||
to 4 plots side by side. Each plot holds up to 4 traces. Every plot shares one time axis and
|
||
the figure has one pair of side margins, so the y labels line up, the data areas start and
|
||
end on the same two columns, and the windows cannot drift apart. The left
|
||
margin holds the y labels; the right one is empty, and is there so the newest tick's label
|
||
and the newest sample's ink have somewhere to land instead of sitting on the frame.</p>
|
||
|
||
<section id="reach">
|
||
<title>How to reach it</title>
|
||
<steps>
|
||
<item>
|
||
<p>Drag a signal's badge from the badge bar onto a row to
|
||
add a trace.</p>
|
||
</item>
|
||
<item>
|
||
<p>Press <key>l</key>, pick <gui>Layout editor</gui> from the overflow menu, or pick
|
||
<gui>Edit the layout…</gui> from a plot's right-click menu, to add
|
||
and remove rows: a <gui>×</gui> appears at the top left of each plot and a <gui>+</gui>
|
||
on each boundary between rows, including above the first and below the last.</p>
|
||
</item>
|
||
<item>
|
||
<p>The editor's own button in the top-right corner leaves it.</p>
|
||
</item>
|
||
</steps>
|
||
</section>
|
||
|
||
<section id="split">
|
||
<title>Splitting a row</title>
|
||
<steps>
|
||
<item>
|
||
<p>In the layout editor, click the <gui>+</gui> at a row's left or right edge, or the
|
||
<gui>+</gui> between two plots, to add a plot to that row. The new plot starts empty.</p>
|
||
</item>
|
||
<item>
|
||
<p>Drag the double-headed arrow on the boundary between two plots to resize them. Neither plot can be
|
||
made narrower than about 96 px, and the widths are saved with the session.</p>
|
||
</item>
|
||
<item>
|
||
<p>Click the <gui>×</gui> of a plot in a split row to remove that plot and its traces.
|
||
In a row with a single plot the <gui>×</gui> removes the row instead.</p>
|
||
</item>
|
||
</steps>
|
||
<p>All the plots of a row, and of the whole figure, share one time window: zooming or
|
||
panning along time in any of them moves all of them, and the vertical cursors are drawn in
|
||
every plot. The plots of a split row also share one y range: the y labels are drawn at the
|
||
left of the first plot only, the horizontal cursors sit at the same values in every plot, the
|
||
hover crosshair's horizontal line spans all of them, and a
|
||
zoom, pan, fit or fixed range in any of them applies to the whole row. The time labels
|
||
sit under the bottom row, and under any row above it whose columns differ from the row below. A row holds at most 4 plots and the figure at most 8
|
||
in total; the <gui>+</gui> buttons go grey at the limit.</p>
|
||
</section>
|
||
|
||
<section id="fullscreen">
|
||
<title>A row full screen, and a second window</title>
|
||
<list>
|
||
<item><p>Every row carries a <gui>full-screen</gui> button in its top-right corner: it comes
|
||
out of hiding when the pointer moves near that corner and hides again when it leaves, so the
|
||
plot is not decorated by a control you are not reaching for. One click makes that row fill the plot area — the
|
||
other rows step aside with everything they were plotting — and the same button (now the
|
||
restore icon) brings the whole layout back exactly as it was. It is a view, not an edit:
|
||
nothing is saved, nothing is dropped, and the rows' traces, colours and cursors come back
|
||
where they were. The plot's right-click menu offers the same as <gui>Full screen this
|
||
figure</gui> (and <gui>Restore the layout</gui> while one is enlarged). A layout of a single
|
||
figure has nothing to enlarge *to*, so it carries no button.</p></item>
|
||
<item><p>A plot's right-click menu has <gui>Open this plot in a new window</gui>: a second
|
||
window showing the same stream through a copy of that figure (its cells, their widths and
|
||
every trace), with its own axes following the main window's time window. The overflow menu's
|
||
<gui>New scope window</gui> opens the same kind of window with an empty figure. Closing one
|
||
closes that view only; the main window keeps acquiring.</p></item>
|
||
</list>
|
||
</section>
|
||
|
||
<section id="knowing">
|
||
<title>Worth knowing</title>
|
||
<list>
|
||
<item><p>A plot's own <gui>right-click menu</gui> (the same compact rows as the app's
|
||
menu) holds the y-axis scale (for the whole row), the two fits, and <gui>Remove signal</gui>, which swaps
|
||
the menu to that plot's traces plus <gui>All traces on this plot</gui> — with a
|
||
<gui>Back</gui> row to return. That is how a trace comes off a row without going through
|
||
the layout editor.</p></item>
|
||
<item><p>A drop <em>adds</em> a trace to the row's next free slot; it does not replace
|
||
one. With four traces already on a plot the drop is refused.</p></item>
|
||
<item><p>Inserting a row moves the rows below it <em>with their contents</em>, split
|
||
rows included. 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 split row's plots are named
|
||
<em>2a</em>, <em>2b</em> and so on.</p></item>
|
||
<item><p>A trace is remembered by the signal's <em>name</em>, not by its channel number,
|
||
because a new CONFIG or an enable renumbers the channels and an index would silently
|
||
re-point the trace.</p></item>
|
||
<item><p>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.</p></item>
|
||
</list>
|
||
</section>
|
||
|
||
<section id="example">
|
||
<title>Example</title>
|
||
<p>With three traces on row 1, pressing <key>l</key> shows 7 buttons: the <gui>×</gui>,
|
||
the two <gui>+</gui> above and below the row with their two resize arrows, and the two
|
||
<gui>+</gui> at the row's left and right edges. Clicking the <gui>+</gui> above row 1 gives 2 rows and 12 buttons,
|
||
with the three traces now on row 2 — the layout probe reports exactly this as
|
||
<code>rows=2 buttons=12 traces=[0:-|1:sine,ramp,noise]</code>.</p>
|
||
</section>
|
||
|
||
</page>
|