diff --git a/_Sidebar.md b/_Sidebar.md index f572fc7..f8c2922 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -26,6 +26,8 @@ **[Auto-numbering](autonumbering)** — schemes, sequences, freezing +**[Title block templates](title_blocks)** — the .titleblock format + **[Elements XML](elements_XML)** * [attribute](elements_definition_attribute) * [uuid](elements_child_uuid) diff --git a/languages.md b/languages.md index 4d13a5d..daab18a 100644 --- a/languages.md +++ b/languages.md @@ -62,6 +62,7 @@ Beginnen Sie mit der deutschen Version dieses Wikis: | Variables & formulas | ✅ | ✅ | ✅ | | Terminal strips | ✅ | ✅ | ✅ | | Auto-numbering | ✅ | ✅ | ✅ | +| Title block templates | ✅ | ✅ | ✅ | **Legend:** ✅ Translated | 📋 Planned | ❌ Not yet started diff --git a/title_blocks-DE.md b/title_blocks-DE.md new file mode 100644 index 0000000..ab11c4f --- /dev/null +++ b/title_blocks-DE.md @@ -0,0 +1,225 @@ +# Schriftfeldvorlagen + +Das Schriftfeld ist das umrahmte Feld mit den Zeichnungsangaben in der Ecke +eines Folios. Sein Aufbau steckt nicht fest im Programm — er ist eine +**Vorlage**, eine `.titleblock`-Datei, die Sie ändern oder selbst schreiben +können. + +QElectroTech liefert zehn Vorlagen mit und bringt einen eigenen Editor dafür +mit. + +Quellen: `sources/titleblocktemplate.cpp`, `sources/titleblockcell.h` und +`sources/titleblock/` für den Editor. + +--- + +## 1. Eine Vorlage ist ein Raster + +Eine Vorlage ist ein Raster aus Zellen. Es gibt drei Zelltypen: + +| Typ | Zeigt | +|---|---| +| **Feld** | eine Beschriftung und einen Wert, beide dürfen Variablen enthalten | +| **Logo** | ein in der Vorlagendatei gespeichertes Bild | +| **Leer** | nichts — die Zelle hält den Platz frei | + +Zellen können benachbarte Zeilen und Spalten **überspannen**; eine breite +Titelzelle oben über einem Stapel kleiner Zellen ist nichts anderes als das. + +### Spaltenbreiten haben drei Naturen + +Das ist der Teil des Formats, den man verstehen sollte, denn er lässt eine +Vorlage zu jedem Papierformat passen. Das Attribut `cols` des Rasters ist eine +Liste von Längen, jede mit ihrem Präfix: + +| Geschrieben | Bedeutet | +|---|---| +| `120px;` | **absolut** — immer 120 Pixel | +| `t22%;` | **22 % der gesamten** verfügbaren Breite | +| `r100%;` | **100 % des Rests**, nachdem absolute und gesamtbezogene Spalten abgezogen sind | + +`cols="t22%;r100%;t22%;"` — die mitgelieferte Vorgabe — heißt also: eine Spalte +mit 22 % der Breite, dann eine, die alles Übrige aufnimmt, dann wieder 22 %. Die +mittlere Spalte dehnt sich, die äußeren behalten ihre Proportion, unabhängig von +der Breite des Folios. + +**Zeilen sind stets absolut**, als Pixelhöhen angegeben: `rows="25;25;"`. Eine +relative Zeilenhöhe gibt es nicht. + +--- + +## 2. Beschriftungen, Werte und Übersetzungen + +Eine Feldzelle enthält zwei Texte, **beide übersetzbar**: + +```xml + + + %author + + + +``` + +- Die **Beschriftung** ist die feste Aufschrift — *Autor* — und wird + üblicherweise in alle von der Vorlage unterstützten Sprachen übersetzt. +- Der **Wert** ist das, was sich je Folio ändert, und enthält gewöhnlich eine + Variable. Meist genügt ein einziger Eintrag, da `%author` in jeder Sprache + gleich ist. +- `displaylabel` entscheidet, ob die Aufschrift überhaupt gezeichnet wird. Eine + große Titelzelle setzt es meist auf `false`. +- `name` bezeichnet die Zelle innerhalb der Vorlage. Er wird **nicht** + gezeichnet. +- `hadjust` verkleinert die Schrift, wenn der Text nicht passt, statt ihn + überlaufen zu lassen. + +--- + +## 3. Variablen + +Schriftfeldzellen haben ihre eigene Ersetzung, und sie ist **großzügiger als +überall sonst in QET**: Jeder Schlüssel im Kontext des Folios wird ersetzt, in +beiden Formen. `%{author}` und `%author` wirken gleichermaßen. + +Standardschlüssel sind die Felder des Folios: `title`, `author`, `filename`, +`folio`, `plant`, `locmach`, `indexrev`, `date`, `display_folio`. +Projekteigenschaften und eigene Foliofelder werden ebenfalls ersetzt — so kann +eine Vorlage ein Feld tragen, von dem QET nichts weiß. + +Zwei Einzelheiten: + +- Schlüssel werden **vom längsten zum kürzesten** ersetzt, mit Absicht, damit + ein Schlüssel namens `plant` nicht den Anfang von `%plantcode` auffrisst. +- Nur die geschweifte Form `%{name}` lässt sich **auffinden**: Der Editor baut + seine Liste der verwendeten Variablen durch Suche nach `%{…}`; ein nacktes + `%name` wird zwar gezeichnet, kann aber von nichts aufgezählt werden. + **Bevorzugen Sie die geschweifte Form** in Vorlagen. + +Vollständige Referenz: **[Variablen und Formeln](variables)**. + +--- + +## 4. Logos + +Logos werden **in** der Vorlagendatei gespeichert; eine Vorlage ist damit in +sich geschlossen und lässt sich als eine Datei weitergeben. + +Das Tag `` steht für zwei verschiedene Dinge — gut zu wissen, bevor man +eine Datei von Hand bearbeitet: + +```xml + + + + … + + + + + + +``` + +In `` ist es das Bild, in `` eine Zelle, die ein Bild über +`resource` bezeichnet. + +Zwei Speicherformen: + +| `storage` | Für | Wie | +|---|---|---| +| `xml` | nur SVG | der ``-Baum wird direkt als XML eingebettet | +| `base64` | jedes Rasterbild (und SVG, wenn man darauf besteht) | die Rohbytes, base64-kodiert, als Text | + +**Rasterbilder können nur als `base64` gespeichert werden** — QET erzwingt das, +gleich was man angibt. SVG kann beides, und `xml` ist die vernünftige Wahl: Die +Datei bleibt vergleichbar und das Logo skalierbar. + +Fügt man ein Logo über den Editor hinzu, versucht QET zuerst SVG und fällt dann +auf Raster zurück; die Speicherform wird also für Sie gewählt. + +> **Bekannter Fehler.** Ein ``, dessen Attribut `storage` weder `xml` noch +> `base64` ist, verliert beim Speichern seine Bilddaten: Das Element wird mit +> seinen Attributen und ohne Inhalt geschrieben, stillschweigend. Der Code +> enthält den Rückfall, der das verhindern würde, benutzt ihn aber nicht. Nur +> von Hand geschriebene oder erzeugte Dateien können darauf laufen — keine der +> mitgelieferten Vorlagen. Bleiben Sie bei den beiden gültigen Werten. + +--- + +## 5. Wo Vorlagen liegen + +Vier Sammlungen, in QETs eigenem Vokabular: + +| Sammlung | Ort | Für | +|---|---|---| +| **Gemeinsam** | `titleblocks/` neben dem Programm | die mit QET gelieferten Vorlagen | +| **Firma** | `/titleblocks-company/` | gemeinsame Vorlagen einer Organisation | +| **Benutzer** | `/titleblocks/` | Ihre eigenen | +| **Eingebettet** | in der `.qet`-Datei | Vorlagen, die ein Projekt mitführt | + +Die eingebettete zählt beim Weitergeben: Ein Projekt, das eine von Ihnen +geschriebene Vorlage nutzt, führt eine Kopie mit und wird daher auch auf einem +Rechner richtig dargestellt, der Ihre Vorlage nie gesehen hat. + +--- + +## 6. Das Format auf einen Blick + +```xml + + + + + + %author + + + … + + +``` + +| Element | Enthält | +|---|---| +| `` | freier Text über die Vorlage — Autor, Zweck | +| `` | die gespeicherten Bilder | +| `` | `cols`, `rows` und die Zellen | +| `` | eine Feldzelle | +| `` (im Raster) | eine Logozelle | +| `` | eine leere Zelle | + +Der **Tagname einer Zelle ist ihr Typ**: `field`, `logo` oder `empty`. +Gemeinsame Attribute sind `row`, `col`, `rowspan`, `colspan` und `name`. Ein +`field` ergänzt `align` (`left`/`center`/`right`), `valign`, `displaylabel`, +`hadjust` und `fontsize` — Letzteres nur, wenn eine Größe gesetzt wurde; ein +fehlendes `fontsize` heißt also „Vorgabe“. Eine `logo`-Zelle ergänzt +`resource`. + +--- + +## 7. Praktische Hinweise + +- **Entwerfen Sie für die Dehnung, nicht für eine feste Breite.** Geben Sie den + Zellen, die ihre Proportion halten müssen, eine `t…%`-Breite und lassen Sie + eine Spalte `r100%` nehmen. Eine nur aus absoluten Breiten gebaute Vorlage + sieht auf einem anderen Papierformat falsch aus. +- **Übersetzen Sie Beschriftungen, nicht Werte.** Ein Wert ist meist eine + Variable und in jeder Sprache gleich. +- **Nutzen Sie `%{geschweifte}` Variablen**, damit der Editor sie auflisten kann. +- **Halten Sie eine Vorlage in sich geschlossen.** Logos leben in der Datei; + verlassen Sie sich nicht auf einen externen Pfad. +- **Ein eigenes Foliofeld genügt für eine zusätzliche Zeile.** Sie müssen QET + nicht ändern, um projektspezifische Angaben zu zeigen: Fügen Sie das Feld dem + Folio hinzu und verweisen Sie mit `%{meinfeld}` darauf. + +--- + +Siehe auch: **[Variablen und Formeln](variables)** · +**[Automatische Nummerierung](autonumbering)** · +[Project XML](project_XML) diff --git a/title_blocks-FR.md b/title_blocks-FR.md new file mode 100644 index 0000000..c48c7fd --- /dev/null +++ b/title_blocks-FR.md @@ -0,0 +1,225 @@ +# Modèles de cartouche + +Le cartouche est le panneau encadré d'informations, dans un coin du folio. Sa +disposition n'est pas figée dans le programme : c'est un **modèle**, un fichier +`.titleblock`, que vous pouvez modifier ou réécrire. + +QElectroTech livre dix modèles et dispose d'un éditeur dédié. + +Sources : `sources/titleblocktemplate.cpp`, `sources/titleblockcell.h`, et +`sources/titleblock/` pour l'éditeur. + +--- + +## 1. Un modèle est une grille + +Un modèle est une grille de cellules, de trois types : + +| Type | Affiche | +|---|---| +| **Champ** | un libellé et une valeur, l'un comme l'autre pouvant contenir des variables | +| **Logo** | une image stockée dans le fichier modèle | +| **Vide** | rien — la cellule réserve la place | + +Les cellules peuvent **fusionner** lignes et colonnes voisines : une large +cellule de titre en haut surmontant une pile de petites cellules, ce n'est que +de la fusion. + +### Les largeurs de colonnes ont trois natures + +C'est la partie du format qu'il faut comprendre, car c'est elle qui permet à un +modèle de s'adapter à tout format de papier. L'attribut `cols` de la grille est +une liste de longueurs, chacune avec son préfixe : + +| Écrit | Signifie | +|---|---| +| `120px;` | **absolu** — toujours 120 pixels | +| `t22%;` | **22 % du total** de la largeur disponible | +| `r100%;` | **100 % du reste**, une fois retirées les colonnes absolues et relatives au total | + +Ainsi `cols="t22%;r100%;t22%;"` — le défaut livré — signifie : une colonne de +22 % de la largeur, puis une colonne qui absorbe tout le reste, puis encore +22 %. La colonne centrale s'étire et les deux extérieures gardent leurs +proportions, quelle que soit la largeur du folio. + +**Les lignes sont toujours absolues**, données en pixels : `rows="25;25;"`. Il +n'existe pas de hauteur de ligne relative. + +--- + +## 2. Libellés, valeurs et traductions + +Une cellule de champ contient deux textes, **tous deux traduisibles** : + +```xml + + + %author + + + +``` + +- Le **libellé** est la légende fixe — *Auteur* — normalement traduite dans + toutes les langues que le modèle prend en charge. +- La **valeur** est ce qui change d'un folio à l'autre, et contient + habituellement une variable. Une seule entrée suffit le plus souvent, puisque + `%author` est identique dans toutes les langues. +- `displaylabel` décide si la légende est dessinée. Une grande cellule de titre + le met généralement à `false`. +- `name` identifie la cellule dans le modèle. Il n'est **pas** dessiné. +- `hadjust` réduit la police quand le texte ne tient pas, au lieu de le laisser + déborder. + +--- + +## 3. Variables + +Les cellules de cartouche ont leur propre substitution, **plus permissive que +partout ailleurs dans QET** : toute clé du contexte du folio est remplacée, sous +les deux formes. `%{author}` et `%author` fonctionnent l'un comme l'autre. + +Les clés standard sont les champs du folio : `title`, `author`, `filename`, +`folio`, `plant`, `locmach`, `indexrev`, `date`, `display_folio`. Les +propriétés du projet et tout champ de folio personnalisé sont également +substitués — c'est ainsi qu'un modèle peut porter un champ dont QET ignore tout. + +Deux détails : + +- Les clés sont substituées **de la plus longue à la plus courte**, + délibérément, pour qu'une clé nommée `plant` ne puisse pas manger le début de + `%plantcode`. +- Seule la forme entre accolades `%{nom}` peut être **découverte** : l'éditeur + construit sa liste de variables employées en cherchant `%{…}` ; un `%nom` nu + s'affiche bien mais rien ne peut l'énumérer. **Préférez la forme entre + accolades** dans un modèle. + +Référence complète : **[Variables et formules](variables)**. + +--- + +## 4. Logos + +Les logos sont stockés **dans** le fichier modèle : un modèle est donc autonome +et se partage en un seul fichier. + +La balise `` sert à deux choses différentes, ce qu'il vaut mieux savoir +avant d'éditer un fichier à la main : + +```xml + + + + … + + + + + + +``` + +Dans `` c'est l'image ; dans `` c'est une cellule, qui désigne une +image par `resource`. + +Deux formes de stockage : + +| `storage` | Pour | Comment | +|---|---|---| +| `xml` | SVG uniquement | l'arbre `` est intégré directement en XML | +| `base64` | toute image matricielle (et le SVG, si vous y tenez) | les octets bruts, encodés en base64, sous forme de texte | + +**Les images matricielles ne peuvent être stockées qu'en `base64`** — QET +l'impose, quoi que vous demandiez. Le SVG accepte les deux, et `xml` est le +choix raisonnable : le fichier reste comparable et le logo reste vectoriel. + +Quand vous ajoutez un logo depuis l'éditeur, QET essaie d'abord le SVG puis se +rabat sur le matriciel : la forme de stockage est donc choisie pour vous. + +> **Défaut connu.** Un `` dont l'attribut `storage` n'est ni `xml` ni +> `base64` perd son image à l'enregistrement : l'élément est écrit avec ses +> attributs et sans contenu, silencieusement. Le code contient le repli qui +> l'éviterait mais ne s'en sert pas. Seuls des fichiers écrits à la main ou +> générés peuvent tomber dessus — aucun modèle livré n'est concerné. Tenez-vous +> aux deux valeurs valides. + +--- + +## 5. Où vivent les modèles + +Quatre collections, dans le vocabulaire de QET : + +| Collection | Emplacement | Pour | +|---|---|---| +| **Commune** | `titleblocks/` à côté du binaire | les modèles livrés avec QET | +| **Entreprise** | `/titleblocks-company/` | les modèles partagés d'une organisation | +| **Utilisateur** | `/titleblocks/` | les vôtres | +| **Intégrée** | à l'intérieur du fichier `.qet` | les modèles portés par un projet | + +L'intégrée est celle qui compte pour le partage : un projet utilisant un modèle +que vous avez écrit en emporte une copie, et s'affiche donc correctement sur une +machine qui n'a jamais vu votre modèle. + +--- + +## 6. Le format en un coup d'œil + +```xml + + + + + + %author + + + … + + +``` + +| Élément | Contient | +|---|---| +| `` | texte libre sur le modèle — auteur, usage | +| `` | les images stockées | +| `` | `cols`, `rows`, et les cellules | +| `` | une cellule de champ | +| `` (dans la grille) | une cellule de logo | +| `` | une cellule vide | + +Le **nom de balise d'une cellule est son type** : `field`, `logo` ou `empty`. +Les attributs communs sont `row`, `col`, `rowspan`, `colspan` et `name`. Un +`field` ajoute `align` (`left`/`center`/`right`), `valign`, `displaylabel`, +`hadjust` et `fontsize` — ce dernier écrit seulement si une taille a été fixée, +un `fontsize` absent signifiant donc « par défaut ». Une cellule `logo` ajoute +`resource`. + +--- + +## 7. Notes pratiques + +- **Concevez pour l'étirement, non pour une largeur fixe.** Donnez une largeur + `t…%` aux cellules qui doivent garder leurs proportions et laissez une colonne + prendre `r100%`. Un modèle bâti uniquement sur des largeurs absolues sera mal + proportionné sur un autre format de papier. +- **Traduisez les libellés, pas les valeurs.** Une valeur est le plus souvent une + variable, identique dans toutes les langues. +- **Utilisez les variables `%{entre accolades}`** pour que l'éditeur puisse les + lister. +- **Gardez un modèle autonome.** Les logos vivent dans le fichier ; ne dépendez + pas d'un chemin externe. +- **Un champ de folio personnalisé suffit à ajouter une ligne.** Nul besoin de + modifier QET pour afficher une information propre à votre projet : ajoutez le + champ au folio et référencez-le par `%{monchamp}`. + +--- + +Voir aussi : **[Variables et formules](variables)** · +**[Numérotation automatique](autonumbering)** · +[Project XML](project_XML) diff --git a/title_blocks.md b/title_blocks.md new file mode 100644 index 0000000..e242ff3 --- /dev/null +++ b/title_blocks.md @@ -0,0 +1,220 @@ +# Title block templates + +The title block is the framed panel of drawing information in the corner of a +folio. Its layout is not hard-coded — it is a **template**, a `.titleblock` +file, and you can edit or write your own. + +QElectroTech ships ten templates and includes a dedicated editor for them. + +Source: `sources/titleblocktemplate.cpp`, `sources/titleblockcell.h`, and +`sources/titleblock/` for the editor. + +--- + +## 1. A template is a grid + +A template is a grid of cells. Each cell is one of three types: + +| Type | Shows | +|---|---| +| **Text** | a label and a value, either of which may contain variables | +| **Logo** | an image stored inside the template file | +| **Empty** | nothing — it reserves space | + +Cells can **span** neighbouring rows and columns, so a wide title cell across +the top and a stack of small cells below is just spanning. + +### Column widths use three kinds of length + +This is the part of the format worth understanding, because it is what makes a +template fit any paper size. The grid's `cols` attribute is a list of lengths, +each with a prefix: + +| Written | Means | +|---|---| +| `120px;` | **absolute** — always 120 pixels | +| `t22%;` | **22% of the total** width available | +| `r100%;` | **100% of the remaining** width, after absolute and total-relative columns are taken out | + +So `cols="t22%;r100%;t22%;"` — the shipped default — is: a column of 22% of the +width, then a column that absorbs everything left over, then another 22%. The +middle column stretches and the outer two stay proportional, whatever the +folio's width. + +**Rows are always absolute**, given as plain pixel heights: `rows="25;25;"`. +There is no relative row height. + +--- + +## 2. Labels, values and translations + +A text cell holds two pieces of text, and **both are translatable**: + +```xml + + + %author + + + +``` + +- The **label** is the fixed caption — *Author* — and is normally translated + into every language the template supports. +- The **value** is what changes per folio, and normally holds a variable. It + usually needs only one entry, since `%author` is the same in every language. +- `displaylabel` decides whether the caption is drawn at all. A big title cell + typically sets it `false`. +- `name` identifies the cell inside the template. It is **not** drawn. +- `hadjust` shrinks the font when the text does not fit, rather than letting it + overflow. + +--- + +## 3. Variables + +Title block cells use their own substitution, and it is **more permissive than +anywhere else in QET**: every key in the folio's context is replaced, in both +the braced and bare forms. `%{author}` and `%author` both work. + +Standard keys are the folio's own fields: `title`, `author`, `filename`, +`folio`, `plant`, `locmach`, `indexrev`, `date`, `display_folio`. Project +properties and any custom folio fields are substituted too — which is how a +template can carry a field QET knows nothing about. + +Two details: + +- Keys are substituted **longest first**, deliberately, so a key named `plant` + cannot eat the front of `%plantcode`. +- Only the braced form `%{name}` can be **discovered**. The editor builds its + list of variables in use by scanning for `%{…}`; a bare `%name` still + renders but nothing can enumerate it. **Prefer the braced form** when writing + a template. + +Full variable reference: **[Variables & formulas](variables)**. + +--- + +## 4. Logos + +Logos are stored **inside** the template file, so a template is self-contained +and can be shared as one file. + +The `` tag is used for two different things, which is worth knowing before +you hand-edit a file: + +```xml + + + + … + + + + + + +``` + +Inside `` it is the image; inside `` it is a cell, referring to an +image by `resource`. + +Two storage forms: + +| `storage` | For | How | +|---|---|---| +| `xml` | SVG only | the `` tree is embedded directly as XML | +| `base64` | any bitmap (and SVG, if you insist) | the raw bytes, base64 encoded, as text | + +**Bitmaps can only be stored as `base64`** — QET forces it regardless of what +you ask for. SVG can use either, and `xml` is the sensible choice: it keeps the +file diffable and lets the logo scale. + +When you add a logo through the editor, QET tries SVG first and falls back to +bitmap, so the storage form is chosen for you. + +> **Known defect.** A `` whose `storage` attribute is neither `xml` nor +> `base64` loses its image data when the template is saved: the element is +> written with its attributes and no content, silently. The code contains the +> fallback that would prevent this but does not use it. Only hand-written or +> generated files can hit this — none of the shipped templates do. Keep +> `storage` to the two valid values. + +--- + +## 5. Where templates live + +Four collections, in QET's own vocabulary: + +| Collection | Location | For | +|---|---|---| +| **Common** | `titleblocks/` next to the binary | the templates that ship with QET | +| **Company** | `/titleblocks-company/` | an organisation's shared templates | +| **Custom** | `/titleblocks/` | your own | +| **Embedded** | inside the `.qet` file | templates carried by a project | + +Embedded is the one that matters for sharing work: a project that uses a +template you wrote carries a copy, so it renders correctly on a machine that has +never seen your template. + +--- + +## 6. The file format at a glance + +```xml + + + + + + %author + + + … + + +``` + +| Element | Holds | +|---|---| +| `` | free text about the template — author, purpose | +| `` | the stored images | +| `` | `cols`, `rows`, and the cells | +| `` | a text cell | +| `` (in grid) | a logo cell | +| `` | an empty cell | + +The cell's **tag name is its type**: `field`, `logo` or `empty`. Common +attributes are `row`, `col`, `rowspan`, `colspan` and `name`. A `field` adds +`align` (`left`/`center`/`right`), `valign`, `displaylabel`, `hadjust` and +`fontsize` — the last written only when a size has actually been set, so an +absent `fontsize` means "default". A `logo` cell adds `resource`. + +--- + +## 7. Practical notes + +- **Design against the stretch, not a fixed width.** Give the cells that must + keep their proportions a `t…%` width and let one column take `r100%`. A + template built from absolute widths only will look wrong on a different paper + size. +- **Translate labels, not values.** A value is usually a variable and the same + in every language. +- **Use `%{braced}` variables** so the editor can list them. +- **Keep a template self-contained.** Logos live inside the file; do not rely on + an external path. +- **A custom folio field is enough to add a row.** You do not need to modify + QET to show project-specific information — add the field to the folio and + reference it as `%{yourfield}`. + +--- + +See also: **[Variables & formulas](variables)** · +**[Auto-numbering](autonumbering)** · +[Project XML](project_XML)