KPluginLoader
#include <KPluginLoader>

Properties | |
QString | fileName |
QLibrary::LoadHints | loadHints |
QString | pluginName |
quint32 | pluginVersion |
![]() | |
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 () |
![]() | |
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 ®Exp, 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 ®Exp) |
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) |
![]() | |
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 | |
![]() | |
typedef | QObjectList |
![]() | |
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:
- See also
- KPluginFactory
- Deprecated:
- Since 5.86, the
findPluginsById
,findPlugins
andfactory
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]
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]
|
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()
|
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()
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()
|
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 withdirectory
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 andfalse
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 offilter
- Since
- 5.1
- Deprecated:
- Since 5.86 use KPluginMetaData::findPlugins instead
Definition at line 272 of file kpluginloader.cpp.
◆ findPluginsById()
|
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 withdirectory
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.
- Since
- 5.11
- Deprecated:
- Since 5.86 use KPluginMetaData::findPluginsById instead
Definition at line 293 of file kpluginloader.cpp.
◆ forEachPlugin()
|
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 withdirectory
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
- 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()
|
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:
- Parameters
-
directory the directory to search for plugins. If a relative path is given for directory
, all entries of QCoreApplication::libraryPaths() will be checked withdirectory
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 andfalse
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.
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
|
related |
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
|
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 37 of file kexportplugin.h.
The documentation for this class was generated from the following files:
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Dec 8 2023 04:03:01 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006
KDE's Doxygen guidelines are available online.