Developer – Calligra

Docs: Generic Calligra plugin creation

Mon, 01 Jan 0001 00:00:00 +0000

Writing a plugin for Calligra technically means that you create the following things:

A plugin class, as an entry point to everything below. This is really a plugin-loader object, and it is created only so that it can register the plugin's factories with the relevant Calligra registries.
An implementation of one of the base classes (interfaces) from the Calligra libraries, for the functionality that is unique to your plugin. Examples of these interfaces are KoShape, KoToolBase and KoColorSpace.
A factory class. The factory design pattern allows the plugin to create as many instances of the plugin's object as required by the user. For example, when a new view is opened, Calligra asks shape plugins to create a new tool for that view. Each Calligra plugin type has its own factory base class that your factory should inherit from.
A plugin library that contains all classes that make up the plugin.
A JSON metadata file installed alongside the plugin, with information about the plugin such as its name and the service types it provides.

This tutorial assumes that you have a basic understanding of C++ and Qt/KDE Frameworks concepts, and that you have the development packages for Qt and KDE Frameworks 6 installed, as well as extra-cmake-modules.

The concept of a plugin

The concept is based on what object-oriented design calls a programming interface: you can define an interface and encapsulate it in a class without saying much about how it is implemented. You can then supply several classes that actually contain the implementation of that interface, each in their own way. Plugins are a way to provide a different implementation for a known interface, without the application that uses the interface needing to know about it at compile time.

Calligra has defined several classes as base classes and has made the interfaces of those base classes generic enough that a wide range of functionality can be accomplished by shipping a plugin with a new implementation of such a base class.

For example, one plugin type that Calligra supports is a docker widget: a widget shown on screen, like a QDockWidget in any other Qt application. A plugin can ship a new implementation of QDockWidget, providing whatever text, buttons and functionality it needs using the full API of Qt and the Calligra libraries. This means you could write a plugin that ships a docker that shows the time of day. Once the plugin is installed, Calligra applications find it and the docker is created and shown on screen.

One unique property of a plugin is that it is self-contained: the end result is one library that exports just the 'plugin object'. This means that code and classes changed in one plugin cannot affect code in another plugin, or in the Calligra applications themselves. This keeps development more separated, so changes in one place do not cause problems in another. You are therefore free to use whatever number of classes fit your design and programming style, and to avoid namespaces or class name prefixes if you wish — your plugin is walled off, so nobody is bothered by what you do or how you do it.

Components

The first component is the class that implements the interface this plugin represents. Each plugin type goes into detail on this elsewhere, as each interface has different features and requirements — see Flake shape creation for the KoShape case.

The factory component is also unique per plugin type, but generic in setup and idea. The reason a factory exists is that it makes it possible to create any number of instances of the plugin's object, whenever the host application (probably at the request of the user) wants to do so. The general workflow is:

A plugin is loaded and a factory is created (see the plugin component below).
The factory is registered in a registry (KoShapeRegistry, KoToolRegistry, KoDockRegistry, ...).
Applications query the registry for all available plugins, and use, for example, the name and icon from the factory to show buttons on screen.
The user clicks a button, or otherwise selects the plugin.
The plugin factory is asked to create a new instance of the thing it is meant to create.
That new shape, tool, widget or other object is used in the document or the GUI, depending on the plugin type.

This means that a factory is your plugin's main advertisement to the outside world, since it is used to show the user what your plugin can do. Each plugin type has its own factory base class, with at minimum a create()-like method that returns a new instance. These factory base classes typically expose a number of properties you can set to describe your plugin, such as a name or an icon — it is worth filling in as many of these as are relevant.

The next component is the plugin component: a QObject-derived class with a specific constructor signature that is instantiated once, immediately used to register its factories, and then deleted again. The trick is therefore to do all the work of creating and registering factories in the constructor. The code for this class is simple, and you copy-paste it with only a few modifications.

In the header file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


#pragma once

#include <QObject>
#include <QVariantList>

class MyPlugin : public QObject
{
 Q_OBJECT
public:
 MyPlugin(QObject *parent, const QVariantList &);
};

In the cpp file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


#include "MyPlugin.h"

#include <KPluginFactory>

#include <KoShapeRegistry.h>
#include <KoToolRegistry.h>

#include "MyShapeFactory.h"
#include "MyToolFactory.h"

K_PLUGIN_FACTORY_WITH_JSON(MyPluginFactory, "myplugin.json", registerPlugin<MyPlugin>();)

