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:

<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>

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.

4. Logos

Logos are stored inside the template file, so a template is self-contained and can be shared as one file.

The <logo> tag is used for two different things, which is worth knowing before you hand-edit a file:

<logos>
    <!-- the stored image itself -->
    <logo storage="xml" type="svg" name="qelectrotech.svg">
        <svg …>…</svg>
    </logo>
</logos>
<grid cols="…" rows="…">
    <!-- a cell that displays one -->
    <logo row="0" col="0" rowspan="1" name="" resource="qelectrotech.svg"/>
</grid>

Inside <logos> it is the image; inside <grid> it is a cell, referring to an image by resource.

Two storage forms:

`storage`	For	How
`xml`	SVG only	the `<svg>` 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 <logo> 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	`<data dir>/titleblocks-company/`	an organisation's shared templates
Custom	`<data dir>/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

<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="en">Author</translation></label>
        </field>
        …
    </grid>
</titleblocktemplate>

Element	Holds
`<information>`	free text about the template — author, purpose
`<logos>`	the stored images
`<grid>`	`cols`, `rows`, and the cells
`<field>`	a text cell
`<logo>` (in grid)	a logo cell
`<empty>`	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}.