Document using the element editor -- drawing tools, not just the resulting XML

sources/editor/ is ~22,900 lines and the only wiki coverage was a stub
telling readers to see the elements_XML reference for 'designing element
graphics' and 'defining connection terminals' -- which documents the
file format an element becomes, not how to use the editor that draws it.
element_linking already covers the master/slave/terminal semantics; this
covers the tool itself.

The finding worth having written down: width, height and hotspot have no
input dialog at all. ElementScene::toXml() derives them from the drawn
geometry on every save -- bounding rect rounded up to the next multiple
of 10 (with a quirk: a remainder over 6 rounds up an extra ten, which is
exactly the 42-to-50 example elements_definition_attribute.md already
used without explaining where the number came from), hotspot centered
in that box. And if the drawing doesn't straddle the scene origin,
centerElementToOrigin() actually moves every primitive on save, not just
the saved coordinates -- draw far from the crosshair and a save visibly
shifts everything.

Also: the checkElement() validation that runs before every save (0
terminals warns but doesn't block, except folio-report and
conductor-definition elements, which must have exactly one or the save
is refused); the Save vs Save As vs Save As File distinction (opened-from
location vs a collection picker vs a raw file picker); and the terminal
placement shortcuts (Space rotates through the four orientations while
placing, the tool re-arms at the same orientation for a row of pins).

