kotschak/qelectrotech-source-mirror
0
0
Fork 0
mirror of https://github.com/qelectrotech/qelectrotech-source-mirror.git synced 2026-09-20 07:14:13 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity

Add a Templates page, and correct how templates are placed 

The wiki had no page on the Modèles tab, and the one sentence that
described it said a template is "dropped back in as a group at a click".
A click is exactly what does not work: clicking and double-clicking a
template are explicit no-ops in the code, and its context menu has no
insert entry. Drag-and-drop is the only route.

That sentence has a cost. An electrician reported the feature as broken
on the forum this month (viewtopic.php?pid=23296, item 5): "dans la liste
des modèles quand j'en sélectionne un que j'ai créé, il ne se dépose pas
sur le folio". He did what the wiki said and filed a bug.

The new page covers creating a template from a selection, placing one,
where the files live and how to relocate the folder, what a .qetmak
contains, how templates compare with elements and with copy/paste, the
limitations, and the four questions people actually arrive with.

Checked against the source and against a running build rather than
written from memory: the context-menu entry and save dialog were driven
by hand, the resulting .qetmak inspected, and the "double-click does
nothing" claim measured (two elements on the folio before, two after).
The placement gestures, the storage path and the file format come from
reading the code.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CaKympWT3owLotCpEN2CFj
ispyisail
2026-09-19 12:28:13 +12:00
parent b0c030f682
commit 9e6eefa6b1
3 changed files with 202 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
_Sidebar.md
+2
@@ -32,6 +32,8 @@
**[Managing collections](collection_browser)** — folders, writability, building your own shortlist
**[Templates](templates)** — reusable multi-element blocks, and why clicking one does nothing
**[Search & Replace](search_and_replace)** — bulk property changes
**[Building a nomenclature query](nomenclature_query)** — the BOM/summary table builder
collection_browser.md
+6 -4
@@ -20,12 +20,14 @@ The Elements panel has two tabs:
| Tab | Shows |
|---|---|
| **Collections** | the element tree — common, custom, company, and anything embedded in the current project |
| **Templates** | reusable diagram fragments ("macros") you can drop onto a folio, separate from single elements |
| **Templates** | reusable diagram fragments ("macros") you drag onto a folio, separate from single elements — see **[Templates](templates)** |
A macro is a saved chunk of diagram content — elements, conductors, whatever
was selected — dropped back in as a group at a click. It is a distinct
mechanism from an element and isn't covered further here; the browsing and
folder-management rules on this page apply equally to both tabs.
was selected — dropped back in as a group. It is placed by **dragging it onto
the folio**: clicking or double-clicking its name does nothing, which catches
people out. It is a distinct mechanism from an element and is covered on its
own page, **[Templates](templates)**; the browsing and folder-management rules
on this page apply equally to both tabs.
The **search box** at the top filters the current tab as you type.
templates.md
+194
@@ -0,0 +1,194 @@
# Templates (the "Modèles" tab)
A **template** is a saved chunk of a folio — the elements you had selected,
with their own symbol definitions travelling inside the file — that you can
drop back onto any folio, in any project, as a group. QElectroTech calls them
templates in the interface and *macros* in the source and on disk (`.qetmak`);
the two words mean the same thing.
They are the right tool for the wiring block you draw over and over: a motor
starter, a lighting circuit, a standard supply arrangement. An element is one
symbol; a template is an arrangement of them.
> **Placing a template is drag-and-drop only.** Clicking or double-clicking
> its name in the list does nothing at all — deliberately, in the code — and
> its right-click menu has no "insert" entry. If you have selected a template
> and waited for something to happen, nothing was broken: drag it onto the
> folio instead. This is the single most common confusion about the feature.
---
## 1. Creating a template
1. On a folio, select the items you want to keep. Anything you can select
works — elements, conductors, texts, images.
2. **Right-click the selection → "Créer un template"**. The entry only appears
when something is selected; right-clicking empty space gives you the folio
menu instead (properties, add/remove row or column).
3. A dialog, *"Enregistrer un template"*, asks where to put it. Pick the
collection in the tree, type a name in **"Nom du nouveau template"**, and
press **Save**.
4. A message box confirms the full path it was written to.
The `.qetmak` extension is added for you, and is hidden again when the
template is listed in the panel.
> The template collection is labelled **"Makros"** in the tree — a German
> string that shows up untranslated in the French and English interfaces. It
> is the user templates folder described below.
---
## 2. Placing a template
Open the **Modèles** tab of the elements panel (beside **Collections**),
then **drag the template onto the folio**.
| Step | What happens |
|---|---|
| You drop it on the folio | A semi-transparent preview of the whole template appears and follows the pointer, snapped to the grid |
| **Left click** | The template is placed at the preview's position |
| **Right click** | Placement is cancelled, nothing is added |
| **Escape** | Also cancels — from the moment you drop, not just after the first click |
While a placement is in progress the folio's own right-click menu is switched
off, which is why right-click cancels rather than opening a menu.
What does **not** place a template, by design:
| Action | Result |
|---|---|
| Single click on the name | selects the row, nothing else |
| Double click on the name | nothing — an explicit early return in the code |
| Right-click menu on the template | offers delete (and folder management), never "insert" |
---
## 3. Where templates are stored
Templates live in their own collection, separate from elements:
| | Path |
|---|---|
| Default | *(application data folder)*`/macros/` |
| Linux | `~/.local/share/QElectroTech/QElectroTech/macros/` |
| Windows | `%APPDATA%\QElectroTech\QElectroTech\macros\` |
| macOS | `~/Library/Application Support/QElectroTech/QElectroTech/macros/` |
The exact base is Qt's *application data* location, so a portable or
sandboxed install (Snap, Flatpak, AppImage with a custom home) will resolve it
inside that sandbox rather than in your normal home folder.
You can move the folder elsewhere — a shared network drive, for instance, so a
team draws from the same template library — in
**[Preferences → General](preferences)**, in the same group of settings that
relocates the custom element and title-block collections. QElectroTech falls
back to the default folder if the configured path no longer exists, so a
missing network share leaves you with an empty template list rather than an
error.
Each template is one file. Copying a `.qetmak` into the folder makes it appear
in the panel, and deleting the file removes it; you can also create
subfolders to organise them.
---
## 4. What is inside a `.qetmak` file
A template is XML, and it carries the symbol definitions with it. That is what
makes a template portable between projects and between machines: the receiving
project does not need the elements to be installed already.
```xml
<qet_macro>
<collection>
<element path="import/lampe_pe.elmt">
<definition height="50" hotspot_x="15" hotspot_y="25" ...>
...the full symbol drawing...
</definition>
</element>
</collection>
<diagram_content>
<diagram projectId="0" ...>
<elements>
...the items you had selected...
</elements>
</diagram>
</diagram_content>
</qet_macro>
```
| Part | What it holds |
|---|---|
| `<collection>` | one `<element>` per **distinct** symbol used, with its complete definition — a template using six identical relays stores the relay once |
| `<diagram_content>` | the selected content itself, as a normal folio fragment |
| `type` attributes | rewritten to `macro://…` so the placed items resolve against the definitions carried in the file |
A template holding a single lamp is around 3 KB, almost all of it the symbol
definition.
---
## 5. Templates compared with the alternatives
| | Template (`.qetmak`) | Element (`.elmt`) | Copy & paste |
|---|---|---|---|
| Holds several items and their wiring | yes | no — one symbol | yes |
| Survives closing the project | yes | yes | no, clipboard only |
| Reusable across projects | yes | yes | only while both are open |
| Carries symbol definitions with it | yes | n/a | no |
| Placed by | dragging from the Modèles tab | dragging from the Collections tab | Ctrl+V |
| Edited after saving | re-create it from a new selection | element editor | n/a |
There is no template editor: to change a template, place it, adjust it on a
folio, and save a new template over the old name.
---
## 6. Limitations
- **Drag-and-drop is the only way to place one.** There is no menu item, no
keyboard route and no double-click shortcut.
- **Templates cannot be edited in place.** Re-create them from a corrected
selection.
- **No preview thumbnail in the panel** — templates are listed by name only,
so the names you choose are the only clue to what they contain.
- **The collection is labelled "Makros"** regardless of interface language.
- If you are running a development build from before **13 September 2026**,
dragging a template onto a folio does nothing on Qt 6 builds; that was
fixed in
[PR #853](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/853).
Update before concluding the feature is broken.
---
## 7. Troubleshooting
**"I select my template in the list and nothing lands on the folio."**
Expected: selecting does nothing. Drag it onto the folio instead. See the note
at the top of this page.
**"I dragged it and still nothing happened."**
Check the build date — see the Qt 6 note above. Then check you dropped inside
the folio's drawing area rather than the grey surround.
**"The preview is stuck to my pointer."**
A placement is in progress: left click to place it, or press Escape or right
click to cancel.
**"My templates have disappeared."**
The templates folder is configurable in Preferences → General. If it points at
a drive that is not mounted, QElectroTech shows an empty collection. Check the
path, or copy the `.qetmak` files into the default folder above.
---
## See also
- **[Managing collections](collection_browser)** — the panel the Modèles tab
lives in, and how folders and writability work
- **[Using the element editor](element_editor)** — for building the single
symbols a template is assembled from
- **[Preferences reference](preferences)** — where the templates folder is set
- **[Tips & Tricks](tips_and_tricks)** — other ways to speed up repeated
drawing