udpscope/help/C/org.udpscope.app/layout.page

<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 &amp; 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>, or pick <gui>Layout editor</gui> from the overflow 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, 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="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>