Een QCAD-plugin maken

Inleiding

QCAD-plugins kunnen worden gebruikt om QCAD uit te breiden met functionaliteit die in C of C++ is geïmplementeerd.

RPluginInterface implementeren

Alle QCAD-plugins moeten direct of indirect zijn afgeleid van QObject en de abstracte basisklasse RPluginInterface.

Bestand RExamplePlugin.h

Voor onze eerste, minimalistische voorbeeldplugin voegen we voor de meeste methoden van RPluginInterface lege of minimalistische implementaties rechtstreeks toe aan het headerbestand. Deze aanvankelijke structuur van het headerbestand kan worden gekopieerd om een eerste werkende plugin te verkrijgen die in QCAD kan worden geladen.

#include <QObject>
#include <QScriptEngine>

#include "RPluginInterface.h"

class RExamplePlugin : public QObject, public RPluginInterface
{
    Q_OBJECT
    Q_INTERFACES(RPluginInterface)
#if QT_VERSION >= 0x050000
    Q_PLUGIN_METADATA(IID "org.qcad.exampleplugin")
#endif

public:
    virtual bool init() { return true; }
    virtual void uninit(bool) {}
    virtual void postInit(InitStatus status) {}
    virtual void initScriptExtensions(QScriptEngine& engine) {}
    virtual RPluginInfo getPluginInfo();
    virtual bool checkLicense() { return true; }
};

Bestand RExamplePlugin.cpp

Voor de methode getPluginInfo voegen we een eenvoudige implementatie toe aan het cpp-bestand, zodat we iets kunnen zien in het dialoogvenster “Over” van QCAD.

#include "RExamplePlugin.h"

RPluginInfo RExamplePlugin::getPluginInfo() {
    RPluginInfo ret;
    ret.set("Version", "1.0");
    ret.set("ID", "EXAMPLE");
    ret.set("Name", "Example Plugin");
    ret.set("License", "GPLv3");
    ret.set("URL", "http://qcad.org");
    return ret;
}

#if QT_VERSION < 0x050000
QT_BEGIN_NAMESPACE
Q_EXPORT_PLUGIN2(example, RExamplePlugin)
QT_END_NAMESPACE
#endif

Bestand exampleplugin.pro

Om onze plugin te compileren, hebben we ook een Qt-projectbestand nodig dat met Qt qmake in een Makefile kan worden omgezet.

CONFIG += plugin
TARGET = example
include(../../../shared.pri)

TEMPLATE = lib
HEADERS = RExamplePlugin.h
SOURCES = RExamplePlugin.cpp
DESTDIR = ../../../plugins
LIBS += -lqcadcore -lqcadgui -lqcadecmaapi

De include op regel 3 moet verwijzen naar het bestand shared.pri van de installatie van de QCAD-broncode (bijvoorbeeld qcad/shared.pri). Als DESTDIR kunt u de map plugins van een werkende QCAD-installatie kiezen, zodat de plugin op de juiste plek wordt gecompileerd, van waaruit hij ook door QCAD kan worden geladen.

Compilatie

Uw plugin kan met deze drie bestanden worden gecompileerd, waarbij het bestand qcad/plugins/qcadexample.dll of libqcadexample.so of libqcadexample.dylib wordt aangemaakt.

Let op: als u een in debug-modus gecompileerd QCAD-binair bestand uitvoert, moet de plugin ook in debug-modus worden gecompileerd. Als u QCAD in release-modus uitvoert, moet de plugin eveneens in release-modus worden gecompileerd.

Om de plugin in debug-modus te compileren, voert u uit:

Linux / macOS:

qmake
make debug

Windows:

qmake
nmake debug

Om in release-modus te compileren, voert u in plaats daarvan make release of nmake release uit.

Uiteraard doet de plugin nog niets nuttigs, maar u zou uw plugin in het dialoogvenster “Over” van QCAD moeten kunnen zien:

Als u uw plugin niet ziet, controleer dan het terminal op fouten tijdens het starten van QCAD. Mogelijk ziet u ook een foutmelding in het dialoogvenster “Over”.