MyPlugin::MyPlugin(QObject *parent, const QVariantList &)
 : QObject(parent)
{
 KoShapeRegistry::instance()->add(new MyShapeFactory());
 KoToolRegistry::instance()->add(new MyToolFactory());
}

#include "MyPlugin.moc"

This example registers two factories, but you can register any number in a single plugin. Note how only the factories are created here, and nothing else is done — this keeps loading of the plugin as fast as possible.

If you copy-paste this code, update MyPlugin, MyPluginFactory and the included headers to match your own class names, and change "myplugin.json" to the name of your own metadata file. The K_PLUGIN_FACTORY_WITH_JSON macro, from <KPluginFactory>, is what turns your plugin class into a loadable KDE plugin; it also takes care of exposing the JSON metadata to the plugin loader.

The library is what contains all the compiled classes of your plugin. A plugin is technically implemented as a shared library, loaded by Calligra the first time something asks its registry for plugins of the relevant type — not necessarily at application start. It is possible for your plugin to depend on other shared libraries, apart from the Calligra and KDE Frameworks ones, but you are then responsible for making sure they are installed alongside your plugin.

In CMake, building and installing the plugin library looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


cmake_minimum_required(VERSION 3.16)
project(myplugin)

set(CMAKE_AUTOMOC ON)

find_package(ECM REQUIRED NO_MODULE)
list(APPEND CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)

find_package(CalligraQt6 REQUIRED COMPONENTS flake)

add_definitions(-DTRANSLATION_DOMAIN=\"myplugin\")

set(myplugin_SRCS
 MyPlugin.cpp
 MyShapeFactory.cpp
 MyShape.cpp
 MyToolFactory.cpp
 MyTool.cpp
)

add_library(myplugin MODULE ${myplugin_SRCS})

target_link_libraries(myplugin CalligraQt6::flake)

install(TARGETS myplugin DESTINATION ${KDE_INSTALL_PLUGINDIR}/calligra/shapes)

A few things worth noting:

The plugin is built as a MODULE library, not a normal shared library — it is meant to be loaded dynamically at runtime, not linked against.
Calligra's registries look for plugins in specific subdirectories of the Qt plugin path, under calligra/. Shape plugins go in calligra/shapes, tools in calligra/tools, and dockers in calligra/dockers. Installing into the right subdirectory is what makes your plugin discoverable — the ServiceTypes entry in the JSON metadata is only informational.
TRANSLATION_DOMAIN should match the name you use for the plugin's .po files, so that strings wrapped in i18n() are translated correctly.
find_package(CalligraQt6 REQUIRED COMPONENTS flake) is Calligra's CMake package config. It provides one imported target per library, namespaced as CalligraQt6::<library> — here CalligraQt6::flake — and each of those already carries the right include directories and public link dependencies with it, so you only need to link the one component you actually use. CalligraQt6 currently provides these components: flake, pigmentcms, koodf, kowidgetutils, kundo2, kostore and interfaces — request whichever ones your plugin needs directly (e.g. COMPONENTS flake pigmentcms if you also touch color spaces), and find_package() fails with a clear error if a requested component isn't available.
This only works once Calligra itself has been configured and installed with -DSHOULD_BUILD_DEVEL_HEADERS=ON — that's what makes CalligraQt6Config.cmake get installed in the first place (see the note above).

Last is the JSON metadata component, which is how the plugin is described to the plugin loader. In older Calligra (and KDE Frameworks 4) versions this used to be a .desktop file, but KDE Frameworks plugins are now described with an embedded JSON document instead. For our example, here is myplugin.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
 "KPlugin": {
 "Name": "My Shape",
 "Description": "A shape that does something useful",
 "ServiceTypes": [
 "Calligra/Shape"
 ]
 },
 "X-Flake-MinVersion": "28",
 "X-Flake-PluginVersion": "28"
}

A couple of things are important:

The Name is shown to the user in plugin listings.
The ServiceTypes field records which kind of plugin this is (Calligra/Shape, Calligra/Tool, Calligra/Dock, ...). It is mostly documentation at this point, since Calligra locates plugins by scanning the plugin subdirectory described above, but it is good practice to keep it accurate.
X-Flake-MinVersion and X-Flake-PluginVersion let Calligra pick the newest version of a plugin when the same plugin is found installed in more than one location; bump X-Flake-PluginVersion whenever you release an updated version of the plugin.

See Flake shape creation for a full, concrete walk-through of writing a shape plugin using these building blocks.

Docs: Flake shape creation

