KPluginLoader

#include <KPluginLoader>

Inheritance diagram for KPluginLoader:

Properties
QString	fileName

QLibrary::LoadHints	loadHints

QString	pluginName

quint32	pluginVersion

Properties inherited from QObject
	objectName

Public Member Functions
	KPluginLoader (const KPluginName &name, QObject *parent=nullptr)

	KPluginLoader (const QString &plugin, QObject *parent=nullptr)

	~KPluginLoader () override

QString	errorString () const

KPluginFactory *	factory ()

QString	fileName () const

QObject *	instance ()

bool	isLoaded () const

bool	load ()

QLibrary::LoadHints	loadHints () const

QJsonObject	metaData () const

QString	pluginName () const

quint32	pluginVersion ()

void	setLoadHints (QLibrary::LoadHints loadHints)

bool	unload ()

Public Member Functions inherited from QObject
	QObject (QObject *parent)

bool	blockSignals (bool block)

const QObjectList &	children () const const

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const const

void	deleteLater ()

void	destroyed (QObject *obj)

bool	disconnect (const char signal, const QObject receiver, const char *method) const const

bool	disconnect (const QObject receiver, const char method) const const

void	dumpObjectInfo ()

void	dumpObjectInfo () const const

void	dumpObjectTree ()

void	dumpObjectTree () const const

QList< QByteArray >	dynamicPropertyNames () const const

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

T	findChild (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const const

bool	inherits (const char *className) const const

void	installEventFilter (QObject *filterObj)

bool	isWidgetType () const const

bool	isWindowType () const const

void	killTimer (int id)

virtual const QMetaObject *	metaObject () const const

void	moveToThread (QThread *targetThread)

QString	objectName () const const

void	objectNameChanged (const QString &objectName)

QObject *	parent () const const

QVariant	property (const char *name) const const

	Q_CLASSINFO (Name, Value)

	Q_DISABLE_COPY (Class)

	Q_DISABLE_COPY_MOVE (Class)

	Q_DISABLE_MOVE (Class)

	Q_EMIT Q_EMIT

	Q_ENUM (...)

	Q_ENUM_NS (...)

	Q_ENUMS (...)

	Q_FLAG (...)

	Q_FLAG_NS (...)

	Q_FLAGS (...)

	Q_GADGET Q_GADGET

	Q_INTERFACES (...)

	Q_INVOKABLE Q_INVOKABLE

	Q_NAMESPACE Q_NAMESPACE

	Q_NAMESPACE_EXPORT (EXPORT_MACRO)

	Q_OBJECT Q_OBJECT

	Q_PROPERTY (...)

	Q_REVISION Q_REVISION

	Q_SET_OBJECT_NAME (Object)

	Q_SIGNAL Q_SIGNAL

	Q_SIGNALS Q_SIGNALS

	Q_SLOT Q_SLOT

	Q_SLOTS Q_SLOTS

T	qFindChild (const QObject *obj, const QString &name)

QList< T >	qFindChildren (const QObject *obj, const QRegExp &regExp)

QList< T >	qFindChildren (const QObject *obj, const QString &name)

T	qobject_cast (const QObject *object)

T	qobject_cast (QObject *object)

	QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT

void	removeEventFilter (QObject *obj)

void	setObjectName (const QString &name)

void	setParent (QObject *parent)

bool	setProperty (const char *name, const QVariant &value)

bool	signalsBlocked () const const

int	startTimer (int interval, Qt::TimerType timerType)

int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)

QThread *	thread () const const

Static Public Member Functions
static QString	findPlugin (const QString &name)

static QVector< KPluginMetaData >	findPlugins (const QString &directory, std::function< bool(const KPluginMetaData &)> filter=std::function< bool(const KPluginMetaData &)>())

static QVector< KPluginMetaData >	findPluginsById (const QString &directory, const QString &pluginId)

static void	forEachPlugin (const QString &directory, std::function< void(const QString &)> callback=std::function< void(const QString &)>())

static QList< QObject * >	instantiatePlugins (const QString &directory, std::function< bool(const KPluginMetaData &)> filter=std::function< bool(const KPluginMetaData &)>(), QObject *parent=nullptr)

Static Public Member Functions inherited from QObject
QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

Related Functions
(Note that these are not member functions.)
#define	K_EXPORT_PLUGIN_VERSION(version) Q_EXTERN_C Q_DECL_EXPORT const quint32 kde_plugin_version = version;