Scripts als resources in een plugin compileren

QCAD-plugins kunnen worden gebruikt om een verzameling scripts en andere resources (UI-bestanden, pictogrammen, enz.) tot een plugin te compileren. Dit heeft als voordeel dat de code van meerdere ECMAScript-bestanden kan worden gebundeld in één enkel, gecompileerd binair bestand. Plugins laden doorgaans sneller dan afzonderlijke bestanden van schijf en nemen minder schijfruimte in beslag.

Bestand scripts/MyTool/MyTool.js

Laten we aannemen dat er een map scripts/MyTool is met een bestand MyTool.js dat een QCAD-gereedschap bevat, geïmplementeerd in ECMAScript. Het gereedschap voegt zichzelf bovenaan het menu Diverse toe en geeft “Hello World” uit wanneer het wordt geactiveerd.

include("scripts/EAction.js");

function MyTool(guiAction) {
    EAction.call(this, guiAction);
}

MyTool.prototype = new EAction();

MyTool.prototype.beginEvent = function() {
    EAction.prototype.beginEvent.call(this);

    EAction.handleUserMessage("Hello World");

    this.terminate();
};

MyTool.init = function(basePath) {
    var action = new RGuiAction("&MyTool", RMainWindowQt.getMainWindow());
    action.setRequiresDocument(true);
    action.setScriptFile(basePath + "/MyTool.js");
    action.setGroupSortOrder(0);
    action.setSortOrder(0);
    action.setWidgetNames(["MiscMenu"]);
};

Bestand scripts.qrc

Om dit scriptgereedschap in onze C++-plugin te compileren, moeten we een Qt-resourcebestand maken dat qmake naar het bestand verwijst dat we in de plugin willen compileren:

<!DOCTYPE RCC>
<RCC version="1.0">
    <qresource>
        <file alias="scripts/MyTool/MyTool.js">scripts/MyTool/MyTool.js</file>
    </qresource>
</RCC>

Het qrc-bestand vermeldt de paden waaronder de resources beschikbaar moeten worden gemaakt in het resourcesysteem van Qt (alias=“scripts/MyTool/MyTool.js”) en het werkelijke pad waar het bestand op schijf te vinden is (alleen gebruikt voor de compilatie). Het bovenstaande voorbeeld betekent dat er op schijf een bestand is onder scripts/MyTool/MyTool.js dat in de plugin zal worden gecompileerd. Zodra de plugin is geladen, is het bestand beschikbaar onder het pad “:/scripts/MyTool/MyTool.js”. QCAD vindt het gereedschap automatisch onder dat pad, aangezien het zowel de map “scripts” als “:/scripts” op scripts doorzoekt.

We moeten het qrc-bestand ook aan het projectbestand (exampleplugin.pro) toevoegen door de volgende regel toe te voegen:

RESOURCES = scripts.qrc

Voer na het bewerken van het bestand exampleplugin.pro opnieuw qmake en make uit en laad de plugin. Er zou nu bovenaan het menu Diverse in QCAD een menu-item “MyTool” moeten staan.

Broncode

U vindt de volledige broncode voor deze voorbeeldplugin op:

https://github.com/qcad/qcad/tree/master/support/examples/exampleplugin

Problemen oplossen

• Als uw plugin compileert maar niet door QCAD kan worden geladen, zorg er dan voor dat dezelfde Qt-versie wordt gebruikt als voor QCAD (zie Hulp > Over QCAD). Zorg ervoor dat, als QCAD in release-modus wordt uitgevoerd, uw plugin eveneens in release-modus is gecompileerd.
• Start QCAD vanuit een terminal of de opdrachtregel en controleer de console-uitvoer op foutmeldingen. Geef meldingen uit in uw plugin om te bevestigen dat hij wordt geladen, bijvoorbeeld in uw init-functie.
• Controleer het dialoogvenster “Over” (Hulp > Over QCAD > Plugins) op foutmeldingen.