16.1. Plug-ins voor Python structureren

De belangrijkste stappen voor het maken van een plug-in zijn:

Idee: Heb een idee over wat u wilt doen met uw nieuwe plug-in voor QGIS.
Instellen: De bestanden voor uw plug-in maken. Afhankelijk van het type plug-in, sommige zijn verplicht, waar andere optioneel zijn
Ontwikkel: De code schrijven in toepasselijke bestanden
Documenteren: De documentatie voor de plug-in schrijven
Optioneel: Vertalen: Uw plug-in vertalen in verschillende talen
Testen: Uw plug-in opnieuw laden om te controleren of alles OK is
Publiceren: Publiceer uw plug-in in de opslagplaats van QGIS of maak uw eigen opslagplaats als een “arsenaal” van persoonlijke “wapens voor GIS”.

16.1.1. Beginnen 

Kijk eerst eens in de Officiële Python plug-in opslagplaats vóór het beginnen te schrijven van een nieuwe plug-in. De broncode van bestaande plug-ins kan u helpen meer te leren over programmeren. U zou ook kunnen vinden dat een soortgelijke plug-in al bestaat en u zou in staat kunnen zijn die uit te breiden of tenminste erop doorbouwen om uw eigen te ontwikkelen.

16.1.1.1. De bestandsstructuur van de plug-in instellen 

We moeten de noodzakelijk bestanden voor de plug-in instellen om te beginnen met een nieuwe plug-in.

Er zijn twee sjabloonbronnen voor plug-ins die u op weg zouden kunnen helkpen:

Voor educatieve doeleinden of wanneer een minimalistische benadering gewenst is, verschaft de minimal plugin template de noodzakelijke basisbestanden (skelet) om een geldige plug-in voor Python in QGIS te maken.
Voor een meer volledige sjabloon voor plug-ins kan de Plugin Builder sjablonen maken voor meerdere verschillende typen plug-ins, inclusief objecten mogelijkheden, zoals lokalisatie (vertaling) en testen.

Een map voor een normale plug-in bevat de volgende bestanden:

metadata.txt - vereist - Bevat algemene informatie, versie, naam en enkele andere metadata, gebruikt door de website van de plug-in en infrastructuur van de plug-in.
__init__.py - required - Het beginpunt van de plug-in. Het moet de methode classFactory() hebben en mag elke andere code voor initialisatie hebben.
mainPlugin.py - broncode - De belangrijkste werkende code van de plug-in. Bevat alle informatie over de acties van de plug-in en de hoofdcode.
form.ui - voor plug-ins met aangepaste gebruikersinterface - De gebruikersinterface die is gemaakt met Qt Designer.
form.py - gecompileerde gebruikersinterface - De vertaling van form.ui, hierboven beschreven, naar Python.
resources.qrc - optioneel - Het door Qt Designer gemaakte .xml-document. Bevat relatieve paden naar de bronnen van de formulieren voor de gebruikersinterface.
resources.py - gecompileerde bronnen, optioneel - De vertaling van het bestand .qrc, hierboven beschreven, naar Python.

Waarschuwing

Als u van plan bent de plug-in te uploaden naar Officiële Python plug-in opslagplaats moet u controleren of uw plug-in enkele aanvullende regels volgt, vereist voor plug-in Validatie.

16.1.2. Een plug-in schrijven 

Het volgende gedeelte laat zien welke inhoud zou moeten worden ingevoegd in elke van de hierboven geïntroduceerde bestanden.

16.1.2.1. metadata.txt 

Als eerste moet Plug-ins beheren en installeren enige basisinformatie ophalen over de plug-in, zoals de naam, omschrijving etc. ervan. Deze informatie wordt opgeslagen in metadata.txt.

Notitie

Alle metadata moet in de codering UTF-8 zijn.

