KPluginTrader

#include <KPluginTrader>

Public Member Functions

 ~KPluginTrader ()
 
KPluginInfo::List query (const QString &subDirectory, const QString &serviceType=QString(), const QString &constraint=QString())
 

Static Public Member Functions

static void applyConstraints (KPluginInfo::List &lst, const QString &constraint)
 
template<class T >
static T * createInstanceFromQuery (const QString &subDirectory, const QString &serviceType=QString(), const QString &constraint=QString(), QObject *parent=nullptr, const QVariantList &args=QVariantList(), QString *error=nullptr)
 
template<class T >
static T * createInstanceFromQuery (const QString &subDirectory, const QString &serviceType, const QString &constraint, QObject *parent, QWidget *parentWidget, const QVariantList &args=QVariantList(), QString *error=nullptr)
 
static KPluginTraderself ()
 

Detailed Description

A trader interface which provides a way to query specific subdirectories in the Qt plugin paths for plugins.

KPluginTrader provides an easy way to load a plugin instance from a KPluginFactory, or just querying for existing plugins.

KPluginTrader provides a way for an application to query directories in the Qt plugin paths, accessed through QCoreApplication::libraryPaths(). Plugins may match a specific set of requirements. This allows to find specific plugins at run-time without having to hard-code their names and/or paths. KPluginTrader does not search recursively, you are rather encouraged to install plugins into specific subdirectories to further speed searching.

KPluginTrader exclusively searches within the plugin binaries' metadata (via QPluginLoader::metaData()). It does not search these directories recursively.

KPluginTrader does not use KServiceTypeTrader or KSyCoCa. As such, it will only find binary plugins. If you are looking for a generic way to query for services, use KServiceTypeTrader. For anything relating to mimetypes (type of files), use KMimeTypeTrader.

Example

If you want to find all plugins for your application, you would define a KMyApp/Plugin servicetype, and then you can query the trader for it:

KPluginTrader::self()->query("KMyApp/Plugin", "kf5");

You can add a constraint in the "trader query language". For instance:

KPluginTrader::self()->query("KMyApp/Plugin", "kf5",
"[X-KMyApp-InterfaceVersion] > 15");

Please note that when including property names containing arithmetic operators like - or +, then you have to put brackets around the property name, in order to correctly separate arithmetic operations from the name. So for example a constraint expression like

X-KMyApp-InterfaceVersion > 4 // wrong!

needs to be written as

[X-KMyApp-InterfaceVersion] > 4

otherwise it could also be interpreted as Subtract the numeric value of the property "KMyApp" and "InterfaceVersion" from the property "X" and make sure it is greater than 4.
Instead of the other meaning, make sure that the numeric value of "X-KMyApp-InterfaceVersion" is greater than 4.

See also
KMimeTypeTrader, KServiceTypeTrader, KPluginInfo
QCoreApplication::libraryPaths
QT_PLUGIN_PATH (env variable)
KPluginFactory
kservice_desktop_to_json (Cmake macro)
K_PLUGIN_FACTORY_WITH_JSON (macro defined in KPluginFactory)
Since
5.0

Definition at line 88 of file kplugintrader.h.

Constructor & Destructor Documentation

KPluginTrader::~KPluginTrader ( )

Standard destructor.

Definition at line 41 of file kplugintrader.cpp.

Member Function Documentation

template<class T >
static T* KPluginTrader::createInstanceFromQuery ( const QString subDirectory,
const QString serviceType = QString(),
const QString constraint = QString(),
QObject parent = nullptr,
const QVariantList &  args = QVariantList(),
QString error = nullptr 
)
inlinestatic

Get a plugin from a trader query.

Example:

