forked from AG_QGIS/Plugin_SN_Basis
188 lines
4.4 KiB
Plaintext
188 lines
4.4 KiB
Plaintext
# Wrapper‑Architektur – Übersicht
|
||
Die Wrapper‑Architektur von sn_basis bildet das Fundament für eine robuste, testbare und zukunftssichere QGIS‑Plugin‑Entwicklung.
|
||
Sie kapselt sämtliche QGIS‑ und Qt‑Abhängigkeiten hinter klar definierten Schnittstellen und ermöglicht dadurch:
|
||
|
||
Mock‑fähige Unit‑Tests ohne QGIS
|
||
|
||
PyQt5/6‑Kompatibilität ohne Code‑Änderungen
|
||
|
||
saubere Trennung von UI, Logik und Infrastruktur
|
||
|
||
stabile APIs, die unabhängig von QGIS‑Versionen bleiben
|
||
|
||
klare Erweiterbarkeit für zukünftige Module und Plugins
|
||
|
||
Die Wrapper‑Schicht ist das zentrale Bindeglied zwischen der Plugin‑Logik und der QGIS‑/Qt‑Umgebung.
|
||
|
||
## Ziele der Wrapper‑Architektur
|
||
🎯 1. Entkopplung von QGIS und Qt
|
||
Alle direkten Importe wie from qgis.core import ... oder from qgis.PyQt.QtWidgets import ... verschwinden aus der Plugin‑Logik.
|
||
Stattdessen werden sie über Wrapper‑Module abstrahiert.
|
||
|
||
🎯 2. Testbarkeit ohne QGIS
|
||
Im Mock‑Modus liefern die Wrapper:
|
||
|
||
Dummy‑Objekte
|
||
|
||
simulierte Rückgabewerte
|
||
|
||
speicherbare Zustände (z. B. Variablen, Layer, Nachrichten)
|
||
|
||
Damit laufen Tests in jeder CI‑Umgebung.
|
||
|
||
🎯 3. Einheitliche API für alle Plugins
|
||
Plugins greifen nicht mehr direkt auf QGIS zu, sondern nutzen:
|
||
|
||
Code
|
||
sn_basis.functions.qgiscore_wrapper
|
||
sn_basis.functions.qgisui_wrapper
|
||
sn_basis.functions.qt_wrapper
|
||
sn_basis.functions.variable_wrapper
|
||
sn_basis.functions.message_wrapper
|
||
sn_basis.functions.dialog_wrapper
|
||
🎯 4. Zukunftssicherheit
|
||
Ändert sich die QGIS‑ oder Qt‑API, wird nur der Wrapper angepasst, nicht jedes Plugin.
|
||
|
||
## Architekturüberblick
|
||
Die Wrapper‑Schicht besteht aus mehreren Modulen, die jeweils einen klar abgegrenzten Verantwortungsbereich haben.
|
||
|
||
### 1. qt_wrapper – Qt‑Abstraktion
|
||
Kapselt alle Qt‑Widgets, Dialoge und Konstanten:
|
||
|
||
QWidget, QDialog, QMessageBox, QToolBar, QMenu, …
|
||
|
||
Layouts, Buttons, Labels, LineEdits
|
||
|
||
Qt‑Konstanten wie YES, NO, Dock‑Areas
|
||
|
||
Mock‑Modus:
|
||
Stellt Dummy‑Widgets bereit, die keine UI öffnen.
|
||
|
||
### 2. qgiscore_wrapper – QGIS‑Core‑Abstraktion
|
||
Abstraktion für:
|
||
|
||
QgsProject
|
||
|
||
Layer‑Zugriff
|
||
|
||
Projekt‑Metadaten
|
||
|
||
Pfade, CRS, Feature‑Zugriff
|
||
|
||
Mock‑Modus:
|
||
Simuliert ein Projekt und Layer‑Container.
|
||
|
||
### 3. qgisui_wrapper – QGIS‑UI‑Abstraktion
|
||
Kapselt UI‑bezogene QGIS‑Funktionen:
|
||
|
||
Zugriff auf iface
|
||
|
||
Dock‑Management
|
||
|
||
Menü‑ und Toolbar‑Integration
|
||
|
||
Hauptfenster‑Zugriff
|
||
|
||
Mock‑Modus:
|
||
Stellt ein Dummy‑Interface bereit.
|
||
|
||
### 4. variable_wrapper – QGIS‑Variablen
|
||
Abstraktion für:
|
||
|
||
Projektvariablen (projectScope)
|
||
|
||
globale Variablen (globalScope)
|
||
|
||
Mock‑Speicher für Tests
|
||
|
||
Vorteile:
|
||
|
||
keine QGIS‑Abhängigkeit in der Logik
|
||
|
||
testbare Variablenverwaltung
|
||
|
||
einheitliches API
|
||
|
||
### 5. message_wrapper – Meldungen & Logging
|
||
Einheitliche Schnittstelle für:
|
||
|
||
Fehlermeldungen
|
||
|
||
Warnungen
|
||
|
||
Info‑Meldungen
|
||
|
||
Logging
|
||
|
||
Mock‑Modus:
|
||
Speichert Nachrichten statt sie an QGIS zu senden.
|
||
|
||
### 6. dialog_wrapper – Benutzer‑Dialoge
|
||
Abstraktion für:
|
||
|
||
Ja/Nein‑Dialoge
|
||
|
||
spätere Erweiterungen (Eingabedialoge, Dateidialoge, etc.)
|
||
|
||
Mock‑Modus:
|
||
Gibt Default‑Werte zurück, öffnet keine UI.
|
||
|
||
### 7. DockManager & Navigation
|
||
Diese Module nutzen die Wrapper‑Schicht, um:
|
||
|
||
DockWidgets sicher zu verwalten
|
||
|
||
Toolbars und Menüs zu erzeugen
|
||
|
||
Reload‑sichere UI‑Strukturen aufzubauen
|
||
|
||
Sie sind keine Wrapper, sondern Wrapper‑Konsumenten.
|
||
|
||
## Designprinzipien
|
||
🧱 1. Single Source of Truth
|
||
Jede QGIS‑ oder Qt‑Funktionalität wird nur an einer Stelle implementiert.
|
||
|
||
🔄 2. Austauschbarkeit
|
||
Mock‑Modus und Echtmodus sind vollständig austauschbar.
|
||
|
||
🧪 3. Testbarkeit
|
||
Jede Funktion kann ohne QGIS getestet werden.
|
||
|
||
🧼 4. Saubere Trennung
|
||
UI → qt_wrapper
|
||
|
||
QGIS‑Core → qgiscore_wrapper
|
||
|
||
QGIS‑UI → qgisui_wrapper
|
||
|
||
Logik → settings_logic, layer_logic, prüfmanager, …
|
||
|
||
🔌 5. Erweiterbarkeit
|
||
Neue Wrapper können jederzeit ergänzt werden, ohne bestehende Plugins zu brechen.
|
||
|
||
## Vorteile für Entwickler
|
||
Keine QGIS‑Abhängigkeiten in der Logik
|
||
|
||
IDE‑freundlich (Pylance, Autocomplete, Typing)
|
||
|
||
CI‑fähig (Tests ohne QGIS)
|
||
|
||
saubere Architektur
|
||
|
||
leichte Wartbarkeit
|
||
|
||
klare Dokumentation
|
||
|
||
## Fazit
|
||
Die Wrapper‑Architektur ist das Herzstück von sn_basis.
|
||
Sie ermöglicht eine moderne, modulare und testbare QGIS‑Plugin‑Entwicklung, die unabhängig von QGIS‑Versionen, Qt‑Versionen und Entwicklungsumgebungen funktioniert.
|
||
|
||
Sie bildet die Grundlage für:
|
||
|
||
stabile APIs
|
||
|
||
saubere UI‑Abstraktion
|
||
|
||
automatisierte Tests
|
||
|
||
nachhaltige Weiterentwicklung |