The QPluginLoader class loads a plugin at runtime. More...

Inheritance diagram for QPluginLoader:

Public Methods
	QPluginLoader (const QString &fileName, QObject *parent=nullptr)

	QPluginLoader (QObject *parent=nullptr)

	~QPluginLoader ()

QString	errorString () const

QString	fileName () const

QObject *	instance ()

bool	isLoaded () const

bool	load ()

QLibrary::LoadHints	loadHints () const

void	setFileName (const QString &fileName)

void	setLoadHints (QLibrary::LoadHints loadHints)

bool	unload ()

Public Methods inherited from QObject
	QObject (QObject *parent=nullptr)

	~QObject ()

bool	blockSignals (bool block)

const QList< QObject * > &	children () const

bool	connect (const QObject *sender, const QString &signalMethod, const QString &location, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

bool	connect (const QObject *sender, const QString &signalMethod, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

bool	disconnect (const QObject *receiver, const QString &slotMethod=QString ()) const

bool	disconnect (const QString &signalMethod, const QString &location, const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const

bool	disconnect (const QString &signalMethod=QString (), const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const

void	dumpObjectInfo ()

void	dumpObjectTree ()

QList< QString >	dynamicPropertyNames () const

virtual bool	event (QEvent *event)

virtual bool	eventFilter (QObject watched, QEvent event)

template<typename T >
T	findChild (const QString &childName=QString ()) const

template<class T >
QList< T >	findChildren (const QRegularExpression &regExp, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const

template<class T >
QList< T >	findChildren (const QString &childName=QString (), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const

bool	inherits (const QString &className) const

void	installEventFilter (QObject *filterObj)

bool	isWidgetType () const

bool	isWindowType () const

void	killTimer (int id)

const QMetaObject *	metaObject () const

void	moveToThread (QThread *targetThread)

QString	objectName () const

QObject *	parent () const

template<class T = QVariant>
T	property (const QString &name) const

void	removeEventFilter (QObject *obj)

void	setObjectName (const QString &name)

void	setParent (QObject *parent)

bool	setProperty (const QString &name, const QVariant &value)

bool	signalsBlocked () const

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

QThread *	thread () const

Static Public Methods
static QObjectList	staticInstances ()

static QVector< QMetaObject * >	staticPlugins ()

Static Public Methods inherited from QObject
static bool	connect (const QObject sender, const QMetaMethod &signalMethod, const QObject receiver, const QMetaMethod &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

static bool	connect (const QObject sender, const QString &signalMethod, const QObject receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection, const QString &location=QString ())

static bool	connect (const QObject sender, const QString &signalMethod, const QString &location, const QObject receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool	connect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver receiver, SlotReturn (SlotClass::slotMethod)(SlotArgs...), Qt::ConnectionType type=Qt::AutoConnection)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool	connect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver *receiver, T slotLambda, Qt::ConnectionType type=Qt::AutoConnection)

static bool	disconnect (const QObject sender, const QMetaMethod &signalMethod, const QObject receiver, const QMetaMethod &slotMethod)

static bool	disconnect (const QObject sender, const QString &signalMethod, const QObject receiver, const QString &slotMethod)

static bool	disconnect (const QObject sender, const QString &signalMethod, const QString &location, const QObject receiver, const QString &slotMethod)

static bool	disconnect (const QObject sender, std::nullptr_t, const QObject receiver, std::nullptr_t)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool	disconnect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver receiver, SlotReturn (SlotClass::slotMethod)(SlotArgs...))

template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
static bool	disconnect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver *receiver, std::nullptr_t slotMethod=nullptr)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool	disconnect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver *receiver, T slotMethod)

static QMetaObject &	staticMetaObject ()

static QString	tr (const char text, const char comment=nullptr, std::optional< int > numArg=std::optional< int >())

Properties
	fileName

	loadHints

Properties inherited from QObject
	objectName

Additional Inherited Members
Public Signals inherited from QObject
void	destroyed (QObject *obj=nullptr)

void	objectNameChanged (const QString &objectName)

Public Slots inherited from QObject
void	deleteLater ()

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

virtual void	connectNotify (const QMetaMethod &signalMethod) const

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const QMetaMethod &signalMethod) const

bool	isSignalConnected (const QMetaMethod &signalMethod) const

int	receivers (const QString &signal) const

QObject *	sender () const

int	senderSignalIndex () const

virtual void	timerEvent (QTimerEvent *event)

Related Functions inherited from QObject
T	qobject_cast (QObject *object)

	QObjectList

Detailed Description

The QPluginLoader class loads a plugin at runtime. A plugin is stored in a shared library (usually a .DLL or .SO file) and offers several benefits over shared libraries accessed using QLibrary.

QPluginLoader verify that a plugin is linked with the same version of CopperSpice as the user application
QPluginLoader provides direct access to an object exported by the plugin

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 with setFileName().

The most important methods are load() which is used to dynamically load the plugin. The method isLoaded() can be used to check whether the load was successful. Call instance() to retrieve the root component from the plugin. This method implicitly tries to load the plugin if it has not been loaded. Multiple instances of QPluginLoader 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 using unload(), but if other instances of QPluginLoader are using the same library, the call will fail, and unloading will only happen when every instance has called unload(). Right before the unloading happen, the root component will also be deleted.

In order to speed up loading and validation of plugins, some of the information that is collected during loading is cached in persistent memory (through QSettings). For instance, the result of a load operation (e.g. succeeded or failed) is stored in the cache, so that subsequent load operations do not try to load an invalid plugin. However, if the "last modified" timestamp of a plugin has changed, the plugin's cache entry is invalidated and the plugin is reloaded regardless of the values in the cache entry. The cache entry is then updated with the new result of the load operation.

This also means that the timestamp must be updated each time the plugin or any dependent resources (such as a shared library) is updated, since the dependent resources might influence the result of loading a plugin.

The QPluginLoader can not be used if your application is statically linked with CopperSpice. In this case, you will also have to link to plugins statically. You can use QLibrary if you need to load dynamic libraries in a statically linked application.

Refer to Creating Plugins for more information about extending your application through plugins.

See also: QLibrary

Constructor & Destructor Documentation

QPluginLoader::QPluginLoader ( QObject * parent = nullptr )

explicit

Constructs a plugin loader with the given parent.

QPluginLoader::QPluginLoader	(	const QString &	fileName,
		QObject *	parent = `nullptr`
	)

explicit

Constructs a plugin loader with the given parent that will load the plugin specified by fileName.

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 Mac OS X, and .dll on Windows. The suffix can be verified with QLibrary::isLibrary().

See also: setFileName()

QPluginLoader::~QPluginLoader ( )

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

See also: isLoaded(), unload()

Method Documentation

QString QPluginLoader::errorString ( ) const

Returns a text string with the description of the last error that occurred.

QString QPluginLoader::fileName ( ) const

Returns the value of the property fileName.

QObject * QPluginLoader::instance ( )

Returns the root component object of the plugin and then loads if necessary. This method returns a nullptr if the plugin could not be loaded or if the root component object could not be instantiated. If the root component object was destroyed then calling this method creates a new instance.

The root component is not deleted when the QPluginLoader is destroyed. To ensure the root component is deleted call unload() when the plugin library is no longer needed. When the library is unloaded the root component will automatically be deleted.

Since this method returns a QObject, use dynamic_cast() to verify the plugin at runtime.

See also: load()

bool QPluginLoader::isLoaded ( ) const

Returns true if the plugin is loaded, otherwise returns false.

See also: load()

bool QPluginLoader::load ( )

Loads the plugin and returns true if the plugin was loaded successfully, otherwise returns false. Since instance() always calls this method 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 method directly.

See also: unload()

QLibrary::LoadHints QPluginLoader::loadHints ( ) const

Returns the value of the property loadHints.

void QPluginLoader::setFileName ( const QString & fileName )

Sets the value of the property fileName to fileName.

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

Sets the value of the property loadHints to hints.

QObjectList QPluginLoader::staticInstances ( )

static

Returns a list of static plugin instances (root components) held by the plugin loader.

QVector< QMetaObject * > QPluginLoader::staticPlugins ( )

static

Returns a list of QStaticPlugins held by the plugin loader. The method is similar to staticInstances(), with the addition that this method may contain meta data information.

See also: staticInstances()

bool QPluginLoader::unload ( )

Unloads the plugin and returns true if the plugin could be unloaded, otherwise returns false. This happens automatically on application termination, so you should not normally need to call this method. If other instances of QPluginLoader are using the same plugin, the call will fail, and unloading will only happen when every instance has called unload().

Do not try to delete the root component. Instead rely on that unload() will automatically delete it when needed.

See also: instance(), load()

Property Documentation

QPluginLoader::fileName

This property holds the file name of the plugin.

The file suffix must be a valid name for the current platform. For example, .so on Unix, .dylib on Mac OS X, and .dll on Windows. The suffix can be verified with QLibrary::isLibrary().

If the file name does not exist this property will contain an empty string. By default, this property contains an empty string.

See also: load()

Properties	Class Methods
read	fileName
write	setFileName

QPluginLoader::loadHints

This property holds contains hints for how the load() method will happen. You can give hints on how the symbols in the plugin are resolved. By default, none of the hints are set. Refer to the documentation for QLibrary::loadHints for a complete description of how this property works.

See also: QLibrary::loadHints

Properties	Class Methods
read	loadHints
write	setLoadHints

Public Methods

Static Public Methods

Properties

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Method Documentation

Property Documentation