Skapa ett QCAD-plugin

Introduktion

QCAD-plugins kan användas för att utöka QCAD med funktionalitet implementerad i C eller C++.

Implementera RPluginInterface

Alla QCAD-plugins måste vara direkt eller indirekt härledda från QObject och den abstrakta basklassen RPluginInterface.

Fil RExamplePlugin.h

För vårt första, minimalistiska exempel-plugin lägger vi till tomma eller minimalistiska implementeringar för de flesta metoderna i RPluginInterface direkt i header-filen. Denna inledande struktur av header-filen kan kopieras för att få ett första fungerande plugin som kan läsas in i QCAD.

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

Fil RExamplePlugin.cpp

För metoden getPluginInfo lägger vi till en enkel implementering i cpp-filen för att kunna se något i QCAD:s om-dialog.

#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

Fil exampleplugin.pro

För att kompilera vårt plugin behöver vi också en Qt-projektfil som kan omvandlas till en Makefile med Qt qmake.

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

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

Include på rad 3 bör peka på filen shared.pri i installationen av QCAD:s källkod (t.ex. qcad/shared.pri). Som DESTDIR kanske du vill välja plugins-mappen i en fungerande QCAD-installation, så att pluginet kompileras på rätt plats varifrån det också kan läsas in av QCAD.

Kompilering

Ditt plugin kan kompileras med dessa tre filer, vilket skapar filen qcad/plugins/qcadexample.dll eller libqcadexample.so eller libqcadexample.dylib.

Obs: om du kör en QCAD-binär kompilerad i felsökningsläge (debug) måste pluginet också kompileras i felsökningsläge. Om du kör QCAD i release-läge måste pluginet också kompileras i release-läge.

För att kompilera pluginet i felsökningsläge kör:

Linux / macOS:

qmake
make debug

Windows:

qmake
nmake debug

För att kompilera i release-läge kör make release eller nmake release i stället.

Pluginet kommer naturligtvis inte att göra något användbart ännu, men du bör kunna se ditt plugin i QCAD:s om-dialog:

Om du inte kan se ditt plugin, kontrollera efter fel i terminalen medan du startar QCAD. Du kan också se ett felmeddelande i om-dialogen.

Kompilera skript som resurser in i ett plugin

QCAD-plugins kan användas för att kompilera en samling skript och andra resurser (ui-filer, ikoner osv.) in i ett plugin. Detta har fördelen att koden från flera ECMAScript-filer kan buntas ihop inuti en enda, kompilerad binärfil. Plugins tenderar att läsas in snabbare än enskilda filer från disk och tar upp mindre diskutrymme.

Fil scripts/MyTool/MyTool.js

Låt oss anta att det finns en mapp scripts/MyTool med en fil MyTool.js som innehåller ett QCAD-verktyg, implementerat i ECMAScript. Verktyget lägger till sig själv högst upp i Diverse-menyn och skriver ut “Hello World” när det utlöses.

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

Fil scripts.qrc

För att kompilera detta skriptverktyg in i vårt C++-plugin måste vi skapa en Qt-resursfil som pekar qmake mot filen vi vill kompilera in i pluginet:

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

qrc-filen listar sökvägarna under vilka resurser ska göras tillgängliga i Qt:s resurssystem (alias=“scripts/MyTool/MyTool.js”) och den faktiska sökvägen där filen kan hittas på disk (används endast för kompilering). Exemplet ovan innebär att det finns en fil på disk under scripts/MyTool/MyTool.js som kommer att kompileras in i pluginet. Så snart pluginet är inläst kommer filen att vara tillgänglig under sökvägen “:/scripts/MyTool/MyTool.js”. QCAD hittar verktyget automatiskt under den sökvägen eftersom det skannar mappen “scripts” såväl som “:/scripts” efter skript.

Vi måste också lägga till qrc-filen i projektfilen (exampleplugin.pro) genom att lägga till följande rad:

RESOURCES = scripts.qrc

Efter att ha redigerat filen exampleplugin.pro, kör qmake och make igen och läs in pluginet. Det bör nu finnas en menypost “MyTool” högst upp i Diverse-menyn i QCAD.

Källkod

Du kan hitta den fullständiga källkoden för detta exempel-plugin på:

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

Felsökning

• Om ditt plugin kompileras men inte kan läsas in av QCAD, se till att samma Qt-version används som för QCAD (se Hjälp > Om QCAD). Se till att om QCAD körs i release-läge är ditt plugin också kompilerat i release-läge.
• Starta QCAD från en terminal eller kommandoraden och kontrollera konsolutdata efter felmeddelanden. Skriv ut meddelanden i ditt plugin för att bekräfta att det läses in. Till exempel i din init-funktion.
• Kontrollera om-dialogen (Hjälp > Om QCAD > Plugins) efter felmeddelanden.