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 :

<field row="0" col="0" name="author" align="left" valign="center"
       displaylabel="true" hadjust="true">
    <value>
        <translation lang="en">%author</translation>
    </value>
    <label>
        <translation lang="en">Author</translation>
        <translation lang="fr">Auteur</translation>
        <translation lang="de">Autor</translation>
    </label>
</field>

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.

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 <logo> sert à deux choses différentes, ce qu'il vaut mieux savoir avant d'éditer un fichier à la main :

<logos>
    <!-- l'image stockée elle-même -->
    <logo storage="xml" type="svg" name="qelectrotech.svg">
        <svg …>…</svg>
    </logo>
</logos>
<grid cols="…" rows="…">
    <!-- une cellule qui en affiche un -->
    <logo row="0" col="0" rowspan="1" name="" resource="qelectrotech.svg"/>
</grid>

Dans <logos> c'est l'image ; dans <grid> c'est une cellule, qui désigne une image par resource.

Deux formes de stockage :

`storage`	Pour	Comment
`xml`	SVG uniquement	l'arbre `<svg>` 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 <logo> 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	`<dossier de données>/titleblocks-company/`	les modèles partagés d'une organisation
Utilisateur	`<dossier de données>/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

<titleblocktemplate name="default">
    <information></information>
    <logos/>
    <grid cols="t22%;r100%;t22%;" rows="25;25;">
        <field row="0" col="0" name="author" align="left" valign="center"
               displaylabel="true" hadjust="true">
            <value><translation lang="en">%author</translation></value>
            <label><translation lang="fr">Auteur</translation></label>
        </field>
        …
    </grid>
</titleblocktemplate>

Élément	Contient
`<information>`	texte libre sur le modèle — auteur, usage
`<logos>`	les images stockées
`<grid>`	`cols`, `rows`, et les cellules
`<field>`	une cellule de champ
`<logo>` (dans la grille)	une cellule de logo
`<empty>`	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}.