<b>Trigger</b>

The trigger watches one signal for a condition and captures a window around it. The
<b>Shape</b> dropdown chooses what counts as an event; the arming, hold-off, pre/post window
and Normal/Single mode are the same for all four shapes.
The captured window is frozen on screen until you re-arm.

<b>How to reach it</b>

The trigger button in the toolbar (<tt>t</tt>) reveals the trigger panel: the signal, the level,
the shape, the edge (rising, falling, either), the mode (Normal or Single) and the pre-trigger
share. <b>Arm</b> starts watching; <tt>a</tt> arms and disarms from the keyboard.
<b>Search the buffer</b> is at the foot of the same panel.

<b>Worth knowing</b>

• <b>Every triggered acquisition is kept.</b> Latches are written to the event cache
  (<tt>~/.cache/udpscope/events/&lt;source&gt;/</tt>) as a <tt>.npy</tt> of the event, a
  <tt>.txt</tt> of what it was, and a <tt>.bmp</tt> picture drawn from the samples. The
  <b>Events</b> pane on the left -- opened from the toolbar's event-history button, which appears
  while recording is enabled, and collapsed until you ask for it -- lists the last 32 newest first
  (time, duration, signals, rate), each row with its own picture beside the numbers. Clicking a row
  <i>replays</i> it: the stored event is loaded exactly like an exported file, <b>without changing the
  layout</b> -- the rows, the colours, the window, the cursors and the measurements stay where they
  are and read the stored data instead. A replay leaves trigger mode, because a file has no edge to
  wait for, and the pane stays open. Drag the pane's edge to resize it. <b>Live</b> goes back to the
  stream; the status bar names the file until you do.
  Select two or more events in the list and the two buttons under the header act on them:
  <b>Compare</b> puts two events in two plots side by side, keeping the layout you have -- one plot per
  event, the axes synchronised, so zooming a row in one zooms the same row in the other -- and
  <b>Accumulate</b> overlays up to four of them in the same traces, translucent, so where they agree
  the trace is brighter. Your own traces stay where they are in both. They need events with the same
  signals and the same length. A single click selects, a <i>double</i> click replays.
  <b>Record events</b>, in the trigger panel with the trigger's other options, is what decides whether
  anything is kept. It is <b>off by default</b> -- nothing is written to disk until you ask -- and
  with it off the history button goes with it.

• Arming <i>enables</i> the signal if it was off, because a trigger on a signal nobody acquires
  can never fire.
• The pre-trigger share is a share of the <i>display window</i>, not of the ring. A 2 s window
  at 50% captures 1 s before the edge and 1 s after.
• There are four display states, and the status bar names each: <tt>armed</tt> (watching,
  nothing drawn yet), <tt>capturing</tt> (the edge was accepted and the post window is filling
  <i>in view</i>, with the marker at x = 0), <tt>event held</tt> (the frozen capture) and
  <tt>disarmed</tt>. A held capture is never quietly replaced by live data.
• The first edge after arming is only accepted once the history reaches back a full pre-trigger
  window, so a capture may legitimately be shorter than you asked for. The axis is pinned to
  what the capture actually got.
• Disarming <i>during</i> a capture publishes what the capture got to, so the picture on screen
  at that moment stays on screen. No event fired, so the event count does not move.
• The trigger reads the <b>stored</b> signal — decimated and averaged — not the wire signal.
  A spike narrower than one decimation group is filtered away rather than triggering on data
  the buffer does not contain.
• The four shapes: <b>edge</b> — a crossing of the level in the chosen direction, the classic
  behaviour. <b>Pulse width</b> — a crossing and its return, qualified by how long the excursion
  lasted: less than, greater than, within or outside a pair of widths; the event is timed at the
  closing edge. <b>Window</b> — the signal entering or leaving a band between two levels; the
  panel keeps the two levels at least one increment apart, because a zero-width band is not a
  band: the condition becomes an exact float-equality test against the level, which an ordinary
  signal never satisfies and a signal sitting at the level satisfies on every transition.
  <b>Dropout</b> —
  the absence of a crossing for longer than a timeout; one event per outage, re-arms when a
  crossing returns.
• The shape's own rows are the only ones shown; the rest are hidden, so the panel never offers
  a pulse width to a window trigger.
• <b>Search the buffer</b> runs the same condition over the whole retained ring and lists every
  place it holds. The arrows step through hits; each step pauses on the hit, centred, exactly as
  the Pause button does. Up to 16 hits in the visible window are marked on every row; when there
  are more the panel says how many and suggests zooming in. The search uses the trigger's own
  condition, set in one place, so a hit is by construction an instant the trigger would have fired.

<b>Example</b>

A 1 Hz sine, level 0, rising, 2 s window at 50%, Single. The capture spans
<tt>[-1.000 .. 1.000]</tt> with <tt>n=20001</tt> samples at 10 kS/s — the span times the real
rate, plus one — and the marker sits at x = 0 throughout.