Naam van de metadata	Vereist	Opmerkingen
name	Ja	een korte string die de naam van de plug-in bevat
qgisMinimumVersion	Ja	notatie, met punten, van de minimale versie van QGIS
qgisMaximumVersion	Nee	notatie, met punten, van de maximale versie van QGIS
description	Ja	korte tekst die de plug-in beschrijft, geen HTML toegestaan
about	Ja	langere tekst die de plug-in tot in detail beschrijft, geen HTML toegestaan
version	Ja	korte string met de versie in notatie met punten
author	Ja	naam van de auteur
email	Ja	e-mail van de auteur, alleen weergegeven op de website voor ingelogde gebruikers, maar zichtbaar in Plug-ins beheren en installeren nadat de plug-in is geïnstalleerd
changelog	Nee	string, mag meerdere regels zijn, geen HTML toegestaan
experimental	Nee	Booleaanse vlag, `True` of `False` - True als deze versie experimenteel is
deprecated	Nee	Booleaanse vlag, `True` of `False`, is van toepassing op de gehele plug-in en niet alleen op de geüploade versie
tags	Nee	kommagescheiden lijst, spaties zijn binnen de individuele tags toegestaan
homepage	Nee	een geldige URL die verwijst naar de startpagina voor uw plug-in
repository	Ja	een geldige URL voor de opslagplaats van de broncode
tracker	Nee	een geldige URL voor tickets en probleemrapporten
icon	Nee	een bestandsnaam of een relatief pad (relatief ten opzichte van de basismap van het gecomprimeerde pakket van de plug-in) of een webvriendelijke afbeelding (PNG, JPEG)
category	Nee	één van `Raster`, `Vector`, `Database`, `Mesh` en `Web`
plugin_dependencies	Nee	PIP-achtige kommagescheiden lijst van andere te installeren plug-ins, gebruik de namen van de plug-in vanuit hun veld voor de naam in de metadata
server	Nee	Booleaanse vlag, `True` of `False`, bepaalt of de plug-in een server-interface heeft
hasProcessingProvider	Nee	Booleaanse vlag, `True` of `False`, bepaalt of de plug-in algoritmes voor Processing verschaft

Standaard worden plug-ins geplaatst in het menu Plugins (we zullen in het volgende gedeelte zien hoe een menu-item toe te voegen voor uw plug-in), maar zij kunnen ook worden geplaatst in de menu’s Raster, Vector, Database, Mazen en Web.

Een overeenkomend item voor de metadata “category” bestaat om dat te specificeren, zodat de plug-in overeenkomstig kan worden geclassificeerd. Dit item voor de metadata wordt gebruikt als tip voor de gebruikers en vertelt ze waar (in welk menu) de plug-in kan worden gevonden. Toegestane waarden voor “category” zijn: Vector, Raster, Database of Web. Als u bijvoorbeeld wilt dat uw plug-in bereikbaar is in het menu Raster, voeg dat dan toe aan metadata.txt

category=Raster

Notitie

Als qgisMaximumVersion leeg is, zal het automatisch worden ingesteld op de hoofdversie plus .99 indien geüpload naar de Officiële Python plug-in opslagplaats.

Een voorbeeld voor dit metadata.txt

; the next section is mandatory

[general]
name=HelloWorld
email=me@example.com
author=Just Me
qgisMinimumVersion=3.0
description=This is an example plugin for greeting the world.
    Multiline is allowed:
    lines starting with spaces belong to the same
    field, in this case to the "description" field.
    HTML formatting is not allowed.
about=This paragraph can contain a detailed description
    of the plugin. Multiline is allowed, HTML is not.
version=version 1.2
tracker=http://bugs.itopen.it
repository=http://www.itopen.it/repo
; end of mandatory metadata

; start of optional metadata
category=Raster
changelog=The changelog lists the plugin versions
    and their changes as in the example below:
    1.0 - First stable release
    0.9 - All features implemented
    0.8 - First testing release

; Tags are in comma separated value format, spaces are allowed within the
; tag name.
; Tags should be in English language. Please also check for existing tags and
; synonyms before creating a new one.
tags=wkt,raster,hello world

; these metadata can be empty, they will eventually become mandatory.
homepage=https://www.itopen.it
icon=icon.png

; experimental flag (applies to the single version)
experimental=True

; deprecated flag (applies to the whole plugin and not only to the uploaded version)
deprecated=False

; if empty, it will be automatically set to major version + .99
qgisMaximumVersion=3.99

; Since QGIS 3.8, a comma separated list of plugins to be installed
; (or upgraded) can be specified.
; The example below will try to install (or upgrade) "MyOtherPlugin" version 1.12
; and any version of "YetAnotherPlugin".
; Both "MyOtherPlugin" and "YetAnotherPlugin" names come from their own metadata's
; name field
plugin_dependencies=MyOtherPlugin==1.12,YetAnotherPlugin

16.1.2.2. init.py 

Dit bestand wordt vereist door het systeem voor importeren van Python. Ook vereist QGIS dat dit bestand een functie classFactory() bevat, die wordt aangeroepen als de plug-in wordt geladen in QGIS. Het ontvangt een verwijzing naar de instance van QgisInterface en moet een object teruggeven van de klasse van uw plug-in uit mainplugin.py — in ons geval is dat genaamd TestPlugin (zie hieronder). Zo zou __init__.py er uit moeten zien

