Ein QCAD-Plugin erstellen

Einführung

QCAD-Plugins können verwendet werden, um QCAD um Funktionalität zu erweitern, die in C oder C++ implementiert ist.

RPluginInterface implementieren

Alle QCAD-Plugins müssen direkt oder indirekt von QObject und der abstrakten Basisklasse RPluginInterface abgeleitet werden.

Datei RExamplePlugin.h

Für unser erstes, minimalistisches Beispiel-Plugin fügen wir für die meisten Methoden von RPluginInterface leere oder minimalistische Implementierungen direkt in die Header-Datei ein. Diese anfängliche Struktur der Header-Datei kann kopiert werden, um ein erstes funktionierendes Plugin zu erhalten, das in QCAD geladen werden kann.

#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; }
};

Datei RExamplePlugin.cpp

Für die Methode getPluginInfo fügen wir der cpp-Datei eine einfache Implementierung hinzu, damit im Über-Dialog von QCAD etwas zu sehen ist.

#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

Datei exampleplugin.pro

Um unser Plugin zu kompilieren, benötigen wir außerdem eine Qt-Projektdatei, die sich mit Qt qmake in ein Makefile umwandeln lässt.

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

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

Der include in Zeile 3 sollte auf die Datei shared.pri der QCAD-Quellcodeinstallation verweisen (z. B. qcad/shared.pri). Als DESTDIR sollten Sie den Ordner plugins einer funktionierenden QCAD-Installation wählen, damit das Plugin an der richtigen Stelle kompiliert wird, von wo aus es auch von QCAD geladen werden kann.

Kompilierung

Ihr Plugin kann mit diesen drei Dateien kompiliert werden, wobei die Datei qcad/plugins/qcadexample.dll bzw. libqcadexample.so bzw. libqcadexample.dylib erzeugt wird.

Hinweis: Wenn Sie eine im Debug-Modus kompilierte QCAD-Binärdatei ausführen, muss das Plugin ebenfalls im Debug-Modus kompiliert werden. Wenn Sie QCAD im Release-Modus ausführen, muss auch das Plugin im Release-Modus kompiliert werden.

Um das Plugin im Debug-Modus zu kompilieren, führen Sie aus:

Linux / macOS:

qmake
make debug

Windows:

qmake
nmake debug

Um im Release-Modus zu kompilieren, führen Sie stattdessen make release oder nmake release aus.

Natürlich tut das Plugin noch nichts Nützliches, aber Sie sollten Ihr Plugin im Über-Dialog von QCAD sehen können:

Wenn Sie Ihr Plugin nicht sehen, prüfen Sie das Terminal beim Start von QCAD auf Fehler. Möglicherweise sehen Sie auch eine Fehlermeldung im Über-Dialog.

Skripte als Ressourcen in ein Plugin kompilieren

QCAD-Plugins können verwendet werden, um eine Sammlung von Skripten und anderen Ressourcen (UI-Dateien, Icons usw.) in ein Plugin zu kompilieren. Dies hat den Vorteil, dass der Code mehrerer ECMAScript-Dateien in einer einzigen, kompilierten Binärdatei gebündelt werden kann. Plugins laden tendenziell schneller als einzelne Dateien von der Festplatte und benötigen weniger Speicherplatz.

Datei scripts/MyTool/MyTool.js

Nehmen wir an, es gibt einen Ordner scripts/MyTool mit einer Datei MyTool.js, die ein in ECMAScript implementiertes QCAD-Werkzeug enthält. Das Werkzeug fügt sich selbst am oberen Ende des Menüs Diverses hinzu und gibt beim Auslösen “Hello World” aus.

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"]);
};

Datei scripts.qrc

Um dieses Skriptwerkzeug in unser C++-Plugin zu kompilieren, müssen wir eine Qt-Ressourcendatei erstellen, die qmake auf die Datei verweist, die wir in das Plugin kompilieren möchten:

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

Die qrc-Datei listet die Pfade auf, unter denen die Ressourcen im Ressourcensystem von Qt verfügbar gemacht werden sollen (alias=“scripts/MyTool/MyTool.js”), sowie den tatsächlichen Pfad, unter dem die Datei auf der Festplatte zu finden ist (nur für die Kompilierung verwendet). Das obige Beispiel bedeutet, dass es auf der Festplatte eine Datei unter scripts/MyTool/MyTool.js gibt, die in das Plugin kompiliert wird. Sobald das Plugin geladen ist, ist die Datei unter dem Pfad “:/scripts/MyTool/MyTool.js” verfügbar. QCAD findet das Werkzeug automatisch unter diesem Pfad, da es sowohl den Ordner “scripts” als auch “:/scripts” nach Skripten durchsucht.

Wir müssen die qrc-Datei außerdem der Projektdatei (exampleplugin.pro) hinzufügen, indem wir die folgende Zeile einfügen:

RESOURCES = scripts.qrc

Führen Sie nach dem Bearbeiten der Datei exampleplugin.pro qmake und make erneut aus und laden Sie das Plugin. Am oberen Ende des Menüs Diverses in QCAD sollte nun ein Menüeintrag “MyTool” vorhanden sein.

Quellcode

Den vollständigen Quellcode für dieses Beispiel-Plugin finden Sie unter:

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

Fehlerbehebung

• Wenn Ihr Plugin kompiliert, aber nicht von QCAD geladen werden kann, stellen Sie sicher, dass dieselbe Qt-Version wie für QCAD verwendet wird (siehe Hilfe > Über QCAD). Stellen Sie sicher, dass Ihr Plugin ebenfalls im Release-Modus kompiliert ist, wenn QCAD im Release-Modus ausgeführt wird.
• Starten Sie QCAD von einem Terminal oder der Kommandozeile aus und prüfen Sie die Konsolenausgabe auf Fehlermeldungen. Geben Sie in Ihrem Plugin Meldungen aus, um zu bestätigen, dass es geladen wird, zum Beispiel in Ihrer init-Funktion.
• Prüfen Sie den Über-Dialog (Hilfe > Über QCAD > Plugins) auf Fehlermeldungen.