Replaces the empty 'Creating Custom Elements' stub in user_manual (all
three languages) with links to this page, element_linking and
elements_XML instead of a four-bullet list pointing at one reference
page. EN/FR/DE.
ispyisail
2026-09-12 07:02:59 +12:00
parent c1b47381b2
commit 1bf1740fc0
8 changed files with 443 additions and 15 deletions
+2
@@ -22,6 +22,8 @@
**[Linking elements](element_linking)** — master, slave, terminal
**[Using the element editor](element_editor)** — drawing tools, saving, checks
**[Linking wires across pages](folio_links)** — folio reports
**[Variables & formulas](variables)** — `%f`, `%{label}`, sequences
+142
@@ -0,0 +1,142 @@
# Den Element-Editor benutzen
**[Elemente verknüpfen](element_linking-DE)** dokumentiert die `.elmt`-Datei,
die beim Erstellen eines Elements entsteht — Master/Slave/Klemme,
Kontaktgruppen, Informationsschalter. Diese Seite dokumentiert die andere
Hälfte: ein Element im eingebauten Editor von QET tatsächlich zeichnen.
Quelle: `sources/editor/` (~22.900 Zeilen) — `qetelementeditor.cpp` (das
Fenster), `elementscene.cpp` (die Zeichenfläche), `graphicspart/` (eine
Klasse je zeichenbarer Primitive), `esevent/` (die interaktiven
Platzierungswerkzeuge), `ui/` (die Eigenschaftenfelder).
---
## 1. Ein Element beginnen
*Neues Element* öffnet einen dreistufigen Assistenten:
1. **Übergeordnete Kategorie** — wo im Sammlungsbaum das Element leben wird.
2. **Dateiname** — die Endung `*.elmt` wird automatisch ergänzt, wenn Sie sie
weglassen.
3. **Name(n)** — der Anzeigename des Elements, je einer pro Sprache; nur Ihre
aktuelle Oberflächensprache ist erforderlich, die übrigen lassen sich
später ergänzen.
Der Editor öffnet mit einer leeren Zeichenfläche. Es gibt keinen eigenen
Schritt „Größe des Elements festlegen" — siehe §3.
Sie können auch ein **vorhandenes** Element zum Bearbeiten öffnen, oder mit
einer über *Datei → DXF-Datei importieren* eingelesenen
**[DXF-Datei](dxf-DE)** als Strichzeichnung in einem neuen Element beginnen —
ein Weg, CAD-Geometrie nachzuzeichnen statt von Grund auf zu zeichnen.
---
## 2. Die Zeichenwerkzeuge
Eine Symbolleistenschaltfläche je Primitivtyp:
| Werkzeug | Zeichnet |
|---|---|
| Linie | eine gerade Strecke |
| Rechteck | Ecke-zu-Ecke ziehen |
| Ellipse | einen Begrenzungsrahmen ziehen |
| Vieleck | jeden Eckpunkt anklicken; **Doppelklick zum Abschließen**, **Rechtsklick, um den letzten Punkt rückgängig zu machen** |
| Bogen | einen Kreisbogen |
| Text | eine feste Beschriftung, nach dem Platzieren auf einem Folio nicht mehr bearbeitbar |
| Dynamisches Textfeld | ein Text, der sich je Instanz auf einem Folio bearbeiten **lässt** — hier setzen Elementinformationen und Formelvariablen an, siehe **[Variablen und Formeln](variables-DE)** |
| Klemme | ein Anschlusspunkt |
### Klemmen platzieren
Eine Klemme braucht eine Ausrichtung — auf welcher Seite des Körpers sie
heraustritt und damit, aus welcher Richtung ein Draht sie erreichen darf.
Während des Platzierens **drehen Sie sie mit der Leertaste** durch die vier
Himmelsrichtungen, bevor Sie mit einem Klick bestätigen.
Nach dem Setzen einer Klemme beginnt das Werkzeug sofort die nächste **mit
derselben Ausrichtung** — praktisch für eine Reihe gleich ausgerichteter
Pins. Ein Rechtsklick beendet das Werkzeug.
Typ und Funktion der Klemme (generisch, Sicherung, Diode, Erde …) werden
anschließend in ihren eigenen Eigenschaften eingestellt, nicht beim
Platzieren — siehe **[Elemente verknüpfen](element_linking-DE)** §4.
---
## 3. Breite, Höhe und Ankerpunkt werden berechnet, nicht eingegeben
Es gibt keinen Dialog, in dem Sie Breite, Höhe oder Ankerpunkt des Elements
eintragen. **Sie werden automatisch aus dem Gezeichneten abgeleitet und bei
jedem Speichern neu berechnet:**
- Das Begrenzungsrechteck aller Primitive auf der Zeichenfläche wird
gemessen.
- Breite und Höhe werden **aufgerundet** auf das nächste Vielfache von 10 —
mit einer Besonderheit: Beträgt der Rest mehr als 6, wird ein *weiterer*
Zehner aufgerundet. Eine 42 px breite Zeichnung wird zu 50 (genau das
Beispiel, das **[Elements XML](elements_definition_attribute)** für die
Rundung nennt — jetzt wissen Sie, woher die Zahl stammt).
- Der Ankerpunkt wird in die Mitte dieses gerundeten Begrenzungsrechtecks
gelegt.
### Die Falle: Fernab vom Szenenursprung zeichnen verschiebt die Teile
Überlappt Ihre Zeichnung nicht den Ursprungspunkt `(0,0)` der Szene,
**zentriert QET beim Speichern jede Primitive neu**, damit das der Fall ist —
Teile bewegen sich tatsächlich auf der Zeichenfläche, nicht nur in den
gespeicherten Koordinaten. Zeichnen Sie bequem nahe am Fadenkreuz in der
Mitte der Zeichenfläche, und das überrascht nie; zeichnen Sie weit an einer
Seite, und ein Speichern kann sichtbar alles verschieben.
---
## 4. Speichern
Drei verwandte Aktionen, leicht zu verwechseln:
| Aktion | Ziel |
|---|---|
| **Speichern** | dorthin, woher das Element geöffnet wurde — ein Sammlungsort, wenn es aus dem Elementpanel geöffnet wurde, ein einfacher Dateipfad, wenn es über eine Datei geöffnet wurde |
| **Speichern unter** | fragt nach einem **Sammlungsort** (Kategorie + Name), der übliche Weg, ein neues Element in Ihrer eigenen Sammlung zu speichern |
| **Speichern unter (Datei)** | fragt nach einem gewöhnlichen Dateisystempfad, außerhalb jeder Sammlung |
Alle drei führen zuerst dieselbe Prüfung aus (§5); scheitert sie, wird das
Speichern verhindert und keine der drei schreibt etwas.
---
## 5. Was vor dem Speichern geprüft wird
QET prüft das Element und meldet Probleme entweder als **Warnung** (Speichern
läuft weiter) oder als **Fehler** (Speichern wird verhindert):
| Bedingung | Schwere |
|---|---|
| Überhaupt keine Klemmen | **Warnung** — außer bei Folioverweisen, Leiterdefinitionen oder Vorschaubildern, die berechtigterweise keine haben dürfen |
| Ein Folioverweis-Element hat etwas anderes als **genau eine** Klemme | **Fehler** |
| Eine Leiterdefinition hat etwas anderes als **genau eine** Klemme | **Fehler** |
Ein Element ohne jede Klemme wird trotzdem gespeichert — Sie erhalten
lediglich einen Hinweis, dass es mit nichts verbunden werden kann, was
manchmal genau das Gewünschte ist (ein Vorschaubild, ein Textblock, eine
Schriftfeld-Verzierung).
---
## 6. Über die Grundlagen hinaus
- **SPS-Master-Tabellen.** Den Typ eines Master-Elements auf SPS zu setzen,
ersetzt die üblichen Kontaktbudget-Einstellungen durch eine interaktive
E/A-Tabelle — siehe **[Elemente verknüpfen](element_linking-DE)** §5. Kein
Element der ausgelieferten Sammlung nutzt diese Funktion derzeit.
- **Der Linienstil** (Stärke, Farbe, Strichmuster) wird je Primitive im
eigenen Eigenschaftenfeld eingestellt, nicht über die Symbolleiste.
- **Raster und Einrasten** funktionieren wie im Folio-Editor.
---
Siehe auch: **[Elemente verknüpfen](element_linking-DE)** ·
**[Elements XML](elements_XML)** · **[DXF-Import und -Export](dxf-DE)** ·
**[Variablen und Formeln](variables-DE)**
+144
@@ -0,0 +1,144 @@
# Utiliser l'éditeur d'élément
**[Lier des éléments](element_linking-FR)** documente le fichier `.elmt` qui
résulte de la création d'un élément — maître/esclave/borne, groupes de
contacts, indicateurs d'information. Cette page documente l'autre moitié :
dessiner réellement un élément dans l'éditeur intégré de QET.
Source : `sources/editor/` (~22 900 lignes) — `qetelementeditor.cpp` (la
fenêtre), `elementscene.cpp` (le plan de travail), `graphicspart/` (une classe
par primitive dessinable), `esevent/` (les outils de placement interactifs),
`ui/` (les panneaux de propriétés).
---
## 1. Démarrer un élément
*Nouvel élément* ouvre un assistant en trois étapes :
1. **Catégorie parente** — où, dans l'arborescence de la collection, l'élément
vivra.
2. **Nom de fichier** — l'extension `*.elmt` est ajoutée automatiquement si
vous l'omettez.
3. **Nom(s)** — le nom d'affichage de l'élément, un par langue ; seule votre
langue d'interface actuelle est requise, les autres peuvent être renseignées
plus tard.
L'éditeur s'ouvre sur un plan de travail vide. Il n'y a pas d'étape distincte
« définir la taille de l'élément » — voir §3.
Vous pouvez aussi ouvrir un élément **existant** pour le modifier, ou partir
d'un **[fichier DXF](dxf-FR)** importé comme tracé dans un nouvel élément via
*Fichier → Importer un fichier DXF* — une façon de calquer une géométrie CAO
plutôt que de dessiner à partir de rien.
---
## 2. Les outils de dessin
Un bouton de barre d'outils par type de primitive :
| Outil | Dessine |
|---|---|
| Ligne | un segment droit |
| Rectangle | cliquez-glissez un coin à l'autre |
| Ellipse | cliquez-glissez une boîte englobante |
| Polygone | cliquez chaque sommet ; **double-clic pour terminer**, **clic droit pour annuler le dernier point** |
| Arc | un arc de cercle |
| Texte | une étiquette fixe, non modifiable une fois placée sur un folio |
| Champ texte dynamique | un texte qui **peut** être modifié par instance sur un folio — c'est à lui que s'accrochent les informations d'élément et les variables de formule, voir **[Variables et formules](variables-FR)** |
| Borne | un point de connexion |
### Placer des bornes
Une borne a besoin d'une orientation — de quel côté du corps elle sort, et
donc de quelle direction un fil peut l'approcher. Pendant le placement,
**appuyez sur Espace pour la faire pivoter** parmi les quatre directions
cardinales avant de cliquer pour valider.
Une fois une borne posée, l'outil en démarre immédiatement une autre **avec la
même orientation** — pratique pour une rangée de broches orientées de la même
façon. Le clic droit termine l'outil.
Le *type* et la *fonction* de la borne (générique, fusible, diode, terre…) se
règlent ensuite dans ses propres propriétés, pas au moment du placement — voir
**[Lier des éléments](element_linking-FR)** §4.
---
## 3. Largeur, hauteur et point d'accroche sont calculés, pas saisis
Il n'existe aucun dialogue où saisir la largeur, la hauteur ou le point
d'accroche de l'élément. **Ils sont calculés automatiquement à partir de ce
que vous avez dessiné, et recalculés à chaque enregistrement :**
- Le rectangle englobant de toutes les primitives du plan de travail est
mesuré.
- Largeur et hauteur sont arrondies **vers le haut** au multiple de 10
supérieur — avec une particularité : si le reste dépasse 6, un dizaine
*supplémentaire* est ajoutée. Un dessin de 42 px de large devient 50 (c'est
exactement l'exemple d'arrondi utilisé par
**[Elements XML](elements_definition_attribute)** — vous savez maintenant
d'où vient ce chiffre).
- Le point d'accroche est placé au centre de ce rectangle englobant arrondi.
### Le piège : dessiner loin de l'origine de la scène déplace vos parties
Si votre dessin ne chevauche pas le point d'origine de la scène `(0,0)`, QET
**recentre toutes les primitives** à l'enregistrement pour qu'il le fasse —
les parties se déplacent réellement sur le plan de travail, pas seulement dans
les coordonnées enregistrées. Dessinez confortablement près du réticule au
centre du plan de travail et cela ne vous surprendra jamais ; dessinez loin sur
un côté et un enregistrement peut visiblement tout décaler.
---
## 4. Enregistrer
Trois actions proches, faciles à confondre :
| Action | Destination |
|---|---|
| **Enregistrer** | là d'où l'élément a été ouvert — un emplacement de collection s'il a été ouvert depuis le panneau des éléments, un simple chemin de fichier s'il a été ouvert par fichier |
| **Enregistrer sous** | demande un emplacement de **collection** (catégorie + nom), la façon normale d'enregistrer un nouvel élément dans votre collection personnelle |
| **Enregistrer sous (fichier)** | demande un chemin de système de fichiers ordinaire, hors de toute collection |
Les trois exécutent d'abord la même validation (§5) ; un contrôle échoué
bloque l'enregistrement et aucune des trois n'écrit rien.
---
## 5. Ce qui est vérifié avant l'enregistrement
QET valide l'élément et signale les problèmes comme un **avertissement**
(l'enregistrement continue) ou une **erreur** (l'enregistrement est bloqué) :
| Condition | Gravité |
|---|---|
| Aucune borne du tout | **avertissement** — sauf si l'élément est un renvoi de folio, une définition de conducteur ou une vignette, qui peuvent légitimement n'en avoir aucune |
| Un renvoi de folio possède autre chose qu'**exactement une** borne | **erreur** |
| Une définition de conducteur possède autre chose qu'**exactement une** borne | **erreur** |
Un élément sans aucune borne s'enregistre quand même — vous obtenez simplement
un dialogue indiquant qu'il ne pourra être relié à rien, ce qui est parfois
exactement ce que vous voulez (une vignette, un bloc de texte, une décoration
de cartouche).
---
## 6. Au-delà des bases
- **Tables API maîtres.** Régler le type d'un élément maître sur API
remplace les réglages habituels de budget de contacts par une table d'E-S
interactive — voir **[Lier des éléments](element_linking-FR)** §5. Aucun
élément de la collection livrée n'utilise actuellement cette fonction.
- **Le style de ligne** (épaisseur, couleur, motif de tirets) se règle par
primitive depuis son propre panneau de propriétés, pas depuis la barre
d'outils.
- **Grille et accrochage** fonctionnent comme dans l'éditeur de folio.
---
Voir aussi : **[Lier des éléments](element_linking-FR)** ·
**[Elements XML](elements_XML)** · **[Import et export DXF](dxf-FR)** ·
**[Variables et formules](variables-FR)**
+137
@@ -0,0 +1,137 @@
# Using the element editor
**[Linking elements](element_linking)** documents the `.elmt` file that
results from element authoring — master/slave/terminal, contact groups,
information flags. This page documents the other half: actually drawing an
element in QET's built-in editor.
Source: `sources/editor/` (~22,900 lines) — `qetelementeditor.cpp` (the
window), `elementscene.cpp` (the canvas), `graphicspart/` (one class per
drawable primitive), `esevent/` (the interactive placement tools), `ui/` (the
property panels).
---
## 1. Starting an element
*New element* opens a three-step wizard:
1. **Parent category** — where in the collection tree the element will live.
2. **File name** — the `*.elmt` extension is added automatically if you leave
it off.
3. **Name(s)** — the element's display name, one per language; only your
current UI language is required, the rest can be filled in later.
The editor opens on an empty canvas. There is no separate "set the element's
size" step — see §3.
You can also open an **existing** element to edit it, or start from
**[a DXF file](dxf)** imported as line art into a new element via *File →
Import a DXF file* — a way to trace CAD geometry rather than draw from
scratch.
---
## 2. The drawing tools
One toolbar button per primitive type:
| Tool | Draws |
|---|---|
| Line | a straight segment |
| Rectangle | click-drag a corner-to-corner rectangle |
| Ellipse | click-drag a bounding box |
| Polygon | click each vertex; **double-click to finish**, **right-click to undo the last point** |
| Arc | a circular arc |
| Text | a fixed label, not editable once placed on a diagram |
| Dynamic text field | a text item that **can** be edited per-instance on a diagram — this is what element information and formula variables attach to, see **[Variables & formulas](variables)** |
| Terminal | a connection point |
### Placing terminals
A terminal needs an orientation — which side of the body it points out of,
and therefore which direction a wire may approach it from. While placing one,
**press Space to rotate it** through the four cardinal directions before
clicking to commit.
After you place a terminal, the tool immediately starts another one **at the
same orientation** — convenient for a row of same-facing pins. Right-click
ends the tool.
Terminal *type* and *function* (generic, fuse, diode, ground…) are set
afterward in the terminal's own properties, not while placing it — see
**[Linking elements](element_linking)** §4.
---
## 3. Width, height and hotspot are computed, not typed
There is no dialog where you enter the element's width, height or hotspot.
**They are derived automatically from whatever you've drawn, recalculated on
every save:**
- The bounding rectangle of every primitive on the canvas is measured.
- Width and height are rounded **up** to the next multiple of 10 — with a
quirk: if the remainder is more than 6, it rounds up an *extra* ten. A
drawing 42 px wide becomes 50 (this is the exact case
**[Elements XML](elements_definition_attribute)** uses as its rounding
example — now you know where the number comes from).
- The hotspot is placed at the centre of that rounded bounding box.
### The gotcha: drawing away from the scene origin moves your parts
If your drawing doesn't straddle the scene's origin point `(0,0)`, QET
**re-centres every primitive** on save so that it does — parts actually move
on the canvas, not just in the saved coordinates. Draw comfortably near the
crosshair at the canvas centre and this never surprises you; draw far off to
one side and a save can visibly shift everything.
---
## 4. Saving
Three related actions, easy to confuse:
| Action | Destination |
|---|---|
| **Save** | wherever the element was opened from — a collection location if opened from the elements panel, a plain file path if opened by file |
| **Save As** | asks for a **collection** location (category + name), the normal way to save a new element into your custom collection |
| **Save As File** | asks for a plain filesystem path, outside any collection |
All three run the same validation first (§5); a failed check blocks the save
and none of them writes anything.
---
## 5. What's checked before saving
QET validates the element and reports problems as either a **warning** (save
proceeds) or an **error** (save is blocked):
| Condition | Severity |
|---|---|
| No terminals at all | **warning** — unless the element is a folio report, a conductor definition, or a thumbnail, which are allowed to have none |
| A folio report element has anything other than **exactly one** terminal | **error** |
| A conductor definition element has anything other than **exactly one** terminal | **error** |
An element with zero terminals still saves — you'll just get a dialog telling
you it can't be wired to anything, which is sometimes exactly what you want
(a thumbnail, a text block, a title-block decoration).
---
## 6. Beyond the basics
- **PLC master tables.** Setting a master element's type to PLC replaces the
usual contact-budget controls with an interactive I/O table — see
**[Linking elements](element_linking)** §5. No element in the shipped
collection currently uses this.
- **Line style** (weight, colour, dash pattern) is set per-primitive from its
own properties panel, not the toolbar.
- **Grid and snap** work the same way as the diagram editor.
---
See also: **[Linking elements](element_linking)** ·
**[Elements XML](elements_XML)** · **[DXF import & export](dxf)** ·
**[Variables & formulas](variables)**
+1
@@ -66,6 +66,7 @@ Beginnen Sie mit der deutschen Version dieses Wikis:
| Linking wires across pages | ✅ | ✅ | ✅ |
| Importing EPLAN parts (.edz) | ✅ | ✅ | ✅ |
| DXF import & export | ✅ | ✅ | ✅ |
| Using the element editor | ✅ | ✅ | ✅ |
**Legend:** ✅ Translated | 📋 Planned | ❌ Not yet started
+6 -5
@@ -553,11 +553,12 @@ Berichte erstellen automatisch Dokumentation aus Ihrem Schema:
### Benutzerdefinierte Elemente erstellen
Siehe **[Elemente erstellen](elements_XML)** für detaillierte Anweisungen zu:
- Entwerfen von Element-Grafiken
- Definieren von Verbindungsanschlüssen
- Erstellen von Element-Metadaten
- Verpacken zur Verteilung
**[Den Element-Editor benutzen](element_editor-DE)** behandelt das Zeichnen
eines Elements im eingebauten Editor von QET — Werkzeuge, Klemmenplatzierung
und die Prüfungen beim Speichern. **[Elemente verknüpfen](element_linking-DE)**
behandelt, wie man daraus einen Master, Slave oder eine Klemme macht.
**[Elements XML](elements_XML)** dokumentiert direkt das resultierende
Dateiformat, für alle, die `.elmt`-Dateien ohne den Editor erzeugen.
### Element-Sammlungen und Bibliotheken
+6 -5
@@ -555,11 +555,12 @@ Les rapports créent automatiquement une documentation à partir de votre schém
### Créer des Éléments Personnalisés
Voir **[Créer des Éléments](elements_XML)** pour les instructions détaillées sur :
- Concevoir des graphiques d'élément
- Définir les bornes de connexion
- Créer des métadonnées d'élément
- Empaqueter pour la distribution
**[Utiliser l'éditeur d'élément](element_editor-FR)** couvre le dessin d'un
élément dans l'éditeur intégré de QET — outils, placement des bornes et
vérifications à l'enregistrement. **[Lier des éléments](element_linking-FR)**
couvre la manière d'en faire un maître, un esclave ou une borne.
**[Elements XML](elements_XML)** documente directement le format de fichier
résultant, pour qui génère des `.elmt` sans passer par l'éditeur.
### Collections d'Éléments et Bibliothèques
+5 -5
@@ -553,11 +553,11 @@ Reports automatically create documentation from your schema:
### Creating Custom Elements
See **[Creating Elements](elements_XML)** for detailed instructions on:
- Designing element graphics
- Defining connection terminals
- Creating element metadata
- Packaging for distribution
**[Using the element editor](element_editor)** covers drawing an element in
QET's built-in editor — tools, terminal placement, and the save-time checks.
**[Linking elements](element_linking)** covers making it a master, slave or
terminal. **[Elements XML](elements_XML)** documents the resulting file
format directly, for anyone generating `.elmt` files without the editor.
### Element Collections & Libraries