#define	Q_STANDARD_CALL

Additional Inherited Members
Public Attributes inherited from QObject
typedef	QObjectList

Protected Member Functions inherited from QObject
virtual void	childEvent (QChildEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const QMetaMethod &signal)

bool	isSignalConnected (const QMetaMethod &signal) const const

int	receivers (const char *signal) const const

QObject *	sender () const const

int	senderSignalIndex () const const

virtual void	timerEvent (QTimerEvent *event)

Detailed Description

This class behaves largely like QPluginLoader (and, indeed, uses it internally), but additionally reads the plugin version, as provided by the K_EXPORT_PLUGIN_VERSION macro (see pluginVersion()) and provides access to a KPluginFactory instance if the plugin provides one (see factory())

Note that the factory() is a typesafe convenience method that just wraps a qobject_cast on the result of QPluginLoader::instance(). Therefore, if you do not need the plugin version feature, you can (and should) just use QPluginLoader instead.

Unlike QPluginLoader, it is not possible to re-use KPluginLoader for more than one plugin (it provides no setFileName method).

The same notes and caveats that apply to QPluginLoader also apply to KPluginLoader.

Sample code:

KPluginLoader loader( ...library or kservice... );
KPluginFactory* factory = loader.factory();
if (!factory) {
    qWarning() << "Error loading plugin:" << loader.errorString();
} else {
    MyInterface* obj = factory->create<MyInterface>();
    if (!obj) {
        qWarning() << "Error creating object";
    }
}

See also: KPluginFactory

Author: Bernhard Loos nhuh.[email protected][email protected][email protected]web.d[email protected]e

Deprecated:: Since 5.86, the findPluginsById, findPlugins and factory methods have been imported to KPluginMetaData. Check the deprecating messages of the other search related methods for porting instructions. The methods which are exclusively used to work around QTBUG-39642 are deprecated in favour of using QPluginLoader directly. With Qt 5.15 this bug has been fixed.

Definition at line 69 of file kpluginloader.h.

Constructor & Destructor Documentation

◆ KPluginLoader() [1/2]

KPluginLoader::KPluginLoader	(	const QString &	plugin,
		QObject *	parent = `nullptr`
	)

explicit

Load a plugin by name.

This should be the name of the plugin object file, without any suffix (like .so or .dll). Plugin object files should not have a 'lib' prefix.

fileName() will be empty if the plugin could not be found.

Parameters

plugin	The name of the plugin.
parent	A parent object.

Definition at line 62 of file kpluginloader.cpp.

◆ KPluginLoader() [2/2]

KPluginLoader::KPluginLoader	(	const KPluginName &	name,
		QObject *	parent = `nullptr`
	)

explicit

Load a plugin by name.

This constructor behaves exactly the same as KPluginLoader(const QString&,QObject*). It allows any class that can be cast to KPluginName (such as KService) to be passed to KPluginLoader.

Parameters

name	The name of the plugin.
parent	A parent object.

Definition at line 72 of file kpluginloader.cpp.

◆ ~KPluginLoader()

KPluginLoader::~KPluginLoader ( )

overridedefault

Destroys the plugin loader.

Unless unload() was called explicitly, the plugin stays in memory until the application terminates.

Member Function Documentation

◆ errorString()

QString KPluginLoader::errorString ( ) const

Returns the last error.

Returns: The description of the last error.

See also: QPluginLoader::errorString()

Deprecated:: Since 5.86, use QPluginLoader::errorString() instead

Definition at line 139 of file kpluginloader.cpp.

◆ factory()

KPluginFactory * KPluginLoader::factory ( )

Returns the factory object of the plugin.

This is typically created by one of the KPluginFactory macros. Internally, this uses QPluginLoader::instance(), and the same behaviours apply.

Since KF 5.77, the factory will have the metadata set fetched from any JSON metadata that is embedded into the plugin binary.

Returns: The factory of the plugin or nullptr on error.

Deprecated:: Since 5.86, use KPluginFactory::loadFactory or KPluginFactory::instantiatePlugin instead

Definition at line 94 of file kpluginloader.cpp.

◆ fileName()

QString KPluginLoader::fileName ( ) const

Returns the path of the plugin.

This will be the full path of the plugin if it was found, and empty if it could not be found.

Returns: The full path of the plugin, or the null string if it could not be found.

