From b4c9b0e3f595345aeda7f32ab5b7719b0042852c Mon Sep 17 00:00:00 2001 From: ispyisail Date: Sat, 12 Sep 2026 07:24:52 +1200 Subject: [PATCH] Document managing collections: folders, writability, the two-tab panel sources/ElementsCollection/ is the largest undocumented chunk found this session -- separate from elements_XML (the file format) and element_editor (drawing one element), nothing covered day-to-day collection management. The finding worth having written down: the common collection's read-only status is not a filesystem permissions check. ElementsLocation::isWritable() refuses anything under commonElementsDirN() unconditionally, by path -- that's why New folder/New element/rename/delete are greyed out there even running as an administrator, and why dragging an element out of the common collection copies it (there is no source to remove) while nothing can be rearranged inside it. Custom and company are genuinely writable; an embedded (project-internal) element follows the project's own read-only state. Also documents the panel's second tab -- Templates/macros, a reusable diagram-fragment mechanism distinct from single elements, drag-dropped onto a folio as a group -- and the full context-menu action set (new folder/element, edit, delete with a real not-undoable warning, reveal in file manager, reload from disk, the solo-folder filter, folder properties). Updates the Element Collections & Libraries stub in user_manual (EN/FR/DE) to link here instead of the placeholder bullets from the correction pass. EN/FR/DE. --- _Sidebar.md | 2 + collection_browser-DE.md | 96 ++++++++++++++++++++++++++++++++++++++++ collection_browser-FR.md | 96 ++++++++++++++++++++++++++++++++++++++++ collection_browser.md | 91 +++++++++++++++++++++++++++++++++++++ languages.md | 1 + user_manual-DE.md | 9 ++-- user_manual-FR.md | 10 ++--- user_manual.md | 8 ++-- 8 files changed, 296 insertions(+), 17 deletions(-) create mode 100644 collection_browser-DE.md create mode 100644 collection_browser-FR.md create mode 100644 collection_browser.md diff --git a/_Sidebar.md b/_Sidebar.md index 5cf80f6..1d1d164 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -26,6 +26,8 @@ **[Preferences reference](preferences)** — what each settings page does +**[Managing collections](collection_browser)** — folders, writability + **[Linking wires across pages](folio_links)** — folio reports **[Variables & formulas](variables)** — `%f`, `%{label}`, sequences diff --git a/collection_browser-DE.md b/collection_browser-DE.md new file mode 100644 index 0000000..3da1498 --- /dev/null +++ b/collection_browser-DE.md @@ -0,0 +1,96 @@ +# Sammlungen verwalten + +Diese Seite behandelt das **Elementepanel** selbst — Ordner organisieren, +Elemente verschieben und löschen, und was „beschreibbar" im Alltag +tatsächlich bedeutet. Getrennte Seiten behandeln das Dateiformat +(**[Elements XML](elements_XML)**) und das Zeichnen eines Elements +(**[Den Element-Editor benutzen](element_editor-DE)**). + +Quelle: `sources/ElementsCollection/` — `elementscollectionwidget.cpp` (das +Panel), `elementstreeview.cpp` / `elementscollectionmodel.cpp` (der Baum), +`elementslocation.cpp` (Identität und Beschreibbarkeit). + +--- + +## 1. Zwei Reiter, ein Panel + +Das Elementepanel hat zwei Reiter: + +| Reiter | Zeigt | +|---|---| +| **Sammlungen** | den Elementebaum — gemeinsam, eigen, Firma, und alles im aktuellen Projekt Eingebettete | +| **Vorlagen** | wiederverwendbare Folio-Ausschnitte („Makros"), die sich auf ein Folio ziehen lassen — getrennt von einzelnen Elementen | + +Ein Makro ist ein gespeicherter Ausschnitt aus einem Folio — Elemente, +Leiter, was auch immer ausgewählt war —, der sich per Klick als Gruppe +zurücksetzen lässt. Das ist ein eigener Mechanismus, kein Element, und wird +hier nicht weiter vertieft; die Regeln zum Durchsuchen und Verwalten von +Ordnern auf dieser Seite gelten für beide Reiter gleichermaßen. + +Das **Suchfeld** oben filtert den aktuellen Reiter während der Eingabe. + +--- + +## 2. Die drei Sammlungen, und welche sich wirklich bearbeiten lassen + +| Sammlung | Ort | Beschreibbar? | +|---|---|---| +| **Gemeinsam** | mit QET ausgeliefert | **Nein — immer schreibgeschützt**, unabhängig von Dateiberechtigungen auf der Platte | +| **Eigen** | Ihre eigene | ja | +| **Firma** | innerhalb einer Organisation geteilt | ja | +| **Eingebettet** | im geöffneten Projekt | folgt dem Projekt — schreibgeschützt, wenn das Projekt selbst es ist | + +Der Schreibschutz der gemeinsamen Sammlung ist **keine +Berechtigungsprüfung** — `ElementsLocation::isWritable()` verweigert sie +bedingungslos, anhand des Pfads. Deshalb sind Neuer Ordner, Neues Element, +Umbenennen und Löschen dort immer ausgegraut, selbst als Administrator. + +Alle drei obersten Pfade (dazu die beiden Schriftfeldvorlagen-Pfade und der +Makropfad) lassen sich unter +**[Einstellungen → Allgemein](preferences-DE)** verlagern. + +--- + +## 3. Elemente organisieren + +Rechtsklick im Baum für: + +| Aktion | Tut | +|---|---| +| **Neuer Ordner** | legt einen Unterordner an — nur wo die Sammlung beschreibbar ist | +| **Neues Element** | startet den **[Assistenten für neue Elemente](element_editor-DE)** in diesem Ordner | +| **Element bearbeiten** | öffnet es im Element-Editor | +| **Ordner bearbeiten** | benennt ihn um | +| **Element löschen** | fragt nach Bestätigung, entfernt dann die Datei — **nicht rückgängig zu machen** | +| **Ordner löschen** | fragt nach Bestätigung, entfernt dann den Ordner samt Inhalt — **nicht rückgängig zu machen** | +| **Entsprechenden Ordner öffnen** | zeigt den Ort im Dateimanager des Betriebssystems | +| **Sammlungen neu laden** | liest den Sammlungsbaum erneut von der Platte — nützlich nach Bearbeitung von Dateien außerhalb von QET | +| **Nur diesen Ordner anzeigen / Alle Ordner anzeigen** | ein „Solo"-Filter, um den Baum auf einen Zweig zu beschränken | +| **Ordnereigenschaften** | Dateisystempfad, dazu die Anzahl der enthaltenen Elemente und Unterordner | + +**Ziehen und Ablegen verschiebt Elemente und Ordner** zwischen Orten im +Baum, unter derselben Beschreibbarkeitsregel — aus der gemeinsamen Sammlung +**heraus** lässt sich ziehen (eine Kopie, da sich die Quelle nicht entfernen +lässt), **innerhalb** von ihr aber nichts umsortieren. + +Löschen ist echtes Löschen, kein QET-eigenes Rückgängig/Papierkorb. Könnte +ein Ordner oder Element noch gebraucht werden, verschieben Sie ihn statt ihn +zu löschen. + +--- + +## 4. In ein Projekt eingebettete Elemente + +Ein Projekt kann eine eigene Kopie der von ihm verwendeten Elemente +mitführen, unabhängig von jeder Sammlung auf der Platte — das ist die Zeile +**Eingebettet** oben. Das macht eine `.qet`-Datei in sich geschlossen: Sie +an jemanden zu schicken, nimmt Elemente aus Ihrer eigenen Sammlung mit, +korrekt dargestellt, selbst wenn der Empfänger diese Sammlung gar nicht +besitzt. + +--- + +Siehe auch: **[Elements XML](elements_XML)** · +**[Den Element-Editor benutzen](element_editor-DE)** · +**[Einstellungsreferenz](preferences-DE)** · +**[EPLAN-Teile importieren (.edz)](edz_import-DE)** diff --git a/collection_browser-FR.md b/collection_browser-FR.md new file mode 100644 index 0000000..33750dc --- /dev/null +++ b/collection_browser-FR.md @@ -0,0 +1,96 @@ +# Gérer les collections + +Cette page couvre le **panneau des éléments** lui-même — organiser des +dossiers, déplacer et supprimer des éléments, et ce que « modifiable » +signifie concrètement au quotidien. Des pages séparées couvrent le format de +fichier (**[Elements XML](elements_XML)**) et le dessin d'un élément +(**[Utiliser l'éditeur d'élément](element_editor-FR)**). + +Source : `sources/ElementsCollection/` — `elementscollectionwidget.cpp` (le +panneau), `elementstreeview.cpp` / `elementscollectionmodel.cpp` (l'arbre), +`elementslocation.cpp` (identité et modifiabilité). + +--- + +## 1. Deux onglets, un seul panneau + +Le panneau des éléments comporte deux onglets : + +| Onglet | Affiche | +|---|---| +| **Collections** | l'arbre des éléments — commune, personnelle, entreprise, et tout ce qui est intégré au projet en cours | +| **Modèles** | des fragments de folio réutilisables (« macros ») que l'on peut déposer sur un folio, distincts des éléments individuels | + +Une macro est un fragment de folio enregistré — éléments, conducteurs, tout +ce qui était sélectionné — redéposé en bloc d'un clic. C'est un mécanisme +distinct d'un élément, non détaillé davantage ici ; les règles de parcours +et de gestion de dossiers de cette page s'appliquent aux deux onglets. + +Le **champ de recherche** en haut filtre l'onglet en cours au fur et à +mesure de la saisie. + +--- + +## 2. Les trois collections, et celles que vous pouvez réellement modifier + +| Collection | Emplacement | Modifiable ? | +|---|---|---| +| **Commune** | livrée avec QET | **Non — toujours en lecture seule**, quels que soient les droits du fichier sur le disque | +| **Personnelle** | la vôtre | oui | +| **Entreprise** | partagée au sein d'une organisation | oui | +| **Intégrée** | dans le projet ouvert | suit le projet — en lecture seule si le projet lui-même l'est | + +Le statut lecture seule de la collection commune n'est **pas une +vérification de permissions** : `ElementsLocation::isWritable()` la refuse +inconditionnellement, par chemin. C'est pourquoi Nouveau dossier, Nouvel +élément, renommer et supprimer y sont toujours grisés, même en administrateur. + +Les trois chemins de premier niveau (plus les deux chemins de modèles de +cartouche et celui des macros) peuvent être relocalisés depuis +**[Préférences → Général](preferences-FR)**. + +--- + +## 3. Organiser les éléments + +Clic droit dans l'arbre pour : + +| Action | Fait | +|---|---| +| **Nouveau dossier** | crée un sous-dossier — uniquement là où la collection est modifiable | +| **Nouvel élément** | démarre l'**[assistant de nouvel élément](element_editor-FR)** dans ce dossier | +| **Éditer l'élément** | l'ouvre dans l'éditeur d'élément | +| **Éditer le dossier** | le renomme | +| **Supprimer l'élément** | demande confirmation, puis supprime le fichier — **irréversible** | +| **Supprimer le dossier** | demande confirmation, puis supprime le dossier et tout son contenu — **irréversible** | +| **Ouvrir le dossier correspondant** | révèle l'emplacement dans le gestionnaire de fichiers du système | +| **Recharger les collections** | relit l'arbre des collections depuis le disque — utile après une modification de fichiers en dehors de QET | +| **Afficher uniquement ce dossier / Afficher tous les dossiers** | un filtre « solo » pour concentrer l'arbre sur une branche | +| **Propriété du dossier** | chemin système, plus le nombre d'éléments et de sous-dossiers qu'il contient | + +**Le glisser-déposer déplace éléments et dossiers** entre emplacements de +l'arbre, sous la même règle de modifiabilité — on peut glisser *hors de* la +collection commune (une copie, puisqu'on ne peut pas retirer la source) mais +pas réorganiser *à l'intérieur*. + +La suppression est une vraie suppression, pas un annuler/corbeille propre à +QET. Si un dossier ou un élément pourrait encore servir, déplacez-le plutôt +que de le supprimer. + +--- + +## 4. Éléments intégrés à un projet + +Un projet peut porter sa propre copie des éléments qu'il utilise, +indépendamment de toute collection sur le disque — c'est la ligne +**Intégrée** ci-dessus. C'est ce qui rend un fichier `.qet` autonome : +envoyez-le à quelqu'un, et les éléments tirés de votre collection +personnelle l'accompagnent, correctement rendus, même si le destinataire ne +possède pas cette collection. + +--- + +Voir aussi : **[Elements XML](elements_XML)** · +**[Utiliser l'éditeur d'élément](element_editor-FR)** · +**[Référence des préférences](preferences-FR)** · +**[Importer des pièces EPLAN (.edz)](edz_import-FR)** diff --git a/collection_browser.md b/collection_browser.md new file mode 100644 index 0000000..48a08e7 --- /dev/null +++ b/collection_browser.md @@ -0,0 +1,91 @@ +# Managing collections + +This page covers the **Elements panel** itself — organizing folders, moving +and deleting elements, and what "writable" actually means day to day. +Separate pages cover the file format (**[Elements XML](elements_XML)**) and +drawing one element (**[Using the element editor](element_editor)**). + +Source: `sources/ElementsCollection/` — `elementscollectionwidget.cpp` (the +panel), `elementstreeview.cpp` / `elementscollectionmodel.cpp` (the tree), +`elementslocation.cpp` (identity and writability). + +--- + +## 1. Two tabs, one panel + +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 | + +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. + +The **search box** at the top filters the current tab as you type. + +--- + +## 2. The three collections, and which ones you can actually edit + +| Collection | Location | Writable? | +|---|---|---| +| **Common** | ships with QET | **No — always read-only**, regardless of file permissions on disk | +| **Custom** | yours | yes | +| **Company** | shared within an organisation | yes | +| **Embedded** | inside the open project | follows the project — read-only if the project itself is read-only | + +The common collection's read-only status is **not a permissions check** — +`ElementsLocation::isWritable()` refuses it unconditionally, by path. That's +why New folder, New element, rename and delete are always greyed out there, +even running as an administrator. + +All three top-level paths (plus the two title-block-template paths and the +macros path) can be relocated from **[Preferences → General](preferences)**. + +--- + +## 3. Organizing elements + +Right-click in the tree for: + +| Action | Does | +|---|---| +| **New folder** | creates a sub-folder — only where the collection is writable | +| **New element** | starts the **[new-element wizard](element_editor)** in that folder | +| **Edit the element** | opens it in the element editor | +| **Edit the folder** | rename it | +| **Delete the element** | asks for confirmation, then removes the file — **not undoable** | +| **Delete the folder** | asks for confirmation, then removes the folder and everything in it — **not undoable** | +| **Open the corresponding folder** | reveals the location in your OS file manager | +| **Reload collections** | re-reads the collection tree from disk — useful after editing files outside QET | +| **Show only this folder / Show all folders** | a "solo" filter, to focus the tree on one branch | +| **Folder properties** | filesystem path, plus a count of elements and sub-folders it holds | + +**Drag and drop moves elements and folders** between locations in the tree, +subject to the same writability rule — you can drag *out of* the common +collection (copying, since you can't remove the source) but not rearrange +*within* it. + +Deletion is real deletion, not a QET-level undo/trash. If a folder or +element might still be needed, move it rather than delete it. + +--- + +## 4. Elements embedded in a project + +A project can carry its own copy of elements it uses, independent of any +collection on disk — that's the **Embedded** row above. This is what makes a +`.qet` file self-contained: send someone the file, and elements you pulled +from your custom collection travel with it, correctly rendered, even though +the recipient has no such collection. + +--- + +See also: **[Elements XML](elements_XML)** · +**[Using the element editor](element_editor)** · +**[Preferences reference](preferences)** · +**[Importing EPLAN parts (.edz)](edz_import)** diff --git a/languages.md b/languages.md index 25d6bca..154b9f1 100644 --- a/languages.md +++ b/languages.md @@ -68,6 +68,7 @@ Beginnen Sie mit der deutschen Version dieses Wikis: | DXF import & export | ✅ | ✅ | ✅ | | Using the element editor | ✅ | ✅ | ✅ | | Preferences reference | ✅ | ✅ | ✅ | +| Managing collections | ✅ | ✅ | ✅ | **Legend:** ✅ Translated | 📋 Planned | ❌ Not yet started diff --git a/user_manual-DE.md b/user_manual-DE.md index ff29a02..00556fe 100644 --- a/user_manual-DE.md +++ b/user_manual-DE.md @@ -523,12 +523,9 @@ Dateiformat, für alle, die `.elmt`-Dateien ohne den Editor erzeugen. ### Element-Sammlungen und Bibliotheken -QET unterscheidet drei Sammlungen: die mitgelieferte **gemeinsame** -Sammlung, eine **eigene** Sammlung, die Ihnen gehört, und eine -**Firmen**-Sammlung für die gemeinsamen Elemente einer Organisation. Einen -integrierten Browser für ein öffentliches Online-Element-Repository gibt es -nicht — ein Element mit jemandem zu teilen heißt, die `.elmt`-Datei (oder -den ganzen Ordner der eigenen/Firmen-Sammlung) direkt weiterzugeben. +**[Sammlungen verwalten](collection_browser-DE)** behandelt das Organisieren +von Ordnern, das Verschieben und Löschen von Elementen, und welche der drei +Sammlungen (gemeinsam/eigen/Firma) sich tatsächlich bearbeiten lässt. ### Multi-Benutzer-Workflows diff --git a/user_manual-FR.md b/user_manual-FR.md index 61fa6fd..21ccaa2 100644 --- a/user_manual-FR.md +++ b/user_manual-FR.md @@ -525,12 +525,10 @@ résultant, pour qui génère des `.elmt` sans passer par l'éditeur. ### Collections d'Éléments et Bibliothèques -QET distingue trois collections : la collection **commune** livrée avec le -logiciel, une collection **personnelle** qui est la vôtre, et une collection -**entreprise** pour les éléments partagés d'une organisation. Il n'existe -pas de navigateur intégré vers un dépôt public d'éléments en ligne : -partager un élément avec quelqu'un revient à lui donner directement le -fichier `.elmt` (ou tout le dossier de collection personnelle/entreprise). +**[Gérer les collections](collection_browser-FR)** couvre l'organisation des +dossiers, le déplacement et la suppression d'éléments, et laquelle des trois +collections (commune/personnelle/entreprise) vous pouvez réellement +modifier. ### Workflows Multi-Utilisateurs diff --git a/user_manual.md b/user_manual.md index 8aba14e..08800ce 100644 --- a/user_manual.md +++ b/user_manual.md @@ -512,11 +512,9 @@ format directly, for anyone generating `.elmt` files without the editor. ### Element Collections & Libraries -QET distinguishes three collections: the **common** one it ships with, a -**custom** one that's yours, and a **company** one for an organisation's -shared elements. There is no in-app browser for a public online element -repository — sharing an element with someone else means giving them the -`.elmt` file (or the whole custom/company collection folder) directly. +**[Managing collections](collection_browser)** covers organizing folders, +moving and deleting elements, and which of the three collections +(common/custom/company) you can actually write to. ### Multi-User Workflows