KTextEditor

Hosting KTextEditor plugins

While the KTextEditor framework provides a powerful text editor in itself, further features are available from plugins (KTextEditor::Plugin). At the time of this writing, all known KTextEditor plugins are maintained by the kate project, but most can be used in other hosting applications, as well.

This page is about supporting KTextEditor plugins in your application. For information on developing the plugins themselves, refer to KTextEditor::Plugin.

Loading simple plugins

The steps needed to find and load basic KTextEditor plugins are roughly as follows:

QStringList plugins_to_load = QStringList() << "openlinkplugin" << "rainbowparens";
QList<KPluginMetaData> plugins = KPluginMetaData::findPlugins(QStringLiteral("ktexteditor"));
for (const auto &plugin_meta_data : plugins) {
QString identifier = plugin_meta_data.filename().basename();
if (!plugins_to_load.contains(identifier)) {
continue;
}
plugins_to_load.removeOne(identifier); // avoid loading separate versions of the same plugin
KTextEditor::Plugin *plugin = KPluginFactory::instantiatePlugin<KTextEditor::Plugin>(plugin_meta_data, this, QVariantList() << identifier).plugin;
if (plugin) {
QObject* created = plugin->createView();
if (created) {
emit mainWindow()->main->pluginViewCreated(identifier, created);
KTextEditor::SessionConfigInterface *interface = qobject_cast<KTextEditor::SessionConfigInterface *>(created);
if (interface) {
// NOTE: Some plugins will misbehave, unless readSessionConfig has been called!
KConfigGroup group = KSharedConfig::openConfig()->group(QStringLiteral("KatePlugin:%1:").arg(identifier));
interface->readSessionConfig(group);
}
}
}
}
KConfigGroup group(const QString &group)
static QList< KPluginMetaData > findPlugins(const QString &directory, std::function< bool(const KPluginMetaData &)> filter={}, KPluginMetaDataOptions options={})
static KSharedConfig::Ptr openConfig(const QString &fileName=QString(), OpenFlags mode=FullConfig, QStandardPaths::StandardLocation type=QStandardPaths::GenericConfigLocation)
void pluginCreated(const QString &name, KTextEditor::Plugin *plugin)
This signal is emitted when an Plugin was loaded.
static Editor * instance()
Accessor to get the Editor instance.
virtual KTextEditor::Application * application() const =0
Current hosting application, if any set.
KTextEditor Plugin interface.
Definition plugin.h:79
virtual QObject * createView(KTextEditor::MainWindow *mainWindow)=0
Create a new View for this plugin for the given KTextEditor::MainWindow.
Session config interface extension for the Plugin and Plugin views.
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
bool removeOne(const AT &t)
bool contains(QLatin1StringView str, Qt::CaseSensitivity cs) const const

Note, however, that only a few basic plugins will actually be functional with the above, alone. For others, we need to implement several additional functions, as detailed, below.

Implementing full plugin hosting

I order to allow plugins to interact with the hosting application (e.g. creating or activating additional windows/widgets), you need to implement two interfacing classes:

The latter corresponds to top level windows in your application (it's ok, if your application only supports a single toplevel window), with the assumption being that several document- and/or tool-windows can existing in each main window.

The two classes are really just a thin layer to dispatch from API to be used in plugins to the appropiate functionality in your application. For best runtime compatibility even across different version of KTextEditor, this is implemented using Qt slots. E.g. KTextEditor::MainWindow::activeView() is defined as:

KTextEditor::View *MainWindow::activeView()
{
// dispatch to parent
KTextEditor::View *view = nullptr;
QMetaObject::invokeMethod(parent(), "activeView", Qt::DirectConnection, Q_RETURN_ARG(KTextEditor::View*, view));
return view;
}
A text widget with KXMLGUIClient that represents a Document.
Definition view.h:244
bool invokeMethod(QObject *context, Functor &&function, FunctorReturnType *ret)
DirectConnection

I.e. this function (and most others in KTextEditor::MainWindow and KTextEditor::Application) simply invokes a slot by the same name and signature in its parent QObject. This is what you need to provide. The following example should illustrate the idea:

class MyKTEMainWindow : public QObject {
MyKTEMainWindow() {
// create a dispatch object _as a child of this object_
kte_win = new KTextEditor::MainWindow(this);
}
[...]
public slots:
KTextEditor::View* activateView(KTextEditor::Document *document) {
auto view = myFindViewForDoc(document);
myActivateView(view);
return view;
}
[further implementations]
private:
friend class MyKTEApplication;
}
class MyKTEApplication : public QObject {
MyKTEApplicaiton() {
// create a dispatch object _as a child of this object_
kte_app = new KTextEditor::Application(this);
// For simplicity, let's assume a single main window, and create a wrapper for it, here
my_main_win = new MyKTEMainWindow;
// register with KTextEditor
}
[...]
public slots:
KTextEditor::MainWindow* activeMainWindow() {
return my_main_win->kte_win;
}
[further implementations]
private:
MyKTEMainWindow* my_main_win;
}
This class allows the application that embeds the KTextEditor component to allow it access to applica...
Definition application.h:44
A KParts derived class representing a text document.
Definition document.h:284
virtual void setApplication(KTextEditor::Application *application)=0
Set the global application object.
This class allows the application that embeds the KTextEditor component to allow it to access parts o...
Definition mainwindow.h:47
Note
Due to the lose coupling via Qt slots, you may not need to implement a dispatch slots for every single member in KTextEditor::Application, and KTextEditor::MainWindow. Naturally, however, plugins will be more likely to work as expected, the more complete the hosting app implements these interfaces.
Don't forget to integrate the plugin config pages, if desired:
See also
KTextEditor::Plugin::configPage(),
KTextEditor::Plugin::configPages().
KTextEditor::Plugin, KTextEditor::Application, KTextEditor::MainWindow
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:05:19 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.