PluginManager Class | Extending Qt Creator Manual

Extending Qt Creator Manual | PluginManager

Extending Qt Creator Manual 4.12.0

# PluginManager Class

(ExtensionSystem::PluginManager)

The PluginManager class implements the core plugin system that manages the plugins, their life cycle, and their registered objects. More...

Header: | #include <PluginManager>

- List of all members, including inherited members

## Public Functions

| PluginManager()
void | remoteArguments(const QString &serializedArgument, QObject *socket)
void | shutdown()

## Static Public Members

void | addObject(QObject *obj)
QVector<QObject *> | allObjects()
QStringList | arguments()
QStringList | argumentsForRestart()
void | formatOptions(QTextStream &str, int optionIndentation, int descriptionIndentation)
void | formatPluginOptions(QTextStream &str, int optionIndentation, int descriptionIndentation)
void | formatPluginVersions(QTextStream &str)
T * | getObject()
T * | getObject(Predicate predicate)
QObject * | getObjectByName(const QString &name)
QSettings * | globalSettings()
bool | hasError()
ExtensionSystem::PluginManager * | instance()
void | loadPlugins()
QVector<ExtensionSystem::PluginSpec *> | loadQueue()
bool | parseOptions(const QStringList &args, const QMap<QString, bool> &appOptions, QMap<QString, QString> *foundAppOptions, QString *errorString)
QString | pluginIID()
QStringList | pluginPaths()
const QVector<ExtensionSystem::PluginSpec *> | plugins()
const QSet<ExtensionSystem::PluginSpec *> | pluginsRequiredByPlugin(ExtensionSystem::PluginSpec *spec)
const QSet<ExtensionSystem::PluginSpec *> | pluginsRequiringPlugin(ExtensionSystem::PluginSpec *spec)
void | removeObject(QObject *obj)
QString | serializedArguments()
void | setGlobalSettings(QSettings *settings)
void | setPluginIID(const QString &iid)
void | setPluginPaths(const QStringList &paths)
void | setSettings(QSettings *settings)
QSettings * | settings()

## Detailed Description

The plugin manager is used for the following tasks:

- Manage plugins and their state
- Manipulate a common object pool

### Plugins

Plugins must derive from the IPlugin class and have the IID `"org.qt-project.Qt.QtCreatorPlugin"`.

The plugin manager is used to set a list of file system directories to search for plugins, retrieve information about the state of these plugins, and to load them.

Usually, the application creates a PluginManager instance and initiates the loading.

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

Additionally, it is possible to directly access plugin meta data, instances, and state.

### Object Pool

Plugins (and everybody else) can add objects to a common pool that is located in the plugin manager. Objects in the pool must derive from QObject, there are no other prerequisites. Objects can be retrieved from the object pool via the getObject() and getObjectByName() functions.

Whenever the state of the object pool changes, a corresponding signal is emitted by the plugin manager.

A common usecase for the object pool is that a plugin (or the application) provides an extension point for other plugins, which is a class or interface that can be implemented and added to the object pool. The plugin that provides the extension point looks for implementations of the class or interface in the object pool.

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

The ExtensionSystem::Invoker class template provides syntactic sugar for using soft extension points that may or may not be provided by an object in the pool. This approach neither requires the user plugin being linked against the provider plugin nor a common shared header file. The exposed interface is implicitly given by the invokable functions of the provider object in the object pool.

The ExtensionSystem::invoke() function template encapsulates ExtensionSystem::Invoker construction for the common case where the success of the call is not checked.

      // 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.
          }
      };

Note: The type of the parameters passed to the `invoke()` calls is deduced from the parameters themselves and must match the type of the arguments of the called functions exactly. No conversion or even integer promotions are applicable, so to invoke a function with a `long` parameter explicitly, use `long(43)` or such.

Note: The object pool manipulating functions are thread-safe.

## 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]` 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]` 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]` QSettings *PluginManager::globalSettings()

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

See also setGlobalSettings().

### `[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]` QStringList 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.

### 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::setGlobalSettings(QSettings *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().

See also globalSettings().

### `[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 QStringList &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(QSettings *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]` QSettings *PluginManager::settings()

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

### void PluginManager::shutdown()

Shuts down and deletes all plugins.