See also: QPluginLoader::fileName(), pluginName()

Deprecated:: Since 5.86, use QPluginLoader::fileName() instead, in case of complex query logic consider using KPluginLoader::findPlugins

◆ findPlugin()

QString KPluginLoader::findPlugin ( const QString & name )

static

Locates a plugin.

Searches for a dynamic object file in the locations KPluginLoader and QPluginLoader would search (ie: the current directory and QCoreApplication::libraryPaths()).

This can be useful if you wish to use a plugin that does not conform to the Qt plugin scheme of providing a QObject that declares Q_PLUGIN_METADATA. In this case, you can find the plugin with this method, and load it with QLibrary.

Note that the path is not necessarily absolute. In particular, if the plugin is found in the current directory, it will be a relative path.

Parameters

name	The name of the plugin (can be a relative path; see above). This should not include a file extension (like .so or .dll).

Returns: The path to the plugin if it was found, or QString() if it could not be found.

Since: 5.0

Deprecated:: Since 5.86, contruct a QPluginLoader and call fileName() or use KPluginMetaData::findPluginById instead

Definition at line 49 of file kpluginloader.cpp.

◆ findPlugins()

QVector< KPluginMetaData > KPluginLoader::findPlugins	(	const QString &	directory,
		std::function< bool(const KPluginMetaData &)>	filter = `std::function<bool(const KPluginMetaData &)>()`
	)

static

Find all plugins inside directory.

Only plugins which have JSON metadata will be considered.

Parameters

directory	The directory to search for plugins. If a relative path is given for `directory`, all entries of QCoreApplication::libraryPaths() will be checked with `directory` appended as a subdirectory. If an absolute path is given only that directory will be searched.
filter	a callback function that returns `true` if the found plugin should be loaded and `false` if it should be skipped. If this argument is omitted all plugins will be loaded.

Returns: all plugins found in directory that fulfil the constraints of filter

See also: KPluginLoader::instantiatePlugins()

Since: 5.1

Deprecated:: Since 5.86 use KPluginMetaData::findPlugins instead

Definition at line 272 of file kpluginloader.cpp.

◆ findPluginsById()

QVector< KPluginMetaData > KPluginLoader::findPluginsById	(	const QString &	directory,
		const QString &	pluginId
	)

static

Find all plugins inside directory with a given pluginId.

Only plugins which have JSON metadata will be considered.

Parameters

directory	The directory to search for plugins. If a relative path is given for `directory`, all entries of QCoreApplication::libraryPaths() will be checked with `directory` appended as a subdirectory. If an absolute path is given only that directory will be searched.
pluginId	The Id of the plugin, for example KPluginMetaData.pluginId().

Returns: all plugins found in directory with the given pluginId.

See also: KPluginLoader::instantiatePlugins()

Since: 5.11

Deprecated:: Since 5.86 use KPluginMetaData::findPluginsById instead

Definition at line 293 of file kpluginloader.cpp.

◆ forEachPlugin()

void KPluginLoader::forEachPlugin	(	const QString &	directory,
		std::function< void(const QString &)>	callback = `std::function<void(const QString &)>()`
	)

static

Invokes callback for each valid plugin found inside directory.

This is useful if your application needs to customize the behaviour of KPluginLoader::findPlugins() or KPluginLoader::instantiatePlugins().

Note: The files found do not necessarily contain JSON metadata and may not be loadable using K/QPluginLoader. The only guarantee made is that they are valid library file names as determined by QLibrary::isLibrary().

Parameters

directory	The directory to search for plugins. If a relative path is given for `directory`, all entries of QCoreApplication::libraryPaths() will be checked with `directory` appended as a subdirectory. If an absolute path is given only that directory will be searched.
callback	This function will be invoked for each valid plugin that is found. It will receive the absolute path to the plugin as an argument

See also: KPluginLoader::findPlugins(), KPluginLoader::instantiatePlugins()

Since: 5.1

Deprecated:: Since 5.86 use KPluginMetaData::findPlugins instead. This will warn about invalid plugin metadata and only return valid results.

Definition at line 234 of file kpluginloader.cpp.

◆ instance()

QObject * KPluginLoader::instance ( )

Returns the root object of the plugin.

The plugin will be loaded if necessary. If the plugin used one of the KPluginFactory macros, you should use factory() instead.

Returns: The plugin's root object.

See also: QPluginLoader::instance()

