Écriture de Plugins Pour XINX

Préface

Ce document décrit l'écriture de Plugins pour XINX. Vous pouvez trouver plus d'informations dans la documentation de XINX livrée avec celui-ci.

Les plugins peuvent être utilisés pour étendre XINX de plusieurs manières :

• Ajout d'un gestionnaire de version.
• Ajout d'une coloration syntaxique pour un type de fichier.
• Ajout de la complétion pour un type de fichier.

Seul le premier point sera traité dans ce document, car considéré comme stable. L'interface utilisée pour la complétion a beaucoup de chance d'évoluer énormément par la suite.

La liste des plugins peut être trouvée dans la boite de dialogue de configuration de XINX du menu Outils.

Les bases

Un plugin doit implémenter au minimum une interface : IXinxPlugin. Cette interface est utilisée pour obtenir différentes informations sur le plugin, comme son nom, sa description, son auteur, sa licence, ...

Si un plugin implémente uniquement cette interface, il sera reconnu par XINX mais ne fera rien.

Pour implémenter le plugin, vous devez écrire le code suivant :

/* fooplugin.h */

class FooPlugin : public QObject, public IXinxPlugin {
        Q_OBJECT
        Q_INTERFACES(IXinxPlugin)
public:
        FooPlugin();
        virtual ~FooPlugin();
        
        virtual bool initializePlugin( const QString & lang );
        virtual QVariant getPluginAttribute( const enum IXinxPlugin::PluginAttribute & attr );
};

/* fooplugin.cpp */

FooPlugin::FooPlugin() {
        // Make some initialization
}

FooPlugin::~FooPlugin() {
        // Make some cleanup
}

bool FooPlugin::initializePlugin( const QString & lang ) {
        // Make some initialization about the localization
        return true;
}

QVariant FooPlugin::getPluginAttribute( const enum IXinxPlugin::PluginAttribute & attr ) {
        switch( attr ) {
        case PLG_NAME:
                return tr("A foo plugins");
        case PLG_DESCRIPTION:
                return tr("Just a foo plugins that do nothing.");
        case PLG_AUTHOR:
                return "Ulrich Van Den Hekke";
        case PLG_VERSION:
                return "0.1";
        case PLG_LICENCE:
                return "GPL v2.0 or later";
        }
        return QVariant();
}
Q_EXPORT_PLUGIN2(fooplugin, FooPlugin)

Le plugin doit hériter de la classe QObject (voir la documentation de Qt), et doit appeler la macro Q_OBJECT. Il peut également hériter de IXinxPlugin indirectement (par une classe telle que IRCSPlugin), mais doit définir l'implémentation à l'aide de la macro Q_INTERFACE.

Le plugin doit également appeler sa macro Q_EXPORT_PLUGIN2 dans sa partie implémentation afin de créer une variable statique utilisée pour appeler le plugin dans l'application.

Un plugin peut proposer une boite de dialogue pour sa configuration. Pour cela il doit implémenter l'interface IXinxPluginConfiguration.

Le plugin de gestion de version

Partie gestionnaire de version

Le gestionnaire de version est géré au travers de l'objet RCS dont vous pouvez trouver le source ici : source:/trunk/libxinx/rcs.h. Pour écrire un gestionnaire de version personnalisé, il faut dériver de cette classe et ré-implémenter les méthodes abstraites.

/* rcs_foo.h */

class RCS_Foo : public RCS {
        Q_OBJECT
public:
        RCS_Foo( const QString & basePath ) : RCS( basePath ) {};
        virtual ~RCS_Foo() {};

La première étape est de définir le constructeur et le destructeur. RCS est dérivé de QObject, il ne faut donc pas oublier la macro Q_OBJECT générant les informations sur la meta-class, ce qui permettra de gérer les signaux.

        virtual struct_rcs_infos infos( const QString & path ); 
        virtual FilesOperation operations( const QStringList & paths );
        virtual void update( const QStringList & path );
        virtual void commit( const FilesOperation & path, const QString & message );
        virtual void add( const QStringList & path );
        virtual void remove( const QStringList & path );
        virtual void updateToRevision( const QString & path, const QString & revision, QString * content = 0 );
public slots:
        virtual void abort();
};

Vient ensuite la ré-implémentation des différentes méthodes. Il faut bien faire attention au fait que les méthodes update, commit, add, remove, updateToRevision doivent rendre la main le plus rapidement possible afin de ne pas bloquer l'application. Pour cela il est possible de lancer ces méthodes aux travers de Thread (en utilisant un objet dérivé de XinxThread?) ou au travers de processus.

Vous pouvez vous inspirer de l'encapsulation de SubVersion? pour faire votre propre plugin.

Partie plugin

Le plugin de gestion de version doit implémenter l'interface IRCSPugin. Le plugin peut à l'aide de cette interface, implémenter un ou plusieurs gestionnaires de version.

/* fooplugin.h */

class FooPlugin : public QObject, public IRCSPlugin {
        Q_OBJECT
        Q_INTERFACES(IXinxPlugin)
        Q_INTERFACES(IRCSPlugin)
public:
        FooPlugin();
        virtual ~FooPlugin();
        
        virtual bool initializePlugin( const QString & lang );
        virtual QVariant getPluginAttribute( const enum IXinxPlugin::PluginAttribute & attr );

        virtual QStringList rcs();
        virtual QString descriptionOfRCS( const QString & rcs );
        virtual RCS * createRCS( const QString & rcs, const QString & basePath );
};

/* fooplugin.cpp */

QStringList FooPlugin::rcs() {
        return QStringList() << "foo";
}
 
QString FooPlugin::descriptionOfRCS( const QString & rcs ) {
        if( rcs.toLower() == "foo" )
                return tr( "Foo - Foo Version System" );
        return QString();
}

RCS * FooPlugin::createRCS( const QString & rcs, const QString & basePath ) {
        if( rcs.toLower() == "foo" ) {
                return new RCS_Foo( basePath );
        }
        return NULL;
}

Dans la méthode rcs() le plugin définit la liste des gestionnaires de version qu'il veut gérer. Le nom est arbitraire mais doit être explicite pour ne pas donner lieu à confusion lors de l'écriture d'un autre plugin. Le plugin définit également une description à l'aide de la méthode descriptionOfRCS() pour chaque gestionnaire de version qu'il implémente.

La description sera ensuite affichée dans la boite de dialogue de propriété du projet et permettra à l'utilisateur de choisir quel gestionnaire de version utilisé.

Dans la troisième méthode le plugin créé un objet RCS. C'est cet objet qui sera utilisé par l'application pour communiquer avec le gestionnaire de version.