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, const QString &constraint, QObject parent, QWidget parentWidget, const QVariantList &args=QVariantList(), QString *error=nullptr)

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)

static KPluginTrader *	self ()

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 MIME types (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:

KPluginInfo::List offers =

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 81 of file kplugintrader.h.

Constructor & Destructor Documentation

◆ ~KPluginTrader()

KPluginTrader::~KPluginTrader ( )

Standard destructor.

Definition at line 36 of file kplugintrader.cpp.

Member Function Documentation

◆ createInstanceFromQuery() [1/2]

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

subDirectory	The subdirectory under the Qt plugin paths to search in
serviceType	the type of service for which to find a plugin
constraint	an optional constraint to pass to the trader (see KTrader)
parent	the parent object for the part itself
parentWidget	the parent widget for the plugin
args	A list of arguments passed to the service component
error	The 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.

Deprecated:: since 5.82, use KPluginLoader API.

Definition at line 219 of file kplugintrader.h.

◆ createInstanceFromQuery() [2/2]

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

subDirectory	The subdirectory under the Qt plugin paths to search in
serviceType	The type of service for which to find a plugin
constraint	An optional constraint to pass to the trader (see KTrader)
parent	The parent object for the part itself
args	A list of arguments passed to the service component
error	The 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.

Deprecated:: since 5.82, use KPluginLoader API.

Definition at line 188 of file kplugintrader.h.

◆ query()

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

subDirectory	The subdirectory under the Qt plugin path
servicetype	A service type like 'KMyApp/Plugin' or 'KFilePlugin'
constraint	A constraint to limit the choices returned, QString() to get all services of the given `servicetype`