QPluginLoader¶
The
QPluginLoader
class loads a plugin at run-time. More…
Synopsis¶
Functions¶
def
errorString
()def
fileName
()def
instance
()def
isLoaded
()def
load
()def
metaData
()def
setFileName
(fileName)def
unload
()
Static functions¶
def
staticInstances
()
Detailed Description¶
QPluginLoader
provides access to a Qt plugin. A Qt plugin is stored in a shared library (a DLL) and offers these benefits over shared libraries accessed usingQLibrary
:
QPluginLoader
checks that a plugin is linked against the same version of Qt as the application.
QPluginLoader
provides direct access to a root component object (instance()
), instead of forcing you to resolve a C function manually.An instance of a
QPluginLoader
object operates on a single shared library file, which we call a plugin. It provides access to the functionality in the plugin in a platform-independent way. To specify which plugin to load, either pass a file name in the constructor or set it withsetFileName()
.The most important functions are
load()
to dynamically load the plugin file,isLoaded()
to check whether loading was successful, andinstance()
to access the root component in the plugin. Theinstance()
function implicitly tries to load the plugin if it has not been loaded yet. Multiple instances ofQPluginLoader
can be used to access the same physical plugin.Once loaded, plugins remain in memory until all instances of
QPluginLoader
has been unloaded, or until the application terminates. You can attempt to unload a plugin usingunload()
, but if other instances ofQPluginLoader
are using the same library, the call will fail, and unloading will only happen when every instance has calledunload()
. Right before the unloading happens, the root component will also be deleted.See How to Create Qt Plugins for more information about how to make your application extensible through plugins.
Note that the
QPluginLoader
cannot be used if your application is statically linked against Qt. In this case, you will also have to link to plugins statically. You can useQLibrary
if you need to load dynamic libraries in a statically linked application.See also
QLibrary
Plug & Paint Example
- class PySide2.QtCore.QPluginLoader([parent=None])¶
PySide2.QtCore.QPluginLoader(fileName[, parent=None])
- param parent:
- param fileName:
str
Constructs a plugin loader with the given
parent
.Constructs a plugin loader with the given
parent
that will load the plugin specified byfileName
.To be loadable, the file’s suffix must be a valid suffix for a loadable library in accordance with the platform, e.g.
.so
on Unix, -.dylib
on macOS and iOS, and.dll
on Windows. The suffix can be verified withisLibrary()
.See also
- PySide2.QtCore.QPluginLoader.errorString()¶
- Return type:
str
Returns a text string with the description of the last error that occurred.
- PySide2.QtCore.QPluginLoader.fileName()¶
- Return type:
str
This property holds the file name of the plugin.
We recommend omitting the file’s suffix in the file name, since
QPluginLoader
will automatically look for the file with the appropriate suffix (seeisLibrary()
).When loading the plugin,
QPluginLoader
searches in all plugin locations specified bylibraryPaths()
, unless the file name has an absolute path. After loading the plugin successfully, returns the fully-qualified file name of the plugin, including the full path to the plugin if one was given in the constructor or passed to .If the file name does not exist, it will not be set. This property will then contain an empty string.
By default, this property contains an empty string.
See also
- PySide2.QtCore.QPluginLoader.instance()¶
- Return type:
Returns the root component object of the plugin. The plugin is loaded if necessary. The function returns
None
if the plugin could not be loaded or if the root component object could not be instantiated.If the root component object was destroyed, calling this function creates a new instance.
The root component, returned by this function, is not deleted when the
QPluginLoader
is destroyed. If you want to ensure that the root component is deleted, you should callunload()
as soon you don’t need to access the core component anymore. When the library is finally unloaded, the root component will automatically be deleted.The component object is a
QObject
. Useqobject_cast()
to access interfaces you are interested in.See also
- PySide2.QtCore.QPluginLoader.isLoaded()¶
- Return type:
bool
Returns
true
if the plugin is loaded; otherwise returnsfalse
.See also
- PySide2.QtCore.QPluginLoader.load()¶
- Return type:
bool
Loads the plugin and returns
true
if the plugin was loaded successfully; otherwise returnsfalse
. Sinceinstance()
always calls this function before resolving any symbols it is not necessary to call it explicitly. In some situations you might want the plugin loaded in advance, in which case you would use this function.See also
- PySide2.QtCore.QPluginLoader.metaData()¶
- Return type:
QJsonObject
Returns the meta data for this plugin. The meta data is data specified in a json format using the
Q_PLUGIN_METADATA()
macro when compiling the plugin.The meta data can be queried in a fast and inexpensive way without actually loading the plugin. This makes it possible to e.g. store capabilities of the plugin in there, and make the decision whether to load the plugin dependent on this meta data.
- PySide2.QtCore.QPluginLoader.setFileName(fileName)¶
- Parameters:
fileName – str
This property holds the file name of the plugin.
We recommend omitting the file’s suffix in the file name, since
QPluginLoader
will automatically look for the file with the appropriate suffix (seeisLibrary()
).When loading the plugin,
QPluginLoader
searches in all plugin locations specified bylibraryPaths()
, unless the file name has an absolute path. After loading the plugin successfully, returns the fully-qualified file name of the plugin, including the full path to the plugin if one was given in the constructor or passed to .If the file name does not exist, it will not be set. This property will then contain an empty string.
By default, this property contains an empty string.
See also
- static PySide2.QtCore.QPluginLoader.staticInstances()¶
- Return type:
Returns a list of static plugin instances (root components) held by the plugin loader.
See also
staticPlugins()
- PySide2.QtCore.QPluginLoader.unload()¶
- Return type:
bool
Unloads the plugin and returns
true
if the plugin could be unloaded; otherwise returnsfalse
.This happens automatically on application termination, so you shouldn’t normally need to call this function.
If other instances of
QPluginLoader
are using the same plugin, the call will fail, and unloading will only happen when every instance has called .Don’t try to delete the root component. Instead rely on that will automatically delete it when needed.
See also
© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.