Opprette en QCAD-plugin

Innledning

QCAD-plugins kan brukes til å utvide QCAD med funksjonalitet implementert i C eller C++.

Implementere RPluginInterface

Alle QCAD-plugins må være direkte eller indirekte avledet fra QObject og den abstrakte basisklassen RPluginInterface.

Fil RExamplePlugin.h

For vår første, minimalistiske eksempel-plugin legger vi til tomme eller minimalistiske implementeringer for de fleste metodene i RPluginInterface direkte i header-filen. Denne innledende strukturen i header-filen kan kopieres for å få en første fungerende plugin som kan lastes inn 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

For metoden getPluginInfo legger vi til en enkel implementering i cpp-filen for å kunne se noe i QCADs 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

For å kompilere pluginen vår trenger vi også en Qt-prosjektfil som kan gjøres om til 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å linje 3 bør peke til filen shared.pri i installasjonen av QCAD-kildekoden (f.eks. qcad/shared.pri). Som DESTDIR vil du kanskje velge plugins-mappen til en fungerende QCAD-installasjon, slik at pluginen kompileres på riktig sted, hvorfra den også kan lastes inn av QCAD.

Kompilering

Pluginen din kan kompileres med disse tre filene, noe som oppretter filen qcad/plugins/qcadexample.dll eller libqcadexample.so eller libqcadexample.dylib.

Merk: hvis du kjører en QCAD-binærfil kompilert i feilsøkingsmodus (debug), må pluginen også kompileres i feilsøkingsmodus. Hvis du kjører QCAD i release-modus, må pluginen også kompileres i release-modus.

For å kompilere pluginen i feilsøkingsmodus kjør:

Linux / macOS:

qmake
make debug

Windows:

qmake
nmake debug

For å kompilere i release-modus, kjør make release eller nmake release i stedet.

Pluginen vil selvfølgelig ikke gjøre noe nyttig ennå, men du bør kunne se pluginen din i QCADs om-dialog:

Hvis du ikke kan se pluginen din, sjekk for feil i terminalen mens du starter QCAD. Du kan også se en feilmelding i om-dialogen.

Kompilere skript som ressurser inn i en plugin

QCAD-plugins kan brukes til å kompilere en samling skript og andre ressurser (ui-filer, ikoner osv.) inn i en plugin. Dette har den fordelen at koden fra flere ECMAScript-filer kan samles inne i én enkelt, kompilert binærfil. Plugins har en tendens til å laste raskere enn individuelle filer fra disk og tar opp mindre diskplass.

Fil scripts/MyTool/MyTool.js

La oss anta at det finnes en mappe scripts/MyTool med en fil MyTool.js som inneholder et QCAD-verktøy, implementert i ECMAScript. Verktøyet legger seg selv til øverst i Diverse-menyen og 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

For å kompilere dette skriptverktøyet inn i C++-pluginen vår må vi opprette en Qt-ressursfil som peker qmake mot filen vi vil kompilere inn i pluginen:

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

qrc-filen lister opp stiene som ressurser skal gjøres tilgjengelige under i Qts ressurssystem (alias=“scripts/MyTool/MyTool.js”), og den faktiske stien der filen kan finnes på disk (brukes kun til kompilering). Eksempelet ovenfor betyr at det finnes en fil på disk under scripts/MyTool/MyTool.js som vil bli kompilert inn i pluginen. Så snart pluginen er lastet, vil filen være tilgjengelig under stien “:/scripts/MyTool/MyTool.js”. QCAD vil finne verktøyet automatisk under den stien siden det skanner mappen “scripts” så vel som “:/scripts” for skript.

Vi må også legge til qrc-filen i prosjektfilen (exampleplugin.pro) ved å legge til følgende linje:

RESOURCES = scripts.qrc

Etter å ha redigert filen exampleplugin.pro, kjør qmake og make igjen og last inn pluginen. Det bør nå være en menyoppføring “MyTool” øverst i Diverse-menyen i QCAD.

Kildekode

Du kan finne den komplette kildekoden for denne eksempel-pluginen på:

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

Feilsøking

• Hvis pluginen din kompileres, men ikke kan lastes inn av QCAD, sørg for at samme Qt-versjon brukes som for QCAD (se Hjelp > Om QCAD). Sørg for at hvis QCAD kjøres i release-modus, er pluginen din også kompilert i release-modus.
• Start QCAD fra en terminal eller kommandolinjen og sjekk konsollutdataene for feilmeldinger. Skriv ut meldinger i pluginen din for å bekrefte at den lastes inn. For eksempel i init-funksjonen din.
• Sjekk om-dialogen (Hjelp > Om QCAD > Plugins) for feilmeldinger.