Mon, 01 Jan 0001 00:00:00 +0000

This tutorial will guide you step by step through the creation of a Flake shape. At the end you will be able to write a shape that is loadable by any Calligra application.

For a technical introduction to how plugins in general are structured in Calligra, see Generic Calligra plugin creation — this tutorial reuses that plugin/factory pattern for the shape-specific parts.

Note

This tutorial builds the shape as a standalone plugin against an installed Calligra, via find_package(CalligraQt6). That means you need a Calligra built and installed with devel headers enabled (-DSHOULD_BUILD_DEVEL_HEADERS=ON; check for CalligraQt6Config.cmake under <prefix>/lib64/cmake/CalligraQt6).

Do the groundwork: create a shape

First of all you need a class derived from the KoShape class. This will be the actual shape class, so you have to ensure that all the data you need for painting is accessible from this KoShape-derived class.

The only method you have to reimplement is paint(), which is responsible for painting your shape. loadOdf() and saveOdf() are also pure virtual, so your shape needs to implement ODF loading and saving as well, even if that just means storing and restoring your shape's data in a private namespace.

You might also be interested in the setSize() and size() methods, which control the size available to the shape. Some shapes know the size they need on their own, so they reimplement size() to return that fixed size instead of the size set on them — KoFormulaShape does this, because a formula's size is dictated by its contents.

If your shape has a special outline, reimplement outline() to return your shape's outline correctly. Rotation, scaling and skewing are handled through a transformation matrix, so you don't need to worry about them yourself.

Here is roughly how your shape's header might look:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


#pragma once

#include <KoShape.h>

class SomeDataClass; // whatever data backs your shape

class KoFooShape : public KoShape
{
public:
 KoFooShape();
 ~KoFooShape() override;

 // absolutely necessary:
 void paint(QPainter &painter, const KoViewConverter &converter, KoShapePaintingContext &paintContext) override;
 bool loadOdf(const KoXmlElement &element, KoShapeLoadingContext &context) override;
 void saveOdf(KoShapeSavingContext &context) const override;

private:
 SomeDataClass *m_dataClass;
};

Note that paint() now takes a KoShapePaintingContext in addition to the QPainter and KoViewConverter — this carries extra state (such as whether the shape is being painted for on-screen display or for a thumbnail) that used to be threaded through in other ways in older versions of Calligra.

Make your shape loadable: create a factory and a plugin

Once you have created your shape class and implemented everything necessary to make it at least compile, you can think about how it gets loaded.

Calligra apps use KoShapeFactoryBase to obtain instances of shapes in a generic way — an application of the abstract factory pattern. You should implement a KoShapeFactoryBase-derived class that makes creating new instances of your shape possible. There's one method you must override, since it's pure virtual:

bool supports(const KoXmlElement &element, KoShapeLoadingContext &context) const — return true if the given ODF/SVG element is one your shape knows how to load. This is how Calligra picks the right shape factory while loading a document.

And two more you will usually want to override too:

KoShape *createDefaultShape(KoDocumentResourceManager *documentResources = nullptr) const
KoShape *createShape(const KoProperties *params, KoDocumentResourceManager *documentResources = nullptr) const

Both take an optional KoDocumentResourceManager, which gives you access to resources shared by the whole document (such as an image collection), and both have sensible default implementations in KoShapeFactoryBase — createShape() by default just ignores params and calls createDefaultShape() — so you only need to reimplement the ones your shape actually needs.

An example factory header:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


#pragma once

#include <KoShapeFactoryBase.h>

class FooShapeFactory : public KoShapeFactoryBase
{
public:
 FooShapeFactory();
 ~FooShapeFactory() override = default;

 KoShape *createDefaultShape(KoDocumentResourceManager *documentResources = nullptr) const override;
 KoShape *createShape(const KoProperties *params, KoDocumentResourceManager *documentResources = nullptr) const override;
 bool supports(const KoXmlElement &element, KoShapeLoadingContext &context) const override;
};

And the corresponding implementation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


#include "FooShapeFactory.h"
#include "KoFooShape.h"

#include <KLocalizedString>
#include <KoXmlNS.h>
#include <KoXmlReader.h>

FooShapeFactory::FooShapeFactory()
 : KoShapeFactoryBase("FooShape", i18n("Foo Shape"))
{
 setToolTip(i18n("A foo shape"));
}

KoShape *FooShapeFactory::createDefaultShape(KoDocumentResourceManager *documentResources) const
{
 KoFooShape *fooShape = new KoFooShape();
 // set defaults
 return fooShape;
}