Deprecated:: Since 5.86, use QPluginLoader::instance() instead

Definition at line 156 of file kpluginloader.cpp.

◆ instantiatePlugins()

QList< QObject * > KPluginLoader::instantiatePlugins	(	const QString &	directory,
		std::function< bool(const KPluginMetaData &)>	filter = `std::function<bool(const KPluginMetaData &)>()`,
		QObject *	parent = `nullptr`
	)

static

Finds and instantiates (by calling QPluginLoader::instance()) all plugins from a given directory.

Only plugins which have JSON metadata will be considered. A filter can be passed which determines which of the found plugins should actually be loaded.

If you use KConfig you could have a group "Plugins" in your configuration file with the plugin name as the key and true/false as the value to indicate whether the plugin should be loaded. In order to easily load all the enable plugins you could use the following code:

KConfigGroup pluginGroup = KSharedConfig::openConfig()->group("Plugins");
auto filter = [&](const KPluginMetaData &md) {
    if (!pluginGroup.hasKey(md.pluginName())) {
        return md.isEnabledByDefault();
    } else {
        return pluginGroup.readEntry(md.pluginName(), false);
    }
};
QList<QObject*> plugins = KPluginLoader::instantiatePlugins("myapp", filter);

Parameters

directory	the directory to search for plugins. If a relative path is given for `directory`, all entries of QCoreApplication::libraryPaths() will be checked with `directory` appended as a subdirectory. If an absolute path is given only that directory will be searched.
filter	a callback function that returns `true` if the found plugin should be loaded and `false` if it should be skipped. If this argument is omitted all plugins will be loaded.
parent	the parent to set for the instantiated plugins, if the plugins were not already loaded.

Note: If the plugins have been previously loaded (via QPluginLoader, directly or due to this class) without being deleted in the meantime then they are not re-created or re-parented and will be returned using the parent they were originally created with.

See also: QPluginLoader::instance().

Returns: a list containing an instantiation of each plugin that met the filter criteria

See also: KPluginLoader::findPlugins()

Since: 5.1

Deprecated:: Since 5.86 create instances from the KPluginMetaData::findPlugins result instead. In case you are using KPluginFactory use KPluginMetaData::factory on the returned metadata objects. Otherwise use KPluginMetaData::instantiate or QPluginLoader on the returned metadata objects.

See also: KPluginFactory::loadFactory, KPluginFactory::instantiatePlugin

Definition at line 301 of file kpluginloader.cpp.

◆ isLoaded()

bool KPluginLoader::isLoaded ( ) const

Determines whether the plugin is loaded.

Returns: True if the plugin is loaded, false otherwise.

See also: QPluginLoader::isLoaded()

Deprecated:: Since 5.86, use QPluginLoader::isLoaded() instead

Definition at line 167 of file kpluginloader.cpp.

◆ load()

bool KPluginLoader::load ( )

Loads the plugin.

It is safe to call this multiple times; if the plugin was already loaded, it will just return true.

Methods that require the plugin to be loaded will load it as necessary anyway, so you do not normally need to call this method.

Returns: True if the plugin was loaded successfully, false otherwise.

See also: QPluginLoader::load()

Deprecated:: Since 5.86, use QPluginLoader::load() instead

Definition at line 174 of file kpluginloader.cpp.

◆ loadHints()

QLibrary::LoadHints KPluginLoader::loadHints ( ) const

Returns the load hints for the plugin.

Determines how load() should work. See QLibrary::loadHints for more information.

Returns: The load hints for the plugin.

See also: QPluginLoader::loadHints(), setLoadHints()

Deprecated:: Since 5.86, use QPluginLoader::loadHints() instead

◆ metaData()

QJsonObject KPluginLoader::metaData ( ) const

Returns the meta data for the plugin.

Returns: A JSON object containing the plugin's metadata, if found.

See also: QPluginLoader::metaData()

Deprecated:: Since 5.86, use QPluginLoader::metaData() or KPluginMetaData instead

Definition at line 209 of file kpluginloader.cpp.

◆ pluginName()

QString KPluginLoader::pluginName ( ) const

Returns the name of this plugin as given to the constructor.

If the KService constructor was used, this is the name of the library provided by the service.

Returns: The plugin name.

See also: fileName()

Deprecated:: Since 5.86, use KPluginMetaData::pluginId instead

◆ pluginVersion()

quint32 KPluginLoader::pluginVersion ( )

