Revision as of 22:57, 14 April 2015

Plugin system

Calligra in some 2.x version stopped to use kdelibs' KSyCoCa (System Configuration Cache) and the class KServiceTypeTrader to find any installed shapes, parts, filters or other plugins. Instead it uses its own system, based on the .desktop files of all plugins, with the plugin metadata, being installed in the subfolder /calligra of the install dir for the service metadata. And uses the class KoServiceLocator from libs/koplugin to query from those metadata for the matching shapes, parts, filters or other plugin types.

With Qt5 there is now the option to store the metadata about plugins directly into the binary module file itself (using a special section) and to also read the metadata from there, without actually loading the plugin. So for Calligra it was decided to move like proposed from the desktop files to the embedded metadata. The metadata is stored in JSON format.

Adapting plugins

Creating the metadata in JSON format from the desktop file:

Instead of installing the desktop file, use the given macro to create a JSON file in the build dir from the desktop file. The generated JSON file will have the same basename as the .desktop file, e.g. foo.json with foo.desktop

Original Code	Ported Code
add_library(foo MODULE ${foo_SRCS}) install(FILES foo.desktop DESTINATION ${SERVICES_INSTALL_DIR}/calligra)	add_library(foo MODULE ${foo_SRCS}) kcoreaddons_desktop_to_json(foo foo.desktop)

Including the generated JSON file into the plugin via a C++ macro:

Original Code	Ported Code
K_PLUGIN_FACTORY(FooFactory, registerPlugin<Foo>();) K_EXPORT_PLUGIN(FooFactory("foo"))	K_PLUGIN_FACTORY_WITH_JSON(FooFactory, "foo.json", registerPlugin<Foo>();)

Adapting searches

When searching for plugins with embedded JSON metadata one uses KoJsonTrader from libs/koplugin.

Searching parts for a mimetype:

Original Code

Ported Code

#include <KoServiceLocator.h>
// ...
    const KService::List offers = KoServiceLocator::instance()->entries("Calligra/Part", mimetype);

    foreach(KService::Ptr offer, offers) {

#include <KoJsonTrader.h>
#include <QPluginLoader>
// ...
    const QList<QPluginLoader *> offers = KoJsonTrader::self()->query("Calligra/Part", mimetype);

    foreach(QPluginLoader *pluginLoader, offers) {

Searching plugins of a type, with custom filtering of the results:

Original Code

Ported Code

#include <KoServiceLocator.h>
// ...
    const KService::List offers = KoServiceLocator::instance()->entries(serviceType);

    foreach(KService::Ptr offer, offers) {
            const QString pluginName = service->property(QLatin1String("X-KDE-PluginInfo-Name"), QVariant::String).toString();

#include <KoJsonTrader.h>
#include <QPluginLoader>
// ...
    const QList<QPluginLoader *> offers = KoJsonTrader::self()->query(serviceType, QString());

    foreach(QPluginLoader *loader, offers) {
        QJsonObject json = loader->metaData().value("MetaData").toObject();
        json = json.value("KPlugin").toObject();
        const QString pluginName = json.value("Id").toString();

More info and other plugin systems:

KService - initial blog http://vizzzion.org/blog/2013/08/kde-frameworks-5-plugin-factory-guts (note: a bit outdated info [1])
A sample with deps: DTK
Advanced: KDCF
Advanced: commontk

Resource system

Translations

Debug logging

@@ Line 103: / Line 103: @@
 </source>
 |}
+More info and other plugin systems:
+* [http://api.kde.org/frameworks-api/frameworks5-apidocs/kservice/html/index.html KService] - initial blog http://vizzzion.org/blog/2013/08/kde-frameworks-5-plugin-factory-guts (note: a bit outdated info [https://git.reviewboard.kde.org/r/121959/])
+* A sample with deps: [http://dtk.inria.fr/blog/?p=502 DTK]
+* Advanced: [http://www.kdab.com/kdab-products/kdcf-overview/ KDCF]
+* Advanced: [http://www.commontk.org/index.php/Documentation/Plugin_Framework commontk]
 = Resource system =
 = Translations =
 = Debug logging =