Repository navigation
element_linking
Most elements in the collection are simple: they are drawn, placed, wired, and that is all. A handful of element types do more — they link to each other, they constrain what the user can connect, and they change what appears in the cross-reference block and in the bill of materials.
That behaviour is decided by one attribute in the .elmt file, and set in
the element editor under File → Element properties. This page documents what
each choice does, what it writes to the file, and which options are safe to
rely on today.
The authoritative source for everything below is
sources/properties/elementdata.cpp(typeFromString,masterTypeToString,slaveTypeToString,slaveStateToString,kindInfoToXml,kindInfoFromXml) andsources/editor/ui/elementpropertieseditorwidget.cppfor the editor side.
link_type is an attribute of the root <definition> tag:
<definition version="0.90" type="element" link_type="master"
width="200" height="70" hotspot_x="100" hotspot_y="35">link_type |
Editor label (FR) | What it means |
|---|---|---|
simple |
Simple | Ordinary element. The default — an unknown or missing value falls back to this. |
master |
Maître | Owns a cross-reference: coils, protections, switches, PLC modules. |
slave |
Esclave | A contact that attaches to a master and is listed in its cross-reference. |
next_report |
Renvoi de folio suivant | Sheet report, forward. |
previous_report |
Renvoi de folio précédent | Sheet report, backward. |
terminal |
Bornier | A terminal-strip terminal. |
thumbnail |
Vignette | Thumbnail element. |
conductor_definition |
Définition de conducteur | Conductor definition. |
Anything QET does not recognise silently becomes simple (with a warning on
stderr). There is no validation error, so a typo in a hand-edited .elmt file
shows up only as an element that mysteriously stopped cross-referencing.
master, slave and terminal are the three types that also write a
<kindInformations> block. The other types do not.
<kindInformations>
<kindInformation name="type">coil</kindInformation>
</kindInformations>
type value |
Editor label (FR) | Typical element |
|---|---|---|
coil |
Bobine | Contactor and relay coils. The fallback value. |
protection |
Organe de protection | Circuit breakers, thermal relays, fuses with contacts. |
commutator |
Commutateur / bouton | Selector switches, pushbuttons. |
plc |
Module PLC | PLC / I-O module (see §5). |
<kindInformations>
<kindInformation name="type">coil</kindInformation>
<kindInformation name="max_slaves">4</kindInformation>
</kindInformations>Written only when a limit is set. The default is -1, meaning unlimited,
and -1 is never written to the file — an absent max_slaves and
max_slaves = -1 mean the same thing.
max_slaves counts slave elements, not contacts. One slave element can
itself declare number = 4, so a master with max_slaves = 4 can end up
carrying far more than four physical contacts. This is the single most common
misreading of the feature; the master reports itself as full when the count of
attached slave elements reaches the limit, regardless of how many contacts
each of those slaves represents.
In the editor the limit is a checkbox plus a spin box, shown for coil,
protection and commutator. Selecting plc hides it and forces -1.
A master can describe the contacts it actually offers, typed and labelled:
<kindInformations>
<kindInformation name="type">coil</kindInformation>
<slaveContactGroups>
<group type="NO" subtype="simple" contactCount="2" terminalCount="4">
<label>13</label>
<label>14</label>
<label>23</label>
<label>24</label>
</group>
<group type="NC" subtype="simple" contactCount="1" terminalCount="2">
<label>21</label>
<label>22</label>
</group>
</slaveContactGroups>
</kindInformations>| Attribute | Values | Meaning |
|---|---|---|
type |
NO, NC, SW, Other
|
Contact state. Defaults to NO. |
subtype |
simple, power, delayOn, delayOff, delayOnOff, plc
|
Contact kind. Defaults to simple. |
contactCount |
integer | How many contacts this group provides. Defaults to 1. |
terminalCount |
integer | Terminals in the whole group, shared out over its contacts in order. Defaults to 1. |
<label> |
text | One per terminal, in order (13, 14, …). |
The whole block is written only when the Contact groups checkbox is ticked in
the editor; when it is present on load, that checkbox is ticked again. It is not
available for plc masters.
In the element editor, changing a group's contact count changes its terminal
count with it, keeping the same number of terminals per contact (2 by default,
3 for a changeover SW). A terminal count you type yourself stands until you
change the contact count again.
By default a master's contact comb (the cross-reference drawn as contacts under a coil) shows only the slaves actually linked to it, in their order on the sheets. When the master declares contact groups, it can show all of them instead, before any slave is placed, so you can see which contacts are still free.
Turn it on in the Cross-references tab (Références croisées) of a project's properties, or of Configurer QElectroTech ▸ Nouveau projet for future projects (see Preferences reference §2). Pick the element type, keep Afficher en contacts (Show as contacts) selected, and tick Afficher tous les esclaves définis par le maître (Show all slaves defined by the master). The checkbox is greyed out while Afficher en croix (Show as cross) is selected, and hidden for PLC masters, which always draw their I/O table.
With it on:
| Slot | Drawn as |
|---|---|
| Linked to a slave | as before: the slave's position, hover and double-click to jump to it |
| Free | the contact symbol and the terminal numbers from the group, with no position and no hover or double-click |
| A linked slave with no group assigned | added after the declared groups, in sheet order |
A master that declares no contact groups draws exactly as before, with or
without the option. It is saved in the project as the showallconfiguredslaves
attribute; a project without it has the option off.
Status: shipped but unused. Of the 6 918 elements in the 10_electric
collection, 0 declare slaveContactGroups and 0 declare max_slaves.
The feature works, but no element in the shipped collection exercises it yet, so
a new element using it is breaking new ground rather than following a pattern.
In the same Références croisées (Cross-references) tab, Positionner : (position) chooses where a master's cross-reference is drawn: Sous le label de l'élément (under the element's label) or En bas de page (at the bottom of the page).
At the bottom of the page, two coils in the same column used to draw their
cross-references on the same spot, so the texts printed over each other —
1-B9 and 1-D9 read as one. Now, when the texts of two references
would overlap, the one belonging to the higher element is moved up, above
the other, in the same order as the elements on the sheet. References whose
texts do not overlap stay on the bottom row; frames, lines or empty margins
that merely touch do not count.
This is the checkbox Empiler les références dont les textes se chevauchent (stack references whose texts overlap), one per element type (coil, protective device, switch / button), in the project's properties and in Configuration ▸ Configurer QElectroTech ▸ Nouveau projet. It is ticked by default. Untick it and references are placed exactly as before, overlapping or not. It is greyed out with Sous le label de l'élément, and not shown for PLC masters.
| In the file |
stackoverlapping="false" on the project's <xref> element when unticked; a project without the attribute stacks |
| Re-placing | unticking or ticking the box re-places the open sheet at once; moving an element re-places the references too |
| Limitation | deleting a coil does not lower the references above it until the sheet is re-placed (moving an element, or reopening the project) |
Projects saved by older versions with an empty cross-reference position used to draw a contact's reference over its label. It now goes below the label, and the next save writes the position into the file (#1263).
<kindInformations>
<kindInformation name="type" show="1">simple</kindInformation>
<kindInformation name="state" show="1">NO</kindInformation>
<kindInformation name="number" show="1">1</kindInformation>
</kindInformations>All three keys are always written for a slave.
| Key | Values | Meaning |
|---|---|---|
type |
simple, power, delayOn, delayOff, delayOnOff, plc
|
Contact kind. Falls back to simple. |
state |
NO, NC, SW, Other
|
Normally open / normally closed / changeover / other. Falls back to NO. |
number |
integer | How many contacts this one element represents. |
Editor labels: Simple, Puissance, Temporisé travail, Temporisé repos,
Temporisé travail & repos for type; Normalement ouvert, Normalement
fermé, Inverseur, Other for state.
The editor's state list carries one extra entry, Esclave PLC, which is not a
state at all — picking it sets type = plc and state = Other, and disables
the type list. That is why plc appears in the type vocabulary but never in
the state vocabulary.
number is what makes a master's contact tally larger than its slave count —
see the max_slaves note above.
<kindInformations>
<kindInformation name="type">generic</kindInformation>
<kindInformation name="function">phase</kindInformation>
</kindInformations>| Key | Values | Editor labels (FR) |
|---|---|---|
type |
generic, fuse, sectional, diode, ground
|
Générique, Fusible, Séctionnable, Diode, Terre |
function |
generic, phase, neutral
|
Générique, Phase, Neutre |
Both fall back to generic.
Setting a master's type to plc replaces the max_slaves and contact-group
controls with a PLC I-O table, serialised as a <plcMasterData> block inside
<kindInformations>: row height, break positions, per-column widths,
visibility, names and order, header and cell fonts, and a <plcIOs> list of
<plcIO> entries carrying type, address, functionText, comment,
crossRef, terminalCount and the terminal names.
No element in the shipped 10_electric collection is a plc master.
For the workflow this data format supports — building the I/O table, linking a slave to a specific entry, and what the linking UI actually shows — see PLC modules.
These are not in <kindInformations>. They live in <elementInformations>
as ordinary <elementInformation> entries, and they are set per-element on the
diagram, not in the element editor:
<elementInformations>
<elementInformation show="1" name="potential_isolating">true</elementInformation>
</elementInformations>| Key | Applies to | Effect |
|---|---|---|
potential_isolating |
terminal elements | Stops electrical potential propagating through the terminal, so the two sides are numbered as separate potentials. |
auto_num_locked |
terminal elements | Terminal numbering skips this terminal instead of renumbering it. |
exclude_from_bom |
any element | Element is left out of the nomenclature / BOM export. |
All three are compared against the exact string "true". "True", "1"
and "yes" are all read as not set. The checkboxes in the element
information dialog always write "true", so this only bites when a .qet file
is edited or generated by hand.
exclude_from_bom is filtered in SQL, in the element_nomenclature_view
definition in sources/dataBase/projectdatabase.cpp.
An element carries four auxiliary information blocks, auxiliary1 through
auxiliary4, each with its own description_, designation_,
manufacturer_, manufacturer_reference_, machine_manufacturer_reference_,
supplier_, quantity_ and unity_ variants — for example
manufacturer_reference_auxiliary2. They are intended for accessories sold
with a component (auxiliary contact blocks, coils, mounting kits) so that the
nomenclature can list them as separate line items against the same element.
Like contact groups, this is shipped and dormant: no project in the shipped examples uses them.
Copy and paste a coil together with its contacts (or a PLC master with its slave I/O), or duplicate a whole sheet from the project panel's right-click Copier et coller (Copy and paste), and the copies are linked to each other, as the originals are. The originals keep their own links, and no copy links back to an original. Before PR #997 (merged 2026-09-23) every copy arrived unlinked.
If only one side is copied — the contact without its coil — the copy comes in unlinked, as before: there is nothing in the paste for it to link to. The follow-up for cut and paste, where keeping the link to the original partner would be right, is discussion #1174.
| I want to… | Set |
|---|---|
| make a coil that contacts cross-reference to |
link_type="master", type = coil
|
| make a contact that attaches to a coil |
link_type="slave", state = NO/NC/SW
|
| say a contact block holds three contacts | slave number = 3
|
| cap how many contacts may attach to a coil | master max_slaves = N (N counts slave elements) |
| describe a coil's real contact budget | master <slaveContactGroups>
|
| break a potential at a terminal | element info potential_isolating = true
|
| keep a terminal's number during renumbering | element info auto_num_locked = true
|
| hide an element from the parts list | element info exclude_from_bom = true
|
See also: Elements XML · kindInformations · elementInformations · definition attribute
