PluginManager Class

// 'plugins' and subdirs will be searched for plugins
PluginManager::setPluginPaths(QStringList("plugins"));
PluginManager::loadPlugins(); // try to load all the plugins

// Plugin A provides a "MimeTypeHandler" extension point
// in plugin B:
MyMimeTypeHandler *handler = new MyMimeTypeHandler();
PluginManager::instance()->addObject(handler);
// In plugin A:
MimeTypeHandler *mimeHandler =
    PluginManager::getObject<MimeTypeHandler>();

// In the "provide" plugin A:
namespace PluginA {
class SomeProvider : public QObject
{
    Q_OBJECT

public:
    Q_INVOKABLE QString doit(const QString &msg, int n) {
    {
        qDebug() << "I AM DOING IT " << msg;
        return QString::number(n);
    }
};
} // namespace PluginA


// In the "user" plugin B:
int someFuntionUsingPluginA()
{
    using namespace ExtensionSystem;

    QObject *target = PluginManager::getObjectByClassName("PluginA::SomeProvider");

    if (target) {
        // Some random argument.
        QString msg = "REALLY.";

        // Plain function call, no return value.
        invoke<void>(target, "doit", msg, 2);

        // Plain function with no return value.
        qDebug() << "Result: " << invoke<QString>(target, "doit", msg, 21);

        // Record success of function call with return value.
        Invoker<QString> in1(target, "doit", msg, 21);
        qDebug() << "Success: (expected)" << in1.wasSuccessful();

        // Try to invoke a non-existing function.
        Invoker<QString> in2(target, "doitWrong", msg, 22);
        qDebug() << "Success (not expected):" << in2.wasSuccessful();

    } else {

        // We have to cope with plugin A's absence.
    }
};

Member Function Documentation

PluginManager::PluginManager()

Creates a plugin manager. Should be done only once per application.

[static] void PluginManager::addObject(QObject *obj)

Adds the object obj to the object pool, so it can be retrieved again from the pool by type.

The plugin manager does not do any memory management. Added objects must be removed from the pool and deleted manually by whoever is responsible for the object.

Emits the objectAdded() signal.

See also PluginManager::removeObject(), PluginManager::getObject(), and PluginManager::getObjectByName().

[static] QVector<QObject *> PluginManager::allObjects()

Retrieves the list of all objects in the pool, unfiltered.

Usually, clients do not need to call this function.

See also PluginManager::getObject().

[static] QStringList PluginManager::arguments()

The arguments left over after parsing (that were neither startup nor plugin arguments). Typically, this will be the list of files to open.

[static] QStringList PluginManager::argumentsForRestart()

The arguments that should be used when automatically restarting the application. This includes plugin manager related options for enabling or disabling plugins, but excludes others, like the arguments returned by arguments() and the appOptions passed to the parseOptions() method.

[static] void PluginManager::formatOptions(QTextStream &str, int optionIndentation, int descriptionIndentation)

Formats the startup options of the plugin manager for command line help with the specified optionIndentation and descriptionIndentation. Adds the result to str.

[static] void PluginManager::formatPluginOptions(QTextStream &str, int optionIndentation, int descriptionIndentation)

Formats the plugin options of the plugin specs for command line help with the specified optionIndentation and descriptionIndentation. Adds the result to str.

[static] void PluginManager::formatPluginVersions(QTextStream &str)

Formats the version of the plugin specs for command line help and adds it to str.

[static] template <typename T> T *PluginManager::getObject()

Retrieves the object of a given type from the object pool.

This function uses qobject_cast to determine the type of an object. If there are more than one objects of the given type in the object pool, this function will arbitrarily choose one of them.

See also addObject().

[static] template <typename T, typename Predicate> T *PluginManager::getObject(Predicate predicate)

Retrieves the object of a given type from the object pool that matches the predicate.

This function uses qobject_cast to determine the type of an object. The predicate must be a function taking T * and returning a bool. If there is more than one object matching the type and predicate, this function will arbitrarily choose one of them.

See also addObject().

[static] QObject *PluginManager::getObjectByName(const QString &name)

Retrieves one object with name from the object pool.

See also addObject().

[static] Utils::QtcSettings *PluginManager::globalSettings()

Returns the global (user-independent) settings used for information about default disabled plugins.

[static] bool PluginManager::hasError()

Returns true if any plugin has errors even though it is enabled. Most useful to call after loadPlugins().

[static] ExtensionSystem::PluginManager *PluginManager::instance()

Gets the unique plugin manager instance.

[static] void PluginManager::loadPlugins()

Tries to load all the plugins that were previously found when setting the plugin search paths. The plugin specs of the plugins can be used to retrieve error and state information about individual plugins.

See also setPluginPaths() and plugins().

[static] QVector<ExtensionSystem::PluginSpec *> PluginManager::loadQueue()

Returns a list of plugins in load order.

[static] bool PluginManager::parseOptions(const QStringList &args, const QMap<QString, bool> &appOptions, QMap<QString, QString> *foundAppOptions, QString *errorString)

Takes the list of command line options in args and parses them. The plugin manager itself might process some options itself directly (-noload <plugin>), and adds options that are registered by plugins to their plugin specs.

The caller (the application) may register itself for options via the appOptions list, containing pairs of option string and a bool that indicates whether the option requires an argument. Application options always override any plugin's options.

foundAppOptions is set to pairs of (option string, argument) for any application options that were found. The command line options that were not processed can be retrieved via the arguments() function. If an error occurred (like missing argument for an option that requires one), errorString contains a descriptive message of the error.

Returns if there was an error.

[static] QString PluginManager::pluginIID()

The IID that valid plugins must have.

See also setPluginIID().

[static] Utils::FilePaths PluginManager::pluginPaths()

The list of paths were the plugin manager searches for plugins.

See also setPluginPaths().

[static] const QVector<ExtensionSystem::PluginSpec *> PluginManager::plugins()

List of all plugins that have been found in the plugin search paths. This list is valid directly after the setPluginPaths() call. The plugin specifications contain plugin metadata and the current state of the plugins. If a plugin's library has been already successfully loaded, the plugin specification has a reference to the created plugin instance as well.

See also setPluginPaths().

[static] const QSet<ExtensionSystem::PluginSpec *> PluginManager::pluginsRequiredByPlugin(ExtensionSystem::PluginSpec *spec)

Returns all plugins that spec requires to be loaded. Recurses into dependencies.

[static] const QSet<ExtensionSystem::PluginSpec *> PluginManager::pluginsRequiringPlugin(ExtensionSystem::PluginSpec *spec)

Returns all plugins that require spec to be loaded. Recurses into dependencies.

[static] void PluginManager::remoteArguments(const QString &serializedArgument, QObject *socket)

Parses the options encoded in serializedArgument and passes them on to the respective plugins along with the arguments.

socket is passed for disconnecting the peer when the operation is done (for example, document is closed) for supporting the -block flag.

[static] void PluginManager::removeObject(QObject *obj)

Emits the aboutToRemoveObject() signal and removes the object obj from the object pool.

See also PluginManager::addObject().

[static] QString PluginManager::serializedArguments()

Serializes plugin options and arguments for sending in a single string via QtSingleApplication: ":myplugin|-option1|-option2|:arguments|argument1|argument2", as a list of lists started by a keyword with a colon. Arguments are last.

See also setPluginPaths().

[static] void PluginManager::setInstallSettings(Utils::QtcSettings *settings)

Defines the global (user-independent) settings to use for information about default disabled plugins. Needs to be set before the plugin search path is set with setPluginPaths().

[static] void PluginManager::setPluginIID(const QString &iid)

Sets the IID that valid plugins must have to iid. Only plugins with this IID are loaded, others are silently ignored.

At the moment this must be called before setPluginPaths() is called.

See also pluginIID().

[static] void PluginManager::setPluginPaths(const Utils::FilePaths &paths)

Sets the plugin paths. All the specified paths and their subdirectory trees are searched for plugins.

See also pluginPaths() and loadPlugins().

[static] void PluginManager::setSettings(Utils::QtcSettings *settings)

Defines the user specific settings to use for information about enabled and disabled plugins. Needs to be set before the plugin search path is set with setPluginPaths().

See also settings().

[static] Utils::QtcSettings *PluginManager::settings()

Returns the user specific settings used for information about enabled and disabled plugins.

[static] void PluginManager::shutdown()

Shuts down and deletes all plugins.

[static] ExtensionSystem::PluginSpec *PluginManager::specForPlugin(ExtensionSystem::IPlugin *plugin)

Returns the PluginSpec corresponding to plugin.