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 QString &plugin, QObject *parent=nullptr)
 
 KPluginLoader (const KPluginName &name, QObject *parent=nullptr)
 
 ~KPluginLoader ()
 
QString errorString () const
 
KPluginFactoryfactory ()
 
QString fileName () const
 
QObjectinstance ()
 
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 QObjectListchildren () 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< QByteArraydynamicPropertyNames () const const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (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
 
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 QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () 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
 
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)
 
qobject_cast (QObject *object)
 
qobject_cast (const 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)
 
QThreadthread () const const
 

Static Public Member Functions

static QString findPlugin (const QString &name)
 
static QVector< KPluginMetaDatafindPlugins (const QString &directory, std::function< bool(const KPluginMetaData &)> filter=std::function< bool(const KPluginMetaData &)>())
 
static QVector< KPluginMetaDatafindPluginsById (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 *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
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, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &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
 
QObjectsender () 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

Definition at line 60 of file kpluginloader.h.

Constructor & Destructor Documentation

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
pluginThe name of the plugin.
parentA parent object.

Definition at line 58 of file kpluginloader.cpp.

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
nameThe name of the plugin.
parentA parent object.

Definition at line 68 of file kpluginloader.cpp.

KPluginLoader::~KPluginLoader ( )

Destroys the plugin loader.

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

Definition at line 89 of file kpluginloader.cpp.

Member Function Documentation

QString KPluginLoader::errorString ( ) const

Returns the last error.

Returns
The description of the last error.
See also
QPluginLoader::errorString()

Definition at line 137 of file kpluginloader.cpp.

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.

Definition at line 94 of file kpluginloader.cpp.

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()
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
nameThe 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

Definition at line 45 of file kpluginloader.cpp.

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
directoryThe 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.
filtera 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

Definition at line 258 of file kpluginloader.cpp.

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
directoryThe 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.
pluginIdThe 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

Definition at line 274 of file kpluginloader.cpp.

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
directoryThe 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.
callbackThis 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

Definition at line 233 of file kpluginloader.cpp.

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()

Definition at line 154 of file kpluginloader.cpp.

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);
}
};
Parameters
directorythe 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.
filtera 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.
parentthe 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

Definition at line 283 of file kpluginloader.cpp.

bool KPluginLoader::isLoaded ( ) const

Determines whether the plugin is loaded.

Returns
True if the plugin is loaded, false otherwise.
See also
QPluginLoader::isLoaded()

Definition at line 165 of file kpluginloader.cpp.

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()

Definition at line 172 of file kpluginloader.cpp.

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()
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()

Definition at line 207 of file kpluginloader.cpp.

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()
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.
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
loadHintsThe load hints for the plugin.
See also
QPluginLoader::setLoadHints(), loadHints()

Definition at line 214 of file kpluginloader.cpp.

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()

Definition at line 221 of file kpluginloader.cpp.

Friends And Related Function Documentation

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

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

Definition at line 21 of file kexportplugin.h.

#define Q_STANDARD_CALL
related

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 35 of file kexportplugin.h.


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 Sat Nov 21 2020 23:02:16 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.