def classFactory(iface):
  from .mainPlugin import TestPlugin
  return TestPlugin(iface)

# any other initialisation needed

16.1.2.3. mainPlugin.py 

Dit is waar de magie gebeurt en dit is hoe de magie eruit ziet: (bijv. mainPlugin.py)

from qgis.PyQt.QtGui import *
from qgis.PyQt.QtWidgets import *

# initialize Qt resources from file resources.py
from . import resources

class TestPlugin:

  def __init__(self, iface):
    # save reference to the QGIS interface
    self.iface = iface

  def initGui(self):
    # create action that will start plugin configuration
    self.action = QAction(QIcon("testplug:icon.png"),
                          "Test plugin",
                          self.iface.mainWindow())
    self.action.setObjectName("testAction")
    self.action.setWhatsThis("Configuration for test plugin")
    self.action.setStatusTip("This is status tip")
    self.action.triggered.connect(self.run)

    # add toolbar button and menu item
    self.iface.addToolBarIcon(self.action)
    self.iface.addPluginToMenu("&Test plugins", self.action)

    # connect to signal renderComplete which is emitted when canvas
    # rendering is done
    self.iface.mapCanvas().renderComplete.connect(self.renderTest)

  def unload(self):
    # remove the plugin menu item and icon
    self.iface.removePluginMenu("&Test plugins", self.action)
    self.iface.removeToolBarIcon(self.action)

    # disconnect form signal of the canvas
    self.iface.mapCanvas().renderComplete.disconnect(self.renderTest)

  def run(self):
    # create and show a configuration dialog or something similar
    print("TestPlugin: run called!")

  def renderTest(self, painter):
    # use painter for drawing to map canvas
    print("TestPlugin: renderTest called!")

De enige functies voor plug-ins die moeten bestaan in het hoofd-bronbestand (bijv. mainPlugin.py) zijn:

__init__ dat toegang geeft tot de interface van QGIS
initGui() aangeroepen als de plug-in wordt geladen
unload() aangeroepen als de plug-in wordt ontladen

In het voorbeeld hierboven wordt addPluginToMenu() gebruikt. Dit zal de overeenkomstige actie voor het menu toevoegen aan het menu Plug-ins. Alternatieve methoden bestaan om de actie aan een ander menu toe te wijzen. Hier is een lijst met die methoden:

Alle hebben dezelfde syntaxis als de methode addPluginToMenu().

Toevoegen van het menu van uw plug-in aan een van de voorgedefinieerde methoden wordt aanbevolen om consistentie te behouden in hoe items voor plug-ins zijn georganiseerd. U kunt echter uw aangepaste groepen voor het menu direct aan de Menubalk toevoegen, zoals het volgende voorbeeld demonstreert:

def initGui(self):
    self.menu = QMenu(self.iface.mainWindow())
    self.menu.setObjectName("testMenu")
    self.menu.setTitle("MyMenu")

    self.action = QAction(QIcon("testplug:icon.png"),
                          "Test plugin",
                          self.iface.mainWindow())
    self.action.setObjectName("testAction")
    self.action.setWhatsThis("Configuration for test plugin")
    self.action.setStatusTip("This is status tip")
    self.action.triggered.connect(self.run)
    self.menu.addAction(self.action)

    menuBar = self.iface.mainWindow().menuBar()
    menuBar.insertMenu(self.iface.firstRightStandardMenu().menuAction(),
                       self.menu)

def unload(self):
    self.menu.deleteLater()

Vergeet niet om QAction en QMenu objectName in te stellen op een naam die specifiek is voor uw plug-in zodat hij kan worden aangepast.

Hoewel acties Help en Over ook kunnen worden toegevoegd aan uw aangepaste menu, is een handiger plaats om ze beschikbaar te maken het QGIS hoofdmenu van Help ► Plug-ins. Dit wordt gedaan met de methode pluginHelpMenu().

def initGui(self):

    self.help_action = QAction(
        QIcon("testplug:icon.png"),
        self.tr("Test Plugin..."),
        self.iface.mainWindow()
    )
    # Add the action to the Help menu
    self.iface.pluginHelpMenu().addAction(self.help_action)

    self.help_action.triggered.connect(self.show_help)

@staticmethod
def show_help():
    """ Open the online help. """
    QDesktopServices.openUrl(QUrl('https://docs.qgis.org'))

