Creare un plugin QCAD

Introduzione

I plugin QCAD possono essere usati per estendere QCAD con funzionalità implementate in C o C++.

Implementare RPluginInterface

Tutti i plugin QCAD devono derivare direttamente o indirettamente da QObject e dalla classe base astratta RPluginInterface.

File RExamplePlugin.h

Per il nostro primo plugin di esempio minimalista, aggiungiamo implementazioni vuote o minimaliste per la maggior parte dei metodi di RPluginInterface direttamente nel file di intestazione. Questa struttura iniziale del file di intestazione può essere copiata per ottenere un primo plugin funzionante che può essere caricato in 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; }
};

File RExamplePlugin.cpp

Per il metodo getPluginInfo, aggiungiamo una semplice implementazione al file cpp per poter vedere qualcosa nella finestra di dialogo «Informazioni» di 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

File exampleplugin.pro

Per compilare il nostro plugin, abbiamo anche bisogno di un file di progetto Qt che può essere trasformato in un Makefile con Qt qmake.

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

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

L’include alla riga 3 dovrebbe puntare al file shared.pri dell’installazione del codice sorgente di QCAD (ad esempio qcad/shared.pri). Come DESTDIR, potreste voler scegliere la cartella plugins di un’installazione QCAD funzionante, in modo che il plugin venga compilato nel posto giusto, da dove può anche essere caricato da QCAD.

Compilazione

Il vostro plugin può essere compilato con questi tre file, creando il file qcad/plugins/qcadexample.dll o libqcadexample.so o libqcadexample.dylib.

Nota: se eseguite un binario QCAD compilato in modalità debug, anche il plugin deve essere compilato in modalità debug. Se eseguite QCAD in modalità release, anche il plugin deve essere compilato in modalità release.

Per compilare il plugin in modalità debug, eseguite:

Linux / macOS:

qmake
make debug

Windows:

qmake
nmake debug

Per compilare in modalità release, eseguite invece make release o nmake release.

Ovviamente, il plugin non fa ancora nulla di utile, ma dovreste poter vedere il vostro plugin nella finestra di dialogo «Informazioni» di QCAD:

Se non vedete il vostro plugin, controllate la presenza di errori nel terminale all’avvio di QCAD. Potreste anche vedere un messaggio di errore nella finestra di dialogo «Informazioni».

Compilare script come risorse in un plugin

I plugin QCAD possono essere usati per compilare una raccolta di script e altre risorse (file UI, icone, ecc.) in un plugin. Questo ha il vantaggio che il codice di più file ECMAScript può essere raggruppato all’interno di un unico file binario compilato. I plugin tendono a caricarsi più velocemente dei singoli file su disco e occupano meno spazio su disco.

File scripts/MyTool/MyTool.js

Supponiamo che esista una cartella scripts/MyTool con un file MyTool.js che contiene uno strumento QCAD, implementato in ECMAScript. Lo strumento si aggiunge in cima al menu Varie e restituisce “Hello World” quando viene attivato.

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

File scripts.qrc

Per compilare questo strumento di script nel nostro plugin C++, dobbiamo creare un file di risorse Qt che indichi a qmake il file che vogliamo compilare nel plugin:

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

Il file qrc elenca i percorsi sotto i quali le risorse devono essere rese disponibili nel sistema di risorse di Qt (alias=“scripts/MyTool/MyTool.js”) e il percorso effettivo in cui il file può essere trovato su disco (usato solo per la compilazione). L’esempio precedente significa che c’è un file su disco sotto scripts/MyTool/MyTool.js che verrà compilato nel plugin. Non appena il plugin viene caricato, il file sarà disponibile sotto il percorso “:/scripts/MyTool/MyTool.js”. QCAD troverà lo strumento automaticamente sotto tale percorso, poiché analizza sia la cartella “scripts” sia “:/scripts” alla ricerca di script.

Dobbiamo inoltre aggiungere il file qrc al file di progetto (exampleplugin.pro) aggiungendo la seguente riga:

RESOURCES = scripts.qrc

Dopo aver modificato il file exampleplugin.pro, eseguite nuovamente qmake e make e caricate il plugin. Ora dovrebbe esserci una voce di menu “MyTool” in cima al menu Varie in QCAD.

Codice sorgente

Potete trovare il codice sorgente completo di questo plugin di esempio all’indirizzo:

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

Risoluzione dei problemi

• Se il vostro plugin viene compilato ma non può essere caricato da QCAD, assicuratevi che venga usata la stessa versione di Qt di QCAD (vedere Aiuto > Informazioni su QCAD). Assicuratevi che, se QCAD viene eseguito in modalità release, anche il vostro plugin sia compilato in modalità release.
• Avviate QCAD da un terminale o dalla riga di comando e controllate l’output della console alla ricerca di messaggi di errore. Emettete messaggi nel vostro plugin per confermare che viene caricato, ad esempio nella vostra funzione init.
• Controllate la finestra di dialogo «Informazioni» (Aiuto > Informazioni su QCAD > Plugins) alla ricerca di messaggi di errore.