Linking wires across pages

A wire that runs off the edge of one page and continues on another is drawn in QElectroTech as a pair of folio reports — one arrow saying "continues on page 4", another on page 4 saying "comes from page 2", and a link between them.

Vocabulary. The interface and this page say page and wire; the code and some dialogs say folio and conductor. A folio report is also called a renvoi de folio. They are the same things — see the glossary at the end.

Source: sources/qetgraphicsitem/reportelement.cpp, sources/undocommand/linkelementcommand.cpp, sources/pdf_links.cpp.

1. The two halves

A folio report is an ordinary element whose link_type is one of two values:

`link_type`	Editor label	Meaning
`next_report`	Renvoi de folio suivant	the wire continues onward from here
`previous_report`	Renvoi de folio précédent	the wire arrives here from elsewhere

You place them like any other element, from the terminals and reports section of the collection, and connect a wire to each. At that point they are two unrelated arrows: placing them does not link them. The link is a separate, explicit step.

2. Making the link

Select a report element and open its properties. It offers Link the element, with a list of the free reports of the opposite kind elsewhere in the project — free meaning "not already linked to something". The list shows each candidate's wire number, function, tension/protocol, position and folio title, so you can tell two similar arrows apart.

Pick one, and the pair is linked. The operation is undoable.

To relink, unlink first: a report holds exactly one link, and linking it to a new partner replaces the old one — the previous partner is silently freed.

3. What QET checks, and what it does not

This is worth knowing precisely, because it is less than most people assume. When deciding whether two elements may be linked, QET checks two things:

Type — a next_report may only link to a previous_report, and vice versa.
Freedom — both must currently be unlinked (or already linked to each other).

That is the whole contract. QET does not check:

that the two reports are on different pages — you can link two reports on the same folio;
that either one has a wire connected at all;
that the wires at the two ends belong to the same potential, or carry the same number, or are electrically related in any way;
that the arrows point in sensible directions.

A folio report link is therefore a statement you make about your drawing, and QET renders it faithfully without verifying it. Two arrows can claim continuity between wires that have nothing to do with each other, and nothing will object.

If you want that checked, check it yourself — see §6.

4. What the label shows

The text on a report is not about itself. It describes the other end: where the wire goes, or where it came from.

The format comes from one project-wide setting, Project properties → cross-references, stored as:

<report label="%f-%l%c"/>

With the default %f-%l%c, a report whose partner sits on page 4 at row B, column 7 reads 4-B7. Change that one setting and every report in the project changes with it. The variables are the ordinary label variables — see Variables & formulas.

Because the text is generated from the partner's position, it follows the partner. Move the other arrow to a different column, insert a page ahead of it, and the label updates by itself.

Only five variables work inside a report's text

A report's dynamic text is restricted to a small set — much smaller than an ordinary element's:

Variable	Shows
`%{label}`	the wire number
`%{function}`	conductor function
`%{tension_protocol}`	tension / protocol
`%{conductor_color}`	wire colour
`%{conductor_section}`	wire section

Anything else you put in a report's composite text is stripped. If you expected %{comment} or a manufacturer field to appear on a folio report, this is why it does not.

5. Wire numbers and the link

Two behaviours follow from a report being a page-crossing marker rather than a real piece of hardware:

A report terminal is not counted as a connection. When QET builds the list of wire numbers, terminals belonging to a report element are deliberately skipped, because they do not represent a real terminal on real equipment. A wire that runs between two pages is not reported as having two extra ends.
Numbering does not cross the link automatically. The two wires are separate conductors on separate pages, each in its own potential. Giving both ends the same wire number is a matter of numbering them consistently — see Auto-numbering for how a new conductor takes or inherits a number.

6. Checking and exporting links

In an exported PDF the links become clickable. A report's label is turned into a hyperlink that jumps to its partner on the other page — so a reader can follow a wire through a set of drawings with the mouse.

There is a condition: the link is only injected when the text actually shows the label, i.e. it is the element-info text label, or a composite text containing %{label}. A report whose text you replaced with something else is still linked, but is not clickable in the PDF.

To audit every link in a project, use the CLI:

qelectrotech --export-links myproject.qet links.csv

That lists each linkable element and what it links to, flagging masters and slaves and reports that have no link. Since QET will not tell you about a forgotten arrow while you draw, this is the practical way to find one — a report with no partner is a wire that goes nowhere.

7. Vocabulary

This page says	The code says	French UI
page	diagram	folio
wire	conductor	conducteur
link between pages	folio report	renvoi de folio
onward arrow	`next_report`	renvoi de folio suivant
return arrow	`previous_report`	renvoi de folio précédent
cross-reference	master / slave	référence croisée

8. Folio reports are not cross-references

The two mechanisms look alike and are often confused:

	Folio report	Cross-reference
Links	a wire to its continuation	a coil to its contacts
Types	`next_report` ↔ `previous_report`	`master` ↔ `slave`
How many	exactly one partner each	one master, many slaves
Text shows	the other end's position	the list of contacts, or the coil's position

Cross-references are covered in Linking elements.

One rule they share, and one they do not: both require matching types and a free partner, but a master/slave pair has an extra restriction — a PLC master links only to a PLC slave, and a non-PLC master only to a non-PLC slave.

9. Things that catch people out

Placing two arrows does not link them. The link is an explicit action; a drawing can look finished and contain no links at all.
Nothing validates the link. Same page, no wire, unrelated potentials — all permitted. --export-links is the check.
Linking replaces, it does not add. A report has one partner; pointing it at a new one frees the old silently.
Most variables do not work in a report's text — only the five in §4.
The label describes the partner, not itself. If a label looks wrong, the thing to move is usually the arrow at the other end.
A report whose text does not show %{label} is not clickable in PDF, even though the link exists.