qt-creator/doc/api/pluginmanager.qdoc

/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
**
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
**
****************************************************************************/

/*!
    \page pluginmanager.html
    \title The Plugin Manager, the Object Pool, and Registered Objects

    Usually, plugins do not need to access the plugin manager directly.
    They interact with it mostly indirectly through the ExtensionSystem::IPlugin interface.
    There are occasions though, where using the plugin manager API is necessary.
    Plugins need to access the plugin manager's object pool to extend
    some aspects of \QC, for example to add pages to the options dialog. They
    can also utilize the object pool to provide extension points for other plugins
    (see \l{Extending and Providing Interfaces}).

    \section1 Plugin Manager

    The plugin manager handles all the details regarding finding plugins, reading their
    description files, resolving plugin dependencies, loading and initializing all plugins
    in the right order, and passing on command line arguments.

    In addition, the plugin manager manages an \e{object pool}, where objects can be registered
    and retrieved depending on different criteria.

    Most interaction of plugins with the plugin manager should be done through the
    ExtensionSystem::IPlugin interface, but the following tables summarize some functions
    and signals that can be useful for plugins.
    See the ExtensionSystem::PluginManager reference documentation for the complete list.

    \table
        \header
            \li Function
            \li Description
        \row
            \li instance()
            \li Returns the singleton plugin manager instance, for example for connecting to signals.
        \row
            \li addObject()
            \li Registers an object in the object pool.
                Also available through ExtensionSystem::IPlugin::addObject().
        \row
            \li removeObject()
            \li Unregisters an object from the object pool.
                Also available through ExtensionSystem::IPlugin::removeObject().
        \row
            \li getObjects<T>()
            \li Returns all objects of type T that are registered in the object pool.
                This respects \l{Aggregations}.
        \row
            \li getObject<T>()
            \li Returns one object of type T that is registered in the object pool.
                This respects \l{Aggregations}.
        \row
            \li getObjectByName(const QString &name)
            \li Returns one object with the given object name that is registered in the object pool.
        \row
            \li getObjectByClassName(const QString &className)
            \li Returns one object with the given class name that is registered in the object pool.
    \endtable

    \table
        \header
            \li Signal
            \li Description
        \row
            \li objectAdded(QObject *object)
            \li Sent after an object is registered in the object pool.
        \row
            \li aboutToRemoveObject(QObject *object)
            \li Sent just before an object is unregistered from the object pool.
        \row
            \li initializationDone()
            \li Sent when plugins are running and all delayed initialization is done.
    \endtable

    \target object pool
    \section1 Object Pool and Registered Objects

    Plugins can register objects to a common \e pool that is managed by
    the plugin manager. Objects in the pool must derive from QObject, there are no other
    prerequisites.

    All objects of a specified type can be retrieved from the object pool
    via the \l{ExtensionSystem::PluginManager::getObjects()}{getObjects()} and
    \l{ExtensionSystem::PluginManager::getObject()}{getObject()} functions.
    They are aware of Aggregation::Aggregate, so these functions use the Aggregation::query()
    functions instead of qobject_cast to determine the matching objects.

    It is also possible to retrieve an object with a specific object name with
    \l{ExtensionSystem::PluginManager::getObjectByName()}{getObjectByName()}
    (see QObject::objectName()), and an object with a given class name with
    \l{ExtensionSystem::PluginManager::getObjectByClassName()}{getObjectByClassName()}
    (see QMetaObject::className()).

    Whenever the state of the object pool changes, a corresponding
    \l{ExtensionSystem::PluginManager::objectAdded()}{objectAdded()} or
    \l{ExtensionSystem::PluginManager::aboutToRemoveObject()}{aboutToRemoveObject()} signal is
    emitted by the plugin manager.

    A common use case for the object pool is that a plugin (or the application) provides
    an \e{extension point} for other plugins, which is a class that can
    be implemented and added to the object pool to be retrieved by the providing plugin.
    It is also possible to use the object pool to provide access to an object without actually
    linking against the providing plugin library. See \l{Extending and Providing Interfaces}
    for details.
*/