def unload(self):

    self.iface.pluginHelpMenu().removeAction(self.help_action)
    del self.help_action

Bij het werken aan een echte plug-in is het verstandig om de plug-in in een andere (werk-)map te schrijven en een makefile te maken dat de UI + bronbestanden zal maken en de plug-in zal installeren in uw installatie van QGIS.

16.1.3. Documenteren van plug-ins 

De documentatie voor de plug-in mag worden geschreven als helpbestanden in HTML. De module qgis.utils verschaft een functie, showPluginHelp() dat de browser voor Helpbestanden zal openen, op dezelfde manier als andere help voor QGIS.

De functie showPluginHelp`() zoekt naar de helpbestanden in dezelfde map als waar de module wordt aangeroepen. Het zal zoeken naar, op volgorde, index-ll_cc.html, index-ll.html, index-en.html, index-en_us.html en index.html, en geeft die, welke als eerste wordt gevonden, weer. Hier is ll_cc de locale van QGIS. Dit maakt het mogelijk meerdere vertalingen van de documentatie op te nemen met de plug-in.

De functie showPluginHelp() kan ook de parameters packageName , welke een specifieke plug-in specificeert waarvoor de Helpbestanden zullen worden weergegeven, filename, wat “index” mag vervangen in de namen van de gezochte bestanden, en section, wat de naam is van een tag voor een HTML-anker in het document waar de browser zal worden gepositioneerd, aannemen.

16.1.4. Vertalen van plug-ins 

Met enkele stappen kunt u de omgeving instellen voor de vertaling van de plug-in zodat, afhankelijk van de instellingen voor de locale op uw computer, zal de plug-in worden geladen in verschillende talen.

16.1.4.1. Software vereisten 

De eenvoudigste manier om alle bestanden voor vertalingen te maken en te beheren is om Qt Linguist te installeren. In een op Debian gebaseerde GNU/ Linux-achtige omgeving kunt u het installeren door te typen:

sudo apt install qttools5-dev-tools

16.1.4.2. Bestanden en map 

Wanneer u de plug-in maakt vindt u de map i18n in de hoofdmap van de map.

Alle bestanden voor de vertalingen moeten in deze map staan.

16.1.4.2.1. .pro-bestand 

Eerst zou u een .pro-bestand moeten maken, dat is een project-bestand dat kan worden beheerd door Qt Linguist.

In dit .pro-bestand dient u alle bestanden en formulieren te specificeren die u wilt vertalen. Dit bestand wordt gebruikt om de bestanden en variabelen voor de vertalingen in te stellen. Een mogelijk projectbestand dat overeenkomt met de structuur van onze voorbeeld plug-in:

FORMS = ../form.ui
SOURCES = ../your_plugin.py
TRANSLATIONS = your_plugin_it.ts

Uw plug-in zou een meer complexe structuur kunnen hebben, en het zou uit meerdere verschillende bestanden kunnen bestaan. Als dat het geval is, onthoud dan dat pylupdate5, het programma dat we gebruiken om het .pro-bestand te lezen en de te vertalen tekenreeksen bij te werken, geen jokertekens toestaat, dus dient u elk bestand expliciet te vermelden in het .pro-bestand. Uw projectbestand zou er dan mogelijk als volgt uit kunnen zien:

FORMS = ../ui/about.ui ../ui/feedback.ui \
        ../ui/main_dialog.ui
SOURCES = ../your_plugin.py ../computation.py \
          ../utils.py

Verder is het bestand your_plugin.py het bestand dat alle menu’s en sub-menu’s van uw plug-in in de werkbalk van QGIS aanroept en u wilt het in zijn geheel vertalen.

Tenslotte kunt u met de variabele TRANSLATIONS de vertaalde talen specificeren die u wilt.

Waarschuwing

Zorg er voor het bestand ts net zo te noemen als your_plugin_ + language + .ts anders zal het laden van de taal mislukken! Gebruik de 2-letterige afkortingen voor de taal (it voor Italiaans, de voor Duits, etc…)

16.1.4.2.2. .ts-bestand 

Als u eenmaal de .pro hebt gemaakt bent u gereed om de/het .ts bestand(en) van de taal(talen) voor uw plug-in te maken.

Open een terminal, ga naar de map your_plugin/i18n en typ:

pylupdate5 your_plugin.pro

U zou het/de bestand(en) your_plugin_language.ts moeten zien.

Open het bestand .ts met Qt Linguist en begin met vertalen.

16.1.4.2.3. .qm-bestand 

Wanneer het vertalen van uw plug-in voltooid is (als enkele tekenreeksen niet voltooid zijn zal de taal van de bron worden gebruikt voor die tekenreeksen) dient u het bestand .qm te maken (het gecompileerde .ts-bestand dat zal worden gebruikt door QGIS).

Open een terminal, cd naar de map your_plugin/i18n en typ:

lrelease your_plugin.ts

Nu zou u in de map i18n het/de bestand(en) your_plugin_qm moeten zien.

16.1.4.3. Vertalen met behulp van Makefile 

Als u uw plug-in maakte met Plugin Builder kunt u als alternatief Makefile gebruiken om berichten uit te nemen uit code voor Python of dialoogvensters van Qt. Aan het begin van Makefile staat een variabele LOCALES:

LOCALES = en

Voeg de afkorting voor de taal toe aan deze variabele, bijvoorbeeld voor de Hongaarse taal:

LOCALES = en hu

Nu kunt u het bestand hu.ts (en het bestand en.ts ook) uit de bronnen maken of bijwerken met:

make transup

Hierna heeft u de bestanden .ts voor alle talen die zijn ingesteld in de variabele LOCALES bijgewerkt. Gebruik Qt Linguist om de berichten van het programma te vertalen. Als het vertalen voltooid is kunnen de bestanden .qm worden gemaakt met de transcompile:

make transcompile

U dient de bestanden .ts te distribueren met uw plug-in.

16.1.4.4. De plug-in laden 

Open, om de vertaling van uw plug-in te kunnen zien, QGIS, wijzig de taal (Extra ► Opties ► Algemeen) en start QGIS opnieuw.

U zou uw plug-in in de juiste taal moeten zien.

Waarschuwing

Indien u iets wijzigt in uw plug-in (nieuwe UI’s, nieuw menu, etc..) dient de bijgewerkte versie van de bestanden .ts en .qm opnieuw te generen, voer dus opnieuw de hierboven genoemde opdracht uit.

16.1.6. Tips en trucs 

16.1.6.1. Plugin Reloader 

Gedurende de ontwikkeling van uw plug-in zult u die regelmatig opnieuw in QGIS moeten laden om te testen. Dat is heel gemakkelijk met de plug-in Plugin Reloader. Die kunt u vinden met Plug-ins beheren en installeren.

16.1.6.2. Automatiseren van verpakken, uitgave en vertaling met qgis-plugin-ci 

qgis-plugin-ci verschaft een interface voor de opdrachtregel om automatisch verpakken en uitrollen voor plug-ins van QGIS op uw computer uit te voeren, of doorlopende integratie te gebruiken, zoals GitHub werkstromen of Gitlab-CI als ook Transifex voor vertaling.

Het maakt uitgeven, vertalen, publiceren of maken van een XML-bestand voor de opslagplaats van plug-ins via CLI of in acties voor CI mogelijk.

16.1.6.3. Toegang tot plug-ins 

Met Python kunt u toegang krijgen tot alle klassen van geïnstalleerde plug-ins vanuit QGIS, wat handig kan zijn voor debuggen.

my_plugin = qgis.utils.plugins['My Plugin']

16.1.6.4. Logboekmeldingen 

Plug-ins hebben hun eigen tab in het Paneel Logboekmeldingen.

16.1.6.5. Bronbestand 

Sommige plug-ins gebruiken resource-bestanden, bijvoorbeeld resources.qrc dat de bronnen voor de gebruikersinterface definieert, zoals pictogrammen:

<RCC>
  <qresource prefix="/plugins/testplug" >
     <file>icon.png</file>
  </qresource>
</RCC>

Het is goed om een voorvoegsel te gebruiken dat niet zal botsen met andere plug-ins of andere delen van QGIS, anders krijgt u misschien bronnen die u niet wilt. Nu dient u nog slechts een bestand in Python te maken dat de bronnen zal bevatten. dat wordt gedaan met de opdracht pyrcc5

pyrcc5 -o resources.py resources.qrc

Notitie

In omgevingen van Windows zal het proberen uit te voeren van de opdracht pyrcc5 vanuit de Opdracht prompt of Powershell resulteren in de fout “Windows cannot access the specified device, path, or file […]”. De eenvoudigste oplossing is waarschijnlijk om de OSGeo4W Shell te gebruiken maar als u er niet voor terugschrikt om de omgevingsvariabele PATH aan te passen of het pad naar het uitvoerbare bestand expliciet te specificeren zou u in staat moeten zijn het te vinden op <Your QGIS Install Directory>\bin\pyrcc5.exe.