KMyAppPlugin* plugin = KPluginTrader::createInstanceFromQuery<KMyAppPlugin>(subDirectory, serviceType, QString(), parentObject );
if ( plugin ) {
....
}
Parameters
subDirectoryThe subdirectory under the Qt plugin pathes to search in
serviceTypeThe type of service for which to find a plugin
constraintAn optional constraint to pass to the trader (see KTrader)
parentThe parent object for the part itself
argsA list of arguments passed to the service component
errorThe string passed here will contain an error description.
Returns
A pointer to the newly created object or a null pointer if the factory was unable to create an object of the given type.

Definition at line 189 of file kplugintrader.h.

template<class T >
static T* KPluginTrader::createInstanceFromQuery ( const QString subDirectory,
const QString serviceType,
const QString constraint,
QObject parent,
QWidget parentWidget,
const QVariantList &  args = QVariantList(),
QString error = nullptr 
)
inlinestatic

Get a plugin from a trader query.

This method works like createInstanceFromQuery(const QString&, const QString& ,const QString&, QObject*, const QVariantList&, QString*), but you can specify an additional parent widget. This is important for a KPart, for example.

Parameters
subDirectoryThe subdirectory under the Qt plugin pathes to search in
serviceTypethe type of service for which to find a plugin
constraintan optional constraint to pass to the trader (see KTrader)
parentthe parent object for the part itself
parentWidgetthe parent widget for the plugin
argsA list of arguments passed to the service component
errorThe string passed here will contain an error description.
Returns
A pointer to the newly created object or a null pointer if the factory was unable to create an object of the given type.

Definition at line 218 of file kplugintrader.h.

KPluginInfo::List KPluginTrader::query ( const QString subDirectory,
const QString serviceType = QString(),
const QString constraint = QString() 
)

The main function in the KPluginTrader class.

It will return a list of plugins that match your specifications. Required parameter is the service type and subdirectory. This method will append the subDirectory to every path found in QCoreApplication::libraryPaths(), append the subDirectory parameter, and search through the plugin's metadata

KPluginTrader exclusively searches within the plugin binaries' metadata (via QPluginLoader::metaData()). It does not search these directories recursively.

The constraint parameter is used to limit the possible choices returned based on the constraints you give it.

The constraint language is rather full. The most common keywords are AND, OR, NOT, IN, and EXIST, all used in an almost spoken-word form. An example is:

(Type == 'Service') and (('KParts/ReadOnlyPart' in ServiceTypes) or (exist Exec))

If you want to load a list of plugins from a specific subdirectory, you can do the following:

const KPluginInfo::List plugins = KPluginTrader::self()->query("plasma/engines");
for (const KPluginInfo &info : plugins) {
KPluginLoader loader(info.libraryPath());
const QVariantList argsWithMetaData = QVariantList() << loader.metaData().toVariantMap();
// In many cases, plugins are actually based on KPluginFactory, this is how that works:
KPluginFactory* factory = loader.factory();
if (factory) {
Engine* component = factory->create<Engine>(parent, argsWithMetaData);
if (component) {
// Do whatever you want to do with the resulting object
}
}
// Otherwise, just use the normal QPluginLoader methods
Engine *myengine = qobject_cast<Engine*>(loader.instance());
if (myengine) {
// etc. ...
}
}

If you have a specific query for just one plugin, use the createInstanceFromQuery method.

The keys used in the query (Type, ServiceType, Exec) are all fields found in the .json files which are compiled into the plugin binaries.

Parameters
subDirectoryThe subdirectory under the Qt plugin path
servicetypeA service type like 'KMyApp/Plugin' or 'KFilePlugin'
constraintA constraint to limit the choices returned, QString() to get all services of the given servicetype
Returns
A list of services that satisfy the query
See also
http://techbase.kde.org/Development/Tutorials/Services/Traders#The_KTrader_Query_Language

Definition at line 69 of file kplugintrader.cpp.

KPluginTrader * KPluginTrader::self ( )
static

This is a static pointer to the KPluginTrader singleton.

You will need to use this to access the KPluginTrader functionality since the constructors are protected.

Returns
Static KPluginTrader instance

Definition at line 30 of file kplugintrader.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Wed Aug 5 2020 22:45:46 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.