Returns the plugin version.

This will load the plugin if it is not already loaded.

Returns: The version given to K_EXPORT_PLUGIN_VERSION, or (quint32) -1 if the macro was not used or the plugin could not be loaded.

Deprecated:: Since 5.84, use KPluginMetaData::version() or a versioned namespace instead

◆ setLoadHints()

void KPluginLoader::setLoadHints ( QLibrary::LoadHints loadHints )

Set the load hints for the plugin.

Determines how load() should work. See QLibrary::loadHints for more information.

Parameters

loadHints The load hints for the plugin.

See also: QPluginLoader::setLoadHints(), loadHints()

Deprecated:: Since 5.86, use QPluginLoader::setLoadHints instead

Definition at line 216 of file kpluginloader.cpp.

◆ unload()

bool KPluginLoader::unload ( )

Attempts to unload the plugin.

If other instances of KPluginLoader or QPluginLoader are using the same plugin, this will fail; unloading will only happen when every instance has called unload().

Returns: True if the plugin was unloaded, false otherwise.

See also: QPluginLoader::unload(), load(), instance(), factory()

Deprecated:: Since 5.86, use QPluginLoader::unload() instead

Definition at line 223 of file kpluginloader.cpp.

Friends And Related Function Documentation

◆ K_EXPORT_PLUGIN_VERSION

#define K_EXPORT_PLUGIN_VERSION ( version ) Q_EXTERN_C Q_DECL_EXPORT const quint32 kde_plugin_version = version;

Use this macro if you want to give your plugin a version number. You can later access the version number with KPluginLoader::pluginVersion()

Deprecated:: Since 5.84, use KPluginMetaData::version() or a versioned namespace instead

Definition at line 23 of file kexportplugin.h.

◆ Q_STANDARD_CALL

#define Q_STANDARD_CALL

This macro exports the main object of the plugin. Most times, this will be a KPluginFactory or derived class, but any QObject derived class can be used. Take a look at the documentation of Q_EXPORT_PLUGIN2 for some details.

Definition at line 37 of file kexportplugin.h.

The documentation for this class was generated from the following files:

KConfigGroup::readEntry

QString readEntry(const char *key, const char *aDefault=nullptr) const

QList

KSharedConfig::openConfig

static KSharedConfig::Ptr openConfig(const QString &fileName=QString(), OpenFlags mode=FullConfig, QStandardPaths::StandardLocation type=QStandardPaths::GenericConfigLocation)

KPluginFactory

Definition: kpluginfactory.h:427

KPluginLoader

Definition: kpluginloader.h:69

QtConcurrent::filter

QFuture< void > filter(Sequence &sequence, KeepFunctor filterFunction)

KPluginLoader::factory

KPluginFactory * factory()

Returns the factory object of the plugin.

Definition: kpluginloader.cpp:94

KPluginFactory::create

T * create(QObject *parent=nullptr, const QVariantList &args=QVariantList())

Use this method to create an object.

Definition: kpluginfactory.h:936

KConfigGroup

KConfigGroup::hasKey

bool hasKey(const char *key) const

KPluginLoader::instantiatePlugins

static QList< QObject * > instantiatePlugins(const QString &directory, std::function< bool(const KPluginMetaData &)> filter=std::function< bool(const KPluginMetaData &)>(), QObject *parent=nullptr)

Finds and instantiates (by calling QPluginLoader::instance()) all plugins from a given directory.

Definition: kpluginloader.cpp:301

KPluginMetaData

Definition: kpluginmetadata.h:87

KDE's Doxygen guidelines are available online.

Class Picker

Quick Links

About KCoreAddons

KPluginLoader

Properties

Public Member Functions

Static Public Member Functions

Related Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ KPluginLoader() [1/2]

◆ KPluginLoader() [2/2]

◆ ~KPluginLoader()

Member Function Documentation

◆ errorString()

◆ factory()

◆ fileName()

◆ findPlugin()

◆ findPlugins()

◆ findPluginsById()

◆ forEachPlugin()

◆ instance()

◆ instantiatePlugins()

◆ isLoaded()

◆ load()

◆ loadHints()

◆ metaData()

◆ pluginName()

◆ pluginVersion()

◆ setLoadHints()

◆ unload()

Friends And Related Function Documentation

◆ K_EXPORT_PLUGIN_VERSION

◆ Q_STANDARD_CALL