KoShape *FooShapeFactory::createShape(const KoProperties *params, KoDocumentResourceManager *documentResources) const
{
 KoFooShape *fooShape = new KoFooShape();
 // use the params
 return fooShape;
}

bool FooShapeFactory::supports(const KoXmlElement &element, KoShapeLoadingContext &context) const
{
 Q_UNUSED(context);
 // return true for whichever ODF element(s) this shape knows how to load,
 // e.g. a custom draw:frame with a draw:foo child
 return element.localName() == "foo" && element.namespaceURI() == KoXmlNS::draw;
}

With the factory, there is now a generic way to obtain an instance of your shape. But somehow you still have to publish your shape as a plugin, so a Calligra application knows there is something to load. The flake library provides KoShapeRegistry for this: each application has access to the registry, and to let the application know about your shape you register it there:

KoShapeRegistry::instance()->add(new FooShapeFactory());

This call has to happen somewhere, and that somewhere is the plugin class described in Generic Calligra plugin creation — a small QObject-derived class that is instantiated once by the plugin loader purely so its constructor can perform this registration.

Example plugin header:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


#pragma once

#include <QObject>
#include <QVariantList>

class FooShapePlugin : public QObject
{
 Q_OBJECT
public:
 FooShapePlugin(QObject *parent, const QVariantList &);
};

Example plugin implementation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


#include "FooShapePlugin.h"
#include "FooShapeFactory.h"

#include <KPluginFactory>

#include <KoShapeRegistry.h>

K_PLUGIN_FACTORY_WITH_JSON(FooShapePluginFactory, "calligra_shape_foo.json", registerPlugin<FooShapePlugin>();)

FooShapePlugin::FooShapePlugin(QObject *parent, const QVariantList &)
 : QObject(parent)
{
 // register the shape's factory
 KoShapeRegistry::instance()->add(new FooShapeFactory());
 // we could register more things here in this same plugin.
}

#include "FooShapePlugin.moc"

The K_PLUGIN_FACTORY_WITH_JSON macro (from <KPluginFactory>) is what makes FooShapePlugin loadable as a KDE plugin, and ties it to the JSON metadata file described next.

The last piece is the JSON metadata file that describes your plugin and makes it findable by Calligra. Example calligra_shape_foo.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
 "KPlugin": {
 "Name": "Foo Shape",
 "Description": "A foo shape",
 "ServiceTypes": [
 "Calligra/Shape"
 ]
 },
 "X-Flake-MinVersion": "28",
 "X-Flake-PluginVersion": "28"
}

Finally, here is a CMakeLists.txt that builds and installs the plugin. Note that it installs into calligra/shapes under the Qt plugin directory; that is what makes KoShapeRegistry find it, since shape plugins are located by directory rather than by their ServiceTypes entry:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


cmake_minimum_required(VERSION 3.16)
project(fooshape)

set(CMAKE_AUTOMOC ON)

find_package(ECM 6 REQUIRED NO_MODULE)
list(APPEND CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)

find_package(CalligraQt6 REQUIRED COMPONENTS flake)

add_definitions(-DTRANSLATION_DOMAIN=\"calligra_shape_foo\")

add_library(calligra_shape_foo MODULE
 KoFooShape.cpp
 FooShapeFactory.cpp
 FooShapePlugin.cpp
)

target_link_libraries(calligra_shape_foo CalligraQt6::flake)

install(TARGETS calligra_shape_foo DESTINATION ${KDE_INSTALL_PLUGINDIR}/calligra/shapes)

Once this is configured and built, your plugin is known system-wide and can be loaded by any Calligra application. See Generic Calligra plugin creation for more detail on each of these pieces.

Make your shape editable: create a tool

To edit your shape in the GUI, the user needs a tool to select and manipulate it. For this you provide a KoToolBase-derived class, together with a KoToolFactoryBase that Calligra uses to instantiate your tool for each canvas — much like KoShapeFactoryBase is used to instantiate shapes. A tool class implements all the edit actions that can be performed on your shape, and it is possible to register more than one tool for the same shape (for example, a dedicated tool that only edits your shape's text, in addition to a general-purpose one).

The factory is registered the same way a shape factory is, from your plugin's constructor:

KoToolRegistry::instance()->add(new FooToolFactory());

For a complete, real-world example of a shape and its accompanying tool, see the picture shape plugin in the Calligra source tree, which pairs PictureShape/PictureShapeFactory with PictureTool/PictureToolFactory.