Créer un plugin QCAD

Introduction

Les plugins QCAD peuvent être utilisés pour étendre QCAD avec des fonctionnalités implémentées en C ou C++.

Implémenter RPluginInterface

Tous les plugins QCAD doivent être dérivés directement ou indirectement de QObject et de la classe de base abstraite RPluginInterface.

Fichier RExamplePlugin.h

Pour notre premier plugin d’exemple minimaliste, nous ajoutons des implémentations vides ou minimalistes pour la plupart des méthodes de RPluginInterface directement dans le fichier d’en-tête. Cette structure initiale du fichier d’en-tête peut être copiée pour obtenir un premier plugin fonctionnel qui peut être chargé dans 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; }
};

Fichier RExamplePlugin.cpp

Pour la méthode getPluginInfo, nous ajoutons une implémentation simple au fichier cpp afin de voir quelque chose dans la boîte de dialogue « À propos » de 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

Fichier exampleplugin.pro

Pour compiler notre plugin, nous avons également besoin d’un fichier de projet Qt qui peut être transformé en Makefile avec 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 à la ligne 3 doit pointer vers le fichier shared.pri de l’installation du code source de QCAD (par exemple qcad/shared.pri). Comme DESTDIR, vous voudrez peut-être choisir le dossier plugins d’une installation QCAD fonctionnelle, afin que le plugin soit compilé au bon endroit, d’où il peut aussi être chargé par QCAD.

Compilation

Votre plugin peut être compilé avec ces trois fichiers, créant le fichier qcad/plugins/qcadexample.dll ou libqcadexample.so ou libqcadexample.dylib.

Remarque : si vous exécutez un binaire QCAD compilé en mode debug, le plugin doit également être compilé en mode debug. Si vous exécutez QCAD en mode release, le plugin doit lui aussi être compilé en mode release.

Pour compiler le plugin en mode debug, exécutez :

Linux / macOS :

qmake
make debug

Windows :

qmake
nmake debug

Pour compiler en mode release, exécutez make release ou nmake release à la place.

Bien entendu, le plugin ne fait encore rien d’utile, mais vous devriez pouvoir voir votre plugin dans la boîte de dialogue « À propos » de QCAD :

Si vous ne voyez pas votre plugin, vérifiez les erreurs dans le terminal au démarrage de QCAD. Vous pourriez aussi voir un message d’erreur dans la boîte de dialogue « À propos ».

Compiler des scripts comme ressources dans un plugin

Les plugins QCAD peuvent être utilisés pour compiler une collection de scripts et d’autres ressources (fichiers UI, icônes, etc.) dans un plugin. Cela présente l’avantage que le code de plusieurs fichiers ECMAScript peut être regroupé dans un seul fichier binaire compilé. Les plugins ont tendance à se charger plus vite que des fichiers individuels sur le disque et occupent moins d’espace disque.

Fichier scripts/MyTool/MyTool.js

Supposons qu’il existe un dossier scripts/MyTool avec un fichier MyTool.js contenant un outil QCAD, implémenté en ECMAScript. L’outil s’ajoute lui-même en haut du menu Divers et affiche « Hello World » lorsqu’il est déclenché.

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

Fichier scripts.qrc

Pour compiler cet outil de script dans notre plugin C++, nous devons créer un fichier de ressources Qt qui indique à qmake le fichier que nous voulons compiler dans le plugin :

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

Le fichier qrc liste les chemins sous lesquels les ressources doivent être rendues disponibles dans le système de ressources de Qt (alias=“scripts/MyTool/MyTool.js”) et le chemin réel où le fichier peut être trouvé sur le disque (utilisé uniquement pour la compilation). L’exemple ci-dessus signifie qu’il existe sur le disque un fichier sous scripts/MyTool/MyTool.js qui sera compilé dans le plugin. Dès que le plugin est chargé, le fichier sera disponible sous le chemin “:/scripts/MyTool/MyTool.js”. QCAD trouvera l’outil automatiquement sous ce chemin, car il analyse aussi bien le dossier “scripts” que “:/scripts” à la recherche de scripts.

Nous devons aussi ajouter le fichier qrc au fichier de projet (exampleplugin.pro) en ajoutant la ligne suivante :

RESOURCES = scripts.qrc

Après avoir modifié le fichier exampleplugin.pro, exécutez à nouveau qmake et make, puis chargez le plugin. Il devrait maintenant y avoir une entrée de menu “MyTool” en haut du menu Divers dans QCAD.

Code source

Vous pouvez trouver le code source complet de ce plugin d’exemple à l’adresse :

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

Dépannage

• Si votre plugin compile mais ne peut pas être chargé par QCAD, assurez-vous que la même version de Qt que pour QCAD est utilisée (voir Aide > À propos de QCAD). Assurez-vous que si QCAD est exécuté en mode release, votre plugin est lui aussi compilé en mode release.
• Lancez QCAD depuis un terminal ou la ligne de commande et vérifiez la sortie console à la recherche de messages d’erreur. Affichez des messages dans votre plugin pour confirmer qu’il est chargé, par exemple dans votre fonction init.
• Vérifiez la boîte de dialogue « À propos » (Aide > À propos de QCAD > Plugins) à la recherche de messages d’erreur.